Codex を開発チームに広げると、「本番のデータベースに触るコマンドは止めたい」「作業が終わったら必ずテストを走らせたい」「プロンプトに API キーを貼っていないか確かめたい」といった要望が出てきます。どれも研修やガイドラインで呼びかけることはできますが、全員が毎回守るとは限りません。

こうしたルールを 仕組みとして自動でかける のが Codex の hooks です。hooks は、Codex が作業を進める途中の決まった場面(コマンドを実行する前・プロンプトを送る前・作業の区切りが付いたときなど)で、社内で用意したスクリプトや MCP のツールを自動で呼び出します。

この記事では、hooks の置き場所、使えるイベント、コマンドを止める書き方、信頼の確認、管理者が全員に配る方法、そして hooks だけに頼れない理由を整理します。製品の内容は、2026年11月10日に OpenAI の公式ドキュメント「Hooks」で確かめた範囲に絞りました。スクリプトの中身の書き方は会社ごとに違うため、ここでは扱いません。

結論: 管理者の hooks と現場の hooks を分ける

先に要点をまとめます。

  1. hooks は Codex の作業の途中で社内のスクリプトを自動で動かす仕組み。既定で有効になっている
  2. 置き場所は個人(~/.codex/)とリポジトリ(<repo>/.codex/)の hooks.json か config.toml。見つかった hooks はすべて動き、上の層が下の層を置き換えることはない
  3. 会社の管理下にない hooks は、利用者が中身を確認して信頼するまで動かない。書き換えると信頼し直しになる
  4. 全員に必ずかけたいルールは、requirements.toml の managed_dir で配る。こちらは利用者が止められない
  5. hooks は「完全な強制の境界ではない」と公式に書かれている。サンドボックスと承認の設定の代わりにはしない

hooks でできること

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

  • やり取りの記録を残す
  • プロンプトに API キーが貼り付けられていないかを調べる
  • 要約からメモリーを作る
  • 作業の区切りでチェックを走らせる

法人の現場に置き換えると、たとえば次のような使い方が考えられます。

やりたいこと 使うイベント hooks の動き
危ないコマンドを止める PreToolUse コマンドの中身を調べ、社内で禁止しているものなら実行を断る
承認の判断を一部自動にする PermissionRequest 承認を求める場面で、許可または拒否を返す
秘密情報の貼り付けを防ぐ UserPromptSubmit 送信前のプロンプトを調べ、鍵らしい文字列があれば送らせない
作業の終わりに検査を走らせる Stop テストや静的検査を動かし、失敗したら続きの作業を頼む
利用の記録を残す SessionStart・SessionEnd など セッションの開始と終了を社内の記録に送る

hooks の置き場所

Codex は、有効になっている設定の層の隣にある hooks.json か、config.toml の中の [hooks] の表から hooks を探します。公式ドキュメントが「もっとも使う」として挙げている置き場所は次の4つです。

置き場所 効く範囲 向いている hooks
~/.codex/hooks.json その人のすべての作業 個人の記録や通知
~/.codex/config.toml その人のすべての作業 同上(TOML で書きたいとき)
<repo>/.codex/hooks.json そのリポジトリでの作業 プロジェクトのテストや検査
<repo>/.codex/config.toml そのリポジトリでの作業 同上(TOML で書きたいとき)

このほか、プラグインの中に hooks/hooks.json を入れたり、.codex-plugin/plugin.json に hooks の項目を書いたりして配ることもできます。

ここで押さえておきたい点は3つです。

  1. すべての層の hooks が動く: 優先度の高い層が低い層の hooks を置き換えることはなく、条件に合う hooks はすべて実行されます
  2. 同じ層に両方あると合わさる: 1つの層に hooks.json と [hooks] の両方があると、Codex は両方を合わせて読み込み、起動時に警告を出します。社内ではどちらか一方にそろえるほうが混乱しません
  3. リポジトリの hooks は信頼済みのときだけ: プロジェクトの .codex/ の層が信頼されていないと、そのプロジェクトの hooks は読み込まれません

使えるイベント

hooks をどの場面で動かすかは、イベントの名前で指定します。公式ドキュメントに載っているイベントは次のとおりです。

イベント 動く場面
SessionStart セッションやサブエージェントが始まったとき
UserPromptSubmit プロンプトを送る前
PreToolUse ツールを実行する前
PermissionRequest Codex が承認を求めようとしたとき
PostToolUse ツールが結果を返したあと
PreCompact・PostCompact 会話の要約(コンパクション)の前とあと
SubagentStart・SubagentStop サブエージェントの開始と終了
Stop 1回の作業の区切りが付いたとき
PreModelRequest・PostModelRequest モデルへのリクエストの前とあと(診断用)
Interrupt 実行中の作業が中断されたとき
SessionEnd メインのセッションが終わったとき(サブエージェントでは動かない)

PreToolUse・PostToolUse・PermissionRequest では、matcher に正規表現を書いて対象のツールを絞れます。公式ドキュメントには Bash・apply_patch・Edit|Write・mcp__filesystem__.* といった例が載っています。* や空の文字列にするか、書かなければすべてが対象です。UserPromptSubmit・Stop・Interrupt は matcher を見ません。

設定の書き方

config.toml に書く場合、公式ドキュメントの例は次の形です。Bash のコマンドを実行する前に、リポジトリの中のチェック用スクリプトを動かします。

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

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

hooks.json で書く場合も中身は同じで、イベントの下に matcher のまとまりを置き、その中に実際に動かす処理(ハンドラー)を並べます。ハンドラーの種類は、コマンドを動かす command と、接続済みの MCP サーバーのツールを呼ぶ mcp_tool の2つです。prompt と agent の種類は読み込まれても実行されません。

時間の上限(timeout)は秒で指定します。既定はほとんどのイベントで600秒です。SessionEnd と Interrupt だけは既定が1秒で、最大3秒までしか延ばせません。終わり際の記録は短い処理にしておく必要があります。

コマンドを止める・書き換える

hooks のスクリプトは、標準入力で1つの JSON を受け取ります。session_id・cwd・hook_event_name・model などの共通の項目に加えて、イベントによって tool_name・tool_input・prompt などが入ります。スクリプトは結果を JSON で標準出力に返します。

よく使う返し方は次のとおりです。

やりたいこと イベント 返し方
ツールの実行を断る PreToolUse permissionDecision を deny にし、permissionDecisionReason に理由を書く
コマンドを書き換えて実行させる PreToolUse permissionDecision を allow にし、updatedInput に書き換えた内容を入れる
承認の場面で許可・拒否する PermissionRequest decision の behavior を allow か deny にする。複数の hooks のうち1つでも拒否すれば拒否
プロンプトを送らせない UserPromptSubmit decision を block にし、reason に理由を書く
終わったあとに作業を続けさせる Stop decision を block にすると、reason を次の指示として作業が続く

終了コードで止める方法もあります。終了コード0で何も出力しなければ成功、終了コード2なら止められるイベントでは処理を止め、理由は標準エラーに書きます。

注意したいのは PostToolUse です。ここで止めても、実行済みのコマンドが取り消されるわけではありません。ツールの結果が hooks の返したメッセージに置き換わるだけです。止めたい操作は PreToolUse で止めてください。

信頼の確認: 書き換えたら確認し直す

会社の管理下にない hooks は、動く前に利用者が中身を確認して信頼する必要があります。公式ドキュメントでは、Codex は hooks の その時点のハッシュ に対して信頼を記録すると説明されています。そのため、新しく足した hooks や書き換えた hooks は、信頼し直すまで飛ばされます。プラグインのスクリプトが変わったときも確認し直しです。

確認と信頼の操作は次の画面で行います。

  1. CLI: /hooks を開き、hooks を確認・信頼・無効化する
  2. デスクトップアプリ: 入力欄の Review hooks か、Settings > Hooks を開く

チームで使う hooks をリポジトリに置く場合は、「hooks を書き換えたら全員が確認し直す」ことを周知しておくと、「自分の PC だけテストが走らない」という問い合わせを減らせます。

なお、外部で hooks を確かめたうえで1回だけ自動で動かしたいときのために --dangerously-bypass-hook-trust という指定もあります。名前のとおり危険をともなう指定なので、社員の普段の作業では使わないよう決めておくのが安全です。

管理者が全員に配る hooks

社内のすべての PC で必ず動かしたい hooks は、組織の管理設定 requirements.toml で指定します。公式ドキュメントの例は次の形です。

allow_managed_hooks_only = true

[features]
hooks = true

[hooks]
managed_dir = "/enterprise/hooks"
windows_managed_dir = 'C:\enterprise\hooks'

それぞれの意味は次のとおりです。

設定 意味
managed_dir・windows_managed_dir 管理者の hooks を置くフォルダ(前者は Mac と Linux・後者は Windows)。ここの hooks は方針によって信頼済みとして扱われ、利用者は無効にできない
allow_managed_hooks_only = true 利用者・プロジェクト・セッション・プラグインの hooks を無視し、管理者の hooks だけを読み込む
[features] の hooks = true hooks を有効に固定し、利用者が手元で無効にできないようにする

ここで見落としやすいのが配布の役割分担です。公式ドキュメントでは、Codex は managed_dir のスクリプトを配らないと明記されています。スクリプトを各 PC に置いて更新するのは、MDM などの会社の配布の仕組みの役目です。requirements.toml だけ配ってフォルダが空のままにならないよう、配布の手順を情シスと決めておいてください。requirements.toml で設定を固定する考え方はセキュリティとガバナンスの記事で解説しています。

allow_managed_hooks_only をいきなり全員にかけると、現場がリポジトリに置いていたテスト用の hooks もすべて止まります。まずは管理者の hooks だけを配り、現場の hooks と並べて動かす期間を設けてから判断するのがおすすめです。

hooks だけに頼れない理由

hooks は便利ですが、公式ドキュメントはツールの hooks を「役に立つガードレールだが、完全な強制の境界ではない」と位置づけています。理由として次の点が挙げられています。

  • Web 検索のような OpenAI 側で動くツールは、PreToolUse と PostToolUse の対象にならない
  • 実行中のコマンドへの入力(write_stdin)では、PreToolUse が改めて動かない
  • 一部の特殊なツールの経路は、hooks を通らないことがある
  • SessionEnd は参考(advisory)の扱いとされ、MCP のツールを呼ぶ hooks にも対応していない

つまり「hooks で止めているから大丈夫」とは言えません。ファイルの読み書きの範囲やネットワークの許可はサンドボックスの設定で、自動で進めてよい操作の範囲は承認の設定で決め、hooks はその上に重ねる追加の見張りとして使います。土台の設定の考え方はサンドボックスと承認ポリシーの記事に、鍵や .env を読ませない設定は鍵と環境変数の記事にまとめています。

導入の進め方

社内に hooks を入れるときは、次の順番で進めると手戻りが少なくなります。

  1. 止めたいことを書き出す: 「本番環境への接続」「強制 push」「鍵の貼り付け」など、社内で止めたい操作を情シスと開発の責任者で一覧にする
  2. 土台の設定で守れるものを先に外す: サンドボックスと承認の設定で止められるものはそちらに任せ、hooks で見る対象を絞る
  3. 試験用のリポジトリで書く: <repo>/.codex/hooks.json に hooks を書き、/hooks で信頼してから動きを確かめる。断る場合の理由の文面も、社員が読んで分かる言葉にする
  4. 数人のチームで1〜2週間使う: 止めすぎていないか、時間の上限に引っかかっていないかを記録する
  5. 全員にかけるものだけ管理者の hooks に移す: requirements.toml の managed_dir で配り、スクリプトの配布と更新の手順も決める
  6. 変更の手順を決める: hooks を書き換えるたびに信頼し直しになることを周知し、変更の連絡先を決めておく

hooks の出力は Codex のモデルにも渡ります。公式ドキュメントでは、複数の hooks の内容は積み重なるため短く保つよう勧められています。1つの hooks が返すメッセージの既定の上限はおよそ2,500トークンで、超えた分は一時フォルダのファイルに保存されます。理由の文面は短く具体的にしておきましょう。

リポジトリごとの作業の決まりを Codex に伝える方法としては、hooks のほかに AGENTS.md もあります。「こう進めてほしい」という指示は AGENTS.md に、「これだけは機械的に止めたい」というルールは hooks に、と役割を分けると整理しやすくなります。書き方はAGENTS.md の書き方の記事をご覧ください。

まとめ

Codex の hooks を使うと、コマンドの実行前やプロンプトの送信前などに社内のスクリプトを自動で動かし、危ない操作を止めたり、作業の終わりに検査を走らせたりできます。個人とリポジトリの hooks は利用者が確認して信頼してから動き、書き換えると信頼し直しになります。全員に必ずかけたいルールは requirements.toml の managed_dir で配り、スクリプトの配布は会社の仕組みで行います。そして hooks は完全な強制の境界ではないため、サンドボックスと承認の設定を土台にして、その上に重ねて使います。

この記事の内容は、2026年11月10日時点の OpenAI 公式ドキュメントの記載に基づいています。イベントの名前や設定の項目は変わることがあるため、使う前に最新の記載をご確認ください。デジライズでは、止めたい操作の洗い出しから、サンドボックス・承認・hooks を組み合わせた設定の設計、配布の手順づくりまでを情報システム部門と一緒に進める Codex の法人導入支援のご相談を承っています。「まず1つのチームで試したい」という段階からでもお問い合わせください。