Claude Code 装不上、请求失败、升不了级：一份完整排错手册（2026）

Claude Code 出问题几乎都能归到三件事：装不上、装上了请求失败、用得好好的升不了级。这三件事依赖三个互相独立的服务，混在一起排查会越查越乱——最典型的表现是明明环境变量配错了，却一直在反复重装。本文按这三层拆开，Is a directory、404、请求全部超时、claude update 卡死这些常见报错都给出可复制的诊断命令。

遇到下面这些现象，直接跳到对应小节：

如果还不知道自己卡在哪一层，先看第一节的 10 秒定位。

为什么要按三层拆：安装走 npm registry，请求走 API 端点，升级走官方发布源。三个服务彼此不影响，所以经常出现「装好了但请求失败」「用得好好的但升级卡住」这类看似矛盾的情况——它们本来就不是一回事。

下面每层都给独立的验证命令，都能直接复制运行。

环境为 Windows 11 + WSL2 (Ubuntu) 与原生 Linux，macOS 除路径外基本一致。

一、先花 10 秒定位：到底卡在哪一层

动手前先跑这两条，能省掉大量无效尝试：

# 1. 安装源响应情况
curl -sI -m 10 https://registry.npmjs.org/@anthropic-ai/claude-code | head -1

# 2. API 端点响应情况
curl -sI -m 10 https://api.anthropic.com/v1/messages | head -1

结果直接决定你该看哪一节：

二、安装：两种方式，选错了后面很痛苦

Claude Code 有两种安装形态，区别不只是命令不同，后续的升级方式完全不一样。

2.1 npm 安装

npm install -g @anthropic-ai/claude-code

官方源响应慢时换国内镜像：

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

2.2 native 安装（推荐）

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

装完后的结构：

~/.local/bin/claude                    # 软链
~/.local/share/claude/versions/<版本>   # 实际二进制

推荐 native 的三个理由：

一是不依赖 Node 环境。npm 版需要本机有可用的 Node，版本过低或全局目录权限不对都会出问题，而这类问题的报错信息往往指向别处，很难一眼看出根因。

二是多版本共存。native 版每个版本单独占一个目录，切换只是改一个软链，升级失败可以立刻切回去。

三是启动更快，省掉了 Node 的启动开销。

代价是它的自动升级依赖官方发布源，响应不稳定时会卡住。第六节给出用 npm 镜像源手工升级的方法，补上这个短板。

2.3 确认自己装的是哪种

which claude
ls -la $(which claude)

输出指向 ~/.local/share/claude/versions/... 就是 native 版；指向 node_modules 就是 npm 版。

三、验证安装

claude --version

能输出版本号（例如 2.1.238），说明二进制本身没问题，后面的问题都在网络或配置层面。

四、配置：用环境变量指定 API 端点

Claude Code 支持通过两个官方环境变量指定请求地址与身份，这是产品内置的配置能力：

export ANTHROPIC_BASE_URL=https://你的网关地址
export ANTHROPIC_AUTH_TOKEN=你的密钥

4.1 临时生效（当前终端）

export ANTHROPIC_BASE_URL=https://your-gateway.example.com
export ANTHROPIC_AUTH_TOKEN=sk-xxxxxxxx
claude

关掉窗口就没了，适合临时测试不同的网关地址。

优先级有个坑：命令行里 export 的值会覆盖 shell 配置文件里的值。所以如果你改了 .bashrc 但不生效，先检查当前终端是不是早就 export 过一个旧值——这时候 source ~/.bashrc 也救不回来，得开个新终端或手动重新 export。

4.2 持久化（推荐）

# bash
echo 'export ANTHROPIC_BASE_URL=https://your-gateway.example.com' >> ~/.bashrc
echo 'export ANTHROPIC_AUTH_TOKEN=sk-xxxxxxxx' >> ~/.bashrc
source ~/.bashrc

# zsh
echo 'export ANTHROPIC_BASE_URL=https://your-gateway.example.com' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN=sk-xxxxxxxx' >> ~/.zshrc
source ~/.zshrc

4.3 验证端点是否真的通了

别直接开 claude 试，先用 curl 单独验证，报错信息清楚得多：

curl -sS https://your-gateway.example.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-xxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-sonnet-5","max_tokens":32,
       "messages":[{"role":"user","content":"只回复两个字：通了"}]}'

返回 JSON 且 content 里有文本，这条链路就是通的。

4.4 注意 base_url 的路径规则

这是最容易出错的一处。 多数客户端会自己补 /v1/messages，所以：

• 网关地址填到域名或 /v1 为止，不要把 /v1/messages 也写进去
• 写重了会变成 /v1/messages/v1/messages，返回 404

这个 404 特别有迷惑性，因为密钥和网络都是好的，看起来哪儿都对。我把完整的诊断步骤单独写过一篇排查记录，里面有逐段拆 URL 的方法。

五、第一次运行

cd 你的项目目录
claude

首次进入会要求信任当前目录——这是安全设计，Claude Code 只在你明确信任的目录下工作。

启动后它会读取当前目录的 CLAUDE.md（如果有）作为项目上下文。这个文件是纯 Markdown，用来写项目约定、目录结构、踩过的坑。它每次会话开始都会被加载，所以别写太长。

常用命令：

/help        # 查看全部命令
/init        # 生成 CLAUDE.md，新项目第一件事
/clear       # 清空当前对话上下文
/status      # 查看当前模型与连接状态
/cost        # 查看当前会话消耗

六、升级：自动升级卡住时怎么办

这一节网上资料比较少，但踩的人不少。

6.1 现象

claude update
# 或
claude install

长时间无响应最后超时。原因是这两条命令走官方发布源，网络条件不佳时容易卡住。

6.2 解法：从 npm 镜像源取同一份二进制

关键点是——npm 上的 @anthropic-ai/claude-code-linux-x64 包里就是同一个二进制文件，而 npmmirror 是国内常用镜像源，响应稳定。所以可以手工替换：

# 查最新版本号
curl -s https://registry.npmmirror.com/@anthropic-ai/claude-code/latest \
  | grep -o '"version":"[^"]*"' | head -1

V=2.1.238          # 换成上面查到的版本号，别照抄
cd "$(mktemp -d)"
curl -sSL -o p.tgz \
  "https://registry.npmmirror.com/@anthropic-ai/claude-code-linux-x64/-/claude-code-linux-x64-$V.tgz"
tar xzf p.tgz      # 二进制在 package/claude

选包提示：glibc 系统（Ubuntu、Debian、CentOS）用 linux-x64，别选 -musl（那是 Alpine 用的）。

6.3 安装到版本目录并切换软链

D=~/.local/share/claude/versions/$V
install -Dm755 package/claude "$D/claude"

# 先确认新版本能跑，再切软链
"$D/claude" --version

# 确认输出正确后再执行这一步
ln -sfn "$D/claude" ~/.local/bin/claude

6.4 ⚠️ 一个会让你卡很久的坑

两种目录布局并存，装之前必须先确认手上这个版本是哪种：

• 早期版本：versions/<版本> 本身就是那个 ELF 二进制文件
• 较新版本（实测 2.1.219 之后）：versions/<版本>/ 是目录，二进制在 versions/<版本>/claude

一条命令判断：

V=2.1.238
ls -la ~/.local/share/claude/versions/$V
# 输出是文件 → 早期布局；是目录且里面有 claude → 新布局

如果按早期布局的习惯把软链指向目录，会得到这个报错：

/home/用户名/.local/bin/claude: Is a directory

排查第一步永远是看软链指向哪儿：

ls -la ~/.local/bin/claude

软链必须指向二进制文件本身，不能指向目录。 回滚到老版本时同理——早期版本指到 versions/<版本>，新版本指到 versions/<版本>/claude，两者不能混。这个报错的完整成因和几种变体我整理在这篇。

正确状态长这样：

$ ls -la ~/.local/bin/claude
lrwxrwxrwx ... /home/你的用户名/.local/bin/claude -> /home/你的用户名/.local/share/claude/versions/2.1.233/claude

6.5 升级失败不会失去可用版本

老版本仍留在 versions/ 下，随时切回去：

ls ~/.local/share/claude/versions/     # 看有哪些版本
ln -sfn ~/.local/share/claude/versions/<老版本>/claude ~/.local/bin/claude

另外，改软链不影响已经在运行的会话，需要重启 Claude Code 才生效。

七、常见错误排查

7.1 Is a directory

软链指到了版本目录而不是二进制。见 6.4。

7.2 请求全部超时，但 curl 直连端点是通的

先检查 shell 里有没有残留的网络相关环境变量。这类变量一旦指向一个当前环境里不存在的地址，所有请求都会先撞一次超时才失败——现象就是「什么都慢、什么都失败」，但单独用 curl 测端点却是好的。

env | grep -iE "proxy|PROXY"        # 看有没有

如果有，且你并不需要它们：

unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY
claude --version

7.3 WSL 里要特别注意的一点

WSL 和 Windows 是两套独立的网络栈。.bashrc 里写的 127.0.0.1:某端口，在 WSL 里指的是 WSL 自己的回环地址，不是 Windows 侧的同名端口——如果那个端口只在 Windows 上监听，WSL 里就是连不通的。

curl -sI --max-time 3 http://127.0.0.1:端口号 || echo "该端口在 WSL 内不可用"

结论：WSL 里跑的命令通常直接走默认网络即可，配了不可用的地址反而让每个请求都先超时一轮。

7.4 401 / 403

密钥错误或已失效。用 4.3 节的 curl 单独验证，把客户端因素排除掉。

7.5 404

ANTHROPIC_BASE_URL 里重复写了 /v1/messages。见 4.4。

7.6 temperature is deprecated for this model

Claude 5 家族等新模型已弃用 temperature 参数，请求里带上会直接 400。自己写脚本调用时去掉即可。

八、命令速查

claude --version                         # 查版本
claude                                   # 在当前目录启动
claude --help                            # 全部参数
which claude && ls -la $(which claude)   # 确认安装方式与软链指向
env | grep -i proxy                      # 排查残留的网络环境变量
ls ~/.local/share/claude/versions/       # 查看已安装的版本

九、关于接入方式的一点说明

前面第四节留了个口子没展开：ANTHROPIC_BASE_URL 该填什么。

这取决于你怎么接入。用官方订阅就填官方地址；如果因为支付方式等原因走第三方网关，就填对方给的地址——客户端完全一样，都是官方原生的 Claude Code CLI，区别只在这两个环境变量。这也意味着换回来的成本是零，改两行配置的事。

我自己用的是 Code2AI（code2ai.codes），选它主要是两个原因：控制台能实时看到 5 小时 / 7 天双窗口的已用与剩余额度和逐条请求日志（用量不可查的话，配额优化根本无从下手），以及按月付费不按 token 计价。各档位价格在定价页上有完整对照。

FAQ

Q：npm 版和 native 版，已经装了一个还能换吗？

能。先 npm uninstall -g @anthropic-ai/claude-code 卸掉旧的，再按 2.2 装 native，然后用 which claude 确认软链指向对了。两种并存时 PATH 顺序会决定实际调用哪个，容易混淆，建议只留一个。

Q：claude --version 正常但一启动就报错，怎么查？

说明二进制没问题，是配置或网络层。按顺序：先 env | grep -i anthropic 看环境变量对不对，再用 4.3 节的 curl 直接打端点，最后看 env | grep -i proxy 有没有残留变量。三步能覆盖绝大多数情况。

Q：为什么 .bashrc 改了不生效？

当前终端里已经 export 过旧值，优先级高于配置文件。开个新终端，或者手动重新 export 一次。

Q：CLAUDE.md 应该写什么？

项目约定、目录结构说明、踩过的坑、不要动的文件。它每次会话都会被完整加载，所以要精简——写成几百行的文档反而浪费上下文。用 /init 可以先生成一份基础版再手工改。

Q：怎么判断是网关的问题还是客户端的问题？

用 4.3 节那条 curl。curl 通而 claude 不通 → 客户端配置问题；curl 也不通 → 端点或密钥问题。这一步能把排查范围直接砍掉一半。

小结

三类问题对应三个位置：

最后提一个排查习惯：遇到问题先用 curl 把客户端因素排除掉。Claude Code 是交互式程序，出错提示往往被 TUI 界面吞掉或简化，而 curl 会把 HTTP 状态码和响应体原样打出来。先确认端点本身是通的，再回头看客户端配置，能省大量时间。

文中版本号只是示例，实际操作时用 6.2 节那条命令查当前最新版，别照抄。