疑难解答

汇总 Claude Code、Codex CLI、OpenClaw 以及各类第三方客户端在接入过程中的高频问题与报错处理方案。按大类分页维护，点击进入对应分类：

• 请求错误类问题 — 400 / 413 / 429 / 500 / 上下文超限
• Claude Code 专项问题 — 首次启动、401 / 403、令牌失效、WebFetch、上下文档位
• Codex CLI 专项问题 — Base URL、配置文件、Reconnecting、图片输入
• 外接与兼容类问题 — 403 排查、User-Agent、Base URL、IDE 外接
• OpenClaw 专项问题 — 安装、provider 配置、飞书渠道
• 网络与连接问题 — 连接超时、备用域名、代理工具配置
• 进阶配置与省 Token — 减少非必要流量、CLAUDE.md、常用命令速查

排查前先做两件事

1. 确认是不是普遍问题：先看群里有没有大面积反馈。如果没人反馈，基本可以判断是本机配置或网络问题。
2. 确认余额和令牌状态：前往 控制台 查看令牌是否有效、额度是否充足。很多「报错」本质上是额度耗尽或令牌过期。

通用排障清单

不确定问题属于哪一类时，按这个顺序过一遍，能解决大部分情况：

1. 确认令牌分组与所用模型匹配（Claude 模型用 Claude 分组，GPT 模型用 Codex 分组）
2. 确认 Base URL 写法正确：Claude 类接入不带 /v1，Codex / OpenAI 兼容类接入带 /v1
3. 检查系统环境变量是否残留了旧服务的配置（Windows：Win + R → sysdm.cpl；macOS / Linux：查看 ~/.zshrc 或 ~/.bashrc）
4. 检查 ~/.claude.json 是否有官网 OAuth 登录残留（执行 claude auth logout 清除）
5. 用 cc-switch 重新写入一次配置，然后完全关闭终端窗口再打开（不是新建标签页）
6. 换个网络环境再试一次（详见网络与连接问题）

走完还是没解决，按售后与反馈里的三要素进群或提工单，别只说「用不了」。