返回指南
设置·2026年8月5日·更新于 2026年11月14日·阅读约 8 分钟

安装 Claude Code——适用于所有操作系统的命令、首次登录及常见错误

在每个平台上安装 Claude Code 都只需一条命令。下面介绍各操作系统对应的命令、无法正常运行时应执行的操作,以及之后将其指向其他端点所需的四个环境变量。

最后审核于 。

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

安装——原生安装程序

这是每个平台上的推荐方式。它会安装自包含的二进制文件,并在后台自动保持更新。

install.sh
# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash
PowerShell
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
cmd.exe
:: 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 上运行错误的命令是最常见的安装失败原因——请查看下方的故障排除表,了解两种情况对应的准确错误。

软件包管理器

如果你希望由现有的软件包管理器负责安装,可以使用这些方式。代价在于更新:与原生安装程序不同,这些方式默认都不会自动更新。

package-managers.sh
# 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-code

Homebrew 发布两个 cask:claude-code跟踪稳定频道(通常落后约一周,并跳过存在重大回归的版本),claude-code@latest则会立即发布每个版本。Debian / Ubuntu、Fedora / RHEL 和 Alpine 分别提供签名的 apt、dnf 和 apk 软件源,每个软件源都有 stable 和 latest 频道。

使用 npm 时,绝不要使用 sudo npm install -g——这会导致权限问题,也会带来安全风险。npm 软件包安装的原生二进制文件与独立安装程序完全相同,因此无论采用哪种方式,运行时都不依赖 Node。

验证安装

verify.sh
claude --version   # prints e.g. "2.1.211 (Claude Code)"
claude doctor      # read-only install + settings diagnostics
claude             # start a session in the current project

claude 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,因此这是受支持的配置,而不是权宜之计。不需要插件、代理或修改过的二进制文件:

~/.zshrc
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%。

后续步骤