安装 Claude Code：Windows、macOS 和 Linux 的命令——以及如何不使用订阅

安装 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 官方安装文档核对。

安装前

在 macOS 和 Linux 上安装

打开终端并粘贴：

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

这是推荐方法：安装一个会在后台自动更新的独立二进制文件。快捷方式位于 ~/.local/bin/claude，已经打开的终端无法看到新的 PATH——因此请打开另一个窗口后再测试。在 WSL 中使用相同命令。

在 Windows 上安装

Windows 上有两条不同的命令，唯一的区别在于所使用的终端。如果提示符以 PS C:\Users\SeuNome> 开头，就是 PowerShell；没有 PS、只有 C:\Users\SeuNome> 的是命令提示符（CMD）。无需以管理员身份运行。

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

:: Windows Prompt de Comando (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

将命令粘贴到错误的终端中是最常见的失败原因。在 PowerShell 中运行 CMD 命令会得到 The token '&&' is not a valid statement separator；在 CMD 中运行 PowerShell 命令会得到 'irm' is not recognized as an internal or external command（在中文版 Windows 中为“不是内部或外部命令”）。macOS 的 curl … | bash 粘贴到 PowerShell 中会得到 A parameter cannot be found that matches parameter name 'fsSL'。这三种情况只需使用正确的命令即可。

安装 Git for Windows 是可选的，但建议安装：Claude Code 使用其中附带的 Git Bash 运行命令；没有它时则使用 PowerShell。如果 Git 已安装但仍找不到 Git Bash，请在设置的 env 部分中设置 CLAUDE_CODE_GIT_BASH_PATH，并将其指向 bash.exe。

在 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) — canal stable
brew install --cask claude-code

# WinGet (Windows)
winget install Anthropic.ClaudeCode

# npm — exige Node.js 22 ou mais novo; nunca com sudo
npm install -g @anthropic-ai/claude-code

通过 npm 安装时，自 2.1.198 版本起，软件包要求 Node.js 22 或更高版本；在旧版 Node 上，npm 只会显示 EBADENGINE 警告，安装仍会完成。该软件包安装的是相同的原生二进制文件，运行时不使用 Node.js。绝不要使用 sudo npm install -g：这会导致权限问题，并带来安全风险。

检查安装

claude --version   # imprime a versão, por exemplo 2.1.211 (Claude Code)
claude doctor      # diagnóstico da instalação e das configurações, sem abrir sessão

记住 claude doctor：无需登录，它会显示安装健康状况、配置文件错误和建议的修复方式——这是最快判断问题来自安装还是配置的方法。

如果出现 command not found: claude（或者在 Windows 上提示无法识别 claude），说明安装目录不在 PATH 中。在 macOS 和 Linux 上，打开一个新的终端；如果仍未解决，请在 ~/.zshrc 或 ~/.bashrc 中将 ~/.local/bin 添加到 PATH。在 Windows 上，目录是 %USERPROFILE%\.local\bin；使用 PowerShell 检查并添加：

# 1. Veja se a pasta de instalação já está no PATH
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Sem saída? Adicione ao PATH do usuário e abra um terminal novo
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. No terminal novo: se houver duas instalações, aparecem dois caminhos
where.exe claude

首次连接：订阅或 API 密钥

路径 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   # só o domínio, sem /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 窗口中进行测试：

# Vale só para esta janela do 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 和 ANTHROPIC_DEFAULT_SONNET_MODEL。 Claude Code 的默认模型和 opus 别名都指向最新的 Opus；如果 Kunavo 尚未提供该模型，第一次请求会返回 404。sonnet 别名已经请求 Sonnet 5.5，而 Kunavo 不提供该模型：如果不固定它，/model sonnet、opusplan 的执行阶段以及设置为 model: sonnet 的子代理会收到 404。opus 别名固定为 Opus 5.5（claude-opus-5-5），这要求 Claude Code v2.1.280 或更高版本；旧版本请运行 claude update。
• 并固定设置 ANTHROPIC_DEFAULT_HAIKU_MODEL。haiku别名会请求 Kunavo 不提供的 ID（从 v2.1.293 起为 Haiku 5.5）：如果不固定模型，/model haiku和设为 model: haiku 的子代理都会返回 404。同一行还会将 Claude Code 自行发起的后台调用（摘要、标题）从主模型转移出去。

绝不要将密钥放在项目的 .claude/settings.json 中——该文件会进入 git，也会被所有克隆仓库的人获得。在 VS Code 扩展中，变量应放在 claudeCode.environmentVariables 的 VS Code 用户设置中，因为扩展会在启动前检查凭据。

从目录读取的每 1M token 价格：

要在会话内切换模型，请使用 /model 加完整名称（例如 /model claude-opus-5-5），或者使用 claude --model claude-opus-5-5 启动 Claude Code。一个月使用成本以及订阅何时更划算，请参阅 Claude Code 定价指南。

如何确认当前启用的路径

在 Claude Code 中运行 /status。出现 Auth token 行表示密钥正在生效；出现带有 claude.ai 账户的 Login method 行表示变量未被读取。二者不会叠加：设置变量后，订阅会停用；移除变量后，它会恢复使用订阅，无需重新安装。

通过网关时，有三件事会改变：Remote Control 和语音听写无法使用（它们需要 claude.ai 身份）；/fast 可能会提示快速模式不可用，因为该检查会直接访问 Anthropic，但普通请求不会改变；/context 中的数字会变为本地估算值。代码、工具、子代理、MCP、hooks 和提示缓存的工作方式不变。详情请参阅集成文档（英文）。

从巴西付款——结账时使用 Pix

claude.ai 订阅是以美元收取的周期性费用，需要一张已开通境外支付功能的国际银行卡。在 API 密钥流程中，充值通过 Stripe 结账页面完成，Pix 会作为巴西付款者可用的付款方式显示：价格以 USD 计价，Stripe 会在你确认前显示换算成雷亚尔的金额。国际银行卡（Visa、Mastercard、American Express）、Apple Pay、Google Pay 和 Link 也会出现在结账页面中。钱包采用预付费模式——最低充值 $10，余额永不过期，失败的请求不会收费——每个密钥还可以设置月度支出限额。逐屏说明请参阅如何使用 Pix 支付 API。

常见错误

安装后

首次使用时，在项目内运行 /init：Claude Code 会读取仓库，并生成一个 CLAUDE.md，其中包含它发现的测试命令和约定。请检查该文件并保持简短——它会在每个会话中加载。在无关任务之间，/clear 会开始新的对话；对于已经很长的任务，/compact 会总结历史并继续。

坦诚地说，对于每天使用 Claude Code 多个小时的人，订阅月费通常更便宜；当使用量波动，或你不想受 5 小时窗口限制时，按用量付费更划算——而整月不用时成本为零。通过 Kunavo，你使用的是共享容量，没有专用配额，也没有合同 SLA；需要这些保障的用户应直接向 Anthropic 购买。

常见问题