Codex hooksの使い方と安全確認、Windows設定まで整理

Codex hooksとは何か

Codex hooksは、Codexの会話やツール呼び出しを取り巻くライフサイクルに、利用者が用意したコマンドを接続する仕組みです。通常の依頼はモデルが内容を理解して返答や変更を作りますが、フックは指定されたイベントをきっかけに決められた処理を呼び出します。入力を検査する、結果を記録する、次の判断に必要な短い情報を返す、といった役割を明確に分けられるのが特徴です。モデルの能力に期待する処理と、毎回同じ条件で確認したい処理を分けることで、結果の読み方も安定します。CodexをCLI、IDE拡張、アプリのどこから使う場合でも、設定された層に応じてフックが読み込まれます。

イベントごとに差し込む役割

公式ドキュメントには、会話の途中で使うPreToolUse、PermissionRequest、PostToolUse、PreCompact、PostCompact、UserPromptSubmit、SubagentStop、Stop、開始時に使うSessionStartとSubagentStart、メインスレッドの終了時に使うSessionEndが掲載されています。たとえばPreToolUseはツールを呼ぶ前の確認、PostToolUseは呼び出し後の結果整理、SessionStartは開始時の案内に向きます。すべてのイベントに同じ処理を置くのではなく、確認したい事実が生まれる直前か直後かで選ぶと、ログも追加情報も必要な量に抑えられます。

モデルへの依頼と分ける理由

「結果を短く要約して」と依頼するだけならモデルへの指示で十分ですが、特定のファイル変更があったら形式を調べる、ツールの入力を記録する、開始時に作業場所を知らせる、といった処理はフックに置くと条件をそろえやすくなります。反対に、仕様の解釈や修正方針の比較はモデルの判断が必要です。フックで判断まで代替しようとせず、事実の収集と通知を担当させると、Codexの返答に根拠を足しながら人の判断も残せます。OpenAIの公式発表でも、Hooksは検証、記録、メモリ作成、ディレクトリごとの調整に使える機能として案内されています。

2026年8月に確認したい公式の変更

Codex hooksを今確認する理由は、単に新しい設定項目が増えたからではありません。2026年5月14日のOpenAIの発表でHooksが一般提供として案内され、すべてのプランで利用できること、リポジトリやディレクトリに応じてCodexの扱いを変えられることが示されました。さらに公式ドキュメントは、定義ファイルの探索場所だけでなく、複数の設定層が同時に読み込まれること、変更されたフックを確認して信頼すること、Windows用のコマンドを分けて書けることまで具体化しています。過去の紹介記事だけで判断せず、利用時点の公式ページを基準にする必要があります。

5月14日の一般提供が示すこと

OpenAIの発表では、Hooksはプロンプトの検査、検証処理、会話の記録、メモリ作成、特定のリポジトリやディレクトリでの調整に使える機能として紹介されています。ここで重要なのは、フックが特別なモデルを選ぶ機能ではなく、Codexの動作の節目に外部コマンドを置く機能だという点です。利用可能になったことと、どのイベントをどの範囲で使うかが明確になったことを分けて考えると、導入後に「設定したのに何も変わらない」という混乱を減らせます。使えるプランの確認は発表のAvailability欄を読み、細かな仕様はドキュメントへ戻って確認します。

公式ドキュメントで8月に見る項目

8月11日に確認したいのは、Hooksの一覧、探索場所、承認の扱い、設定形式、イベントごとの入力と出力です。公式資料ではhooks.jsonまたはconfig.tomlを使い、ユーザー用の場所とプロジェクト用の場所を分けて記述できます。プロジェクト側のフックは、そのプロジェクトの設定層を信頼した後に読み込まれると説明されています。また、複数の定義が一致する場合はすべてが対象になり、後から置いた設定が前の設定を単純に置き換えるわけではありません。この点を先に理解しておくと、同じ処理が二度走る原因を追いやすくなります。

hooks.jsonとconfig.tomlの置き場所

Codexがフックを見つける場所は、利用者の設定とプロジェクトの設定を分けて考えると理解しやすくなります。公式ドキュメントに示されている代表的な候補は、ユーザー側の~/.codex/hooks.json、~/.codex/config.toml、リポジトリ側の.codex/hooks.json、.codex/config.tomlです。ユーザー側に置けば複数のプロジェクトで共通の確認を使いやすくなり、プロジェクト側に置けば、そのコードベースだけで必要な検査に絞れます。最初は一つの層だけに置き、どの定義が読み込まれたかを確認してから範囲を広げるのが安全です。

ユーザー単位とリポジトリ単位を分ける

すべてのプロジェクトで行いたい確認と、特定のリポジトリの事情に依存する確認は同じ場所へ置かない方が管理しやすくなります。たとえば入力に認証情報が含まれていないかを見る処理はユーザー側の共通設定に向き、特定の言語やディレクトリ構成を検査する処理はプロジェクト側に向きます。プロジェクトを別の人へ渡すときは、設定だけでなく呼び出すコマンドの中身と、どの情報を外へ出すかも確認します。設定の場所を明記しておけば、画面で動作を見たときに原因を探しやすくなります。

二つの書き方を混ぜない

hooks.jsonではJSONのhooksオブジェクトにイベントとハンドラーを記述し、config.tomlでは[[hooks.SessionStart]]のような配列テーブルで同じ構造を表します。公式資料では同じ設定層にhooks.jsonとconfig.tomlの両方がある場合、内容が統合されて起動時に注意が表示されると説明されています。試す段階では一つのファイル形式に統一し、設定を移行するときだけもう一方へ書き換える方が差分を読みやすくなります。下の例は、セッション終了時にWindowsとそれ以外で呼び出すコマンドを分け、処理時間を限定する最小構成です。

{
  "description": "作業終了時に確認を行う設定",
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 .codex/hooks/check.py",
            "commandWindows": "py -3 .codex/hooks/check.py",
            "timeout": 30,
            "statusMessage": "確認中"
          }
        ]
      }
    ]
  }
}

Windowsで設定するときの注意

Windowsでは、同じ処理でも実行ファイルの呼び出し方、パスの区切り、現在の作業場所が違うため、macOSやLinux向けの例をそのまま貼り付けないことが大切です。公式のHooks仕様にはWindows専用のcommandWindowsがあり、JSONではこの項目にWindows用のコマンドを指定できます。設定ファイルを置いた場所と、実際にCodexを開始した場所が別でも、コマンドが正しい作業ディレクトリを受け取れるかを確認してください。表示されたステータスだけで成功と決めず、標準入力、終了コード、出力ファイルを一つずつ見ます。

commandWindowsを使う

Windows専用の呼び出しを用意すると、PythonやNode.jsなどの実行方法を環境に合わせられます。たとえばpython3が見つからない端末ではpy -3を使う、スクリプトの場所を絶対パスで指定する、引数に空白がある場所を引用符で囲む、といった調整を行います。JSONのキーはcommandWindows、TOMLではcommand_windowsまたは公式資料に示される表記を使います。設定を配布する場合は、利用者ごとのインストール場所に依存しない呼び出し方を選び、最初に版番号と実行場所を表示させると切り分けが簡単です。

実行場所とパスを確認する

コマンドはセッションの現在の作業ディレクトリで動くため、相対パスがどこを指すかを確認します。Codexをリポジトリのサブディレクトリから開く場合、.codex/hooks/check.pyをそのまま指定すると期待した場所を指さないことがあります。公式資料が勧めるように、リポジトリのルートを基準にパスを解決する処理を用意すると、起動場所の違いによる失敗を減らせます。ドライブ文字、空白を含むフォルダー名、日本語のフォルダー名を小さな検証用ディレクトリで試し、表示された場所と実際の場所が一致するか確認してください。

長さと失敗時の扱いを決める

フックにはtimeoutを秒で指定できます。省略時は多くのイベントで600秒が使われ、SessionEndは既定値が1秒で最大3秒と説明されています。長い検査を一つのフックに詰め込むと、Codexの次の応答を待たせる原因になります。開始時は30秒程度の短い処理に絞り、時間を超えた場合に何を記録し、利用者へどの表示を出すかを決めます。フックが失敗したときに作業全体を止めるのか、注意だけを残して続けるのかはイベントによって意味が変わるため、実際の確認結果で判断します。

イベントの選び方と実務例

イベント選びは、処理の名前ではなく「いつ事実を確認したいか」から考えます。ツールを呼ぶ前の入力を見たいならPreToolUse、呼び出し後の結果を整理したいならPostToolUse、会話開始時に前提を渡したいならSessionStart、作業が止まった時点で検証したいならStopが候補です。PreCompactやPostCompactは長い会話の整理前後、PermissionRequestは承認が必要になる場面に対応します。公式仕様では、イベントごとにmatcherが使える範囲や出力の扱いが違うため、名前が似ているからと同じ処理を横展開しないでください。

PreToolUseで変更前を確認する

PreToolUseは、Bash、apply_patch、MCPツールなど、対応するツールの呼び出し前に処理できます。ツール名をmatcherで絞り、入力されたコマンドや変更対象を見て、追加情報を返したり、対応範囲では拒否や入力の書き換えを行ったりできます。ここで大事なのは、すべての変更を一律に拒否することではありません。読み取りと書き込みを分け、対象外のディレクトリや明らかに意図しない操作だけを人に知らせるようにすると、確認の負担を増やさずに境界を見やすくできます。拒否の理由は短く具体的にし、次に何を確認すべきかを表示してください。

PostToolUseで結果を見る

PostToolUseは、ツールが返した結果を受け取った後に記録や補足を行う場所です。変更内容、テスト結果、対象ファイルの一覧などを短くまとめてCodexへ渡すと、次の判断に必要な事実を会話へ戻せます。ただし、ツールがすでにファイルを書き換えた後では、PostToolUseで副作用を取り消せません。変更を防ぎたい条件はPreToolUseで確認し、変更後に検査したい条件はPostToolUseへ置くという分担が必要です。長い出力をそのまま返すと文脈を圧迫するため、要点と保存場所だけを返す設計にします。

SessionStartとStopで前後を整える

SessionStartは起動、再開、クリア、圧縮などの開始理由を見分けるために使えます。プロジェクトの説明や現在の確認事項を短く表示するなら、開始時の情報提供に向きます。Stopはメインの応答が終わる場面で、必要なファイルが存在するか、検証結果が残っているかを確かめる用途に使えます。SessionEndは終了処理の時間が短く制限されるため、大きな検査を置く場所としては慎重に考えます。開始と終了にそれぞれ長い処理を入れるのではなく、事前に必要な準備と、最後に確認すべき最小条件を分けてください。

Step 1から始める安全な試し方

Codex hooksの導入は、設定ファイルを書いた瞬間に完成するものではありません。まず処理が呼ばれたか、どの入力が届いたか、どの場所で動いたか、終了時に何を返したかを把握します。確認用の処理は読み取りだけにし、ファイルの変更や外部送信を行わない状態から始めると、設定の問題と処理内容の問題を分けられます。次の順番は、Windowsを含む複数の環境で同じ設定を試すときにも使いやすい流れです。

Step 1: 対象イベントを一つに絞る

最初はSessionStartかStopのどちらか一つだけを選びます。PreToolUseのように影響範囲が広いイベントから始めると、別のツールや設定と重なったときに原因が見えにくくなります。イベントを選んだら、起動時なのか再開時なのか、応答の終了時なのかを一文で記録します。目的が「呼ばれたことを確認する」なら、処理の中身を増やさず、時刻とイベント名だけを表示するところから始めます。

Step 2: 標準入力の形を保存して見る

公式仕様では、コマンドフックは標準入力から一つのJSONオブジェクトを受け取ります。session_id、cwd、hook_event_name、modelなどの共通項目に加え、イベント固有の情報が含まれます。最初の確認では、値をそのまま外へ送らず、ローカルの検証用場所へ必要な項目だけ保存します。transcript_pathは便利な参照先ですが、固定された連携形式とは限らないと公式に説明されているため、長期利用の根拠をそこだけに置かないようにします。

Step 3: 短い検証と表示だけ返す

入力の形が分かったら、次にファイルの存在確認や拡張子の確認など、結果が明確な処理を一つだけ加えます。モデルに追加情報を返す場合は、何が確認できたかを一文で示し、詳細なログはローカルに残します。公式仕様では追加コンテキストが大きいと一時ファイルへ保存され、短いプレビューがモデルへ渡されるため、最初から大量の内容を返す設計は避けます。確認が通ったかどうかを終了コードと表示の両方で見られるようにすると、画面とログのどちらかだけに依存せずに済みます。

Step 4: 承認と停止条件を確認する

管理対象ではないコマンドフックは、実行前に定義をレビューして信頼する必要があります。Codexは現在のフック定義のハッシュを記録し、内容が変わると再確認を求めます。/hooksで登録されたソースを確認し、どのコマンドがどのイベントで動くかを読んでから有効にします。検証中に意図しないコマンドが走った場合の停止方法、設定を元へ戻す方法、問題を伝える短い表示も先に決めます。承認を省くための強いオプションは、処理の内容と対象を別途確認できる環境に限って検討してください。

承認・権限・情報の扱い

HooksはCodexの操作に近い場所で動くため、便利さだけでなく、何を読み、何を記録し、どこへ渡すかを明確にする必要があります。プロジェクトに置かれた定義は、知らないコマンドを含んでいる可能性があります。公式資料では、管理されていないフックは定義をレビューして信頼するまで実行されず、システムや管理側から配られたフックは別の扱いになると説明されています。複数の設定層が同時に読み込まれる仕組みもあるため、個別のファイルだけを見て安全だと判断しないことが重要です。

新規または変更後のフックをレビューする

フックを追加したときだけでなく、コマンド、引数、マッチ条件、実行場所を変更したときも同じ確認を行います。/hooksを開いて登録元、イベント、matcher、呼び出す実行ファイル、タイムアウトを読み、必要な範囲だけを信頼します。プロジェクトを複製した場合は、見覚えのあるファイル名でも中身を確認します。定義の名前が「確認用」でも、実際のコマンドがファイルを変更したり外部へ送信したりする可能性があるため、名前と動作を別々に見ます。

APIキーなどの認証情報を処理から分離する

入力や会話の記録を扱うフックでは、APIキー、接続文字列、利用者の個人情報が標準入力やログへ混ざらない設計にします。全部の入力を保存するのではなく、イベント名、対象ファイル、検査結果など必要な項目だけを選びます。画面に見せる追加情報にも、認証情報や不要な会話本文を含めないことが大切です。外部の記録先へ渡す処理を作る場合は、送信先、保存期間、削除方法を先に決め、まずはローカルだけで動作を確かめてから範囲を広げます。

追加コンテキストを短く保つ

フックからCodexへ返す追加情報は、短い事実と参照先に絞ります。大きなログ、ファイル全体、会話の全文を毎回返すと、モデルが本来の依頼へ使える文脈を圧迫します。公式仕様にはadditionalContextLimitがあり、一定量を超えた出力を一時ファイルへ退避してプレビューを返す仕組みが説明されています。上限を大きくするより、検証側で出力を要約し、必要なら人が保存先を開く形にする方が、応答の安定と情報の扱いやすさを両立できます。

Codex hooksとSkills・プラグインの使い分け

Codexには、フックのほかにもAGENTS.md、Skills、MCP、プラグインなど、作業を調整する入口があります。役割を混ぜると、設定を読んだ人がどこを直せば結果が変わるのか分からなくなります。Hooksはイベントの前後で決めたコマンドを動かし、Skillsは再利用する指示や知識をまとめ、MCPは外部の情報や操作を接続し、プラグインは関連する機能のまとまりを届けるものです。最初に「固定の検証か、モデルに読ませる手順か、外部ツールへの接続か」を決めると、必要な仕組みを選びやすくなります。

ルールを守らせるならAGENTS.md

プロジェクトの命名規則、テストの実行方法、触れてはいけない範囲などをCodexに読ませたい場合は、AGENTS.mdのような指示ファイルが候補です。ここに書く内容はモデルが理解して判断するための前提であり、ファイル形式を検査する処理そのものではありません。ルールを読ませても守られたかを機械的に確かめられるわけではないため、必要な条件だけをPostToolUseやStopで確認する方法を組み合わせます。指示と検証を分けることで、説明責任のある結果を残せます。

手順を再利用するならSkills

調査、テスト作成、レビューなどの進め方を毎回同じ形で依頼したい場合はSkillsが向きます。Skillsは、モデルが読む手順や補助資料をまとめて呼び出しやすくする仕組みです。一方、ファイルに機密な文字列が含まれていないか、特定の拡張子が追加されていないかといった決められた検査はHooksの方が役割に合います。判断を伴う手順と、結果を確認する処理を別々に置くと、どちらかの変更で全体が分からなくなる事態を避けられます。

ツール接続が必要ならプラグイン

外部サービスや追加のアプリ、Skillsを一つのまとまりとして扱いたい場合はプラグインを検討します。プラグインにフックを含められる場合でも、インストールや有効化だけでコマンドが信頼されるわけではなく、公式ドキュメントでは同じレビュー手順を使うと説明されています。名前が似たプラグインが複数あるときは、含まれるコマンド、読み取り範囲、変更範囲、停止方法を確認してから使います。Hooksをプラグインの便利な付属品とだけ考えず、単独の設定層として動作を追うことが大切です。

導入前後に確認する項目

Codex hooksを使い始めるときは、設定が存在することよりも、予想したイベントで、予想した場所から、予想した範囲の処理が呼ばれることを確かめます。確認の順番を記録しておけば、CLIの版やWindowsの端末を変えたときに差を比較できます。以下の表は、最初の読み取り中心の検証と、通常の開発へ広げる前に見る項目をまとめたものです。すべてを一度に有効にせず、一行ずつ条件を増やす方が原因を追いやすくなります。

Step 5: 安定版と先行版を分けて比べる

Codex CLIやアプリの更新でフックの挙動が変わる可能性があるため、設定を調べるときは使っている版番号も残します。安定版で動いた定義を、先行版へ切り替えた直後に同じ条件で確認し、イベントの発生、入力の形、Windowsの呼び出し、表示の違いを記録します。版番号を残さないまま「昨日は動いた」と判断すると、設定の変更とクライアントの変更を区別できません。更新後に問題があれば、設定を増やす前に一つ前の版と最小構成で再現することが有効です。

Codex hooksを長く使うための考え方

Hooksは、Codexに複雑な判断を追加する道具ではなく、判断の前後に観測できる条件を置く道具として扱うと長持ちします。何を確認するのか、どのイベントで必要なのか、結果を誰が読むのか、失敗時に作業を止めるのかを決めてから設定を書きます。機能が増えるほどフック同士の重なり、出力の量、処理時間、設定層の優先関係が見えにくくなるため、少数の定義から始めて、役割が重なる処理を整理することが大切です。

まず「確認できる事実」を一つ置く

良い最初のフックは、呼ばれたかどうかと、どの作業場所で呼ばれたかが分かる程度の小さなものです。次に対象ファイルの存在、変更の有無、検査結果など一つの事実を加えます。処理が増えるたびに、イベント、入力、出力、待ち時間を記録します。もし結果が曖昧なら、モデルへ長い説明を返すのではなく、人が開ける保存場所と短い要約に分けます。小さな事実を積み重ねると、失敗時の切り分けも説明しやすくなります。

定義を読める状態で共有する

フックをチームや別の端末へ渡す場合は、設定ファイルだけでなく、使うコマンドの目的、入力の扱い、必要な実行環境、終了時の意味を短く添えます。動作が便利でも、読んだ人が信頼すべき対象を判断できなければ、設定の共有は負担になります。プロジェクト側に置く処理は対象リポジトリの中で完結させ、共通設定から呼ぶ処理は保存先と情報の範囲を明示します。誰がいつ変更したかを追える形にしておくと、定義のハッシュが変わったときの確認も早くなります。

公式資料を基準に更新する

Hooksはイベント、入力項目、Windows用キー、承認の仕組みが更新される可能性があります。記事や検索結果だけで設定を固定せず、利用時にはOpenAI公式ドキュメントのイベント表、設定例、入力と出力の説明を読み直してください。Codex全体の提供状況や利用できる入口はOpenAIの公式発表で確認できます。公式の説明と手元の版番号を並べて読む習慣があれば、以前の設定が今も有効か、仕様の変更で見直すべきかを判断しやすくなります。

まとめ

Codex hooksは、SessionStart、PreToolUse、PostToolUse、Stopなどの節目に定型のコマンドを置き、検証、記録、追加情報の提示を行うための仕組みです。2026年5月14日に一般提供が案内され、8月11日時点の公式ドキュメントではhooks.jsonとconfig.toml、ユーザー用とプロジェクト用の設定層、Windows専用のコマンド、定義をレビューして信頼する流れまで確認できます。まず一つのイベントで入力と実行場所を観測し、短い処理だけを加え、承認とタイムアウトを確かめてください。Hooksはモデルの判断を置き換えるものではなく、人が結果を読んで判断するための境界を見やすくする道具です。