Codex エージェント設定
SpecDojo CLI と Codex CLI を組み合わせてマルチエージェント実行を行うための設定・構成を定義する。
1. 設計方針
共通の責務分担、実行フロー、割り当て、失敗処理、worktree は エージェント共通設定 に従う。本書では Codex CLI 固有の設定だけを定義する。
Codex CLI は非対話実行、sandbox、reasoning effort、構造化出力を組み合わせられるため、自動化・CI・複雑な実装タスクに適する。
- 非対話実行は
codex exec: TUI を起動せず、タスクプロンプトを渡して応答後に終了する。approval_policy="never"を指定し、sandbox 外の操作は承認待ちにせず失敗としてrunnerへ返す。 - 用途別モデル分担: 標準作業を高速・低コストモデル、複雑な設計判断を高性能モデルで分担する。
- 制限情報は実行結果から扱う: token usage は JSONL から取得できるが、session limit や quota 残量を返す専用 status API を前提にしない。
- 共有設定は
.codex/config.toml: trusted project で読み込まれるプロジェクトデフォルトを定義する。 - プロジェクト共通ルールは
AGENTS.md: セッション開始時に自動読み込みされる。 - custom agent は
.codex/agents/*.toml: 親 Codex が明示的に spawn する subagent の定義に使用する。SpecDojo が直接起動する worker とは分離する。 - 権限は最小化する: edit / review ともresult更新のため
workspace-writeを使用する。reviewはplanで成果物変更を禁止する。danger-full-accessと--yoloは使用しない。
2. 責務分担
3層の共通責務は親設計に従う。Codex agent は、Codex 固有の sandbox、reasoning effort、モデル、構造化出力を使用して plan を処理する。claim、complete、reopen、block、並列起動、worktree 管理は行わない。
3. 全体フロー
specdojo exec run
→ providers.codex の command template から解決した codex exec --ephemeral ... を起動
→ plan を標準入力で渡す
→ Codex agent が成果物または result を編集
→ Codex CLI の終了状態を共通フローへ返すedit / review の選択と終了後の状態遷移は親設計に従う。
4. ディレクトリ構成
repo-root/
├─ AGENTS.md # プロジェクト共通ルール
├─ .codex/
│ ├─ config.toml # プロジェクト共通設定
│ └─ agents/
│ ├─ codex-executor.toml # 必要時に親 Codex が spawn する pipeline executor（edit）subagent
│ ├─ codex-expert-executor.toml # 複雑な作業用の expert pipeline executor（edit）subagent
│ ├─ codex-review-executor.toml # 必要時に親 Codex が spawn する pipeline executor（review）subagent
│ └─ codex-expert-review-executor.toml # 複雑なレビュー用の expert pipeline executor（review）subagent個人設定・認証情報・CLI profile は ~/.codex/ に置き、リポジトリへコミットしない。
SpecDojo の project management 配下と worktree の共通構成は親設計を参照する。
5. 認証・モデル設定
5.1. 認証方法
| 方式 | 用途 | 設定方法 |
|---|---|---|
| ChatGPT サインイン | 個人開発・対話利用 | codex login / codex login --device-auth |
| OpenAI API key | CI/CD・自動化・利用量課金 | API key を使用して codex login |
CODEX_API_KEY | 単一の codex exec 自動実行 | 実行プロセスだけに環境変数を注入 |
| Codex access token | Enterprise の信頼済み自動実行 | 管理者が許可した trusted runner で使用 |
API key はジョブ全体の環境変数に設定せず、codex exec 実行時だけ注入する。~/.codex/auth.json は秘密情報として扱い、コミットしない。
5.2. モデル選択
モデルは .codex/config.toml の model または codex exec --model で指定する。モデル名と推奨モデルは Codex の更新に合わせて見直す。
| 用途 | モデル例 | reasoning effort | 方針 |
|---|---|---|---|
| 標準 edit / review | gpt-5.4-mini | medium | 高速・低コストな通常作業 |
| expert edit / review | gpt-5.5 | high | 複雑な分析・設計判断・重要レビュー |
6. .codex/config.toml 設計
.codex/config.toml は trusted project で読み込まれるプロジェクト共通設定である。認証・provider・個人 profile は置かず、チームで共有可能な実行デフォルトのみ定義する。
実際のファイル: .codex/config.toml
model = "gpt-5.5"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
[agents]
max_threads = 6
max_depth = 1自動実行では .specdojo/exec-defaults.yaml の command template で sandbox を明示する。CLI flag と -c key=value は .codex/config.toml より優先される。--profile は ~/.codex/<profile-name>.config.toml を読み込む個人設定であり、プロジェクト共有設定としては使用しない。
7. AGENTS.md 設計
リポジトリルートの AGENTS.md は、すべての Codex セッションが読み込む共通ルールを記述する。Language・Project Policy・Safety の3セクションで構成する。
Codex は Git root から現在の作業ディレクトリまで AGENTS.md を探索し、より近いディレクトリの指示を後から適用する。局所ルールは対象ディレクトリの AGENTS.md、一時的な上書きは AGENTS.override.md に記述する。
# Agent Instructions
## Language
- 回答は原則として日本語で行う。
## Project Policy
- 変更前に関連する設計書を確認する。
- タスクに関係しない変更を行わない。
## Safety
- 認証情報、秘密鍵、`.env`、`secrets/` を読み込まない。
- 破壊的変更や `git push` を行わない。SpecDojo のタスク実行手順（plan の読み方・result の記入方法）は exec plan ファイル自体に記載されるため、AGENTS.md には含めない。AGENTS.md はプロジェクト全体の言語・ポリシー・安全規則のみを定義する。
8. Codex worker と custom agent の設計
worker は全員 stage_role（executor / reporter）を持つ pipeline 構成とし、単体で edit/review を完結する legacy 構成は使わない。stage_role: executor は成果物の編集・検証だけを行い result を更新せず、mode: edit は成果物への書き込みを許可し、mode: review は成果物・result のいずれへの書き込みも developer_instructions と plan の指示で禁止する（Codex の sandbox はパス単位の書き込み制御を持たないため、この境界はプロンプトと specdojo CLI の commit 許可リストで作る）。stage_role: reporter は executor の evidence から構造化 result を作るだけで、ファイルへは一切書き込まない。
8.1. SpecDojo worker
specdojo exec run が直接起動する Codex プロセスを worker と呼ぶ。worker のモデル・reasoning effort・sandbox は .specdojo/exec-defaults.yaml の providers.codex の command template で指定し、worker は渡された plan を1件だけ実行する。
| nickname | mode | stage_role | モデル例 | reasoning effort | sandbox | 用途 |
|---|---|---|---|---|---|---|
codex-executor | edit | executor | gpt-5.4-mini | medium | workspace-write | 標準的な文書作成・実装（result は更新しない） |
codex-expert-executor | edit | executor | gpt-5.5 | high | workspace-write | 複雑な設計判断・詳細分析を伴う実装 |
codex-review-executor | review | executor | gpt-5.4-mini | medium | workspace-write | done_criteria の多観点レビュー（成果物・result いずれも変更しない） |
codex-expert-review-executor | review | executor | gpt-5.5 | high | workspace-write | 高品質な多観点レビュー（成果物・result いずれも変更しない） |
codex-reporter | - | reporter | gpt-5.4-mini | medium | workspace-write | evidence からの構造化 result 生成 |
8.2. .codex/agents/*.toml
custom agent は親 Codex セッションが明示的に spawn する subagent である。SpecDojo が複数 worker を起動する仕組みとは別であり、1つの複雑な plan 内で探索・レビューなどを委譲する場合だけ使用する。worker の nickname と名称を揃えているが、codex-reporter はファイルへ一切書き込まない役割のため subagent 定義を持たない。
必須フィールドは name・description・developer_instructions。モデル、reasoning effort、sandbox などは親セッションから継承するか、agent ファイルで上書きする。本文には最小限の実行契約だけを置き、タスク固有の手順は edit / review plan を正本とする。
codex-executor は成果物を編集・検証するため workspace-write を使用するが、result は更新しない（reporter / runner の責務として扱う）。
実際のファイル: .codex/agents/codex-executor.toml
codex-expert-executor は複雑な分析・設計判断を伴う executor plan を担当し、gpt-5.5 と reasoning effort high を使用する。result は更新しない。
実際のファイル: .codex/agents/codex-expert-executor.toml
codex-review-executor は成果物・result のいずれも変更せず、review plan の各観点に従ってレビューするだけである。Codex の sandbox はパス単位の書き込み制御を提供しないため workspace-write のままだが、成果物・result への書き込み禁止を developer_instructions と plan で制約する。
実際のファイル: .codex/agents/codex-review-executor.toml
codex-expert-review-executor は複雑な多観点 review plan を担当し、成果物・result のいずれも変更しない。gpt-5.5 と reasoning effort high を使用する。
実際のファイル: .codex/agents/codex-expert-review-executor.toml
配布原本は templates/codex/agents/ 配下に置く。利用プロジェクトの .codex/agents/ へは specdojo exec scaffold --provider codex で配置する。
| ファイル名 | モデル | reasoning effort | sandbox | 用途 |
|---|---|---|---|---|
codex-executor.toml | gpt-5.4-mini | medium | workspace-write | pipeline executor（edit） |
codex-expert-executor.toml | gpt-5.5 | high | workspace-write | pipeline expert executor（edit） |
codex-review-executor.toml | gpt-5.4-mini | medium | workspace-write | pipeline executor（review） |
codex-expert-review-executor.toml | gpt-5.5 | high | workspace-write | pipeline expert executor（review） |
並列 write は競合しやすいため、親セッションからsubagentをspawnする場合も同一ファイルを複数agentへ割り当てない。
8.3. agent 選択の仕組み
Codex連携には、SpecDojo workerの選択とCodex custom subagentの選択という2段階がある。command lineの引数だけで .codex/agents/*.toml を選択する仕組みではない。
sch-strategy の phase 要件
↓
SpecDojo が .specdojo/agent-members.yaml から worker を選択
↓
providers.codex の command template を worker 属性で展開して codex exec を起動
↓
Codex が AGENTS.md と標準入力の plan を読み込む
↓
必要な場合だけ、親 Codex が .codex/agents/*.toml の custom subagent を spawnSpecDojo workerの選択
specdojo exec run は、taskのphase要件と .specdojo/agent-members.yaml の各memberを次の順で照合する。
type: agentであり、起動コマンドを解決できる（provider に command template があるか、member にcommand上書きがある）memberだけを候補にする。- taskのagent_pipeline stage（
executor/reporter）とmemberのstage_roleが一致する候補だけを残す。 - memberが
modeを持つ場合は、taskのmodeと一致する候補だけを残す（modeを持たない member は edit/review どちらのtaskにもマッチする）。reporterstageの選定ではtaskのmodeそのものを比較条件に使わない（reporterの役割はedit/reviewで変わらないため）。 - taskが要求する
capabilitiesをすべて持つ候補だけを残す。 - taskに
proficiencyが指定されている場合は、同じ値の候補だけを残す。 priorityの数値が小さい候補を優先する。priorityが同じ場合は、task要件に対する余分なcapabilityが少ない候補を優先する。
並べ替え後の先頭候補が通常の実行workerになる。critical path上でrate limitが発生し、fallback方針が try_next の場合は、同じ条件に適合する後続候補を順に試す。
たとえば、phaseが mode: edit、stage_role: executor、proficiency: expert、capabilities: [web_search] を要求する場合、codex-expert-executor がCodex候補になる。選択後に実行されるcommandは次のとおりである。
codex exec \
--ephemeral \
--sandbox workspace-write \
-c approval_policy='"never"' \
-c sandbox_workspace_write.network_access=false \
--model gpt-5.5 \
-c model_reasoning_effort='"high"'このcommandの --model、--sandbox、model_reasoning_effort は、選択済みworkerの実行設定であり、worker名を選択する引数ではない。codex exec にはOpenCodeやClaude Codeの --agent <name> に相当する直接worker選択オプションはない。
memberを明示して実行する場合は --by にnicknameを指定する。
specdojo exec run --by codex-executor --task <task-id>
specdojo exec run --by codex-expert-review-executor --task <task-id>--by は member 選択と、event や result に記録する actor の指定を兼ねる。
Codex custom subagentの選択
.codex/agents/*.toml は、起動済みの親Codexが内部で追加agentへ委譲する場合の定義である。SpecDojoと codex exec のcommand lineは、このファイルを直接選択しない。
codex-executor.toml: 親Codexが標準edit作業（成果物の編集・検証のみ、result更新なし）を分担させる場合のsubagentcodex-expert-executor.toml: 親Codexが複雑なedit作業を分担させる場合のsubagentcodex-review-executor.toml: 親Codexが標準reviewを分担させる場合のsubagent（成果物・result いずれも変更しない）codex-expert-review-executor.toml: 親Codexが複雑なreviewを分担させる場合のsubagent（成果物・result いずれも変更しない）
親Codexはsubagentのnameとdescriptionを参照し、必要な場合に明示的にspawnする。spawnしない場合、.codex/agents/*.toml はworker実行へ影響せず、workerは AGENTS.md、command template から解決した起動コマンド、標準入力のplanだけで動作する。
workerのnicknameとcustom subagentのnameは運用上同じ名称に揃えているが、Codex CLIが自動的に両者を関連付けるわけではない。たとえば .specdojo/agent-members.yaml で codex-expert-executor が選ばれても、.codex/agents/codex-expert-executor.toml が自動適用されることはない。
9. エージェント割り当て設定
9.1. 起動コマンドの設計
起動コマンドは親設計の 起動コマンドの解決 に従い、.specdojo/exec-defaults.yaml の providers.codex で定義する。.specdojo/agent-members.yaml の member には command を書かない。codex exec には worker 名を選択するオプションがないため、テンプレートに {nickname} は含めず、モデルと reasoning effort を command_params.by_proficiency で切り替える。
providers:
codex:
command_template: 'codex exec --ephemeral --sandbox workspace-write -c approval_policy="never" -c sandbox_workspace_write.network_access=false --model {model} -c model_reasoning_effort="{effort}"'
command_params:
by_proficiency:
normal: { model: gpt-5.4-mini, effort: medium }
expert: { model: gpt-5.5, effort: high }.specdojo/agent-members.yaml の member は選択属性だけを持つ。全員 stage_role（executor / reporter）を持つ pipeline member とし、単体で edit/review を完結する legacy member は使わない。
members:
- nickname: codex-executor
type: agent
provider: codex
mode: edit
stage_role: executor
capabilities: [web_search]
proficiency: normal
priority: 2
scheduler_strategy: critical-first
- nickname: codex-expert-executor
type: agent
provider: codex
mode: edit
stage_role: executor
capabilities: [web_search]
proficiency: expert
priority: 1
scheduler_strategy: critical-first
- nickname: codex-review-executor
type: agent
provider: codex
mode: review
stage_role: executor
capabilities: [web_search]
proficiency: normal
priority: 2
scheduler_strategy: fifo
- nickname: codex-expert-review-executor
type: agent
provider: codex
mode: review
stage_role: executor
capabilities: [web_search]
proficiency: expert
priority: 1
scheduler_strategy: fifo
- nickname: codex-reporter
type: agent
provider: codex
stage_role: reporter
capabilities: []
proficiency: normal
priority: 2
scheduler_strategy: fifo--ephemeral はセッション rollout ファイルを保存しない。実行履歴の正本は SpecDojo の event・plan・result とする。モデル名の更新（例: 新世代モデルへの切り替え）は command_params.by_proficiency の1箇所だけを変更すればよく、member 定義には影響しない。
9.2. sch-strategy-<track>.yaml
phase の共通契約は親設計に従う。Codex の Web 検索が必要な phase は capabilities: [web_search] を指定し、複雑な実装や設計判断が必要な場合は proficiency: expert を指定する。
9.3. .specdojo/exec-defaults.yaml
共通の retry / fallback / block 方針とグローバル既定 / provider 別上書きの2層構造は親設計に従う。Codex 固有の検出条件は providers.codex.rate_limit_detection に置き、.specdojo/agent-members.yaml で provider: codex の member に適用する。
Codex worker は workspace-write sandbox 内で npm run test:unit を実行する。実 Git・worktree・CLI 子プロセスを必要とする integration テストは sandbox を広げず、SpecDojo 親 runner の固定許可リストへ分離する。
pipeline:
parent_validations:
- test-integration
providers:
codex:
rate_limit_detection:
stderr_patterns:
- "rate limit"
- "429"
- "session limit"
- "weekly limit"
- "usage limit"test-integration は親 runner が npm run test:integration として shell: false で実行する固定 ID である。Codex の出力に書かれた command は実行せず、親検証結果だけを source: runner 付きで evidence へ追記する。これにより danger-full-access を使わず、reporter が単体・統合の両方を根拠に判定できる。
Codex は API 利用と ChatGPT プラン利用で limit の考え方が異なり、複数の limit がスタックする。共通モデルへの写像は親設計の limit 表に従う。
| limit | 概要 | reset horizon | provider_signal.kind | 扱い |
|---|---|---|---|---|
rate limit（429） | API リクエスト過多による一時制限 | 秒〜分 | rate_limit | limited / retryable。wait+backoff か try_next |
| 5時間枠（session） | ChatGPT プランのローリング5時間枠。ローカルメッセージとクラウドタスクで共有 | 時間 | session_limit | limited。別 provider / 別アカウントへ try_next を優先 |
| 週次上限 | 5時間枠とは別にスタックする週次上限。5時間枠の reset では回復しない | 日〜週 | quota_exhausted | limited だが run 内回復は不可。try_next か block |
429 または rate limit を示すメッセージを rate limit シグナルとして検出する。session limit / weekly limit も CLI の stderr message として現れうるため検出対象に含める。共通層では limited として扱うが、provider 固有シグナルでは rate_limit / session_limit / quota_exhausted を区別して保持する。残量と reset 時刻は codex の /status で人が確認する補助情報とし、自動制御は message pattern と exit code に基づく。汎用的な exit_codes: [1] は使わず stderr で判定する。
stderr の実文言は CLI バージョンで変わりうるため、上記 pattern は実際の出力で検証してから確定する。
実際のファイル: .specdojo/exec-defaults.yaml
9.4. exec run による実行
共通の実行コマンドは親設計を参照する。Codex member は phase の capabilities / proficiency と .specdojo/agent-members.yaml の属性により自動選択される。
10. 非対話実行と出力
codex exec は進捗を stderr、最終メッセージを stdout に出力する。--json を指定すると JSONL イベントを stdout に出力できる。SpecDojo の判定を構造化出力へ拡張する場合は、--output-schema と --output-last-message の利用を検討する。
--json の turn.completed event には usage 情報を含められるため、input token、cached input token、output token などの実測値は取得できる。一方で、残り quota、残り session 枠、reset 時刻を返す documented な共通 status コマンドは前提にしない。codex login status は認証状態の確認用であり、利用残量 API ではない。
codex exec \
--ephemeral \
--sandbox workspace-write \
--model gpt-5.4-mini \
-c approval_policy='"never"' \
-c model_reasoning_effort='"medium"' \
"SpecDojo task を1件実行してください"specdojo exec run との統合では、plan の内容は引数ではなく stdin 経由で渡す。YAML frontmatter の --- がコマンドラインオプションとして誤認されるのを防ぐためである。
cat exec/plans/<task-id>-plan.md | codex exec \
--ephemeral \
--sandbox workspace-write \
--model gpt-5.4-mini \
-c approval_policy='"never"' \
-c model_reasoning_effort='"medium"'非対話実行では新しい承認要求に応答できない。必要な操作が sandbox の範囲を超える場合は、権限を広げて再実行せず非0で終了し、runner に block 判断を戻す。
11. worktree 分離セットアップ
worktree のライフサイクル、配置、ブランチ名、イベントファイル名は親設計に従う。edit worker の並列実行ではworktreeを使用する。review workerは workspace-write だが成果物を変更せずresultだけを更新するため、成果物競合防止を目的としたworktree分離は不要とする。