Codex Router 工作原理 — 架构与请求流程
Codex Router 是编码 Agent 客户端与外部模型供应商之间的本地服务。Codex 仍是主要前端，同一份已认证模型注册表还可发布给 DeepSeek Harness、Gemini CLI、Cursor、Claude Code、OpenClaw、opencode、pi、omp、Command Code 与 Hermes Agent。本页解释请求流程与安全边界。
为什么需要路由器
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 请求发送到 4202 端口的回环路由器：
| 端口 | 监听器 | 职责 |
|---|---|---|
| 4202 | 路由器 | 接收客户端请求并认证 caller capability |
| 4200 | LiteLLM | 把 Responses 翻译为各供应商的原生协议 |
| 4201 | Kimi OAuth | 用刷新后的 OAuth bearer 转发给 Kimi |
| 4203 | API 转发器 | 用所选密钥转发给 API Key 供应商 |
对于原生 GPT 模型，路由器用放行列表中的 Codex 头与原生模型 ID 转发给 ChatGPT Codex 后端——路由器绝不会把原生请求发送给外部供应商。
对于注册表模型（例如 kimi-oauth/k3），路由器校验调用方、把网关模型加内部密钥交给 LiteLLM，LiteLLM 翻译请求并交给匹配的转发器。转发器丢弃内部密钥，只注入所选供应商凭据。流经 LiteLLM 以 Responses 事件返回。
一份注册表，多个客户端
Codex、DeepSeek Harness、Gemini CLI、Cursor、Claude Code、OpenClaw、opencode、pi、omp、Command Code 与 Hermes Agent 共用供应商可见性和逐模型选择状态。每个发布器只适配最外层客户端契约——Responses、Gemini、Anthropic Messages 或 Cursor edge——随后重新进入同一条路由请求路径。Command Code 与 Hermes Agent 使用 Claude Code 相同的 Anthropic Messages 接口，opencode、pi 与 omp 则接收已认证的本地回环 /v1 路径。这五个“发布进去”的客户端没有 MODEL_ROUTER_TARGET，也没有第二个服务；启用供应商或整理模型会一并重新发布。只有用户显式运行 chatgpt-session enable 后，非 Codex 客户端才会看到原生 ChatGPT 模型。
凭据边界
| 路由 | 入站 Codex 凭据 | 上游凭据 |
|---|---|---|
| 原生 GPT | 放行并转发 | 已有 ChatGPT/Codex 认证 |
| Kimi OAuth | 丢弃 | ~/.kimi-code 的 Kimi CLI OAuth bearer |
| Kimi API | 丢弃 | Kimi Platform API Key |
| DeepSeek | 丢弃 | DeepSeek API Key |
| GitHub Copilot | 丢弃 | 经过 Copilot 权益和端点校验的 GitHub fine-grained token |
Codex 到路由器与内部服务这两条信任边界使用两个不同的随机密钥，分别以 mode 600 或当前用户 Windows ACL 存储。外部转发器在上游请求前移除 Codex 账户、安装、attestation 与私有头。
GitHub Copilot 是 catalog-only 供应商。它会先通过 GitHub Copilot 账户端点校验 fine-grained token，并且只接受 GitHub 自有的 Copilot 推理主机。实时发现只展示当前账户可见、同时支持流式输出和工具调用的 Responses 模型，因此实际模型和额度取决于用户的 Copilot 套餐及组织策略。
安全模型
- 本地调用方认证。 托管 base URL 包含独立的随机能力；路由器在读取模型请求或联系任何上游前先校验它。Codex 无法给内置供应商附加路由器专用头，因此能力放在 URL 路径中。状态、迁移与支持工具会脱敏它。
- 无浏览器访问。 路由器要求 JSON 内容、拒绝浏览器来源头、绝不授予 CORS。
- 脱敏错误。 面向网络的错误有限且不含敏感信息；原始异常文本被替换。
- 无凭据泄漏。 诊断只报告存在与来源，绝不报告值。受保护文件使用 mode
600或当前用户 ACL。
传输与压缩
当前 Codex 构建可能使用带认证的 Responses WebSocket。路由器会在同一个 caller-capability 边缘接受连接、按请求推导身份，并保留配额/错误元数据，再让请求进入同一条受管理 Responses 路径；HTTP 仍然支持。请求体可使用 Zstandard、gzip、deflate 或 Brotli，声明超限的压缩帧会在解码前被拒绝。
外部 Chat Completions 供应商无法创建 OpenAI 的不透明加密压缩载荷，因此路由器让所选外部模型生成续写摘要，并以路由器所有的 kcr1: 载荷包装。重放时把它转回普通续写消息。
哪些仍留在 Codex
命令、权限、MCP 工具、技能、代理循环与任务状态都留在 Codex。路由器只处理模型推理与外部模型压缩；它不能添加所选模型或供应商未实现的能力。
对于协作子代理，路由器通过已认证的原生 Codex 后端转发确切的原生任务载荷——该转发要求有效 ChatGPT 登录，在免登录模式下宁可失败关闭，也不把不可读密文转发给外部供应商。把某个模型开启为子代理时会先进行自动研究：分离的探测验证流式与强制工具调用，通过后以 experimental v2 覆盖项发布；首次真实子代理回合记录机器本地证明，结构性拒绝则带原因降回 v1。生成的路由 agent 定义还会写入该模型配置的 model_reasoning_effort，因此低推理档位的父代理不会悄悄把所有子代理也限制在低档位。
当某个看起来符合条件的模型无法被委派时，不必先派一个子代理再从 codex exited 1 里找原因，直接提问即可：
./bin/model-router codex subagents explain <provider/model>该命令会指出第一个阻塞点以及修复它的命令，并区分拼写错误、尚未定制的模型与原生 slug。它还会说明某条路线的 v2 声明来自注册表、来自本机五项检查，还是来自你自己的选择。该命令只读，不消耗任何额度。
原生工具与自定义模型技能包
通过路由器运行的自定义模型仍可使用 Codex 原生的任务、自动化、应用内浏览器和电脑操作工具。考虑到部分模型需要更明确的工具调用引导，安装程序会加入四个受管理技能：codex-router、codex-app-threads、codex-in-app-browser 和 codex-computer-use。若用户已有同名技能则跳过，不会覆盖；卸载时只移除路由器管理的副本，doctor 会核验技能包是否与当前检出和应用工具集一致。
原生目录被保留
集成保留内置 OpenAI 供应商、原生 GPT 模型、ChatGPT 登录、配置档案、MCP 设置、项目信任与推理默认值。它只向 Codex 配置添加一个标记根块和一个惰性自定义供应商表，disable 会精确恢复此前值。