Codexサブエージェント設定と実践活用：探索・検証・実装を安全に分担する
Codex CLIで役割別サブエージェントを設定し、並列探索・検証・安全な実装を運用する実践ガイドです。
Codexサブエージェントの実践設定
大きな作業で要件・検索結果・テストログを一つのスレッドに詰め込むと信頼性が落ちます。サブエージェントを使えば、メインは判断と統合を担当し、境界の明確な探索・検証・実装を別スレッドへ委任できます。現行リリースでは既定で有効で、CLIの`/agent`から確認できます。
> 例は2026-09-08にCodex CLI 0.153.4と公式文書で確認しました。キーとモデルはバージョン・契約に依存します。必ず`--strict-config`で検証してください。
1. 独立性で分割する
並列化に向くのは独立した読み取り中心の仕事です。セキュリティ確認、テスト不足、API文書確認は同時に進められますが、同じファイルの並行編集は競合を生みます。
• **Explorer:** ファイル探索と呼び出し経路の追跡を読み取り専用で行う。
• **Verifier:** テスト・lint・buildを実行し、正確な証拠を返す。
• **Worker:** 所有ファイルを明示して最小変更を実装する。
• **Main:** 要件、優先順位、最終diff、結論を所有する。
各サブエージェントは個別にモデルとツールを使うため、単一実行よりトークンを消費します。独立性が高く短い要約を返せる場合に使います。
2. グローバル設定と名前付きロール
```toml
[agents]
default_subagent_model = "gpt-5.4-mini"
default_subagent_reasoning_effort = "low"
max_concurrent_threads_per_session = 4
[agents.explorer]
description = "Read-only codebase mapping and evidence gathering."
config_file = "agents/explorer.toml"
[agents.verifier]
description = "Run tests, lint, build, and report exact failures."
config_file = "agents/verifier.toml"
```
ユーザー設定は`~/.codex/config.toml`、信頼済みプロジェクトは`.codex/config.toml`に置けます。相対`config_file`は宣言元を基準に解決されます。公式文書は`~/.codex/agents/`と`.codex/agents/`の独立ロールも説明し、現行スキーマでは`name`、`description`、`developer_instructions`が必須です。方式を混ぜる前に厳格検証してください。
Explorer — read-only
```toml
name = "explorer"
description = "Read-only explorer for locating code and tracing behavior."
developer_instructions = """
Inspect only. Cite files and symbols. Do not edit or propose broad refactors.
Return a concise evidence map to the parent.
"""
model = "gpt-5.4-mini"
model_reasoning_effort = "low"
sandbox_mode = "read-only"
```
Verifier — workspace-write
```toml
name = "verifier"
description = "Runs checks and reports exact failures."
developer_instructions = """
Run the requested checks. Do not fix application code.
Report the command, exit status, failing assertion, and likely root cause.
"""
model = "gpt-5.4"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
```
子は親ターンの現在のsandboxと承認ポリシーを継承します。実行中の権限変更がロール既定値より優先されることがあります。まず親の権限を最小化してください。
3. 使用前に検証
```bash
codex --version
codex features list
codex exec --strict-config -s read-only \
"Inspect the repository configuration and return a short summary. Do not edit files."
```
`--strict-config`は未対応フィールドを拒否します。典型例は`reasoning_effort`と`model_reasoning_effort`の取り違え、存在しない`config_file`、利用不可モデルです。`/model`、ローカルカタログ、実行結果で確認し、変更後は新しいセッションを開始します。
4. 呼び出しパターン
```text
Review this branch against main. Run explorer read-only to map changed paths,
and verifier to execute relevant tests and the build. Run them in parallel,
wait for both, then return one summary with file paths, commands, and evidence.
Do not edit code.
```
```text
Run explorer and verifier in parallel first. Only after the main agent confirms
the root cause, start one worker. The worker owns only src/parser.ts and makes
the smallest fix. Finally, verifier reruns the same commands.
```
プロンプトに分担、待機、完了条件を明記します。`/agent`で進捗を確認し、方向修正や停止を行えます。
5. Claude Codeで同じ役割分担を作る方法
Claude Codeにもカスタムサブエージェント機能はありますが、CodexのTOML設定をそのまま使うわけではありません。プロジェクト用の役割は通常、`.claude/agents/explorer.md`と`.claude/agents/verifier.md`のようなMarkdownファイルで定義します。「Claudeにエージェントがない」のではなく、**Codexと同じTOML構造がないため、Markdownの役割ファイルで同等の分担を表現する**という違いです。
```markdown
name: explorer
description: 編集せずにコード位置と呼び出し経路を調査します。
tools: Read, Grep, Glob
model: haiku
ファイルを変更せず、根拠を短く親エージェントへ返してください。
```
```markdown
name: verifier
description: テストとビルドを実行し、正確な失敗を報告します。
tools: Read, Grep, Glob, Bash
コードは修正せず、コマンド、終了コード、失敗箇所を報告してください。
```
個人用は`~/.claude/agents/`、プロジェクト共有用は`.claude/agents/`に置きます。frontmatterは変わり得るため、公式文書とインストール済みバージョンを確認してください。
6. 安全チェックリスト
• 読み取りは並列化し、共有ファイルへの書き込みは直列化する。
• 各エージェントに質問・成果物・停止条件を一つずつ与える。
• 自己申告ではなく、コマンド、終了コード、diffを確認する。
• 非対話実行では承認が必要な操作が失敗し得る。
• 外部sandboxなしに`danger-full-access`や承認回避を使わない。
• 秘密、認証ファイル、個人パスを貼り付けない。
• 少ない同時数から始め、計測後に増やす。
7. 再現可能なレシピ
**Map → Decide → Change → Verify**を使います。独立領域を探索し、メインが範囲を決め、一人のworkerが編集し、verifierが再検証し、メインが証拠で完了を判断します。
価値は人数ではなく境界です。読み取り専用探索、証拠中心の検証、明示的なファイル所有でメイン文脈を清潔に保てます。
参考資料
• https://developers.openai.com/codex/subagents
• https://developers.openai.com/codex/config-reference
• https://developers.openai.com/codex/config-file/config-advanced
• https://developers.openai.com/codex/cli