Claude Code 安装教程：Windows、macOS 安装命令，不登录账号用 API key 配置，支付宝、微信支付充值

Claude Code 推荐用 Anthropic 官方原生安装命令安装，npm 是官方备选路线，需要 Node.js 22 以上。不登录 Claude 账号也能用 Claude Code：设置 ANTHROPIC_BASE_URL（只写到域名，不加 /v1）、ANTHROPIC_AUTH_TOKEN 和三行模型固定，即可改用按 token 计费的 API key。Kunavo 的 API 余额可以用支付宝或微信支付充值，最低 $10。最后在 Claude Code 里运行 /status 确认连接。

# 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

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

安装前确认

方式一：官方原生安装（推荐）

官方安装文档把原生安装标为推荐方式，命令就是本页开头的三段：macOS、Linux 和 WSL 用 install.sh 那一行，Windows PowerShell 用 irm … | iex，Windows CMD 用 install.cmd 那一行。原生安装会在后台自动更新到最新版本；官方文档同时写明，Homebrew 和 WinGet 安装默认不会自动更新。

装完后开一个新的终端窗口（已经开着的窗口读不到新的 PATH），然后确认：

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

claude doctor 不会开启会话，只打印安装状态和设置文件的诊断信息，可以用来分辨是「安装坏了」还是「设置坏了」。

下载出错时

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

方式二：npm 安装（需要 Node.js 22 以上）

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

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

官方文档明确要求不要用 sudo npm install -g，会带来权限问题和安全风险。升级时用 npm install -g @anthropic-ai/claude-code@latest，不要用 npm update -g。

默认源下载失败或很慢时：npmmirror

如果从 npm 默认源下载失败或很慢，可以改用 npmmirror。npmmirror 首页（核对于 2026年10月3日）说明它是「完整 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

用镜像安装 Claude Code 有两个容易漏掉的条件，都来自官方排错文档：

• 镜像必须同时提供 8 个平台包。npm 包本身只是一个外壳，真正的程序以 @anthropic-ai/claude-code-* 平台包的形式作为可选依赖下载。镜像缺少平台包时，装完在 macOS 或 Linux 上运行 claude 会提示 claude native binary not installed（Windows 上则是 PowerShell 或 CMD 报告无法运行这个文件）。2026年10月3日，Kunavo 从中国大陆以外的网络查看，npmmirror 上的主包和 Windows x64、macOS ARM64、Linux x64 三个平台包与 npmjs 的最新版本一致；其余平台包（ARM64 Windows、Intel Mac、ARM64 Linux 和两个 musl 版本）没有核对。
• 不能跳过可选依赖。安装命令里不要带 --omit=optional，也要确认 .npmrc 里没有设置 optional=false。

Windows 专项

Windows 有两条不同的安装命令，区别只在你打开的是哪种终端。提示符是 PS C:\Users\你的用户名> 的是 PowerShell；没有 PS、只有 C:\Users\你的用户名> 的是命令提示符（CMD）。官方文档说明安装不需要以管理员身份运行。

Windows 上一个常见错误是贴错终端：在 PowerShell 里运行了 CMD 那一行，会看到 The token '&&' is not a valid statement separator；在 CMD 里运行了 PowerShell 那一行，会看到 'irm' is not recognized as an internal or external command。两种情况换回对应的那一行即可。另外，开始菜单里有「Windows PowerShell」和「Windows PowerShell (x86)」两个入口，后者是 32 位进程，会报 Claude Code does not support 32-bit Windows，请打开不带 (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。

选 WSL 的话，要在 WSL 终端里运行 macOS／Linux 那一行，也在 WSL 里启动 claude，而不是在 PowerShell 或 CMD 里。

npm 路线的执行策略报错

在 PowerShell 里用 npm 安装或运行时，如果看到 npm.ps1 cannot be loaded because running scripts is disabled on this system，是 PowerShell 的执行策略拦住了 npm 生成的 .ps1 启动脚本。官方给出三种解决办法：允许当前用户运行本地脚本（下面这行）；改用 npm.cmd、claude.cmd；或者改用 PowerShell 原生安装命令。

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

装好后提示找不到 claude

出现 command not found: claude 或 'claude' is not recognized，说明安装目录不在 PATH 里。原生安装把程序放在 macOS／Linux 的 ~/.local/bin/claude，Windows 的 %USERPROFILE%\.local\bin\claude.exe。先开一个新终端再试；Windows 上仍然不行时，按官方排错文档用 PowerShell 检查并加入用户 PATH：

# 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

配置 API key：不登录 Claude 账号

ANTHROPIC_BASE_URL 是 Claude Code 自带的环境变量，官方文档对它的描述是：覆盖 API 端点，让请求经过代理或网关。所以把 Claude Code 指向提供 Anthropic Messages API 的端点，是官方支持的配置方式，不需要插件或修改过的程序。macOS／Linux 写进 shell 配置文件：

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
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

Windows 想先在一个 PowerShell 窗口里试：

# 只对当前 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"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "claude-haiku-4-5"
claude

长期使用，建议写进用户级设置文件 ~/.claude/settings.json 的 env（Windows 是 %USERPROFILE%\.claude\settings.json）。写在这里，每个终端和后台任务都能读到；文件里已有其他设置的话，把 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",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

这五行各有一个容易设错的地方：

• ANTHROPIC_BASE_URL 只写到域名。Claude Code 会自己拼上 /v1/messages；多写了 /v1 就会变成 /v1/v1/messages，返回 404。
• 用 ANTHROPIC_AUTH_TOKEN，不用 ANTHROPIC_API_KEY。官方文档说明，ANTHROPIC_AUTH_TOKEN 的值会作为 Authorization 头发送，并自动加上 Bearer 前缀，设置后立即生效；ANTHROPIC_API_KEY 则要在交互模式下先确认一次，确认时选了拒绝，之后这把 key 会被静默忽略（要在 /config 的 Use custom API key 里重新启用）。
• ANTHROPIC_MODEL 决定主模型。这里固定为 Claude Sonnet 5（claude-sonnet-5）。模型名要和 Kunavo 的模型列表完全一致，带日期后缀的旧名称不会被自动对应。
• ANTHROPIC_DEFAULT_OPUS_MODEL 决定 opus 别名。按 官方模型配置文档（核对于 2026年10月3日），API 用户的默认模型和 opus 别名指向最新的 Opus（目前是 Opus 5.5），sonnet 别名指向 Sonnet 5.5，而且别名会跟着 Anthropic 的新版本移动。官方文档写明别名「会随时间更新」，要固定版本，就写完整模型名或设置 ANTHROPIC_DEFAULT_OPUS_MODEL 这类变量。Kunavo 目前没有提供 Sonnet 5.5，Anthropic 以后发布新 Opus 时 Kunavo 也不一定已经上架，没上架的模型会返回 404。这就是要把主模型和 opus 别名都固定下来的原因。如果你习惯用 /model sonnet 切换，还可以再加一行 ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5，官方文档说明它决定 sonnet 别名指向哪个模型。
• ANTHROPIC_DEFAULT_HAIKU_MODEL 也管后台任务。官方文档说明，这个变量决定 haiku 别名，也用于后台功能。Claude Haiku 4.5 在 Kunavo 每百万 token 输入 $0.70、输出 $3.50；主模型 Claude Sonnet 5 是 $1.40 / $7.00（Anthropic 官方价 $2.00 / $10.00）；Claude Opus 5 是 $3.50 / $17.50。

key 不要写进项目里的 .claude/settings.json：官方文档提醒，这个文件会被提交，分享给每个克隆仓库的人。另外要知道一条优先级：shell 和 settings 文件同时设置同一个变量时，以 settings 文件里的值为准。改了 shell 变量却不生效时，先检查 settings 文件。

第一次运行会发生什么

按官方的 网关连接文档（核对于 2026年10月3日），设置了 ANTHROPIC_AUTH_TOKEN 后运行 claude，会直接进入会话，不显示登录页；这个变量立即生效，不像 ANTHROPIC_API_KEY 那样要先确认一次。如果打开后看到的是登录页，说明 Claude Code 没有读到凭据。

凭据要放在 Claude Code 在首次设置之前就会读取的地方：shell 里的 export，或用户级 ~/.claude/settings.json 的 env。官方文档说明，交互模式下，项目里 .claude/settings.json 或 .claude/settings.local.json 的 env 要等首次设置向导和文件夹信任提示之后才生效，所以 key 写在项目级设置里时，第一次启动仍会看到登录页。

进入会话后，运行 /status，在 Status 页看两行：

• Anthropic base URL：只有设置了网关地址才会出现，应显示 https://api.kunavo.com。没有这一行，说明 ANTHROPIC_BASE_URL 没有传到这个会话。
• Auth token：写着 ANTHROPIC_AUTH_TOKEN，说明正在用 API key，而不是已保存的 claude.ai 登录。看到的是 Login method 加一个 claude.ai 账号，说明变量没有生效。

想在打开 Claude Code 之前先单独测试地址和 key，可以照官方文档的方法发一条只要 1 个输出 token 的请求（会按 token 扣极少的余额）。这条命令读取的是 shell 里的变量，所以即使你把 key 写进了 settings 文件，也要先在当前终端里 export 一遍。返回以 {"id":"msg_ 开头的 JSON，说明地址和 key 都没问题；返回 401，说明 key 没被认出。

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": "."}]}'

走 API key 时有哪些不一样

• Remote Control 和语音输入不可用。官方文档说明，这两项依赖 claude.ai 身份，设置了 ANTHROPIC_AUTH_TOKEN 时不可用；ANTHROPIC_BASE_URL 指向非 Anthropic 地址时，Remote Control 也会被关闭。
• /fast 会显示 fast 模式已关闭。官方文档说明，只有 bearer token 时，Claude Code 直接把 fast 模式当作关闭，不发送可用性检查。
• MCP 工具搜索默认关闭。官方文档说明，ANTHROPIC_BASE_URL 指向非 Anthropic 地址时，MCP tool search 默认关闭。
• /context 里的数字是本地估算。Kunavo 目前不提供 /v1/messages/count_tokens。按 官方网关兼容性文档（核对于 2026年10月3日），网关没有这个端点时，Claude Code 改用按字符估算，/context 显示的是近似值。

完整的接入说明见 Claude Code 接入文档（英文）。

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 到底关掉了什么

按 官方环境变量文档（核对于 2026年10月3日），它的作用是关闭 Claude Code 的非必要网络流量，官方列出的内容是：

• 自动更新、遥测、错误报告；
• /feedback 命令和 Claude 起草的反馈；
• 发布说明、PR／MR 状态徽标检查；
• fast 模式等可用性检查；
• 功能开关（feature flag）拉取，因此 Remote Control 和其他依赖功能开关的功能会不可用；
• 插件 command 来源的后台重新运行（这是本地命令，不是网络流量，因为它可能触发依赖安装）。

还有几点官方写明的细节：设成 0 或 false 也算开启，和大多数开关变量不同，只有删掉这个变量才会恢复；官方插件市场的自动安装不在它的范围内；它不影响网关模型发现。官方网关文档补充，它不影响 WebFetch 工具的域名安全检查，这项检查仍会访问 api.anthropic.com，要关闭得另外在设置里加 skipWebFetchPreflight: true。官方文档没有把这个变量描述成与账号风控有关的设置。

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

开启的代价是不再自动更新，官方建议另外安排更新途径。npm 安装的话用 @latest 手动升级（见上面 npmmirror 那段的最后一行）。

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

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

用支付宝或微信支付充值，拿到 key

Anthropic 官方的网页订阅只收信用卡或借记卡（Claude 付费计划账单 FAQ，核对于 2026年10月3日）。在 Kunavo 充值可以用支付宝或微信支付，步骤概要如下，完整步骤见 Claude API 支付宝、微信支付充值教程：

1. 注册 Kunavo 账号，邮箱或 Google 账号都可以，注册不需要绑卡。
2. 在 Billing 选择充值金额，最低 $10，没有月费。充得多有赠送：充 $100 到账 $110、充 $1000 到账 $1200、充 $5000 到账 $6250。
3. 在 Stripe 结账页选择支付宝或微信支付，扫码付款。在中国大陆打开时，金额按人民币显示，以结账页上的数字为准。
4. 到 /app/keys 创建一把 sk-kn- 开头的 key（只显示一次，请立即保存），填进上面的 ANTHROPIC_AUTH_TOKEN。

支付宝和微信支付只能手动充值；自动充值只能绑定银行卡或 Link。Kunavo 不开具中国的增值税发票，充值记录可以在 Billing 页面查看。

大概花多少（示意算法）

Claude Code 按 token 扣费，每次请求都会把对话上下文重新发送一遍，其中与上一次相同的前缀可以按缓存读取计价。下面只是一组示意的 token 算术，不是实测账单，也不是费用上限。假设条件全部列出：

• 每次请求输入 40,000 token，其中 36,000（90%）按缓存读取计价，其余 4,000 按缓存写入计价；
• 每次请求输出 1,000 token；
• 一段工作时间发出 50 次这样的请求；不计 Claude Haiku 4.5 的后台调用；
• Kunavo 价格：缓存读取是输入价的 10%，缓存写入是输入价的 1.25 倍（Claude Sonnet 5 的比例；表中每个模型按各自的比例计算）。

实际花费取决于上下文有多长、缓存命中多少、输出多长，以及你在任务之间是否用 /clear 清空对话。Claude Code 订阅和 API 怎么选、一个月大概花多少，见 Claude Code 价格；各模型的完整价格见 Claude API 价格和 价格页；想按自己的用量估算，可以用 Claude token 成本计算器（英文）。

常见报错对照

需要知道的限制

• Kunavo 不开具中国的增值税发票。
• 支付宝和微信支付只能手动充值；自动充值只能绑定银行卡或 Link。
• 这是按 token 计费的 API，不是 Claude Pro／Max 订阅；走 API key 时 Remote Control 和语音输入不可用。两者怎么选见 Claude Code 价格。
• Kunavo 没有在中国大陆做过网络连通性测试。claude.ai 的安装地址、npm 源、npmmirror 和 api.kunavo.com 在你的网络里能否访问、速度如何，都需要你自己确认。
• Anthropic 支持的国家和地区名单（核对于 2026年10月3日）中没有中国大陆、香港和澳门，Claude Code 官方安装文档把所在地区列为系统要求之一。

常见问题