--- title: "Codexカスタムエージェントの作り方｜サブエージェントのTOML定義と設定・権限の注意点【2026年10月】" url: "https://www.issoh.co.jp/tech/details/11463/" published: 2026-03-20 updated: 2026-10-19 categories: ["AIエージェント・MCP"] publisher: "株式会社一創" --- # 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月時点の解説（当記事の旧版を含む）のまま設定すると、効かないキーやエラーになるフラグを書くことになります。主な変更は次のとおりです。 | 項目 | 7月時点の書き方 | 2026年10月の扱い | 根拠 | | ----------- | ------------------------- | ------------------------------------ | -------------- | | CSVから一括起動 | `spawn_agents_on_csv` | 削除 | 0.145.0（7月21日） | | 定義ファイルの権限指定 | `sandbox_mode` を書く | 効かない（親を継承） | 0.149.0（8月20日） | | 同時スレッド数 | `max_threads` | `max_concurrent_threads_per_session` | 設定リファレンス | | ワーカーの制限時間 | `job_max_runtime_seconds` | 互換のため受け付けるだけ | 0.162.1 のソース | | スレッドの切り替え | `/agent` | `/subagents` | 0.162.1 のソース | | 承認の自動判定 | Smart Approvals（guardian） | Auto-review の名前で説明 | 公式ドキュメント | | CIの全自動フラグ | `--full-auto` | 未対応（エラー） | 公式ドキュメント | | モデル例 | GPT-5.6 Sol／Terra／Luna | GPT-6.1 Sol／GPT-6 Luna | 公式ドキュメント | CSVジョブの削除は [Codex 0.145.0 のリリースノート](https://github.com/openai/codex/releases/tag/rust-v0.145.0)に「Remove CSV-backed agent jobs」、定義ファイルの制限は [0.149.0 のリリースノート](https://github.com/openai/codex/releases/tag/rust-v0.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ページ](https://learn.chatgpt.com/docs/agent-configuration/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バイトで、モデルや権限は親と同じになります。 | 名前 | 親への説明（要旨） | 向く仕事 | | ---------- | -------------------- | ----------------- | | `default` | 汎用 | 役割が決まらない委任 | | `worker` | 実装・修正の担当。担当ファイルを明示せよ | 機能の一部実装、テストやバグの修正 | | `explorer` | 範囲を絞ったコードベースの質問に使う | 影響範囲の特定、呼び出し経路の追跡 | explorer が「読み取り専用」と紹介されることがありますが、権限としての制限はありません。親を書き込み可で起動していれば explorer も書き込めます。worker の説明文には「担当ファイルを明示し、他のworkerの変更を戻さないよう伝えよ」という指示が入っており、複数の worker を並べるときはこの分担を依頼文に書くのが前提です。カスタムエージェントに `explorer` など組み込みと同じ名前を付けると、カスタム側が優先されます。 ## カスタムエージェントをTOMLで作る手順 ### 置き場所と読み込まれる条件 定義は専用ディレクトリに1ファイル1エージェントで置くのが基本です（`config.toml` の `[agents.]` から `config_file` で定義ファイルを指す書き方も残っています）。0.162.1 のローダーはディレクトリ配下を再帰的にたどって `.toml` を集めるので、`.codex/agents/review/` のようにサブフォルダで分けても読み込まれます。 | スコープ | 置き場所 | 読み込まれる条件 | | ------ | ------------------ | ---------------- | | 個人 | `~/.codex/agents/` | 常に | | プロジェクト | `.codex/agents/` | プロジェクトを信頼済みにしたとき | プロジェクトの `.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 のソースで実際に反映される項目を確かめた結果が次の表です。 | 項目 | 定義ファイルでの扱い | | --------------------------------------------------------- | ----------------- | | `model`・`model_reasoning_effort` | 反映される（ファイルの値が最優先） | | `model_reasoning_summary`・`model_verbosity`・`personality` | 反映される | | `nickname_candidates` | 反映される（スレッドの表示名候補） | | `features.shell_tool` など5種 | `false` にしたときだけ反映 | | `skills.config` など | スキルの無効化だけ反映 | | `sandbox_mode`・`approval_policy` | 書いても効かない（親を継承） | | `mcp_servers`・`model_provider` | 書いても効かない（親で設定する） | 無効化できる機能は `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条件で実行しました。 | 親の起動 | エージェント定義 | 結果 | | --------------------------- | ----------------------------- | ----------------------------- | | `--sandbox workspace-write` | `sandbox_mode = "read-only"` | ファイルが作られた | | `--sandbox workspace-write` | `features.shell_tool = false` | ファイルが作られた | | `--sandbox read-only` | 組み込みの `worker` | 作成失敗（operation not permitted） | 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]` で決めます。[設定リファレンス](https://learn.chatgpt.com/docs/config-file/config-reference)に載っている現行のキーは次の5つです。 | キー | 既定 | 役割 | | ------------------------------------ | --------- | ---------------------- | | `enabled` | `true` | サブエージェント機能のオン・オフ | | `max_concurrent_threads_per_session` | Codexが決める | 同時に開ける子スレッド数（主スレッドを除く） | | `default_subagent_model` | なし | 子に使う既定のモデル | | `default_subagent_reasoning_effort` | なし | 子に使う既定の推論努力 | | `interrupt_message` | `true` | 中断されたことを子に伝える | ``` # ~/.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` も併記します。 | 役割 | 公式の記述 | 推論努力の目安 | | ------------- | ------------- | ------------ | | 計画・検証まで要る重い仕事 | `gpt-6.1-sol` | 選んだモデルが対応する値 | | 範囲が明確で数が多い仕事 | `gpt-6-luna` | `high` から始める | | Astraを指定する場合 | `gpt-6-astra` | `low` から始める | 推論努力には `low`・`medium`・`high`・`xhigh`・`max`・`ultra` などがあり、どこまで選べるかはモデルによって違います。公式の目安では、レビューやセキュリティ確認のように論理を追う役は `high`、速い走査は Luna とされています。Free と Go プランなら、公式の案内どおりデスクトップアプリで Luna を選びます。Sol・Luna・Astra の違いと料金は[GPT-6 Solとは？6.1 Solの変更点とLuna・Astraの使い分け【2026年10月】](/tech/details/18251/)で比べています。 ## 承認の扱い：Auto-reviewとCIでの実行 サブエージェントは親の承認方針をそのまま継承します。対話中のCLIでは子スレッドからの承認要求も画面に出ますが、[公式ドキュメント](https://learn.chatgpt.com/docs/agent-configuration/subagents)によれば、非対話の実行や新しい承認を出せない状況では、承認が必要な操作は失敗し、そのエラーが親に返ります。6体走らせて6体が承認待ちになる事態を避けるには、承認の判定役を人から別のエージェントに替える Auto-review を使います。 7月版で Smart Approvals（guardian）として紹介した機能で、[Auto-reviewのページ](https://learn.chatgpt.com/docs/sandboxing/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` は[非対話モードのページ](https://learn.chatgpt.com/docs/non-interactive-mode)で「サポートされなくなった」とされ、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月】](/tech/details/8157/)にまとめています。 ## サブエージェントを使わない方がよい場面 公式ドキュメントは、各サブエージェントが自分でモデルとツールを使うため、同等の単一エージェント実行よりトークンを多く消費すると書いています。増え方はスレッド数と各スレッドが読むファイル量で決まり、一律の倍率はありません。次の場面では、並列化しても遅く高くなるだけです。 - **1ファイルで終わる修正や定型の変更**：委任の説明と結果の集約の手間が、作業そのものより重くなります。 - **同じファイルを複数の書き込み役に触らせる分担**：後から書いた変更が前の変更を消します。公式も、並列にするなら探索・テスト・トリアージ・要約のような読み取り中心の仕事から始めるよう勧めています。 - **人が1つずつ確認したい本番反映**：承認が子スレッドに散らばり、誰が何を許可したか追いにくくなります。 逆に効くのは、レビューを観点で分ける、複数のコンポーネントを横断して調べる、テストログのような長い出力を親から切り離す、といった仕事です。社内の業務フローにこうした分業型のエージェントを組み込む場合は、[AIエージェント開発](/service/ai/agent/)として権限設計から相談いただけます。複数エージェントの構成パターン全般は[マルチエージェントとは？仕組み・構成パターンと採用判断を研究データで解説【2026年10月】](/tech/details/13604/)で扱っています。 ## よくある質問 ### 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対応】](/tech/details/7911/)、両製品の比較は[CodexとClaude Codeの違い｜料金・使用量・設定と併用の判断【2026年版】](/tech/details/17627/)を参照してください。 ## 関連記事 - [Codexの使い方｜料金・始め方・情報漏洩対策まで2026年7月版で解説](/tech/details/6968/) - [Codex CLIのプロキシ設定・承認モード・オプション一覧｜導入とアンインストール【2026年9月】](/tech/details/8157/) - [CodexとClaude Codeの違い｜料金・使用量・設定と併用の判断【2026年版】](/tech/details/17627/) - [Claude Codeのサブエージェントとは？作り方・設定項目・使い方【v2.1.287対応】](/tech/details/7911/) - [GPT-6 Solとは？6.1 Solの変更点とLuna・Astraの使い分け【2026年10月】](/tech/details/18251/) --- 出典: [Codexカスタムエージェントの作り方｜サブエージェントのTOML定義と設定・権限の注意点【2026年10月】]()（株式会社一創）