Claude Code 指南第 10 章参考

排错常见报错与怎么查

连不上、报 401、突然变慢、回答变笨、命令卡住。按现象查,大多数问题五分钟内能定位。

更新于 2026年10月17日 · 依据 Claude Code 2.1.301 官方文档核对 · AGI Dawn 编辑部 · 审定 kk

全部章节
本页

先跑这三条

bash
claude doctor          # 检查安装、版本与配置文件
claude auth status     # 看当前用的是哪种凭据
claude -p "ping"       # 最小请求,确认链路通不通

claude -p 能通,说明接入没有问题,问题出在会话或项目本身。

按状态码

报错原因怎么办
401Key 无效或已停用、这把 Key 的额度用完或已过期,或同时设置了 ANTHROPIC_API_KEY到控制台检查 Key 状态与额度;unset ANTHROPIC_API_KEY;用 echo ${ANTHROPIC_AUTH_TOKEN:0:8} 确认变量已生效(只显示前 8 位,避免泄露)
403账户余额不足、这把 Key 剩余额度不够本次请求;或请求的模型不在这把 Key 允许的范围、IP 不在白名单,或账户被停用先看返回的 message:额度问题就充值、使用兑换码或调高这把 Key 的额度,会话不会丢;模型或 IP 不在允许范围就到控制台调整这把 Key 的设置;账户被停用请联系商务
404模型名不存在用 模型页 里的模型 ID,或在 /model 里选
429请求太频繁,或上游繁忙等几十秒重试;持续出现请联系商务
5xx、overloaded上游临时异常重试;Claude Code 默认会自动重试几次

按现象

启动后要求登录官方账号

这个终端没有读到 ANTHROPIC_AUTH_TOKEN。常见原因是写进 ~/.zshrc 后没有重开终端,或者 IDE 内置终端没有继承环境变量。用 claude auth status 确认;想退出之前登录的官方账号,在会话里输入 /logout 或执行 claude auth logout。

改了环境变量不生效

写进 ~/.zshrc 后要执行 source ~/.zshrc 或重开终端;Windows 写入用户环境变量后要重开 PowerShell。也可以改用 ~/.claude/settings.json 的 env 字段,不依赖 shell。

公司网络连不上

需要走代理时设置 HTTPS_PROXY。代理会拦截 HTTPS 的,先看根证书:Claude Code 默认信任系统证书库,原生安装一定会读,npm 安装要 Node 22.15 及以上才会读。公司根证书已装进系统证书库,就不用额外配置;没装进去,或 Node 版本更低,用 NODE_EXTRA_CA_CERTS 指向根证书文件。

auto 模式提示服务器没有返回安全判定

经 ANTHROPIC_BASE_URL 接入时,服务端审核有时拿不到结果。设置 CLAUDE_CODE_AUTO_MODE_SERVER=0,让 Claude Code 自己另发分类器请求(会额外消耗少量 tokens,计入账单),见 权限模式。

越用越慢、越来越笨

上下文太长了。用 /context 看上下文占了多少,再 /compact 压缩或 /clear 重开,见 日常工作流。

它反复做不对同一件事

换个说法不如换个方法。先进计划模式让它把理解说出来;或者开一个新会话,交给更强的模型做这一步,见 成本与模型选择。

命令卡住不动

多半是它启动了一个不会自己退出的进程,比如开发服务器、watch 模式、等待输入的命令。按 Esc 打断,告诉它改用后台方式运行或加超时。

改动被覆盖或消失

两个会话在同一个目录里改了同一批文件。用 git worktree 隔开,见 子代理与并行;提交过的内容可以用 git reflog 找回。

MCP 工具不出现

输入 /mcp 看服务器状态。本地服务器多半是启动命令或依赖有问题,先在终端里手工运行那条命令看报错,见 MCP 与工具。

Hook 不生效或误拦

输入 /hooks 查看已加载的 Hook 及来源;用一段示例 JSON 手工喂给脚本,看退出码,见 Hooks 与自动化。

还是查不出来

  • 加 --debug 启动,或在会话里输入 /debug。调试日志不打印在终端里,而是写到 ~/.claude/debug/<session-id>.txt,也可以用 --debug-file <路径> 指定位置。Hook 的匹配与退出码、MCP 服务器的报错输出、证书文件有没有加载,都能在日志里查到。
  • 在控制台「使用日志」里找到对应时间的请求,看状态码与错误信息。
  • 把现象、复现步骤与 claude --version 的输出发给你的专属商务,或写信到 [email protected]。