🩺 常见报错速查

先别急着重装～ 复制报错里的关键词，对照下面这张表。本文按 Maru Code 接入整理，配置步骤看 Maru Code 教程，术语看 AI 名词小词典。

🔎 先查这张表

报错 / 现象	多半是	怎么办
Invalid API Key / 401	Key 不完整、已停用或带了空白	重新复制完整 sk- 密钥，检查空格、换行和启用状态；改完重启客户端，新开对话
403	需要核对密钥权限和分组，单看状态码不能确定	看完整报错，核对 Key 是否启用、分组是否支持模型；仍失败就带脱敏信息求助
404	Base URL 路径错了	Claude Code 填 https://api.muteki.site；Codex / OpenAI 兼容客户端填 https://api.muteki.site/v1（Cherry Studio 例外：填根地址不加 /v1，否则会变成 /v1/v1）；别填具体接口
INSUFFICIENT_BALANCE / SUBSCRIPTION_NOT_FOUND / API_KEY_QUOTA_EXHAUSTED	余额或密钥分组问题	查余额、套餐与密钥分组，按后台提示处理
当前分组不支持该模型	Key 的分组和模型不对应	换对应分组的密钥，例如生图要用生图分组的 Key
Image generation is not enabled for this group	当前分组没开生图	Codex 不需要生图时，在 config.toml 的 [features] 下设 image_generation = false，见下文
模型不可用 / 没有可用账号 / Trae 等添加自定义模型报 404	模型名填错	去模型广场复制完整模型 ID 原样粘贴，大小写和横线都别改
429	请求太频繁 / 限流	稍等再试，别连续点重试
500 / 502 / 503	上游临时故障	先看 health 和群公告，稍后再试
stream disconnected before completion	Codex 上下文过长时可能断流	超过约 272k 时，按下文调整上下文与自动压缩阈值；也检查网络和站点状态
TOML 解析错误	配置文件格式不对	查重复键、引号、编码和文件后缀，见下文
Windows Codex App 一直 Reconnecting	多半是网络	打开上网工具后重试，见下文
回答很慢	思考强度高，或网络、上游状态有波动	小任务先用 low / medium，再看 health 和群公告；别反复重发长任务

health 怎么看？

打开 https://api.muteki.site/health，返回 {"status":"ok"} 表示站点正常。这不保证每个模型都正常，仍要结合完整报错和群公告判断。

🛠️ Codex 专属问题

桌面版安装、找不到命令行或更新后出问题？先看 Claude / Codex 桌面版安装指南。

TOML 解析错误

先备份，再检查用户级 ~/.codex/config.toml；Windows 是 %USERPROFILE%\.codex\config.toml。

• 文件用 UTF-8，后缀是 .toml，不是 .toml.txt。
• 引号用英文双引号 "，别用中文弯引号。
• 顶层键不能重复，已有同名键就改原值。
• 顶层配置放在 [features] 这类小节之前，别误塞到小节里。

完整接入示例看 Codex 手动配置。改完完全退出并重开 Codex，再新开对话。

Windows App 卡在 Reconnecting

多半是网络。先打开上网工具，再重试。

也可以在用户级 .codex 目录放 .env，设置本机上网工具端口；常见端口是 7890 / 7897，以自己工具的实际设置为准。具体网络设置去上网工具页看。

stream disconnected：上下文太长

如果上下文超过约 272k 后出现 stream disconnected before completion，可在用户级 config.toml 的顶层合并：

model_context_window = 272000
model_auto_compact_token_limit = 240000

这组数值要按模型调整，不是所有模型都照抄。已有同名键就修改，不要重复添加；改完重启、新开对话。

压缩会不会变笨？

压缩会丢一些细节。长任务先让它总结目标、已完成内容、关键决定和下一步，再开新对话接着做。解释见上下文压缩。

新模型没出现在菜单里

Codex Desktop 菜单可能还没更新。可以在用户级 config.toml 里把 model 改成官网已支持的新模型名，或在 CLI 指定：

codex --model 模型名

把「模型名」换成官网给出的实际名称，别照着猜。可用模型以官网模型页为准。

Work 模式用 API 报账号认证错误

改用 Codex 模式，再按 Maru Code 接入教程检查 API 配置。

当前分组没开生图

不需要生图时，在用户级 config.toml 合并：

[features]
image_generation = false

已有 [features] 就把这一项放到原小节里；已有 image_generation 就改原值。需要生图则换支持生图分组的 Key。

✅ Claude Code 专属问题

CC Switch 切了，怎么没变化？

确认供应商已启用，然后关闭旧终端，重开终端，再启动 Claude Code、新建对话。接着核对 Base URL 和 Key。

CC Switch 健康检测报 503

检测报 503 不代表不能用，先在 Claude Code 里实际发一条消息。如果实际使用也报错，再查 health、群公告和上面的速查表。

🙋 怎么求助才有人理

把下面几项一次说清楚，大家才不用来回猜～

要发什么	例子
系统	Windows / macOS / Linux，以及系统版本
工具	Codex Desktop / CLI、Claude Code、CC Switch，以及版本
完整报错	报错文字或截图，说明在哪一步出现
Base URL	例如 https://api.muteki.site/v1
脱敏的 Key	sk-abc1****wxyz
已试过什么	已重启、新开对话、检查余额等

绝不发完整 Key

截图、配置和日志也先检查一遍，遮住完整密钥再发。已经泄露就去后台删掉重建。

回到接入教程 查名词 官方常见问题 人工客服