如何在 Windows、macOS 和 Linux 上安装 Claude Code——以及如何不订阅即可使用

安装 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 行）。然后打开新的终端，使用 claude --version 检查，进入项目文件夹并运行 claude；第一个有用的命令是 /init。连接有两种方式：使用 Pro、Max、Team、Enterprise 或 Console 账户登录（Claude.ai 免费套餐不包含 Claude Code），或定义两个环境变量 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN，并使用按量付费的 API 密钥，无需订阅。

已验证的命令，验证日期为 2026年9月11日，依据是Anthropic 官方安装文档。

要求

在 macOS 和 Linux 上安装

打开终端并粘贴：

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

这是推荐方法：安装一个可在后台自动更新的独立二进制文件。可执行文件位于 ~/.local/bin/claude，而已打开的终端看不到新的 PATH，因此请先打开另一个窗口再进行测试。在 WSL 中命令相同。

在 Windows 上安装 Claude Code

Windows 有两行不同的命令，唯一变化的是终端。如果提示符以 PS C:\Users\TuNombre> 开头，你使用的是 PowerShell；如果没有 PS，只有 C:\Users\TuNombre>，则是命令提示符（CMD）。不需要以管理员身份运行。

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

:: Windows Símbolo del sistema (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

将命令粘贴到错误的终端是最常见的问题。CMD 命令在 PowerShell 中会显示 The token '&&' is not a valid statement separator；PowerShell 命令在 CMD 中会显示 'irm' is not recognized as an internal or external command（在西班牙语 Windows 中为“不是内部或外部命令”）；而将 macOS 的 curl … | bash 粘贴到 PowerShell 中会显示 A parameter cannot be found that matches parameter name 'fsSL'。三种情况下只需使用对应的命令即可。

安装 Git for Windows 是可选但推荐的：Claude Code 使用其 Git Bash 执行命令；没有它时则使用 PowerShell。如果已安装 Git，但仍找不到 Git Bash，请在配置的 env 区块中将 CLAUDE_CODE_GIT_BASH_PATH 设置为 bash.exe 的路径。

使用 WSL 时，在 WSL 终端内执行 macOS/Linux 命令，并在那里打开 claude，不要从 PowerShell 或 CMD 打开。

使用包管理器

同样可用，但有一个重要区别：默认情况下都不会自动更新（你需要运行 brew upgrade claude-code 或 winget upgrade Anthropic.ClaudeCode）。此外，还提供适用于 Debian/Ubuntu、Fedora/RHEL 和 Alpine 的已签名 apt、dnf 和 apk 软件源。

# Homebrew (macOS, Linux) — canal stable
brew install --cask claude-code

# WinGet (Windows)
winget install Anthropic.ClaudeCode

# npm — requiere Node.js 22 o posterior; nunca con sudo
npm install -g @anthropic-ai/claude-code

使用 npm 时，自 2.1.198 版本起，该软件包要求 Node.js 22 或更高版本；使用旧版 Node 时，npm 只会显示 EBADENGINE 警告，安装仍会完成。它安装的是同一个原生二进制文件，运行时不使用 Node.js。绝不要使用 sudo npm install -g：这会导致权限问题并带来安全风险。

检查安装

claude --version   # imprime la versión, por ejemplo 2.1.211 (Claude Code)
claude doctor      # diagnóstico de la instalación y la configuración, sin abrir sesión

使用 claude doctor：无需登录即可显示安装状态、配置文件错误和建议的解决方案。这是判断问题出在安装还是配置上的最快方式。

如果看到 command not found: claude（或者在 Windows 中看到 claude 未被识别），说明安装目录不在 PATH 中。在 macOS 和 Linux 上打开新终端；如果仍然如此，将 ~/.local/bin 添加到 ~/.zshrc 或 ~/.bashrc 中的 PATH。在 Windows 上，目录是 %USERPROFILE%\.local\bin；请检查并在 PowerShell 中添加它：

# 1. Comprueba si la carpeta de instalación ya está en el PATH
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. ¿Sin salida? Añádela al PATH de usuario y abre una terminal nueva
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. En la terminal nueva: si hay dos instalaciones, verás dos rutas
where.exe claude

首次连接：订阅或 API 密钥

选项 A — 使用订阅登录

在项目目录中运行 claude，然后使用 Pro、Max、Team、Enterprise 或 Console 账户在浏览器中完成登录。有一点容易造成困惑：如果已设置 ANTHROPIC_API_KEY 变量，Claude Code 会只询问一次你是否要使用该密钥。如果你选择否，之后它会忽略该变量且不再询问，看起来就像没有读取变量。要重新启用：/config → Use custom API key。

选项 B — 没有订阅，使用按量付费密钥

Claude Code 原生读取 ANTHROPIC_BASE_URL，因此将其指向任何 Anthropic Messages API 端点都是受支持的配置：无需插件、代理或修改后的二进制文件。步骤如下：创建账户，充值余额（最低 $10），在密钥面板中生成 sk-kn- 密钥（仅显示一次），并将此 env 区块添加到用户配置 ~/.claude/settings.json 中（Windows 使用 %USERPROFILE%\.claude\settings.json）。这样所有终端、编辑器扩展和后台进程都能看到它：

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

要先在单个 PowerShell 窗口中测试：

# Solo para esta ventana de PowerShell (en macOS/Linux: export VARIABLE=valor)
$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

• ANTHROPIC_BASE_URL只包含域名。 Claude Code 会添加 /v1/messages；末尾加上 /v1 时，请求会发送到 /v1/v1/messages 并返回 404。
• 使用 ANTHROPIC_AUTH_TOKEN，不要使用 ANTHROPIC_API_KEY。 二者位于不同的 HTTP 标头中：前者发送 Authorization: Bearer 并立即生效；后者发送 x-api-key，还会经过上文所述的一次性批准。
• 在 ANTHROPIC_MODEL 中填写模型的准确名称。 Kunavo 只识别完全相同的名称，不会翻译带日期的旧名称。
• 同时固定 ANTHROPIC_DEFAULT_OPUS_MODEL。Claude Code 的默认模型及其别名 opus指向最新的 Opus；如果 Kunavo 尚未提供该模型，首次请求会返回 404。此处将别名 opus固定为 Claude Opus 5.5（claude-opus-5-5），这要求 Claude Code v2.1.280 或更高版本；如果使用更早版本，请执行 claude update。
• 同时固定 ANTHROPIC_DEFAULT_SONNET_MODEL。别名 sonnet请求 Sonnet 5.5，但 Kunavo 不提供该模型：如果没有此变量，/model sonnet、opusplan的执行阶段以及配置为使用 sonnet的子代理都会返回 404。将其固定为 claude-sonnet-5即可避免此问题。
• 同样要设置 ANTHROPIC_DEFAULT_HAIKU_MODEL。haiku别名会请求 Kunavo 不提供的 ID（从 v2.1.293 起为 Haiku 5.5）：若没有此变量，/model haiku和设为 haiku 的子代理都会返回 404。将其固定为 claude-haiku-4-5即可避免此问题；此外，它还会把 Claude Code 自行发起的后台调用（摘要、标题）从主模型转移出去。

绝不要将密钥放在项目的 .claude/settings.json 中：该文件会进入代码仓库。在 VS Code 扩展中，变量应放在 claudeCode.environmentVariables 的 VS Code 用户配置中，因为扩展会在启动前检查凭据。

每 1M 个 token 的费率，读取自目录：

如何知道当前启用的选项

在 Claude Code 中运行 /status。出现 Auth token 行表示正在使用密钥；出现 Login method 行且账户为 claude.ai，则表示未读取该变量。二者不会叠加：只要变量存在，订阅就会暂停；删除变量后，Claude Code 会恢复使用订阅，无需重新安装。

通过网关时会有三点变化：Remote Control 和语音听写不可用（它们需要 claude.ai 身份）；/fast 可能提示快速模式不可用，因为该检查会直接连接 Anthropic，但普通请求不变；/context 中的数字会变成本地估算。代码、工具、子代理、MCP、hooks 和 prompt caching 均保持不变。完整详情见集成文档和Claude Code API key 指南（均为英文）。

如何使用 Claude Code：入门步骤

# 1. Arranca siempre dentro de la carpeta del proyecto
cd ~/proyectos/mi-app
claude

# 2. Primer comando: lee el repositorio y genera CLAUDE.md
> /init

# 3. Pide las tareas en español y con la ruta del archivo
> cambia la validación de src/api/user.ts a zod y arregla los tests

# 4. Para tareas que tocan muchos archivos: Shift+Tab activa el modo plan

Claude Code 会在编辑文件或执行命令前请求许可；如果方向不对，按 Esc 停止，并使用 /rewind 返回到之前的状态。/init生成的 CLAUDE.md 是草稿：只保留你每次会话都会重复的内容（测试命令、约定、不应触碰的目录）。它会在每次会话中加载并随每个请求发送，Anthropic 建议不要超过 200 行。

• 切换模型： 使用 /model 加完整名称，例如 /model claude-opus-5，或使用 claude --model claude-opus-5 启动。请在任务之间切换：每个模型都有自己的缓存，中途切换会迫使系统在没有缓存的情况下重新读取整个对话。
• 在无关任务之间使用 /clear。 开始新对话无需费用；之前的对话可通过 /resume 恢复。
• 任务变长时使用 /compact： 压缩历史并继续。使用 API 密钥时，缓存默认持续五分钟，因此应在长时间暂停之前压缩，而不是之后。
• 一次会话的费用： /usage 会显示 token 数量，但它计算的金额是按 Anthropic 标价进行的本地估算；使用 Kunavo 时，实际费用位于你的使用情况页面。

付款与关于选择的坦诚说明

余额通过 Stripe 预付：银行卡（Visa、Mastercard、American Express、JCB、UnionPay）、Apple Pay、Google Pay 或 Link；不提供 SEPA 直接扣款。最低充值金额为 $10，余额不会过期，失败的请求不收费，且每个密钥都支持月度支出上限。所有费率均列于价格页面。

如果你每天长时间使用 Claude Code，订阅的固定费用通常更便宜；当使用不规律或你不想受 5 小时窗口限制时，按量付费更划算，而且整月没有活动时费用为零。完整比较（英文）见 Claude Code pricing。通过 Kunavo 使用的是共享容量，没有专用配额或合同 SLA；如果需要这些保证，请直接向 Anthropic 购买。

常见问题