Codexカスタムエージェントの作り方｜サブエージェントのTOML定義と設定・権限の注意点【2026年10月】

Codexのカスタムエージェントは、.codex/agents/ にTOMLファイルを1つ置くだけで作れる、役割付きのサブエージェントです。ただし2026年7月以降に仕様がいくつも変わり、定義ファイルに sandbox_mode = "read-only" と書いても書き込みは止まらなくなりました。この記事では、2026年10月時点の公式ドキュメントと Codex CLI 0.162.1 のソースを根拠に、定義の書き方、config.toml の [agents] 設定、モデルの割り当て、承認とCIの扱いを整理し、権限まわりは手元で実際に動かした結果を載せます。

まとめ

• カスタムエージェントは ~/.codex/agents/（個人）か .codex/agents/（プロジェクト）に1ファイル1エージェントのTOMLで置く。必須は name・description・developer_instructions の3つで、1つでも欠けると警告を出してそのファイルは無視される。
• 定義ファイルで変えられるのはモデル・推論努力・指示・一部機能やスキルの無効化などに限られる。sandbox_mode・approval_policy・mcp_servers は書いても効かず、サブエージェントは親セッションの権限を引き継ぐ（0.149.0で変更）。
• 調査役に書き込ませたくないなら、親セッションを --sandbox read-only で起動するしかない。定義側の sandbox_mode や features.shell_tool = false では、実測でもファイルが作られた。
• 同時に開けるスレッド数は [agents] の max_concurrent_threads_per_session（旧名 max_threads）で決める。job_max_runtime_seconds と CSV一括起動は削除済み。
• モデルは重い役に gpt-6.1-sol、速さ優先の役に gpt-6-luna が公式の推奨。サブエージェントは各自がモデルとツールを使うので、単一エージェントよりトークンを多く消費する。

2026年7月版から変わったサブエージェントの仕様

サブエージェントとカスタムエージェントは、Codex CLI 0.115.0 が公開された2026年3月16日に一般提供が始まり、その後も毎週のように変更されています。7月時点の解説（当記事の旧版を含む）のまま設定すると、効かないキーやエラーになるフラグを書くことになります。主な変更は次のとおりです。

CSVジョブの削除は Codex 0.145.0 のリリースノートに「Remove CSV-backed agent jobs」、定義ファイルの制限は 0.149.0 のリリースノートに「Restrict agent roles to bounded configuration overrides」として載っています。0.162.1 のソースでも、job_max_runtime_seconds は「削除済みの設定を互換のために残した何もしない項目」とコメントされています。最新の安定版は10月15日公開の 0.163.0 で、サブエージェント関連の修正が続いているため、設定を書く前に codex --version で手元の版を確かめてください。

サブエージェントを起動する依頼の書き方

現行の Codex ではサブエージェント機能は既定で有効です。ただしローカルの Codex（デスクトップアプリ・CLI・IDE拡張）が自分から委任することはなく、公式のSubagentsページによれば、ユーザーが直接頼んだときか、AGENTS.md やスキルの指示が委任を求めているときに起動します。公式は、良い依頼文には「仕事の分け方」「全員の完了を待つか」「何を返させるか」の3点を書くよう勧めています。

このブランチを main と比べてレビューして。
reviewer を観点ごとに3体起動し、1体目はセキュリティ、2体目はテスト不足、3体目は保守性を見ること。
3体の結果がそろうまで待ってから、観点別にファイル名と行番号付きで指摘をまとめて。

カスタムエージェントを使わせたいときは、上の例のように name で指名します。指名しなければ、Codex が description を見て組み込みの3種とカスタムエージェントの中から選び、種別を指定せずに起動した場合は default になります。毎回同じ分担で頼むなら、依頼文ではなくリポジトリの AGENTS.md に「レビュー依頼では reviewer を観点別に起動する」と書いておくと、プロンプトの書き忘れで並列化されない事故を防げます。

走っているスレッドの確認と停止

CLIでは /subagents で稼働中のスレッドを切り替えて中身を見られます（旧 /agent は現在のコマンド一覧になく、似た名前の /agents は別機能のコマンドセンターです）。別スレッドから承認要求が来ると、発生元のラベル付きで表示され、o キーでそのスレッドを開いてから許可・拒否できます。デスクトップアプリはメインのチャットに出る各スレッドから中身を開け、IDE拡張は入力欄の上のパネルから状態確認と一括停止ができます。ローカルのどの画面でも、個別の停止や方針変更は「reviewer を止めて」のようにチャットで頼みます。

組み込みエージェント default・worker・explorer の違い

カスタム定義を書く前に、組み込みの3種で足りるかを確かめてください。3種の違いは、親エージェントに見せる「使いどころの説明文」だけです。0.162.1 のソースでは、explorer 用の設定ファイル explorer.toml は0バイトで、モデルや権限は親と同じになります。

explorer が「読み取り専用」と紹介されることがありますが、権限としての制限はありません。親を書き込み可で起動していれば explorer も書き込めます。worker の説明文には「担当ファイルを明示し、他のworkerの変更を戻さないよう伝えよ」という指示が入っており、複数の worker を並べるときはこの分担を依頼文に書くのが前提です。カスタムエージェントに explorer など組み込みと同じ名前を付けると、カスタム側が優先されます。

カスタムエージェントをTOMLで作る手順

置き場所と読み込まれる条件

定義は専用ディレクトリに1ファイル1エージェントで置くのが基本です（config.toml の [agents.<name>] から config_file で定義ファイルを指す書き方も残っています）。0.162.1 のローダーはディレクトリ配下を再帰的にたどって .toml を集めるので、.codex/agents/review/ のようにサブフォルダで分けても読み込まれます。

プロジェクトの .codex/ は、信頼済みのプロジェクトでだけ読み込まれる設定レイヤーで、エージェント定義もこのレイヤーごとに探されます。個人とプロジェクトに同じ name がある場合は、プロジェクト側の定義ファイルが丸ごと使われます。個人側から補われるのは description と nickname_candidates が欠けているときだけで、モデルや指示は引き継がれません。チームで使う役割はリポジトリの .codex/agents/ に置いてバージョン管理すると、人によって同名エージェントの指示が違う状態を避けられます。エージェントの識別に使われるのはファイル名ではなく name の値です。

必須3フィールドと書き分け

# .codex/agents/reviewer.toml
name = "reviewer"
description = "PRの差分を正確性・セキュリティ・テスト不足の観点で点検する担当。修正はしない。"
model = "gpt-6.1-sol"
model_reasoning_effort = "high"
developer_instructions = """
変更されたファイルだけを読む。
指摘は「動作が壊れる箇所」「認証・入力検証の欠落」「テスト不足」の順に並べ、
必ずファイル名と行番号を付ける。ファイルは編集しない。
"""

description は、親が「この仕事を誰に渡すか」を決めるときに読む説明です。「優秀なレビュアー」のような自己紹介ではなく、何を受け取って何を返す担当かを書きます。developer_instructions はサブエージェント自身の行動規範で、出力の形や禁止事項を書く場所です。「ファイルは編集しない」はここに書けますが、これはお願いであって権限ではありません（次の章の実測を参照）。

定義ファイルで変えられる項目・変えられない項目

0.149.0 以降、定義ファイルで上書きできる項目は限られています。0.162.1 のソースで実際に反映される項目を確かめた結果が次の表です。

無効化できる機能は features.shell_tool・features.apps・features.plugins・features.memories・features.request_permissions_tool の5つです。ソースでは true を書いても無視され、親で切っている機能を子だけ有効にすることはできません。MCPサーバーを特定のエージェントにだけ持たせる書き方も通らないため、MCPは親の config.toml で設定し、使わせたくないエージェントには developer_instructions で使用範囲を指示します。

定義が読み込まれないときの確認

必須項目が欠けたファイルは、起動時に警告を出してそのファイルだけ無視されます。developer_instructions を書き忘れたファイルを置いて codex exec を実行すると、次の警告が出て、そのエージェントは一覧に出ませんでした。

warning: Ignoring malformed agent role definition: agent role file at /private/tmp/c11463/proj/.codex/agents/broken.toml must define `developer_instructions`

処理は止まらないため、警告を見落とすと「定義したのに使われない」状態になります。カスタムエージェントが選ばれないときは、(1)起動時の警告に Ignoring malformed agent role definition が無いか、(2)プロジェクト側の定義ならそのプロジェクトを信頼済みにしているか、(3)同じ name が別のファイルに無いか、の順に確かめます。同じレイヤーに同名が2つあると、2つ目は重複の警告付きで無視されます。

実測：定義ファイルのsandbox_modeと書き込みの可否

「調査役は定義ファイルで read-only にしておく」という設定例は、国内の解説記事にまだ残っています。そこで2026年10月17日に macOS 上の codex-cli 0.162.1（モデル gpt-6-astra）で、サブエージェントにファイル作成を指示する codex exec を3条件で実行しました。

1つ目は、定義に read-only と書いた reviewer が、エラーを出さずにファイルを作りました（実行後に ls で作成と中身を確認）。0.162.1 のソースでも、子の設定を組み立てるときに承認方針と権限プロファイルを親のターンから上書きしており、定義ファイルの sandbox_mode は読み捨てられます。2つ目はシェル実行ツールを外した定義ですが、サブエージェントは使えたツールとして exec（コード実行）と apply_patch（ファイル編集）を報告し、ファイルは作成されました。シェルを外しても、ほかの実行・編集手段は残ります。

書き込みが止まったのは、3つ目の親セッションを read-only で起動したときだけでした（worker のシェルでの書き込みが operation not permitted で失敗）。公式ドキュメントも「カスタムエージェントの指示で編集を避けるよう頼めるが、別の read-only サンドボックスは作られない」と明記しています。調査とレビューだけのセッションは codex exec --sandbox read-only（codex exec の既定も read-only）で起動し、書き込みが必要な実装は別セッションに分けて worker に任せる、という分け方が現実的です。

config.tomlの[agents]設定と並列数の上限

サブエージェント全体の挙動は、個々の定義とは別に config.toml の [agents] で決めます。設定リファレンスに載っている現行のキーは次の5つです。

# ~/.codex/config.toml（またはプロジェクトの .codex/config.toml）
[agents]
max_concurrent_threads_per_session = 4
default_subagent_model = "gpt-6-luna"
default_subagent_reasoning_effort = "high"

max_threads は旧名として今も読み込まれ、内部で max_concurrent_threads_per_session に置き換えられます。未設定時の値は「Codexが決める」とされ、0.162.1 のソースでは従来方式で6、新方式（multi-agent v2）で3（主スレッドを含めて4）です。どちらの方式になるかは features.multi_agent_v2 とモデルの設定で決まります。並列数を前提に作業を組むなら、既定に頼らず明示してください。0 を書くと起動時にエラーになります。

7月版で紹介した max_depth（入れ子の深さ、既定1）は、現在の公式ドキュメントからは消えています。ソースには従来方式向けの設定として残っていますが、新方式では無視されると書かれているため、孫エージェントを作らせる設計は前提にしないほうが安全です。

サブエージェントのモデルと推論努力の割り当て

モデルと推論努力の決まり方は、公式ドキュメントでは次の順です。依頼で明示した値、[agents] の既定、親の値の順に解決され、最後に定義ファイルに model や model_reasoning_effort があればそちらが勝ちます。何も指定しなければ親と同じモデルと推論努力になります。依頼や [agents] の既定でモデルだけを選んだ場合は、そのモデルの既定の推論努力です。一方、定義ファイルに model だけを書いた場合は、それまでに決まった推論努力が引き継がれ、新しいモデルがその値に対応していないと起動時にエラーになるため、model_reasoning_effort も併記します。

推論努力には low・medium・high・xhigh・max・ultra などがあり、どこまで選べるかはモデルによって違います。公式の目安では、レビューやセキュリティ確認のように論理を追う役は high、速い走査は Luna とされています。Free と Go プランなら、公式の案内どおりデスクトップアプリで Luna を選びます。Sol・Luna・Astra の違いと料金はGPT-6 Solとは？6.1 Solの変更点とLuna・Astraの使い分け【2026年10月】で比べています。

承認の扱い：Auto-reviewとCIでの実行

サブエージェントは親の承認方針をそのまま継承します。対話中のCLIでは子スレッドからの承認要求も画面に出ますが、公式ドキュメントによれば、非対話の実行や新しい承認を出せない状況では、承認が必要な操作は失敗し、そのエラーが親に返ります。6体走らせて6体が承認待ちになる事態を避けるには、承認の判定役を人から別のエージェントに替える Auto-review を使います。

7月版で Smart Approvals（guardian）として紹介した機能で、Auto-reviewのページによれば、サンドボックスの外に出る操作の承認要求を別のレビュー用エージェントへ回します。CLIでは approvals_reviewer = "auto_review" を、approval_policy = "on-request" のような対話型の承認方針と組み合わせて設定し、デスクトップアプリでは権限の選択で「Approve for me」を選びます。Auto-review は判定役を替えるだけで、書き込み可能な範囲やネットワークの許可は広げません。approval_policy = "never" では判定する承認が無いため働きません。

CIで codex exec を回すときは、次のように権限を明示します。

# 編集を許す（承認要求は出さない）
codex exec --sandbox workspace-write "テストを直して"

# workspace-write で動かし、承認要求を Auto-review に回す（--sandbox とは併用しない）
codex exec --approve-for-me "依存関係を更新してテストを通して"

--full-auto は非対話モードのページで「サポートされなくなった」とされ、0.162.1 で実行すると unexpected argument '--full-auto' found で止まります。古いCIテンプレートを流用している場合は --sandbox workspace-write か --approve-for-me に書き換えてください。承認もサンドボックスも外す --dangerously-bypass-approvals-and-sandbox（隠しエイリアス --yolo）は、使い捨てのコンテナのように外側で隔離された環境に限ります。その他のオプションはCodex CLIのプロキシ設定・承認モード・オプション一覧｜導入とアンインストール【2026年9月】にまとめています。

サブエージェントを使わない方がよい場面

公式ドキュメントは、各サブエージェントが自分でモデルとツールを使うため、同等の単一エージェント実行よりトークンを多く消費すると書いています。増え方はスレッド数と各スレッドが読むファイル量で決まり、一律の倍率はありません。次の場面では、並列化しても遅く高くなるだけです。

• 1ファイルで終わる修正や定型の変更：委任の説明と結果の集約の手間が、作業そのものより重くなります。
• 同じファイルを複数の書き込み役に触らせる分担：後から書いた変更が前の変更を消します。公式も、並列にするなら探索・テスト・トリアージ・要約のような読み取り中心の仕事から始めるよう勧めています。
• 人が1つずつ確認したい本番反映：承認が子スレッドに散らばり、誰が何を許可したか追いにくくなります。

逆に効くのは、レビューを観点で分ける、複数のコンポーネントを横断して調べる、テストログのような長い出力を親から切り離す、といった仕事です。社内の業務フローにこうした分業型のエージェントを組み込む場合は、AIエージェント開発として権限設計から相談いただけます。複数エージェントの構成パターン全般はマルチエージェントとは？仕組み・構成パターンと採用判断を研究データで解説【2026年10月】で扱っています。

よくある質問

Codexのカスタムエージェントはどこに置けば使えますか？

個人用は ~/.codex/agents/、プロジェクト用は .codex/agents/ に、1ファイル1エージェントのTOMLとして置きます。プロジェクト側は信頼済みのプロジェクトでだけ読み込まれ、必須3項目が欠けたファイルは警告付きで無視されます。

サブエージェントは何体まで同時に動きますか？

[agents] の max_concurrent_threads_per_session（旧名 max_threads）で決まります。未設定時は方式によって6か3（0.162.1 のソース）なので、上限を前提にするなら明示してください。

explorerやカスタムエージェントを読み取り専用にできますか？

定義ファイルではできません。sandbox_mode = "read-only" を書いても親の権限が使われ、実測でもファイルが作られました。読み取り専用にしたいときは、親セッションを --sandbox read-only で起動します。

サブエージェントごとにモデルを変えられますか？

定義ファイルの model と model_reasoning_effort で個別に指定でき、依頼文や [agents] の既定より優先されます。重い仕事は gpt-6.1-sol、範囲の明確な仕事は gpt-6-luna が公式の推奨です。

ChatGPT Workでもサブエージェントは使えますか？

使えます。ChatGPT Work では OpenAI 側の環境でサブエージェントが動き、多くの知能レベルでは「並列で分担して」のように明示的に頼みます。Ultra では、並列化が速さや品質を大きく上げると判断したときに自分から委任します。カスタムエージェントの定義はローカルの Codex 向けで、Web のサブエージェント一覧は閲覧のみで個別の停止はできません。

Claude Codeのサブエージェントと何が違いますか？

定義の形式が違い、Codex はTOML、Claude Code はフロントマター付きのMarkdownです。Claude Code は定義に使えるツールを列挙して絞れますが、Codex の定義でできるのは5種類の機能の無効化までで、権限は親セッションで決めます。Claude Code 側の書き方はClaude Codeのサブエージェントとは？作り方・設定項目・使い方【v2.1.287対応】、両製品の比較はCodexとClaude Codeの違い｜料金・使用量・設定と併用の判断【2026年版】を参照してください。

関連記事

• Codexの使い方｜料金・始め方・情報漏洩対策まで2026年7月版で解説
• Codex CLIのプロキシ設定・承認モード・オプション一覧｜導入とアンインストール【2026年9月】
• CodexとClaude Codeの違い｜料金・使用量・設定と併用の判断【2026年版】
• Claude Codeのサブエージェントとは？作り方・設定項目・使い方【v2.1.287対応】
• GPT-6 Solとは？6.1 Solの変更点とLuna・Astraの使い分け【2026年10月】