sybil-solutions/codex-shim

codex‑shim – Codex Desktop 用のローカルルーティングシム

何であるか

• Codex Desktop が期待する OpenAI Responses API を偽装する、小さな Python + aiohttp サーバー。
• 127.0.0.1:8765 で動作し、設定したアップストリームモデル（OpenAI、Anthropic、DeepSeek、Gemini、OpenRouter、ローカルの Ollama サーバー、あるいは公式の ChatGPT Codex エンドポイント）にリクエストを転送します。
• リクエスト/レスポンスの形状（ストリーミング SSE、ツールコール、画像入力など）を変換するため、Codex Desktop はネイティブ UI とエージェントループを変更せずにそのまま利用できます。

なぜ使うか

• BYOK（自分のモデルを導入） – アプリの再ビルドなしに Codex Desktop に独自モデルを追加できます。モデルの情報を記述した JSON ファイルを配置するだけで、ピッカーにモデルが表示されます。
• Codex の UX を維持 – 関数コール、推論ブロック、画像処理、ストリーミングが、組み込みモデルと同様に動作します。
• オプションの ChatGPT パススルー – 有効な Codex アクセストークンを持っている場合、gpt‑5.5 スラッグで公式 ChatGPT Codex バックエンドに /v1/responses を転送できます。
• Cursor 統合 – Cursor にログインしている場合、別途 Dashboard API キーを必要とせずに composer‑2‑5 モデルを公開できます。
• スマートな自動ルーター（オプション） – 低コストの分類器が、特定のタスクを処理できる最も安価なモデルを自動的に選択します。
• プロキシ対応 – シムの前に別のローカルプロキシを配置し、指示を挿入したり、プロンプトを重複除去したり、ポリシーを強制したりできます。

動作方法

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 で loopback アドレスで待機する aiohttp デーモンを起動します。
4. Codex Desktop に接続 – codex‑shim app . で Codex Desktop を起動し、~/.codex/config.toml にローカルプロバイダを注入します。アプリは、リストしたすべてのモデルと、トークンがある場合のオプションの gpt‑5.5 パススルーを認識します。
5. モデルの切り替え – codex‑model list でスラッグを確認し、codex‑model <slug> で選択、codex‑app で再起動して新しいデフォルトを適用します。

サポートされるアップストリーム

プロバイダ	アップストリームエンドポイント
openai	OpenAI /v1/chat/completions
generic-chat-completion-api	任意の OpenAI 形式のチャットエンドポイント
anthropic	Anthropic /v1/messages
ollama（generic を通じて）	ローカル Ollama /v1/chat/completions
opencode‑go（refresh コマンド）	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 で構成されたクロスプラットフォームのシムであり、新しいモデルやトレーニングフレームワークではありません。