安装 Claude Code：Windows 和 macOS 安装命令、无需 Pro/Max 方案的 API 密钥配置，以及使用银行卡或 Link 支付

想在不购买 Pro/Max 套餐的情况下使用 Claude Code，需要完成三步：使用官方原生安装命令安装（下方为每种终端各提供一行命令），设置 ANTHROPIC_BASE_URL=https://api.kunavo.com（不带 /v1）、ANTHROPIC_AUTH_TOKEN 以及四个用于固定模型的变量，然后输入 /status，确认 Claude Code 正在使用密钥运行。Token 费用从预付余额中扣除，最低充值金额为 10 USD，可使用 Visa/Mastercard 卡或 Link 充值；不支持 MoMo、ZaloPay 和 VNPay。如果通过 npm 安装，电脑需要安装 Node.js 22 或更高版本。

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

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

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

本文中的安装命令和变量名称取自 Claude Code 官方文档，包括安装页面和环境变量列表，于2026年10月3日重新查阅。Anthropic 尚未提供这些页面的越南语版本（同日访问/docs/vi/setup时返回 404），因此文中的错误提示保留英语原文，方便您搜索。Kunavo 的价格和付款方式核实于2026年10月10日。

根据当前打开的终端选择安装命令

所有安装方式都会得到同一个 claude 程序；区别在于由谁负责更新。官方文档将原生方式放在“Native Install (Recommended)”选项卡中，这也是唯一一种无需你做任何操作即可自动升级到新版本的方式。

# Homebrew (macOS, Linux) – mặc định không tự cập nhật
brew install --cask claude-code

# WinGet (Windows) – mặc định không tự cập nhật
winget install Anthropic.ClaudeCode

计算机需要满足以下条件（根据截至 2026年10月3日 阅读的安装页面）：

• 操作系统：macOS 13.0 或更高版本；Windows 10 版本 1809 或更高版本，或 Windows Server 2019 或更高版本；Ubuntu 20.04+、Debian 10+ 或 Alpine Linux 3.19+。
• 至少 4 GB RAM，CPU 为 x64 或 ARM64。Windows 32 位不受支持。
• Shell 为 Bash、Zsh、PowerShell 或 CMD，并且需要 Internet 连接。
• 仅通过 npm 安装时需要 Node.js，且版本必须为 22 或更高。

安装完成后，不要立即在旧窗口中输入 claude：该窗口尚未读取新的 PATH。打开另一个终端，然后运行：

claude --version   # in ra số phiên bản, kèm chữ (Claude Code)
claude doctor      # chẩn đoán cài đặt và file cấu hình, không mở phiên làm việc

如果 claude --version 输出版本号，则安装已完成；之后的任何错误都属于配置问题。当你不确定错误出在哪里时，claude doctor 很有用，因为它会检查安装和 settings 文件，而不会打开任何工作会话。

Windows：五个常见陷阱

1. 粘贴了错误的命令行。 PowerShell 遇到 CMD 命令会报告 The token '&&' is not a valid statement separator；CMD 遇到 PowerShell 命令会报告 'irm' is not recognized as an internal or external command。查看提示符：如果有 PS，就使用 irm；没有则使用 install.cmd。
2. 误打开了“Windows PowerShell (x86)”。 开始菜单中的这一项是 32 位进程，因此即使在 64 位计算机上也会显示 Claude Code does not support 32-bit Windows。请选择不带 (x86) 字样的选项。
3. 以 Administrator 权限运行是多余的。文档没有要求这样做，而 native 版本会安装到用户目录：%USERPROFILE%\.local\bin\claude.exe。
4. 输入 claude 后报告“not recognized”。上述目录尚未加入 PATH。先尝试打开新终端；如果仍然报错，则使用下面的 PowerShell 片段检查并添加路径。在 macOS/Linux 上，对应的错误是 command not found: claude，程序位于 ~/.local/bin/claude。
5. npm 报告 npm.ps1 cannot be loaded because running scripts is disabled on this system。PowerShell 的 Execution policy 阻止了 npm 创建的 .ps1 脚本。文档提供了三种解决方式：使用下面的 Set-ExecutionPolicy 命令，让当前用户运行本地脚本；调用 npm.cmd 和 claude.cmd，而不是 .ps1；或者放弃 npm，改用 native 命令。

# 1. Kiểm tra thư mục cài đặt đã có trong PATH chưa
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Không có kết quả nào? Thêm vào PATH của người dùng, rồi đóng và mở lại terminal
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Trong terminal mới
claude --version

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

原生版还是 WSL？如果项目位于 Windows 上，直接运行原生版即可。此时，Git for Windows是可选项：安装后，Claude Code 会通过 Git Bash 运行命令；未安装则使用 PowerShell。如果已安装 Git，但 Claude Code 找不到 Git Bash，请在~/.claude/settings.json的env区块中设置CLAUDE_CODE_GIT_BASH_PATH，并将其指向bash.exe（文档中的示例为C:\Program Files\Git\bin\bash.exe）。如果需要 Linux 工具，或希望命令在沙盒中运行，请选择 WSL 2，因为只有 WSL 2 支持沙盒；Windows 原生版和 WSL 1 均不支持。只有在电脑无法启用 WSL 2 时，才考虑使用 WSL 1。选择 WSL 后，请通过命令install.sh安装，并全程在 WSL 终端中运行claude。

通过 npm 安装：条件和三个注意事项

如果您已使用 Node 管理命令行工具，或者公司网络只允许通过 npm registry 下载软件包，使用 npm 是合理的选择。要求是安装Node.js 22 或更高版本；许多旧文章中提到的 Node 18 已不再适用。需要注意的是，较旧版本的 Node 不会导致安装失败：npm 只会打印EBADENGINE警告，因为实际运行的是由 npm 软件包下载的原生程序，与 Node 无关。如果电脑尚未安装 Node，请从nodejs.org获取 22 或更高版本。

node -v                                    # cần v22 trở lên
npm install -g @anthropic-ai/claude-code   # không dùng sudo

# nâng cấp bằng @latest, không dùng npm update -g
npm install -g @anthropic-ai/claude-code@latest

• 不要使用 sudo npm install -g：文档警告这种方式会导致权限错误并带来安全风险。
• 使用 npm install -g @anthropic-ai/claude-code@latest 升级到新版本；npm update -g 不是文档推荐的方法。
• Native 程序来自一个可选依赖（与你的平台对应的 @anthropic-ai/claude-code-* 软件包）。--omit=optional 标志、.npmrc 中的 optional=false 行或 --ignore-scripts 会导致缺少该依赖；在 macOS/Linux 上，你会看到 claude native binary not installed。

需要 VPN 吗？下载安装脚本时出错

不需要。越南位于 Anthropic 针对 Claude.ai 和 API 提供服务的受支持国家列表中（核实日期：2026年10月3日）。真正容易引发问题的是 VPN：根据安装故障排查页面（查阅日期：2026年10月3日），当安装地址返回App unavailable in region时，Claude Code 无法在您的连接显示为所在的地区使用。如果您人在越南却看到此提示，请关闭连接到其他国家/地区的 VPN 或代理，然后重新运行。

剩下的两个错误源于同一个问题：syntax error near unexpected token '<' 或 curl: (22) The requested URL returned error: 403 表示你收到的是 HTML 页面或错误代码，而不是脚本。带有代理的企业网络或阻止文件下载的防火墙是首要怀疑对象。不要急着改用 Homebrew、WinGet 或 npm：文档建议先检查网络连接，因为替代安装方式也会从同一服务器下载。尝试使用其他网络，或请 IT 部门解除拦截。

配置 API key：无需 Pro/Max 方案即可运行 Claude Code

Claude Code 通过两种方式之一进行身份验证。下表简要对比；本文其余部分将按照右侧一列展开。

将 Claude Code 指向 Anthropic 之外的其他服务并不是技巧：官方文档说明，ANTHROPIC_BASE_URL 是在通过代理或网关时用于覆盖 API endpoint 的变量。Kunavo 使用标准 Anthropic Messages API 协议，因此你可以直接使用原版 Claude Code，无需插件或补丁。需要准确设置以下六个变量：

在哪里设置变量

长期使用时，最简洁的方法是在用户 settings 文件中的 env 块中设置，即 ~/.claude/settings.json（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"
  }
}

如果更喜欢将其放在 shell 中，请添加到 ~/.zshrc 或 ~/.bashrc。在 Windows 上，下面第二段（$env: 行）适合快速测试，但关闭 PowerShell 窗口后变量会立即丢失。

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # chỉ tên miền, không thêm /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

# Chỉ có hiệu lực trong cửa sổ PowerShell này, đóng cửa sổ là mất
$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中。网关连接文档提醒，该文件会被提交到代码库，任何克隆代码库的人都能看到。
• Settings 文件优先于 shell。如果同一个变量存在于两处，则使用 settings 文件中 env 块的值。在 shell 中修改却看不到变化时，先检查 settings 文件。
• 首次运行需要用户级别的 key。在交互模式下，项目的 env、.claude/settings.json 或 .claude/settings.local.json 中的块只有在首次向导和“是否信任此目录”的询问之后才会生效。如果 key 只放在那里，首次启动时仍会显示登录界面。

ANTHROPIC_AUTH_TOKEN 还是 ANTHROPIC_API_KEY，以及“403 错误”

Kunavo 会从Authorization: Bearer和x-api-key读取密钥，因此两种变量都能用于连接。区别在于 Claude Code 这一侧。根据环境变量文档（查阅日期：2026年10月3日），ANTHROPIC_AUTH_TOKEN会被放入带有Bearer前缀的Authorization标头中，并立即生效。ANTHROPIC_API_KEY会被放入X-Api-Key标头中；在交互模式下，Claude Code 会询问您是否要用此密钥替代订阅。回答“不”后，密钥会被忽略，且不会再次询问；要重新启用，请进入/config，找到Use custom API key。本文选择ANTHROPIC_AUTH_TOKEN，只是为了跳过这一确认步骤。

一些越南语指南称，ANTHROPIC_API_KEY会导致 Claude Code 忽略ANTHROPIC_BASE_URL，直接调用api.anthropic.com并收到 403 错误。环境变量文档和网关连接文档（查阅日期：2026年10月3日）都没有这样的说明：这两个变量只是将密钥传递给ANTHROPIC_BASE_URL中同一网关的两种方式。如果更换变量后确实遇到 403 错误，请重新检查 base URL 和密钥，而不要来回更换变量名称。

为什么要固定模型，以及每个模型的价格

Claude Code 的别名会变化。根据模型配置文档（查阅日期：2026年10月3日），对于 API 用户，默认模型和别名opus当前指向 Opus 5.5，别名sonnet指向 Sonnet 5.5；文档还指出，别名会“随着时间推移更新”，并建议在需要固定版本时使用完整名称或ANTHROPIC_DEFAULT_*_MODEL变量。截至2026年10月3日，Kunavo 提供 Opus 5.5，但不提供 Sonnet 5.5。如果跳过固定步骤，将导致以下情况：默认会话使用 Opus 5.5，成本高于Claude Sonnet 5；/model sonnet、opusplan的执行阶段以及设置为model: sonnet的子代理会返回 404；下一次别名opus切换到新的 Opus 版本时，该版本也未必已在 Kunavo 上提供。因此，上述配置会使用ANTHROPIC_DEFAULT_SONNET_MODEL将别名sonnet固定到claude-sonnet-5，并将别名opus固定到 Opus 5.5（claude-opus-5-5）。使用 Opus 5.5 需要 Claude Code v2.1.280 或更高版本；较早版本请运行claude update。

Kunavo 价格按每百万 token 计算（输入 / 输出）：Claude Sonnet 5 1.40 USD / 7.00 USD （Anthropic 价格：2.00 美元 / 10.00 美元）；Claude Opus 5.5 2.80 USD / 14.00 USD；Claude Haiku 4.5 0.70 USD / 3.50 USD。

使用 /status 检查

读取到 ANTHROPIC_AUTH_TOKEN 后，claude 命令会直接进入工作会话，不会显示登录界面（根据网关连接文档，读取日期为 2026年10月3日）；首次运行仍有一些设置步骤，例如确认是否信任目录。看到登录界面就表示 key 尚未被读取。在会话中输入 /status 并查找：

• Anthropic base URL：https://api.kunavo.com。只有存在网关地址时才会显示此行；缺少它表示 ANTHROPIC_BASE_URL 未能进入会话。
• Auth token：ANTHROPIC_AUTH_TOKEN。如果这里显示 Login method 并附带一个 claude.ai 账户，则会话仍在使用已保存的登录信息。

在打开 Claude Code 之前，如果想确认 key 和地址正确，可以发送一个请求，只请求 1 个输出 token（会从余额中扣除极少金额）。该命令从当前 shell 读取变量，因此如果 key 只存在于 settings 文件中，请先在此终端中执行 export。结果以 {"id":"msg_ 开头表示正常；401 表示 key 被拒绝。

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 版本；成功时，结果中的 id 字段以 msg_ 开头：

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 key 会失去什么

• Remote Control 和语音输入需要 claude.ai 身份，因此在 ANTHROPIC_AUTH_TOKEN 生效时无法运行。当 ANTHROPIC_BASE_URL 指向不同于 api.anthropic.com 的其他服务器时，Remote Control 也会被禁用。
• /fast 报告 Fast mode has been disabled by your organization：根据网关连接文档，fast mode 的检查步骤需要登录 claude.ai 或使用 Anthropic API key，因此对于 bearer token，Claude Code 会将其视为已禁用，不会询问服务器。
• 当 base URL 不是 Anthropic 的地址时，MCP tool search 默认关闭。
• /context中的数值为估算值：Kunavo 没有/v1/messages/count_tokens端点；根据网关协议文档（查阅日期：2026年10月3日），缺少此端点时，Claude Code 会根据字符数估算 token 数量。

集成详情请参阅Claude Code 集成文档（英文）；对应的英文文章是 Install Claude Code。

从越南充值：银行卡或 Link，不支持本地电子钱包

先明确说明：Kunavo 不接受 MoMo、ZaloPay、VNPay 或银行转账。仅支持 Napas 网络的越南本地 ATM 卡也无法使用，因为它不是 Visa 或 Mastercard。Kunavo 的 Stripe 付款页面为越南买家提供以下选项：

• Visa 或 Mastercard，国际信用卡或借记卡均可。
• Link是 Stripe 的电子钱包，可保存付款方式，以便下次更快付款（Link 文档，查阅日期：2026年10月3日）。
• Apple Pay 或 Google Pay仅会在已设置相应钱包的设备和浏览器上显示，因为它们使用钱包中的银行卡付款。Apple Pay 于 2023 年 08 月 08 日在越南推出，可用于在线购物（Apple 越南新闻室，查阅日期：2026年10月3日）。

Anthropic 方面也是如此：在网站购买 Claude 计划只接受信用卡或借记卡（Claude 账单常见问题，查阅日期：2026年10月3日），因此无法直接使用越南电子钱包付款；通过 iOS 或 Android 应用购买的计划则使用 App Store 或 Google Play 的付款方式。不同之处在于，充入 Kunavo 的金额会成为 API 余额；按上述方式配置密钥后，Claude Code 会根据 token 用量逐步扣款。

使用 VND 还是 USD 付款

Kunavo 以美元标价。由于越南属于Stripe Adaptive Pricing的服务市场（查阅日期：2026年10月3日），付款页面可能显示换算成越南盾后的金额；确切金额始终会在您点击确认前显示。Stripe 提供的汇率已包含由购买者承担的 2–4% 货币换算费。选择以美元付款则不收取这笔费用，但发卡银行可能会采用自己的汇率并收取费用。

以越南盾付款也未必更便宜：有些银行会对以越南盾支付给境外注册商家的交易收取费用。例如，Techcombank 自 2023 年 08 月 13 日起，对 Visa 借记卡收取交易金额 1.1% 的“境外本币交易费”（含增值税）（Techcombank 常见问题，查阅日期：2026年10月3日）。这只是某家银行的例子，Kunavo 尚未核实该银行是否将本平台的交易归入此类；请先查看您银行卡的费率表，再选择以越南盾或美元付款。

银行卡被拒通常是因为尚未在银行应用中启用在线支付或国际支付。启用后重试，或改用 Link；也可以使用该钱包支持的银行卡，通过 Apple Pay/Google Pay 付款。

从注册到获得 key

1. 使用电子邮件或 Google 账户注册 Kunavo；此步骤不要求银行卡。
2. 打开 Billing，选择充值金额（最低为 10 USD）。较高档位会额外增加：充值 100 美元后，余额增加 110 美元；充值 1.000 美元后，余额增加 1.200 美元；充值 5.000 美元后，余额增加 6.250 美元。
3. 在 Stripe 页面选择银行卡、Link 或设备上可用的钱包，检查金额并确认。
4. 进入 API Keys，创建 key sk-kn-…。Key 只显示一次，因此请立即将其复制到 ANTHROPIC_AUTH_TOKEN。

如果希望余额较低时自动充值，必须使用已保存的银行卡或 Link。余额不过期，失败的 request 不收费。Kunavo 不提供 VAT 发票，包括越南法规规定的电子发票；充值历史可在 Billing 中查看。该余额仅用于 Kunavo API，不能用于支付 Claude Pro、Claude Max 或 ChatGPT Plus。

一次代码会话大约需要多少钱？

每次请求中，Claude Code 都会重新发送整个对话上下文，因此费用很大程度上取决于缓存：重复的上下文部分按明显更低的缓存读取价格计费。下表是在明确假设下进行的理论计算，不是实际测量值，也不是上限：

• 每个 request 包含 40,000 个输入 token：其中 36,000 个 token（90%）从缓存读取，4,000 个 token 写入缓存；
• 每个 request 包含 1,000 个输出 token；
• 一次会话包含 50 个 request，不计入 Claude Haiku 4.5 执行的后台任务；
• 对于 Kunavo 上的 Claude Sonnet 5，缓存读取按输入价格的 10% 计费，缓存写入按输入价格的 1.25 倍计费；表中的每个模型使用自己的比例。

最后一列显示缓存的重要性。上下文越长、回答越长，或在不同任务之间忘记 /clear，都会推高数值。在Claude Code 价格一文中可以比较订阅方案与 API 并估算月度费用；各模型价格请查看Claude API 价格表或价格页面；如需输入自己的数据，请使用Claude token 成本计算器（英文）。

按错误消息排查

充值前

• 仅支持 Visa/Mastercard 银行卡、Link 以及基于银行卡运行的钱包；不支持 MoMo、ZaloPay、VNPay 或银行转账。
• 自动充值仅适用于已保存的银行卡或 Link。Kunavo 不提供 VAT 发票。
• 这是按 token 计费的 API，而不是 Claude Pro/Max 方案：不提供 Remote Control 和语音输入，/fast 报告为已关闭，MCP tool search 默认关闭。
• 截至 2026年10月3日，Kunavo 不提供 Sonnet 5.5，因此尚未固定的 alias sonnet 会返回 404。
• Claude Code 文档和Kunavo 集成文档目前只有英文版本。

常见问题