codex-shim：让 Codex Desktop 用上任何大模型的本地透明网关

你有没有遇到过这样的场景：手里攥着 DeepSeek 的 API Key，眼睁睁看着 Codex Desktop 的模型选择器里只有 GPT-5.5 一个选项？或者你想用 Claude 来驱动代码助手，却被告知不支持？codex-shim 就是来解决这个问题的。

这是一个由独立开发者 0xSero 维护的开源项目（928 星，Python 语言，MIT 协议），它用不到 200 行配置加一个轻量 Python 服务，将 Codex Desktop 变成一个真正的模型无关代码助手。无论你是想用自带的 ChatGPT 订阅、还是接入 Anthropic、DeepSeek、Gemini、OpenRouter，甚至是本地部署的模型，codex-shim 都能帮你绕过 Codex 的服务端配置限制，在本地完成路由转发。

一行命令，Codex 用上所有模型

codex-shim 的核心是一个运行在 127.0.0.1:8765 的 Python/aiohttp 代理服务器。它模拟了 Codex 期望的 Responses API 端点，Codex Desktop 的请求发到本地 shim，shim 根据 ~/.codex-shim/models.json 的配置，将请求转发到真实的模型提供商。

想象一下：Codex 是一个只会说普通话的快递员，而全球的 AI 模型是说英语、日语、中文的各色仓库。codex-shim 就是那个站在中间的国际快递转运站，把快递员的普通话包裹拆开，重新打包成目标仓库能看懂的语言，再把回件翻译回来。

架构解析：六层模块的精密协作

从源码来看，codex-shim 的代码库结构清晰，核心逻辑分布在以下文件中（按体积排序）：

server.py（约 100KB） — 这是整个 shim 的心脏。它用 aiohttp 构建了一个完整的 HTTP 服务器，注册了以下路由：

• GET /health — 健康检查
• GET /v1/models — 返回配置的模型列表（供 Codex picker 使用）
• POST /v1/chat/completions — OpenAI 兼容端点
• POST /v1/messages — Anthropic Messages 端点
• POST /v1/responses — OpenAI Responses API 端点
• POST /v1/responses/compact — 内部压缩端点（减少 token 往返）
• GET /picker — 返回一个自定义的模型选择器 HTML 页面
• POST /api/switch — 动态切换模型

aiohttp 的 client_max_size 被设为 64MB，以支持图像理解等大请求。超时配置为 sock_connect=120s，无 sock_read 超时（支持长时间推理）。安全中间件 host_guard_middleware 基于白名单限制可访问的 hosts。

translate.py（约 47KB） — 这是 codex-shim 最体现功力的模块。AI 领域有多种请求/响应协议：OpenAI 的 Chat Completions、Anthropic Messages、OpenAI Responses API，各有各的格式。translate.py 负责在这些协议之间双向翻译。例如 anthropic_messages_to_chat() 将 Anthropic 的消息格式转为 OpenAI chat 格式；responses_to_chat() 将 Responses API 响应转为 chat 格式。它还处理 function calling、tool use、reasoning block 等复杂场景，确保 Codex 原生的 Agent 能力（函数调用、工具输出、图像理解、流式 SSE）不被破坏。

router.py（约 21KB） — Auto Router（自动路由器）的核心实现。这是一个基于分类模型（classifier）的智能路由引擎：添加一个虚拟模型 codex-auto，当用户选择它时，shim 会先调用一个小型的分类模型，对当前任务进行评分，预测哪个已配置的模型能以最低成本完成这个任务，然后将请求路由到足够好且最便宜的模型。设计亮点：分类器只看能力不看价格（价格由最便宜且合格逻辑处理）；路由结果按用户消息 hash 缓存 256 条，避免重复分类开销；每一步都有优雅降级，classifier 不可用则 fallback 到最便宜模型，任何错误 fallback 到默认模型。

cli.py（约 51KB） — 命令行工具的完整实现。codex-shim generate 生成配置文件，codex-shim start 启动服务，codex-shim status 查看状态，codex-shim list 列出可用模型，codex-shim model <slug> 切换默认模型，codex-shim patch-app（macOS only）为 Codex Desktop 打 ASAR 补丁来显示自定义模型选项，codex-shim restore-app 恢复原始状态。cli.py 还负责写入 Codex 的 ~/.codex/config.toml 配置文件，使其指向 shim 端点。

cursor_passthrough.py（约 12KB） — 接入 Cursor/Composer 订阅的特殊逻辑。如果 cursor-agent login 处于活跃状态，shim 暴露 composer-2-5 slug，将请求通过 Cursor 的内部 API 路由，不需要 Dashboard API key（crsr_...）。

支持的模型与集成方式

根据 settings.py 和源码的静态分析，codex-shim 支持的模型来源包括：

所有模型通过 models.json 配置，每条配置包含：API 类型（OpenAI/Anthropic/自定义）、base URL、API key、模型 slug、显示名称。

部署体验：3 分钟跑起来

codex-shim 的安装极简主义到了极致。唯一强制依赖是 aiohttp>=3.9，Python 3.11+ 即可。安装方式只有一种：pip install -e . 从源码安装（推荐）或直接 pip install aiohttp 后用 bin/codex-shim 脚本运行。

没有 Docker 支持，也没有 docker-compose，所以不满足 quick_deploy: supported 的条件，但 pip install 几乎等同于一键部署，实际难度为极简。

首次使用需要运行 codex-shim generate 生成 ~/.codex-shim/models.json 模板，然后编辑填入自己的 API key 和模型配置。如果只用 ChatGPT/Codex 透传功能，只需要 ~/.codex/auth.json 中有有效的 access token 即可。

macOS 特别说明：Codex Desktop 的模型选择器默认隐藏自定义模型条目，需要运行 codex-shim patch-app 对 Electron ASAR 包打补丁（需要 npx 和 codesign），这一步是可选的，shim 服务器本身不需要它。

Windows 支持：原生 PowerShell/cmd、WSL、Git Bash 均支持，行为一致。注意 Windows Store/MSIX 版的 Codex Desktop 对自定义 slug 限制更严格，可能被强制重写为 gpt-5.5，但 codex exec、TUI 和 shim 端点不受影响。

性能与成本优化

作者在 README 中提到，在实际编码任务中，使用 ChatGPT 透传加 prompt-catching proxy 前置的组合，相比直接用 ChatGPT 的默认路由，输入 token 费用降低到原来的几分之一，响应速度也有明显提升（未提供正式 benchmark）。不过这是非正式测试数据，真实收益因任务类型差异很大。

Auto Router 是另一个成本优化手段：简单任务（代码补全、简单解释）路由到便宜模型，复杂任务（架构设计、长文本生成）路由到强模型，整体上可以显著降低平均推理成本。

局限与风险

1. Codex 版本依赖：作者明确测试了 0.133.0-alpha.1 版本，新版 Codex 的 API 行为可能变化，需要留意 CHANGELOG。
2. 透传 API key 安全：ChatGPT/Cursor 透传需要将 access token 写入本地配置文件，需注意本机安全。
3. 非官方绕过：虽然 shim 本身是纯本地透明代理，但 Codex 的服务端 allowlist 机制可能会随着版本更新收紧。
4. 测试覆盖：代码库处于 Alpha 阶段，测试覆盖虽完整，但尚未经过大规模生产验证。

总结

codex-shim 是 AI 代码助手生态中一个非常巧妙的中间件项目。它没有重新造模型，也没有改动 Codex 本身，而是在协议翻译层找到了一个精妙的切入点。如果你有多个模型提供商的 API key，或者想在本地部署开源模型（如 DeepSeek Coder）来驱动 Codex，codex-shim 能在不破坏原有体验的前提下，将这一切串联起来。对于成本敏感的用户，Auto Router 的智能路由功能也值得关注，同样的任务，花更少的钱，效果不打折扣。

项目亮点：多协议翻译引擎完善、Auto Router 思路优雅、支持平台广泛（macOS/Linux/Windows/WSL/Git Bash）。主要不足：无 Docker 支持、Alpha 阶段稳定性待验证。