安装 Claude Code：Windows、macOS 和 Linux 的命令、无需订阅的 API 密钥，以及使用 MB WAY 支付

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 行）。之后有两种使用方式。使用订阅时，使用 Pro、Max、Team、Enterprise 或 Console 账户登录（只有 Claude.ai 免费计划的用户无法使用 Claude Code）。没有订阅时，使用 API 密钥：设置 ANTHROPIC_BASE_URL（仅域名，不含 /v1）、ANTHROPIC_AUTH_TOKEN 和四个模型变量，并使用 /status 确认。Kunavo 余额可在欧元结账页面使用 MB WAY 充值，最低金额为 US$ 10，无月费。

我们于 2026年10月3日 对照Claude Code 官方安装文档和环境变量文档核实了命令和变量；于 2026年10月10日 核实了价格和支付方式。葡萄牙在Anthropic 支持的国家/地区列表中（查询于 2026年10月3日），Claude.ai 和 API 均支持葡萄牙。本指南也提供英文版：安装 Claude Code。

安装前

macOS、Linux 和 WSL：一行命令

在终端中（macOS 上位于“应用程序 › 实用工具”），执行：

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

这是推荐的原生安装方式：一个独立程序，根据官方文档会在后台自动更新。claude 命令位于 ~/.local/bin。已经打开的终端尚未识别新的 PATH，因此请在测试前打开一个新窗口。在 WSL 中，命令完全相同，应在 WSL 终端内执行。

在 Windows 上安装

Windows 上有两行命令，选择仅取决于当前打开的窗口。如果命令行以 PS C:\Users\Nome> 开头，则使用的是 PowerShell；如果只显示 C:\Users\Nome>，不含 PS，则使用的是命令提示符（CMD）。无需使用“以管理员身份运行”：官方文档明确说明不需要，这与一些葡萄牙语指南的建议相反。

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

:: Linha de Comandos do Windows (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

在 Windows 上，最常见的问题是窗口选错。如果 PowerShell 返回 The token '&&' is not a valid statement separator，说明输入了 CMD 命令；如果 CMD 返回 'irm' is not recognized as an internal or external command，说明输入了 PowerShell 命令。在葡萄牙语 Windows 中，第二条消息可能会以翻译后的形式出现，但原因相同。此外，将带有 | bash 的 macOS 命令粘贴到 PowerShell 中，会报错说 bash 未被识别。这三种情况下，解决方法都是使用与当前窗口对应的命令。

Git for Windows 是可选的。安装后，Claude Code 的 Bash 工具会在 Git Bash 中运行，PowerShell 仍可同时使用；未安装时，所有命令都通过 PowerShell 运行。如果 Git 安装在非默认目录，且 Claude Code 找不到 bash.exe，请在 ~/.claude/settings.json 的 env 区块中通过 CLAUDE_CODE_GIT_BASH_PATH 指定其路径；文档中的示例为 C:\Program Files\Git\bin\bash.exe。

因此，WSL 是一种选择而非要求，这与一些指南中的说法相反。选择 WSL 的用户应在 WSL 终端中执行 macOS/Linux 命令，并在那里启动 claude，而不是从 PowerShell 或 CMD 启动。

通过 Homebrew、WinGet 或 npm

也可以使用，但有一个重要区别：根据官方文档，通过 Homebrew 和 WinGet 安装的版本不会自动更新。需要手动更新。此外，Linux 还有已签名的 apt、dnf 和 apk 软件源。

# Homebrew
brew install --cask claude-code
brew upgrade claude-code              # não se atualiza sozinho

# WinGet (Windows)
winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode   # não se atualiza sozinho

npm 软件包需要 Node.js 22 或更高版本——不是一些指南仍然指示的 Node.js 18。使用较旧的 Node.js 时，npm 只会在安装期间显示 EBADENGINE 警告，而不会失败。不要使用 sudo npm install -g：官方文档明确不建议这样做。更新时请使用 @latest，不要使用 npm update -g。

node -v                                           # tem de ser v22 ou posterior
npm install -g @anthropic-ai/claude-code          # nunca com sudo

# para atualizar mais tarde: com @latest, não com npm update -g
npm install -g @anthropic-ai/claude-code@latest

确认安装

claude --version   # mostra o número da versão, seguido de (Claude Code)
claude doctor      # diagnóstico só de leitura da instalação e das definições, sem abrir sessão

claude doctor 不会启动任何会话：它会显示安装状态和设置文件状态。这是判断问题出在安装还是配置上的最快方式。

command not found: claude（或在 Windows 上提示 claude 不是已知命令）表示终端不知道程序安装在哪里。很多时候，只需关闭窗口再重新打开即可。如果问题仍然存在，说明该目录未加入 PATH：macOS 和 Linux 上的目录是 ~/.local/bin，应将其添加到 shell 启动文件（~/.zshrc 或 ~/.bashrc）中；Windows 上的目录是 %USERPROFILE%\.local\bin。根据官方故障排查指南，可在 PowerShell 中按如下方式确认并添加：

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

# 2. Sem resultado? Acrescente-a ao PATH do utilizador e abra uma janela nova
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Na janela nova: dois caminhos significam duas instalações lado a lado
where.exe claude

如果你通过 npm 安装，并且 PowerShell 返回 npm.ps1 cannot be loaded because running scripts is disabled on this system，则是 PowerShell 的执行策略阻止了 npm 脚本。请使用原生安装程序，或允许当前用户运行本地脚本：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

如果出现 Claude Code does not support 32-bit Windows，说明打开的是“Windows PowerShell (x86)”。Windows 有两个 PowerShell 入口，x86 版本以 32 位进程运行；请打开不带 (x86) 的“Windows PowerShell”入口。

首次使用：订阅或 API 密钥

首次启动时会决定 Claude Code 的付费方式。更改路由不需要重新安装：决定因素是是否设置了密钥。

路线 A——使用订阅登录

在项目目录中执行 claude，然后在浏览器中登录。注意：如果环境中已有 ANTHROPIC_API_KEY，Claude Code 不会打开浏览器，而是要求对该密钥进行一次性批准。拒绝批准后，该密钥将被忽略，问题不会再次出现，看起来就像变量未被读取。重新启用方法：/config → Use custom API key。

路线 B——不使用订阅，使用 API 密钥

ANTHROPIC_BASE_URL 是 Claude Code 自身的变量，用于通过代理或网关转发请求。因此，将其指向兼容 Anthropic Messages API 的端点是受支持的配置，无需插件或修改版。步骤如下：

1. 创建 Kunavo 账户。
2. 在 账单 中充值，最低金额为 US$ 10（MB WAY 支付方式见下文）。
3. 在 /app/keys 中创建一个以 sk-kn- 开头的密钥。密钥只显示一次，因此最好立即保存。
4. 设置变量。在 macOS 和 Linux 上，在 ~/.zshrc 或 ~/.bashrc 中：

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

如需永久使用，最佳位置是用户设置中的 env 块：~/.claude/settings.json（Windows 上为 %USERPROFILE%\.claude\settings.json）。其中的值会应用于所有项目，包括后台代理；VS Code 扩展除外（见下文）。在 shell 中导出的变量只会传递给从该 shell 启动的程序：通过 Dock 或“开始”菜单打开的编辑器看不到它。如果文件中已有其他设置，只需添加 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"
  }
}

切勿将密钥放入项目的 .claude/settings.json：根据官方网关文档（查阅于 2026年10月3日），此文件会包含在提交中，并与任何克隆该仓库的人共享。还要注意优先级：当 shell 和设置文件定义了同一个变量时，以设置文件为准。如果在 shell 中所做的更改没有生效，请先检查 settings.json。

使用 VS Code 扩展的用户应在 claudeCode.environmentVariables 中设置变量，即 VS Code 自身的用户设置中（命令 Preferences: Open User Settings (JSON)）。根据网关文档，扩展会在启动前先检查此设置中的凭据；~/.claude/settings.json 中的值会传递给 Claude Code 进程，但不会传递给该检查：

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://api.kunavo.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-kn-..." },
    { "name": "ANTHROPIC_MODEL", "value": "claude-sonnet-5" },
    { "name": "ANTHROPIC_DEFAULT_OPUS_MODEL", "value": "claude-opus-5-5" },
    { "name": "ANTHROPIC_DEFAULT_SONNET_MODEL", "value": "claude-sonnet-5" },
    { "name": "ANTHROPIC_DEFAULT_HAIKU_MODEL", "value": "claude-haiku-4-5" }
  ]
}

四个模型变量和其他注意事项

该块中的每一行都有需要注意的地方：

• ANTHROPIC_BASE_URL 中不能包含路径。 路径 /v1/messages 会由 Claude Code 自行附加；已经以 /v1 结尾的地址会变成 /v1/v1/messages，从而返回 404。
• ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY：Kunavo 两者都接受。 根据网关文档，ANTHROPIC_AUTH_TOKEN 会使用 Authorization: Bearer 标头并立即生效；ANTHROPIC_API_KEY 会使用 x-api-key 标头，在交互模式下必须先批准一次才能生效（见路线 A）。因此本指南使用 ANTHROPIC_AUTH_TOKEN。
• ANTHROPIC_MODEL 中的名称必须准确。 请按此处显示的内容复制：claude-sonnet-5。
• 不设置 ANTHROPIC_DEFAULT_SONNET_MODEL 和 ANTHROPIC_DEFAULT_OPUS_MODEL，别名就会自行变化。根据模型配置文档（查询于 2026年10月3日），对于使用 Anthropic API 的用户，别名 opus 指向 Opus 5.5，别名 sonnet 指向 Sonnet 5.5；这些别名会随新版本发布而变化。可通过完整模型名称或变量（例如 ANTHROPIC_DEFAULT_OPUS_MODEL）固定版本。Kunavo 不提供 Sonnet 5.5，不存在的模型会返回 404：如果不设置 ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5，/model sonnet、使用 model: sonnet 的子代理以及 opusplan 的执行阶段都会失败。另一方面，opus 指向 claude-opus-5-5，Kunavo 提供该模型，但要求使用 Claude Code v2.1.280 或更高版本；旧版本用户请运行 claude update。
• 还要设置 ANTHROPIC_DEFAULT_HAIKU_MODEL。 别名 haiku 请求的是 Kunavo 未提供的 ID：从 v2.1.293 起为 Haiku 5.5，此前则是带日期的 Haiku 4.5 ID。缺少这一行时，/model haiku 和使用 model: haiku 的子代理会返回 404。
• ANTHROPIC_DEFAULT_HAIKU_MODEL 也会影响后台任务。 根据文档，它定义 haiku 别名和 Claude Code 后台功能使用的模型。设置 Claude Haiku 4.5 后，这些调用会使用下表中最便宜的模型。

每百万 token 的价格来自 Kunavo 目录；Anthropic 一栏来自 claude.com/pricing（查询于 2026年10月3日）：

在会话中，可以使用 /model claude-opus-5-5 切换模型，也可以直接使用 claude --model claude-opus-5-5 启动。欧元计费、每月使用示例以及订阅更划算的起点，见Claude Code 欧元价格；每个人的用量可使用token 成本计算器计算。所有模型和价格都列在价格页面。

使用 /status 确认

执行 claude。设置了 ANTHROPIC_AUTH_TOKEN 后，不会出现登录界面：变量会立即生效。如果出现登录界面，则 Claude Code 没有读取任何密钥。这种情况下，请将密钥设置在 Claude Code 会在首次启动助手之前读取的位置：shell 中的 export，或 ~/.claude/settings.json 的 env 块。项目的 .claude/settings.json 或 .claude/settings.local.json 中的 env 块，在交互会话中只有在首次启动助手以及回答是否信任该文件夹之后才会生效。

在会话中输入 /status，然后在 Status 选项卡中查找两行信息（来源：官方网关文档，查询于 2026年10月3日）：

• Anthropic base URL 应显示 https://api.kunavo.com。只有定义了网关地址时才会显示这一行；如果缺少该变量，ANTHROPIC_BASE_URL 就不会传递到会话中。
• Auth token 行应显示 ANTHROPIC_AUTH_TOKEN。如果显示的是 Login method，并且关联的是 claude.ai 账户，则变量未被读取，会话正在使用订阅。

已经使用订阅登录的用户在启动时可能会看到有两个凭据处于活动状态的警告（消息以 auth may not work as expected 结尾）。请求会通过密钥发送；/logout 会清除旧的登录状态。

在打开 Claude Code 前测试地址和密钥时，文档建议发送一个只返回单个输出 token 的请求，只会消耗极少一部分余额。这些命令会读取 shell 中的变量，因此即使变量已经写入 settings.json，也要在那里设置它们。

curl -sS -w '\n%{http_code}\n' -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": "."}]}'

Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
  -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

以 {"id":"msg_ 开头的 JSON 响应表示地址和密钥有效；在 PowerShell 中会显示一个以 msg_ 开头的 id。401 表示密钥未被识别。

使用 API 密钥会发生什么变化

• 没有 Remote Control 或语音听写。 根据网关文档，只要 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 或 apiKeyHelper 处于启用状态，这些功能就不可用；当 ANTHROPIC_BASE_URL 指向 Anthropic 之外的地址时，Remote Control 也会被禁用。
• /fast 将快速模式显示为已禁用。仅使用 bearer token 时，Claude Code 会将快速模式视为关闭。
• 当 ANTHROPIC_BASE_URL 指向 Anthropic 以外的地址时，MCP 工具搜索（MCP tool search）默认处于关闭状态（环境变量文档，查询于 2026年10月3日）。
• /context 中的数值是估算值。Kunavo 不提供 /v1/messages/count_tokens。根据网关兼容性文档（查询于 2026年10月3日），没有该端点时，Claude Code 会根据字符数进行估算。

其余部分——代码、工具、子代理、MCP 服务器、hooks 和提示缓存——均按原样运行。更多详情请参阅Claude Code 集成文档（英文）以及Claude Code without a subscription（英文）。

使用 MB WAY 支付余额

首先说订阅：通过 Claude 网站购买的 Claude 订阅只能使用信用卡或借记卡支付（Anthropic付费方案帮助文章，查询于 2026年10月3日）；在 Claude iOS 或 Android 应用中订阅，则使用 App Store 或 Google Play 提供的支付方式。Kunavo 的支付方式（包括 MB WAY）不能用于支付 Claude Pro 或 Max，只能用于为 Kunavo API 余额充值，该余额用于路线 B。

余额通过 Stripe 结账页面充值。价格以美元计价；在葡萄牙购买的用户会看到 Stripe 显示的欧元金额。根据 Stripe 关于 Adaptive Pricing 的文档（查询于 2026年10月3日），该兑换包含 2–4% 的手续费，由买家承担；选择以美元付款的用户（使用银行卡、Apple Pay、Google Pay 或 Link）无需支付这笔手续费，但银行可能会采用自己的汇率并收取手续费。MB WAY 仅支持欧元。欧元结账页面提供：

• MB WAY。选择 MB WAY，输入手机号码，然后通过通知或活动页面在 MB WAY 应用中确认购买（Stripe 的MB WAY 说明和 MB WAY 的在线购物说明，查询于 2026年10月3日）。Stripe 表示，系统接受国际号码，但大多数客户使用以 +351 开头的葡萄牙号码。
• 银行卡（Visa、Mastercard）、Apple Pay、Google Pay 和 Link。

以下方式不提供：Multibanco 参考码（通过实体和参考码付款）、PayPal、SEPA 直接扣款以及 Klarna；Klarna 仅向美国买家提供。欧元兑换来自 Stripe 的 Adaptive Pricing，其支持的支付方式列表包含 MB WAY，但不包含 Multibanco。MB WAY 也支持生成用于在线购物的 MB NET 虚拟卡（MB WAY 的MB NET 说明，查询于 2026年10月3日）；尚未确认结账页面的银行卡字段是否接受此类卡，因此稳妥的方式是直接选择 MB WAY。

Stripe 文档中关于 MB WAY 的内容（核查于 2026年10月3日）：

• 每笔支付：0.50 € 至 5000 €。
• 每天：默认 1000 €，可在 MB WAY 应用中调整至 10,000 €。较大的充值可能超过预设每日限额；在这种情况下，请先在应用中提高限额再付款。请将结账页面显示的欧元金额与这些限额进行比较。
• 周期性付款：不支持。
• 账单中会显示 Stripe 的名称（Stripe Inc）以及交易金额。

1. 创建 Kunavo 账户。
2. 在 账单 中选择金额，最低金额为 US$ 10。较大的充值会获得额外余额：充值 US$ 100 的用户会获得 US$ 110；充值 US$ 1000 的用户会获得 US$ 1200；充值 US$ 5000 的用户会获得 US$ 6250。
3. 在 Stripe 结账页面中，以欧元金额选择 MB WAY，输入手机号码，并在 MB WAY 应用中确认购买。欧元金额会在确认前显示。
4. 在 /app/keys 中创建密钥，并将其放入 ANTHROPIC_AUTH_TOKEN。

余额采用预付费模式：没有月费，余额不会过期，失败的请求不会收费。自动充值仅适用于已保存的银行卡或 Link；使用 MB WAY 时始终需要手动充值，因为根据 Stripe 的说明，MB WAY 不接受周期性付款，也不会保存以供未来付款使用。Kunavo 不开具发票，无论是否提供 NIF 或 IVA；充值记录保存在 Billing 中。这些支付方式只能为 Kunavo API 余额充值。更多相关信息请参阅使用 MB WAY 支付 Claude。

常见错误

安装后

在项目中首次启动时，请输入 /init：Claude Code 会遍历仓库，并写入一个 CLAUDE.md，其中包含它推断出的信息：如何运行项目、如何测试更改，以及项目遵循哪些样式规则。请检查该文件并保持简短，因为它会在每个会话中加载。在独立任务之间，/clear 会开始新的对话；在长任务中，/compact 会总结历史记录以便继续。

需要了解的事项

• 这是按 token 付费的 API，不是 Claude Pro 或 Max 订阅。每天使用 Claude Code 数小时的人通常通过订阅支付更少；按 token 付费适合使用不规律的情况，而停用一个月不会产生费用。欧元价格比较见Claude Code 的欧元价格。
• 使用 API 密钥的用户无法使用 Remote Control 和语音听写。
• 通过 Kunavo 使用的是共享容量，没有预留配额，也没有合同保障；需要这些保障的用户应直接与 Anthropic 签约。
• MB WAY 仅用于手动充值；自动充值需要银行卡或 Link。
• 结账页面显示的欧元金额已包含 Stripe 的兑换手续费。

常见问题