在 Windows、Mac 和 Linux 上安装 Claude Code：无需订阅的 API 密钥，以及使用 Satispay 付款

安装 Claude Code 只需一个命令，具体取决于终端：macOS、Linux 和 WSL 使用包含 install.sh 的命令行，PowerShell 使用 irm … | iex，命令提示符使用包含 install.cmd 的命令行。这是 Anthropic 推荐的方法；也可以使用 npm，但需要 Node.js 22 或更高版本。Claude 免费套餐不包含 Claude Code，因此需要 Pro 或更高版本的订阅，或者 API 密钥。这里采用第二种方式：ANTHROPIC_BASE_URL=https://api.kunavo.com（不带 /v1），将密钥放入 ANTHROPIC_AUTH_TOKEN，设置四个固定模型的变量，并使用 /status 进行最终验证。余额通过欧元 Satispay 从 $10 起充值，并且只需支付实际消耗的 token。

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

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

:: Windows – Prompt dei comandi (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

这些命令的来源：Claude Code 文档也提供意大利语版本，我们于 2026年10月3日 重新查阅了相关内容，尤其是安装和LLM 网关页面。Kunavo 的价格和支付方式已更新至 2026年10月10日。Anthropic 在意大利同时提供 Claude.ai 和 API 服务（支持的国家和地区，查阅于 2026年10月3日）。

所需条件

官方文档（查阅于 2026年10月3日）列出的要求不高：

• macOS 13.0 或更高版本；Windows 10 1809 或更高版本，或 Windows Server 2019 或更高版本；Ubuntu 20.04+、Debian 10+ 或 Alpine Linux 3.19+。
• 至少 4 GB RAM，以及 x64 或 ARM64 处理器。不支持 32 位 Windows。
• Bash、Zsh、PowerShell 和 CMD 中的任意一种 shell。
• 需要从 Anthropic 支持的国家/地区连接：意大利在支持范围内。
• 仅在选择 npm 时需要 Node.js，此时版本须为 22 或更高。

在哪个终端中运行哪个命令

不需要管理员权限，也不需要 WSL：官方文档对此有明确说明，尽管网上不止一份指南给出了相反建议。安装完成后，Claude Code 会在后台自动更新。如果更喜欢使用包管理器，可以使用 Homebrew 或 WinGet，但在这种情况下需要手动启动更新：

# Homebrew – canale stable; non si aggiorna da solo
brew install --cask claude-code

# WinGet (Windows) – non si aggiorna da solo
winget install Anthropic.ClaudeCode

开始尝试前，关闭终端并打开一个新终端：只有新窗口才会重新读取 PATH。然后进行验证。claude doctor 之后也会派上用场，因为它可以在不打开会话的情况下检查安装和设置，并立即告诉你问题出在其中哪一项。

claude --version   # stampa la versione, ad esempio 2.1.284 (Claude Code)
claude doctor      # diagnostica di installazione e impostazioni, senza aprire una sessione

下载被阻止：403 或脚本位置出现 HTML 页面

安装脚本未能下载时，终端的报错可能不够清楚：bash 会报 syntax error near unexpected token '<'（它试图执行一个网页），或者 curl 会因 curl: (22) The requested URL returned error: 403 而停止。官方安装问题排查页面（英文，查阅于 2026年10月3日）区分了两种情况。如果下载的页面显示 App unavailable in region，说明服务器认为你是从不支持的国家或地区连接的：从意大利连接时，这几乎总是因为 VPN 或代理的出口位于国外。没有附带文本的 403 错误通常来自企业代理或防火墙。更换安装方式没有帮助，因为 Homebrew 和 WinGet 也会从相同的服务器下载：请尝试使用其他网络，或请 IT 部门解除对这些域名的限制。

使用 npm：Node.js 22，而不是 18

如果你每天都在使用 Node.js，npm 看起来是很自然的选择。它可以正常使用，也是文档列出的方法之一，但有一项许多意大利语指南尚未更新的要求：需要 Node.js 22 或更高版本。使用更旧的 Node.js 时，你会看到 EBADENGINE 警告，但安装仍会完成，claude 也仍能启动（官方文档，查阅于 2026年10月3日）。Node.js 最新版本可从 nodejs.org 获取。

node -v                                    # serve v22 o successiva
npm install -g @anthropic-ai/claude-code   # senza sudo

# aggiornamento: @latest, non npm update -g
npm install -g @anthropic-ai/claude-code@latest

应避免的三种做法：

• 在 npm install -g 前加上 sudo。 官方文档不建议这样做，原因包括权限冲突和安全问题。
• 使用 npm update -g 进行更新。 应改为使用 @latest 重新安装，就像上面最后一行所示。
• 跳过可选依赖项。 Claude Code 的二进制文件正是作为可选依赖项提供的，每个平台对应一个 @anthropic-ai/claude-code-* 软件包。使用 --omit=optional，或在 .npmrc 文件中设置 optional=false 时，都不会下载该二进制文件；在 macOS 或 Linux 上，claude 会返回 claude native binary not installed（安装问题排查，英文，查阅于 2026年10月3日）。

Windows 上的 Claude Code：容易卡住的地方

Claude Code 可在 Windows 上原生运行，安装本身很简单。问题通常出在运行环境。首先是终端：如果在 PowerShell 中粘贴 CMD 命令行，PowerShell 会因 && 报错；如果在 CMD 中粘贴 PowerShell 命令行，CMD 不认识 irm；而 Mac 上的 curl … | bash 命令行在 PowerShell 中完全无法运行。在意大利语版 Windows 上，其中一些报错可能会以翻译后的文本显示。无论哪种情况，解决办法都是回到上方的表格，选择与你当前终端对应的命令行（英文报错列于页面底部的错误表格中；来源：文档，查阅于 2026年10月3日）。

还要注意“开始”菜单：“Windows PowerShell (x86)”会打开 32 位进程，即使电脑是 64 位，Claude Code 也会因 Claude Code does not support 32-bit Windows 而停止。请选择不带 (x86) 的选项。

Git for Windows 不是必需的。如果已安装，Claude Code 会通过 Git Bash 执行命令；如果未安装，则使用 PowerShell。当 Git 已安装但 Claude Code 找不到 bash.exe 时，请在 ~/.claude/settings.json（通常是 C:\Program Files\Git\bin\bash.exe）的 env 块中，通过 CLAUDE_CODE_GIT_BASH_PATH 指定其路径。那 WSL 呢？它只适用于一种特定情况：

使用 WSL 时，所有操作都在 Linux 中进行：应在 WSL shell 中运行 install.sh，然后从那里启动 claude。

找不到“claude”

如果安装后终端返回 command not found: claude 或 'claude' is not recognized，说明程序存在，但其目录不在 PATH 中。原生安装程序会在 macOS 和 Linux 上将其复制到 ~/.local/bin/claude，在 Windows 上复制到 %USERPROFILE%\.local\bin\claude.exe。首先尝试打开一个新终端。如果在 Windows 上仍然不行，以下是文档中用于检查并将该目录添加到用户 PATH 的 PowerShell 命令：

# 1. Controlla se la cartella di installazione è già nel PATH
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Nessun risultato? Aggiungila al PATH utente, poi chiudi e riapri il terminale
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Nel nuovo terminale
claude --version

PowerShell 中的 npm.ps1 cannot be loaded

这只影响使用 npm 安装的用户：PowerShell 的执行策略会阻止 npm 创建的 .ps1 脚本，完整消息中包含 running scripts is disabled on this system。文档给出了三种解决方式：使用下面的命令允许当前用户执行本地脚本；改用 npm.cmd 和 claude.cmd；或者放弃 npm，使用原生安装程序。

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

无需订阅：Claude 账户或 API 密钥

安装完成不代表已经可以使用：首次启动 Claude Code 时需要登录，而且 Claude.ai 免费计划无法满足要求（文档，查阅于 2026年10月3日）。以下是两种方案的对比：

还可以使用 Anthropic Console 密钥，费用也按用量计算。不过，预付额度会在一年后过期且不予退款（Anthropic 帮助，查阅于 2026年10月3日）；付款可使用银行卡，而 ACH 银行转账仅向按月结算的 API 账户开放（Anthropic 帮助）。Kunavo 余额永不过期。

配置 API 密钥：六个变量

Claude Code 使用不同于 Anthropic 的端点是受支持的：官方文档提供了一个页面，说明如何将其连接到 LLM 网关，该页面也有意大利语版本。无需插件，也无需修改版本。只需设置以下变量：

在 macOS 和 Linux 上，将其添加到 ~/.zshrc 或 ~/.bashrc 的末尾：

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # solo il dominio, senza /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 solo in questa finestra di PowerShell: chiusa la finestra, sparisce
$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"
  }
}

AUTH_TOKEN 还是 API_KEY？

Kunavo 会从这两个请求头 Authorization: Bearer 和 x-api-key 中读取密钥，因此理论上两个变量都可以使用。区别在于 Claude Code 的行为。使用 ANTHROPIC_API_KEY 并将其作为 x-api-key 发送时，交互会话会询问一次是否批准该密钥；如果回答否，它会静默忽略该密钥，直到你通过 /config → Use custom API key 重新启用。ANTHROPIC_AUTH_TOKEN 不会提示，而且当你不确定该选哪个时，网关文档（查阅于 2026年10月3日）也建议使用这个变量。

为什么要固定模型

不设置变量时，Claude Code 会按别名选择模型，而这些别名会跟随 Anthropic 的模型发布变化。根据模型配置文档（查阅于 2026年10月3日），目前使用 API 的用户会将 opus 解析为 Opus 5.5，将 sonnet 解析为 Sonnet 5.5。Kunavo 截至 2026年10月3日 尚未提供 Sonnet 5.5：若未设置 ANTHROPIC_DEFAULT_SONNET_MODEL，/model sonnet、opusplan 的执行阶段以及使用 model: sonnet 的子代理都会请求 Kunavo 未提供的模型，并收到 404 错误。将 claude-sonnet-5 设为该变量的值后，该别名会指向 Claude Sonnet 5，也就是与 ANTHROPIC_MODEL 相同的模型。而后者决定会话使用的模型：如果未设置，Claude Code 将使用其默认模型，目前为 Opus 5.5。Kunavo 提供 Opus 5.5；将 opus 固定为 claude-opus-5-5 则是为了避免别名改为后续 Opus 模型时，模型和价格在某一天突然发生变化。Claude Opus 5.5 需要 Claude Code 2.1.280 或更高版本；如果版本较旧，请先运行 claude update。

配置中三个模型的 Kunavo 费率，按每百万 token 计（输入 / 输出）：Claude Sonnet 5 $1.40 / $7.00 （Anthropic 目录价：$2.00 / $10.00）；Claude Opus 5.5 $2.80 / $14.00；Claude Haiku 4.5 $0.70 / $3.50，后者也会在后台运行。

不应放在哪里，以及哪个设置优先

项目内的 .claude/settings.json 会被提交：写在其中的密钥会进入代码仓库，并交给所有克隆该仓库的人（网关文档）。如果某个变量同时出现在 shell 和设置文件的 env 块中，则以设置文件中的值为准：若更改 ~/.zshrc 后看起来没有生效，原因几乎总在这里。设置文件中的 model 字段则优先级低于 ANTHROPIC_MODEL。在 Claude Code 的 VS Code 扩展中，同样的变量应添加到 VS Code 用户设置中的 claudeCode.environmentVariables。Claude 桌面应用不适用这些设置：它既不读取 ANTHROPIC_BASE_URL，也不读取 settings.json（网关文档，查阅于 2026年10月3日）。

首次启动并使用 /status 检查

如果密钥已正确设置，运行 claude 时会跳过登录界面：只需完成初始配置，并确认是否信任该文件夹。如果出现登录界面，则说明 Claude Code 没有找到密钥。常见原因是密钥只写在项目的 .claude/settings.json 或 .claude/settings.local.json 中：在交互模式下，只有完成初始配置并确认信任后，env 块才会生效（网关文档，查阅于 2026年10月3日），因此首次启动时它尚未生效。请将密钥移至 shell 或用户设置文件中。以前的 Pro 或 Max 登录不会造成影响，因为变量的优先级高于已保存的登录信息；如需清除登录信息，可以运行 /logout。

在会话中输入 /status。需要关注的有两行：

• Anthropic base URL，仅在设置了网关时显示：应显示 https://api.kunavo.com。如果没有显示，说明 ANTHROPIC_BASE_URL 没有传递到会话中。
• Auth token，名称为 ANTHROPIC_AUTH_TOKEN：表示正在使用该密钥。如果看到的是使用 claude.ai 账户的 Login method，说明变量被忽略了。

想在打开 Claude Code 之前就进行检查？文档建议发送一个最小请求，输出 1 个 token，仅从余额中扣除可忽略的金额。该命令读取当前 shell 的变量：如果密钥只存在于 settings.json 中，请先在此终端中导出它。如果返回的 JSON 以 {"id":"msg_ 开头，就说明配置正确；401 表示密钥被拒绝。

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

在 PowerShell 中，相同的测试如下；正确的响应包含一个以 msg_ 开头的 id：

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

使用 API 密钥会失去什么

• Remote Control 和语音听写。 它们需要 claude.ai 身份，不能与 ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY 一起使用；从 2.1.196 版本起，当 ANTHROPIC_BASE_URL 指向非 Anthropic 主机时，Remote Control 也会关闭。
• /fast 模式。 仅使用 bearer token 时，Claude Code 会将其视为已禁用，甚至不会尝试请求。
• MCP 工具搜索在启动时默认关闭。使用自定义 ANTHROPIC_BASE_URL 时，该功能默认关闭（MCP 文档，英文，查阅于 2026年10月3日）。如果网关转发 tool_reference 块，可以通过 ENABLE_TOOL_SEARCH=true 重新启用；我们尚未在 Kunavo 上测试过。
• /context 的精度。Kunavo 不提供 /v1/messages/count_tokens，而根据网关规范（查阅于 2026年10月3日），这是一个可选端点；没有该端点时，Claude Code 会根据字符数估算 token 数量。

深入了解（英文）：Claude Code 集成文档、ANTHROPIC_BASE_URL 的边界情况页面以及 安装 Claude Code 指南。

使用 Satispay 付款，无需信用卡

先澄清一个最常见的问题：Satispay 不能用于支付 Claude 订阅。Anthropic 仅接受信用卡或借记卡支付网页版 Pro 和 Max 计划（Anthropic 帮助），不接受 PayPal（Anthropic 帮助），两项信息均查阅于 2026年10月3日。在 Kunavo 上，Satispay 用于为 API 余额充值，Claude Code 会使用上文配置的密钥消耗该余额。包括为“可用余额”充值的费用在内的所有详情，请参阅使用 Satispay 支付 Claude 费用指南。Claude Code 的操作顺序如下：

1. 使用电子邮件或 Google 账户注册 Kunavo：无需银行卡。
2. 打开 账单 并选择充值金额：最低 $10，无订阅费。 达到某些金额门槛后可获得奖励：$100 变为 $110、$1,000 变为 $1,200和$5,000 变为 $6,250 余额。
3. 在 Stripe 结账页面中，页面会显示欧元金额，请选择 Satispay。随后会跳转到 Satispay 页面（Stripe 文档）：输入手机号码，或使用应用扫描二维码，然后点击 发送 确认（Satispay 帮助，查阅于 2026年10月3日）。建议在开始前确保可用余额充足。
4. Stripe 确认付款后，余额会立即显示在 Billing 中。如果没有立即看到，请刷新页面，而不要再次付款：第二笔付款会累加到余额中，不会替代第一笔。
5. 在API 密钥中生成密钥 sk-kn-…，并立即将其复制到 ANTHROPIC_AUTH_TOKEN：它只会显示一次。

Kunavo 以美元定价，Stripe 会将金额换算成欧元，并收取由付款方承担的 2–4% 汇率转换费（Stripe，Adaptive Pricing，查阅于 2026年10月3日）：最低 $10 充值金额对应的费用约为 $0.20 至 $0.40。使用美元付款则无需支付这笔费用，但 Satispay 也无法使用，因为它仅适用于欧元结账；如果结账页面显示美元，通常与 VPN 有关。确认前，结账页面上显示的欧元金额就是确切金额。

使用 Satispay 充值需要手动操作：Kunavo 的自动充值仅支持向已保存的银行卡或 Link 扣款。持有 Satispay 卡的用户可以保存该卡并像使用普通银行卡一样付款；该卡是适用于 Plus、Metal 和 Velvet 计划的 Mastercard 借记卡（Satispay 帮助，查阅于 2026年10月3日）。余额不会过期，失败的请求不会扣款。Kunavo 不开具发票，包括增值税发票和通过 SDI 开具的电子发票；充值记录可在 Billing 中查看。

坦诚说明：Satispay 自 2026 年 10 月 3 日起已加入 Kunavo 的结算页面，Stripe 也在欧元付款中提供该方式，但目前还没有任何充值通过它完成。如果找不到该选项，银行卡、Apple Pay、Google Pay 和 Link 也能完成相同操作。

一次工作会话的费用

使用 API 密钥时，费用取决于 token，而 Claude Code 会发送很多 token：每一步都会重新发送完整上下文。不过，不变的部分可以从缓存中读取，费率会低得多。下面是一个经过设计的示例，假设条件均已明确：这不是实际测量值，也不是费用上限。

• 每个请求 40,000 个输入 token，其中 36,000（90%）从缓存读取，4,000 写入缓存；
• 每个请求 1,000 个输出 token；
• 每个会话 50 个请求，不包括后台对 Claude Haiku 4.5 的调用；
• 从缓存读取时按输入费率的 10% 计费，写入缓存时按输入费率的 1.25× 计费：这是 Kunavo 针对 Claude Sonnet 5 的比例，表中每一行都使用对应模型的比例。

上下文较长、缓存读取较少以及回答冗长都会增加费用；任务之间使用一次 /clear 会降低费用。是否订阅或使用 API 更划算，请查看Claude Code 的费用；所有 Claude 模型的费率请参阅Claude API 价格和价格页面。如需使用自己的数字重新计算，请使用Claude token 费用计算器（英文）。

错误：消息、原因、解决方法

此配置不会执行的操作

• 不会启用 Claude Pro 或 Max 订阅：Kunavo 余额用于支付 API 和使用密钥的 Claude Code，而不是 claude.ai 或 Claude 应用。
• 不会生成发票：既不会生成含增值税的发票，也不会通过 SDI 生成电子发票。
• 不会通过 Satispay 自动充值：自动充值需要已保存的银行卡或 Link。
• 在 Kunavo 提供 Sonnet 5.5 之前，如果没有模型变量就无法运行（截至 2026年10月3日）：sonnet 别名会返回 404，连同它一起受影响的还有 /model sonnet、opusplan 的执行阶段以及使用 model: sonnet 的子代理。
• 没有意大利语版的 Kunavo 文档：集成指南和余额与付款页面为英文，而 Anthropic 的 Claude Code 页面已有翻译。

如需了解在意大利使用 Claude 进行开发的整体情况，请参阅意大利 Claude API 指南。开始方式：创建账户，使用 Satispay 充值 $10，设置六个变量，然后使用 /status 进行检查。

常见问题