Codex Desktopのサブエージェントとhooksを検証｜設定が静かに無視される罠【AI活用検証vol.75】

AIコーディングツールを比較するとき、チャットの精度だけを見ると判断を誤ります。自動化・並列化の仕組みがあるかで、実務での使い方が変わるためです。

この検証では、Codex DesktopのサブエージェントとHooksを実際に設定し、動くもの・動かないものを切り分けました。あわせてコンテキストウィンドウが経路によって大きく違うという事実も確認しています。

この検証の概要

結論：サブエージェントは動く、DesktopのHooksは動かない

切り分けた結果はこうです。

Hooksについて重要なのは、設定は静かに無視されるという点です。エラーも警告も出ません。

気づけたのは、アプリログの Features enabled を確認したためです。

# 実際のログ
Features enabled: "enable_request_compression, collaboration_modes, personality,
request_rule, fast_mode, image_generation, ..."
# → codex_hooks の記載なし

設定を書いたのに動かないとき、ログの有効フィーチャー一覧を見るのが最短の切り分けです。設定ファイルの書き方を延々と疑う前に、そもそも機能が有効かを確認できます。

Claude Codeとの機能対応

設定ファイルの形式が非互換である点は、両方を使う場合に効いてきます。同じ内容を2つの形式で維持することになります。

サブエージェント：tomlを置くだけ

設定は単純です。プロジェクト配下の .codex/agents/ に .toml ファイルを置くだけで認識されます。config.toml への追記は不要です。

name = "code-reviewer"
description = "Review diffs and report concrete risks before summarizing."
developer_instructions = """
You are a review-focused sub-agent.
Inspect the diff carefully and report:
- correctness bugs
- behavioral regressions
- security or data-loss risks
- missing tests
Order findings by severity, cite files and lines when possible.
"""
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"

プロジェクトを trust_level = "trusted" に設定していれば即時認識され、デスクトップUIからスレッドとして呼び出せます。

特徴はエージェントごとにモデル・推論レベル・MCPサーバーをオーバーライドできる点です。レビュー用は軽量モデル、設計用は高性能モデルといった使い分けができます。

Hooks：書き方の落とし穴

Desktopでは発火しませんでしたが、設定の書き方自体には確認できた点があります。

[features]
codex_hooks = true

[[hooks.PreToolUse]]
command = "/path/to/scripts/security-check.sh"

書き方の注意点

• [hooks.PreToolUse]（単一テーブル）はエラー。[[hooks.PreToolUse]]（配列テーブル）が正しい
• matcher = { tool_name = "bash" } はエラー。matcher = "bash" の文字列形式が正しい
• スクリプトを置くだけでは動作しない。必ず config.toml への登録が必要

イベントは6種類で固定です。

イベント種類はプラットフォーム固定でユーザーによる追加・変更は不可ですが、1つのイベントに複数スクリプトを設定でき、各スクリプトに matcher で実行条件を絞り込めます。

コンテキストウィンドウは経路で変わる

この検証で最も実務的な発見です。

ポイントは3つあります。

① Codexは上限が400Kに制限されている——APIやChatGPTでは1,050,000トークン使えますが、Codex Desktop・CLIはモデル仕様の約1/3に絞られています。

② CLIの実効値はさらに低い（既知のバグ）——CLIが「272K入力 + 128K出力 = 400K」という分割値を誤認し、実際には約258,400トークンしか使えない状態です。修正要求のIssueが上がっています。

③ GPT-5.5リリース後、1M設定が機能しなくなった——以前は config.toml での1M設定が動いていたケースがありましたが、機能しなくなったとの報告が多数あります。

感覚的に整理するとこうなります。

ChatGPT/API : 1,050,000トークン（本の約800ページ分）
Codex Desktop:   400,000トークン（約300ページ分）
Codex CLI実効:   258,400トークン（約200ページ分）

「モデルのコンテキスト長」と「そのツールで実際に使える長さ」は別物です。ツール選定時にはモデル仕様だけを見ても判断できません。

だからサブエージェントが要る

この2つの発見はつながっています。

Codexはコンテキストが意図的に絞られているため、大規模プロジェクトほどサブエージェントで分割処理する必要性が高くなります。

ただし、分割の価値はそれだけではありません。

並列処理の本質は「速さ」だけでなく「各エージェントが迷わず集中できること」です。コンテキストウィンドウが大きくても並列処理が有効なのは、各エージェントが専用のクリーンなコンテキストで作業できるため品質が上がるからです。

ビジネス側への説明

非エンジニアに伝えるなら、次の言い換えが分かりやすくなります。

• サブエージェント = 「複数担当者を同時にアサインする感覚」
• Hooks = 「AIの行動にコンプライアンス・承認・ログを自動連動させる仕組み」

Hooksは、AIが何かをする前後に自動でスクリプトを走らせる仕組みです。承認プロセスや監査ログを、人の運用ではなく仕組みで担保できます。

よくある質問

Codex DesktopでHooksは使えますか？

v26.422時点では使えません。codex_hooks フィーチャーキーが未実装で、設定は静かに無視されます。アプリログの Features enabled に含まれていないことで確認できます。CLI版には実装されています。

サブエージェントの設定方法は？

.codex/agents/ に .toml ファイルを置くだけです。config.toml への追記は不要で、プロジェクトが trusted であれば即時認識されます。

Hooksの設定でエラーが出ます

[[hooks.PreToolUse]] の配列テーブル形式を使ってください。[hooks.PreToolUse]（単一テーブル）はエラーになります。matcher も文字列形式（matcher = "bash"）が正しい書き方です。

Codexのコンテキストは1Mではないのですか？

APIやChatGPT経由では1,050,000トークンですが、Codex Desktop・CLIは400Kに制限されています。さらにCLIは既知のバグにより実効値が約258,400トークンにとどまります。

まとめ

• サブエージェントは.codex/agents/ にtomlを置くだけで動作。モデル・推論レベルをエージェント単位で指定できる
• Desktop v26.422ではHooksが未実装。設定はエラーなく静かに無視される
• 動かないときはログの Features enabled を確認するのが最短の切り分け
• Hooksの書き方は[[hooks.PreToolUse]] の配列テーブル形式、matcher は文字列形式
• Codexのコンテキストは400K（CLI実効値は約258,400）。モデル仕様の1Mとは異なる
• 並列処理の価値は速さだけでなく各エージェントがクリーンなコンテキストで集中できること

ツールの機能表と実際に動くものは一致しないことがあります。導入判断の前に、使いたい機能が本当に有効かを確認しておくと手戻りが減ります。

株式会社AI棒では、こうしたAI活用の検証を日々行い、企業の開発体制へのAI導入を支援しています。ご相談はお問い合わせフォームから、継続的な伴走支援についてはAI参謀をご覧ください。