下载 Claude Code 前，先分清桌面安装包和终端命令

更新于 2026-10-21 · soleapi.cyou

简答：要在终端里用 Claude Code，不要下桌面 dmg 或 exe。先跑官方安装脚本，再新开终端执行 claude --version，能打出版本号才算装上。免费 claude.ai 计划不含 Claude Code，要用 Pro、Max、Team、Enterprise 或 Console。桌面应用和 VS Code 扩展都不会把 claude 写进 PATH。

定义：Claude Code 终端版是本机的 claude 命令，和 Claude 桌面安装包、编辑器扩展、网页入口不是同一个下载。

先看对照表：你要下的是哪一个

本页是第三方接入说明，不是 Anthropic 官网，也不提供安装包镜像。搜索 claude code download 时，Claude 官方下载页先放桌面按钮，页内没有终端安装命令。终端里的 claude 要另装。本文不覆盖模型评测、价格与额度，不写 Amazon Bedrock、Google Cloud Agent Platform、Microsoft Foundry 的控制台步骤，也不写绕过地区或网络限制的做法。

先对下面这张表，再决定下安装包还是跑命令。只有终端安装才会在系统 PATH 里留下 claude。

你的目标	该安装什么	终端里有没有 claude	谁负责更新
在终端改代码、跑脚本	官方原生安装脚本	有，必须新开终端再查	后台自动更新，默认 latest
图形界面改本机项目	桌面应用里的 Code 标签	不依赖本机 claude 命令	本文未展开桌面端的更新机制
留在 VS Code 里	Claude Code 扩展	扩展不写入 PATH	扩展版本号就是它自带的那份 CLI
留在 JetBrains 里	先装 CLI，再装插件	插件调用 PATH 上的 claude	跟随你安装 CLI 的那种方式
不想安装本机程序	网页入口	没有本机命令	不适用

系统要求以 Claude Code 高级设置为准。CLI 支持 macOS 13.0+、Windows 10 1809+ 或 Windows Server 2019+、Ubuntu 20.04+、Debian 10+、Alpine Linux 3.19+，需要 4 GB 以上内存，以及 x64 或 ARM64。桌面应用的要求写在安装 Claude Desktop 的帮助中心说明：macOS 13 或更高、Windows 10 或更高；Linux 桌面仍是 beta，只写了 Ubuntu 22.04 LTS+ 或 Debian 12+，架构为 x64 或 arm64。CLI 能覆盖的发行版比 Linux 桌面 beta 多，不要把两套要求当成同一条。

桌面应用快速上手写明：Code 标签使用桌面应用自带的 Claude Code，不必先装 Node.js 或终端 CLI；点 Code 若提示升级，需要先订阅付费计划。VS Code 扩展说明写明扩展自带一份私有 CLI，供聊天面板使用，不会把 claude 放进 PATH；要在 VS Code 集成终端里输入 claude，仍要单独安装 CLI。扩展要求 VS Code 1.94.0 或更高。JetBrains 插件说明写明插件不打包 CLI，它在 IDE 终端里运行 claude；PATH 上没有这个命令时，会提示无法启动。Claude Code 快速上手把网页入口记为 claude.ai/code，那不是本机命令。

帮助中心的功能表把 Claude Code 标在 Pro、Max、Team、Enterprise，免费计划只有聊天。这和 CLI 文档一致：免费 claude.ai 计划不含 Claude Code。

终端版按官方脚本安装

原生安装是现行推荐方式：一个自包含可执行文件，不依赖 Node.js，安装过程没有进度条，窗口要保持开着直到结束。只从下面这些官方地址安装，不要运行来源不明的 exe 或脚本。

macOS、Linux 和 WSL

在终端执行：

curl -fsSL https://claude.ai/install.sh | bash

这是默认的 latest。要改走大约滞后一周、并跳过有严重回归的 stable，执行：

curl -fsSL https://claude.ai/install.sh | bash -s stable

安装时选定的通道会成为以后自动更新的默认通道。设置页里锁定具体版本的示例写成 bash -s 2.1.89，那个数字只说明写法，不是当前最新版。装完后 claude --version 会打印你实际装上的版本。

WSL 要在发行版自己的终端里跑这条 Linux 命令，不要在外面的 PowerShell 或 CMD 里装完却指望 WSL 里出现命令。Alpine 和其它 musl 发行版默认往往没有 bash 与 curl，官方示例是先安装 bash、curl、libgcc、libstdc++、ripgrep，再把 USE_BUILTIN_RIPGREP 设为 0。文档里的 community 仓库路径用 Alpine v3.22 做例子，要换成你自己的版本号。

Windows：先分清 PowerShell 和 CMD

行首带 PS 是 PowerShell，没有 PS 是 CMD。两条命令不能混用。不需要用管理员身份运行。

PowerShell：

irm https://claude.ai/install.ps1 | iex

CMD：

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

stable 通道在 PowerShell 里是 & ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable，在 CMD 里是把上面的 install.cmd 改成 install.cmd stable。出现 The token '&&' is not a valid statement separator，说明你在 PowerShell 里跑了 CMD 命令。出现 'irm' is not recognized，说明你在 CMD 里跑了 PowerShell 命令。原生 Windows 建议另外安装 Git for Windows，这样 Bash 工具可用；没装时，Claude Code 改用 PowerShell 执行命令。WSL 不需要 Git for Windows。Git Bash 路径变量名是 CLAUDE_CODE_GIT_BASH_PATH，写法见高级设置页，不要从旧博客抄盘符。

Homebrew、WinGet、apt、dnf、apk

Homebrew 稳定通道：brew install --cask claude-code。最新通道：brew install --cask claude-code@latest。两者默认都不自动更新，分别用 brew upgrade claude-code 或 brew upgrade claude-code@latest。cask 名决定通道，不看 autoUpdatesChannel 设置。
WinGet：winget install Anthropic.ClaudeCode。默认不自动更新，以后执行 winget upgrade Anthropic.ClaudeCode。程序正在运行时升级可能失败，因为 Windows 会锁住可执行文件。
Debian、Ubuntu 用 apt，Fedora、RHEL 用 dnf，Alpine 用 apk。仓库分 stable 与 latest，默认不由 Claude Code 自动更新，因为升级需要更高权限。升级命令分别是 sudo apt update && sudo apt upgrade claude-code、sudo dnf upgrade claude-code、apk update && apk upgrade claude-code。添加仓库前要核对签名。设置页给出的指纹是 31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE。本文不把整段仓库配置拆短，避免少抄一行后出现 NO_PUBKEY。

原生安装会在后台检查更新，下次启动再生效。Homebrew 和 WinGet 可以把 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE 设为 1，让 Claude Code 代跑对应的升级命令。apt、dnf、apk 仍然要手动升级。设置页还写了一条已知情况：Claude Code 可能在软件源还没有新版本时就提示更新，升级失败就稍后再试。

只有需要时才用 npm

npm 全局安装要求 Node.js 22 或更新：npm install -g @anthropic-ai/claude-code。更旧的 Node.js 会打出 EBADENGINE 警告，但安装不一定失败，因为装上的是原生二进制，运行时不调用你的 Node.js。不要执行 sudo npm install -g，设置页写明这会带来权限和安全问题。升级用 npm install -g @anthropic-ai/claude-code@latest，不要用 npm update -g，后者会受当初版本范围限制。

装完自检：新开终端、版本和 PATH

安装命令返回后，关掉当前终端，新开一个再查。已经开着的窗口、以及编辑器里的集成终端，都还拿着旧的 PATH。

claude --version

claude doctor

版本命令成功时会打印版本号，并带有 (Claude Code)。高级设置页用 2.1.211 (Claude Code) 说明输出长什么样，这不是固定的当前版本。claude doctor 只做只读诊断，不开启会话，会显示安装健康状况、设置文件错误，以及最近一次更新尝试的结果。

提示 command not found

原生安装把程序放在 macOS 与 Linux 的 ~/.local/bin/claude，或 Windows 的 %USERPROFILE%\.local\bin\claude.exe。安装器如果发现这个目录不在 PATH 里，会在 Setup notes 里说明，但不会替你改 PATH。只装了 VS Code 扩展时，这个路径本来就不存在，要回到上一节做独立安装。步骤以安装和登录排错为准。

macOS 或 Linux 先看文件在不在：ls -la ~/.local/bin/claude。没有这个文件，就还没装上原生版。
再看目录在不在 PATH 里：echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"。没有输出时，Zsh 执行 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc，然后 source ~/.zshrc。Linux 上的 Bash 把同一行追加到 ~/.bashrc。macOS 上的 Bash 不要写进 ~/.bashrc，终端把 Bash 当成登录 shell，应写入 ~/.bash_profile；若已经有 ~/.bash_login 或 ~/.profile 且没有 ~/.bash_profile，就写进已有的那个文件。
Windows PowerShell 先执行 Test-Path "$env:USERPROFILE\.local\bin\claude.exe"。结果为 True 但命令仍不可用时，执行 $currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')，再执行 [Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')，然后重新打开终端。CMD 用 dir "%USERPROFILE%\.local\bin\claude.exe" 检查文件，缺目录时到系统的用户环境变量里添加 %USERPROFILE%\.local\bin。
再次执行 claude --version。仍找不到时，用 echo $0 确认当前 shell，避免把 PATH 写进另一个 shell 的配置文件。编辑器里的终端要连编辑器一起退出重开。

安装脚本报 403 或返回网页

命令没有进度是正常的，先等到它结束。若出现 syntax error near unexpected token '<'，或 PowerShell 在解析 HTML，说明下到的不是安装脚本。排错页把 curl: (22) The requested URL returned error: 403 归到同一类：常见原因是代理或网络过滤拦了主机，或者当前地区不在支持范围。地区名单以 Anthropic 支持国家列表为准，本文不逐国抄录，也不提供绕过限制的步骤。5xx 在该页被写成暂时性服务问题，过几分钟再试。登录阶段的 OAuth 或 403 是另一件事，见下一节，不要和安装脚本的 403 混在一起查。

同一台机器上如果原生安装、旧的 ~/.claude/local 和 npm 全局包同时存在，版本会打架。macOS 与 Linux 用 which -a claude 查看 PATH 里的全部命令。官方建议保留原生安装，去掉多余的那一份；具体卸载命令在排错页按安装方式分开写。

登录，以及兼容接口的三项核对

文件装上还不等于能用。高级设置写明：Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 账号，免费 claude.ai 计划不含这项能力。快速上手把订阅登录列为推荐，Console 是预充值的 API 访问；第一次用 Console 登录时，会自动建一个名为 Claude Code 的工作区用来记费用。云厂商和自建网关是另外的登录路径，本文只核对环境变量，不展开各家控制台。

第一次启动先看它在用哪一种凭据

在项目目录执行 claude。订阅或 Console 会打开浏览器登录。凭据保存后，以后不必每次再登，会话里可以用 /login 换账号。登录失败时按这个顺序看，不必先重装：

账号是不是免费计划。免费计划不含 Claude Code，桌面里点 Code 若要求升级，也是同一门槛。
环境里有没有已经导出的 ANTHROPIC_API_KEY。交互模式会问一次是否改用这把 Key；你确认后，它会代替订阅登录。非交互的 claude -p 只要这把 Key 存在就会使用它。想回到订阅，执行 unset ANTHROPIC_API_KEY，或在 /config 里关掉自定义 API Key。这个开关只在环境变量仍存在时出现。
凭据优先级以 Claude Code 认证说明为准：云厂商开关 CLAUDE_CODE_USE_BEDROCK、CLAUDE_CODE_USE_VERTEX、CLAUDE_CODE_USE_FOUNDRY 优先；其次是 ANTHROPIC_AUTH_TOKEN，它会放进 Authorization: Bearer；再次是 ANTHROPIC_API_KEY，它走 X-Api-Key。网关令牌会立刻盖过已保存的 claude.ai 登录。
地区是否在支持国家列表里。不在列表里时，安装和登录都可能失败，处理方式仍以上一节的官方说明为准。

兼容接口只核 Base URL、认证头、模型名

环境变量说明写明：ANTHROPIC_BASE_URL 用来把请求改送到代理或网关，它不负责挑选模型。变量要在启动 claude 之前设好，已经开着的会话读不到后来的修改。直连 Anthropic 时，列出模型的官方示例使用主机 https://api.anthropic.com。走网关时，基址用网关给你的地址，末尾不要再加 /v1，因为下面的路径会自己拼上 /v1/models 和 /v1/messages。

把 Claude Code 接到 LLM 网关把凭据分成两种：对方要 Bearer 或 Authorization 头时用 ANTHROPIC_AUTH_TOKEN；对方要 API Key 或 x-api-key 时用 ANTHROPIC_API_KEY。没说明就先试 ANTHROPIC_AUTH_TOKEN，验证请求返回 401 再换另一种。头放错时，网关读不到凭据，结果同样是 401。未知模型名仍然说明地址和凭据已被接受，因为对方是先认证、再拒绝模型名。

网关协议说明写明 Messages 请求要转发 anthropic-version，当前值为 2023-06-01。模型名不要手写记忆。先调用列出模型接口 GET /v1/models，从响应 data 数组的 id 原样复制。下文用占位 <MODEL_ID>，发出前必须换成你复制到的 id。

先在当前 shell 设置基址和 Key，不要把 Key 写进仓库，也不要给 curl 加 -v，避免详细日志打出凭据。下面先验证 Key，再发一条带模型 id 的最小 Messages 请求。状态码用 -o 写入临时文件后单独打印，不和响应体拼在一起交给解析器。临时文件用 trap 在退出时删除。

export ANTHROPIC_BASE_URL="https://api.anthropic.com"

export ANTHROPIC_API_KEY="换成你自己的 Key"

resp_file=$(mktemp)

trap 'rm -f "$resp_file"' EXIT

code=$(curl -sS -o "$resp_file" -w '%{http_code}' -H "x-api-key: ${ANTHROPIC_API_KEY}" -H "anthropic-version: 2023-06-01" "${ANTHROPIC_BASE_URL}/v1/models")

printf '%s\n' "$code"

状态码是 200 后，打开 $resp_file 复制一个 id，再发 Messages。把下一行的占位换成那个 id，变量 MODEL_ID 会用在请求体里，不要在 -d 里再写死另一个模型名。

MODEL_ID='<MODEL_ID>'

payload=$(printf '{"model":"%s","max_tokens":1,"messages":[{"role":"user","content":"."}]}' "$MODEL_ID")

code=$(curl -sS -o "$resp_file" -w '%{http_code}' -X POST "${ANTHROPIC_BASE_URL}/v1/messages" -H "x-api-key: ${ANTHROPIC_API_KEY}" -H "anthropic-version: 2023-06-01" -H "content-type: application/json" -d "$payload")

printf '%s\n' "$code"

网关要求 Bearer 时，把请求头 x-api-key: ${ANTHROPIC_API_KEY} 换成 Authorization: Bearer ${ANTHROPIC_AUTH_TOKEN}，并改用对应的环境变量。401 就换另一种头再测一次。200 且响应里能看到消息内容，才说明这条路径可用。

Windows 下不要把 Key 写在命令文本里。下面按 Windows PowerShell 5.1 的 WebException 读取错误响应；本文未在 5.1 或 7.x 上复跑。PowerShell 7 的失败对象经常不是 HttpWebResponse，不能假定同一段 catch 在 7.x 上还能读到状态码。Key 用 SecureString 输入，用完后释放。

$env:ANTHROPIC_BASE_URL = "https://api.anthropic.com"

$env:MODEL_ID = "<MODEL_ID>"

$secure = Read-Host -AsSecureString -Prompt "API key"

$ptr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure)

try { $key = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($ptr); $json = '{"model":"' + $env:MODEL_ID + '","max_tokens":1,"messages":[{"role":"user","content":"."}]}'; $bytes = [System.Text.Encoding]::UTF8.GetBytes($json); try { $resp = Invoke-WebRequest -UseBasicParsing -Method Post -Uri ($env:ANTHROPIC_BASE_URL + "/v1/messages") -Headers @{ "x-api-key" = $key; "anthropic-version" = "2023-06-01" } -ContentType "application/json" -Body $bytes; Write-Output $resp.StatusCode } catch [System.Net.WebException] { $http = $_.Exception.Response; if ($null -ne $http) { Write-Output ([int]$http.StatusCode); $reader = New-Object System.IO.StreamReader($http.GetResponseStream()); try { Write-Output $reader.ReadToEnd() } finally { $reader.Dispose() } } else { Write-Output $_.Exception.Message } } } finally { if ($ptr -ne [IntPtr]::Zero) { [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ptr) }; $key = $null; $secure.Dispose() }

列出模型把方法改成 Get，去掉 Body 和模型字段，URI 改成 $env:ANTHROPIC_BASE_URL + "/v1/models"，头仍保留 x-api-key 和 anthropic-version。先看状态码，再从正文里抄 id，然后才跑上面的 Post。

写进设置文件时不要提交 Key

shell 里的 export 只对当前终端和从它启动的程序有效，从启动台或开始菜单打开的编辑器看不到。要让 CLI 每次都走到同一基址，把变量放进用户设置 ~/.claude/settings.json 的 env。Windows 路径是 %USERPROFILE%\.claude\settings.json。同一变量若 shell 和设置文件都有，以设置文件为准。启动后用 /status 看 Anthropic base URL 和当前凭据来源。不要把 Key 放进项目里的 .claude/settings.json，那个文件会随仓库分享。项目本地文件如果用 .claude/settings.local.json，先把它加入 gitignore。

桌面应用不读 ANTHROPIC_BASE_URL，也不读这份 settings.json。网关连接说明写明：桌面走它自己的第三方推理配置，可以由管理员下发，或在开发者菜单里填写基址。VS Code 扩展要写在编辑器用户设置的 claudeCode.environmentVariables 里，只改 ~/.claude/settings.json 不够，因为扩展会在启动前先检查自己的凭据。

旧教程里这三处已经过时

对照过高级设置和快速上手之后，下面三句不要再照做。

不要为了原生安装先去装 Node.js 18。原生脚本不需要 Node.js。只有 npm 这条路才看 Node.js 版本，而且现行要求是 22 或更新。
不要用 sudo npm install -g。权限报错时按排错页处理安装目录，而不是把全局安装提升成 root。
装完不要去跑旧文里的 claude config 当作必做步骤。现行顺序是新开终端、claude --version、claude doctor，然后运行 claude 按浏览器登录。

截至 2026-10-21，本文命令、账号门槛和通道差异都来自当天能打开的官方页面。下面这些没有写成确定结论：当前最新版本号；任何价格、额度或限速数字；Bedrock、Google Cloud Agent Platform、Microsoft Foundry 的点击步骤；桌面应用自己的更新节奏；支持国家名单上的某一国是否可用。文档示例版本 2.1.211 只演示版本命令的输出样子，2.1.89 只演示锁定版本，以及带分离签名的 manifest 从该版本起提供。不要把它们当成最新版。

常见问题

官网下载页为什么没有终端安装命令？

官方下载页先给 macOS、Windows 和 Linux 桌面入口。终端版不在那个安装包里，要在终端执行 claude.ai 上的官方安装脚本，装完新开终端再查版本。

执行 claude 提示 command not found 怎么办？

先确认不是只装了桌面应用或 VS Code 扩展。原生程序在 macOS 与 Linux 的 ~/.local/bin/claude，或 Windows 用户目录下的 .local\bin\claude.exe。目录不在 PATH 时，按对应 shell 补上后重新打开终端，再跑 claude --version。

免费账号能用 Claude Code 吗？

不能。免费 claude.ai 计划不含 Claude Code。CLI 需要 Pro、Max、Team、Enterprise 或 Console；桌面里的 Code 标签需要付费订阅，点进去若要求升级，就是还没有这份权益。

VS Code 已经装了扩展，为什么终端里还是没有 claude？

扩展只在自己的目录里放了一份私有 CLI，供侧边栏使用，不会写入系统 PATH。JetBrains 插件则相反，它要求 PATH 上已经有 claude。需要终端命令时，单独跑官方安装脚本。

latest 和 stable 怎么选？

原生安装默认是 latest，发布后就会收到。stable 通常大约滞后一周，并跳过有严重回归的版本。Homebrew 用 cask 名区分：claude-code 是 stable，claude-code@latest 是 latest。Homebrew、WinGet、apt、dnf、apk 默认都不会像原生安装那样自动更新。

参考资料

Quickstart - Claude Code Docs（code.claude.com）
Advanced setup - Claude Code Docs（code.claude.com）
Get started with the desktop app - Claude Code Docs（code.claude.com）
Install Claude Desktop（support.claude.com）
Use Claude Code in VS Code（code.claude.com）
JetBrains IDEs - Claude Code Docs（code.claude.com）
Troubleshoot installation and login - Claude Code Docs（code.claude.com）
Authentication - Claude Code Docs（code.claude.com）
Environment variables - Claude Code Docs（code.claude.com）
Connect Claude Code to an LLM gateway（code.claude.com）
LLM gateway protocol - Claude Code Docs（code.claude.com）
List Models - Claude API Reference（platform.claude.com）