Codex Hooks(鉤子)怎麼配:hooks.json 路徑、觸發事件與 /hooks 信任審核

想讓 Codex 在執行工具前自動做策略校驗、改完代碼停下前自動跑單測,可以配置內置的生命週期鉤子(Hooks)。本文根據官方文檔講清 hooks.json 與 config.toml 兩種寫法、四大加載層級、完整事件表以及必做的 /hooks 哈希信任審核。

NNathaniel bigo··原創首發·AI 輔助撰寫
9 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 Plus 帳號

結論先說

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

Codex 四層 Hooks 加載位置與信任

圖:本站根據 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 按從高到低的系統治理範圍依次掃描四處位置:

  1. 系統託管層:macOS / Linux 為 /etc/codex/hooks.json,Windows 為 %ProgramData%\OpenAI\Codex\hooks.json(由企業管理員下發,預設強制受信任且不可被個人關閉);
  2. 個人用戶層:~/.codex/hooks.json(Windows 為 %USERPROFILE%\.codex\hooks.json);
  3. 受信任項目層:倉庫內的 .codex/hooks.json;
  4. 插件自帶層:已啟用插件目錄下的 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"

配置並啟用 Codex 生命週期鉤子四步

圖:本站根據 OpenAI Codex 官方文檔 Hooks 整理的示意圖

三、關鍵一步:用 /hooks 審核信任讓配置真正生效

這是防止克隆惡意開源倉庫後一啟動就被偷跑木馬腳本的核心安全防線(沙箱基礎見 /guides/codex-permissions-sandbox):

  1. 儲存好 hooks.json 後打開 Codex CLI,頂部會提示有待審核的鉤子;
  2. 輸入斜槓命令 /hooks 打開鉤子管理器,查看來源路徑與具體要執行的命令行;
  3. 確認安全後標記為受信任(Trust)。注意信任綁定的是當前定義的哈希值——以後只要有人改動了裏面的命令參數,舊信任立即失效,必須重新進 /hooks 點一次確認。

日常用 Codex 搭自動化研發防護鏈、對比各檔官方訂閱所含本地與雲端額度時,也可參考 /chongzhi/chatgpt-plus 的整理說明。

常見問題

Q:在 CI 流水線無頭腳本里跑一次性任務,沒法手敲 /hooks 點信任怎麼辦?

按官方文檔說明,如果外部流水線環境已經自行完成了代碼與鉤子來源的安全審計,可以在單次命令行調用時顯式傳入 --dangerously-bypass-hook-trust,僅跳過這一次調用的持久化信任檢查;切勿在來路不明的外部 PR 分支上開這個開關。

Q:為什麼我的鉤子腳本同一輪突然被執行了兩遍?

檢查是不是在 ~/.codex/ 用戶目錄和倉庫 .codex/ 目錄裏登記了相同的鉤子,或者在同一個目錄既放了 hooks.json 又在 config.toml 裏寫了 [hooks]。刪掉重複聲明即可恢復單次運行。

相關教學

參考資料

  • OpenAI Codex 官方文檔:Hooks — https://learn.chatgpt.com/docs/hooks
  • OpenAI Codex 開發者中心 — https://developers.openai.com/codex

Nathaniel 的更多內容

  1. 01

    LangGraph 流式輸出(Streaming)詳解:逐字 Token 流、節點進度與自定義事件寫法

    多步智能體如果等全部節點跑完才返回,網頁前端就會白屏乾等十幾秒。本文按 LangGraph 官方文檔講清 updates、messages、custom 與 values 四種 stream_mode 的區別,以及組合訂閱逐字打字機輸出加工具內部實時進度的完整代碼。

    其他 AI 工具0
  2. 02

    LangGraph 持久化與長期記憶怎麼配:Checkpointer、Store 與 PostgreSQL 實戰

    在生產環境跑 LangGraph,單靠 InMemorySaver 一重啟就會丟失全部對話。本文按官方文檔講清線程內短期檢查點(Checkpointer)與跨線程長期記憶(Store)的分工,以及用 langgraph-checkpoint-postgres 對接 PostgreSQL 的完整步驟。

    其他 AI 工具0
  3. 03

    LangGraph 多智能體怎麼寫:Supervisor 主管包與 Subgraph 隔離子圖實戰

    在 LangGraph 裏把單個圖擴展成多智能體協作有兩條官方路線:快速原型用預置包 langgraph-supervisor,大型生產系統用原生子圖(Subgraph)嵌套。本文講清兩種寫法的完整代碼、私有狀態隔離防 Token 膨脹技巧以及檢查點傳播規則。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入審批怎麼寫:interrupt 暫停圖運行與 Command 恢復實戰

    企業之所以選 LangGraph,很大程度看中它能安全掛起等待人工審批(Human-in-the-Loop)。本文按官方最新規範講清 interrupt() 動態暫停、Checkpointer 必備條件、Command(resume=...) 恢復執行,以及防止副作用重複運行的重入規則。

    其他 AI 工具0
  5. 05

    多 Agent 協作平台怎麼選:Dify、釦子(Coze)、n8n 與 LangGraph 多智能體機制對比

    搜「多agent協作平台」時,Dify、釦子、n8n 和 LangGraph 都宣稱支持多智能體,但底層的調度方式完全不同。本文跳過基礎安裝,專門從多 Agent 角色跳轉、子代理工具調用、上下文隔離與私有化部署四個維度幫你一次選準。

    其他 AI 工具0
  6. 06

    企業微信有官方 MCP 和 CLI 嗎:@wecom/cli 安裝初始化、長連接機器人與接入教學

    搜「企業 微信 有 mcp 嗎」不用再東拼西湊民間群機器人腳本了:企業微信官方已推出 @wecom/cli 命令行工具並內置 stdio 模式的 MCP Server。本文按官方開發者文檔講清安裝、智能機器人長連接初始化、業務命令與接入 Claude Code 步驟。

    Claude其他 AI 工具0

同產品的其他教學

  1. 01

    多 Agent 協同開發怎麼落地:「一個寫、一個審」雙代理工作流搭建指南

    多 Agent 協同開發裏投入產出比最高的模式就是「一個寫、一個審」。本文依據 Anthropic 與 OpenAI 官方編碼最佳實踐,講清為什麼同會話自審容易漏問題,以及用只讀子代理、跨模型交叉審查(Claude Code + Codex)和自動化閉環落地的具體方法。

    ClaudeCodex0
  2. 02

    codebase-memory 類 MCP 是什麼、怎麼用:基於語法樹圖譜的本地代碼索引原理與配置

    codebase-memory-mcp(DeusData/codebase-memory-mcp)是一類本地代碼圖譜 MCP 伺服器:用 Tree-sitter 把倉庫解析成函數與調用關係的 SQLite 圖庫,幫編碼助手查調用鏈並省下讀整份文件的額度。

    ClaudeCodex0
  3. 03

    Chrome DevTools MCP 怎麼用、怎麼保留登入態:安裝配置、獨立目錄與遠程調試端口連接

    Chrome DevTools MCP 本身免費且無需註冊帳號,大家搜「登入」通常是為了讓 AI 調試需要登入的網頁後台。本文按官方倉庫文檔講清安裝命令,以及用 --userDataDir 持久化獨立配置目錄、用 --browserUrl 掛載已登入瀏覽器的兩種標準做法。

    ClaudeCodex0
  4. 04

    Codex 接入 Amazon Bedrock 與 Google Cloud Vertex AI 教學:企業雲託管配置

    企業合規要求模型流量統一走自家 AWS 或 GCP 雲帳單時,不需要硬拼第三方代理。本文根據 OpenAI Codex 官方文檔,講清原生接入 Amazon Bedrock(四種 AWS 憑證方式)與 Google Cloud Vertex AI(ADC 認證與區域駐留)的完整步驟。

    Codex0
  5. 05

    Codex 自動審查 GitLab Merge Request 怎麼配:公有云與自託管實例接入指南

    代碼託管在 GitLab 的團隊同樣可以用上 OpenAI 官方的雲端代碼審查。本文根據官方文檔講清 GitLab.com 與企業自託管實例的服務帳號配置、Developer 權限、Webhook 開啟與 AGENTS.md 規則約束。

    ChatGPTCodex0
  6. 06

    Codex 接入 Linear 怎麼用:指派 Issue、評論 @Codex 自動改碼與 Triage 分流教學

    用 Linear 管研發任務單的團隊,可以直接把 Issue 指派給 Codex 或在評論區 @Codex 自動拉起雲端環境改代碼。本文按 OpenAI 官方文檔講清雲端環境前置準備、連接器安裝、多倉庫指定技巧以及 Triage 規則自動派單配置。

    ChatGPTCodex0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~