Codex 中转站故障手册

🔴 断流 · 请求体

💥

stream disconnected before completion

请求体过大，中转站流式接口撑不住半途断流

流式中断▼

错误信息

stream disconnected before completion:
error sending request for url
(http://127.0.0.1:15721/v1/responses)

根本原因

项目中 node_modules/、dist/、__pycache__/ 未排除 → Codex 将 2000+ 文件（可达 40MB） 全打入请求体 → 中转站撑不住断流。其他项目正常是因为文件少或已有 .codexignore。

立即修复

在出问题的项目根目录创建 .codexignore
或运行一键初始化脚本自动生成
关闭 Codex 该项目会话，重新打开

powershell -File C:\Users\<用户名>\.codex\new-project-init.ps1

✓ 验证：文件数应从 2000+ 降至 <100，请求体从 40MB 降至 <500KB

🧠

xhigh 推理档位放大请求体

xhigh 触发 extended thinking，prompt 膨胀叠加大 context 必然超限

配置问题▼

根本原因

model_reasoning_effort = "xhigh" 触发 extended thinking 模式，系统 prompt 更长，叠加大文件扫描必然触发中转站限制。

修复（编辑 config.toml）

# C:\Users\<用户名>\.codex\config.toml
# 改前
model_reasoning_effort = "xhigh"
# 改后
model_reasoning_effort = "high"

⚠️ xhigh 仅在明确需要最高推理时使用，日常任务 high 足够且更快

🔑 认证 · 配额

🔐

401 Unauthorized

API Key 无效、已过期，或粘贴时带了多余空格

认证失败▼

根本原因

cc-switch 中配置的 API Key 无效或已过期，中转站向上游验证失败后返回 401。中转站 Key 有效期可能较短。

解决步骤

打开 cc-switch → 供应商设置
重新粘贴有效 API Key（注意无前后空格）
点保存，等待热切换完成（约 3 秒）
在 cc-switch 日志确认「Live 配置已接管」

ℹ️ 中转站 Key 需从服务商渠道定期更新

💳

402 Payment Required

免费中转站每日 / 月度配额耗尽

余额不足▼

根本原因

中转站的每日/月度配额已用完，无法继续转发请求。

解决步骤

等待配额重置（通常每日 UTC 00:00）
在 cc-switch 切换到备用供应商
重要任务绑定个人 OpenAI/Anthropic 官方 Key

⚠️ 中转站配额有限，关键项目建议准备自己的备用 Key

🌐 网关错误

🚫

501 Not Implemented

中转站不支持 /v1/responses（OpenAI Responses API）

接口不支持▼

根本原因

Codex 默认使用 /v1/responses（Responses API），但中转站只实现了旧版 /v1/chat/completions，返回 501 表示该端点未实现。这是供应商级别问题，与项目无关。

解决方案（二选一）

换供应商：在 cc-switch 切换到支持 Responses API 流式的中转站
改协议：在 config.toml 对应 provider 段改 wire_api

[model_providers.your_provider]
wire_api = "chat_completions"  # 从 responses 改为此值

ℹ️ 修改 wire_api 后需重启 Codex Desktop 生效

🌩️

502 Bad Gateway

中转站已收到请求，但上游 API 返回错误

上游错误▼

根本原因

中转站上游（OpenAI / Anthropic 官方）返回错误，中转站将其转发为 502。常见原因：上游 API 抖动、中转站后端配置失效、模型名称不被上游识别。

解决步骤

等待 2–5 分钟后重试
检查中转站社群/状态页
cc-switch 切换备用供应商临时顶替
确认 config.toml 中 model 名称拼写正确

🔌

503 Service Unavailable

中转站服务器过载或临时停机，高峰期多发

服务不可用▼

根本原因

中转站服务器过载或临时停机。公益免费站在高峰时段（UTC 14:00–22:00）尤其易触发。

解决步骤

等待 5–10 分钟后重试
cc-switch 临时切换其他供应商
避开高峰时段（UTC 14:00–22:00）使用中转站

⚠️ 公益中转站无 SLA 保证，关键任务准备多个备用供应商

⏱️

504 Gateway Timeout

上游 API 响应超时，常因 context 过大或 xhigh 推理太慢

网关超时▼

根本原因

上游 API 响应太慢，中转站等待超时。常见于 token 数过多、xhigh 推理时间过长、上游负载高。

解决步骤

精简 .codexignore 减小 context 体积
将 reasoning_effort 从 xhigh 改为 high
对话轮次过多时新开会话清空历史

🔄 cc-switch 专项

🔀

热切换供应商时会话断流

切换时 Codex 重新连接，大 context 扫描中途失败后反复恢复

cc-switch▼

日志特征

[10:22:02] Updated codex Live backup（hot switch）
[10:22:16] Updated codex Live backup（hot switch）
[10:26:17] Codex Live 配置已恢复

根本原因

热切换时 cc-switch 修改 Codex 配置文件，Codex 检测到变更重新连接，若此时有大 context 扫描进行中请求失败，cc-switch 反复尝试从备份恢复。

解决

只在 Codex 空闲状态切换供应商
切换后等日志出现「Live 配置已接管」再使用
添加 .codexignore 减少重连时扫描耗时

🔴

端口 15721 无响应 / cc-switch 未启动

本地代理服务未运行，Codex 无法连接中转站

cc-switch▼

诊断命令

netstat -ano | findstr ":15721"
# 无输出 = cc-switch 未运行

解决步骤

重启 cc-switch 桌面应用
查看系统托盘是否有 cc-switch 图标
确认设置中「启用本地代理」已勾选
端口被占用时：taskkill /PID <pid> /F 后重启

💾

每轮对话全量重传 context

disable_response_storage=true 禁用服务端缓存，每轮必传完整历史

cc-switch▼

根本原因

config.toml 中 disable_response_storage = true 禁用服务端 context 缓存，每轮请求都携带完整历史，随轮次增加越来越慢，最终断流。

建议

中转站支持 storage 则改为 false
必须保持 true 时更严格控制 context 体积
对话轮次超 20 轮主动新开会话

🗺️ 快速诊断流程

⚡ 点击选项，一步步定位问题

cc-switch 正在运行吗？（系统托盘有图标）

✓ 是，在运行

✗ 没看到

→ 先启动 cc-switch
重启桌面应用，确认托盘出现图标后再试。若端口被占：netstat -ano | findstr :15721 找 PID 后 taskkill /PID <pid> /F

错误信息中包含 "stream disconnected"？

✓ 是

✗ 不是

→ 请求体过大，执行以下命令查文件数：
Get-ChildItem <项目路径> -Recurse -File | Measure-Object

文件数 > 200 → 立即创建 .codexignore（运行 new-project-init.ps1）
文件数正常但仍断 → 改 model_reasoning_effort = "high"，或新开会话

HTTP 错误码是多少？

401

402

501

502

503 / 504

401 → API Key 失效，打开 cc-switch 供应商设置重新粘贴有效 Key

402 → 配额耗尽，等待重置（UTC 00:00）或切换备用供应商

501 → 中转站不支持 /v1/responses，换支持 Responses API 的供应商，或在 config.toml 改 wire_api = "chat_completions"

502 → 上游 API 抖动，等 2–5 分钟重试或切换备用供应商

503/504 → 中转站过载/超时，等 5–10 分钟或切换备用供应商；避开 UTC 14–22 高峰

问题发生在切换供应商后？

✓ 是，刚切换完就断了

✗ 不是

→ 热切换时机问题
确保 Codex 空闲状态再切换（无进行中对话）。切换后等 cc-switch 日志出现「Live 配置已接管」再发请求。

→ 其他情况
查看 cc-switch 日志（C:\Users\<用户名>\.cc-switch\logs\cc-switch.log）寻找具体错误行，或检查 disable_response_storage 配置。

↺ 重置流程

✅ 新项目防护清单

🛡️ 开工前全部打勾，杜绝中转站断流

项目根目录存在 .codexignore 必须

运行 powershell -File C:\Users\<用户名>\.codex\new-project-init.ps1 一键生成

node_modules/ · dist/ · __pycache__/ 已排除 必须

验证：Codex 扫描文件数应 < 200，请求体 < 500KB

config.toml 中 model_reasoning_effort = "high" 必须

文件：C:\Users\<用户名>\.codex\config.toml（非 xhigh）

Codex++ Context Meter 占用 < 40% 推荐

超过 70% 立即新开会话，避免请求体膨胀超限

供应商切换只在 Codex 空闲时进行 推荐

切换后等「Live 配置已接管」出现再发请求

cc-switch 中准备 2 个以上备用供应商 推荐

当前 Codex：备用中转站 A · Claude：备用中转站 B

设计文档 >10KB 的 .md 放入 docs/ 并加入 ignore 可选

只保留 AGENTS.md 在根目录供 Codex 读取指令