Claude Code Manual

排错与更新

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

先运行自检

claude doctor

它会只读地检查安装方式、版本、配置文件和依赖,并指出问题所在,不会修改任何东西。进入会话后的 /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 加镜像安装
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 update

Homebrew、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)。