Claude Code installation guide: Windows and macOS installation commands, API key configuration without signing in, and top-ups with Alipay or WeChat Pay

Claude Code recommends installing with Anthropic's official native installation command. npm is the official alternative and requires Node.js 22 or later. You can use Claude Code without signing in to a Claude account: set ANTHROPIC_BASE_URL (write only the domain, without /v1), ANTHROPIC_AUTH_TOKEN, and the four model-pinning variables to switch to a token-billed API key. Kunavo API balance can be topped up with Alipay or WeChat Pay, with a minimum top-up of $10. Finally, run /status in Claude Code to confirm the connection.

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

# 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

命令和环境变量核对于 October 3, 2026，依据 Claude Code official installation documentation和 Official environment variable documentation；价格和付款方式核对于 October 3, 2026。先说明一个事实：Anthropic supported countries and regions（核对于 October 3, 2026）中没有中国大陆、香港和澳门，Claude Code 安装文档的系统要求里也有一行「所在地区：Anthropic 支持的国家」。本页只讲官方文档写明的安装和配置方法，不提供任何绕过地区限制的办法。Kunavo 没有在中国大陆做过网络连通性测试，下面提到的下载地址、npm 源和 api.kunavo.com 能否在你的网络里访问，需要你自己确认。

Before installation

Method 1: Official native installation (recommended)

The official installation documentation marks native installation as the recommended method. The commands are the three sections at the beginning of this page: macOS, Linux, and WSL use the install.sh line; Windows PowerShell uses irm … | iex; and Windows CMD uses the install.cmd line. Native installation automatically updates to the latest version in the background; the official documentation also states that Homebrew and WinGet installations do not automatically update by default.

After installation, open a new terminal window (already-open windows cannot see the new PATH), then confirm:

claude --version   # 正常会打印版本号，后面跟着 (Claude Code)
claude doctor      # 只读的安装与设置诊断，不会开启会话

claude doctor does not start a session; it only prints diagnostic information about the installation status and settings files. Use it to distinguish a broken installation from broken settings.

When the download fails

如果终端里出现 syntax error near unexpected token '<' 或 curl: (22) The requested URL returned error: 403，按 Official installation troubleshooting documentation（核对于 October 3, 2026）的说法，这表示安装地址返回的是一个网页或错误状态码，而不是安装脚本。如果返回的网页写着 App unavailable in region，官方的解释是：Claude Code 在你所在的国家或地区不可用。不带网页内容的 403 也可能来自公司代理或防火墙拦截下载；官方建议，在支持地区内仍然遇到 403 时，先排查网络连接，再考虑其他安装方式。

Method 2: npm installation (requires Node.js 22 or later)

npm 仍是官方文档列出的安装方式。官方文档写明 npm 包需要 Node.js 22 或更高版本；版本较旧时 npm 会打印 EBADENGINE 警告但不会失败，安装照样完成，因为这个包下载的是一个运行时不依赖 Node.js 的原生程序。没有 Node.js 的话，从 Node.js official website安装 22 或更高版本。

node -v                                    # 需要 v22 或更高
npm install -g @anthropic-ai/claude-code   # 不要加 sudo

The official documentation explicitly says not to use sudo npm install -g, because it causes permission problems and security risks. For upgrades, use npm install -g @anthropic-ai/claude-code@latest instead of npm update -g.

When the default registry download fails or is very slow: npmmirror

如果从 npm 默认源下载失败或很慢，可以改用 npmmirror。npmmirror homepage（核对于 October 3, 2026）说明它是「完整 npmjs.com 镜像」，只读，会「尽量与官方服务实时同步」，并给出了 registry 地址和设置命令。首页没有写明具体同步频率。

# 只在这一次安装时使用 npmmirror
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

# 或者把 npmmirror 设为 npm 的默认源（之后所有 npm 安装都会走它）
npm config set registry https://registry.npmmirror.com

# 以后升级用 @latest，不要用 npm update -g
npm install -g @anthropic-ai/claude-code@latest --registry=https://registry.npmmirror.com

Installing Claude Code from a mirror has two easy-to-miss requirements, both from the official troubleshooting documentation:

• The mirror must provide all 8 platform packages. The npm package itself is only a wrapper; the actual program is downloaded as an optional dependency in the form of @anthropic-ai/claude-code-* platform packages. If the mirror lacks platform packages, running claude after installation on macOS or Linux shows claude native binary not installed (on Windows, PowerShell or CMD reports that the file cannot be run). On October 3, 2026, checking from a network outside mainland China, Kunavo confirmed that the main package and the Windows x64, macOS ARM64, and Linux x64 packages on npmmirror match the latest npmjs versions; the remaining packages (ARM64 Windows, Intel Mac, ARM64 Linux, and the two musl versions) were not checked.
• Do not skip optional dependencies.Do not include --omit=optional in the installation command, and confirm that .npmrc does not contain optional=false.

Windows-specific details

Windows has two different installation commands; the only difference is which terminal you opened. A prompt containing PS C:\Users\你的用户名> indicates PowerShell; one without PS and containing only C:\Users\你的用户名> indicates Command Prompt (CMD). The official documentation says installation does not need to be run as administrator.

A common Windows error is pasting the wrong terminal command: running the CMD line in PowerShell produces The token '&&' is not a valid statement separator; running the PowerShell line in CMD produces 'irm' is not recognized as an internal or external command. Switch to the corresponding line in either case. Also, the Start menu has two entries, “Windows PowerShell” and “Windows PowerShell (x86)”; the latter is a 32-bit process and produces Claude Code does not support 32-bit Windows, so open the one without (x86).

Git for Windows 是可选的：装了以后 Claude Code 用它附带的 Git Bash 执行命令；没装时改用 PowerShell 工具执行。装了却找不到 Git Bash 时，在 ~/.claude/settings.json 的 env 里设置 CLAUDE_CODE_GIT_BASH_PATH，指向 bash.exe，官方示例路径是 C:\Program Files\Git\bin\bash.exe。

If you choose WSL, run the macOS/Linux line in the WSL terminal and start claude there, not in PowerShell or CMD.

Execution-policy error on the npm route

When installing or running npm in PowerShell, if you see npm.ps1 cannot be loaded because running scripts is disabled on this system, PowerShell's execution policy has blocked the .ps1 startup script generated by npm. The official solutions are: allow the current user to run local scripts (the line below); use npm.cmd and claude.cmd instead; or use PowerShell's native installation command.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

claude not found after installation

Seeing command not found: claude or 'claude' is not recognized means the installation directory is not in PATH. Native installation places the program in ~/.local/bin/claude on macOS/Linux and %USERPROFILE%\.local\bin\claude.exe on Windows. Open a new terminal and try again; if it still fails on Windows, follow the official troubleshooting documentation to inspect and add the user PATH in 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. 重新打开终端后确认
claude --version

Configure an API key: without signing in to a Claude account

ANTHROPIC_BASE_URL is an environment variable built into Claude Code. The official documentation describes it as overriding the API endpoint so requests pass through a proxy or gateway. Therefore, pointing Claude Code to an endpoint that provides the Anthropic Messages API is an officially supported configuration and requires no plugin or modified program. On macOS/Linux, add it to your shell configuration file:

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 test it first in a 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 ~/.claude/settings.json's env (on Windows, %USERPROFILE%\.claude\settings.json). Settings written here are available to every terminal and background task. 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 has one easy-to-misconfigure detail:

• ANTHROPIC_BASE_URL must contain only the domain.Claude Code appends /v1/messages itself; adding /v1 makes it /v1/v1/messages, which returns 404.
• Use ANTHROPIC_AUTH_TOKEN, not ANTHROPIC_API_KEY.The official documentation says the value of ANTHROPIC_AUTH_TOKEN is sent as the Authorization header and automatically receives the Bearer prefix, taking effect immediately; ANTHROPIC_API_KEY requires one confirmation in interactive mode. If you reject it, this key is silently ignored afterward (re-enable it in /config's Use custom API key).
• ANTHROPIC_MODEL determines the primary model.Set it here to Claude Sonnet 5 (claude-sonnet-5). The model name must exactly match Kunavo's model list; old names with date suffixes are not mapped automatically.
• ANTHROPIC_DEFAULT_OPUS_MODEL determines the opus alias.按 Official model configuration documentation（核对于 October 3, 2026），API 用户的默认模型和 opus 别名指向最新的 Opus（目前是 Opus 5.5），sonnet 别名指向 Sonnet 5.5，而且别名会跟着 Anthropic 的新版本移动。官方文档写明别名「会随时间更新」，要固定版本，就写完整模型名或设置 ANTHROPIC_DEFAULT_OPUS_MODEL 这类变量。Kunavo 目前没有提供 Sonnet 5.5，Anthropic 以后发布新 Opus 时 Kunavo 也不一定已经上架，没上架的模型会返回 404。这就是要把主模型、opus 和 sonnet 别名都固定下来的原因。这里 opus 别名固定为 Claude Opus 5.5（claude-opus-5-5），需要 Claude Code v2.1.280 或更高版本，旧版本先运行 claude update 升级。
• ANTHROPIC_DEFAULT_SONNET_MODEL determines the sonnet alias.The official documentation says this variable determines which model the sonnet alias points to and which model opusplan uses outside plan mode (during execution). The sonnet alias requests Sonnet 5.5 by default, which Kunavo does not currently provide; without this line, the execution phases of /model sonnet and opusplan, and subagents specifying model: sonnet, all return 404. Set it here to Claude Sonnet 5 (claude-sonnet-5).
• ANTHROPIC_DEFAULT_HAIKU_MODEL also controls background tasks. The official documentation states that this variable determines the haiku alias and is also used for background features. On Kunavo, Claude Haiku 4.5 costs $0.70 for input and $3.50 for output per million tokens; the main model, Claude Sonnet 5, costs $1.40 / $7.00(Anthropic's official price: $2.00 / $10.00); Claude Opus 5.5, assigned to the opus alias, costs $2.80 / $14.00.

Do not put the key in the project's .claude/settings.json: the official documentation warns that this file is committed and shared with everyone who clones the repository. Also note the priority rule: when the same variable is set in both the shell and the settings file, the settings-file value takes precedence. If changing a shell variable has no effect, check the settings file first.

What happens the first time you run it

按官方的 Gateway connection documentation（核对于 October 3, 2026），设置了 ANTHROPIC_AUTH_TOKEN 后运行 claude，会直接进入会话，No login page appears；这个变量立即生效，不像 ANTHROPIC_API_KEY 那样要先确认一次。如果打开后看到的是登录页，说明 Claude Code 没有读到凭据。

Credentials must be placed where Claude Code reads them before initial setup: export in the shell or env in the user-level ~/.claude/settings.json. The official documentation says that in interactive mode, env in the project-level .claude/settings.json or .claude/settings.local.json only takes effect after the initial setup wizard and folder-trust prompt. Therefore, if the key is in project-level settings, the login page still appears on the first launch.

After entering a session, run /status and check two lines on the Status page:

• Anthropic base URL: this appears only when a gateway address is configured and should show https://api.kunavo.com. If this line is absent, ANTHROPIC_BASE_URL was not passed to this session.
• Auth token: if it says ANTHROPIC_AUTH_TOKEN, you are using an API key rather than a saved claude.ai login. If you see Login method plus a claude.ai account, the variable did not take effect.

To test the address and key separately before opening Claude Code, follow the official method and send a request requiring only 1 output token (a very small token charge applies). This command reads the shell variables, so even if you put the key in the settings file, you must first run export in the current terminal. JSON beginning with {"id":"msg_ means the address and key are both valid; 401 means the key was not recognized.

curl -sS -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

What differs when using an API key

• Remote Control and voice input are unavailable.The official documentation says both depend on claude.ai identity and are unavailable when ANTHROPIC_AUTH_TOKEN is set; Remote Control is also disabled when ANTHROPIC_BASE_URL points to a non-Anthropic address.
• /fast reports that fast mode is disabled.The official documentation says that with only a bearer token, Claude Code treats fast mode as disabled and sends no availability check.
• MCP tool search is disabled by default.The official documentation says MCP tool search is disabled by default when ANTHROPIC_BASE_URL points to a non-Anthropic address.
• The number in /context is a local estimate.Kunavo 目前不提供 /v1/messages/count_tokens。按 Official gateway compatibility documentation（核对于 October 3, 2026），网关没有这个端点时，Claude Code 改用按字符估算，/context 显示的是近似值。

For complete integration instructions, see the Claude Code integration documentation (English).

What exactly does CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC disable?

按 Official environment variable documentation（核对于 October 3, 2026），它的作用是关闭 Claude Code 的非必要网络流量，官方列出的内容是：

• Automatic updates, telemetry, and error reports;
• The /feedback command and Claude-drafted feedback;
• Release notes and PR/MR status badge checks;
• Availability checks such as fast mode;
• Feature-flag fetching, so Remote Control and other feature-flag-dependent features are unavailable;
• Background reruns from the plugin command (this is a local command, not network traffic, because it may trigger dependency installation).

The official documentation also specifies: setting it to 0 or false counts as enabled, unlike most switch variables, and only removing the variable restores it; automatic installation from the official plugin marketplace is outside its scope; it does not affect gateway model discovery. The official gateway documentation adds that it does not affect the WebFetch tool's domain safety check, which still accesses api.anthropic.com; disabling that requires adding skipWebFetchPreflight: true separately in settings. The official documentation does not describe this variable as an account-risk-control setting.

Kunavo 不要求设置它，它也不影响发往 Kunavo 的模型请求。什么时候值得开启，官方 Gateway connection documentation（核对于 October 3, 2026）给了一个场景：即使 ANTHROPIC_BASE_URL 指向网关，Claude Code 仍会向 Anthropic 和 GitHub 等第三方发送版本检查、遥测、发布说明之类的后台请求；如果你的网络只允许访问网关地址，这些请求会失败，并可能在出站监控里显示为被拦截的连接，官方的做法就是和网关变量一起设置这个变量。

The cost of enabling it is that updates are no longer automatic; the official recommendation is to arrange another update method. For npm installations, manually upgrade with @latest (see the final line of the npmmirror section above).

# 可选：关闭 Claude Code 的非必要网络流量（会同时关闭自动更新）
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

# 想恢复时删掉这个变量；设成 0 或 false 仍然算开启
unset CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC

Top up with Alipay or WeChat Pay and obtain a key

Anthropic 官方的网页订阅只收信用卡或借记卡（Claude paid-plan billing FAQ，核对于 October 3, 2026）。在 Kunavo 充值可以用支付宝或微信支付，步骤概要如下，完整步骤见 Claude API Alipay and WeChat Pay top-up guide：

1. Create a Kunavo account; email or Google accounts are both supported, and registration does not require a card.
2. In Billing, choose a top-up amount; the minimum is $10, and there is no monthly fee. Larger top-ups include bonuses: 充 $100 到账 $110、充 $1000 到账 $1200、充 $5000 到账 $6250.
3. Select Alipay or WeChat Pay on the Stripe checkout page and pay by scanning the QR code. When opened in mainland China, the amount is displayed in RMB; use the amount shown on the checkout page.
4. Go to /app/keys and create a key beginning with sk-kn- (it is shown only once, so save it immediately), then enter it in the ANTHROPIC_AUTH_TOKEN above.

Alipay and WeChat Pay support manual top-ups only; automatic top-ups require a bank card or Link. Kunavo does not issue Chinese VAT invoices; top-up records are available on the Billing page.

How much it may cost (illustrative calculation)

Claude Code charges by token. Each request resends the conversation context, and a prefix identical to the previous one can be billed as a cache read. The following is only illustrative token arithmetic, not an actual bill or a spending limit. All assumptions are listed:

• Each request contains 40,000 input tokens, of which 36,000 (90%) are billed as cache reads; the remaining 4,000 are billed as cache writes;
• Each request produces 1,000 output tokens;
• 50 such requests are sent during a work period; background calls from Claude Haiku 4.5 are excluded;
• Kunavo pricing: cache reads are 10% of the input price, and cache writes are 1.25 times the input price (the ratio for Claude Sonnet 5; each model in the table uses its own ratio).

Actual cost depends on context length, cache-hit volume, output length, and whether you use /clear to clear the conversation between tasks. For how to choose between a Claude Code subscription and the API and how much it may cost per month, see Claude Code pricing; complete model pricing is available in Claude API pricing and the pricing page; to estimate based on your own usage, use the Claude token cost calculator (English).

Common error reference

Limitations to know

• Kunavo does not issue Chinese VAT invoices.
• Alipay and WeChat Pay support manual top-ups only; automatic top-ups require a bank card or Link.
• This is a token-billed API, not a Claude Pro/Max subscription; Remote Control and voice input are unavailable when using an API key. See Claude Code pricing for how to choose.
• Kunavo has not tested network connectivity from mainland China. You must verify whether claude.ai's installation URL, the npm registry, npmmirror, and api.kunavo.com are accessible from your network and how fast they are.
• The Anthropic supported countries and regions list (verified on October 3, 2026) does not include mainland China, Hong Kong, or Macao, and Claude Code's official installation documentation lists location as one of the system requirements.

Frequently asked questions