はじめに（注意喚起）
本記事で紹介する方法は、コードからCodexCLIを呼び出す手法です。つまり、Codexセッションの中からさらに別のCodexセッションを起動することになり、当たり前ですがその分Codexの利用枠を消費します。
- サブスクリプションでCodexを利用している方：残りの利用枠にご注意ください
- API従量課金の方：課金額にご注意ください
今回のサンプルでは意図的に大量の利用枠を消費するような実装にはしていませんが、AIエージェントのトークン消費は事前に予測しづらいため、あらかじめご了承ください。
また、本記事で紹介する手法はベストプラクティスではありません。CodexSDKを利用して擬似的にClaudeCodeのサブエージェント機能を再現してみよう、という実験的な内容です。効率的な方法かどうかはわかりませんが、CodexCLIをより効果的に使うヒントにはなると思いますので、ぜひ読んでいただければと思います。
Codexにサブエージェントが欲しい
Codexはモデルの性能が高く、コーディング支援ツールとして非常に便利です。しかし、ClaudeCodeのようなカスタマイズ性がない点が惜しいところ。特にサブエージェントなどのコンテキストエンジニアリング関連の仕組みが弱いと感じていました。
そこで今回、Codexでもサブエージェント的な仕組みを実装してみようと思います。本記事では最低限のサンプルと仕組みを紹介しますので、これを参考にご自身でより良い設計を目指していただければ幸いです。
今回紹介する手法の概要
そもそもサブエージェントとは？
サブエージェントとは、メインのエージェントから呼び出される、特定のタスクに特化した小さなエージェントのことです。メインエージェントが「この作業は専門家に任せよう」と判断して、サブエージェントに仕事を投げるイメージですね。
サブエージェントがあると何が嬉しいか
最大のメリットはコンテキストの節約です。
例えばエラー調査を考えてみましょう。メインエージェントがエラー調査を行うと、調査の過程（ファイルを読んだ、grepした、推論した…）がすべてメインのコンテキストに蓄積されます。調査が長引くほどコンテキストを圧迫し、本来やりたかった作業に使える余裕が減っていきます。
サブエージェントに調査を任せれば、調査過程はサブエージェント側のコンテキストで消費され、メイン側には調査結果だけが返ってきます。つまり、調査過程で消費するコンテキストをサブエージェント側に「押し付ける」ことができるわけです。
どうやって実現するか
今回は以下のアプローチで実現します：
- Codexからコマンド経由で別のCodexを起動する
- あらかじめ専用のプロンプトを用意し、Codexを呼び出すコマンドとセットにする
これにより、サブエージェント的な扱いができるようになります。
使用する技術
- Node.js：JavaScript のランタイム環境
- CodexSDK(
@openai/codex-sdk)：CodexCLIをラップして簡単に扱える公式SDK
これらを使って、エラーを調査し調査結果を返すことに特化したサブエージェントを作ります。
処理の流れ
今回実装するサブエージェントの処理フローは以下の通りです：
ポイントは、サブエージェントの調査過程（ファイル読み込み、推論など）はメインのコンテキストに含まれないこと。メインが受け取るのは最終的な調査レポートだけです。
実際のコードを見ていこう
1. サブエージェント本体（error_research_subagent.mjs）
まずはサブエージェントのメイン処理を見ていきます。
ポイント解説
Codex SDK でセッションを起動
startThread() でプロンプトを渡す Codex セッションを作成できます。ここで設定できる主なオプション：
model：使用するモデル（今回は軽量なgpt-5-codex-mini）sandboxMode：サンドボックスのモードworkingDirectory：Codex がファイルを参照するディレクトリ
なぜ read-only を指定するのか
サブエージェントには sandboxMode: 'read-only' を強く推奨します。理由は再帰的なループを防ぐためです。
もしサブエージェントがコマンド実行可能な状態だと、「サブエージェントの中でさらにサブエージェントを呼び出す」という再帰的なループに陥る可能性があります。read-onlyにしておけば、ファイルの読み取りはできますが書き込みやコマンド実行はできないため、安全です。
推論過程の表示について
開発中は推論過程（Codexが何を考えているか）を表示すると参考になります。ただし、本番運用では出力しない方がよいでしょう。なぜなら、この出力がメイン側のセッションにも含まれてしまい、結局コンテキストを消費することになるからです。
2. プロンプト組み立て（error_research_setup.mjs）
次に、サブエージェントに渡すプロンプトを組み立てる部分です。
ここは比較的シンプルです。エラー調査に特化したプロンプトを定義し、ユーザーから渡されたエラー説明と組み合わせて完全なプロンプトを作成しています。
出力フォーマットを明確に指定することで、サブエージェントからの応答が整理された形で返ってくるようにしています。
3. カスタムコマンド用プロンプト
最後に、メインのCodexからサブエージェントを呼び出すためのカスタムコマンド用プロンプトです。
このプロンプトをカスタムコマンドとして登録しておきます。
カスタムコマンドの登録方法（Mac の場合）
- ホームディレクトリに
.codexという隠しディレクトリがあります - その中に
promptsディレクトリを作成します - マークダウンファイル（例：
error-research.md）としてプロンプトを保存します
CodexCLIでスラッシュ / を入力すると候補に表示されるので、Enterで使えます。
スクリプトの配置方法
上記のスクリプトを自分のプロジェクトで使うための配置方法を説明します。
ディレクトリ構成
プロジェクトのルートに subagents/ ディレクトリを作成し、以下のように配置します：
package.json の設定
Codex SDK を依存関係に追加します：
セットアップ手順
これで、プロジェクト内から node subagents/error_research_subagent.mjs "<エラー説明>" でサブエージェントを呼び出せるようになります。
実際に使ってみる
エラーが起きるサンプルを用意
意図的にエラーが起きるコードを用意しました：
Codexを起動してエラーを発生させる
※以下は実行時の出力イメージです。実際の出力とは異なる場合があります
カスタムコマンドでサブエージェントを呼び出す
※以下は実行時の出力イメージです。実際の出力とは異なる場合があります
調査レポートが返ってきました！メインのCodexはこのレポートを元に修正を進められます。
おわりに
今回はCodexSDKを使って「サブエージェント的なもの」を実装してみました。
改めて注意ですが、CodexSDKを通して別のCodexを起動しているので、その分利用枠を消費します。このサンプルを試して利用枠がたくさん消費されても自己責任でお願いします。
今回学んだことを応用すれば、以下のようなことも可能です：
- 複数のCodexを並列で起動して、異なる観点から同時に調査
- 様々な解析タスクを自動化（セキュリティチェック、パフォーマンス分析など）
- 特定ドメインに特化したサブエージェント群を作成
AIエージェントはGUIツールかCLIツールか、どちらが良いかという議論をSNS上でも見かけますが、プログラムに組み込んで利用できることはCLIのわかりやすい強みだと思います。今回の記事でその魅力が伝わったら嬉しいです。
ぜひ皆さんも独自のCLIツールを駆使して独自のエージェントを開発して見てください。
