codex-cli-model-bridge

Codex CLI モデルブリッジ

Codex を WorkBuddy のように扱わずに、サブスクリプションに紐づくモデルやローカルプロキシモデルを管理します。Codex は Responses API Provider とモデルカタログを使用し、WorkBuddy は独立した JSON エントリーを使用します。CLIProxyAPI インフラストラクチャと検証済みの Provider 情報は共有しますが、各アプリケーションの書き込み処理と状態は分離しておきます。

Codex はタスクごとに 1 つの model_provider を選択します。モデルカタログのエントリーにモデルごとの Provider ルーティングはありません。インデックス化されたタスク履歴の大半を所有する Provider の ID（通常は openai）を維持してください。通常のデスクトップ利用では、サポートされているブリッジ設計により、model_provider = "openai" を維持し、ChatGPT のサブスクリプション認証をそのまま保ち、組み込み Provider の openai_base_url を、所有者のみがアクセスできるループバックのヘッダー書き換えプロキシに向けます。これにより CLIProxyAPI は、タスクの Provider ID を変更せずに、ネイティブの GPT サブスクリプションモデルと検証済みのサードパーティモデルを 1 つのカタログの背後でルーティングできます。Windows では分離された $CODEX_HOME/cli-proxy.config.toml プロファイルをデフォルトの方法として使い、それ以外の環境ではフォールバックとして維持してください。

これは透過的な単一 Provider のルーティングであり、モデルごとの Provider ルーティングではありません。履歴の大半が openai に属する場合、デスクトップのデフォルトを cli_proxy またはベンダーの ZAI に設定しないでください。

ユーザーが Coding Plan キーで GLM-5.3 を使いたい場合は、glm-coding-plan.md を参照してください。デスクトップですでにポート 4202 の Codex Router を使用している場合は、OpenAI Provider の ID を維持したまま、そこに zai-coding を追加してください。npx @z_ai/coding-helper は実行しないでください。

Windows では、まず分離されたプロファイルを使用してください。windows.md を参照してください。Homebrew、LaunchAgents、Codex Router は必須ではありません。

Skill ディレクトリの解決

読み込まれたこの Skill のディレクトリを <skill-dir> として解決します。<python> は、python3、py -3、python のうち最初に使用可能なものとして解決します。決定的なエントリポイントを使用してください。

<python> <skill-dir>/scripts/bridge.py

以下の例では python3 を使用しています。このコマンドがない場合は <python> に置き換えてください。

デフォルトのワークフロー

1. 変更前に監査する

python3 <skill-dir>/scripts/bridge.py audit

監査ではシークレットをマスキングし、次の項目を検証する必要があります。

• Codex CLI のバージョン、~/.codex/config.toml、ファイルの権限、TOML の妥当性
• デフォルトの model_provider、Provider ごとのインデックス化されたタスク数、SQLite の整合性、履歴の大半を占める Provider
• アクティブなブリッジモード：デスクトップ透過型または分離プロファイル型
• デスクトップ透過型の openai_base_url、ChatGPT 認証の継続性、ループバックの健全性、または分離プロファイルのコマンドベース認証
• ループバック限定の CLIProxyAPI への到達性と、稼働中の /v1/models
• アクティブなカタログの妥当性、表示されるモデル ID、ブリッジの所有状態
• 古いカタログエントリー、管理対象モデルのライブ経路の欠落、一覧に表示されたネイティブモデルまたは現在のデフォルトモデル、プロキシには存在するが Codex には存在しないモデル

Codex がカスタム Provider で公式にサポートしているのは Responses ワイヤー API のみです。Chat Completions 専用の経路を登録して、Codex 互換と呼ばないでください。

デフォルト Provider がインデックス化された履歴で最も多い Provider と異なる場合は、履歴の復元を最初の修復として扱ってください。現在の Provider に合わせるためにタスク行を編集しないでください。

2. デスクトップのデフォルトと履歴を復元する

プレビューします。

python3 <skill-dir>/scripts/bridge.py restore-default

プレビューでは、1 つの検出 ID、現在の設定の SHA-256、正確な単一ファイルの差分、変更前のスレッド一覧が報告されます。修復が許可され、SHA が現在の値と一致する場合にのみ適用してください。

python3 <skill-dir>/scripts/bridge.py restore-default \
  --expected-sha256 <approved-sha256> \
  --apply

デフォルトの対象は、インデックス化されたタスク数が最も多い Provider です。このコマンドは、--allow-minority-provider が明示されていない限り、少数派の Provider を拒否します。また、ネイティブモデルを復元し、カスタムのルートカタログ上書きを削除し、無関係な TOML を維持し、0600 のバックアップを作成して、タスク一覧のダイジェストが変更されていないことを証明します。

3. 分離された CLIProxyAPI プロファイルを設定または修復する

Windows では、これがデフォルトの方法です。プレビューして適用します。

python3 <skill-dir>/scripts/bridge.py configure
python3 <skill-dir>/scripts/bridge.py configure --apply

このコマンドは ~/.codex/config.toml を書き換えません。無関係なプロファイルセクションを保持し、タイムスタンプ付きの 0600 バックアップを作成します。また、既存の CLIProxyAPI クライアントキーをコピーせずに読み取る、所有者のみが使用できる認証情報ヘルパーをインストールし、~/.codex/cli-proxy.config.toml を次のように設定します。

• model_provider = "cli_proxy"
• model_catalog_json = "~/.codex/model-catalog-cli-proxy.json"
• ループバック URL と wire_api = "responses" を含む [model_providers.cli_proxy]
• ローカルヘルパーコマンドを使用する [model_providers.cli_proxy.auth]

Windows で Ruby が不要になるよう、デフォルトではヘルパーに Python を使用します。既存の .rb ヘルパーはそのまま残します。ユーザーから明示的に依頼されない限り、デフォルトのモデルを設定または変更しないでください。組み込みの Provider ID を上書きしないでください。このプロファイルを作成した後は、codex --profile cli-proxy を使用します。

4. プロファイルのモデルカタログを同期する

同梱モデルをプレビューします。

python3 <skill-dir>/scripts/bridge.py sync

ライブのルート検証後に適用します。

python3 <skill-dir>/scripts/bridge.py sync --apply

同期コマンドは、必要なランタイムメタデータを引き継ぐために Codex のネイティブモデルキャッシュを最初に読み込み、<skill-dir>/models/ にある検証済みのモデルマニフェストを重ね合わせ、管理対象外または手動で追加されたプロファイル項目を保持します。--adopt を明示しない限り、所有権のない項目との競合を上書きせず、対象をバックアップしてアトミックに書き込み、管理対象の ID を ~/.config/codex-cli-model-bridge/state.json に記録します。

ピッカーポリシーは <skill-dir>/policies/catalog.json にあります。hidden_native_model_ids に含まれる ID は、Codex ネイティブの visibility = "hide" の動作を適用してカタログ内に保持されます。そのため、既存のタスクやルートは引き続き動作し、それらの項目はモデルピッカーに表示されなくなります。生成されたカタログを手動で編集するのではなく、必ずこの正規のポリシーを変更してください。後続の同期では、Codex の更新によって models_cache.json が更新された後も、このポリシーが再適用されます。

protected_native_model_ids に含まれる ID も、正確なネイティブスラッグのまま保持する必要があります。Codex App の create_thread は、見た目だけのカタログエイリアスとは別にこれらの ID を検証するため、管理対象のマニフェストでこれらの ID を supersede してはなりません。Fast はサービス階層で表現してください。gpt-5.6-sol を *-standard のピッカーエイリアスに置き換えないでください。WorkBuddy が Fast／standard の追加エイリアスを必要とする場合、ネイティブスラッグがライブの /v1/models に残るよう、CLIProxyAPI の oauth-model-alias で fork: true を設定する必要があります。カタログに登録されているモデル、または現在のデフォルトモデルがライブリストにない場合、監査は失敗します。

ブリッジカタログにコピーされたネイティブ項目はメタデータにすぎません。分離プロファイルモードでは cli_proxy 経由でルーティングされます。Desktop 透過モードでは、組み込みの openai Provider ID とそのループバック openai_base_url 経由でルーティングされます。カタログ自体が Provider を選択することはありません。

--models <comma-separated-ids> を使用してサブセットを選択します。--catalog-policy <path> は、明示的に別のポリシーを使用する場合、または分離されたテストを行う場合にのみ使用します。--prune-managed は、古いブリッジ管理モデルの削除をユーザーから明示的に依頼された場合にのみ使用します。ネイティブ項目や手動で追加した項目は削除しないでください。ネイティブのピッカー項目はポリシーを通じて非表示にします。

新しいモデルを導入するときは、model-manifests.md を読んでください。マニフェストはメタデータであり、動作の証明ではありません。そのルートがライブの /v1/models に表示され、実際の codex exec プローブに合格するまで、成功を報告しないでください。

5. Desktop との透過的な共存を有効にする

通常の Desktop ピッカーを使いたいとユーザーが明示し、Node プロセスを起動したままにする場合を除き、Windows ではこの手順をスキップしてください。分離されたプロファイルで十分です。

まず、ルート設定の正確な差分と履歴ガードをプレビューします。

python3 <skill-dir>/scripts/bridge.py configure-desktop

検出結果レベルの差分が承認されたら、報告された SHA-256 を使って適用します。

python3 <skill-dir>/scripts/bridge.py configure-desktop \
  --expected-sha256 <approved-sha256> \
  --apply

このコマンドは、インデックス化された履歴の過半数を openai が所有していること、auth.json に有効な ChatGPT トークンが残っていること、両方のエンドポイントがループバック専用であること、選択したデフォルトモデルがカタログに存在することを確認できない場合、処理を拒否します。次のファイルをインストールします。

• ~/.config/codex-cli-model-bridge/transparent_proxy.mjs。所有者に実行権限を付与します
• macOS では ~/Library/LaunchAgents/com.zhijian.codex-cli-model-bridge-transparent-proxy.plist
• Windows と Linux では、LaunchAgent の代わりにデタッチされた node プロセス
• 127.0.0.1:8318 のリスナー。転送前に、下流の Authorization ヘッダーのみを書き換えて、認証済みの CLIProxyAPI（127.0.0.1:8317）に転送します

その後、model_provider = "openai" を維持し、openai_base_url = "http://127.0.0.1:8318/v1" を設定して、検証済みカタログを有効化し、ChatGPT ログインと無関係な TOML 設定を保持し、0600 のバックアップを作成し、タスクインベントリのダイジェストが変わっていないことを確認します。同じ OAuth ディレクトリを使って CLIProxyAPI のインスタンスを二重に実行しないでください。同時にトークンを更新すると、認証情報が無効になることがあります。

6. Fast モードを正しく扱う

Codex の Fast モードは、通常、2 つ目のモデルエントリではなく、モデルに対するサービスタイアです。カタログで Fast タイアが示されているモデルでは、次を使います。

service_tier = "fast"

または、次のようにして一度限りの実行を開始します。

codex -c 'service_tier="fast"'

Codex は fast を優先リクエスト値にマッピングします。見た目だけのカタログエイリアスとして *-fast を作成しないでください。上流が実際に別のルートを必要とし、ライブの Responses プローブで個別のルーティング動作が検証される場合に限り、別ルートを使用できます。

7. Codex 自体を通してプローブする

カタログを同期した後、影響を受けるモデルをプローブします。

python3 <skill-dir>/scripts/bridge.py probe --models grok-4.6,deepseek-v4-pro

プローブは、各モデルに対してエフェメラルな読み取り専用モードで codex exec --profile cli-proxy を実行し、最終応答が正常に返されることを確認します。--fast は Fast が示されているモデルにのみ使用してください。プロンプトに機密情報を含めず、セッションを永続化しないでください。

通常の Desktop 透過パスでは、Provider の ID を切り替えずにプローブします。

python3 <skill-dir>/scripts/bridge.py probe \
  --desktop \
  --models grok-4.6,deepseek-v4-pro,deepseek-v4-flash,gpt-5.6-sol

--desktop を指定すると、プローブは ~/.codex/config.toml のアクティブなルート model_catalog_json を読み取ります。--catalog は明示的な上書きとしてのみ使用してください。

直接 HTTP プローブはプロキシの診断には使えますが、Codex が Provider とモデルカタログを使用したことの証明にはなりません。完了には Codex レベルのプローブが必要です。

モデルがチャットできても、Codex が空または互換性のない Shell ペイロードを報告する場合は、実際の読み取り専用コマンドイベントを必須にします。

python3 <skill-dir>/scripts/bridge.py probe \
  --desktop \
  --shell \
  --models grok-4.6

Codex が pwd コマンドの実行成功を記録した場合にのみ、このチェックは合格します。単にパスを表示したり、実行したように見せかけたりするモデルは合格しません。失敗したカスタムモデルが OpenAI テンプレートから tool_mode = "code_mode_only" を継承していた場合は、そのモデルのマニフェストで "tool_mode": null を設定して再同期してください。ネイティブ OpenAI モデルからコードモードを一括で削除しないでください。

7.1 サードパーティモデル向けに Codex Multi-Agent の入力を修復する

Codex Multi-Agent v2 は、agent_message という非公開の Responses 入力項目を使用します。OpenAI/Codex のネイティブルートでは受け入れられますが、xAI などのサードパーティ Responses エンドポイントでは、HTTP 422 と ModelInput を返して拒否される場合があります。CLIProxyAPI 7.2.125+ には互換性変換処理が含まれているため、このプロトコル変換を透過ヘッダープロキシで重複して実装しないでください。

正規の CLIProxyAPI 設定でプレビューして有効にします。

python3 <skill-dir>/scripts/bridge.py configure-multi-agent
python3 <skill-dir>/scripts/bridge.py configure-multi-agent \
  --expected-sha256 <approved-sha256> \
  --apply

これにより、codex.optimize-multi-agent-v2 のみが true に変更され、0600 のバックアップが作成され、macOS の Homebrew サービスが存在する場合は CLIProxyAPI が再起動され、透過ルートが復旧するまで待機します。Windows では、ライブの /v1/models チェックで復旧しない場合、ユーザーに CLIProxyAPI をローカルで再起動するよう伝えてください。この変換は、公式 Codex ユーザーエージェントに対してのみ有効です。xAI の場合、agent_message を標準のユーザー message に変換し、暗号化されたコンテンツのラッパーを正規化します。通常の OpenAI の履歴やプロバイダーの識別情報には変更を加えません。

実際に失敗した入力形式を確認してから、通常の Codex プローブを実行します。

python3 <skill-dir>/scripts/bridge.py probe-multi-agent --models grok-4.6
python3 <skill-dir>/scripts/bridge.py probe --desktop --tool-sequence --models grok-4.6

Grok のエージェント機能を使用するには、CLIProxyAPI 7.2.130 以降と、上記の両方のプローブ結果を必須としてください。プレーンテキストの補完や pwd が一度成功しただけでは、モデルが複数ツールや Subagent の作業に対応しているとは判断できません。古いプロキシバージョンでは、Responses のツール識別情報、増分ツール状態、または Codex のマルチエージェント名前空間が正しく処理されない場合があります。

8. 消費状況を確認する

audit を再実行してから sync を繰り返します。2回目の同期は冪等でなければなりません。通常のデスクトップタスクは、最も多くの履歴を持つ Provider のままにしてください。Desktop-transparent モードでは、選択されたすべてのモデルがループバックブリッジ経由でルーティングされますが、タスクの識別情報は openai のままです。これを、モデルごとに独立して Provider を選択できることのように説明しないでください。Windows とフォールバックの診断には codex --profile cli-proxy を使用します。

以下を報告します。

• Codex と CLIProxyAPI のバージョン、およびローカルエンドポイント
• デフォルトの Provider、Provider 別のタスク数、変更がないことを確認したタスクインベントリのダイジェスト
• プロファイルの Provider とカタログのパス。シークレットは省略します
• 追加、更新、削除、保持、または競合したモデル
• ライブのルートと codex exec プローブの結果
• 要求された場合は Fast のセマンティクス
• バックアップのパス、再読み込みの操作、ロールバックコマンド

修復ワークフロー

1. 監査を行い、履歴スコープの不一致、無効な TOML、プロキシ停止、ヘルパーまたは認証の失敗、ルートの欠落、無効なプロファイルカタログ、古いタスク、Provider プロトコルの不一致を区別します。
2. モデル作業の前に、最も多くの履歴を持つ Provider を復元します。タスクの行を書き換えないでください。
3. 最小限の失敗レイヤーを修復します。正常なプロキシは再インストールしないでください。
4. CLIProxyAPI の認証が実際に欠落または拒否されている場合に限り、WorkBuddy ブリッジを使って上流 Provider を再認証します。
5. プロファイルカタログの同期と、影響を受けた Codex レベルのプローブを再実行します。
6. 通常のデスクトップ履歴がデフォルトの Provider で引き続き表示されることを確認します。

HTTP 422 の本文に ModelInput と記載された Subagent の失敗については、失敗したタスクで agent_message 入力項目を確認します。CLIProxyAPI 7.2.125+ では、codex.optimize-multi-agent-v2 を有効にしてから probe-multi-agent を実行します。透過ヘッダープロキシですべてのリクエストを無差別に平坦化しないでください。

失敗の分類とロールバックについては、troubleshooting.md をお読みください。

安全上の境界

• CLIProxyAPI は明示的なループバックに限定し、リモート管理を無効にしてください。
• 現在のデスクトップセッションで Grok などのサードパーティモデルを使用している間は、CLIProxyAPI または 8318 透過プロキシを再起動しないでください。再起動すると、ライブ経路が数秒間切断され、このセッションが unknown provider エラーで中断される場合があります。Sol/Grok の修復が検証された後まで待つか、先にユーザーに伝えてください。
• 関係のない config.toml のセクション、MCP サーバー、フック、スキル、権限、プロジェクトの信頼設定を保持してください。
• API キー、ベアラーヘッダー、OAuth ファイル、ワンタイムコード、生の認証情報ヘルパーの出力、認証情報を含む TOML ブロックを表示しないでください。
• config.toml、カタログ／状態ファイル、プロキシ設定、ヘルパー、バックアップは、非公開のインフラストラクチャが明らかになるおそれがある場合、所有者のみがアクセスできるようにしてください。Unix ではモード 0600 を目標とします。Windows ではファイルを現在のユーザープロファイル内に保管し、共有しないでください。
• コマンド経由の認証、または所有者のみがアクセスできる透過的なヘッダー書き換えを使用してください。experimental_bearer_token を埋め込んだり、プロキシのクライアントキーを重複させたりしないでください。
• ネイティブの models_cache.json は上流からの入力として扱い、この Skill が所有するファイルとして扱わないでください。
• モデルをピッカーに強制的に表示させるために、Codex の SQLite 状態やデスクトップアプリのバンドルを直接編集しないでください。
• インデックス化された Provider の分布を先に読み取らずに、デフォルトの Provider を切り替えないでください。ユーザーが結果を明示的に受け入れない限り、履歴の大半が表示されなくなる切り替えは拒否してください。
• モデルごとの Provider ルーティングを宣伝しないでください。デスクトップでの共存が機能するのは、組み込みの openai Provider ID が、選択されたカタログ内のすべてのモデルを同じループバックブリッジ経由で透過的にルーティングするためです。
• Provider のサブスクリプション条件、クォータ、アカウントの所有権を尊重してください。

完了条件

完了には、次の要件が必要です。

• デフォルトの Codex TOML が、インデックス化された履歴で優勢な Provider に紐づいている
• タスク一覧が修復中に変更されておらず、整合性が確認されている
• 有効な分離フォールバックプロファイル、または ChatGPT 認証が維持された正常なデスクトップ透過型ループバックブリッジ
• 有効なモデルカタログがあり、未承認の重複がない
• 要求されたネイティブピッカーの除外設定が visibility = "hide" で維持されている
• 新たに管理されたすべての経路が CLIProxyAPI から見える
• 対象となるすべてのモデルについて、現在のモードを通じた一時的な codex exec のプローブが成功している
• 要求された場合、Fast がサービス階層として登録され、テストされている
• 変更のない状態での 2 回目の同期
• バックアップとロールバック手順が報告されている

Codex がある経路で Responses リクエストを完了できない場合は、未検証として報告し、/v1/models に名前が表示されることだけを理由に利用可能と宣伝しないでください。