---
title: "Codex Desktopのサブエージェントとhooksを検証｜設定が静かに無視される罠"
excerpt: "Codex Desktopでサブエージェントとhooksを設定し、動くもの・動かないものを切り分けました。サブエージェントは.codex/agents/にtomlを置くだけで動作、一方hooksはv26.422では未実装で設定がエラーなく無視されます。あわせてコンテキストウィンドウが経路によって1M→400K→実効258Kと変わる事実も記録しています。"
author: "AI活編集部"
author_username: ai-katsu-editorial
published_at: 2026-04-27T00:00:00+00:00
verified_at: 2026-04-27T00:00:00+00:00
models: ["OpenAI Codex", "Claude Code"]
tools: ["MCP"]
tasks: ["開発・エンジニアリング", "ツール検証"]
canonical_url: https://ai-katsu.jp/articles/codex-desktop-subagents-hooks
---
# Codex Desktopのサブエージェントとhooksを検証｜設定が静かに無視される罠

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

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

## この検証の概要

| 項目 | 内容 |
| --- | --- |
| 検証日 | 2026年4月27日 |
| 対象 | Codex Desktop（OpenAI）v26.422.30944（macOS） |
| 検証内容 | サブエージェント機能・Hooks機能 |
| 結果 | **サブエージェントは動作確認済み／HooksはDesktop v26.422では未実装（設定は静かに無視される）** |
| 付随する発見 | **Codexのコンテキストは400Kに制限。CLI実効値は約258,400トークン** |
| 状況 | 完了（一部機能は未対応を確認） |

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

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

| 機能 | 結果 |
| --- | --- |
| **サブエージェント** | **動作確認済み。**`.codex/agents/` にtomlを置くだけで即認識 |
| **Hooks（Desktop）** | **発火せず。**`codex_hooks` フィーチャーキーがv26.422では未実装 |

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

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

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

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

## Claude Codeとの機能対応

| 機能 | Claude Code | Codex Desktop/CLI |
| --- | --- | --- |
| サブエージェント | あり（Agentツール） | あり（`.codex/agents/*.toml`） |
| Hooks | あり（7イベント） | CLIはあり / **Desktopは未対応**（v26.422） |
| MCP統合 | あり | あり（豊富、自身をMCPサーバーに公開も可） |
| 設定ファイル | CLAUDE.md | AGENTS.md（**形式非互換**） |
| パーミッションモード | 3段階 | 3段階（**OSサンドボックスが強み**） |
| GitHub Action | なし（公式） | あり（公式サポート） |
| スラッシュコマンド | あり | あり（`/review` `/diff` `/compact` 等） |

設定ファイルの**形式が非互換**である点は、両方を使う場合に効いてきます。同じ内容を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種類で固定**です。

| イベント | タイミング |
| --- | --- |
| `SessionStart` | セッション開始時 |
| `PreToolUse` | ツール実行直前 |
| `PostToolUse` | ツール実行直後 |
| `PermissionRequest` | 承認要求前 |
| `UserPromptSubmit` | プロンプト送信時 |
| `Stop` | 会話終了時 |

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

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

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

| アクセス経路 | GPT-5.4 | GPT-5.5 | gpt-5.4-mini |
| --- | --- | --- | --- |
| API | 1,050,000 | 1,050,000 | 400,000 |
| ChatGPT（ブラウザ/アプリ） | 1,050,000 | 1,050,000 | 400,000 |
| **Codex Desktop** | **400,000** | **400,000** | — |
| Codex CLI（公称） | 400,000 | 400,000 | — |
| **Codex CLI（実効値）** | **約258,400** | **約258,400** | — |

ポイントは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導入を支援しています。ご相談は[お問い合わせフォーム](/contact)から、継続的な伴走支援については[AI参謀](/ai-sanbo)をご覧ください。