Claude Code Manual
排错与更新
遇到问题先运行 claude doctor,再对照下面的常见情况排查。实在解决不了,把完整的报错信息交给 AI 分析。
先运行自检
claude doctor它会只读地检查安装方式、版本、配置文件和依赖,并指出问题所在,不会修改任何东西。进入会话后的 /doctor 范围更宽,还能在你确认后帮你修复。
找不到 claude 命令
报错类似 command not found: claude 或 'claude' 不是内部或外部命令,说明安装目录不在 PATH 里。
- 先关掉终端,重新打开。
- 还不行,检查原生安装目录
~/.local/bin是否在 PATH 中。
macOS(zsh):
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"没有输出就加进去:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrcLinux 默认的 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 加镜像安装 |
Alpine 上提示 not found | 系统没有 bash 和 curl,先运行 apk add bash curl |
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 查看当前实际生效的登录方式和 API 地址:应有 Anthropic base URL 一行显示 https://api.xairouter.com,以及 Auth token 或 API key 一行。
启动时提示同时存在两种凭证? 说明接入用的变量和之前保存的登录并存。要用 XAI Router,运行 /logout 清掉已保存的登录;要用保存的登录,就删掉变量。
设置了 ANTHROPIC_API_KEY 却被忽略,也没有提示? 这个变量需要在交互会话里批准一次,被拒绝过的 Key 不会再询问。在 /config 里打开 Use custom API key 即可。用 ANTHROPIC_AUTH_TOKEN 没有这个步骤。
把 ANTHROPIC_AUTH_TOKEN 写进了项目里的 .claude/settings.json,仍然要求登录? 项目配置里的 env 要等首次设置和信任文件夹提示之后才生效,所以会先弹出登录。把它放到 shell 或 ~/.claude/settings.json 里;也不要把 Key 放进会提交到 Git 的项目配置。
报 429、额度不足? 账户额度用完或请求过于频繁,到账户后台查看。
提示 Claude Code does not support this model,或某个新模型请求失败? 多半是 Claude Code 版本太旧。官方文档标注:Opus 5.5 需要 v2.1.280 及以上,Sonnet 5.5 需要 v2.1.284 及以上,Haiku 5.5 需要 v2.1.293 及以上,Fable 5.2 需要 v2.1.321 及以上。运行 claude update;如果用的是 stable 渠道,新模型可能要等一周左右,或者切到 latest。
报 400,提示 Extra inputs are not permitted、context_management 等未识别字段? 设置环境变量 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1,让 Claude Code 少发一些实验性字段,然后重启。
报 400,提示上下文或 token 超出限制? 先运行 /compact 压缩当前对话。可以用 /autocompact 或环境变量 CLAUDE_CODE_AUTO_COMPACT_WINDOW 把自动压缩的窗口调小。较新的版本在使用自定义 ANTHROPIC_BASE_URL 时,会对支持 1M 上下文的模型按 1M 计算;如果上游只到 200K,请运行 /autocompact 200k。
/fast 提示快速模式不可用? 官方文档说明,快速模式的可用性检查直接访问 Anthropic 官方服务,不经过 ANTHROPIC_BASE_URL,接入网关时可能显示不可用。这不影响普通请求。
一直显示 Remote Control 或语音输入不可用? 接入网关凭证后这两项本来就不可用,见凭证与接入 XAI Router。
网络和代理
- 需要通过代理上网时,设置
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 updateHomebrew、WinGet 安装的不会自动更新,分别用 brew upgrade claude-code(装的是 claude-code@latest 则升级它)、winget upgrade Anthropic.ClaudeCode;apt、dnf、apk 安装的用系统的升级命令。npm 安装的用 npm install -g @anthropic-ai/claude-code@latest。
想用更稳的版本,在 /config 里把 Auto-update channel 改为 stable,或者在 settings.json 里设置 "autoUpdatesChannel": "stable";同时设置 "minimumVersion" 为当前版本号,可以避免被降级。
在 settings.json 的 env 中设置 "DISABLE_AUTOUPDATER": "1" 可以关闭后台自动更新,claude update 仍然可用。
仍然解决不了
把这些信息整理好,交给 AI 或发给客服:
- 操作系统和终端类型(PowerShell、CMD、macOS 终端、WSL);
claude --version的输出;claude doctor的输出;- 完整的报错信息(记得先删掉其中的 Key)。