Claude Code 安装教程——macOS、Windows 命令，安装后使用订阅或 API 密钥连接

Claude Code 的安装只需一行命令：macOS、Linux、WSL 执行 curl -fsSL https://claude.ai/install.sh | bash；Windows 在 PowerShell 中执行 irm https://claude.ai/install.ps1 | iex（在命令提示符 CMD 中则使用下面的 install.cmd 那一行）。安装完成后打开一个新的终端，使用 claude --version 确认，然后执行 claude 开始。第一次连接有两条路径：登录 Pro、Max、Team、Enterprise 或 Console 账号（Claude.ai 免费方案不包含 Claude Code），或者设置 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 两个环境变量，改用按量计费的 API 密钥，完全不需要订阅。

命令核对于 2026年9月11日，依据 Anthropic 官方安装文档。本页面只讲安装和第一次连接；安装完成后的日常使用方法见 Claude Code 教程。

安装前确认

macOS 安装

打开“终端”，粘贴这一行：

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

这是官方建议的原生安装方式：安装的是独立可执行文件，会在后台自动更新。可执行文件的入口在 ~/.local/bin/claude；已经打开的终端不会读取新的 PATH，因此安装完成后请打开一个新窗口。Linux 和 WSL 使用同一条命令。

Windows 安装

Windows 有两条不同的命令，区别只在于你打开的是哪一种终端。提示符为 PS C:\Users\你的名字> 的是 PowerShell；没有 PS、只有 C:\Users\你的名字> 的是命令提示符（CMD）。不需要以管理员身份运行。

# 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

粘贴到错误的位置是 Windows 上最常见的失败原因。在 PowerShell 中运行 CMD 那一行，会看到 The token '&&' is not a valid statement separator；在 CMD 中运行 PowerShell 那一行，会看到 'irm' is not recognized as an internal or external command。把 macOS 的 curl … | bash 粘贴进 PowerShell，则会出现 A parameter cannot be found that matches parameter name 'fsSL'。这三种情况都只需换回对应的那一行。

建议另外安装 Git for Windows：Claude Code 会使用它附带的 Git Bash 执行命令；如果没有安装，则改用 PowerShell 执行。如果已经安装但找不到 Git Bash，在配置文件的 env 区块中加入 CLAUDE_CODE_GIT_BASH_PATH，指向 bash.exe 的路径。

如果选择 WSL，需要在 WSL 的终端中执行上面的 macOS／Linux 命令，也在 WSL 中启动 claude，而不是从 PowerShell 或 CMD 启动。

使用包管理工具安装

也可以让现有的包管理工具进行管理，代价是默认都不会自动更新，需要自己定期升级（例如 brew upgrade claude-code、winget upgrade Anthropic.ClaudeCode）。Debian／Ubuntu、Fedora／RHEL、Alpine 另有官方签名的 apt、dnf、apk 软件包仓库。

# 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

从 v2.1.198 起，npm 这条路径需要 Node.js 22 或更高版本；版本较旧时，npm 只会输出 EBADENGINE 警告，安装仍会完成。它安装的是与原生安装程序相同的可执行文件，运行时并不依赖 Node.js。千万不要使用 sudo npm install -g，这会留下权限问题，也存在安全风险。

确认安装成功

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

claude doctor 最值得记住：它不会启动工作会话，只会列出安装状态、配置文件中的错误和建议的修复方法，是区分“安装坏了”还是“配置坏了”的最快方法。

如果出现 command not found: claude，或 Windows 上的 'claude' is not recognized，表示安装目录不在 PATH 中。macOS／Linux 先打开新的终端再试，仍然不行就把 ~/.local/bin 添加到 ~/.zshrc 或 ~/.bashrc 的 PATH 中。Windows 的安装位置是 %USERPROFILE%\.local\bin，使用 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

第一次连接：订阅登录，或按量计费密钥

路径 A：使用订阅账号登录

在项目文件夹中执行 claude，按照浏览器中的提示登录 Pro、Max、Team、Enterprise 或 Console 账号即可。需要注意一个细节：如果环境中已经有 ANTHROPIC_API_KEY，Claude Code 会改为询问你是否要使用这把密钥；如果当时选择拒绝，之后它会默默忽略这把密钥、不再询问，看起来就像没有读取变量。要重新启用，请进入 /config 中的 Use custom API key。

路径 B：不使用订阅，改用按量计费密钥

Claude Code 原生支持 ANTHROPIC_BASE_URL，因此指向任何提供 Anthropic Messages API 的端点，都是官方支持的设置，不需要插件、代理或修改过的可执行文件。步骤是：注册账号、充值（最低 $10）、在密钥管理页面创建一把以 sk-kn- 开头的密钥（只显示一次），然后设置下面的变量。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

如果想先在 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-5"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "claude-sonnet-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-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-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。两者位于不同的 HTTP 标头中：前者发送 Authorization: Bearer，立即生效；后者发送 x-api-key，还需要经过上文所说的一次性确认。
• ANTHROPIC_MODEL 必须填写完整且正确的模型名称。Kunavo 只识别完全匹配的名称，不会自动将带日期后缀的旧名称映射过来。
• ANTHROPIC_DEFAULT_OPUS_MODEL负责 opus 别名。 Claude Code 的默认模型和 opus 别名都指向最新的 Opus，如果 Kunavo 尚未上线该模型，就会返回 404，因此这一行和 ANTHROPIC_MODEL 都需要固定。这里将 opus 别名固定为 Opus 5.5（claude-opus-5-5），需要 Claude Code v2.1.280 或更高版本，旧版本请先运行 claude update。
• ANTHROPIC_DEFAULT_SONNET_MODEL负责 sonnet 别名。 在 Anthropic API 中，sonnet别名指向 Sonnet 5.5，而 Kunavo 不提供该模型。如果不固定，/model sonnet、opusplan的执行阶段以及设置为 model: sonnet 的子代理都会返回 404，因此这里同样固定为 Claude Sonnet 5（claude-sonnet-5）。
• ANTHROPIC_DEFAULT_HAIKU_MODEL负责 haiku别名。从 Claude Code v2.1.293 起，haiku别名指向 Haiku 5.5；更早版本则指向带日期后缀的 Haiku 4.5 名称。Kunavo 不识别这两个名称。如果不固定指定模型，/model haiku和设为 model: haiku 的子代理（包括 Claude Code 自行启动的 claude-code-guide）都会返回 404，因此这里将其固定为 claude-haiku-4-5。
• ANTHROPIC_DEFAULT_HAIKU_MODEL 负责后台调用。Claude Code 自己执行的摘要、标题都使用这个模型：Claude Haiku 4.5 每 1M token 为 $0.70 / $3.50，主力模型 Claude Sonnet 5 为 $1.40 / $7.00（与 Anthropic 官方同价）。

不要把密钥写进项目中的 .claude/settings.json——该文件会被 commit，并分享给每个 clone 项目的人。如果使用 VS Code 扩展，变量应放在 VS Code 用户设置的 claudeCode.environmentVariables 中，因为扩展会在启动前先检查凭证。

确认连接的是哪条路径

进入 Claude Code 后执行 /status。看到 Auth token 那一行，表示密钥正在生效；看到 Login method 并列出 claude.ai 账号，表示变量没有被读取。两者不会叠加：只要密钥变量仍然存在，已登录的订阅就会被搁置；移除变量即可回到订阅，不必重新安装。

使用网关时有三件事会不同：Remote Control 和语音输入需要 claude.ai 身份，无法使用；/fast 的可用性检查会直接询问 Anthropic，可能显示不可用，但一般请求不受影响；/context 的数字会变成本地估算。编程、工具、子代理、MCP、hooks 和提示缓存都照常运行。完整说明见 Claude Code 集成文档和 Claude Code API key 指南（均为英文）。

常见错误对照

安装完成后

第一次进入项目时，先运行 /init，让它读取整个项目并生成 CLAUDE.md。之后如何根据任务切换 Opus、Sonnet、Haiku，一个工作阶段实际花费多少，以及如何使用 /clear、/compact 压低费用，都在 Claude Code 教程中。

选择哪条路径，也值得坦诚说明：每天长时间互动、用量很大的人，订阅的固定月费通常更划算；按量计费适合用量波动较大，或不想被 5 小时用量窗口限制的人，没有开工的月份费用为 $0。通过 Kunavo 使用的是共享容量，没有专属配额，也没有合约 SLA，需要这些保证的团队应直接向 Anthropic 采购。两条路径的月费与盈亏平衡点见 Claude Code 费用。

常见问题