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、跨平台的代理，而非新模型或訓練框架。