Claude Code Installation Guide — macOS, Windows Commands, and Connecting with a Subscription or API Key After Installation

Claude Code takes just one command to install: on macOS, Linux, and WSL, run curl -fsSL https://claude.ai/install.sh | bash; on Windows, run irm https://claude.ai/install.ps1 | iex in PowerShell (or the install.cmd line below in Command Prompt, CMD). After installation, open a new terminal, verify with claude --version, then run claude to get started. There are two ways to connect the first time: sign in with a Pro, Max, Team, Enterprise, or Console account (Claude.ai Free doesn't include Claude Code), or set the ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN environment variables to use a usage-based API key, with no subscription required.

Commands verified on September 11, 2026, based on Anthropic's official installation documentation. This page covers installation and first connection only. For day-to-day use after installation, see Claude Code tutorial.

Before you install

macOS installation

Open Terminal and paste this line:

# macOS、Linux、WSL
curl -fsSL https://claude.ai/install.sh | bash

This is the officially recommended native installation method. It installs a standalone executable that updates automatically in the background. The executable's entry point is ~/.local/bin/claude. Terminals that are already open won't pick up the updated PATH, so open a new window after installation. Linux and WSL use the same command.

Windows installation

Windows has two different commands, depending on which terminal you're using. If the prompt shows PS C:\Users\你的名字>, you're in PowerShell; if it has no PS and only shows C:\Users\你的名字>, you're in Command Prompt (CMD). You don't need to run it as an administrator.

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

:: Windows 命令提示字元（CMD）
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Pasting the wrong command is the most common failure on Windows. Running the CMD command in PowerShell shows The token '&&' is not a valid statement separator; running the PowerShell command in CMD shows 'irm' is not recognized as an internal or external command. Pasting macOS's curl … | bash into PowerShell produces A parameter cannot be found that matches parameter name 'fsSL'. In all three cases, just use the command for the correct terminal.

We recommend also installing Git for Windows. Claude Code uses the included Git Bash to run commands; if it isn't installed, Claude Code uses PowerShell instead. If Git for Windows is installed but Git Bash can't be found, add CLAUDE_CODE_GIT_BASH_PATH to the env block in the settings file, pointing to the path for bash.exe.

If you choose WSL, run the macOS / Linux command above and launch claude from a WSL terminal, not from PowerShell or CMD.

Install with a package manager

You can also have an existing package manager manage the installation, at the cost that automatic updates are disabled by default, so you'll need to upgrade it regularly yourself (for example, with brew upgrade claude-code or winget upgrade Anthropic.ClaudeCode). Debian / Ubuntu, Fedora / RHEL, and Alpine also have official signed apt, dnf, and apk repositories.

# Homebrew（macOS、Linux）— stable 通道
brew install --cask claude-code

# WinGet（Windows）
winget install Anthropic.ClaudeCode

# npm — 需要 Node.js 22 以上；絕對不要加 sudo
npm install -g @anthropic-ai/claude-code

The npm installation method requires Node.js 22 or later starting with v2.1.198; with older Node.js versions, npm only prints a EBADENGINE warning, and installation still completes. It installs the same executable as the native installer, and that executable does not depend on Node.js at runtime. Never use sudo npm install -g; it will leave permission problems and also poses a security risk.

Confirm the installation

claude --version   # 正常會印出版本號，例如 2.1.211 (Claude Code)
claude doctor      # 唯讀的安裝與設定診斷，不會開啟工作階段

claude doctor is the command worth remembering: it doesn't start a session; it only lists the installation status, configuration file errors, and suggested fixes. It's the fastest way to tell whether the installation is broken or the configuration is.

If you see command not found: claude, or 'claude' is not recognized on Windows, the installation directory isn't on your PATH. On macOS / Linux, first open a new terminal and try again. If that doesn't work, add ~/.local/bin to the PATH in ~/.zshrc or ~/.bashrc. On Windows, the installation location is %USERPROFILE%\.local\bin. Check and add it with PowerShell:

# 1. 檢查安裝目錄是否已在 PATH 裡
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. 沒有任何輸出的話，把它加進「使用者」PATH，然後關掉終端機重開
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. 重開後再確認一次；若有兩份安裝，這行會列出兩個路徑
where.exe claude

First connection: subscription sign-in or usage-based key

Option A: Sign in with a subscription account

Run claude in the project directory and follow the browser prompts to sign in with a Pro, Max, Team, Enterprise, or Console account. One detail to keep in mind: if ANTHROPIC_API_KEY is already set in the environment, Claude Code will ask once whether you want to use that key. If you decline, it silently ignores the key from then on and won't ask again, which can make it look like the variable wasn't read. To re-enable it, choose Use custom API key in /config.

Option B: Use a usage-based key without a subscription

Claude Code natively supports ANTHROPIC_BASE_URL, so pointing it at any endpoint that provides the Anthropic Messages API is officially supported and requires no plugin, proxy, or modified executable. The steps are: create an account, add funds (minimum $10), create a key starting with sk-kn- on the key management page (it will only be shown once), and then set the variables below. macOS / Linux:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # 只寫到網域，不要加 /v1
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

To try it in a single PowerShell window on Windows:

# 只對這個 PowerShell 視窗有效，關掉就沒了
$env:ANTHROPIC_BASE_URL = "https://api.kunavo.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-kn-..."
$env:ANTHROPIC_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL = "claude-opus-5-5"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "claude-haiku-4-5"
claude

For long-term use, add it to the ~/.claude/settings.json block in your user settings file, env (on Windows, %USERPROFILE%\.claude\settings.json). Settings written here are available to every terminal, editor extension, and background process. If the file already contains other settings, merge in env:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

Each of these six lines contains something that, if misconfigured, can leave you stuck for a long time:

• ANTHROPIC_BASE_URL should contain only the domain.Claude Code appends /v1/messages itself; adding /v1 makes it /v1/v1/messages and returns a 404.
• Use ANTHROPIC_AUTH_TOKEN, not ANTHROPIC_API_KEY.They go in different HTTP headers: the first sends Authorization: Bearer and takes effect immediately; the second sends x-api-key and requires the one-time confirmation described above.
• ANTHROPIC_MODEL must contain the complete, correct model name.Kunavo only recognizes exact matches and won't automatically map old names with date suffixes.
• ANTHROPIC_DEFAULT_OPUS_MODEL is responsible for the opus alias. Claude Code's default model and the opus alias both point to the latest Opus, so Kunavo returns 404 if it has not been listed yet; therefore, both this line and ANTHROPIC_MODEL must be fixed. Here, the opus alias is fixed to Opus 5.5 (claude-opus-5-5), which requires Claude Code v2.1.280 or later; on older versions, run claude update first.
• ANTHROPIC_DEFAULT_SONNET_MODEL is responsible for the sonnet alias. On the Anthropic API, the sonnet alias points to Sonnet 5.5, which Kunavo does not provide. If it is not fixed, the /model sonnet and opusplan runtime modes, as well as subagents configured with model: sonnet, will return 404, so here it is likewise fixed to Claude Sonnet 5 (claude-sonnet-5).
• ANTHROPIC_DEFAULT_HAIKU_MODEL handles the haiku alias. Starting with Claude Code v2.1.293, the haiku alias points to Haiku 5.5; earlier versions use a dated Haiku 4.5 name. Kunavo recognizes neither name. Without pinning it, /model haiku and subagents set to model: haiku (including claude-code-guide launched by Claude Code itself) all return 404s, so pin it to claude-haiku-4-5 here.
• ANTHROPIC_DEFAULT_HAIKU_MODEL sets the model for background calls.Claude Code uses this model for its own summaries and titles: Claude Haiku 4.5 costs $0.70 / $3.50 per 1M tokens, while the main model, Claude Sonnet 5, costs $1.40 / $7.00 (the same as Anthropic's official price).

Do not put the key in the project's .claude/settings.json—that file will be committed and shared with everyone who clones the project. If you use the VS Code extension, put the variables in claudeCode.environmentVariables in VS Code user settings, because the extension checks for credentials before it starts.

Check which connection method is active

Once inside Claude Code, run /status. If you see the line Auth token, the key is active. If you see Login method with a claude.ai account listed, the variables weren't read. They don't stack: as long as the key variables are present, the signed-in subscription is put on hold. Remove the variables to return to the subscription; you don't need to reinstall.

Three things work differently when using a gateway: Remote Control and voice input require a claude.ai identity and aren't available; /fast availability checks contact Anthropic directly and may show as unavailable, but regular requests are unaffected; and the numbers shown by /context are local estimates. Coding, tools, subagents, MCP, hooks, and prompt caching continue to work as usual. Full details are in Claude Code integration documentation and Claude Code API key guide (both in English).

Common errors and fixes

After installation

When you first enter a project, run /init to let it read the whole project and create CLAUDE.md. The Claude Code tutorial covers how to switch between Opus, Sonnet, and Haiku for different tasks, what a session actually costs, and how to use /clear and /compact to reduce costs.

It is also worth being candid about which option to choose: for people who interact for long stretches every day and use a lot, a fixed monthly subscription is usually better value. Usage-based billing suits people whose usage varies or who don't want to be constrained by a 5-hour usage window; months with no activity cost $0. Kunavo uses shared capacity, without dedicated quotas or a contractual SLA, so teams that need those guarantees should purchase directly from Anthropic. Monthly prices and break-even points for both options are in Claude Code costs.

Frequently asked questions