主题
报错与踩坑汇总
记录使用 Claude Code 过程中遇到的常见问题，部分条目附有详细的根因分析与修复步骤。
Claude Code
| 编号 | 现象 | 根因 |
|---|---|---|
| EE-11 | 401 / Invalid API Key | 中转 API 的 ANTHROPIC_BASE_URL 未正确配置，请求打到官方端点 |
| EE-12 | context window 超限，对话被截断 | 单次会话积累 token 过多，未及时 /compact 或新开会话 |
| EE-01 | [EE-01] 请求返回 400，与内容无关(./errors/cc-400-experimental-betas) | CC 附加了实验性 Beta 请求头，中转服务不支持 |
| EE-02 | [EE-02] 401 无效令牌（sk 开头令牌）(./errors/cc-401-ide-mcp-conflict) | IDE 插件或 MCP 服务器覆盖了 settings.json 中的 apiKey / baseURL |
| EE-13 | 403 / Missing API Key | 配置冲突或 Claude Code 配置文件被意外修改，推荐用 CC Switch 重新写入 |
| EE-03 | [EE-03] API Error (Connection error.)(./errors/cc-connection-error) | 本地到服务器链路不通，代理节点失效或网络路由异常 |
| EE-04 | [EE-04] API Error (Request timed out.)(./errors/cc-request-timed-out) | 网络延迟过高，或上下文 token 过多处理超时 |
| EE-14 | API Error 400（非内容原因） | CC 本身 bug 导致请求体格式异常，重发或 /compact 后通常恢复 |
| EE-15 | Overloaded / 500 | 官方服务过载或故障，查 status.anthropic.com 确认状态 |
| EE-16 | Command timed out after 2m 0.0s | CC 等待 shell 命令返回超时，与 API 请求无关，可手动执行对应命令 |
| EE-17 | API Error: response exceeded the 32000 | 单次回复超出默认输出 token 上限，设置 CLAUDE_CODE_MAX_OUTPUT_TOKENS=32000 解决 |
| EE-05 | [EE-05] WebFetch 报错，目标网站可访问但联网功能失效(./errors/cc-webfetch-preflight-fail) | CC 在抓取前向 claude.ai 发预检请求，国内网络拦截 claude.ai 导致预检失败 |
| EE-06 | [EE-06] 429 Rate Limit Exceeded，重试无效(./errors/cc-429-rate-limit) | 额度耗尽（insufficient_quota，需充值）或短时间请求过于频繁 |
| EE-07 | [EE-07] Permission denied，文件读写被拒绝(./errors/cc-permission-denied) | 系统文件权限不足、CC Permission 设置为拒绝、或 .claudeignore 规则误匹配 |
| EE-08 | [EE-08] 401 Invalid API Key format，Key 目视正确仍报错(./errors/cc-invalid-key-format) | 从 PDF / 网页 / 截图复制 Key 时混入零宽空格、换行符等不可见字符 |
| EE-09 | [EE-09] 加入 skipAutoPermissionPrompt 后 Plan 模式无法执行(./errors/cc-023-skip-auto-permission-prompt-plan-fail) | 跳过自动权限提示相关流程后，Plan 模式执行阶段无法继续推进 |
Codex CLI
| 编号 | 现象 | 根因 |
|---|---|---|
| EE-10 | [EE-10] 粘贴或发送图片时提示"此模型不支持图片输入"(./errors/cd-model-image-input-unsupported) | 当前模型目录的 input_modalities 缺少 image |