排错常见报错与怎么查
连不上、报 401、突然变慢、回答变笨、命令卡住。按现象查,大多数问题五分钟内能定位。
全部章节
本页
先跑这三条
claude doctor # 检查安装、版本与配置文件
claude auth status # 看当前用的是哪种凭据
claude -p "ping" # 最小请求,确认链路通不通claude -p 能通,说明接入没有问题,问题出在会话或项目本身。
按状态码
| 报错 | 原因 | 怎么办 |
|---|---|---|
| 401 | Key 无效或已停用、这把 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]。