Codex Subagent

codex-subagent-mcp

同じマシン上で実行される OpenAI の Codex CLI に、Claude Code からコーディングタスクを委任できる MCP サーバーです。モデルと推論の深さはタスクごとに選択できます。Claude はオーケストレーターのままです。Codex は Claude が呼び出せるサブエージェントになります。

独立したプロジェクトです。OpenAI または Anthropic とは提携、推奨、支援関係にありません。

クイックスタート

Node.js 22 以降と、インストール済みで PATH にあり、サインイン済みの Codex CLI が必要です。

claude mcp add codex-subagent -- npx -y codex-subagent-mcp

不足しているものがあれば、Claude に codex_doctor を実行するよう依頼してください。プラットフォームのセットアップ、Claude Desktop やその他のインストール方法については docs/INSTALL.md を参照し、書き込みを有効にする前に安全性を確認してください。

利用できる機能

• Codex CLI がリアルタイムで報告するカタログから、タスクごとにモデルと推論の強さを選べます。
• デフォルトでは読み取り専用で、どのツール呼び出しも超えられないサンドボックスの上限があります。
• 委任の完了ごとに、指定したモデル、推論の強さ、サンドボックス、ディレクトリと、Codex が実行時に記録した内容を照合し、異なる場合や確認できなかった場合に通知します。
• output_schema を指定すると、スキーマに一致した JSON が返されるため、Claude が結果をそのまま利用できます。
• キャンセル、タイムアウト、またはシャットダウン時には、Codex とサーバーが追跡できる起動済みコマンドを停止します。そのプロセスツリーから切り離されたコマンドは、実行を続けることがあります。

2026-09-30 に取得した、パッケージ名を尋ねる実際の読み取り専用委任の例です。

codex-subagent-mcp
Commands run (1 total):
- [exit 0] /bin/zsh -lc "sed -n '1,80p' package.json"
model=gpt-5.6-luna | effort=low | sandbox=read-only | working_dir=/Users/you/project | applied=confirmed | duration=8s | tokens=in 35701 (cached 28160, uncached 7541) / out 88 (reasoning 9) | thread_id=01a0f419-9fd2-79e2-8248-91436f04e297

これが必要な理由

1 つのモデルですべてを行うと、繰り返し起こる問題が 3 つあります。委任によって、それぞれを解決できます。

コンテキストウィンドウには限りがあります。 1 つの質問に答えるために Claude に 40 個のファイルを読ませると、実際の作業に必要なコンテキストを消費します。調査を委任すれば、40 個のファイルではなく答えが返ってきます。

1 つのモデルには、1 組の盲点しかありません。 セカンドオピニオンは、異なるモデルファミリーから得られるときに最も価値があります。トレーニングも失敗のパターンも異なるからです。同じモデルに 2 度尋ねても、ほとんどの場合、同じ答えが 2 度返ってくるだけです。

すべてのタスクに同じ推論予算が必要なわけではありません。 変数名の変更と競合状態の診断は、同じ仕事ではありません。ここではそれぞれを個別に調整できます。モデルは基本的な能力を決め、推論の強さはどれだけ長く検討するかを決めます。簡単な作業は高速なモデルに任せ、難しい問題には、必要なだけ高性能なモデルに考えさせます。

このサーバーはお使いのマシン上で動作し、すでにインストール済みの Codex CLI を操作します。サーバー自体は認証情報を保持しません。プロンプトは Codex を通じて OpenAI に届きます。これは、ご自身で codex を実行する場合と同じです。

他の Codex MCP サーバーとのバージョンごとの比較については、比較を参照してください。

使い方

範囲を限定して委任する

コマンドを繰り返し実行して出力が増えると、後続のリクエストに引き継がれるコンテキストも増え、委任のコストが高くなります。質問、対象となる可能性が高いファイル、終了条件、回答に含めるべき根拠を明確にし、習慣ではなく曖昧さに応じて高い推論の強さを選んでください。 委任の書き方 では、実測に基づくコストモデル、優先順位付きのルール、実際のツールパラメーターを使った不十分な例と適切な例を紹介しています。背景情報は context に、ペルソナや追加ルールは system_instructions に記述します。どちらも組み込みの品質基準に追加されます。詳細はツールリファレンスを参照してください。

別のモデルファミリーからセカンドオピニオンを得る

ここで重要なのは、もう一度実行することではなく、異なる盲点を持つモデルに依頼することです。

Codex に src/server.ts の正確性の問題をレビューさせ、エラー経路に重点を置いてください。高い 推論努力を指定し、各指摘について該当行と重要な理由を報告するよう伝えてください。

このようにレビューを委任したところ、このリポジトリ独自のランナーにある terminate() の欠陥が見つかりました。2 つのコードパスでそれぞれタイマーを設定できる一方、クリアされるのは一方だけでした。

コンテキストを消費せずに調査する

40 個のファイルを委任し、返ってくるのは回答 1 つです。Codex は独自に検索し、必要なものを読み込みます。会話に届くのは結論だけです。

MCP ツール呼び出しから Codex CLI に渡される引数まで、推論努力がどのように引き継がれるかを Codex に追跡させ、呼び出しチェーンだけを報告するよう指示してください。

作業をバックグラウンドで実行しながら、作業を続ける

src/jobs.ts のユニットテストを作成する Codex の実行をバックグラウンドで開始し、その間、API レイヤーの作業を続けてください。

すぐに job_id が返されます。必要なときにいつでもステータスを確認し、完了したら結果を読めます。一度に最大 8 件まで実行できます。CODEX_SUBAGENT_MAX_BACKGROUND_JOBS を設定すると、この上限を引き下げられます。ジョブの作成前にキャンセルされたバックグラウンドリクエストは、何も開始しません。

難問 1 つに深い推論を使う

会話全体の推論努力を引き上げるとコストがかかります。1 回の委任だけ引き上げるのであれば、そうではありません。

この断続的なテスト失敗に、これまで 2 回も悩まされています。最大の推論努力で根本原因を究明するよう Codex に依頼してください。test/runner.test.ts と CI ログを渡し、変更は一切加えないよう伝えてください。まずは診断が必要です。

やり取りを続ける

2 つ目の指摘を詳しく説明するよう Codex に依頼してください。

フォローアップでは Codex のコンテキストが再利用されるため、最初の依頼に比べてコストはわずかです。再開時に Codex 自体はモデル、推論努力、ディレクトリを保持しないため、サーバーはフォローアップのたびに同じ内容を再度伝えます。

必要なときは、変更も任せる

最初の 2 つの提案を Codex に適用させてください。ファイルの編集を許可しますが、作業ツリーをクリーンな状態に保てるよう、git worktree 内で作業させてください。

use_worktree を指定すると、実行による変更は ~/.codex/worktrees/ に送られます。結果には Codex が報告したファイル変更と、それぞれが反映された場所が最大 1,000 件まで表示され、その後に省略件数が示されます。また、worktree とその作成元コミットを示す行も含まれます。Codex には事前に、未コミットの変更、未追跡ファイル、インストール済み依存関係などの無視対象ファイルは含まれないと伝えられます。サーバーは worktree をクリーンアップしないため、未適用の作業が残っていることがあります。この実験的な機能が有効になるのは、その実行中だけです。Codex の設定は変更されません。フォローアップは同じ worktree で続行されます。Codex のセッションファイルから場所を確認できなかった場合、フォローアップでは作業ツリー内で再開するのではなく、working_dir を指定するよう求めます。書き込み範囲については安全性を参照してください。

サンドボックスの種類にかかわらず、書き込みを行う委任では、Codex が記録したファイル変更が報告されます。これは Codex による報告であり、ディスクの差分ではありません。

Files changed (2):
- [edit] src/codex/runner.ts
- [add] test/runner.test.ts

安全性

このサーバーはお使いのマシン上で別のプログラムを実行するため、書き込みを有効にする前に 2 分ほど確認しておく価値があります。

保護される内容

委任はデフォルトで読み取り専用です。書き込みには、明示的な sandbox: "workspace-write" またはユーザーが設定したデフォルトが必要です。use_worktree を使うと、編集内容はチェックアウトではなく、管理対象の git worktree に送られます。サンドボックスと add_dirs によって、書き込み可能な範囲も制限されます。この制限を超える、サンドボックスなしでの実行は、明示的に許可しない限り利用できません。

制限を行うのは、オペレーティングシステム自体のサンドボックスです。macOS では Seatbelt、Linux と WSL2 では bubblewrap、Windows ではネイティブサンドボックスが使われます。この表は macOS で測定したものです。測定の詳細は SECURITY.md に記録されています。ここでは Linux と Windows の測定は行っていません。また、OpenAI の Windows ドキュメントには、サンドボックス化されたコマンドでは一部のディレクトリを読み取れない場合があると記載されているため、読み取りの制限はさらに厳しくなる可能性があります。

	read-only	workspace-write	danger-full-access
作業ディレクトリ内への書き込み	いいえ	はい	はい
作業ディレクトリ外（ホームディレクトリ）への書き込み	いいえ	いいえ	はい
ネットワークアクセス	いいえ	いいえ	はい
作業ディレクトリ外の読み取り	はい	はい	はい

サーバーは実行のたびにサンドボックスモードを選択します。ネットワークアクセスや書き込み可能な追加のルートなど、Codex 自体の sandbox_workspace_write 設定は上書きされず、workspace-write でも引き続き適用されます。この表は Codex のデフォルトを示しています。

サンドボックスが制限するのは、Codex がシェルで実行するコマンドです。MCP ツールやプラグインツールは制限されません。これらは、ネットワークも含め、アカウントの全権限を持つ独自のプロセスとして実行されます。また、read-only では、読み取り専用と宣言されたツールは承認なしで実行されます（codex-cli 0.159.2 で測定、ADR 16）。そのため、サーバー設定で許可しない限り、委任では Codex の設定から MCP サーバー、プラグイン、アプリは一切継承されません。また、すべての委任結果には、実行時に許可されていた内容を示す行が含まれます。

サーバーの呼び出し経路にシェルはありません。CLI は argv 配列で起動され、プロンプトは stdin に書き込まれます。コマンド文字列に埋め込まれることはありません。プロンプト内のシェルのメタ文字は無効です。

保護されない内容

読み取りは制限されません。 どのモードでも Codex は、ユーザーアカウントで読み取り可能なあらゆるものを読み取れます。SSH キーやクラウド認証情報も対象です。これは macOS で測定されていますが、どのプラットフォームでもそうであると想定するのが安全です。サンドボックスによってネットワークアクセスが遮断されているため、それらをどこかへ送信することはできません。しかし、レポートはあなたに返されるため、そこが情報の伝達経路になります。

プロンプトは信頼できない入力であり、Codex はその内容に従って動作します。 あなたが書いていない内容、たとえばイシュー本文、Web ページ、ログ、他者のリポジトリのファイルなどに、指示が含まれている場合があります。workspace-write では、その指示によって Codex がリポジトリを変更する可能性があります。読み取り専用であっても、機密情報を読み取り、回答に含めるよう指示される可能性があります。サンドボックスが制限するのは、Codex が書き込める場所です。何を書き込むべきか、その理由を判断するわけではありません。これはプロンプトインジェクションであり、ここで重要なリスクです。

結果はサニタイズされません。 返されるのは、ファイルを読み取ったばかりのモデルによるテキストです。指示ではなくデータとして扱い、依頼どおりに実行したと思い込まず、委任で実行された内容を確認してください。

リスクの軽減

• 組み込みのデフォルト設定はそのままにします。読み取り専用でも、調査、レビュー、診断など、委任の大半を担えます。
• 書き込みを一切許可したくない場合は、上限を設定します：CODEX_SUBAGENT_MAX_SANDBOX=read-only。どの会話でも、この上限を超えることはできません。設定はリポジトリの外部に登録します（Claude Code のデフォルトの local スコープ、--scope user、または Claude Desktop の設定）。書き込み可能な委任によって編集される可能性のある、プロジェクトの .mcp.json には登録しないでください。Configurationを参照してください。
• 書き込みを有効にする場合は、use_worktree も追加して、変更がブランチに反映される前に確認できる場所に保存されるようにします。
• MCP サーバー、プラグイン、アプリを委任で許可するのは、タスクに必要な場合に限り、名前を指定して許可します。許可されたものはサンドボックスの外で実行され、auto_approve を有効にすると、そのツールは一切の承認なしで実行されます。
• 回答に基づいて操作するつもりなら、信頼できないコンテンツから委任用のプロンプトを組み立てないでください。
• この脅威が深刻な懸念となる場合は、秘密情報にアクセスできないアカウントまたはコンテナで Codex を実行してください。これは制限を設けるのではなく、根本から解決します。

SECURITY.mdには、脅威モデルの全容、deny_read ポリシーで追加できる対策、脆弱性の報告方法が記載されています。

設定

すべて任意で、MCP サーバーの環境変数を通じて設定します。

Variable	Values	Default	Effect
CODEX_SUBAGENT_DEFAULT_MODEL	list_codex_modelsのスラッグ	CODEX_SUBAGENT_ALLOWED_MODELSにエントリが1つだけある場合はその値、それ以外の場合、モデルを指定しない呼び出しは候補の提示とともに拒否されます	呼び出しでモデルを指定しない場合に使われるモデルです。
CODEX_SUBAGENT_DEFAULT_EFFORT	none、minimal、low、medium、high、xhigh、max、ultra	モデルのデフォルト	呼び出しで指定しない場合に使われる推論レベルです。
CODEX_SUBAGENT_ALLOWED_MODELS	list_codex_modelsのスラッグをカンマ区切りで指定	制限なし	これ以外の値は拒否されます。エントリが1つだけの場合は、デフォルトのモデルとして使われます。空のエントリ（a,,bや末尾のカンマ）は設定エラーです。
CODEX_SUBAGENT_DEFAULT_SANDBOX	read-only、workspace-write、danger-full-access	read-only	呼び出しで指定しない場合に使われるサンドボックスです。上限を超えることはできません。
CODEX_SUBAGENT_MAX_SANDBOX	read-only、workspace-write、danger-full-access	workspace-write	これを超える呼び出しは拒否されます。danger-full-accessには明示的なオプトインが必要です。
CODEX_SUBAGENT_MAX_EFFORT	none、minimal、low、medium、high、xhigh、max、ultra	制限なし	より高い推論レベルは、対応するレベルに引き下げられます。該当するレベルがない場合は拒否されます。
CODEX_SUBAGENT_MAX_DELEGATIONS_PER_HOUR	1～9007199254740991の10進整数	制限なし	サーバープロセスごとに、ローリング1時間あたりの委任プロセスと後続プロセスの起動数を制限します。プローブはカウントされません。
CODEX_SUBAGENT_MAX_BACKGROUND_JOBS	1～8の10進整数	8	実行中のバックグラウンドジョブ数の上限を引き下げます。ブロッキング呼び出しには適用されません。
CODEX_SUBAGENT_MCP_SERVERS	none、all、またはサーバー名をカンマ区切りで指定	none	委任が引き継ぐ、Codex の設定に含まれる MCP サーバーです。再帰ガードにより、このサーバーは各委任で無効になります。allの指定時に MCP の一覧取得に失敗した場合、またはこのサーバー自体の名前にドットか=が含まれる場合は、結果にガードが適用されなかったことが示されます。
CODEX_SUBAGENT_PLUGINS	none、all、またはプラグイン ID（name@marketplace）をカンマ区切りで指定	none	委任が引き継ぐ、インストール済みの Codex プラグインと、それらが提供する MCP サーバーです。
CODEX_SUBAGENT_APPS	on、off	off	委任が Codex のアプリ（外部サービスへのコネクター）を引き継ぐかどうかを指定します。
CODEX_SUBAGENT_USAGE_LOG	on、off	off	起動した委任の使用回数をローカルに追記します。codex_usageで読み取れます。プロンプト、コード、パスは記録されません。ラベルは呼び出し元が指定したテキストです。
CODEX_BIN	実行ファイル名またはパス。Windows では、.cmdや.batのシムではなく、直接実行可能なファイルを指定	PATH上のcodex	CLI の解決方法を上書きします。Installationを参照してください。
モデルは一部の推論レベルに対応しています。対応していない推論レベルは、注記を付けて最も近い対応レベルに調整されます。完全な仕様については docs/TOOLS.md#configuration を、安全境界については Safety を参照してください。

すべての CODEX_SUBAGENT_* の値は前後の空白が削除され、大文字と小文字が区別されます。空の値は未設定として扱われます。上限や許可リストに反する値は、設定エラーになります。数値の上下限には ASCII 数字のみを使用でき、先頭のゼロは許容されます。無効な値の場合、委任は拒否され、その値は codex_doctor に表示されます。これらの上限を引き上げられるのは、あなただけです。1 時間のウィンドウはメモリ上に保持され、再起動時にリセットされます。また、使用状況ログとは独立しています。起動された各実行は、失敗、タイムアウト、キャンセルの場合も含めて、60 分間カウントされます。保留中の呼び出しは、プローブを実行する前にスロットを確保し、起動されなかった場合はスロットを解放します。拒否された場合、カウント対象のプロセスがあれば、そのうち最も古いプロセスの有効期限（UTC）と残り時間が示されます。まだ起動されたプロセスがない場合は、許可済みの呼び出しの結果が返るまで待つよう求められます。codex_doctor は、両方の上下限、現在のウィンドウ内で起動されたプロセス数、起動前にスロットを確保している呼び出し数を報告します。

Claude は委任するタイミングを判断します。サーバーを利用できる会話では、実行ごとにプロンプトが OpenAI に送信され、Codex の使用量が消費されます。docs/CONTROL.md では、クライアントの権限プロンプト、サーバーの上限、バージョン範囲、独自の CLAUDE.md によるエスカレーションルールについて説明しています。これらのルールはあなた自身が定めるものです。ポリシーの分離については、ADR 12 と ADR 14 を参照してください。

接続時にサーバーの指示で、登録ごとのサンドボックス上限とデフォルト、設定されたモデルと推論レベルのデフォルト、委任時に引き継げる継承ツールの種類が示されます。そのため、オーケストレーターはツールの説明を読み込む前に、ポリシーの異なる登録を区別できます。設定に誤りがある登録では、委任ツールが呼び出しを拒否することと、codex_doctor の参照先が示されます。フォールバック値は提示されません。

モデルの選択

インストール済み CLI の最新カタログを取得するには、list_codex_models を使用してください。モデルと推論レベルは独立しています。モデルは基本的な能力を決定し、推論レベルはどれだけ時間をかけて推論するかを決定します。ultra はサブタスクも自動的に委任します。

サーバーがモデルを選ぶことはありません。 タスクに使用するモデルは、予算と、誤った回答がどれほど大きなコストになるかに応じて決まります。呼び出しまたは設定にモデルが指定されていない場合、サーバーは拒否し、選択するよう促す推奨を返します。

設定済みまたは暗黙のデフォルトがない場合、codex_delegate の説明は、Claude にまず codex_recommend を呼び出し、推奨されたモデルと推論レベルを伝えてから、両方を明示して委任するよう指示します。CODEX_SUBAGENT_DEFAULT_MODEL が設定されている場合、または CODEX_SUBAGENT_ALLOWED_MODELS にモデルがちょうど 1 つ含まれている場合は、代わりに model を省略してデフォルトを適用するよう指示します。設定エラーがある場合は、推奨に関する案内が維持されます。これはモデルへの案内であり、強制ではありません。助言を求めるには、「このリポジトリのテストを vitest に移行するには、どの Codex モデルが適していますか？」と尋ねてください。推奨内容には、モデルの許可リストと推論レベルの上限が反映されます。推奨機能のリファレンスを参照してください。

以降の委任でこの手順を省略するには、list_codex_models からデフォルトを一度設定してください。

claude mcp add codex-subagent -e CODEX_SUBAGENT_DEFAULT_MODEL=gpt-5.6-terra -- npx -y codex-subagent-mcp

ツール

ツール	機能
codex_doctor	Codex CLI のインストールを確認し、修正方法を報告します。extended: true を指定すると、時間がかかるネットワーク接続を伴う config.load レポートを取得できます。
list_codex_models	利用可能なモデルと、それぞれの推論強度レベルを一覧表示します。
codex_recommend	説明されたタスクに適したモデルと推論強度を提案します。
codex_delegate	タスクを同期またはバックグラウンドで実行します。任意で、スキーマに一致する JSON を返します。
codex_follow_up	thread_id を使って、スキーマの有無を問わず、以前の委任タスクを続行します。
codex_job_status	バックグラウンドの委任タスクの状態を確認します。
codex_job_result	完了したバックグラウンドの委任タスクの出力を読み取ります。
codex_job_cancel	実行中のバックグラウンドの委任タスクを停止します。
codex_usage	オプトイン方式のローカル使用状況ログを期間で集計し、モデル、ラベル、結果、または種類ごとにまとめます。

パラメーターの詳細については、docs/TOOLS.md を参照してください。

FAQ

費用はかかりますか？ 自分で codex を実行する場合と同様に、既存の Codex クォータを使用します。このサーバーによる追加費用はなく、費用を確認することもできません。推論強度を上げるほど消費量が増え、ultra はサブタスクも委任します。codex_recommend を使うと、low の作業に ultra を使ってしまうのを防げます。

OpenAI API を呼び出さずに CLI を操作するのはなぜですか？ コーディングの委任は、単一の補完ではありません。サンドボックス、承認モデル、セッションの永続化、プロジェクトの指示ファイルを伴うエージェント型のループです。これらはすべてモデルのエンドポイントではなく、Codex クライアントに備わっています。ADR 1 を参照してください。

Claude Code が必要ですか？それとも Claude Desktop でも使えますか？ どちらでも使えます。Claude Code ではインストールを 1 行で実行できます。Claude Desktop では設定を手動で追加する必要があります。

ターミナルでは codex が動くのに、Codex がインストールされていないと表示されます。 Windows で npm を使ってグローバルインストールした場合に発生することが多く、起動にコマンドシェルが必要な codex.cmd バッチシムが作成されます。codex_doctor はこれを unsupported-shim として報告し、2 つの修正方法を提示します。macOS と Linux では、Node のバージョンマネージャーによって codex が PATH から外れていないか確認してください。

Windows と Linux でも動作しますか？ 変更のたびに CI で Windows、macOS、Linux 上でサーバーのビルド、テスト、起動を行い、それぞれの環境で Codex CLI が正しく解決されることを確認しています。実際の委任タスクを検証できているのは macOS のみです。CI ランナーには Codex がインストールされておらず、認証情報もないためです。Windows と Linux での動作報告を歓迎します。Windows では npm ではなく PowerShell インストーラーで Codex CLI をインストールしてください。Linux では Codex のサンドボックス用に bubblewrap をインストールしてください。インストールを参照してください。

ドキュメント

• docs/INSTALL.md — インストール、プラットフォームに関する注意事項、トラブルシューティング。
• docs/CONTROL.md — 権限、上限、Claude が委任するタイミング。
• docs/DELEGATING.md — 委任タスクの範囲の決め方、測定済みの費用、プロンプトの実例。
• docs/TOOLS.md — すべてのツールとパラメーター。
• docs/COMPARISON.md — 他の Codex MCP サーバーとのバージョン別比較。
• docs/adr/ — 設計の理由を、決定ごとに説明しています。
• docs/ROADMAP.md — 今後の計画と、意図的に対象外としている項目。
• Issues — 現在実際に未解決となっている課題。
• docs/VERSIONING.md — このプロジェクトで破壊的変更と見なされるもの。
• CHANGELOG.md — 各リリースでの変更点と、検証に使用した Codex CLI のバージョン。
• CONTRIBUTING.md — セットアップと、交渉の余地のないルール。

免責事項

公式製品ではありません。 これは独立したコミュニティプロジェクトです。OpenAI または Anthropic との提携、推奨、後援、サポートを受けていません。「Codex」、「ChatGPT」、「OpenAI」は OpenAI の商標であり、「Claude」と「Claude Code」は Anthropic の商標です。これらは、このソフトウェアが連携する対象を説明するためにのみ使用しており、これは名目的な使用です。これらの商標に対する権利を主張するものではありません。いずれの会社もこのソフトウェアに責任を負いません。問題が発生した場合は、各社ではなくこちらに報告してください。

保証なし。 LICENSE に記載されているとおり、このソフトウェアは「現状有姿」で提供され、いかなる種類の保証もありません。ご自身の責任でご利用ください。

書き込みを有効にする前に安全性をお読みください。委任によって、ご自身の Codex の利用枠が消費されます。

ライセンス

MIT。LICENSEをご覧ください。