Codexのサブエージェントとは？使い方・自作の方法・設定項目を解説

「Codexにサブエージェントという機能があるらしいが、何のことか分からない」「調査やレビューを同時に進められると聞いたが、どう頼めばいいのか」と感じている方は多いのではないでしょうか。

サブエージェントは、Codexが別のエージェント（作業を担当するAI）を呼び出し、調査やレビューなどを分担して並行して進めさせ、結果だけをまとめて受け取る機能です。メインの会話に細かい作業の記録が積み上がらないので、長い作業でも話の筋がぶれにくくなります。

この記事では、サブエージェントの仕組み、頼み方、標準のエージェント、自分で作る方法、設定項目、使用量と権限の注意点までを順に解説します。内容は2026年10月時点のOpenAI公式ドキュメントにもとづいています。名称や画面は変わることがあるので、設定の前に公式ページもあわせて確認してください。

Codexのサブエージェントとは

公式ドキュメントでは、サブエージェントを「特定のタスクを担当させるために、Codexが起動する委任先のエージェント」と説明しています。たとえば「セキュリティの観点」「テストの抜け」「コードの読みやすさ」を別々のエージェントに同時に確認させ、最後に1つの報告にまとめる、といった使い方です。

非エンジニアの方には、担当を分けて同時に動いてくれる助手と考えると分かりやすいでしょう。1人のAIが順番に調べるより、手分けした方が早く、しかも「どの視点の指摘か」が整理された形で返ってきます。

用語の整理

公式ドキュメントで使われている言葉を、この記事での呼び方とあわせて整理します。

なぜ役に立つのか

公式ドキュメントは、1つの会話で長く作業すると起きる問題として、次の2つを挙げています。

• コンテキストの汚れ：調べた途中経過、テストのログ、エラーの記録などがたまり、大事な情報が埋もれる
• コンテキストの劣化：会話が長くなり、関係の薄い情報が増えるほど、回答の質が落ちる

サブエージェントは、こうした「ごちゃごちゃした作業」をメインの会話の外で行い、親には要約だけを返します。親は要件の整理と判断に集中できます。もう1つの利点は、互いに関係のない作業を同時に進められること、大きな仕事を区切りのある小さな仕事に分けられることです。

使える場所

公式ドキュメントによると、現在のCodexではサブエージェントは初期状態で有効です。サブエージェントの動きは、次の場所で確認できます。

公式ドキュメントには、どのプランで使えるかを個別に示した記載がありません。利用できるのは「対象のアカウント」ということになるため、使えない場合はアカウントの種類や、アプリ・CLIのバージョンを確かめてください。

サブエージェントの頼み方

サブエージェントを呼び出すための特別な操作はありません。入力欄に「サブエージェントを使って」と日本語で書くだけです。公式ドキュメントによると、Codexは直接の依頼があったとき、またはAGENTS.mdやスキルの指示に書いてあるときに、サブエージェントを起動します。

依頼文に入れる3つのこと

公式ドキュメントは、よい依頼文には次の3つが入っているとしています。

1. どう分けるか観点ごと、ファイルごと、機能ごとなど、仕事の分け方を書きます。「1つの観点につき1つのエージェント」のように書くと伝わります。
2. 待つかどうか全員の結果がそろうのを待ってからまとめるのか、先に出たものから報告するのかを書きます。「全部の完了を待ってから」と書くのが基本です。
3. 何を返すか最終的な報告の形を書きます。「観点ごとにまとめて、ファイル名も添えて」のように具体的にします。

公式ドキュメントに載っている依頼文を、意味が分かるようにまとめると、次のような形です。

このブランチを、サブエージェントを並行して使ってレビューしてください。セキュリティ上の危険、テストの抜け、保守のしやすさについて、1つの観点につき1つのエージェントを起動し、3つとも終わるのを待ってから、観点ごとに指摘をまとめ、該当するファイルも添えてください。

公式にはこのほか、レビューしたい点を並べたうえで「1つの点につき1つのエージェントを起動し、全部を待って、点ごとに結果をまとめて」と頼む例も載っています。

進み具合の見方と、止め方

サブエージェントが動いている間は、画面で状況を確認できます。公式ドキュメントでは、Subagentsの表示に動作中（Active）と完了（Done）の一覧が出ると説明されています。完了したものを選ぶと、詳しい内容と結果を見られます。この一覧は見るだけで、ここから操作はできません。

どの画面でも共通なのは、走っているサブエージェントへの指示・停止・終了は、Codexに言葉で頼むという点です。「3番目のエージェントは止めて」「完了したエージェントのスレッドは閉じて」のように、普通に書けば伝わります。

標準のエージェント

Codexには、最初から使える3種類のエージェントが用意されています。自分で何も作らなくても、依頼文に書けば役割に応じて使い分けられます。

名前は、依頼文の中で「explorerでコードの構造を調べて、workerで修正して」のように使えます。名前を指定しなくても、Codexが仕事の内容を見て選びます。

向く作業と向かない作業

自分で作るカスタムエージェント

標準の3つでは足りない場合は、自分で担当者を作れます。作り方は簡単で、役割と指示を書いた小さなファイルを1つ置くだけです。公式ドキュメントでは「カスタムエージェント」と呼ばれています。

ファイルの形と必須項目

1つのエージェントにつき、TOML形式（設定を書くための簡単な形式）のファイルを1つ作ります。必須の項目は次の3つです。

次の項目は任意です。書かない場合の決まり方は、次の章で説明します。

• model：使うモデル
• model_reasoning_effort：思考の深さ
• model_reasoning_summary、model_verbosity：思考の要約や回答の詳しさ

置く場所

チームで同じ基準のレビューをしたいなら、プロジェクトの.codex/agents/に置くのがおすすめです。公式ドキュメントの例も、すべて.codex/agents/に置く形で書かれています。

作ってみる：文書をチェックするエージェント

ここでは、文書の誤字や数字の食い違いを確認するだけのエージェントを例にします。以下の内容は、この記事のために作った例で、公式ドキュメントに載っているものではありません。名前や指示は自社に合わせて変えてください。

1. 置き場所を決めるプロジェクトのフォルダの中に.codex/agents/を作ります。
2. ファイルを作るたとえばdoc-checker.tomlという名前で、下の内容を保存します。
3. 名前で呼び出す依頼文に「doc_checkerのエージェントで、このフォルダの文書を確認して」と書きます。
4. 結果を確認する返ってきた一覧を、人が目で確かめて直します。

name = "doc_checker"
description = "社内向けの文書で、誤字・表記のゆれ・数字の食い違いを確認するときに使う。ファイルは変更しない。"
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
文書の誤字脱字、表記のゆれ、数字や日付の食い違いを確認する。
ファイルは編集しない。
見つけた点は、ファイル名・該当箇所・理由の順で一覧にして返す。
確実でないものは「要確認」と書き、断定しない。
"""

モデルと思考の深さは、公式ドキュメントの例で使われている組み合わせにそろえています。モデルがアカウントやアプリで選べない場合は、この2行を書かなければ、親と同じ設定で動きます。

名前が標準と同じ場合

カスタムエージェントのnameをexplorerのように標準の名前と同じにすると、自作の方が優先されます。標準のexplorerの振る舞いを、自社のルールに合わせて置き換えたいときに使えます。

設定の選び方

サブエージェント全体の動きは、設定ファイル（config.toml）の[agents]で決められます。公式ドキュメントと設定リファレンスに載っている項目を整理します。

同時に動かせる数の具体的な初期値は、公式には数字で書かれていません。「設定しなければCodexが決める」とされています。数を絞りたい場合だけ、上限を設定します。

設定リファレンスには、このほかにagents.<名前>.descriptionとagents.<名前>.config_fileがあります。役割の説明と、その役割に当てる設定ファイルのパスを、config.tomlの側で宣言するための項目です。

モデルと思考の深さの決まり方

サブエージェントが使うモデルと思考の深さは、次の順で決まります。上に書いてあるものほど優先されます。

1. 呼び出し時の指定依頼やCodexの呼び出しの中で、はっきり指定された値
2. カスタムエージェントのファイルそのファイルにmodelやmodel_reasoning_effortが書かれていれば、その値
3. [agents]の標準値default_subagent_modelなどの値
4. 親の設定どれも指定がなければ、親と同じモデルと思考の深さ

注意したいのは、モデルだけを指定して思考の深さを書かなかった場合です。呼び出しや[agents]の標準値でモデルだけを選ぶと、そのモデルの標準の思考の深さが使われます。一方、カスタムエージェントのファイルにmodelだけを書いた場合は、それまでに決まっていた思考の深さがそのまま残ります。モデルによって使える深さが違うので、組み合わせて書いておく方が確実です。

モデルの選び方の目安

思考の深さ（model_reasoning_effort）は、公式ドキュメントでは次のように説明されています。高くするほど質が上がることがある反面、時間と使用量が増えます。

なお、公式のモデルのページには、Ultraは、複雑な作業の別々の部分をサブエージェントで並行して進めるレベルだと書かれています。また、gpt-6-lunaはMaxまでの思考に対応し、Ultraには対応していません。モデルは「アカウントやアプリで選べる場合」に使えるものなので、選択肢にない場合は無理に指定しなくて構いません。

機能を減らしたいとき

カスタムエージェントには、できることを絞る設定もあります。公式ドキュメントは、次の機能のキーをfalseにすると、その機能を減らせると説明しています。

• features.shell_tool（コマンドの実行）
• features.apps
• features.plugins
• features.memories
• features.request_permissions_tool

スキルを個別に無効にする[[skills.config]]という書き方もあります。pathにスキルのファイルの場所、enabled = falseを書きます。ただし、これらをどこにどう書くかは、公式のサブエージェントのページには例がありません。使う前に、設定リファレンスで書き方を確かめてください。

活用例

どんな場面で使うと得なのかを、場面ごとに整理します。サブエージェントは、「同時に調べる」「観点を分ける」「長いログを親に残さない」のいずれかに当てはまる作業で効果が出ます。

公式の例：PRレビュー

公式ドキュメントには、プルリクエスト（変更の取り込みを確認してもらう依頼）をレビューする3つのエージェントが載っています。

調べる役は軽いモデルで、判断が必要なレビュー役は高いモデルで、と役割ごとにモデルを分けているのが特徴です。

公式の例：画面の不具合の調査

もう1つの例は、画面の不具合を直すための3人組です。

• code_mapper：不具合の出る画面の流れを担当しているコードを整理する
• browser_debugger：ブラウザで不具合を再現し、正確な手順と実際の画面の動きを報告する
• ui_fixer：原因が分かったあと、最小限の修正をする。無関係なファイルは触らず、変更した部分だけを確認する

修正を担当するのは1人だけ、調べる役は読むだけ、という分け方になっています。書き込む人を絞ることで、先ほどの衝突を避けやすくなります。

依頼文の例

非エンジニアの方がよく使うのは、「調べてもらう」使い方です。次のような依頼文が、そのまま使えます。

このフォルダのREADMEとドキュメントを読んで、引き継ぎ用の説明を作ってください。サブエージェントを3つ使い、1つ目は「何をするシステムか」、2つ目は「動かし方と必要な設定」、3つ目は「注意が必要な箇所」を担当してください。3つとも終わるのを待ってから、1枚の説明にまとめてください。

使用量・権限・困ったとき

使用量は増える

公式ドキュメントは、サブエージェントは1つ1つがモデルによる処理とツールの操作を行うため、1つのエージェントだけで進めるより、使用量（トークン）が増えると明記しています。1つのエージェントあたりの使用量の数字は、公式には示されていません。

また、CodexとChatGPT Workは使用量を共有しています。公式の料金ページでは、ChatGPT Workでの使用量は、Codexと同じ料金・クレジット・上限の仕組みで扱われると説明されています。サブエージェントを多用した日は、ほかの作業に使える量も減ります。使用量の確かめ方は、別の記事でまとめています。

権限は親からそのまま引き継がれる

公式ドキュメントが特に強調しているのは、サブエージェントは親の会話のサンドボックスと承認の設定を引き継ぐ点です。たとえば/permissionsで権限を変えた場合や、確認を飛ばす起動の仕方（--yolo）にした場合も、その設定が子にも及びます。

つまり、「サブエージェントだけ権限を広げる」「サブエージェントだけ書き込みを禁止する」といったことは、エージェントのファイルではできません。全体の権限をどうするかは、親の会話の設定で決めることになります。

確認が必要な操作は、失敗することがある

公式ドキュメントでは、対話のできない実行（自動で流す処理など）や、新しい確認を画面に出せない場合に、確認が必要な操作は失敗し、そのエラーが親に返されると説明されています。サブエージェントが止まったように見えるときは、この動きになっていないかを疑ってください。

うまく動かないときの対処

よくある質問

まとめ

サブエージェントは、調べものやレビューのような「読む作業」から試すのが無理のない始め方です。まずは3つ以下の担当で頼み、返ってきた結果と使用量を見ながら、自社の使い方に合う分け方を見つけていってください。

社内で使う権限の決め方や、チームで共有するエージェントの作り方など、導入の段階で決めることは意外と多くあります。INTERCREATE JAPANでは、Claude CodeやCodexの導入から、社内で使い続けられる仕組みづくりまでをお手伝いしています。