排错手册

日常八成的故障都能归到五类里：网络、认证、权限、工具、模型。分类清楚了，排查速度会快很多。这一页按分类整理常见症状和第一步该做什么，遇到问题按图索骥。

排查心法

在开始之前，先说三条通用原则，能少走大量弯路：

• 一次只改一件事。同时改代理、切模型、改配置，成功也不知道是哪一步起了作用，失败也不知道该回滚哪个。
• 先看错误信息本身。红色文字里一般会藏关键词，不要一看到报错就慌着重启。
• 学会看日志。日志比屏幕上的信息完整得多，卡壳的时候一定要打开对应日志文件查。

先从 claude doctor 开始

任何异常先跑一次 claude doctor，它会一次性检查网络连通性、认证状态、Node 环境、配置文件权限、MCP 服务器状态等关键项。输出大致长这样：

Environment:
  claude version: 2.x.x
  node: v20.11.1
  os: win32 10.0.26200
Auth:
  method: api_key
  status: OK
Network:
  api.anthropic.com: reachable (145 ms)
  proxy: none
Config:
  ~/.claude/settings.json: OK
  project CLAUDE.md: found
MCP:
  no servers configured

任何一行显示 FAIL 或 WARN，先按对应分类往下查。绝大多数问题在 doctor 输出里就已经点了名，别急着到处翻教程和帖子。

如果 doctor 本身跑不起来，那大概率是二进制没装好或 PATH 有问题，回到第一章的安装指南重新走一遍即可。

日志文件在哪里

平台	路径
macOS / Linux	~/.claude/logs/
Windows	%APPDATA%\claude\logs\
会话对话历史	~/.claude/projects/<hash>/
MCP 服务器日志	~/.claude/logs/mcp-<name>.log

日志按天滚动，出问题时把当天那份翻出来搜关键词就行。

一、网络类

通用症状

命令挂起、超时、ECONNREFUSED、ETIMEDOUT、getaddrinfo ENOTFOUND。

• 代理没配对。国内环境十有八九是这个。检查 HTTPS_PROXY 和 HTTP_PROXY 环境变量，或者在 ~/.claude/settings.json 里配 proxy 字段。
• 证书问题。企业网络里可能被中间人证书拦截，报 unable to verify the first certificate。设置 NODE_EXTRA_CA_CERTS 指向 CA 文件。
• DNS 污染。ping api.anthropic.com 拿不到 IP。换 DNS 到 1.1.1.1 或走代理。
• 公司防火墙。企业办公网直连不到 api.anthropic.com，需要走内网代理白名单。让 IT 帮你把域名加进出站白名单，或者临时切热点排除掉这个变量。
• 代理只覆盖 http 不覆盖 https。有些老代理配置里只写了 HTTP_PROXY，Claude Code 的接口全走 https，务必两个变量都设。

二、认证类

通用症状

401 Unauthorized、403 Forbidden、invalid api key、session expired。

• API Key 过期或被撤销。去控制台重新生成，claude config set apiKey <new> 更新。
• 登录态过期。用 OAuth 登录的话跑一次 claude login，重新走浏览器授权。
• 组织切错。同时属于多个组织时，claude config get organization 看当前用的是不是想用的那个。
• Key 里混了引号。粘贴 API Key 时不小心带了首尾的引号或空格，编辑 ~/.claude/settings.json 清理干净。
• 多台电脑抢占登录态。同一个账号在多台机器切换太频繁时，某几次登录会互相踢掉。稳定用某一台就行。

三、权限类

通用症状

permission denied、被反复弹权限确认、EACCES。

• 文件系统权限不够。macOS 里 Claude 需要访问项目目录，进入系统设置里的隐私里的完整磁盘访问，勾上终端。
• 权限模式没切对。默认是 plan 或 default，写文件要按 Shift+Tab 切到 acceptEdits。
• 敏感目录被拒。默认拒绝写 ~/.ssh、.env、node_modules 等目录，需要临时放行时在 settings.json 的 permissions.allow 里加。
• 企业策略覆盖。有的公司下发了 managed-settings.json，个人 settings 里再怎么改也没用，联系 IT。
• 符号链接和目录挂载。macOS 上 Claude 拿不到 iCloud 目录里的文件是常见坑，把项目挪出 iCloud 就好。

四、工具类

通用症状

Bash 报错、Edit 找不到目标、MCP 服务连不上、Skill 没触发。

• Bash 卡在提示符。Claude 跑了个交互式命令（vim、less、ssh 等），Escape 中断，改成非交互形式。
• Edit 报字符串不唯一。要匹配的 old_string 在文件里出现多次，加更多上下文让它唯一，或者用 replace_all。
• MCP 服务启动失败。查 ~/.claude/logs/mcp-<name>.log，一般是可执行文件路径写错或依赖没装。
• Skill 没自动触发。Skill 描述里的触发词不够明显。要么手动 Skill 调用，要么改 SKILL.md 的 description 加更多关键词。
• Grep 找不到内容。默认忽略了二进制文件和 gitignore 里的目录。想全量搜时给一个精确的 path。

五、模型类

通用症状

rate limit exceeded、context length exceeded、model not found、回答质量突然下降。

• 限流。免费/付费额度用光，等窗口刷新或升级订阅。/model 换到 Haiku 撑一下。
• 上下文超限。项目文件太多一股脑塞进来。用 /clear 重开会话，或用 /compact 压缩历史。
• 模型 ID 拼错。settings.json 里 model 字段写成了老 ID，参见附录第二节的最新 ID 表。
• Fast 模式误开。以为 Fast 是别的模型，其实是 Opus 的快速输出模式，回答质量没变，但推理深度可能不同。
• 回答绕圈。模型一直在同一个思路里跑，多半是上下文里有噪音。开新会话，只保留必要文件，往往立刻好。

常见 error message 对照表

错误信息	大概率原因	第一步
ENOTFOUND api.anthropic.com	DNS 或代理	ping api.anthropic.com
401 Unauthorized	API Key 无效	claude login 或换 Key
403 Forbidden	组织/权限	检查组织 ID
429 Too Many Requests	限流	换模型或等待
context length exceeded	上下文爆了	/clear 或 /compact
EACCES: permission denied	文件系统	检查文件权限和权限模式
MCP server exited with code 1	MCP 挂了	看对应 log
Skill not found	名字写错	用 ToolSearch 列一遍

实在搞不定

复现步骤 + claude doctor 输出 + 相关日志片段，一起去官方 GitHub Issues 提 issue，或者在附录第四节里的社区渠道求助。别只贴一句 “不行”，那没人能帮上忙。

提问的时候顺手带上：操作系统和版本、Claude Code 版本号、是不是在企业网络下、是不是刚升级过。这四个信息 90% 的排错都用得上，写好一次能帮维护者省下几轮来回问答。

一些额外的经验

用久了会发现这几条经验很实用：

• 定期看官方 Release Notes。很多 bug 上一版就修好了，你还在按老办法绕，纯粹是浪费时间。
• 出现玄学问题先关代理、切网络、重开会话，这三招覆盖了大半玄学。
• 别怕重开会话。上下文越长模型越容易走神，重开一次是最便宜的止损。
• 备份 ~/.claude/settings.json，各种试错之后能一键回到干净配置。
• 把项目的 .claude 目录纳入 git，团队成员共享同一份 Skill、Command、settings，能少踩很多个体差异的坑。