sybil-solutions/codex-shim

codex‑shim – Codex Desktop 的本地路由代理

是什么

• 一个小型 Python + aiohttp 服务器，伪装成 Codex Desktop 期望的 OpenAI Responses API。
• 运行在 127.0.0.1:8765，并将每个请求转发到您配置的任意上游模型——OpenAI、Anthropic、DeepSeek、Gemini、OpenRouter、本地 Ollama 服务器，甚至官方 ChatGPT Codex 后端。
• 该代理会转换请求/响应格式（包括流式 SSE、工具调用、图像输入等），使 Codex Desktop 能够保持其原生 UI 和代理循环不变。

为何使用它

• 自带模型（BYOK） – 无需重新构建应用，即可将您自己的模型引入 Codex Desktop。只需放置一个描述模型的 JSON 文件，代理就会使其出现在选择器中。
• 保留 Codex 的用户体验 – 函数调用、推理块、图像处理和流式传输功能与内置模型完全一致。
• 可选的 ChatGPT 透传 – 如果您拥有有效的 Codex 访问令牌，代理可以将 /v1/responses 转发到官方 ChatGPT Codex 后端，使用 gpt‑5.5 别名。
• 与 Cursor 集成 – 当您登录 Cursor 时，代理可以暴露 composer‑2‑5 模型，无需单独的 Dashboard API 密钥。
• 智能自动路由（可选） – 一个低成本分类器可自动选择能处理特定任务的最便宜模型。
• 代理友好 – 您可以在代理前放置另一个本地代理，用于注入指令、去重提示或强制执行策略。

如何工作

1. 配置 – 创建 ~/.codex‑shim/models.json（或使用 --settings 传入自定义文件）。每个条目包含：
   • model / slug
   • provider（openai、anthropic、generic-chat-completion-api 等）
   • base_url 和认证信息（api_key 或 api_key_env）
   • 可选的 UI 提示，如 display_name、max_context_limit、no_image_support。
2. 生成目录 – codex‑shim generate 读取 JSON 并生成 Codex 兼容目录（custom_model_catalog.json）和提供者配置（config.toml）。
3. 启动代理 – codex‑shim start 启动在回环地址监听的 aiohttp 守护进程。
4. 告知 Codex Desktop 使用它 – codex‑shim app . 启动 Codex Desktop，并将本地提供者注入 ~/.codex/config.toml。应用现在会看到您列出的所有模型，以及可选的 gpt‑5.5 透传（如果您有令牌）。
5. 切换模型 – codex‑model list 显示所有别名；codex‑model <slug> 选择一个，codex‑app 重新启动 Codex 以应用新默认值。

支持的上游

提供者	上游端点
openai	OpenAI /v1/chat/completions
generic-chat-completion-api	任意 OpenAI 风格的聊天端点
anthropic	Anthropic /v1/messages
ollama（通过通用）	本地 Ollama /v1/chat/completions
opencode‑go（刷新命令）	OpenCode Go 目录 API

该代理还能在其自身端点接收 Anthropic 风格的 Messages 请求，并将其转换为上游所需的格式。

主要命令

• codex‑shim generate – 从模型列表构建目录。
• codex‑shim start – 启动本地服务器。
• codex‑shim status – 健康检查和模型数量。
• codex‑shim list – 显示哪些别名映射到哪些上游。
• codex‑shim app – 启动已连接代理的 Codex Desktop。
• codex‑shim model use <slug> – 为下一次会话选择一个模型。
• codex‑shim disable – 从 Codex 配置中移除代理管理的区块。
• codex‑shim patch‑app / restore‑app – macOS 专用 ASAR 补丁，强制 Codex Desktop 选择器显示自定义别名（macOS 上必须，因为官方应用会隐藏未知模型）。
• codex‑shim opencode‑go refresh – 自动拉取最新的 OpenCode Go 模型列表。

安装

git clone https://github.com/0xSero/codex-shim ~/codex-shim
cd ~/codex-shim
python3 -m pip install --user -e .   # 安装 `codex-shim` CLI

（Windows 用户可使用 py -3.11 执行相同步骤。）

平台支持

• 支持 macOS、Linux、WSL、Git Bash 和原生 Windows PowerShell/cmd。
• 核心代理为纯 Python，仅可选的 macOS 选择器补丁需要 npx 和 codesign。
• Windows Store/MSIX 版本的 Codex 可能隐藏自定义别名，但代理路由仍有效；UI 仅显示内置模型。

典型工作流

# 1. 描述您的模型
cat ~/.codex-shim/models.json   # （请参阅 README 了解模式）

# 2. 构建目录并启动代理
codex-shim generate && codex-shim start

# 3. 通过代理启动 Codex Desktop
codex-shim app .

# 4. 从下拉菜单中选择模型（或通过 CLI）
codex-model list
codex-model gpt-5.5
codex-app   # 重新启动以应用新默认值

您将获得

• Codex Desktop 的所有高级功能（函数调用、工具输出、图像支持、流式传输）保持可用。
• 可将简单任务路由到廉价本地模型（如 Ollama），并自动回退到更强大的云模型处理复杂任务。
• 无需重新构建或重新签名 Codex Desktop（仅可选的 macOS 选择器补丁例外）。

---

总结：codex‑shim 是一个实用的桥梁，让商业版 Codex Desktop 编码助手能够使用任何您喜欢的 OpenAI 兼容、Anthropic 或本地托管的 LLM，同时保留应用的原生体验。它是一个纯 Python、跨平台的代理，而非新模型或训练框架。