ChatGPT / Codex

codex プロバイダーは、マッピングされたモデルの推論を、API キーではなくあなたの ChatGPT / Codex サブスクリプションへルーティングします。Codex CLI がすでに ~/.codex/auth.json に書き込んだ認証情報を再利用するため、貼り付けるものは何もなく、トークン単位の課金もありません — リクエストはあなたの ChatGPT アカウントとして認証され、codex CLI が話すのと同じバックエンドによって応答されます。

このページはエンドツーエンドのセットアップです。各トピックを繰り返すのではなく、より深いトピックページ（Effort & Context、Model Discovery、Providers）へリンクします。

クイックスタート

コーディングエージェントにセットアップを任せることもできます。shunt add はこのプロバイダーのセットアップ用ブループリントを出力します（オフラインかつ読み取り専用で、設定を編集するのはエージェントです。このコマンド自体は編集しません）。

shunt add upstream codex --print | claude

または、以下の手順に沿って手動で設定してください。

仕組み

codex は組み込みの kind = "responses" プロバイダーです。shunt は Claude Code の Anthropic Messages リクエストを OpenAI Responses API へ変換し、ChatGPT アカウントの Codex バックエンドへ送信し、ストリーミングされる応答を変換して返します。これを単なる OpenAI ではなく「Codex」たらしめているのは、次の 3 点です。

この方言はプロバイダー名ではなく auth = "chatgpt_oauth" によってキー付けされます。

Codex アカウントをプールすると、成功したバックエンド応答の x-codex-* レート制限ウィンドウが管理画面の Pool health にも表示されます。約 5 時間のウィンドウは 5h、約 7 日のウィンドウは 7d に表示され、日次・月次など未対応のウィンドウは無視されます。Codex には 7d_oi 相当はありません。記録されたウィンドウはクォータを考慮したプール選択にも供給されます — Codex マルチアカウントを参照してください。

1. ログイン

Codex CLI で一度ログインします。shunt は書き込まれたファイルを読み込み、リフレッシュします — Codex 用に独自のログインを実行することはありません。

codex login

これにより ~/.codex/auth.json が作成されます。そのファイルが存在しないか、トークンがないか、リフレッシュトークンが失われている場合、shunt は authentication_error を返し、再度 codex login を実行するよう伝えます。

2. プロバイダーブロック（オプション）

codex は組み込みです — 宣言する必要はありません。以下が完全なデフォルトです。部分的なテーブルは、設定したキーだけをオーバーライドします（設定マップはディープマージします）。

[providers.codex]
kind = "responses"
base_url = "https://chatgpt.com/backend-api"   # shunt appends /codex/responses
auth = "chatgpt_oauth"                          # read + auto-refresh ~/.codex/auth.json
# effort = "high"                               # optional default reasoning effort (§4)
# count_tokens = "tiktoken"                      # default; "estimate" opts out

よくあるオーバーライド: すべての Codex トラフィックに対してデフォルトの effort を固定する、または count_tokens = "estimate" を設定する。api_key_env / api_key_header は chatgpt_oauth には適用されません — 認証情報は認証ファイルから来ます。すべてのキーについては Configuration Reference を参照してください。

3. モデルを codex へルーティングする

リクエストの model id がプロバイダーを選びます。優先順位: 一致する [models.upstream_model] エントリ → 厳密な [[routes]] → [[route_prefixes]] → server.default_provider。

[[routes]]
model = "gpt-5.6-sol"        # the id Claude Code sends (see §4 below)
provider = "codex"
# upstream_model = "gpt-5.6-sol"   # optional: forward a different slug upstream
# effort = "high"                  # optional: pin effort for this route

upstream_model により、Claude Code が送る id とバックエンドが受け取るスラッグを別にできます — これは discovery エイリアスの背後にある仕組みであり、Claude Code の環境に触れずに実際のスラッグを差し替える方法でもあります。

4. Claude Code でモデルを選択する

Claude Code の /model ピッカーは claude/anthropic で始まる discovery id のみを尊重するため、生の gpt-* id には 2 つのパスのいずれかが必要です — それらは claude- プレフィックスで分かれ、重複しません。

主なパス — スラッグをピッカーに直接追加する:

export ANTHROPIC_CUSTOM_MODEL_OPTION="gpt-5.6-sol"

その id はまさに shunt がルーティングに使うものなので、一致する [models.upstream_model] エントリ、[[routes]]、または [[route_prefixes]] ルールで解決される必要があります。これが推奨パスです — 正確なコンテキストウィンドウも設定できる唯一のパスです。代わりに複数の Codex モデルをピッカーに自動リストするには、claude- 命名の discovery エイリアスを使います（200k ウィンドウのトレードオフを受け入れる）。

サブエージェントを Codex スラッグに乗せる

サブエージェントは、メインセッションが Claude のまま残る一方で、Codex スラッグ上で走れます。model: フロントマターフィールドは任意の文字列を受け入れます（Agent/Task ツールの model パラメータとは異なり、後者は組み込みエイリアスのみを取ります）。既存のサブエージェントを gpt-5.6-sol に向けるには、その .claude/agents/<name>.md を編集し model: を設定します。

---
name: researcher
description: Deep research agent.
model: gpt-5.6-sol        # was: sonnet (or absent → inherited)
---

<the agent's system prompt — unchanged>

model オーバーライドなしでスポーンします（ツールパラメータがフロントマターより優先されます）。解決順序: CLAUDE_CODE_SUBAGENT_MODEL > ツールの model > フロントマター > inherit。すべてのサブエージェントを 1 つのスラッグに強制するには、export CLAUDE_CODE_SUBAGENT_MODEL="gpt-5.6-sol" を設定します。

いずれの場合も、スラッグは一致する [models.upstream_model] エントリ、[[routes]]、または [[route_prefixes]] ルールによる明示的なルーティングが必要で、非 claude- であるため CLAUDE_CODE_ALWAYS_ENABLE_EFFORT=1 と CLAUDE_CODE_MAX_CONTEXT_TOKENS に従います — ウィンドウは id に自動的に追随します。

tier エイリアスを Codex へリマップする

1 つのカスタム id を追加する代わりに、Claude Code の組み込み tier エイリアスを Codex スラッグへ再度向けることで、セッション全体の tier システムをあなたの ChatGPT サブスクリプションへ解決させます （model-config 環境変数）。

2 段階のセットアップ — haiku → gpt-5.6-luna、sonnet → gpt-5.6-sol:

export ANTHROPIC_DEFAULT_HAIKU_MODEL="gpt-5.6-luna"
export ANTHROPIC_DEFAULT_SONNET_MODEL="gpt-5.6-sol"

# nicer picker labels (the _NAME/_DESCRIPTION companions work on a gateway)
export ANTHROPIC_DEFAULT_SONNET_MODEL_NAME="GPT-5.6-Sol"
export ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION="ChatGPT/Codex Sol via shunt"
export ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME="GPT-5.6-Luna"
export ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION="ChatGPT/Codex Luna via shunt (background tier)"

# shunt.toml — both resolved ids need a route
[[routes]]
model = "gpt-5.6-luna"
provider = "codex"

[[routes]]
model = "gpt-5.6-sol"
provider = "codex"

/model で Sonnet を選ぶと Codex 経由で gpt-5.6-sol が走り、すべてのバックグラウンド/haiku タスクは gpt-5.6-luna が走ります — 解決された id はまさに shunt がルーティングに使うものなので、 ANTHROPIC_CUSTOM_MODEL_OPTION は不要です。

5. 推論エフォート

エフォートは Claude Code の通常のコントロール（/effort、/model のスライダー、--effort）で設定します。shunt はそれを Responses の reasoning.effort へマッピングし、max をサポートしないスラッグでは max → xhigh に折りたたみます（サポートするのは gpt-5.6 と gpt-6 ファミリーのみ）。

完全な優先順位とエフォートの表: Effort & Context。

Fast モード

Codex CLI の /fast トグルはモデルやエフォートの変更ではありません。Responses API のトップレベルフィールド service_tier: "priority" を送るもので、このティアは「Fast」（使用量が増える代わりに応答が速くなる）と呼ばれます。 shunt は同じノブを設定キーとして公開しており、effort とまったく同様に、プロバイダーレベルとルートレベルの両方で設定できます。

[[routes]]
model = "gpt-5.6-sol"
provider = "codex"
# service_tier = "priority"   # 任意: Codex の「Fast」モードを有効にする

受け入れる値は fast（レガシーエイリアスで、priority に正規化されます）、priority、flex、default （クライアント専用のセンチネルで、ワイヤーには決して送られません）です。デフォルトはオフで、明示的に設定した ときだけ送られます。effort と同じく、ルートレベルの値がプロバイダーレベルのデフォルトより優先されます。ルートを 明示的に default に設定すると、プロバイダーレベルの priority/flex ティアを継承せず、そのルートだけを 除外できます。すべてのキーについては Configuration Reference を参照してください。

Codex CLI 自体は gpt-6-sol と gpt-6-luna のデフォルトを Fast（priority）にしています。これらの models.json エントリが default_service_tier を設定しているためです。これはバックエンドが適用しない クライアント側のデフォルトなので、このガイドで設定する Claude Code のルートでは、service_tier = "fast" を 設定しない限りこれらのモデルは標準ティアで動作します。shunt に接続した Codex CLI は異なります。そのエンドポイントはリクエストをそのまま転送するため、CLI が自身で送るティアが保たれます。

実際にワイヤーに載ったティアは、Codex CLI の x-codex-routing-hint ヘッダーでもバックエンドへ伝えられます。 形式は model=<upstream model>;tier=<tier> です（ティアを送らない場合は model=<upstream model> のみ）。shunt は Codex CLI と同じく、ChatGPT OAuth パスでのみこのヘッダーを送ります。HTTP リクエストではリクエストヘッダーとして、 WebSocket トランスポートではハンドシェイクヘッダーとして送ります。プレフィックスルートや default_provider 経由では upstream モデルがクライアント自身の model 文字列になるため、ヘッダーは防御的に組み立てられます。 妥当なスラッグ（空でなく、128 バイト以下で、ASCII の英数字と - _ . : / + のみを含む）の場合だけ 送り、それ以外はヘッダーだけを落としてリクエストはそのまま送ります。

6. コンテキストウィンドウ

Claude Code はマッピングされた id に対して、コンテキストバーを固定の 200k でサイズします。gpt-5.6-sol の実際のウィンドウは 372k です（gpt-5.5 は 272k）。したがって、非 claude- id にはこれを引き上げてください。

export CLAUDE_CODE_MAX_CONTEXT_TOKENS=372000

これはグローバル（セッションごとに 1 つの値）で、実際のウィンドウより大きく設定すると prompt is too long のオーバーフローによる無駄なやり取りが発生します — マッピングされたモデルのうち最も小さい実ウィンドウに合わせてください。shunt はそのオーバーフローを書き換えて Claude Code が自動コンパクトして再試行するようにしますが、各ラウンドトリップは無駄なレイテンシです。詳細、ライブ検証された境界、count_tokens の挙動: Effort & Context。

完全な例

shunt.toml:

[server]
bind = "127.0.0.1:3001"
default_provider = "anthropic"

[providers.codex]
effort = "high"     # optional: pin high effort for all Codex traffic

[[routes]]
model = "gpt-5.6-sol"
provider = "codex"

シェル（shunt と Claude Code の両方をこれらで実行します）:

codex login                                          # one-time
./target/release/shunt run                           # start the gateway

export ANTHROPIC_BASE_URL=http://127.0.0.1:3001
export ANTHROPIC_CUSTOM_MODEL_OPTION="gpt-5.6-sol"   # add to /model picker
export CLAUDE_CODE_ALWAYS_ENABLE_EFFORT=1            # let the effort slider reach Codex
export CLAUDE_CODE_MAX_CONTEXT_TOKENS=372000         # gpt-5.6-sol's real window

/model から gpt-5.6-sol を選びます。セッション内のそれ以外のすべては引き続き変更なしで Anthropic へ流れます。マッピングされたモデルの推論だけが、あなたの ChatGPT/Codex サブスクリプションによって応答されます。

ウェブ検索

Claude Code の組み込み ウェブ検索 は、追加設定なしで Codex 経路で動作します。有効にすると Claude Code はホスト型の web_search_20250305 ツールを送り、shunt はそれを Responses API のホスト型 web_search ツールとして登録します。そのため検索は、未処理のツール呼び出しとして返されるのではなく、 バックエンドで実際に実行されます。

• ドメインフィルターはそのまま引き継がれます — Claude Code の allowed_domains / blocked_domains が Responses web_search の filters になります。
• codex(ChatGPT)および openai(標準 Responses)プロバイダーに適用されます。
• xAI / Grok ルートは非対応 — Grok の Responses API は関数ツールのみを受け付けるため、shunt は ホスト型ウェブ検索ツールを削除します。ウェブ検索には codex または openai ルートを使ってください。

ツール検索

Claude Code の ツール検索 — MCP / LSP のツールスキーマを遅延させ、ToolSearch ツールで必要なときだけ 明らかにすることで、呼び出さないツールにコンテキストを使わせない機能 — は Codex 経路で動作します。クライアント 側で有効化するには:

export ENABLE_TOOL_SEARCH=true

Claude Code は base URL がファーストパーティの Anthropic ホストでない場合、楽観的なツール検索を無効化します。 shunt はそれに該当しません。したがってこのフラグがないと、最初のターンからすべてのツールの完全なスキーマが アップストリームへ送られ、機能が無意味になります（動作はしますが、何も削減されません）。クライアント自身の 規約は、プロキシが tool_reference ブロックを転送するなら ENABLE_TOOL_SEARCH=true を設定せよ、 というものであり、shunt はこれを転送します。

有効にすると、shunt はすでにサポートが確認されているアップストリームに限り、ツール検索を OpenAI Responses API 自身の ネイティブなクライアント実行 tool_search プロトコルへマッピングし、それ以外のすべてでは #43 のテキストシムを維持します。Claude Code の ToolSearch ツールは tool_search（execution: "client"）ツールになり、その tool_use は tool_search_call になり、tool_reference の結果は ロードされたツールの完全なスキーマを構造化 JSON として運ぶ tool_search_output アイテムとなって input の末尾に追加されます。これが重要な理由は、代替手段 — 明らかにされたツールのスキーマをリクエストの tools 配列へ折り込み直すこと — が、明らかにするたびにキャッシュ済みプロンプトプレフィックスを無効化して しまうからです。tools はそのキャッシュ可能なプレフィックスの一部であり、shunt は毎ターン、クライアントの 履歴からそれを再導出します。配列が伸びるほど、バックエンドはツール境界以降の会話を再処理せざるを得なくなり ます。ネイティブプロトコルの追記オンリーな input 履歴は tools に触れないため、明らかにするたびにキャッ シュ済みプレフィックスは保たれます。

• codex と openai の組み込みプロバイダーのデフォルト（ネイティブ）動作のために shunt.toml を変更する 必要はありません — 純粋に ENABLE_TOOL_SEARCH レベルの Claude Code 環境変数です。
• kind = "responses" のプロバイダー全般に適用されます。ただし、あるプロバイダーがデフォルトでネイティブに なるかシムのままになるかはアップストリームのホストによって決まります — 下記の ネイティブプロトコル を参照してください。
• 遅延しないツール(および上記のホスト型 web_search ツール)は常に転送されます。段階的に明らかにされるのは 遅延可能なツールだけです。

ネイティブプロトコル

要件 — 非対応の組み合わせはエラーにならず、静かに #43 のテキストシムへフォールバックします。シムはまだ明らか にされていない遅延ツールを引き続き tools から除外しますが、Claude Code がツールを一つ明らかにすると、シム はその完全なスキーマを tool_reference テキストとしてレンダリングし、さらに そのツールを tools に再追加 してモデルが呼び出せるようにします — それ以降はスキーマが二重に送られることになり、明らかにするたびに上記の キャッシュ無効化コストを払います:

• アップストリームは標準の OpenAI または ChatGPT/Codex 系の Responses バックエンドである必要があります。 xAI / Grok ルートは常にシムのままです。
• ルーティング先のモデルは gpt-5.4 以降（gpt-5.4、gpt-5.5、または gpt-5.6 ファミリー）である 必要があります。正確なスラッグ gpt-6-astra、gpt-6-sol、gpt-6-luna、gpt-6.1-sol も対象です。それより前のスラッグ（gpt-5.2 以下）は tool_search の値に関わらずシムのままです。
• Claude Code 側で ENABLE_TOOL_SEARCH=true は引き続き必要です — このフラグは shunt がその機能をどう アップストリームへ変換するかだけを変えるもので、Claude Code がそもそもツールを遅延させるかどうかは 変えません。

tool_search は [providers.<name>] の下で三状態の設定です。未設定（デフォルト、「auto」）の場合、すでに tool_search アイテムの実装が確認されているホスト — ChatGPT/Codex バックエンド（組み込みの codex プロバイダー）と api.openai.com（組み込みの openai プロバイダー）— に対してのみネイティブへ解決され、 LiteLLM、vLLM、OpenRouter、自己ホストのプロキシを指すカスタムの kind = "responses" プロバイダーを含む それ以外のすべての OpenAI 互換エンドポイントではテキストシムへ解決されます。ほとんどのサードパーティ Responses バックエンドは tool_search アイテムを実装していないため、そこでネイティブを自動的に有効にする と、穏やかにフォールバックする代わりにターン自体が失敗してしまいます。ネイティブな形状は 2026-07-13 に gpt-5.6 で ChatGPT/Codex バックエンドに対してライブプローブで検証されており (pleaseai/shunt#86)、tool_search は gpt-5.4+ モデル 向けに公開 OpenAI Responses API のドキュメントにも記載されています。

プロトコルの実装を確認したカスタムエンドポイントをネイティブパスへオプトインするには tool_search = true を設定してください — 上記のフレーバー・モデル要件は引き続き適用されます:

[providers.my-litellm]
kind = "responses"
base_url = "https://litellm.internal/v1"
tool_search = true

デフォルトで（またはオプトインで）ネイティブパスを使うことになるプロバイダーでテキストシムを強制したい場合は tool_search = false を設定します:

[providers.codex]
tool_search = false

トラブルシューティング

さらに詳しくは完全な Troubleshooting リファレンスを参照してください。