报错与踩坑汇总
记录使用 Claude Code 及相关插件过程中遇到的真实问题，每个条目均有完整的根因分析、修复步骤和预防方案。
每篇详细文档统一采用「现象 → 根因 → 修复步骤 → 预防措施」结构。
Claude Code 本体
| 编号 | 现象 | 根因 | 状态 | 解决人 |
|---|---|---|---|---|
| CC-001 | 响应极慢，像卡住 | hook 持续尝试连挂死的 worker，每次超时拖慢 CLI | ✅ 已解决 | 天程君 |
| CC-002 | 401 / Invalid API Key | 中转 API 的ANTHROPIC_BASE_URL未正确配置，请求打到官方端点 | 常见 | — |
| CC-003 | 模型返回 503 model_not_found | 所选模型在当前渠道下线或不可用 | 常见 | — |
| CC-004 | context window 超限，对话被截断 | 单次会话积累 token 过多，未及时/compact或新开会话 | 常见 | — |
| CC-005 | 首次启动即报 Unable to connect to Anthropic services | hasCompletedOnboarding字段缺失，Onboarding 探测绕过中转直连官方端点失败 | ✅ 已解决 | GordonCC |
| CC-006 | 请求返回 400，与内容无关 | CC 附加了实验性 Beta 请求头，中转服务不支持 | ✅ 已解决 | — |
| CC-007 | 401 无效令牌（sk 开头令牌） | IDE 插件或 MCP 服务器覆盖了 settings.json 中的 apiKey / baseURL | 常见 | — |
| CC-008 | 403 / Missing API Key | 配置冲突或 Claude Code 配置文件被意外修改，推荐用 CC Switch 重新写入 | 常见 | — |
| CC-009 | API Error (Connection error.) | 本地到服务器链路不通，代理节点失效或网络路由异常 | 常见 | — |
| CC-010 | API Error (Request timed out.) | 网络延迟过高（情况 A）或上下文 token 过多处理超时（情况 B） | 常见 | — |
| CC-011 | API Error 400（非内容原因） | CC 本身 bug 导致请求体格式异常，重发或/compact后通常恢复 | 常见 | — |
| CC-012 | Overloaded / 500 | 官方服务过载或故障，查 status.anthropic.com 确认状态 | 常见 | — |
| CC-013 | Command timed out after 2m 0.0s | CC 等待 shell 命令返回超时，与 API 请求无关，可手动执行对应命令 | 常见 | — |
| CC-014 | 413 请求体过大 / 400 Invalid model name | 上下文超限（413）或 Opus 并发配额不足（400） | 常见 | — |
| CC-015 | API Error: response exceeded the 32000 | 单次回复超出默认输出 token 上限，设置CLAUDE_CODE_MAX_OUTPUT_TOKENS=32000解决 | ✅ 已解决 | — |
| CC-016 | 无效令牌（曾购买过第三方服务后切换） | 旧服务遗留环境变量覆盖新配置，优先级高于配置文件 | ✅ 已解决 | — |
| CC-017 | WebFetch 报错，目标网站可访问但联网功能失效 | CC 在抓取前向 claude.ai 发预检请求，国内网络拦截 claude.ai 导致预检失败 | ✅ 已解决 | — |
| CC-018 | 登录过官网后 API Key 失效，中转服务无法使用 | OAuth 令牌写入 ~/.claude.json，优先级高于 settings.json 中的 API Key | ✅ 已解决 | 🐻 |
| CC-019 | 429 Rate Limit Exceeded，重试无效 | 额度耗尽（insufficient_quota，需充值） | 常见 | — |
| CC-020 | Permission denied，文件读写被拒绝 | 系统文件权限不足、CC Permission 设置为拒绝、或 .claudeignore 规则误匹配 | 常见 | — |
| CC-021 | 401 Invalid API Key format，Key 目视正确仍报错 | 从 PDF / 网页 / 截图复制 Key 时混入零宽空格、换行符等不可见字符 | 常见 | — |
| CC-022 | 重复创建缓存，导致单场重复收费 | 备用负载切号后二次转发携带相关请求头，误路由触发重复建缓存 | ✅ 已解决 | 花衣魔笛 |
| CC-023 | 加入skipAutoPermissionPrompt后 Plan 模式无法执行 | 跳过自动权限提示相关流程后，Plan 模式执行阶段无法继续推进 | 常见 | 寂月止水 |
claude-mem
| 编号 | 现象 | 根因 | 状态 | 解决人 |
|---|---|---|---|---|
| CM-001 | 知识库连续 4 天无产出，pending_messages 堆积 1637 条 | worker 模型通道下线（503 死循环），积压数据被误判为垃圾清空 | ✅ 已解决 | 天程君 |
| CM-002 | Claude Code 命令卡死不返回，终端无报错 | 升级后 worker 挂死，端口残留，进程假活 | ✅ 已解决 | 天程君 |