Codex Hooksとは？AGENTS.mdでは守りきれないルールを設定で動かす機能
Codex Hooksとは、Codexの動作の節目で、ユーザーが決めた処理を自動で実行する仕組みです。
節目にあたるのは、セッションの開始、ツールの実行前後、プロンプトの送信時、Codexが応答を終えたときなどです。OpenAI の公式ドキュメントによると、hooksは「Codexの拡張フレームワーク」で、エージェントの処理ループの中でスクリプトやMCPツールを実行するものと説明されています（出典: chatgpt.com）。設定はJSONかTOMLの設定ファイルに書くだけで、Codex本体のプログラムを変更する必要はありません。
関連記事：Codexでできることを一覧で整理｜非エンジニアでも使える活用法まで
Hooksでできる4つのこと
Hooksの用途は、公式ドキュメントが挙げている例をたどると大きく4つに分かれます。
- ブロック：危険なコマンドや、貼り付けられたAPIキーを含む入力を、実行や送信の前に止める
- 記録：やり取りをログ基盤に送ったり、会話を要約してメモとして残したりする
- 検証：作業が終わるたびに、決めた条件を満たしているかを確認して足りなければ続きを促す
- 文脈の注入：ディレクトリごとに前提や指示を自動で伝え、プロンプトを補う
どれも「人が毎回思い出して確認する」作業を設定で自動化するものです。ブロックは越えてはいけない一線を守る保険になり、記録と検証は成果物の品質を一定に保ちます。文脈の注入は、同じ説明を毎回書く手間を減らします。
AGENTS.md・サンドボックス・承認との違い
Codexには、ルールを守らせるための仕組みがHooks以外にもあります。AGENTS.mdはプロジェクトの前提やルールを文章で伝える仕組みで、Codexはそれを読んで判断します。サンドボックスはファイルやネットワークへのアクセス範囲を物理的に制限する仕組みで、承認ポリシーは操作のたびに人の許可を求めるかを決めます。下表は、動く仕組み・確実性・向いている用途の3観点で4つを整理したものです。ルールの性質に合わせて使い分ける視点が欠かせません。
| 観点 | Codex Hooks | AGENTS.md | サンドボックス | 承認ポリシー |
|---|---|---|---|---|
| 動く仕組み | 設定したイベントで、決めた処理が必ず実行される | Codexが文章を読み、状況に応じて従うかを判断する | 書き込みや通信の範囲をOS側で制限する | 操作ごとに人の許可を求める |
| 確実性 | 決定論的（設定どおりに毎回動く） | 確率論的（守られないことがある） | 決定論的（範囲の外には出られない） | 決定論的（ただし人の判断に依存する） |
| 向いている用途 | 特定のコマンドの停止、ログ記録、終了時の検証など、条件を自分で定義したいルール | 書き方の方針や背景説明など、判断を委ねたい指示 | 「このフォルダの外は触らない」のような境界 | 判断の難しい操作を人に委ねたいとき |
Hooksの位置づけは「サンドボックスより細かく、承認より手間のかからない制御」です。たとえば「本番環境のデータベースに向けたコマンドだけ止める」は、サンドボックスでは表現しにくく、承認に任せると毎回の確認が負担になります。Hooksなら、コマンドの文字列を見て条件に合うものだけを止められます。
Claude Code Hooksとの違いと流用できる範囲
Claude CodeにもHooksがあり、イベント名や入出力のJSONの形はよく似ています。PreToolUse、PostToolUse、UserPromptSubmit、Stopといった主要なイベント名は共通で、終了コード2で止める考え方も同じです。一方で、設定ファイルの置き場所、動くハンドラーの種類、trustの有無が異なります。下表は、Codexへ流用するときに確認する3点を整理したものです。
| 観点 | Codex Hooks | Claude Code Hooks |
|---|---|---|
| 設定ファイル | `hooks.json`、または`config.toml`の`[hooks]`テーブル | `settings.json`の`hooks`キー |
| 動くハンドラー | `command`と`mcp_tool`。`prompt`と`agent`は読み込まれるが実行されない | `command`、`http`、`mcp_tool`、`prompt`、`agent` |
| 実行前の承認 | ハッシュ単位でtrust（信頼）が必要。変更すると再確認になる | trustの工程はない |
Claude Code向けに書いたスクリプトの中身は、入力のJSONの形が近いため大部分をそのまま使えます。移すときに直すのは、設定ファイルの形式と置き場所、promptやagentで判断させていた部分の2点です。公式ドキュメントは、プラグインに同梱したhooksのコマンドにCLAUDE_PLUGIN_ROOTなどの環境変数も渡すと説明しており、既存のプラグインのhooksを動かす互換性にも配慮されています。
関連記事：Claude Code Hooksとは？CLAUDE.mdでは守れないルールを確実に動かす設定と使い方
利用できる条件
Hooksは既定で有効になっており、設定ファイルを置くだけで使えます。公式ドキュメントの範囲では、プランによる利用制限は示されていません。無効にしたい場合は、config.tomlの[features]にhooks = falseを書きます。
注意したいのは、hooksが動くのは個人の環境で動くCodexである点です。公式ドキュメントによると、クラウド側で複数の作業を調整する企業向けの構成では、管理者が定義したMCPツールのhooksだけが動き、コマンド型のhooksやローカルの設定ファイルのhooksは使えません。自分の環境で試した設定が、そのまま会社全体に効くとは限らないと押さえておきます。
Codex Hooksの仕組み｜イベント・ハンドラー・matcher・trustで動きが決まる
Hooksの設定は、3つの要素の組み合わせで決まります。
- イベント：どのタイミングで動くか（ツールの実行前、応答の完了時など）
- ハンドラー：何を実行するか（シェルコマンド、MCPツール）
- matcher：どの対象に絞って動かすか（Bashのときだけ、など）
これに加えて、設定したhooksを実行してよいかを確認するtrust（信頼）の工程があります。
AIエージェントを「どう作り、どう育てるか」を、GiftX記事制作エージェントの実物で解説。
主なイベントと発火タイミング
公式ドキュメントには12のイベントが定義されています。最初に押さえるのは、下表にまとめたものです。
| イベント | 発火するタイミング | 実行を止められるか |
|---|---|---|
| SessionStart | セッションの開始・再開・履歴の圧縮後 | 止められない（文脈の注入に使う） |
| UserPromptSubmit | プロンプトの送信時、Codexが処理する前 | 止められる |
| PreToolUse | ツール呼び出しの実行前 | 止められる。入力を書き換えて通すこともできる |
| PermissionRequest | ツール呼び出しに許可の判断が必要なとき | 代わりに許可・拒否を返せる |
| PostToolUse | ツール呼び出しの完了後 | 実行済みのため取り消せない |
| Stop | Codexが応答を終えたとき | 続行を要求できる |
| SubagentStart / SubagentStop | サブエージェントの開始時・終了時 | 開始は止められない |
| SessionEnd | 会話の終了時（アーカイブ、通常終了、30分の無操作） | 止められない |
PreToolUseは「実行前に止める」、PostToolUseは「実行後に後処理する」と役割がはっきり分かれています。Stopは応答が終わるたびに発火し、decisionにblockを返すと、その理由が次の指示としてCodexに渡されて作業が続きます。
ハンドラーの種類とタイムアウト
ハンドラーは「何を実行するか」を決める部分で、typeで指定します。実行されるのはcommand（シェルコマンド）とmcp_tool（接続済みのMCPサーバーのツール）の2種類です。promptとagentは設定を読み込めますが、現時点では実行されずに飛ばされます。
タイムアウトはtimeoutに秒で指定します。既定は600秒ですが、SessionEndとInterruptだけは既定1秒、最大3秒です。"async": trueを付けると処理を待たずに先へ進み、1つのセッションで最大8本まで同時に動きます。ただし非同期にしたhooksは、操作を止めたり書き換えたりはできません。
OpenAI の公式ドキュメントによると、hooksの出力がおよそ2,500トークンを超えると、全文はディスクに保存され、モデルには冒頭の抜粋だけが渡されます（出典: chatgpt.com）。上限はadditionalContextLimitで変えられ、0にすると全文が渡ります。
matcherと終了コード・JSON出力
matcherで反応する対象を絞り、終了コードとJSON出力で結果を伝えます。
matcherの書き方
matcherは正規表現の文字列です。ツール系のイベント（PreToolUse、PostToolUse、PermissionRequest）ではツール名が対象で、^Bash$のように書くとシェルコマンドのときだけ反応します。apply_patchはファイル編集のEditやWriteにも一致します。
SessionStartは開始の種類（startup、resume、clear、compact、fork）で絞り込めます。"*"か空文字、または省略ですべてに一致し、UserPromptSubmit、Stop、Interruptではmatcherを指定しても無視されます。
終了コードとJSON出力
処理の結果は、まず終了コードで伝えます。exit 0で何も出力しなければ成功です。exit 2で理由をstderrに書くと、PreToolUse、UserPromptSubmit、Stopのように止められるイベントでは処理がブロックされ、理由がCodexに渡ります。
細かい制御ではstdoutにJSONを書きます。PreToolUseならhookSpecificOutput.permissionDecisionにdenyかallowを入れ、denyなら理由をpermissionDecisionReasonで返します。allowと一緒にupdatedInputを返すと、コマンドの中身を書き換えてから通すこともできます。
Codexが対応していないフィールドを返すと、そのhooksは失敗扱いになり、ツール呼び出し自体は続行されます。止めたつもりで止まっていない事故を避けるため、最初はexit 2方式から始めると確実です。
trust（信頼）の仕組み：変更のたびに再確認が要る
Codex Hooks固有の工程がtrustです。管理者が配布したものを除き、hooksは内容を確認して信頼する操作を済ませるまで実行されません。信頼はhooksの内容のハッシュ値に対して記録されるため、コマンドを1文字でも変えると「未確認」に戻り、再び信頼するまで飛ばされます。
確認はCLIの/hooksコマンドで行い、読み込み元の一覧、確認待ちのhooks、個別の無効化ができます。起動時の警告が/hooksへ誘導するので、動かないときはまずここを見ます。--dangerously-bypass-hook-trustで一時的に確認を飛ばせますが、通常の運用には向きません。プラグインに同梱されたhooksも、インストールしただけでは信頼されない点は同じです。
Codex Hooksの使い方｜hooks.jsonの書き方と最初の設定例
設定は、hooks.jsonの中にhooksというキーを作り、イベント名ごとにmatcherとハンドラーの配列を並べる形で書きます。公式のHooksのリファレンスの構成に沿って、最初の1本から見ていきます。
設定ファイルの置き場所と読み込み順
Codexがhooksを読む場所は4つです。自分専用の~/.codex/hooks.jsonと~/.codex/config.toml、プロジェクト共有の<リポジトリ>/.codex/hooks.jsonと<リポジトリ>/.codex/config.tomlです。すべての場所にあるhooksが合わせて実行され、プロジェクト側は.codexフォルダが信頼済みのときだけ読み込まれます。
OpenAI の公式ドキュメントによると、同じ場所にhooks.jsonとconfig.tomlの[hooks]テーブルの両方があると、Codexは両方を読み込んだうえで警告を出すため、1つの場所では1つの形式に揃えることが推奨されています（出典: chatgpt.com）。
関連記事：Codexの設定方法｜設定ファイルconfig.toml・AGENTS.mdと権限のおすすめ設定
最初の1本は危険なコマンドのブロックから
まず、rm -rfを含むシェルコマンドを実行前に止めるhooksを~/.codex/hooks.jsonに書きます。
\{"hooks": \{"PreToolUse": [\{"matcher": "^Bash$", "hooks": [\{"type": "command", "command": "python3 ~/.codex/hooks/block_rm.py", "timeout": 10\}]\}]\}\}
block_rm.pyは、標準入力のJSONからtool_input.commandを読み、rm -rfを含んでいればstderrに理由を書いてexit 2で終わる数行のスクリプトです。保存したら/hooksで設定が見えることを確かめ、確認待ちなら信頼する操作を済ませます。
全国8,000人調査で、AIの活用方法によって生産性向上に約3.8倍の差が生まれることが判明。
操作ログの記録と作業終了時のチェック
2本目と3本目は、プロジェクトの.codex/hooks.jsonに置く記録と検証のhooksです。
実行したコマンドをログに残す
PostToolUseイベントにmatcher^Bash$、コマンドにJSONをファイルへ追記するスクリプトを登録します。入力のtool_inputとtool_responseから、どのコマンドが何を返したかを1行ずつ記録できます。
作業が終わったらテストが通っているかを確かめる
Stopイベントに、テストが失敗していれば\{"decision": "block", "reason": "テストが失敗しています。修正してください"\}をstdoutに返すスクリプトを登録します。Stopではexit 0のときにJSONの出力が求められ、平文は無効になります。blockを返すとreasonが次の指示としてCodexに渡り、修正が続きます。無限に続かないよう、入力のstop_hook_activeを見て2回目以降は通す作りにしておきます。
どの業務のルールから設定に移すかは、「職種別AI活用事例集」が参考になります。
Before/Afterで見るCodex Hooks導入の業務インパクト
社内ツールの修正や定型スクリプトの作成をCodexに毎日任せている担当者1名を例に、Hooksを入れる前後の確認作業を比べます。
Before：実行のたびに人が確認する
Codexがコマンドを実行したりファイルを編集したりするたびに、危険な操作や触ってはいけない設定ファイルの変更がないかを目視で確認します。1日15回の実行に対して1回3分の確認で、1日45分、週にして約3.8時間を確認に使っている状態です。
After：確認は1日1回のログ確認だけ
PreToolUseのhooksで危険なコマンドは実行前に止まり、PostToolUseのhooksで操作ログが自動で残ります。担当者は1日1回ログを見るだけになり、確認は1日10分、週に約50分まで減ります。削減率は約78%で、時給3,000円換算では週約9,000円、年約45万円相当です。
チームの標準にする運用設計と、動かないときの確認手順
Hooksは設定ファイルの置き場所で共有される範囲が決まります。個人の~/.codexに置いた設定は他のメンバーの環境では動かず、チームで守らせたいルールはプロジェクトの.codexに置く必要があります。
| 置き場所 | 効く範囲 | 共有 |
|---|---|---|
| `~/.codex/hooks.json` | 自分の全プロジェクト | されない |
| `<リポジトリ>/.codex/hooks.json` | そのプロジェクト | リポジトリに含めて共有（各メンバーがtrustを済ませる必要がある） |
| `requirements.toml`の`[hooks]` | 組織全体 | 管理者が配布（各自では無効化できない） |
起点は、ブロックやログ記録のように例外を認めないルールを.codex/hooks.jsonに置いて共有することです。組織全体で揃える段階ではrequirements.tomlに移し、allow_managed_hooks_only = trueを設定すると、個人やプロジェクトのhooksは読み込まれなくなります。
GiftXのAIエージェント構築支援でも、記事制作を自動化するリポジトリの.codex/hooks.jsonにSessionStartとPreToolUseのhooksを置き、作業用ブランチの外で編集が始まる操作を止めています。
動かないときに見る3つの順番
設定したのにhooksが動かないときは、次の順番で確認すると原因を切り分けられます。
- trustの状態：
/hooksで確認待ちになっていないか。内容を変更した直後は未確認に戻る - プロジェクトの信頼：
.codexフォルダが信頼済みか。未信頼のプロジェクトでは設定ファイルごと無視される - matcherとイベント：ツール名と大文字小文字まで一致しているか。Stopでmatcherを書いていないか、JSONを返す必要のあるイベントで平文を出していないか
3つとも問題がなければ、timeoutの値とスクリプトの終了コードを見直します。特にSessionEndは最大3秒で切られるため、長い処理を入れていると静かに途中終了します。
Codex Hooksのよくある質問
Hooksを設定する前後で問い合わせが多い点を、公式ドキュメントの記述に沿って整理します。
Codex Hooksは無料で使えますか
Hooksは設定ファイルで動くCodexの機能で、公式ドキュメントにプラン別の制限は示されていません。既定で有効になっているため、追加の申し込みも不要です。ただし企業向けのクラウド構成では、管理者が定義したMCPツールのhooksだけが動きます。
Claude Codeのhooks設定をそのまま使えますか
そのままは使えません。イベント名と入力JSONの形は近いので、スクリプトの中身は大部分を流用できます。直すのは、settings.jsonからhooks.jsonまたはconfig.tomlへの書き換えと、promptやagentで判断させていた部分です。移したあとは、Codex側で/hooksから信頼する操作が必要になります。
プログラミングがわからなくても設定できますか
設定ファイルの形は決まっているため、公式の例を1つ選んで置き換えるだけなら難しくありません。止めるコマンドの条件を書くスクリプトは、Codex自身に「rm -rfを含むコマンドを止めるPreToolUseのhooksを作って」と頼んで作らせる方法もあります。作らせたあとに、何を止めて何を通すかを/hooksの確認画面で読んでから信頼する習慣を付けておきます。
hooksで危険なコマンドの実行を本当に止められますか
止められます。PreToolUseでexit 2かpermissionDecisionにdenyを返せば、そのツール呼び出しは実行されません。ただし、hooksが見ているのはシェルやファイル編集、MCPツールなどのローカルのツール呼び出しで、Web検索のようなホスト側のツールは対象外です。サンドボックスと組み合わせて、境界はサンドボックス、個別の条件はhooksと役割を分けると抜けが減ります。
まとめ｜Codex Hooksは最初の1本から
Codex Hooksは、Codexの動作の節目で決めた処理を必ず実行する仕組みで、AGENTS.mdの指示では守りきれないルールを設定に置き換えます。
イベント・ハンドラー・matcherの3要素と、exit 2で止める終了コードの意味、そして内容を変えるたびに再確認が要るtrustの工程を押さえれば、危険なコマンドのブロック、操作ログの記録、作業終了時の検証といった設定は公式ドキュメントの例をなぞるだけで動きます。チームで効かせるには、個人用ではなくプロジェクトの.codex/hooks.jsonに置いて共有し、組織全体で揃えたい段階でrequirements.tomlへ移す流れが現実的です。
Hooksを含めてCodexを業務の仕組みに組み込む段階では、GiftXが1業務単位のAIエージェント構築を伴走支援しています。詳細は AIエージェント構築支援サービス をご覧ください。
Codexに業務ルールを組み込みたい方へ
本記事で紹介したHooksのように、Codexを自社の業務ルールに沿って動かしたい、どの業務から任せるかを相談したいとお考えの方は、ぜひGiftX AIエージェント構築支援までお問い合わせください。
GiftX AIエージェント構築支援では、貴社の業務に合わせて1業務単位のスモールスタートから本番運用まで、AIエージェント構築をワンストップで支援します。ユースケースの洗い出しから、PoC、本番運用、社内ナレッジ化まで伴走します。
AI活用にご関心のある方は、ぜひ一度ご相談ください。
▶ GiftX AIエージェント構築支援の詳細・お問い合わせはこちら
