安装 Claude Code：Windows、macOS 和 Linux，免订阅 API 密钥，并使用 Bancontact 付款

安装 Claude Code 只需一行命令，但不同环境并不相同：在 macOS、Linux 或 WSL 的终端中运行 curl -fsSL https://claude.ai/install.sh | bash，在 PowerShell 中运行 irm https://claude.ai/install.ps1 | iex，在 Windows 命令提示符中运行 install.cmd。真正的问题出现在首次启动时：谁来支付请求？Pro、Max、Team、Enterprise 或 Console 账户都可以用于登录（Claude.ai 免费套餐不包含 Claude Code）。没有订阅时，只需一个 API 密钥：设置六个变量，其中 ANTHROPIC_BASE_URL 不应包含 /v1 和 ANTHROPIC_AUTH_TOKEN，然后查看 /status。Kunavo 余额可使用银行卡、Apple Pay、Google Pay、Link，或在比利时使用 Bancontact 充值，最低金额为 $10，无需订阅。

信息来源：命令和变量取自 Claude Code 官方文档（安装、环境变量、连接到网关），并于 2026年10月3日 重新核对；Kunavo 的价格和付款方式已于 2026年10月10日 核实。根据 Anthropic 的支持国家/地区列表（查阅日期：2026年10月3日），Claude.ai 和 API 在法国、比利时、瑞士、卢森堡、加拿大、摩洛哥、突尼斯、阿尔及利亚、塞内加尔和科特迪瓦均可使用。本指南也提供英文版，以及供佛兰德斯地区使用的荷兰语版。

应输入哪条命令：完全取决于窗口

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

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

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

前三行安装的是 Anthropic 推荐的原生版本：一个独立二进制文件，存放在 ~/.local/bin（Windows 中为 %USERPROFILE%\.local\bin），会在后台下载更新，并在下次启动时应用。安装完成后，请关闭终端并重新打开一个：用于安装的终端还不知道新的 PATH。

在 Windows 中，选错窗口是失败的首要原因，而错误消息会明确说明这一点。The token '&&' is not a valid statement separator：您把 CMD 行粘贴到了 PowerShell 中。'irm' is not recognized as an internal or external command：反过来了。在法语版 Windows 中，第二条消息可能会显示为翻译后的内容；原因不变。其他消息列在指南末尾的错误表中。

要求

Windows：旧教程所说的内容，以及如今真正适用的内容

不少法语教程写于 Claude Code 的早期版本。以下列出其中最常见的操作说明，并与当前安装文档和故障排除页面（查阅日期：2026年10月3日）进行了对照：

如果您安装了 Git for Windows，Claude Code 会通过 Git Bash 运行，并同时保留 PowerShell 工具。有时它找不到 bash.exe：此时请在 ~/.claude/settings.json 中的 env 代码块内，将其路径填入 CLAUDE_CODE_GIT_BASH_PATH 变量（文档示例为 C:\Program Files\Git\bin\bash.exe）。最后一个容易踩的坑：「Windows PowerShell (x86)」快捷方式会启动 32 位版本，Claude Code 不支持该版本。

使用原生 Windows 还是 WSL，取决于项目所在的位置：

在 WSL 中，所有操作都在 Linux 发行版内部进行：在这里粘贴 curl … | bash，随后也在这里输入 claude。如果从 PowerShell 或 CMD 启动，它看不到这次安装。

Homebrew、WinGet、apt 或 npm

包管理器可以正常工作，但有一个代价：Claude Code 不会通过它们自动更新。对于 Homebrew 和 WinGet，变量 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 会让 Claude Code 自行启动更新；没有该变量，就需要您手动更新：

# Homebrew (macOS)
brew install --cask claude-code
brew upgrade claude-code              # pas de mise à jour automatique

# WinGet (Windows)
winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode   # pas de mise à jour automatique

在 Debian、Ubuntu、Fedora、RHEL 和 Alpine 上，Anthropic 还提供经过签名的 apt、dnf 和 apk 软件源，这些软件源会随系统其余部分一起更新；操作步骤见安装页面。

如果 Node.js 已经是您工具链的一部分，也可以使用 npm。该软件包至少需要 Node.js 22。在更早版本上，npm 只会发出 EBADENGINE 警告，然后继续完成安装，因为该软件包安装的是同一个不需要 Node.js 才能运行的原生二进制文件。遵循两条规则：不要使用 sudo npm install -g，并使用 @latest 更新，因为 npm update -g 仍处于原始版本范围内，可能让您停留在旧版本。

node -v                                       # v22 ou plus récent
npm install -g @anthropic-ai/claude-code      # jamais avec sudo

# mise à jour : avec @latest, pas avec npm update -g
npm install -g @anthropic-ai/claude-code@latest

验证安装并修复 PATH

claude --version   # affiche le numéro de version, suivi de (Claude Code)
claude doctor      # diagnostic de l’installation et des réglages, sans ouvrir de session

如果返回版本号，就表示安装完成。claude doctor 不会启动会话，但会进一步检查：安装状态、设置文件中的错误以及上次更新的结果。出现问题时，这是首先应运行的命令。

macOS 或 Linux 上出现 command not found: claude，Windows 上出现“无法识别”claude：程序已正确安装，但 shell 不知道该去哪里查找它。通常只需新开一个窗口即可。否则，请将 ~/.local/bin 添加到 ~/.zshrc 或 ~/.bashrc 中的 PATH。Windows 用户可按照官方故障排除页面上的三个 PowerShell 步骤操作：

# 1. Le dossier d'installation est-il déjà dans le PATH ?
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Aucun résultat ? Ajoutez-le au PATH de l'utilisateur, puis ouvrez une nouvelle fenêtre
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Dans la nouvelle fenêtre : deux chemins = deux installations concurrentes
where.exe claude

通过 npm 安装后，PowerShell 返回 npm.ps1 cannot be loaded？其执行策略阻止了 npm 脚本。改用原生安装程序，或仅为您的账户允许运行本地脚本：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

谁来支付请求：Claude 订阅还是 API 密钥

这个选择不在安装时做出，而是在首次启动时做出，并且可以随时切换。环境中定义的密钥优先于已保存的 claude.ai 连接，后者会暂时停用；删除该变量后，连接会在下一次启动时重新生效。

使用 Claude 订阅

无需配置：在项目目录中运行 claude，然后在浏览器中登录。唯一的例外是环境中残留的 ANTHROPIC_API_KEY。此时 Claude Code 会询问一次是否使用它；拒绝后会被记住，密钥随后会被静默忽略，这会让人误以为变量没有被读取。要更改此选择：/config → Use custom API key。

没有订阅：Kunavo API 密钥

将 Claude Code 指向 Anthropic 以外的服务并非权宜之计。官方环境变量列表将 ANTHROPIC_BASE_URL 列为把请求发送到代理或网关的方式。Kunavo 使用 Anthropic Messages API 格式响应：您可以继续使用官方 Claude Code，无需扩展或修改版本。

1. 创建账户：注册 Kunavo。
2. 在 Billing 中为余额充值，最低金额为 $10（支付方式见下文）。
3. 在 /app/keys 中生成密钥。密钥以 sk-kn- 开头，且只在创建时显示：请立即复制。
4. 填写下面的六个变量。

为什么要固定四个模型？Claude Code 的别名会随 Anthropic 的版本发布而变化。根据模型配置文档（查阅日期：2026年10月3日），对于 API 账户，目前默认设置和 opus 都指向 Opus 5.5，而 sonnet 指向 Kunavo 不提供的 Sonnet 5.5：如果没有设置 ANTHROPIC_DEFAULT_SONNET_MODEL，/model sonnet、opusplan 的执行阶段以及设为 sonnet 的子代理都会遇到 404。别名 opus 固定到 Opus 5.5（claude-opus-5-5），该模型要求 Claude Code v2.1.280 或更新版本；如果版本较旧，请运行 claude update。Kunavo 也不一定会在新模型发布当天就提供该模型。使用完整模型名称后，每个请求都会发送到 Kunavo 提供的模型，价格也一目了然。网关协议文档（查阅日期：2026年10月3日）确认了后台任务相关的说明：使用 Claude Haiku 4.5 时，这些任务的费用较低。

变量应写入的位置

建议使用的版本；如果文件已有内容，请将其与现有内容合并（只添加 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"
  }
}

macOS 和 Linux 中 shell 的相同值：

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # le domaine seul, sans /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

要在 PowerShell 窗口中快速测试：

# Valable uniquement dans cette fenêtre 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

对于 VS Code 扩展，请在编辑器的用户设置中使用命令 Preferences: Open User Settings (JSON)：

{
  "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" }
  ]
}

Claude 桌面应用是例外：它既不读取 ANTHROPIC_BASE_URL，也不读取 settings.json。如果在 shell 中修改变量却没有效果？先检查 settings.json 中是否存在相同变量，因为它的优先级更高。

以下为 Kunavo 目录中的每百万 token 价格，以及在 claude.com/pricing 查到的 Anthropic 公开价格（查阅日期：2026年10月3日）：

要在一项任务期间切换到 Opus：在会话中运行 /model opus（固定到 claude-opus-5-5 的别名），或在启动时运行 claude --model claude-opus-5-5。根据您的使用情况计算的月度预算，以及订阅开始更划算的门槛，都列在 Claude Code 价格 中。Claude token 成本计算器 可根据您自己的用量进行计算，而价格页面列出了所有模型。

使用 /status 验证

第一个迹象甚至早于 /status：设置好 ANTHROPIC_AUTH_TOKEN 后，Claude Code 会不显示登录界面直接启动。如果出现该界面，则表示没有读取到任何密钥，通常是因为密钥只存在于项目设置中（.claude/settings.json 或 .claude/settings.local.json）。在交互式会话中，只有完成首次启动助手并确认信任该目录后，才会应用此 env 块。请将密钥移到 shell 中，或移到 ~/.claude/settings.json。

进入会话后，/status 会打开 Status 选项卡。根据网关文档（查阅日期：2026年10月3日），各项内容的含义如下：

您之前已经使用订阅登录？此时 Claude Code 可能会在启动时提示有两个身份验证来源处于活动状态，警告以 auth may not work as expected 结尾。实际用于请求的是密钥；运行 /logout 会删除旧连接并消除警告。

要判断问题来自 Kunavo 还是您的配置，请不使用 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": "."}]}'

如果 JSON 以 {"id":"msg_ 开头，或在 PowerShell 中对象的 id 以 msg_ 开头，则表示地址和密钥有效。出现 401：表示密钥被拒绝。

使用 API 密钥后的变化

• Remote Control 和语音听写会消失。二者都依赖 claude.ai 账户，只要定义了 ANTHROPIC_AUTH_TOKEN 就无法使用。当 ANTHROPIC_BASE_URL 指向 Anthropic 之外的其他主机时，Remote Control 也会关闭。
• 快速模式（/fast）会显示为已停用，因为其验证要求使用 claude.ai 连接或 Anthropic 密钥，而不是普通的 bearer token。
• 当 ANTHROPIC_BASE_URL 指向 Anthropic 之外的位置时，MCP 工具搜索默认会被关闭。
• /context 显示的是估算值。Kunavo 不提供 /v1/messages/count_tokens；在这种情况下，Claude Code 会根据字符数进行计数（参见网关协议文档）。

其余功能（代码读写、工具、子代理、MCP 服务器、hooks、提示缓存）均不变。技术细节以英语记录在 Claude Code 集成文档中。

从法国或比利时付款

请勿混淆这两种付款渠道。通过网页购买的 Claude 订阅只能用信用卡或借记卡支付（Anthropic 账单常见问题，查阅日期：2026年10月3日）；通过移动应用订阅则由 App Store 或 Google Play 处理。claude.com/pricing 上的金额未含税。

Kunavo 余额则通过 Stripe 付款页面充值。价格以美元计，但从法国或比利时访问时，Stripe 会显示欧元金额，采用保证 24 小时有效的汇率，其中包含由您承担的 2% 至 4% 货币兑换费（Stripe 关于 Adaptive Pricing 的文档，查阅日期：2026年10月3日）。您可以用美元付款以避免这项费用，但届时由银行按其汇率兑换；此外，只有以欧元付款时才提供 Bancontact。可用的付款方式：

• 法国 CB 卡？根据Stripe 关于 Cartes Bancaires 的文档（查阅日期：2026年10月3日），超过 95% 的 CB 卡同时带有 Visa 或 Mastercard 标志。因此，这些卡在结账时会作为 Visa 或 Mastercard 处理，普通借记卡也可以使用。
• Bancontact面向位于比利时的买家提供。Stripe 会将您转到 Bancontact 网站或应用进行验证，并立即显示结果（Stripe 关于 Bancontact 的文档，查阅日期：2026年10月3日）。
• Pay by Bank（通过网上银行付款）在法国和比利时不可用：结账页面仅向位于英国、爱尔兰和芬兰的买家显示此选项。根据Stripe 关于 Pay by Bank 的文档（查阅日期：2026年10月3日），该服务在法国属于私人预览版，且文档未提及比利时。
• 从瑞士或加拿大付款时，金额会以瑞士法郎或加拿大元显示，可使用银行卡和 Link，也可使用依托银行卡的 Apple Pay 和 Google Pay。

不提供：PayPal、SEPA 直接借记，以及仅限美国买家使用的 Klarna（仅以美元付款并不够）。

1. 注册 Kunavo；此时无需提供银行卡。
2. 在 Billing 中选择金额：最低为 $10。更高金额可获得奖励（已支付 $100，已到账 $110；已支付 $1.000，已到账 $1.200；已支付 $5.000，已到账 $6.250）。
3. 在 Stripe 页面上选择支付方式；确认前会显示欧元金额。使用 Bancontact 时，请在应用中或使用银行卡完成确认。
4. 在 /app/keys 中创建密钥，并将其填入 ANTHROPIC_AUTH_TOKEN。

余额为预付余额：无月费、永不过期，失败的请求不会收费。自动充值需要已保存的银行卡或 Link。Bancontact 不支持 Stripe 的定期付款，因此每次使用 Bancontact 充值都必须手动发起。Kunavo 不提供任何国家/地区的含增值税发票，包括法国和比利时；充值历史可在 Billing 中查看。最后，这些支付方式仅用于 Kunavo API 余额，不能用于支付 Claude Pro 或 Max 订阅。包括 App Store 和 Google Play 在内的其他所有方案，都在 无需银行卡支付 Claude 中进行了介绍。

常见错误

项目入门

在 Claude Code 首次发现的代码仓库中，先运行 /init：它会探索代码，并编写 CLAUDE.md，记录发现的测试命令和约定。请检查并精简该文件，因为它会在每次会话中重新加载。要切换主题，请运行 /clear 开始全新对话；要继续长任务，请运行 /compact 总结历史记录。

API 密钥的限制

• 您按使用量付费，而不是购买 Claude Pro 或 Max 套餐。每天使用 Claude Code 数小时且持续使用时，订阅通常更划算；使用不规律时，按 token 付费更灵活，使用较少的月份无需支付费用。具体数字见 Claude Code 价格。
• 只要密钥处于活动状态，就无法使用 Remote Control 或语音听写。
• Kunavo 的容量是共享的，没有预留配额或合同承诺；如果您需要这些保障，请直接与 Anthropic 签约。
• Bancontact 仅支持手动充值；自动充值需通过已保存的银行卡或 Link。
• 欧元金额包含 Stripe 的兑换费用，Kunavo 不开具含增值税的发票。

常见问题