Codex の中で選べるモデルを増やしたいと思っていました。ただ、AI エージェントのインターフェースをもうひとつ増やすのも、プロバイダーのキーだらけの設定ファイルも避けたかった。Codex Router は、その両方を避けられるローカルの橋渡し役でした。
私は macOS 上で Codex Router 0.5.1 を使って設定しました。Linux の Codex CLI でも動きます。コミュニティのプロジェクトで、OpenAI がつくったものでも公式に認めたものでもありません。
ルーターの役割
Codex はもともと、ユーザー単位の ~/.codex/config.toml を通じてカスタムのモデルプロバイダーとやりとりできます。公式の設定リファレンスには model_provider、カスタムの base_url、model_catalog_json の説明があります。これらはユーザー設定に書くもので、プロジェクトの .codex/config.toml ではありません。
Codex Router は、この配線を代わりにやってくれます。ローカルのバックグラウンドサービスが、有効にしたプロバイダーからモデルカタログをつくり、Codex の Responses リクエストを選んだモデルに振り分けます。Codex が OpenAI にログインしたままなら、ネイティブの GPT モデルも同じ選択メニューに残ります。
うまくできているのはツールの扱いです。外部のモデルにも Codex アプリのツールを理解させる必要があるので、ルーターはネイティブのツール定義を codex_app__ や mcp__ のような平坦な名前にして渡します。モデルがツールを呼ぶと、ルーターが元の名前空間に戻します。ツールを実際に実行するのは Codex のままで、ルーターは変換と振り分けしかしません。
Homebrew でインストールする
Codex App か CLI と、ちゃんと動く Homebrew が必要です。この formula で入るのはルーターとその CLI だけで、Electron Control Center、メニューバーアプリ、デスクトップウィジェットは含まれません。
tap を追加してインストールします。
brew tap duolahypercho/codex-router https://github.com/duolahypercho/codex-router
brew install codex-router
次にガイド付きセットアップを実行します。
codex-router setup --guided
どのプロバイダーを使うかを聞かれ、流用できる既存のログイン情報がないか確認したうえで、足りない認証情報だけを入力を表示しない形で求めてきます。そのあと、ユーザー単位のバックグラウンドサービスを入れて Codex につなぎます。プロバイダーのキーは、コマンドの引数、Git で管理しているファイル、チャットのメッセージには入れないようにしましょう。
最初はプロバイダーをひとつに絞るのがおすすめです。メニューがモデルで埋まる前に、一本の経路が通ることを確かめるほうがずっと楽です。プロバイダーによって API キーだったり OAuth だったり、サブスクリプションやローカルのエンドポイントだったりしますし、課金もそれぞれ別です。
スモークテストを自分で選ばない限り、ガイド付きセットアップが有料のテストリクエストを送ることはありません。
インストールを確認する
まずはサービスの状態を見ます。
codex-router status
続いて、全体の診断を実行します。
codex-router doctor
doctor は、Codex の設定、バックグラウンドサービス、プロバイダーの認証情報、生成されたカタログ、ルーティングするモデルの定義、管理対象のスキルパックを確認します。設定した覚えのないプロバイダーについての警告は、たいてい単なるお知らせです。直すべきなのは、実際に使うつもりのプロバイダー、サービス、カタログに関わる失敗のほうです。
プロバイダーの一覧も安心して表示できます。認証情報は出力されません。
codex-router providers
ここまで問題がなければ、Codex を完全に終了してから開き直します。新しいタスクを始めると、ルーティングされたモデルがメニューに出てくるはずです。Codex が外部カタログを読むのは起動時だけなので、ウィンドウをひとつ閉じて開き直すだけでは足りないことがあります。
CLI では、ルーティングされたモデルを直接指定できます。
codex -m PROVIDER/MODEL
ルーターが表示する ID をそのまま使ってください。同じモデルファミリーが複数のサブスクリプションや API から使えることがあるので、プロバイダーのプレフィックスが重要です。
モデルを追加・更新する
プロバイダーによっては、最新のモデルカタログを公開しています。いま何が使えるかを見るには、次を実行します。
codex-router discover-models PROVIDER
そのうえで、Codex に表示するものを選びます。
codex-router curate-models PROVIDER
カタログを変えたら Codex を再起動します。上流の API が受け付けるとしても、推測でモデル ID を追加することはしません。Codex には、コンテキスト長、推論の設定、入力の種類、検索、ツールの使用についての正しいメタデータも必要です。
実際に動かして確かめるために、Codex Router には明示的なテストコマンドがあります。
codex-router test-model PROVIDER/MODEL --live --yes --quick
これは本物のリクエストを送るので、料金がかかることがあります。--live と --yes の両方が必要なので、うっかり有料のテストを始めてしまうことはありません。
よくある問題
メニューにルーティングされたモデルがひとつも出てこないときは、codex-router providers でプロバイダーが有効になっていて、ログインも済んでいるかを確認します。それから codex-router doctor を実行し、Codex を完全に再起動して、作り直されたカタログを読ませます。
モデルは返事をするのにアプリのツールを使えないときは、doctor の出力にある管理対象のスキルパックを見てください。ブラウザー操作やコンピューター操作用のドライバーを別に入れても解決しません。ルーティングされたモデルは Codex から渡されたツール名を呼ぶもので、名前空間の変換はルーターが受け持ちます。
モデルはメニューに出るのにリクエストが失敗するときは、プロバイダーとモデルの組み合わせを正確に確かめます。使えるモデルは API、サブスクリプション、地域によって違うことがあります。私はまず discover-models を実行し、そのプロバイダーの課金の仕組みを確認してから、小さなテストを送るようにしています。
ルーターの署名付きローカル URL を書き換えたり、内部の認証情報を別の設定ファイルにコピーしたりはしないでください。管理対象の Codex 連携が壊れたら、ガイド付きセットアップをもう一度実行するか、codex-router enable を使います。
更新・削除する
アップグレードするには次を実行します。
brew upgrade codex-router
削除するときは、先にユーザー単位のサービスを止めて管理対象の Codex 設定を元に戻し、それから formula をアンインストールします。
codex-router uninstall
brew uninstall codex-router
順番が大事です。パッケージは Homebrew が管理していますが、ユーザー単位のサービスとセットアップ時に変更した Codex の設定は Codex Router の管理下にあります。