Claude Code 在每个受支持的平台上都可以通过一条命令安装,首次运行的完整流程是:安装、输入 claude、登录。本指南提供每种操作系统的准确命令、无法运行时的检查方法,以及运行成功后如何指向不同端点。
已针对 Anthropic 的 Claude Code 设置文档验证命令 2026年11月14日。
开始之前
| 要求 | 支持内容 |
|---|---|
| 操作系统 | macOS 13.0+、Windows 10 1809+ / Server 2019+、Ubuntu 20.04+、Debian 10+、Alpine Linux 3.19+ |
| 硬件 | 4 GB+ 内存,x64 或 ARM64 |
| 命令行解释器(Shell) | Bash、Zsh、PowerShell 或 CMD |
| 网络 | 需要互联网连接 |
| 账户 | Pro、Max、Team、Enterprise 或 Console——免费的 Claude.ai 计划不包含 Claude Code |
安装——原生安装程序
这是每个平台上的推荐方式。它会安装自包含的二进制文件,并在后台自动保持更新。
# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash# Windows PowerShell
irm https://claude.ai/install.ps1 | iex:: Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd如果你不确定当前使用的是哪种 Windows shell,提示符会告诉你:PowerShell 显示 PS C:\,CMD 显示 C:\,且不带 PS。在 Windows 上运行错误的命令是最常见的安装失败原因——请查看下方的故障排除表,了解两种情况对应的准确错误。
软件包管理器
如果你希望由现有的软件包管理器负责安装,可以使用这些方式。代价在于更新:与原生安装程序不同,这些方式默认都不会自动更新。
# Homebrew (macOS, Linux) — stable channel
brew install --cask claude-code
# WinGet (Windows)
winget install Anthropic.ClaudeCode
# npm — requires Node.js 22+; never with sudo
npm install -g @anthropic-ai/claude-codeHomebrew 发布两个 cask:claude-code跟踪稳定频道(通常落后约一周,并跳过存在重大回归的版本),claude-code@latest则会立即发布每个版本。Debian / Ubuntu、Fedora / RHEL 和 Alpine 分别提供签名的 apt、dnf 和 apk 软件源,每个软件源都有 stable 和 latest 频道。
使用 npm 时,绝不要使用 sudo npm install -g——这会导致权限问题,也会带来安全风险。npm 软件包安装的原生二进制文件与独立安装程序完全相同,因此无论采用哪种方式,运行时都不依赖 Node。
验证安装
claude --version # prints e.g. "2.1.211 (Claude Code)"
claude doctor # read-only install + settings diagnostics
claude # start a session in the current projectclaude doctor 是需要记住的命令:它会在不启动会话的情况下,打印安装健康状态、设置文件验证错误和建议的修复方法,因此是区分安装损坏与配置损坏的最快方式。
首次运行和登录
在你希望处理的项目中打开终端,并运行 claude。它会打开交互式会话,并引导你在浏览器中登录。Claude Code 要求使用 Pro、Max、Team、Enterprise 或 Console 账户。
有一个行为值得提前了解,以免它让你措手不及:如果环境中已经设置了 ANTHROPIC_API_KEY,Claude Code 会提示你一次批准该密钥,而不是打开浏览器。拒绝该提示后,密钥会被静默忽略,之后不再提示——这看起来就像没有读取该变量一样。请在 /config → 使用自定义 API 密钥 中重新启用它。
Windows:原生 Windows 或 WSL
| 选项 | 要求 | 沙盒化 | 在以下情况下选择它 |
|---|---|---|---|
| 原生 Windows | 无;Git for Windows 可选 | 不支持 | 你的项目和工具使用 Windows 原生版本 |
| WSL 2 | 已启用 WSL 2 | 支持 | Linux 工具链,或需要沙盒化命令执行 |
| WSL 1 | 已启用 WSL 1 | 不支持 | 你无法使用 WSL 2 |
在原生 Windows 上,安装 Git for Windows 是可选但推荐的:它提供支持 Bash 工具的 Git Bash。没有它时,Claude Code 会改用 PowerShell 工具运行 shell 命令。在 WSL 中,你应在 WSL 终端内安装并启动 claude,而不是从 PowerShell 启动。
故障排除
| 症状 | 原因和修复方法 |
|---|---|
The token '&&' is not a valid statement separator | 你在 PowerShell 中运行了 CMD 命令。改用 irm … | iex 行。 |
'irm' is not recognized… | 反过来——你在 CMD 中运行了 PowerShell 命令。改用 curl … install.cmd 行。 |
syntax error near unexpected token '<'、403 或其他 curl 错误 | 下载没有返回脚本——通常是你与安装程序之间存在代理或网络过滤器。重试,或改用软件包管理器安装。 |
干净安装后出现 claude: command not found | 打开一个新终端,让 shell 获取安装目录,然后运行 claude doctor。另一个较旧的安装或过时的 shell 别名,是另一个常见原因。 |
| npm 安装期间出现权限错误 | 你使用了 sudo,或者 npm 全局目录不可写。修复目录所有权,而不是使用 sudo 重新运行;不可写的全局目录也会阻止自动更新。 |
npm install -g 后缺少原生二进制文件 | 你的软件包管理器配置为跳过可选依赖。平台二进制文件以可选依赖的形式提供,因此请允许安装可选依赖后重新安装。 |
| 在 Alpine 或其他 musl 发行版上安装失败 | Alpine 未预装 bash 和 curl。安装 bash curl libgcc libstdc++ ripgrep,然后在设置文件的 env 区块中,将 USE_BUILTIN_RIPGREP 设置为 "0"。 |
| 搜索和文件发现失败 | 通常会捆绑 ripgrep。如果它无法在你的平台上运行,请安装系统 ripgrep 并设置 USE_BUILTIN_RIPGREP=0。 |
| 原生 Windows 上缺少 Bash 工具 | 安装 Git for Windows。如果 Claude Code 仍然找不到 Git Bash,请在 ~/.claude/settings.json 的 env 区块中设置 CLAUDE_CODE_GIT_BASH_PATH。 |
配置密钥后出现 401 | 密钥位于服务器不读取的请求头中——在 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 之间切换。详情请参阅API 密钥指南。 |
让 Claude Code 指向 Kunavo
运行成功后,Claude Code 可以使用任何提供 Anthropic Messages API 的端点——它原生读取 ANTHROPIC_BASE_URL,因此这是受支持的配置,而不是权宜之计。不需要插件、代理或修改过的二进制文件:
export ANTHROPIC_BASE_URL=https://api.kunavo.com
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关于该区块,有五点需要注意;如果弄错其中任何一点,都可能浪费你一小时:
ANTHROPIC_BASE_URL只能是源地址。 Claude Code 会自行追加/v1/messages——如果包含路径,就会返回 404。- 使用
ANTHROPIC_AUTH_TOKEN,不要使用ANTHROPIC_API_KEY。 它们位于不同的 HTTP 请求头中。Bearer token 会立即生效,而ANTHROPIC_API_KEY需要上文所述的一次性批准。Kunavo 会从任一请求头读取密钥,包括/v1/models,因此在 Kunavo 上,批准步骤就是区分二者的关键。 - 明确设置
ANTHROPIC_MODEL。 Kunavo 会严格匹配模型 slug,不会为带日期后缀的名称创建别名,因此claude-sonnet-4-5-20250929会返回 404,而claude-sonnet-5可以正常工作。 - 同时固定
ANTHROPIC_DEFAULT_OPUS_MODEL和ANTHROPIC_DEFAULT_SONNET_MODEL。Claude Code 的内置默认模型及其opus别名都会解析为最新的 Opus;如果 Kunavo 尚未提供该模型,第一次请求就会返回 404。该配置块将opus固定为 Opus 5.5(claude-opus-5-5),这需要 Claude Code v2.1.280 或更高版本——旧版本请运行claude update。sonnet别名会请求 Sonnet 5.5,而 Kunavo 不提供该模型,因此如果没有 Sonnet 固定配置/model sonnet,opusplan的执行阶段以及设置为model: sonnet的任何子代理都会返回 404。 - 也要固定指定
ANTHROPIC_DEFAULT_HAIKU_MODEL。haiku别名会请求 Kunavo 不提供的模型 ID(v2.1.293 起为 Haiku 5.5;更早版本则请求带日期的 Haiku 4.5 ID),因此如果没有这一行,/model haiku和设为model: haiku的子代理(包括内置的claude-code-guide)都会返回 404。它还会将 Claude Code 自行发起、用于生成摘要和标题的后台调用从主模型转移出去:claude-haiku-4-5的每百万 token 输入/输出价格为 $0.70 / $3.50,而 Sonnet 为 $1.40 / $7.00。
如果希望编辑器和后台代理也能看到这些变量,请将它们放入 ~/.claude/settings.json 的 env 区块,而不是 shell export 中——绝不要放入项目已提交的 .claude/settings.json。在控制台中注册后创建 sk-kn- 密钥;最低充值金额为 $10,没有月费,余额不会过期。每个模型的每 token 成本,以及与Anthropic 官方 API 定价的对比,将决定这 $10 能使用多久。
网关后的变化
编码、工具、子代理、MCP、hooks 和提示缓存都不受影响。有三件事确实会变化,在认定某些功能损坏之前值得了解:
- Remote Control 和语音听写不可用。 二者都需要 claude.ai 身份,而网关凭证会替代该身份。
/fast可能会报告快速模式已禁用。 可用性检查会直接调用 Anthropic,而不会遵循你的 base URL。正常请求不受影响。/context计数会变成本地估算。 token 计数是 Anthropic 自己的网关规范标记为可选的唯一端点;缺少该端点时,Claude Code 会在本地估算——Kunavo 目前不提供/v1/messages/count_tokens。自动压缩和会话本身不受影响。
完整列表以及路由器与不使用路由器之间的选择,请参阅 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 中运行 `curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd`。原生安装程序是推荐方式,并会在后台自动保持更新。也支持 Homebrew(`brew install --cask claude-code`)、WinGet(`winget install Anthropic.ClaudeCode`)、npm 以及签名的 apt/dnf/apk 软件源,但这些方式默认都不会自动更新。
安装 Claude Code 需要 Node.js 吗?
原生安装程序、Homebrew、WinGet 或 Linux 软件包仓库都不需要——它们安装的是运行时不使用 Node 的原生二进制文件。只有 npm 安装路径涉及 Node;截至 v2.1.198,该软件包要求 Node.js 22 或更高版本。即便如此,npm 也只是通过按平台提供的可选依赖拉取同一个原生二进制文件。
Claude Code 的系统要求是什么?
macOS 13.0+、Windows 10 1809+ 或 Windows Server 2019+、Ubuntu 20.04+、Debian 10+ 或 Alpine Linux 3.19+;x64 或 ARM64 处理器,4 GB 或更多内存;互联网连接;以及 Bash、Zsh、PowerShell 或 CMD shell。你还必须位于 Anthropic 支持的国家/地区。
首次如何登录 Claude Code?
在项目目录中运行 `claude`,然后按照浏览器提示操作。Claude Code 要求使用 Pro、Max、Team、Enterprise 或 Console 账户——免费的 Claude.ai 计划不包含 Claude Code 访问权限。如果设置了 ANTHROPIC_API_KEY 环境变量,Claude Code 会提示你批准该密钥一次,而不是打开浏览器。
可以在不使用 WSL 的情况下在 Windows 上安装 Claude Code 吗?
可以。运行 PowerShell 或 CMD 安装程序,然后从任意终端启动 `claude`;不需要管理员权限。Git for Windows 是可选的,但建议安装,因为它提供支持 Bash 工具的 Git Bash——没有它时,Claude Code 会改用 PowerShell 工具运行 shell 命令。如果你需要 Linux 工具链或沙盒化命令执行,应选择 WSL 2,因为原生 Windows 不支持这些功能。
为什么安装后 `claude` 显示 command not found?
安装目录不在你当前使用的 shell 的 PATH 中。先打开一个新终端——安装程序会在 macOS 和 Linux 上添加 ~/.local/bin,而现有会话不会获取这一变化。运行 `claude doctor`,对安装和设置文件进行只读诊断。另一个较旧的安装,或遗留的 shell 别名,是另一个常见原因。
如何让 Claude Code 使用不同的 API 端点?
将 ANTHROPIC_BASE_URL 设置为任何提供 Anthropic Messages API 的端点的源地址——Claude Code 原生读取该变量,并自行追加 /v1/messages,因此无需插件或代理。将其与用于凭据的 ANTHROPIC_AUTH_TOKEN 和明确设置的 ANTHROPIC_MODEL 配合使用,并将 ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL 和 ANTHROPIC_DEFAULT_HAIKU_MODEL 固定为该端点提供的模型,因为 Opus 和 Sonnet 别名默认会跟随 Anthropic 的最新模型。在 Kunavo 上,同样的 Claude 模型按量付费,价格比 Anthropic 标价低 30%。
后续步骤
- Claude Code API 密钥——在哪里获取、放在哪里,以及大多数 401 错误背后的请求头不匹配问题。
- Claude Code 定价——订阅与 API、按模型计费,以及一个月的成本。
- Claude Code 免费吗?——哪些内容免费,哪些不免费,以及界线在哪里。
- 在没有权限提示的情况下运行——
--dangerously-skip-permissions实际移除了什么,以及三种每种约一分钟即可完成的限制措施。 - Claude Code 与 Codex CLI 对比——如果你仍在选择终端代理。