Codex Router 工作原理 — 架构与请求流程
Codex Router 是一个位于 Codex App/CLI 与外部模型供应商之间的本地 HTTP 服务。本页解释它为什么存在、四个组成部分各做什么、请求如何流过它、以及安全边界在哪里。
为什么需要路由器
Codex App 期望 Responses API 和 Codex 形态的模型目录。Kimi 与 DeepSeek 暴露的是认证和请求细节不同的 OpenAI 兼容 Chat Completions API。路由器桥接这些契约，同时让原生 GPT 流量继续走常规 ChatGPT Codex 后端。
四个组成部分
- 生成的目录把外部模型放到 Codex
model_catalog_json中原生 GPT 模型旁边。 - 调度器按命名空间模型 ID 选择原生或外部路由——以
deepseek/、kimi-oauth/、anthropic-api/等开头的都走外部路径。 - LiteLLM 把 Responses 请求、流与工具调用翻译为各供应商的原生协议，包括 OpenAI 兼容 Chat Completions 与 Anthropic Messages。
- 凭据转发器只注入所选供应商的认证，其余全部剥除。
所有监听器都绑定 127.0.0.1，整个服务都在你的机器本地。
请求流程
Codex 把 Responses 请求发送到 4102 端口的回环路由器：
| 端口 | 监听器 | 职责 |
|---|---|---|
| 4102 | 路由器 | 接收 Codex Responses 请求，认证调用方 |
| 4100 | LiteLLM | 把 Responses 翻译为各供应商的原生协议 |
| 4101 | Kimi OAuth | 用刷新后的 OAuth bearer 转发给 Kimi |
| 4103 | API 转发器 | 用所选密钥转发给 API Key 供应商 |
对于原生 GPT 模型，路由器用放行列表中的 Codex 头与原生模型 ID 转发给 ChatGPT Codex 后端——路由器绝不会把原生请求发送给外部供应商。
对于注册表模型（例如 kimi-oauth/k3），路由器校验调用方、把网关模型加内部密钥交给 LiteLLM，LiteLLM 翻译请求并交给匹配的转发器。转发器丢弃内部密钥，只注入所选供应商凭据。流经 LiteLLM 以 Responses 事件返回。
凭据边界
| 路由 | 入站 Codex 凭据 | 上游凭据 |
|---|---|---|
| 原生 GPT | 放行并转发 | 已有 ChatGPT/Codex 认证 |
| Kimi OAuth | 丢弃 | ~/.kimi-code 的 Kimi CLI OAuth bearer |
| Kimi API | 丢弃 | Kimi Platform API Key |
| DeepSeek | 丢弃 | DeepSeek API Key |
Codex 到路由器与内部服务这两条信任边界使用两个不同的随机密钥，分别以 mode 600 或当前用户 Windows ACL 存储。外部转发器在上游请求前移除 Codex 账户、安装、attestation 与私有头。
安全模型
- 本地调用方认证。 托管 base URL 包含独立的随机能力；路由器在读取模型请求或联系任何上游前先校验它。Codex 无法给内置供应商附加路由器专用头，因此能力放在 URL 路径中。状态、迁移与支持工具会脱敏它。
- 无浏览器访问。 路由器要求 JSON 内容、拒绝浏览器来源头、绝不授予 CORS。
- 脱敏错误。 面向网络的错误有限且不含敏感信息；原始异常文本被替换。
- 无凭据泄漏。 诊断只报告存在与来源，绝不报告值。受保护文件使用 mode
600或当前用户 ACL。
传输与压缩
当前 Codex 构建会先尝试 Responses WebSocket；路由器以 HTTP 426 响应，Codex 回退到 HTTP，这是预期行为。请求体可能使用 Zstandard、gzip、deflate 或 Brotli，路由器会在检查模型 ID 前安全解压。
外部 Chat Completions 供应商无法创建 OpenAI 的不透明加密压缩载荷，因此路由器让所选外部模型生成续写摘要，并以路由器所有的 kcr1: 载荷包装。重放时把它转回普通续写消息。
哪些仍留在 Codex
命令、权限、MCP 工具、技能、代理循环与任务状态都留在 Codex。路由器只处理模型推理与外部模型压缩；它不能添加所选模型或供应商未实现的能力。
对于协作子代理，路由器通过已认证的原生 Codex 后端转发确切的原生任务载荷——该转发要求有效 ChatGPT 登录，在免登录模式下宁可失败关闭，也不把不可读密文转发给外部供应商。
原生目录被保留
集成保留内置 OpenAI 供应商、原生 GPT 模型、ChatGPT 登录、配置档案、MCP 设置、项目信任与推理默认值。它只向 Codex 配置添加一个标记根块和一个惰性自定义供应商表，disable 会精确恢复此前值。