codex-orchestrator

Codex Orchestrator

専門分野に特化した Codex CLI サブエージェントを起動し、的を絞った開発タスクを実行します。各プロファイルでは、エージェントの動作、注力する領域、出力形式を定めるカスタムの AGENTS.md ペルソナを適用します。

アーキテクチャ

Claude Code (orchestrator)
    ↓ invokes skill
codex-orchestrator scripts
    ↓ spawns via Bash
Codex CLI with AGENTS.md
    ↓ executes
Specialized subagent task

前提条件

Codex CLI がインストールされ、設定されていることを確認します。

~/.claude/skills/codex-orchestrator/scripts/codex-status.sh

必須：

• Codex CLI：npm install -g @openai/codex
• API Key：export OPENAI_API_KEY=sk-...

自動更新

このスキルは呼び出されるたびに Codex CLI の更新を自動で確認し、必要に応じて更新します。これにより、古い CLI バージョンに起因する問題を防ぎます。

手動で確認・更新するには：

# Check version only
~/.claude/skills/codex-orchestrator/scripts/codex-version-check.sh

# Check and auto-update if needed
~/.claude/skills/codex-orchestrator/scripts/codex-version-check.sh --auto-update

利用可能なプロファイル

プロファイル	目的	使用する場面
reviewer	コード品質、バグ、パフォーマンス	コミット前のレビュー、PR の評価
debugger	根本原因の分析、修正	バグの調査、問題の追跡
architect	システム設計、コンポーネントの境界	変更の計画、アーキテクチャの評価
security	OWASP、脆弱性、シークレット	セキュリティ監査、コンプライアンスチェック
refactor	コードの整理、モダナイズ	技術的負債の削減、構造の改善
docs	API ドキュメント、README、コメント	ドキュメント関連のタスク
planner	ExecPlan 設計ドキュメント	数時間かかるタスク、複雑な機能、大規模なリファクタリング
syseng	インフラストラクチャ、DevOps、CI/CD、モニタリング	デプロイ、コンテナ、可観測性、本番環境の運用
builder	グリーンフィールド実装、新機能	仕様に基づく新規コードの作成、段階的な機能開発
researcher	読み取り専用の Q&A、コードベース分析	質問、分析、比較（ファイル変更なし）
adjudicator	読み取り専用の比較証拠の評価	仮説が曖昧な場合、解釈の相違、コーパスの比較、符号値の判定
chat	自由形式の会話	一般的な質問、ブレインストーミング、議論（読み取り専用、一時的）
goal	/goal の実行に向けた目標の仕様	自律型の数時間にわたる Codex セッション用の構造化された目標の作成

クイック実行

特定のプロファイルで単発のタスクを実行します。

~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh <profile> "<prompt>"

例：

# Code review
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Review src/auth.ts for security issues"

# Debug investigation
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh debugger "Debug the login timeout on slow networks"

# Architecture design
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh architect "Design a caching layer for the API"

# Security audit
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh security "Audit the payment module for vulnerabilities"

# Write profiles auto-approve by default (uses -a never + --sandbox workspace-write)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Fix all lint errors"

# Create execution plan for complex feature
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh planner "Create an ExecPlan for adding WebSocket support"

# Build new feature from spec
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "Implement user authentication with JWT"

# Continue from previous builder session
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "continue"

# Open-ended conversation (read-only, ephemeral, gpt-5.6-terra via subscription)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "What are the tradeoffs of event sourcing vs CRUD?"

# Conversation via API billing (gpt-5.6-sol, bypasses Codex subscription)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "Explain quantum error correction" --api --model gpt-5.6-sol

# Multi-turn API chat with session file
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "What is the tallest mountain?" --api --session /tmp/chat.json
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "And the deepest ocean?" --api --session /tmp/chat.json

# Streaming API response
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "Tell me about CQRS" --api --model gpt-5.6-sol --stream

# Ask a question about the codebase (read-only, no file changes)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh researcher "Explain the authentication flow in this project"

# Weigh rival hypotheses or ambiguous evidence (read-only, high reasoning)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh adjudicator "With Linear B and Linear A inscriptions side-by-side, weigh candidate values for the missing sound and rank the hypotheses."

# Research with Exa web search (injects Exa guide into AGENTS.md)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh researcher "What are the latest React Server Component patterns?" --web-search

# Research with native Codex web search (model-level tool, works in all sandboxes)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh researcher "What are the latest React patterns?" --search

# Review a screenshot (vision input)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Review this mockup for UX issues" --image screenshot.png

# Resume previous builder session
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "continue" --resume

# JSONL output for structured capture
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh researcher "What is 2+2?" --json | head -5

セッション管理

より細かく制御するには、Python セッションマネージャーを使用します。

# List available profiles
python3 ~/.claude/skills/codex-orchestrator/scripts/codex-session.py list

# Start non-interactive session
python3 ~/.claude/skills/codex-orchestrator/scripts/codex-session.py start debugger "Trace the null pointer in UserService"

# Start interactive session
python3 ~/.claude/skills/codex-orchestrator/scripts/codex-session.py interactive architect

# Show profile details
python3 ~/.claude/skills/codex-orchestrator/scripts/codex-session.py info security

プロファイル選択ガイド

レビュータスク

• 一般的なコード品質やバグには reviewer
• 脆弱性に重点を置いたレビューには security
• 整理できる箇所の洗い出しには refactor

調査タスク

• バグの調査には debugger
• システムの動作を理解するには architect
• 質問や分析には researcher（読み取り専用、変更なし）
• 対立する仮説、曖昧な証拠、コーパスレベルの比較の評価には adjudicator（読み取り専用、高度な推論）
• 自由形式の会話やブレインストーミングには chat（読み取り専用、一時的）

作成タスク

• 設計上の判断には architect
• 新機能の実装には builder
• ドキュメントには docs
• 実装の改善には refactor
• 数時間にわたる実装計画には planner
• 自律型の /goal 目標仕様には goal

連携パターン

レビュー → デバッグ → 修正

# 1. Identify issues
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Review src/api/ for bugs"

# 2. Investigate specific bug
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh debugger "Debug the race condition found in cache.ts"

プランナー → アーキテクト → ビルダー

# 1. Create comprehensive ExecPlan
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh planner "Create ExecPlan for new authentication system"

# 2. Validate architecture
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh architect "Review the auth system ExecPlan for design issues"

# 3. Build (plan guides implementation)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "Implement milestone 1 from the auth ExecPlan"

アーキテクト → ビルダー → レビュアー

# 1. Design approach
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh architect "Design a caching layer for the API"

# 2. Build the feature
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "Implement the caching layer from architect's design"

# 3. Review the implementation
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Review the new caching implementation"

アーキテクト → レビュー → リファクタリング

# 1. Design approach
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh architect "Design repository layer extraction"

# 2. Validate design
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Review the proposed repository pattern"

# 3. Implement
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh refactor "Extract repository pattern from services"

システムエンジニアリング → アーキテクト → プランナー

# 1. Assess infrastructure needs
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh syseng "Evaluate current deployment for scaling to 10x traffic"

# 2. Design architecture changes
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh architect "Design infrastructure to support 10x scale"

# 3. Create implementation plan
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh planner "Create ExecPlan for infrastructure scaling"

セキュリティ → システムエンジニアリング

# 1. Security audit
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh security "Audit the Kubernetes cluster configuration"

# 2. Infrastructure hardening
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh syseng "Implement security recommendations from audit"

リサーチャー → アーキテクト → ビルダー

# 1. Understand the problem space
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh researcher "How does the current caching work? What are its limitations?"

# 2. Design the solution
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh architect "Design a new caching layer addressing the limitations"

# 3. Implement
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "Implement the caching layer from architect's design"

バックグラウンド実行と並列実行

Codex CLI v0.124.0+ では、制御用 TTY が必要です。シェルの & や Claude Code の run_in_background: true を使用して実行すると、TTY が切り離され、Codex は何も出力せずに終了します（openai/codex#19945）。プロンプトが長いほど失敗しやすくなります（実測で確認済み）。researcher プロファイルは特に影響を受けやすくなっています。

codex-exec.sh と codex-goal.sh は、TTY のないコンテキストを自動的に検出し、script(1) で codex exec をラップして擬似 TTY を再接続します。ユーザー側での操作は不要です。

codex-exec.sh を介さずに codex exec を直接呼び出す場合は、手動でラップしてください。

# macOS
script -q /dev/null codex exec --skip-git-repo-check "prompt" </dev/null

# Linux
script -qfc 'codex exec --skip-git-repo-check "prompt" </dev/null' /dev/null

AGENTS.md のバックアップは PID ごとに分けられるため、複数の codex-exec.sh インスタンスを同じディレクトリで安全に実行できます。

--no-cleanup フラグ（codex-exec.sh のみ）：このフラグを設定すると、終了後も出力一時ファイルが保持され、そのパスが stderr に出力されます（OUTPUT_FILE=<path>）。呼び出し元が出力ファイルを非同期に取得する必要がある場合に使用してください。

Goal の実行

/goal コマンドは、Codex が何時間も自律的に取り組む永続的な目標を設定します。Goals は TUI 専用（codex exec モードでは利用不可）のため、Goal の実行には 2 段階のワークフローを使用します。

2 段階のワークフロー

フェーズ 1 — 下書き： goal プロファイルを使って codex exec を実行し、構造化された Goal 仕様ファイルを生成します。

フェーズ 2 — 実行： 仕様ファイルから /goal を設定して、対話型の Codex TUI を起動します。

使用方法

# Draft a goal specification
~/.claude/skills/codex-orchestrator/scripts/codex-goal.sh draft "Add authentication with JWT to the API"

# Draft with custom output path
~/.claude/skills/codex-orchestrator/scripts/codex-goal.sh draft "Migrate to PostgreSQL" --output goals/pg-migration.md

# List existing goals
~/.claude/skills/codex-orchestrator/scripts/codex-goal.sh list

# Launch Codex TUI with a goal
~/.claude/skills/codex-orchestrator/scripts/codex-goal.sh run goals/goal-20260518-143000.md

# Run with custom model
~/.claude/skills/codex-orchestrator/scripts/codex-goal.sh run goals/goal-01.md --model gpt-5.6-sol

Goal ファイルの形式

Goal の仕様は、YAML フロントマターを含む構造化形式に従います。

---
objective: "One-line summary"
status: draft
created: 2026-05-18
project: /path/to/project
---

# Goal: <objective>

## Objective / Stopping Condition / Context / Constraints / Validation / Checkpoints / Progress Log

3,500 文字未満の Goal は /goal コマンドに直接埋め込まれます。それより長い Goal はファイルパスで参照されます。

連携：Planner → Goal → Run → Reviewer

# 1. Plan the feature
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh planner "Create ExecPlan for caching layer"

# 2. Draft a goal from the plan
~/.claude/skills/codex-orchestrator/scripts/codex-goal.sh draft "Implement caching layer per ExecPlan"

# 3. Launch autonomous goal run
~/.claude/skills/codex-orchestrator/scripts/codex-goal.sh run goals/goal-20260518-143000.md

# 4. Review what Codex built
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Review the caching implementation"

注意事項

• /goal は TUI 専用です。run サブコマンドは対話型の Codex セッションを起動します（stdin はリダイレクトされません）。
• ~/.codex/config.toml で features.goals = true を設定する必要があります（または --enable goals フラグを使用します。スクリプトが自動的に渡します）。
• スレッドごとに設定できる Goal は 1 つだけです。別の Goal を設定する前に /goal clear を実行する必要があります。
• /goal の内容は 4,000 文字までです（下書きフェーズでは余裕を確保するため、3,500 文字未満を目標とします）。

/goal コマンドの詳細については、references/goal-command.md を参照してください。

スクリプトオプション

codex-exec.sh のオプション

オプション	説明
--model <model>	モデルを上書きします（デフォルト：プロファイルごとの設定。下記参照）
--reasoning <level>	推論の強度を上書きします：minimal、low、medium、high、xhigh
--sandbox <mode>	read-only、workspace-write、danger-full-access
--no-approve	読み取り専用のサンドボックスを強制します（ファイルへの書き込みなし）
--web-search	Exa のウェブ検索を有効にします（ガイドを AGENTS.md に挿入）
--search	Codex ネイティブのウェブ検索を有効にします（モデルレベルのツールで、すべてのサンドボックスで動作）
--json	JSONL イベントストリームを出力します（jq、ログなどにパイプできます）
--image <file>	プロンプトに画像を添付します（視覚入力）
--resume	前回の exec セッションを再開します（builder の「continue」ワークフロー）
--with-mcp	（何もしません。互換性のために保持されています。MCP は ~/.codex/config.toml で管理してください）
--api	OpenAI API を直接使用します（Codex サブスクリプションではなく、API 課金）
--session <file>	複数ターンの API チャット用のセッションファイルです（--api が必要）
--system <prompt>	API チャット用のシステムプロンプトです（--api が必要）
--stream	API 応答のトークンをストリーミングします（--api が必要）

モデルと推論のデフォルト設定

各プロファイルには、デフォルトのモデルと推論の強度が設定されています。ユーザーフラグを指定すると、これらが上書きされます。

プロファイルの種類	プロファイル	モデル	推論
コーディング	builder, reviewer, debugger, refactor, syseng, security, docs	gpt-5.6-sol	high
プランニング	planner, architect, goal	gpt-5.6-sol	high
リサーチ	researcher	gpt-5.6-sol	medium
判定	adjudicator	gpt-5.6-sol	high
チャット	chat	gpt-5.6-terra	medium

推論の強度：none < minimal < low < medium < high < max

# Uses profile defaults (builder → gpt-5.6-sol + high)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "Implement auth module"

# Uses profile defaults (planner → gpt-5.6-sol + high)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh planner "Create ExecPlan for caching"

# Override model for quick tasks
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Style check" --model gpt-5.6-luna

# Override reasoning only
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "Quick lint fix" --reasoning medium

# Override both
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh planner "Design distributed cache" --model gpt-5.6-sol --reasoning max

API モード（OpenAI API の直接利用）

--api フラグを指定すると、Codex CLI 全体を経由せず、gpt-api-chat.py を通じて OpenAI API を直接呼び出します。料金は Codex サブスクリプションではなく、OPENAI_API_KEY に請求されます。

API モードを使う場合：

• Codex サブスクリプションに含まれないモデルを利用する場合（例：gpt-5.6-sol）
• セッションを保持した複数ターンの会話
• ストリーミング応答
• カスタムシステムプロンプト

# One-shot API query
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "Explain X" --api --model gpt-5.6-sol

# Multi-turn with session file (context carries across calls)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "What is X?" --api --session /tmp/session.json
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "Tell me more" --api --session /tmp/session.json

# Streaming output
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "Describe Y" --api --model gpt-5.6-sol --stream

# Custom system prompt
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "Analyze this" --api --system "You are a security analyst"

# Any profile works with --api (sends raw prompt to OpenAI API, no Codex CLI)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh researcher "What are the latest React patterns?" --api --model gpt-5.6-sol

対応モデル： gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna、gpt-5.5、gpt-5.5-pro、gpt-5.4、gpt-5-mini

3者間モード（Claude + GPT）： Claude Code のセッション内で、Bash 経由で gpt-api-chat.py を呼び出し、GPT の応答を読み取って、各視点を統合しながら会話を進行します。--session を使うと、複数ターンにわたって GPT のコンテキストを維持できます。

必要条件： 環境内の OPENAI_API_KEY（~/.config/env/secrets.env から読み込まれます）

テスト

インストールを確認するには、テストスイートを実行します。

~/.claude/skills/codex-orchestrator/scripts/test-codex.sh         # Full tests
~/.claude/skills/codex-orchestrator/scripts/test-codex.sh --quick # Skip API test

リファレンスドキュメント

詳しくは、次を参照してください。

• references/codex-cli.md - CLI コマンドの完全なリファレンス
• references/agents-md-format.md - AGENTS.md の構文とベストプラクティス
• references/subagent-patterns.md - 委譲パターンと使用例
• references/goal-command.md - /goal コマンドのリファレンスとベストプラクティス

トラブルシューティング

「Codex CLI が見つかりません」

npm install -g @openai/codex

「認証エラー」

export OPENAI_API_KEY=sk-...
# or
codex login

「ChatGPT アカウントではモデルがサポートされていません」

古いモデル名（codex-mini、o3、o4-mini）は非推奨になりました。現在のモデル：gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna、gpt-5.5、gpt-5.5-pro、gpt-5-mini。前世代のモデル（gpt-5.4、gpt-5.4-pro、gpt-5.3-codex、gpt-5.2）も引き続き動作しますが、後継モデルに置き換えられています。 codex login を使わずに API キーを設定します。

export OPENAI_API_KEY=sk-...

「プロファイルが見つかりません」

利用可能なプロファイル：reviewer、debugger、architect、security、refactor、docs、planner、syseng、builder、researcher、adjudicator、chat、goal

プロファイルが存在することを確認します。

ls ~/.claude/skills/codex-orchestrator/agents/

「Codex の出力がありません」

researcher／adjudicator／chat プロファイルは、出力を一時ファイルに保存します。Codex がファイルに書き込まずに終了すると、スクリプトは警告を出して終了コード 1 で終了します。一般的な原因：

• TTY の切り離し（最も一般的）：Codex CLI v0.124.0 以降では、TTY なしでバックグラウンド実行すると、警告なしにクラッシュします。codex-exec.sh は script(1) で自動的にラップします。Codex のバージョンを確認してください（codex --version）。プロンプトが長いほど、失敗する可能性が高くなります。
• Codex セッションが短すぎて、応答を生成できなかった
• モデルが空の応答を返した（再試行してください）
• AGENTS.md がなかった（作業ディレクトリに古い .AGENTS.md.codex-backup.* ファイルがないか確認してください）

結果が良くない場合

• タスクの範囲を絞ります
• プロンプトにより多くのコンテキストを含めます
• 別のプロファイルを試します
• 複雑なタスクには --model gpt-5.6-sol --reasoning max を使います