CodexのHooks(フック)機能とは？設定方法と活用例を解説

Codexを使い始めてから「Hooks機能」という言葉を見聞きする機会が増え、どんなものか気になっている人は多いですよね。

どんなことに使えるかなど、機能の詳細を把握したうえで、使うべきかを決めたい人もいるはず。

そこでこの記事では活用例も交え、Codex・Hooks機能の特徴を解説します。使うべきかの判断基準や使い方なども紹介するので、ぜひ参考にしてください。

Codexの特徴を詳しく知りたい人は、次の記事を参考にしてください。

CodexのHooks機能とは？

Codex Hooksは、Codexの処理フローに自分のスクリプトを組み込める機能です。特定のイベントが発生したタイミングでコマンドを自動実行できるため、繰り返し行う処理を効率化できます。

たとえば、タスクの完了後にテストやコードチェックを実行したり、処理が終わったことを通知したりといった使い方ができます。手動で行っていた操作を自動化できるため、開発作業の効率に役立ちます。

Hooksの設定はJSON形式の設定ファイルに記述します。基本的な設定であれば、JSONの書き方と実行したいコマンドが分かれば利用できます。

ここからはHooksのイベントの仕組みとMCP・スキルとの違いを、2つにまとめて解説します。

Hooksにおけるイベントとは？

Hooksにおけるイベントとは、設定したスクリプトを実行するトリガー（きっかけ）のことです。Codexの処理フローの中で、どのタイミングでスクリプトを実行するかを指定します。

Hooksを設定する際は、イベントの種類や実行するコマンドなどを指定します。たとえば、タスクの完了時に処理を実行するよう設定すれば、作業終了後に通知や検証処理などを自動化できます。

現在主に利用できるイベントは次のとおりです。

hooks.jsonの「event」フィールドにイベント名を指定すると、そのタイミングでコマンドが走ります。たとえば「Stop」を指定すれば、タスク完了時に通知スクリプトが動く流れです。

なお、利用できるイベントや設定項目はCodexのバージョンによって異なる場合があります。実際に設定する際は、使用しているCodexのバージョンに対応した公式ドキュメントも確認しましょう。

イベントの仕組みを正しく理解しておくと、目的に合ったフックを設計できます。

MCP・スキルとの違い

Hooksは「特定のイベントをきっかけに処理を自動実行する仕組み」であり、MCP（Model Context Protocol）やSkillsとは役割が異なります。

MCP（Model Context Protocol）は、外部ツールやサービスとAIを接続するための仕組みです。たとえば、外部サービスから情報を取得したり、対応するツールを呼び出したりするときに利用します。

一方、Skillsは特定の作業を実行するための手順や知識をCodexに与える仕組みです。複数の手順が必要な作業を再利用しやすくする目的で利用できます。

Hooksは、これらとは異なり、特定のイベントをトリガーとして処理を自動実行する点が特徴です。

具体的な違いを次の表にまとめます。

項目	Hooks	MCP	Skills
目的	イベントに応じた処理の自動化	外部ツール・サービスとの連携	特定の作業手順・知識の再利用
設定方法	hooks.json	MCP設定ファイル	プロンプトやCLAUDE.md
実行タイミング	設定したイベント	Codexからのツール呼び出し	ユーザー指示時など
主な用途	通知・検証・後処理など	API・外部サービス連携など	コード生成・修正など

「特定のタイミングで決まった処理を自動実行したい」場合はHooks、「外部のツールやサービスをCodexから利用したい」場合はMCP、「決まった手順の作業をCodexに実行させたい」場合はSkills、と考えると違いを理解しやすいでしょう。

CodexのMCPについて詳しく知りたい人は、次の記事を参考にしてください。

Codex・Hooks機能の活用例

Hooksは設定次第でさまざまな場面に応用できます。実務で役立つ代表的な活用例は次の5つです。

活用例	イベント	実行する処理	メリット
タスク完了時に通知	Stop	Slackなどへの通知処理を実行	作業完了をすぐに把握できる
生成コードを自動チェック	Stop	ESLintやFlake8などを実行	コード品質を自動で確認できる
作業開始前に環境を確認	Start	依存パッケージやDockerなどの状態を確認	環境の問題を早期に発見できる
Subagentの実行状況を記録	Subagent	起動情報などをログファイルに記録	デバッグや処理状況の確認に役立つ
生成ファイルをバックアップ	Stop	ファイルのコピーなどを実行	変更内容を自動で保存できる

Hooksを活用すれば、Codexの作業に合わせて「確認・通知・記録」といった定型処理を自動化できます。

CodexのHooks機能は使うべき？

Codexを日常的に使う人にはHooks機能の導入をおすすめします。繰り返しの手作業を減らし、作業ミスを防げるからです。

たとえば、タスクを実行するたびに手動でリンターを実行している場合、1回あたり30秒〜1分程度かかるとすると、1日10回で5〜10分の作業時間になります。Hooksで自動化すれば、こうした作業を手動で行う必要がなくなります。

ただし、Hooksはシェルコマンドを実行するため、設定内容には注意が必要です。とくにファイルの削除や変更、外部通信などを行うコマンドを設定すると、意図しない処理が実行される可能性があります。

一方で、hooks.jsonには信頼できるコマンドだけを記述し、外部から取得したスクリプトを無検証で設定しないルールを守りましょう。

Codexのコマンドを詳しく知りたい人は、次の記事を参考にしてください。

Codex・Hooksの使い方

ここからはHooks機能の使い方を、6つにまとめて解説します。

初めてHooksを設定する人は、上から順番に進めてください。

Codexの使い方を詳しく知りたい人は、次の記事を参考にしてください。

設定ファイルを作る手順

Hooksは、Codexの設定ファイルに定義します。ユーザー単位で設定する場合は~/.codex/config.toml、プロジェクト単位で設定する場合はプロジェクトの.codex/配下に設定を置きます。

たとえば、ユーザー単位で設定する場合は、ターミナルから次のように設定ファイルを確認できます。

```
cd ~/.codex
ls
```

.codexディレクトリが存在しない場合は、次のコマンドで作成できます。

```
mkdir -p ~/.codex
```

現在のCodexでは、Hooksの設定をconfig.tomlに記述できます。また、過去のバージョンではhooks.jsonを使う設定方法も存在するため、古い記事や設定例と現在の設定方法が異なる場合があります。

Codexのおすすめ設定を詳しく知りたい人は、次の記事を参考にしてください。

Hooksに設定を書く手順

Hooksは、イベントごとに実行するコマンドを設定します。たとえば、タスク終了時にスクリプトを実行する場合は、config.tomlに次のような設定を記述します。

```TOML
[features]
hooks = true

[[hooks.Stop]]
[[hooks.Stop.hooks]]
type = "command"
command = "echo 'タスクが完了しました'"
timeout = 5
```

[[hooks.Stop]]はStopイベントに対する設定、type = “command”はコマンドを実行するHooksであることを表します。commandには実際に実行するコマンドを指定し、timeoutでは処理のタイムアウト時間を設定できます。

Hooksの設定は、使用しているCodexのバージョンによって仕様が変更される可能性があります。設定時は、現在の公式ドキュメントや設定リファレンスも確認してください。

‘/hooks’でHooksを許可する手順

Hooksには、意図しないコマンドが自動実行されるのを防ぐための信頼（trust）の仕組みがあります。

設定したHooksを実行するときは、Codexの画面でHooksの状態を確認し、信頼できる設定だけを有効にしましょう。特に、GitHubなどから取得したプロジェクトにHooksが含まれている場合は注意が必要です。

Hooksは通常のコマンド実行よりも自動化の度合いが高いため、設定内容を確認せずにすべてのHooksを許可するのは避けましょう。

なお、以前のCodexでは/hooksコマンドを使ってHooksを管理する方法が案内されていましたが、現在の実装ではHooksの設定や信頼状態の管理方法が変更されています。利用中のCodexのバージョンに合わせて操作してください。

Stopフックで通知する手順

Stopフックを使えば、タスク完了時に通知を自動送信できます。Slack通知を例に設定方法を説明します。

たとえば、SlackのWebhookへ通知するスクリプトを用意し、そのスクリプトをStopフックから呼び出す方法があります。

```TOML
[features]
hooks = true

[[hooks.Stop]]
[[hooks.Stop.hooks]]
type = "command"
command = "python3 ./scripts/notify_slack.py"
timeout = 10
```

通知処理をスクリプトとして分離しておけば、Hooksの設定ファイルにWebhook URLなどの秘密情報を直接記述せずに済みます。

Webhook URLやAPIキーなどの認証情報は、環境変数や安全なシークレット管理の仕組みで扱い、Gitリポジトリに直接コミットしないようにしましょう。

複数のHooksを同時に動かす手順

Hooksでは、同じイベントに対して複数の処理を設定できます。

たとえば、タスク終了時にログを記録したあと、通知処理を実行する場合は、それぞれのコマンドをHooksとして登録します。

```TOML
[[hooks.Stop]]
[[hooks.Stop.hooks]]
type = "command"
command = "python3 ./scripts/write_log.py"
timeout = 5

[[hooks.Stop]]
[[hooks.Stop.hooks]]
type = "command"
command = "python3 ./scripts/notify_slack.py"
timeout = 10
```

フックの数が増えると管理が煩雑になるため、注意が必要です。それぞれの役割が分かるようにスクリプト名を付けておくと管理しやすくなります。

また、Hooksからファイルの削除やGitへのコミットなど、変更を伴う処理を自動実行する場合は注意してください。まずはログ出力やコードチェックなど、影響範囲の小さい処理から試すことをおすすめします。

リポジトリ単位で共有する方法

チームでHooksを統一する場合は、プロジェクト単位の.codex/設定として管理します。

リポジトリにHooksの設定を含める場合は、次の点に注意しましょう。

Hooksはリポジトリを含めてチームで共有できる一方、設定ファイルそのものが実行可能な処理を定義するものでもあります。実行されるコマンドを確認してから信頼・有効化することが重要です。

Codex・Hooksが動かない時の対処法

Hooksが期待どおりに動かない場合、原因の多くはファイル配置・JSON構文・許可設定のいずれかです。よくある原因と対処法を次にまとめます。

原因	対処法
設定ファイルの配置場所が間違っている	config.tomlなど、使用しているCodexのバージョンに対応した設定ファイルが正しい場所にあるか確認する
設定ファイルの記述ミス	TOMLの構文やHooksの設定項目・イベント名に誤りがないか確認する
Hooksが有効になっていない	Hooksの機能設定や信頼状態を確認し、対象のHooksが有効になっているか確認する
コマンドのパスが間違っている	スクリプトや実行ファイルのパスを確認し、必要に応じて絶対パスを使用する
コマンド自体に問題がある	Hooksから実行するコマンドをターミナルで単体実行し、正常に動作するか確認する
実行時間が長すぎる	timeoutの設定を確認し、必要に応じて十分な実行時間を確保する

まずは使用しているCodexのバージョンと公式ドキュメントを確認したうえで、設定ファイル・Hooksの有効化・実行コマンドの順番に確認すると、原因を切り分けやすくなります。

まとめ

本記事では、Codex Hooksの仕組みと設定方法を解説しました。

Codex Hooksは、特定のイベントをきっかけにコマンドやスクリプトを自動実行できる機能です。タスク完了時の通知やコードチェックなど、これまで手動で行っていた定型作業を自動化できるため、Codexを日常的に利用する方ほどメリットを得やすいでしょう。

まずはシンプルなStopフックを作成し、通知の自動送信など身近な自動化から試してみましょう。慣れてきたら、リンターの自動実行やパターン指定を組み合わせることで、より複雑な処理の自動化にも挑戦できます。