𝐗𝐀𝐈

Claude Code Manual

排错与更新

遇到问题先运行 claude doctor，再对照下面的常见情况排查。实在解决不了，把完整的报错信息交给 AI 分析。

先运行自检

claude doctor

它会检查安装方式、版本、配置文件和依赖，并指出问题所在。

找不到 claude 命令

报错类似 command not found: claude 或 'claude' 不是内部或外部命令，说明安装目录不在 PATH 里。

  1. 先关掉终端，重新打开。
  2. 还不行，检查原生安装目录 ~/.local/bin 是否在 PATH 中。

macOS（zsh）：

echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

没有输出就加进去：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Linux 默认的 bash 写入 ~/.bashrc。

Windows（PowerShell）：

$env:PATH -split ';' | Select-String '\.local\\bin'

没有输出就加进用户 PATH，然后重开终端：

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

安装命令报错

看到的报错原因和解决
irm is not recognized / 'irm' 不是内部或外部命令在 CMD 里运行了 PowerShell 命令，换用 CMD 的安装命令或打开 PowerShell
The token '&&' is not a valid statement separator在 PowerShell 里运行了 CMD 命令，换用 PowerShell 的安装命令
syntax error near unexpected token '<'下载到的是网页而不是脚本，通常是网络问题
Failed to fetch version、连接超时无法访问下载服务器，检查网络和代理，或改用 npm 加镜像安装
EACCES: permission denied安装目录权限不对，不要用 sudo 硬装，按 claude doctor 的提示修复

登录与 401

明明设置了 Key，还是要求浏览器登录？ 说明 Claude Code 没读到 ANTHROPIC_AUTH_TOKEN。确认重开过终端，或者改用 settings.json 的 env 配置，见凭证与接入 XAI Router。

报 401、认证失败？

  • Key 复制错了：多了空格、少了字符。
  • ANTHROPIC_BASE_URL 写错了，应为 https://api.xairouter.com，不要加 /v1。
  • 有残留的旧变量。ANTHROPIC_AUTH_TOKEN 优先于 ANTHROPIC_API_KEY，检查两者，删掉不用的那个。

用 /status 查看当前实际生效的登录方式。

报 429、额度不足？ 账户额度用完或请求过于频繁，到账户后台查看。

网络和代理

  • 需要通过代理上网时，设置 HTTPS_PROXY（必要时加 HTTP_PROXY、NO_PROXY）。
  • 公司代理使用自签证书时，设置 NODE_EXTRA_CA_CERTS 指向证书文件，否则会报 TLS 或证书错误。
  • 访问 Anthropic 官方服务不稳定时，可以设置 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1，关闭自动更新、遥测等非必要请求，之后改为手动更新。

卡顿、占用高

  • 长对话用 /compact 压缩，换任务时用 /clear。
  • 会话卡住时按 Ctrl + C 退出，再用 claude --continue 接着之前的对话。
  • 怀疑是插件、MCP 或 Hooks 引起的问题，用 claude --safe-mode 启动，它会暂时关闭所有自定义扩展，方便判断。
  • WSL 中把项目放在 Linux 的家目录（/home/...）下，不要放在 /mnt/c/...，搜索文件会快很多。

更新

原生安装默认在后台自动更新，下次启动时生效。手动更新：

claude update

Homebrew、WinGet 安装的不会自动更新，分别用 brew upgrade claude-code、winget upgrade Anthropic.ClaudeCode。npm 安装的用 npm install -g @anthropic-ai/claude-code@latest。

在 settings.json 的 env 中设置 "DISABLE_AUTOUPDATER": "1" 可以关闭后台自动更新，claude update 仍然可用。

仍然解决不了

把这些信息整理好，交给 AI 或发给客服：

  • 操作系统和终端类型（PowerShell、CMD、macOS 终端、WSL）；
  • claude --version 的输出；
  • claude doctor 的输出；
  • 完整的报错信息（记得先删掉其中的 Key）。
上一章 日常工作流