結論先說
- 同一配置層裏支持兩種聲明格式(二選一,別混寫):獨立的
hooks.json文件,或者在config.toml裏寫內聯[hooks]表;如果在同一個目錄同時寫了這兩份,Codex 會把兩邊都加載並給出告警。 - 安全機制比普通腳本更嚴:非託管鉤子按哈希值做信任鎖定。不管是你自己的
~/.codex/hooks.json還是同事提交在倉庫.codex/hooks.json裏的鉤子,首次添加或每次改了配置內容後,都必須進命令行敲/hooks審閱確認信任後才會真正運行。 - 跨層級鉤子是「疊加並發執行」而不是覆蓋:系統層、用戶層和受信任項目層如果同時匹配了同一個事件,對應的多個命令鉤子會並發拉起。
- 項目級鉤子要求雙重前提:不僅鉤子哈希要通過審核,當前項目目錄的
.codex/層本身也必須處於已受信任(Trusted)狀態。

圖:本站根據 OpenAI Codex 官方文檔 Hooks 整理的示意圖
本文根據 OpenAI Codex 官方文檔《Hooks》與配置文件參考整理,核對日期 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 OpenAI 官方網站。
適用於誰
- 搜「codex hooks 怎麼配」「codex hooks.json 用法」的開發者與團隊技術負責人;
- 用習慣了 Claude Code 的鉤子機制(見 /guides/claude-code-hooks),切到或雙持 Codex 時也想實現「命令執行前攔截」「回合結束前自動跑格式化與測試」的人;
- 照着文檔建好了
.codex/hooks.json,但啟動會話後發現腳本根本沒跑、頂部還彈出一行審核提醒的同學。
如果你只是想在長任務跑完時彈一個系統桌面提醒或響一聲,直接用更輕量的 notify 配置就夠了(見 /guides/codex-notify-task-completion-alert);需要在智能體循環中間精細介入,才用本文講的 Hooks。
一、鉤子能掛在哪些時間點?官方事件分類表
按官方文檔,Codex 將整場會話拆成了五類精確的掛載時機,覆蓋從輸入提示詞到子代理結束的全鏈路:
- 單輪執行中途:
UserPromptSubmit(提交提示詞時,可用於掃描阻斷誤貼密鑰)、PreToolUse(調工具前校驗)、PermissionRequest(請求權限時)、PostToolUse(工具返回後)、PreCompact/PostCompact(上下文壓縮前後)、SubagentStop與Stop(當前輪準備停下時,最適合掛代碼規範與測試檢查); - 每次向模型發請求前後:
PreModelRequest、PostModelRequest; - 會話與子代理啟停:
SessionStart、SubagentStart、SessionEnd(注:SessionEnd和人工打斷時的Interrupt僅對主線程觸發,不對子代理觸發)。
二、配置文件放在哪,怎麼寫 hooks.json 與內聯 TOML
本地 Codex 按從高到低的系統治理範圍依次掃描四處位置:
- 系統託管層:macOS / Linux 為
/etc/codex/hooks.json,Windows 為%ProgramData%\OpenAI\Codex\hooks.json(由企業管理員下發,預設強制受信任且不可被個人關閉); - 個人用戶層:
~/.codex/hooks.json(Windows 為%USERPROFILE%\.codex\hooks.json); - 受信任項目層:倉庫內的
.codex/hooks.json; - 插件自帶層:已啟用插件目錄下的
hooks/hooks.json。
寫法 A:獨立 JSON 文件(.codex/hooks.json)
結構分「事件名 → matcher 正則匹配組 → hooks 處理器列表」三層:
json
{
"description": "團隊倉庫 Bash 命令策略檢查與收尾校驗",
"hooks": {
"PreToolUse": [
{
"matcher": "^Bash$",
"hooks": [
{
"type": "command",
"command": "python3 .codex/hooks/check_bash_policy.py",
"timeout": 30,
"statusMessage": "正在檢查終端命令合規性"
}
]
}
]
}
}
寫法 B:直接寫進 config.toml(適合個人輕量配置)
如果你本來就在維護 ~/.codex/config.toml(完整鍵說明見 /guides/codex-config-toml-complete-guide),不想多建一個文件,可以用等價的 TOML 數組表語法:
toml
[[hooks.PreToolUse]]
matcher = "^Bash$"
[[hooks.PreToolUse.hooks]]
type = "command"
command = "python3 ~/.codex/hooks/check_bash_policy.py"
timeout = 30
statusMessage = "Checking Bash command"

圖:本站根據 OpenAI Codex 官方文檔 Hooks 整理的示意圖
三、關鍵一步:用 /hooks 審核信任讓配置真正生效
這是防止克隆惡意開源倉庫後一啟動就被偷跑木馬腳本的核心安全防線(沙箱基礎見 /guides/codex-permissions-sandbox):
- 儲存好
hooks.json後打開 Codex CLI,頂部會提示有待審核的鉤子; - 輸入斜槓命令
/hooks打開鉤子管理器,查看來源路徑與具體要執行的命令行; - 確認安全後標記為受信任(Trust)。注意信任綁定的是當前定義的哈希值——以後只要有人改動了裏面的命令參數,舊信任立即失效,必須重新進
/hooks點一次確認。
日常用 Codex 搭自動化研發防護鏈、對比各檔官方訂閱所含本地與雲端額度時,也可參考 /chongzhi/chatgpt-plus 的整理說明。
常見問題
Q:在 CI 流水線無頭腳本里跑一次性任務,沒法手敲 /hooks 點信任怎麼辦?
按官方文檔說明,如果外部流水線環境已經自行完成了代碼與鉤子來源的安全審計,可以在單次命令行調用時顯式傳入 --dangerously-bypass-hook-trust,僅跳過這一次調用的持久化信任檢查;切勿在來路不明的外部 PR 分支上開這個開關。
Q:為什麼我的鉤子腳本同一輪突然被執行了兩遍?
檢查是不是在 ~/.codex/ 用戶目錄和倉庫 .codex/ 目錄裏登記了相同的鉤子,或者在同一個目錄既放了 hooks.json 又在 config.toml 裏寫了 [hooks]。刪掉重複聲明即可恢復單次運行。
相關教學
- /guides/codex-config-toml-complete-guide:Codex
config.toml核心配置項全解 - /guides/codex-notify-task-completion-alert:Codex 任務完成桌面通知與聲音提醒配置
- /guides/codex-permissions-sandbox:Codex 權限審批與沙箱機制詳解
- /guides/claude-code-hooks:Claude Code Hooks 配置方法橫向對比
參考資料
- OpenAI Codex 官方文檔:Hooks — https://learn.chatgpt.com/docs/hooks
- OpenAI Codex 開發者中心 — https://developers.openai.com/codex
0 條評論
還沒有評論,來搶沙發~