Codex Router架构深度解读：一个本地路由器如何桥接30+AI模型协议-育师

Codex Router架构深度解读：一个本地路由器如何桥接30+AI模型协议

【免费下载链接】codex-routerExternal-model router for Codex with guided Kimi OAuth/API, DeepSeek, safe migration, and rollback.项目地址: https://gitcode.com/gh_mirrors/co/codex-router

一句话看懂 Codex Router 是什么

Codex Router是一个运行在你自己电脑上的本地模型路由器：它在 Codex 客户端与 Kimi、DeepSeek、xAI Grok、Claude、GitHub Copilot 等 30 多家外部 AI 模型服务之间架起一座桥，把各家协议互相翻译，让一个客户端能直接调用几乎所有主流大模型。全程无需把你的 API Key 或登录凭证交给任何第三方——凭证只保存在本地。

为什么需要一个"本地路由器"？

不同 AI 厂商说的是不同的"方言"：

Codex App只认 OpenAI 的 Responses API 格式；
Kimi 和 DeepSeek提供的是 OpenAI 兼容但细节不同的 Chat Completions API；
各家认证方式也完全不同：有的用 API Key，有的用 OAuth 登录，有的走订阅制客户端。

如果手动对接每一家，配置会非常痛苦。Codex Router 的做法是：统一入口、按模型 ID 分发、在中间完成协议翻译，你只需在客户端的模型选择器里选一个名字即可。

四层核心架构：请求是如何被转发的

整个路由器由四个部件协作完成，详见官方文档 docs/HOW-IT-WORKS.md：

层次	职责	对应模块
① 模型目录（Catalog）	把外部模型"伪装"成本地原生模型，和 GPT 一起出现在选择器中	src/catalog.mjs
② 分发器（Dispatcher）	按带命名空间的模型 ID 判断：原生 GPT 走官方通道，外部模型走路由	src/router.mjs
③ 协议翻译（LiteLLM 网关）	把 Responses 请求翻译成 Chat Completions，再翻译回 Responses 事件流	src/namespace-relay.mjs
④ 凭证转发（Forwarder）	只注入所选厂商的认证信息，剥离客户端私有头部	src/api-forwarder.mjs

端口即分工：4200–4203 各司其职

路由器的每个端口承担独立职责，定义在 src/paths.mjs 中，这种"平面化"设计让各组件可以独立重启、独立测试：

端口	角色	说明
4200	网关（Gateway）	LiteLLM 协议翻译层，处理 Responses ⇄ Chat Completions 转换
4201	OAuth 转发器	为 Kimi 等 OAuth 厂商刷新并注入 bearer token
4202	主路由器（Router）	对 Codex 暴露`/responses`、`/models`、`/health`等入口
4203	API 转发器	为 API Key 类厂商（DeepSeek、Grok 等）注入上游凭证

一份注册表，多个客户端共用 🗂️

模型配置全部集中在config/目录，按厂商分文件夹，目前覆盖39 家厂商、260 多个模型配置文件。每个模型用一套简单的三元组描述：

{ "slug": "deepseek/deepseek-v4-flash", "gatewayModel": "deepseek-v4-flash", "upstreamModel": "deepseek-v4-flash" }

slug：客户端选择器里看到的名字（如kimi-oauth/k3）
gatewayModel：网关内部使用的模型名
upstreamModel：真正发给厂商的模型 ID

例如 DeepSeek 的注册表在 config/deepseek/，Kimi 同时提供 OAuth 登录和 API Key 两种通道，配置在 config/kimi/。这套注册表被目录生成、路由分发、协议翻译、凭证转发、健康诊断等多个模块共同消费，改一处即全局生效。

安全设计：凭证边界是架构的核心

这是 Codex Router 最值得称道的部分——每一跳都只持有它需要的凭证：

Codex 发来的 ChatGPT 账号信息，到达外部路由时一律丢弃，绝不转发给 Kimi、DeepSeek 等厂商；
客户端与路由器之间、路由器与内部服务之间，各用独立的随机密钥鉴权，且都不是厂商凭证；
GitHub Copilot 路由会先向 GitHub 验证订阅资格，返回的推理端点必须是 GitHub 官方域名才被接受，防止元数据把 token 引向任意服务器；
所有凭证文件权限严格限制（Linux 下 mode 600，Windows 下仅当前用户 ACL）。

简单说：你的 Codex 账号不会漏给外部厂商，厂商的 Key 也不会泄露给其他服务。详见 docs/HOW-IT-WORKS.md。

不止 Codex：一套"路由平面"服务六类客户端 🔌

在 src/paths.mjs 中可以看到，路由器支持 6 个客户端目标：

codex · dsh(DeepSeek Harness) · gemini · cursor · claude · openclaw

关键设计是：服务、端口、网关、凭证、厂商选择构成一个共享的"路由平面"，TARGET只决定写哪个客户端的配置文件。这意味着你装一次、配一次 API Key，Codex、Cursor、Gemini CLI、Claude Code 等客户端就能同时使用同一套模型目录，而不会重复占配额、也不会跑两套网关。

面向长会话的工程细节

除了协议翻译，架构里还内建了大量"让长任务不崩"的机制：

上下文压缩：外部厂商无法生成 OpenAI 的加密压缩包，路由器自建kcr2检查点格式，让 Kimi、DeepSeek 也能安全压缩超长对话（src/compaction-checkpoint.mjs）；
空回复防护：厂商偶尔返回空内容，路由器会拦截并自动重试（src/empty-completion-guard.mjs）；
推理标签清洗：把厂商私有的reasoning标记翻译成标准格式，避免污染上下文（src/reasoning-tag-stripper.mjs）；
模型故障转移：某厂商限流或报错时自动切换备用路由（src/model-failover.mjs）。

用控制中心管理一切 📊

命令行之外，Codex Router 提供 Electron 控制中心（macOS 还有菜单栏托盘和桌面小组件），可以可视化地开关厂商、查看用量、调整模型优先级。

架构速览：一张表总结

设计点	实现方式	好处
协议统一	LiteLLM 网关做 Responses ⇄ Chat 双向翻译	新增厂商只需注册表条目
模型伪装	外部模型克隆原生 GPT 目录结构	原生出现于模型选择器
凭证隔离	每厂商独立转发器 + 丢弃客户端凭证	账号安全不串线
多客户端	一个路由平面，6 种客户端目标	装一次全通用
本地优先	全部服务绑定 127.0.0.1	凭证永不出本机