Claude Code 安装：Windows、macOS 和 Linux 分步指南，无需订阅的 API 密钥及银行卡支付

简要回答：Claude Code 通过一条适用于你终端的命令行安装。在 macOS、Linux 和 WSL 中运行 install.sh，在 Windows PowerShell 中运行 irm … | iex，在命令提示符（CMD）中运行 install.cmd；三条命令如下所示。这种方式不需要 Node.js；如果想使用 npm 安装，则需要 Node.js 22 或更高版本。安装后有两种选择：使用 Claude 账户登录（Pro、Max、Team、Enterprise 或 Console；免费方案不包含 Claude Code），或者不订阅而使用 API 密钥。在密钥方式下，设置 ANTHROPIC_BASE_URL=https://api.kunavo.com（末尾不要添加 /v1）、ANTHROPIC_AUTH_TOKEN 以及用于固定模型的四个变量；会话中的 /status 可显示密钥是否已生效。仅对使用的 token 收费。可以使用 Visa 或 Mastercard 银行卡、Apple Pay、Google Pay 或 Link 为余额充值，最低金额为 10 USD；不提供分期付款和 Papara 选项。

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

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

:: Windows – Komut İstemi (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

这些命令行和下方的变量名称来自 Claude Code 的安装和网关连接文档，查阅日期为 2026年10月3日。Anthropic 未提供土耳其语版本的这些文档，因此我们保留报错信息的英文原文。Kunavo 的价格和支付方式最近一次核实于 2026年10月10日。你无需使用 VPN 或境外代理：Anthropic 支持的国家和地区页面将土耳其列为 Claude.ai 和 API 均支持的国家（核实日期：2026年10月3日）。

哪条命令适用于哪个终端？

大多数安装问题不在命令本身，而在于终端选错了。下表将你的环境与正确的命令行对应起来。如果使用 Windows，我们将在下一节说明如何识别终端。

系统要求

官方安装文档要求的条件（截至 2026年10月3日）：

• 操作系统：macOS 13.0 或更高版本；Windows 10 版本 1809 及更高版本，或 Windows Server 2019 及更高版本；Linux 需要 Ubuntu 20.04、Debian 10 或 Alpine Linux 3.19 及更高版本。
• 硬件：至少 4 GB RAM，以及 x64 或 ARM64 处理器。不支持 32 位 Windows。
• Shell：Bash、Zsh、PowerShell 或 CMD。
• Node.js：原生安装不需要；仅在 npm 方式中需要 22 或更高版本。
• 账户：如果要登录，需要 Pro、Max、Team、Enterprise 或 Console。使用 API 密钥时不需要订阅，也不需要登录。

网上流传的一些土耳其语说明仍在复制这份列表的旧版本：其中仍有人写 npm 需要 Node.js 18，Linux 需要 Ubuntu 18.04 或 CentOS 7。当前文档给出的最低版本是 Node.js 22 和 Ubuntu 20.04。“没有美国出口的固定代理时每一步都会报错”的说法也不适用于土耳其；相反，开放的 VPN 连接可能导致区域错误（请参阅 macOS 和 Linux 部分的下载错误）。

Claude Code Windows 安装

在 Windows 上不需要管理员权限、WSL 或 Git。官方文档不要求以管理员身份打开终端；可以跳过一些土耳其语视频中的“以管理员身份运行 PowerShell”步骤。你唯一需要知道的是当前使用的终端：

• 如果提示符以 PS C:\Users\KullaniciAdi> 这样的 PS 开头，则你位于 PowerShell 中：使用 irm … | iex 命令行。
• 如果开头没有 PS，只显示 C:\Users\KullaniciAdi>，则你位于命令提示符中：使用 install.cmd 命令行。
• 不要打开开始菜单中的“Windows PowerShell (x86)”条目。由于它是 32 位进程，即使在 64 位计算机上也会显示 Claude Code does not support 32-bit Windows 错误；请选择不带后缀的“Windows PowerShell”。

将命令行粘贴到错误的窗口是 Windows 错误的主要原因之一，而错误消息并不会明确说明这一点。粘贴到 PowerShell 中的 CMD 命令行会返回 The token '&&' is not a valid statement separator。粘贴到 CMD 中的 PowerShell 命令行在土耳其语 Windows 中会显示“'irm' 不被识别为内部或外部命令、可运行程序或批处理文件。”（英文系统中为 'irm' is not recognized as an internal or external command）。如果在 PowerShell 中尝试 macOS 的 curl … | bash 命令行，会看到 A parameter cannot be found that matches parameter name 'fsSL' 或 'bash' is not recognized as the name of a cmdlet；在土耳其语系统中，这些文本可能会以土耳其语显示。三种情况下的解决方法相同：使用当前终端对应的命令行。

需要 Git for Windows 和 WSL 吗？

两者都不是必需的。如果已安装 Git for Windows，Claude Code 会在随附的 Git Bash 中运行 shell 命令；如果未安装，则会改用 PowerShell。文档建议安装 Git，但并未将其列为必需项。如果 Git 已安装，但找不到 Git Bash，请在 ~/.claude/settings.json 文件的 env 块中，将变量 CLAUDE_CODE_GIT_BASH_PATH 设置为 bash.exe 文件的完整路径（文档中的示例：C:\Program Files\Git\bin\bash.exe）。

选择 WSL 有两个原因：需要 Linux 工具，或者希望在沙盒（sandbox）中运行命令。原生 Windows 安装没有沙盒：

如果要一直使用 WSL，请在 WSL 终端中完成安装和使用：macOS/Linux 命令行可在那里运行，claude 也应在那里启动。

找不到“claude”命令

安装完成后，如果看到 'claude' is not recognized（macOS 和 Linux 中为 command not found: claude），很可能是在安装前已经打开的窗口中运行：安装程序更新了 PATH 变量，但旧终端看不到更新。请先关闭终端再重新打开。程序在 Windows 中位于 %USERPROFILE%\.local\bin\claude.exe，在 macOS 和 Linux 中位于 ~/.local/bin/claude。如果在 Windows 中打开新窗口仍无效，请按照文档中的命令将该目录添加到用户 PATH 变量中：

# 1. Kurulum klasörü PATH içinde mi?
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Sonuç yoksa kullanıcı PATH'ine ekleyin, terminali kapatıp yeniden açın
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Yeni terminalde
claude --version

无法加载 npm.ps1

此消息只会在 npm 方式中出现：npm 会为 PowerShell 写入一个 .ps1 启动器，而系统的脚本执行策略（execution policy）会阻止它。文档提供了三种解决方法：使用 npm.cmd 和 claude.cmd 名称运行命令，在 PowerShell 中改用原生安装程序，或者仅允许当前用户运行本地脚本：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

在 macOS 和 Linux 上安装

上面的 install.sh 命令行位于官方文档的“Native Install (Recommended)”选项卡中，在 WSL 中也可原样运行。通过这种方式安装的 Claude Code 会在后台自动下载新版本。如果更喜欢使用包管理器，Homebrew 和 WinGet 也是官方选项；但根据文档，这些安装方式默认不会自动更新，你需要通过包管理器自行获取新版本：

# Homebrew – stable kanalı; varsayılan olarak kendini güncellemez
brew install --cask claude-code

# WinGet (Windows) – varsayılan olarak kendini güncellemez
winget install Anthropic.ClaudeCode

如果收到的不是脚本而是 HTML 或 403

syntax error near unexpected token '<' 消息表示 bash 收到的是 HTML 页面而不是脚本；curl: (22) The requested URL returned error: 403 则表示服务器拒绝了下载。安装问题排查文档（核实日期：2026年10月3日）指出，这两种情况都与安装程序地址未返回脚本有关。如果页面显示 App unavailable in region，根据文档，请求看起来像是来自 Claude Code 尚未提供服务的国家或地区。既然土耳其在支持列表中，如果你在土耳其收到此消息，你的流量很可能经由 VPN 或代理从其他国家或地区发出；请关闭 VPN 或代理后重试。不带说明文本的 403 通常来自企业代理或防火墙：请尝试使用其他网络，或请 IT 团队允许访问此地址。

使用 npm 安装：需要 Node.js 22

npm 安装方式仍受支持，官方文档也仍有介绍；不过该软件包现在要求使用 Node.js 22 或更高版本。如果 node -v 显示的是较旧版本，npm 安装不会停止，只会显示 EBADENGINE 警告。最稳妥的做法是通过 nodejs.org 将 Node.js 升级到 22 或更高版本。

node -v                                    # v22 veya üstü olmalı
npm install -g @anthropic-ai/claude-code   # sudo kullanmadan

# güncelleme: npm update -g değil, @latest
npm install -g @anthropic-ai/claude-code@latest

这条路径中有三个习惯会导致问题：

• 使用 sudo 安装。文档警告，这会带来权限问题和安全风险，涉及 sudo npm install -g。
• 使用 npm update -g 更新。正确方式是 npm install -g @anthropic-ai/claude-code@latest。
• 禁用可选依赖。实际的可执行文件作为平台专用的 @anthropic-ai/claude-code-* 软件包，以可选依赖的形式提供。--omit=optional标志或 .npmrc 中的 optional=false 会跳过此软件包：安装会无错误地完成，但在 macOS 和 Linux 上启动 claude 时会显示 claude native binary not installed。

安装成功了吗？

无论您选择哪种路径，都请打开一个新终端并运行以下两个命令：

claude --version   # sürüm numarasını yazar, ör. 2.1.211 (Claude Code)
claude doctor      # oturum açmadan kurulum ve ayar teşhisi

如果 claude --version 输出版本号，就表示程序已就绪。claude doctor 会在无需登录的情况下列出安装状态和设置文件中的问题；如果下一步出现问题，您可以据此判断问题出在安装还是配置。

无需订阅：为 Claude Code 设置 API 密钥

claude首次启动时会要求身份验证。如果您有 Claude 计划，登录后即可继续；如果没有计划，或者您希望按用量付费而不是支付固定月费，则可以使用 API 密钥运行 Claude Code。两种方式的区别如下：

使用密钥是一种 Anthropic 预期的配置方式：ANTHROPIC_BASE_URL 是 Claude Code 的内置变量，官方 gateway 文档也说明应使用此变量让 Claude Code 在代理或 gateway 后运行。您无需安装插件、补丁或修改过的客户端。在 macOS 和 Linux 上，将以下六行添加到 shell 文件（~/.zshrc 或 ~/.bashrc）中：

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # yalnızca alan adı, /v1 yok
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 会话中测试；窗口关闭后，变量也会消失：

# Yalnızca bu PowerShell penceresinde geçerli – pencereyi kapatınca kaybolur
$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 块。根据文档，此文件适用于您的所有项目；在 Windows 上的位置是 %USERPROFILE%\.claude\settings.json。一些 AI 摘要中出现的 %APPDATA%\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_AUTH_TOKEN 还是 ANTHROPIC_API_KEY？ Kunavo 的密钥接受这两个标头：Authorization: Bearer 和 x-api-key。区别在于 Claude Code 的行为。ANTHROPIC_AUTH_TOKEN 会发送到 Bearer 标头，并且无需提问即可运行。ANTHROPIC_API_KEY 会发送到 x-api-key 标头，并在交互模式下首次要求您确认；如果您对该问题选择“否”，密钥会在不发出警告的情况下被忽略。要重新启用它，您需要找到 /config → Use custom API key 路径。本指南使用 ANTHROPIC_AUTH_TOKEN，原因就在于此。

为什么要固定模型？根据模型配置文档（核实日期：2026年10月3日），通过 API 使用 Claude Code 时，如果未进行任何设置，默认模型以及 opus 别名会使用 Opus 5.5，sonnet 别名会使用 Sonnet 5.5；Anthropic 每次发布新模型时，这些别名也会随之更改。截至 2026年10月3日，Kunavo 尚未提供 Sonnet 5.5，因此未固定的 sonnet 请求会返回 404。Kunavo 提供 Claude Opus 5.5，但其价格（$2.80 / $14.00）高于 Claude Sonnet 5（$1.40 / $7.00）；如果不固定模型，你可能会在不知情的情况下使用更贵的模型。因此，上方配置中包含 ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5 这一行：/model sonnet、opusplan 的执行阶段以及设置为 model: sonnet 的子代理都会使用 Claude Sonnet 5，而不是 Sonnet 5.5。我们将 opus 别名固定为 Claude Opus 5.5 模型（claude-opus-5-5）；该模型要求 Claude Code v2.1.280 或更高版本，如果你的版本较旧，请运行 claude update。

Kunavo 的费率（输入 / 输出，每 100 万 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 块中定义，通常以设置文件中的值为准；如果在 shell 中修改的值没有生效，请先检查此处。设置文件中的 model 字段不受此规则影响：ANTHROPIC_MODEL 变量的优先级高于该字段，只有在未设置 model 时才会使用该字段。在 VS Code 扩展中，应将变量添加到 VS Code 用户设置中的 claudeCode.environmentVariables 字段。

首次启动和 /status 检查

如果变量位于正确位置，claude 命令会完全不显示登录界面并打开会话；gateway 文档（检查项：2026年10月3日）说明，在设置 ANTHROPIC_AUTH_TOKEN 时行为就是如此。如果出现登录界面，说明 Claude Code 没有看到密钥。常见原因是密钥只存在于项目设置中：在交互模式下，项目 .claude/settings.json 或 .claude/settings.local.json 文件中的 env 块，要在首次运行向导和文件夹信任提示完成后才会读取。密钥必须位于向导之前读取的位置：shell 中的 export、用户级 ~/.claude/settings.json 或托管设置（managed settings）。

登录会话后输入 /status。以下两行会提供足够的信息：

• Anthropic base URL：仅在设置了自定义地址时显示，并且应为 https://api.kunavo.com。如果完全没有此行，则表示 ANTHROPIC_BASE_URL 未到达会话。
• Auth token：如果旁边显示 ANTHROPIC_AUTH_TOKEN 名称，说明请求正在使用 API 密钥发送。如果出现显示 claude.ai 账户的 Login method 行，则 Claude Code 仍在使用已保存的登录信息；请退出登录，打开新终端，并检查您将变量写在了哪里。

不启动 Claude Code 进行测试

您也可以独立于 Claude Code 测试地址和密钥。官方文档中的方法是发送一个只包含一个输出 token 的请求；只会从余额中扣除极小金额。命令会从当前 shell 读取变量，如果密钥只位于设置文件中，请先在此终端中执行 export。如果响应以 {"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_API_KEY、ANTHROPIC_AUTH_TOKEN 或 apiKeyHelper 时无法运行。从 v2.1.196 起，当 ANTHROPIC_BASE_URL 指向 Anthropic 以外的服务器时，Remote Control 也会被禁用。
• /fast 显示为已关闭。根据文档，仅设置 bearer token 时，Claude Code 不会询问快速模式（fast mode）的状态，而是默认将其视为关闭。
• MCP 工具搜索默认关闭。MCP 文档（核实日期：2026年10月3日）将自定义 ANTHROPIC_BASE_URL 设置列为不会使用工具搜索的配置之一。
• /context 中的数字是近似值。Kunavo 不提供 /v1/messages/count_tokens 端点；在这种情况下，Claude Code 会根据字符数估算上下文用量，依据是网关兼容性文档（核实日期：2026年10月3日）。

集成的技术细节见英文版 Claude Code 集成文档；本指南的英文版本是 Install Claude Code。

从土耳其付款：银行卡、Apple Pay、Google Pay、Link

你在这里支付的不是订阅费用，而是 Claude Code 按 token 消耗的预付 API 余额。通过 Anthropic 网站购买 Pro 和 Max 只能使用信用卡或借记卡付款（Claude 付费计划常见问题，核实日期：2026年10月3日）。向 Kunavo 充值不能替代这些计划，也不能用于支付这些计划。操作步骤如下：

1. 注册 Kunavo。电子邮件地址或 Google 账户即可；注册时不会要求提供银行卡信息。
2. 在 Billing 页面选择金额。最低金额为 10 USD；没有订阅或月费。较高金额会增加奖励：充值 100 USD，获得 110 USD 余额、充值 1.000 USD，获得 1.200 USD 余额和充值 5.000 USD，获得 6.250 USD 余额。
3. Stripe 支付页面会打开。请选择银行卡（Visa、Mastercard）、Apple Pay、Google Pay 或 Link；Apple Pay 和 Google Pay 仅会在支持它们的设备和浏览器上列出。
4. 然后在 API Keys 页面生成一个以 sk-kn- 开头的密钥。密钥只显示一次；请复制后立即写入 ANTHROPIC_AUTH_TOKEN 的值。

金额显示为土耳其里拉还是美元？

Kunavo 以美元定价；Stripe 决定结账页面显示哪种货币，金额也可能以土耳其里拉显示。Stripe 的 Adaptive Pricing 文档（核实日期：2026年10月3日）将土耳其列为支持的市场，并说明这次货币转换所用的汇率会加上 2–4% 的费用，由买家承担。如果选择使用美元付款，则无需支付这笔费用；届时，你的发卡银行会采用自己的汇率，并收取适用的境外交易费。无论使用哪种货币，确认前都可以在结账页面查看确切金额。

分期付款、Papara、银行转账和 Troy

• 没有分期付款，只能一次性支付。使用土耳其银行卡在境外网站消费，之后也无法再分期（enuygunfinans.com，核查日期：2026年10月3日）。
• 不支持 Papara、银行转账/EFT 和 PayPal。支付页面不会出现这些选项。
• Troy：Stripe 的支持的银行卡品牌页面未列出 Troy（核查日期：2026年10月3日）。请使用带有 Visa 或 Mastercard 标志的银行卡付款。
• 不提供发票。Kunavo 不开具任何发票，包括电子存档发票；您的充值记录会保留在 Billing 页面。

如果银行卡被拒绝，请先查看银行的移动应用：银行卡必须开通网上购物和境外交易。自动充值只能使用已保存的银行卡或 Link 设置。余额没有有效期，失败的请求不会收费。所有模型的费率见 Claude API 价格指南。

一次工作会话需要多少钱？

使用密钥时，成本完全取决于 token 数量。Claude Code 会在每次请求中从头发送对话上下文；而当上下文中不变的开头部分从缓存读取时，则按低得多的费率计算。下表不是实际测量结果，而是基于明确假设的计算；也不应将其视为上限。假设如下：

• 每次请求 40,000 个输入 token；其中 36,000 个（%90）从缓存读取，剩余 4,000 个写入缓存；
• 每次请求 1,000 个输出 token；
• 会话中有 50 个请求；未计入后台的 Claude Haiku 4.5 调用；
• 对于 Claude Sonnet 5，从缓存读取的费用是输入费率的 %10，写入缓存则是 1.25 倍。表中的每个模型均按自身费率计算。

实际金额取决于上下文长度、缓存命中情况、回复长度，以及您切换主题时是否清空对话。官方费用文档（核查日期：2026年10月3日）还补充了两点：即使您没有输入任何内容，Claude Code 也会在后台消耗少量 token，通常每个会话低于 0.04 美元；API 密钥的缓存有效期默认为五分钟，因此间隔较长后的第一条消息会无法命中缓存，必须重新处理完整上下文。切换主题时使用 /clear，长会话中使用 /compact，都能降低这项费用。

所有费率都在价格页面上。您可以使用Claude token 成本计算器（英文）估算自己的用量。Claude Code 价格指南讨论订阅和 API 哪个更合适。

错误消息及解决方案

您需要了解的限制

• Kunavo 不提供发票；也不提供电子存档发票。
• 支付一次性扣款：不支持分期付款、Papara 和银行转账/EFT。自动充值需要已保存的银行卡或 Link。
• 这不是 Claude Pro 或 Max 订阅，而是按 token 付费的 API。使用密钥时，Remote Control 和语音听写无法运行，/fast 显示为关闭，MCP 工具搜索默认处于禁用状态。
• 截至 2026年10月3日，Kunavo 不提供 Sonnet 5.5；如果不固定模型，sonnet 别名会返回 404。
• Claude Code 的官方文档和 Kunavo 集成文档 仅提供英文版本（检查项：2026年10月3日）。

常见问题