Codex 常见错误对照

先按这个顺序排查

修改任何配置前，请先备份文件。
CLI 用户备份 ~/.codex/config.toml 和 ~/.codex/auth.json；如果使用 CC Switch，也建议先复制保存这两个文件。这样配置出错或历史会话异常时，可以恢复原来的状态。

确认 API Base URL、API Key 和模型名正确。

确认当前使用方式：安装器、CLI、Harness 或 CC Switch。

改完配置后完全退出 Codex，再重新打开。

提问时提供系统、步骤、错误关键词和截图，并遮住 Key。

历史会话丢失

为什么配置 CC Switch 后历史会话看不到了？通常不是历史记录真的被删除，而是 CC Switch 修改了 ~/.codex/config.toml 中的 provider 配置。Codex 会根据 provider / model provider 读取对应的会话和运行配置，配置节名称改变后，原来的历史会话可能暂时不显示。

需要恢复哪些配置？把 config.toml 中下面几项恢复为原来使用的配置：model_provider、[model_providers.*] 的节名称、name。这三处的 provider 名称必须保持一致。

恢复 config.toml 配置示例 — 将 config.toml 中的 provider 配置恢复为原来的内容，点击图片可放大查看。

model_provider = "custom"
[model_providers.custom]
name = "custom"

完全退出 Codex 和 CC Switch，不要只关闭当前窗口。

打开 ~/.codex/config.toml，将 provider 名称、配置节名称和 name 恢复一致；如果之前有备份，优先直接恢复备份文件。

保存文件后重新启动 Codex，检查原来的会话是否恢复显示。

确认历史恢复后，再重新打开 CC Switch；不要在两个工具之间反复切换并覆盖配置。

如果没有备份文件，请不要删除现有配置。先把当前 config.toml 复制一份，再联系售后，根据原来的 provider 名称逐项恢复。

503 Service Unavailable

先确认当前实际调用的模型登录官网 https://ai.aiyq.cloud/home，进入「请求与用量」页面，在请求明细中查看模型名称。重点确认失败请求对应的模型是否为 luna。

因稳定性问题，当前 luna 模型已经禁用。如果 Codex 窗口里选择的是 sol，但官网请求记录显示实际调用的是 luna，通常有以下两种情况。

情况一：历史窗口仍使用 luna

这个窗口以前使用过 luna，后来才切换到当前站点的 API。即使界面上已经选择 sol，旧窗口的上下文或模型设置可能没有真正更新，导致请求仍然发送到 luna。

请保留当前任务的上下文，点击回复下方的「在新窗口中继续」按钮，将任务带到新窗口，再在新窗口发送消息。新窗口会重新读取当前配置和模型设置。

情况二：调用的 Skills 使用 luna

如果确认不是历史窗口问题，请让 Codex 排查刚刚调用了哪些 Skills，并检查这些 Skills 的配置或说明中是否指定了 luna 模型。

如果某个 Skill 明确调用 luna，请将其改为当前可用的其他模型（例如 gpt-5.6-sol），保存后重新执行任务。修改后再次到官网「请求与用量」确认实际调用模型不再是 luna。

认证与地址

401 Unauthorized / 未授权Key 错误、不完整、过期，或 URL 与 Key 不属于同一服务。重新复制 Key，去掉空格换行；Base URL 使用 https://ai.aiyq.cloud。

403 Forbidden / 没有权限检查余额、订阅分组和模型权限，换成当前账号有权限的模型。

404 Not FoundBase URL 填错或手动追加路径。不要添加 /v1/models、/responses 或 /chat/completions。

Invalid API key确认使用的是完整 Key，不是名称、掩码或兑换码；CLI 检查 auth.json，Harness 检查 credentials，CC Switch 检查供应商卡片。

模型与上下文

model not found / 模型不存在模型 ID 拼写、大小写或分组不匹配。CC Switch 点击「获取模型」；CLI / Harness 检查 model 或 models[].id。

stream disconnected before completion先新建会话、缩短上下文并重试；检查上下文窗口、maxTokens 和网络稳定性。

context length exceeded / 上下文过长减少粘贴内容、拆分任务或新建会话，改用上下文窗口更大的可用模型。

返回空内容或不回复检查模型与协议是否匹配，关闭不需要的路由转换，重启后用短问题测试。

网络与接口

Connection refused / ECONNREFUSED检查本地服务或 CC Switch 供应商是否已启用；不需要本地路由时不要额外启动。

timeout / ETIMEDOUT检查网络、代理和 API 地址，先发送短请求，不要连续重复提交长任务。

SSL / TLS 错误检查系统时间、代理和 HTTPS 地址，不要改成 HTTP。

获取模型失败先检查 Key 和 URL；若服务不支持模型列表接口，手动填写已确认可用的模型。

本地环境

node: command not found安装 Node.js；macOS 可执行 brew install node，然后重启终端。

npm: command not found重启终端并重新执行 npm -v，确认 PATH 已生效。

codex: command not found执行 npm install -g @openai/codex，并检查 npm 全局 bin 是否在 PATH 中。

配置文件找不到CLI 使用 ~/.codex/auth.json 和 ~/.codex/config.toml；Harness 使用 ~/.dsh。

格式与生效

TOML / YAML parse error检查引号、缩进、冒号和括号；YAML 不要使用 Tab，TOML 配置节和 provider 要一致。

修改后仍使用旧配置确认启用了正确供应商、保存到了正确路径，并完全退出所有 Codex 进程后重开。

model_provider 不一致model_provider = "yunqiao" 必须对应 [model_providers.yunqiao]。

Responses / Chat Completions 冲突按服务商要求选择协议；CC Switch 当前云桥API配置选择 Responses（原生），不需额外协议转换。

仍无法解决

请在 QQ 群或微信群提供：系统、使用方式、执行步骤、完整错误文本、截图和模型名。务必遮住 API Key、兑换码和个人信息。