Codexのhooksの使い方!コマンドの記録と実行前に止める設定の手順

Codexに作業を任せていると、どのコマンドを実行したのかを後から確かめたい場面や、ファイルを消すコマンドだけは止めたい場面が出てきます。承認の画面で毎回見張るのは手間がかかり、見落としも出るでしょう。
Codexには、作業の決まった場面で自分の用意したスクリプトを自動で動かす「hooks(フック)」の機能があります。実行したコマンドをファイルに書き残す、指定したコマンドを実行の前に止める、といった決まりを、練習用のフォルダで安全に試せる作りです。
この記事では、Codexのhooksの作り方と信頼の手順から、コマンドの記録、実行前に止める設定、オフにする方法までを実画面で解説します。
この記事を読めば、Codexの操作に自分の決まりを足して、動きを確かめられるようになります。hooksは、中身を確かめて信頼するまで動かない仕組みで、事故を完全に防ぐ仕組みでもありません。まずは練習用のフォルダで試してください。
目次
- Codexのhooksを使う前に準備すること
- Codexのhooksの設定ファイルとスクリプトを作る手順
- Codexでhooksを信頼して動かす手順
- Codexが実行したコマンドを記録する手順
- 指定したコマンドを実行の前に止める手順
- 決めた文字を含む依頼を送る前に止める手順
- Codexのhooksをオフにする・外す手順
- Codexのhooksを書き換えたときと動かないときの注意点
- Codexのhooksに関するよくある質問
- まとめ
- 参考リンク
Codexのhooksを使う前に準備すること
Codexのhooksは、設定ファイルとスクリプトを置いたフォルダで動きます。試す前に準備することは、以下の3つです。
- hooksでできることと限界を知っておく
- python3とCodexの版を確かめる
- 練習用のフォルダを作る
hooksでできることと限界を知っておく
hooksは、Codexの作業の決まった場面で、自分で用意したコマンドを自動で実行する仕組みです。この記事で使う3つの場面は、以下の表のとおりです。
| 場面の名前 | 動くとき | この記事での使い方 |
|---|---|---|
| PostToolUse | Codexがコマンドなどを実行した後 | 実行したコマンドをファイルに記録する |
| PreToolUse | Codexがコマンドなどを実行する前 | rmを含むコマンドを止める |
| UserPromptSubmit | 依頼を送るとき | APIキーの形の文字が入った依頼を止める |
ほかにも、Codexの起動のとき(SessionStart)や、作業が止まるとき(Stop)などの場面があります。
hooksは便利な安全の柵ですが、すべての操作を必ず止める仕組みではありません。Codexがコマンドを使わずにファイルを編集する道具など、一部の経路は「Bash」を対象にしたhooksを通らない作りです。Codex公式ドキュメント「Hooks」も、hooksを完全な強制の境界としては扱っていません。
Codexには、操作できる範囲を決めるサンドボックスと、実行の前に確認する承認の仕組みもあります。hooksは、2つの仕組みに足して使う3つ目の決まりと考えてください。
Codexのサンドボックスを徹底解説!自動承認を安全に使う設定も紹介
python3とCodexの版を確かめる
この記事のスクリプトは、Pythonで書きます。ターミナルを開き、以下の2つのコマンドを1行ずつ入力して、Enterキーを押してください。
python3 --version
codex --version
以下の画像は、編集部のMac miniで2つのコマンドを入力した画面です。
「Python 3.」で始まる版と「codex-cli」の版が表示されれば準備はできています。python3を初めて入力したMacでは、Appleのコマンドラインツールのインストールを求める画面が出る場合があります。案内に沿ってインストールしてから、もう一度入力してください。
Codexが入っていない場合のインストールの手順は、Codexの記事で解説しています。
Codexの使い方を解説!CLIの導入から日本語での依頼・変更確認まで
練習用のフォルダを作る
hooksは、フォルダの中の「.codex」という名前のフォルダに置きます。練習用のフォルダと、消す練習に使う下書きのファイルを作ります。ターミナルに以下のコマンドを1行ずつ入力してください。
mkdir -p ~/touchai-demo/codex-hooks-demo/古い下書き
cd ~/touchai-demo/codex-hooks-demo
git init
echo "練習用の古い下書きです" > 古い下書き/下書き1.txt
echo "練習用の古い下書きです" > 古い下書き/下書き2.txt
ls -R
1行目でフォルダを作り、2行目で練習用のフォルダに移ります。3行目の「git init」は、スクリプトの場所をフォルダの一番上から探すために使います。
以下の画像は、6つのコマンドを入力した画面です。画像の黒い部分は、編集部の環境の情報(ユーザー名の入ったフォルダの場所)を隠しました。
「git init」の後の黄色い「hint」の文は、Gitの最初のブランチの名前についての案内です。練習では読み飛ばしてかまいません。最後の「ls -R」で、古い下書きのフォルダに2つのファイルが表示されれば完了です。
Codexのhooksの設定ファイルとスクリプトを作る手順
hooksは、設定ファイル「.codex/hooks.json」と、動かすスクリプトの組み合わせで作ります。設定ファイルとスクリプトを作る手順は、以下の3つです。
- 作る4つのファイルの中身を用意する
- Codexを起動して4つのファイルを作ってもらう
- 作ったファイルの中身を確かめる
作る4つのファイルの中身を用意する
この記事では、設定ファイル1つとPythonのスクリプト3つを作ります。4つのファイルの役割は、以下のとおりです。
- .codex/hooks.json: どの場面でどのスクリプトを動かすかを書く設定ファイル
- .codex/hooks/log_command.py: 実行したコマンドを「コマンドの記録.txt」に書き足すスクリプト
- .codex/hooks/block_rm.py: rmを含むコマンドを止めるスクリプト
- .codex/hooks/check_prompt.py: APIキーの形の文字が入った依頼を止めるスクリプト
1つ目の「.codex/hooks.json」の中身は、以下のとおりです。行の頭の空白は省いて書いていますが、そのままでも動きます。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/log_command.py\""
}
]
}
],
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/block_rm.py\"",
"statusMessage": "削除のコマンドか確かめています"
}
]
}
],
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/check_prompt.py\""
}
]
}
]
}
}
「matcher」の「Bash」は、Codexがコマンドを実行するときだけhooksを動かす指定です。「command」には、動かすスクリプトを書きます。「$(git rev-parse --show-toplevel)」は、フォルダの一番上の場所に置き換わる書き方です。
2つ目の「.codex/hooks/log_command.py」の中身は、以下のとおりです。実行したコマンドを、日時と一緒に「コマンドの記録.txt」へ1行ずつ書き足します。
import json, os, sys
from datetime import datetime
data = json.load(sys.stdin)
command = str(data.get("tool_input", {}).get("command", ""))
line = datetime.now().strftime("%Y-%m-%d %H:%M:%S") + "\t" + command + "\n"
open(os.path.join(data.get("cwd", "."), "コマンドの記録.txt"), "a", encoding="utf-8").write(line)
3つ目の「.codex/hooks/block_rm.py」の中身は、以下のとおりです。コマンドに「rm」が入っていたら、理由を表示して終了コード2で止めます。
import json, re, sys
command = str(json.load(sys.stdin).get("tool_input", {}).get("command", ""))
message = "このフォルダでは rm でファイルを消すコマンドを止めています。消すファイルは人が確かめてから消してください。"
if re.search(r"(^|[\s;&|(])rm\s", command): print(message, file=sys.stderr); sys.exit(2)
4つ目の「.codex/hooks/check_prompt.py」の中身は、以下のとおりです。依頼の文に「sk-」と、その後ろに英数字・「-」・「_」が16文字以上続く文字が入っていたら、依頼を止めます。
import json, re, sys
prompt = json.load(sys.stdin).get("prompt", "")
reason = "依頼にAPIキーの形の文字が入っています。消してから送り直してください。"
if re.search(r"sk-[A-Za-z0-9_-]{16,}", prompt): print(json.dumps({"decision": "block", "reason": reason}, ensure_ascii=False))
3つのスクリプトは、Codexから作業の内容をJSONの形で受け取って動きます。スクリプトの中身は、自分で読んで何をするのかを確かめてから使ってください。
Codexを起動して4つのファイルを作ってもらう
4つのファイルは、テキストエディタで作ってもかまいません。この記事では、Codexに中身を渡して作ってもらいます。練習用のフォルダで「codex」と入力し、Enterキーを押してください。
新しいフォルダで初めてCodexを起動すると、フォルダを信頼するかを確かめる画面が出ます。以下の画像は、編集部の環境で表示された画面です。
画面には「フォルダの設定は、AIへの依頼がなくても自動でコードを動かせる」とあります。自分で作ったフォルダなので「1. Trust and continue」を選び、Enterキーを押します。フォルダの中のhooksの設定(.codex/hooks.json)を読み込むのは、信頼したフォルダだけです。
Codexの新しい版がある場合は、起動のときに更新の案内が出ます。以下の画像は、編集部の環境で表示された更新の案内です。
更新するなら「1. Update now」、今は更新しないなら「2. Skip」を選びます。編集部は撮影のために「2. Skip」を選び、0.166.0のまま進めました。
以下の画像は、Codexが起動して依頼を入力できるようになった画面です。
画面の下の「GPT-6-Luna」は、編集部が撮影で使ったモデルの名前です。右下の「1 warning」は、編集部のMacにある別の設定についての警告で、hooksの手順とは関係ありません。
入力欄に、以下の依頼の文を入力します。依頼の文の後に、前の手順の4つのファイルの名前と中身を、番号を付けてそのまま続けます。
「次の4つのファイルを、このフォルダの中に作ってください。中身は書いてあるとおりにして、変えないでください。」
以下の画像は、依頼の文と4つのファイルの中身を入力欄に貼り付けた画面です。
長い文を貼り付けると、入力欄には文字数だけが表示されます。Enterキーを押すと依頼が送られます。
「.codex」のフォルダは、Codexが確認なしでは書き込めない場所です。書き込みの許可を求める画面が出たら、中身を確かめて「1. Yes, proceed」を選びます。以下の画像は、書き込みの許可を求める画面です。
編集部の環境では、Codexが作った「hooks.json」の引用符が崩れた状態でした。Codexは作った後にJSONとして読めるかを確かめ、直すための許可をもう一度求めてきました。
以下の画像は、直す許可を求める画面です。
直す許可を出すと、Codexから4つのファイルを作り終えた報告が届きます。ファイルを作る場面の画面は編集部が後から撮り直したため、画面の時刻が後の手順の画面より遅くなっています。
作り終えた後の画面は、以下の画像のとおりです。
作ったファイルの中身を確かめる
Codexに作ってもらったファイルは、自分の目で中身を確かめます。入力欄に「/quit」と入力してEnterキーを押し、Codexを終えてからターミナルに以下の2つのコマンドを入力します。
ls -a .codex .codex/hooks
cat .codex/hooks/block_rm.py
以下の画像は、2つのコマンドを入力した画面です。
ほかのファイルも「cat」の後にファイルの名前を入れて表示し、前の手順の中身と同じかを見比べてください。中身が違っていたら、Codexに直してもらうか、テキストエディタで直します。
Codexでhooksを信頼して動かす手順
Codexのhooksは、2段階の信頼をしてから動きます。1段階目はフォルダの信頼で、前の手順の起動の画面で済ませました。2段階目は、hooksの中身を1つずつ確かめる信頼です。hooksを信頼する手順は、以下の3つです。
- 起動の画面でReview hooksを選ぶ
- hooksの中身を確かめてtキーで信頼する
- 3つのhooksが動く状態になったことを確かめる
起動の画面でReview hooksを選ぶ
練習用のフォルダで、もう一度「codex」と入力してCodexを起動してください。新しいhooksがあると、起動のときに以下の画像の画面が出ます。
画面の注意書きは「hooksは信頼した後、サンドボックスの外で動ける」という意味です。中身を確かめずにまとめて信頼する「2. Trust all and continue」は選ばず「1. Review hooks」を選んでEnterキーを押します。
以下の画像は、hooksの一覧の画面です。場面ごとに、入っているhooksの数と、動く数、確かめが必要な数が並びます。
編集部のMacには、ほかのアプリが入れたhooksが元からあるため、Installedの数はその分だけ多い状態です。練習用のフォルダの3つは、Reviewの列の「1」で確かめられます。
hooksの中身を確かめてtキーで信頼する
一覧で「PreToolUse」を選んでEnterキーを押すと、PreToolUseのhooksが並びます。下矢印キーで「削除のコマンドか確かめています」の行を選ぶと、中身が表示されます。以下の画像は、行を選んだ画面です。
「Source」で設定ファイルの場所を「Command」で動かすコマンドを確かめてください。1行目の「Unnamed hook」は、編集部のMacに元からあるほかのアプリのhooksです。
中身に問題がなければ、tキーを押します。以下の画像のように、Trustの表示が「Trusted」になれば信頼は完了です。
Escキーで一覧に戻り「PostToolUse」と「UserPromptSubmit」も同じように中身を確かめてtキーで信頼します。
PostToolUseのhooksを選んだ画面は、以下の画像のとおりです。
Commandがlog_command.pyを動かすコマンドになっていることを確かめて、tキーを押します。
UserPromptSubmitのhooksを選んだ画面は、以下の画像のとおりです。
3つのhooksが動く状態になったことを確かめる
3つとも信頼すると、一覧の画面からReviewの列が消えます。以下の画像は、3つのhooksを信頼した後の一覧です。
InstalledとActiveの数が同じなら、入っているhooksはすべて動く状態です。Escキーを押して一覧を閉じます。信頼したことは、ホームフォルダの「.codex/config.toml」に記録され、次の起動からは確かめの画面が出ません。
Codexが実行したコマンドを記録する手順
PostToolUseのhooksは、Codexがコマンドを実行した後に動きます。実行したコマンドが記録されるかを確かめる手順は、以下の2つです。
- コマンドを使う作業を頼む
- 記録のファイルを開いて確かめる
コマンドを使う作業を頼む
Codexの入力欄に、以下の依頼を入力してEnterキーを押します。
「ls -la を実行して、このフォルダの中身を見せてください。ほかの作業はしないでください。」
以下の画像は、Codexが依頼のコマンドを実行した画面です。
画面には、hooksが動いたことは表示されません。記録はPostToolUseのhooksが裏で書き込みます。
記録のファイルを開いて確かめる
入力欄に「/quit」と入力してCodexを終え、ターミナルに以下のコマンドを入力します。
cat コマンドの記録.txt
以下の画像は、記録のファイルを表示した画面です。
日時と「ls -la」が1行で記録されていれば、PostToolUseのhooksは動いています。記録のファイルは、練習用のフォルダの一番上にできます。
PostToolUseは、コマンドを実行した後に動く仕組みです。実行したコマンドの結果を元に戻す働きはありません。記録には、コマンドに書かれたファイルの名前なども残るので、記録のファイルの扱いにも気を付けてください。
指定したコマンドを実行の前に止める手順
PreToolUseのhooksは、Codexがコマンドを実行する前に動き、内容によって実行を止められます。rmを含むコマンドが止まるかを確かめる手順は、以下の2つです。
- rmで消すように頼む
- Blocked by hookの表示を確かめる
rmで消すように頼む
練習用のフォルダで「codex」と入力してCodexを起動し、入力欄に以下の依頼を入力します。消す対象は、練習用に作った下書きのフォルダだけです。
「「古い下書き」のフォルダを、rm -rf 古い下書き のコマンドで消してください。」
以下の画像は、依頼を入力した画面です。
依頼の文にコマンドを書いたのは、Codexにコマンドで消してもらうためです。Codexがコマンドを使わずにファイルを編集する道具で消す場合「Bash」を対象にしたhooksでは止まりません。
matcherに「Edit|Write」と書けば、編集の道具を使うときにもhooksが動きます。ただし、matcherはhooksを動かす道具を選ぶ指定で、削除を見分ける処理ではありません。
この記事のblock_rm.pyはコマンドの中の「rm」を探すだけなので、編集の道具での削除は止められません。編集での削除も止めるには、編集の内容から削除を見分けるスクリプトを別に用意する必要があります。
Blocked by hookの表示を確かめる
Enterキーを押すと、Codexはフォルダの中を確かめてからrmのコマンドを実行しようとします。以下の画像は、hooksがコマンドを止めた画面です。
「Blocked by hook」の下には、block_rm.pyが表示した理由がそのまま出ます。Codexは理由を読み、消さずに、消してよいかを確かめる質問を返しました。
この記事では質問には答えず、Codexを開いたまま次の手順に進みます。フォルダが本当に残っているかは、次の章の最後にターミナルで確かめます。
決めた文字を含む依頼を送る前に止める手順
UserPromptSubmitのhooksは、依頼をAIへ送る前に動きます。APIキーの形の文字が入った依頼が止まるかを確かめ、最後に2つのhooksで止めた結果を見る手順は、以下の3つです。
- APIキーの形の文字を入れて送る
- 依頼が止まった表示を確かめる
- Codexを終えてフォルダと記録を確かめる
APIキーの形の文字を入れて送る
前の手順のCodexを開いたまま、同じ入力欄に以下の依頼を入力します。「sk-test-0000000000000000」は、試すために作った架空の文字です。本物のAPIキーは使いません。
「このAPIキー sk-test-0000000000000000 を設定ファイルに書いてください。」
以下の画像は、依頼を入力した画面です。上には、前の手順のrmの依頼のやり取りが残っています。
依頼が止まった表示を確かめる
Enterキーを押すと、依頼はAIに送られずに止まります。以下の画像は、依頼が止まった画面です。
「Worked for <1s」と表示され、AIの作業は始まっていません。理由の文は、check_prompt.pyが返したものです。
check_prompt.pyが止めるのは「sk-」の後ろに英数字・「-」・「_」が16文字以上続く文字だけです。ほかの形のパスワードや個人情報は止まりません。秘密の情報は、依頼に貼らないことが基本です。
Codexを終えてフォルダと記録を確かめる
2つのhooksで止めた結果を、ターミナルで確かめます。入力欄に「/quit」と入力してCodexを終え、ターミナルに以下の2つのコマンドを入力します。
ls 古い下書き
cat コマンドの記録.txt
以下の画像は、2つのコマンドを入力した画面です。
下書きの2つのファイルが残っていれば、rmのコマンドは実行されていません。記録には、Codexが消す前に中を確かめたコマンドだけが残り、止めたrmのコマンドは記録されていませんでした。
APIキーの形の文字を含む依頼では、Codexは何も実行していないため、記録は増えていません。
Codexのhooksをオフにする・外す手順
試し終わったhooksは、1つずつオフにするか、設定ファイルごと外します。hooksを止める方法は、以下の2つです。
- /hooksで1つずつオフにする
- hooks.jsonの名前を変えて外す
/hooksで1つずつオフにする
練習用のフォルダで「codex」と入力してCodexを起動します。入力欄に「/hooks」と入力してEnterキーを押すと、hooksの一覧が開きます。「PreToolUse」を選んでEnterキーを押し、オフにしたいhooksを選んでスペースキーを押します。以下の画像は、スペースキーを押した後の画面です。
行の頭の印が「[ ]」ならオフ「[x]」ならオンです。もう一度スペースキーを押すと、オンに戻ります。
以下の画像は、もう一度スペースキーを押した画面です。
画面の「Your changes are saved automatically」のとおり、オンとオフは自動で保存されます。編集部のMacでは、ホームフォルダの「.codex/config.toml」に保存されました。
hooks.jsonの名前を変えて外す
練習用のフォルダのhooksをすべて外すには、設定ファイルを消すか名前を変えます。Codexを終えてから、ターミナルに以下の2つのコマンドを入力します。
mv .codex/hooks.json .codex/hooks.json.off
ls .codex
以下の画像は、2つのコマンドを入力した画面です。
名前を変えた後にCodexを起動して「/hooks」を開くと、練習用のフォルダの3つのhooksが一覧から消えています。
以下の画像は、名前を変えた後のhooksの一覧です。
元に戻すときは、ファイルの名前を「hooks.json」に戻します。練習用のフォルダごと要らなくなった場合は、Finderで「touchai-demo」の中の「codex-hooks-demo」のフォルダをゴミ箱に入れてください。
Codexのhooksを書き換えたときと動かないときの注意点
hooksは、中身を書き換えたときと信頼していないときに、思ったとおりに動かない場合があります。編集部が実機で確かめた注意点は、以下の3つです。
- hooks.jsonを書き換えると確かめ直しになる
- スクリプトだけを書き換えても確かめ直しの画面は出ない
- 信頼しないで進めるとhooksは動かない
hooks.jsonを書き換えると確かめ直しになる
hooks.jsonの中身を書き換えると、次の起動で、もう一度確かめる画面が出ます。以下の画像は、statusMessageの文を1か所だけ書き換えて起動した画面です。
Codexは、信頼したときのhooksの定義を記録しています。定義が変わったhooksは、確かめて信頼し直すまで動きません。
スクリプトだけを書き換えても確かめ直しの画面は出ない
一方で、hooks.jsonはそのままで、block_rm.pyの中身だけを書き換えた場合は、確かめ直しの画面が出ませんでした。以下の画像は、スクリプトの最後に1行を足してから起動した画面です。
画面は、いつもの起動の画面と同じでした。編集部の環境では、スクリプトの中身が変わっても、Codexは知らせてくれませんでした。共有のフォルダでhooksを使う場合は、スクリプトを書き換えられる人を限り、変更の履歴をGitで確かめてください。
信頼しないで進めるとhooksは動かない
確かめの画面で「3. Continue without trusting (hooks won't run)」を選ぶと、新しいhooksや変わったhooksは動かないまま起動します。hooksが動かないときは「/hooks」の一覧でReviewの列に数が残っていないかを確かめてください。
編集部の環境では、Codexが作ったhooks.jsonの引用符が一度崩れました。Codexに作ってもらったファイルも、作った後に中身を自分の目で確かめてください。
Codexのhooksに関するよくある質問
Codexのhooksを試した後には、ほかの道具との違いや会社での使い方が気になります。Codexのhooksについてよくある質問は、以下の3つです。
- Claude Codeのhooksとは何が違いますか?
- 会社で全員に同じhooksを使わせられますか?
- hooksをまとめて使わないようにできますか?
Claude Codeのhooksとは何が違いますか?
Claude Codeにも、決まった場面でコマンドを動かすhooksがあります。Claude Codeは設定ファイル「settings.json」に書き、Codexは「hooks.json」か「config.toml」に書く点が違います。Codexは、新しいhooksや変わったhooksを、確かめて信頼するまで動かしません。
Claude Code Hooksとは?仕組みと設定・おすすめの3つを徹底解説
会社で全員に同じhooksを使わせられますか?
会社の管理者は、管理用の設定ファイル「requirements.toml」にhooksを書き、全員に使わせられます。管理者が配ったhooksは信頼済みとして扱われ、利用者は一覧からオフにできません。書き方は、Codex公式ドキュメント「Hooks」の管理者向けの説明で確かめてください。
hooksをまとめて使わないようにできますか?
hooksは、最初からオンになっています。すべてのhooksを使わない場合は「.codex/config.toml」に「[features]」の行と「hooks = false」の行を書きます。1つだけ止めたい場合は「/hooks」の一覧でオフにする方法が手軽です。
まとめ
Codexのhooksを使えば、コマンドの記録や、指定したコマンドを実行の前に止める決まりを、自分のスクリプトで足せます。Codexのhooksを使う手順の要点は、以下の5つです。
- 練習用のフォルダに「.codex/hooks.json」とスクリプトを置く
- フォルダを信頼し「Review hooks」で中身を確かめてtキーで信頼する
- PostToolUseで、実行したコマンドを記録する
- PreToolUseで、rmを含むコマンドを実行の前に止める
- 書き換えたら確かめ直し、要らなくなったら「/hooks」でオフにする
hooksは便利な安全の柵ですが、すべての操作を止める仕組みではありません。まずは練習用のフォルダで、コマンドの記録から試してみてください。



