Codex を使うだけで終わらせない：Hook が高度な使い方になる

Codex を使うとき、多くの人は「コードを書かせる」「ファイルを直す」「コマンドを実行させる」ことに注目します。もちろんそれは Codex の最も分かりやすい能力です。しかしそこで止まると、より高度な使い方に向いた機能を見落としがちです。それが Hook です。

Hook の価値は、Codex にもっとコードを書かせることではありません。Codex をよりルールに沿って動かすことにあります。Hook は、ユーザーが prompt を送信する前、ツール呼び出しの前後、権限要求時、ターンの停止時など、Codex の重要なライフサイクルイベントでカスタムスクリプトを実行できます。これにより、チームルール、セキュリティチェック、プライバシー保護、自動記録を Codex のワークフローに組み込めます。

典型例はプライバシーチェックです。ユーザーが prompt を Codex に送る前に、API key、token、秘密鍵、電話番号、内部アドレス、その他の機密情報が含まれていないか Hook でスキャンします。ルールに一致した場合は送信を止めるか、明確な警告を出して、先に内容を整理してもらいます。

Hook とは何か

Codex Hook は、Codex ワークフロー内のライフサイクルハンドラと考えると分かりやすいです。指定したイベントが発生すると起動し、現在のコンテキストを JSON としてスクリプトに渡します。スクリプトは警告、追加コンテキスト、一部イベントでの後続アクションのブロックを返せます。

公式ドキュメントでは、Hook の用途として次のような例が挙げられています。

会話をカスタムログや分析システムへ送る；
チームの prompt をスキャンして API key の誤貼り付けを防ぐ；
会話を自動要約して永続メモリを作る；
会話ターン終了時にカスタム検証を実行する；
現在のディレクトリに応じて特定のプロンプトやルールを補足する。

つまり Hook は、普通のプロンプト技法というより、ワークフロー制御と安全ガードレールの層です。プロンプトは Codex に何をすべきかを伝え、Hook は Codex の動作前後にチェック、記録、制約を差し込みます。

Hook を置く場所

Codex は hooks.json から Hook を読み込むことも、config.toml の [hooks] テーブルからインライン設定を読み込むこともできます。よく使う場所は次の 4 つです。

~/.codex/hooks.json
~/.codex/config.toml
<repo>/.codex/hooks.json
<repo>/.codex/config.toml

ユーザー単位の Hook は、「疑わしい秘密情報を送らない」「毎回終了時に要約する」といった個人共通ルールに向いています。プロジェクト単位の Hook は、「生成ディレクトリを直接編集しない」「コミット前に front matter を確認する」「コマンド実行前に危険操作を止める」といったリポジトリ規約に向いています。

プロジェクトローカルの .codex/ 設定は、そのプロジェクト層が信頼されたときだけ読み込まれます。ユーザー単位の Hook はプロジェクトの信頼状態に依存しません。プロジェクト内の Hook はローカルスクリプトを実行する設定なので、未知のリポジトリを無条件に信頼すべきではありません。

よく使うトリガー

Hook には複数のトリガーがあります。イベントごとに向いている用途が違います。

UserPromptSubmit は、ユーザーの prompt が送信される直前に発生します。プライバシーチェック、機密語チェック、prompt ポリシーチェックに向いています。たとえば prompt に sk- で始まる key が含まれていそうなら、その送信を止められます。

PreToolUse は、Codex がツールを呼び出す前に発生します。コマンド、ファイル書き込み、MCP ツール呼び出しのブロックに向いています。たとえば rm -rf、システムディレクトリへの書き込み、機密パスの読み取りを検出して拒否理由を返せます。

PermissionRequest は、Codex が権限を要求しようとするときに発生します。明確に定義された権限要求を自動許可または拒否する用途に向いています。固定のテストコマンドは許可し、特定ディレクトリへのアクセスは拒否する、といった使い方です。

PostToolUse は、ツール実行後に発生します。コマンド出力の確認、生成ファイルのスキャン、後続手順のリマインドに向いています。すでに発生した副作用は取り消せませんが、Codex が続行する前に追加フィードバックを渡せます。

SessionStart は、セッション開始時または復帰時に発生します。プロジェクト規約、チームルール、よく使うコンテキスト、ローカルメモを読み込む用途に向いています。

Stop は、1 ターンの応答が停止する直前に発生します。テストを実行したか、TODO が残っていないか、もう一度検証すべきか、といった終了前チェックに使えます。

プライバシーチェック Hook の設計

プライバシーチェックは UserPromptSubmit に置くのが自然です。ユーザー内容が Codex のワークフローに入る前に発火するからです。最初から完璧を目指さず、誤って貼り付けやすい内容から始めるのが現実的です。

まずは次のようなパターンを確認します。

OpenAI、GitHub、クラウド事業者の API key；
-----BEGIN PRIVATE KEY----- のような秘密鍵ブロック；
.env ファイル断片；
アクセストークン、Bearer token、JWT；
内部ドメインやデータベース接続文字列；
ID 番号、電話番号、メールアドレスなどの個人情報。

Hook スクリプトは JSON 入力を受け取り、prompt フィールドを読み、正規表現やルール表でスキャンします。問題が見つかったら、次のようにブロックできます。

1
2
3
4


{
  "decision": "block",
  "reason": "疑わしい API key を検出しました。機密情報を削除してから送信してください。"
}

ブロックせずに追加コンテキストだけを返すこともできます。ただし、秘密鍵、秘密情報、トークンのような高リスク内容は、直接ブロックする方が安全です。

`hooks.json` 設定例

リポジトリ単位で設定するなら、.codex/hooks.json を作成します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python .codex/hooks/privacy_check.py",
            "timeout": 10,
            "statusMessage": "Checking prompt privacy"
          }
        ]
      }
    ]
  }
}

対応するスクリプトは標準入力から JSON を読み取れます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


import json
import re
import sys

payload = json.load(sys.stdin)
prompt = payload.get("prompt", "")

patterns = [
    r"sk-[A-Za-z0-9_-]{20,}",
    r"ghp_[A-Za-z0-9_]{20,}",
    r"-----BEGIN [A-Z ]*PRIVATE KEY-----",
    r"Bearer\s+[A-Za-z0-9._-]{20,}",
]

for pattern in patterns:
    if re.search(pattern, prompt):
        print(json.dumps({
            "decision": "block",
            "reason": "疑わしい secret、token、private key を検出しました。機密情報を先に削除してください。"
        }, ensure_ascii=False))
        raise SystemExit(0)

これは考え方を示す例です。実運用では、ルールを保守しやすいリストに分け、誤検知を調整します。通常のドキュメントに Bearer の例があるだけなら漏えいとは限りませんし、テスト用のダミー key がある場合もあります。ルールが厳しいほど誤検知が増え、緩いほど本当のリスクを見落としやすくなります。

`config.toml` のインライン形式

別の hooks.json を管理したくない場合は、config.toml に書くこともできます。インライン TOML Hook は hooks.json と同じイベント構造を使います。

1
2
3
4
5
6
7
8


[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = 'python ".codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

同じ設定レイヤーに hooks.json とインライン [hooks] が両方ある場合、Codex は両方を読み込み、警告します。実際のプロジェクトでは、ルールを追いやすくするためにどちらか一方に揃える方がよいです。

Hook 利用時の注意点

第一に、Hook はローカルコマンドを実行するため、ソースを必ず確認します。非管理 Hook は review と trust の後でなければ実行されません。Hook 定義が変わった場合も再度 trust が必要です。知らないリポジトリの .codex/hooks.json を気軽に許可すべきではありません。

第二に、複数の一致する Hook が実行される可能性があります。1 つの Hook ですべてを止められると仮定せず、ルール同士を衝突させないようにします。チーム環境では、ユーザー単位、プロジェクト単位、管理者管理のどのルールなのかを明確にします。

第三に、Hook はガードレールであり、完全なセキュリティ境界ではありません。たとえば PreToolUse は多くのツール呼び出しを止められますが、公式ドキュメントでもすべての shell 呼び出し経路やすべての非 shell・非 MCP ツールを網羅するわけではないと説明されています。高リスクな場面では、権限設定、サンドボックス、コードレビュー、最小権限が引き続き必要です。

第四に、Hook スクリプトは速くするべきです。プライバシースキャンやコマンドレビューはインタラクションの途中に入ります。毎回数十秒かかると体験を大きく損ないます。単純なルールで済むものは単純なルールにし、毎回重い外部サービスを呼ばないようにします。

第五に、出力形式を厳密に守ります。イベントによってサポートされる戻り値フィールドは異なります。UserPromptSubmit は decision: "block" で prompt を止められますが、PreToolUse には独自の hookSpecificOutput 構造があります。Hook を書く前に、対象イベントの入出力仕様を確認します。

最初に作る価値がある Hook

使い始めたばかりなら、いきなり複雑な企業向けポリシーシステムを作る必要はありません。まずは 3 つの小さな場面から始めるのがよいです。

1 つ目はプライバシーチェックです。実際の効果が出やすく、個人にもチームにも向いています。秘密情報、token、.env 断片の誤貼り付けは、AI コーディングワークフローで現実的に起こる問題です。

2 つ目は危険コマンドのブロックです。Bash の PreToolUse に対して、再帰削除、システムディレクトリの変更、未知のリモートへのアップロードを止める基本ルールを置けます。

3 つ目は終了前チェックです。Stop や PostToolUse を使って、終了前にテスト、ビルド、フォーマット、ドキュメント、未コミット変更を確認するよう促せます。必ずしも強制ブロックする必要はなく、リマインドだけでも仕上げ忘れを減らせます。

結論

Codex Hook の高度な点は、単に機能が 1 つ増えることではありません。「ルール」を Codex の実行ループに接続できることです。

通常の使い方では、prompt で Codex に何をすべきか伝えます。高度な使い方では、Hook で重要なタイミングにルール通り動いているかを確認します。プライバシーチェック、コマンドレビュー、権限ポリシー、セッション要約、終了前検証を、口頭の注意から実行可能なワークフローにできます。

Codex を実際のプロジェクトで使い始めているなら、Hook は早めに設定する価値があります。人間の判断、サンドボックス、権限制御を置き換えるものではありませんが、忘れやすい安全要件や手順を、毎回自動で発火する既定動作にできます。

参考資料：OpenAI Codex Advanced Configuration - Hooks、OpenAI Codex Hooks