實驗性功能尚未正式公告

OpenAI 尚未對 Hooks 進行正式公告，該功能目前處於實驗階段且仍在積極開發中。Windows 支援已暫時停用。

擴展性框架的核心設計

Hooks 是 Codex 的可擴展性框架，允許開發者在 Agent 迴圈中注入自訂指令碼。這些 hook 事件在對話生命週期中執行，支援以下應用場景：

• 將對話傳送至自訂的日誌記錄或分析引擎
• 掃描團隊提示詞以阻止意外貼上 API 金鑰
• 自動總結對話以建立持久記憶
• 在對話輪次停止時執行自訂驗證器，強制執行標準
• 在特定目錄時自訂提示詞

Hooks 預設隱藏在 config.toml 的功能旗標後，需明確啟用 codex_hooks = true 才能使用。

事件與執行流程

Hooks 組織為三層結構：hook 事件（如 PreToolUse、PostToolUse、Stop）、決定事件何時觸發的匹配器群組，以及匹配時執行的 hook 處理器。執行時需注意以下行為：

• 來自多個檔案的匹配 hook 會全部執行
• 同一事件的多個匹配命令 hook 並行啟動，因此一個 hook 無法阻止另一個匹配 hook 啟動
• PreToolUse、PostToolUse、UserPromptSubmit 和 Stop 在轉換範圍內執行
• 匹配欄位使用正規表示式進行過濾，支援 "*"、""，或完全忽略 matcher 以匹配所有出現次數

配置與發現機制

Codex 在作用中配置層旁搜尋 hooks.json。最實用的兩個位置為：

• ~/.codex/hooks.json（使用者層級）
• <repo>/.codex/hooks.json（專案層級）

存在多個 hooks.json 檔案時，Codex 會載入所有匹配的 hook；較高優先順序的配置層不會取代較低優先順序的 hook。

事件特定行為與限制

目前只有部分 Codex 事件支援 matcher 過濾。PostToolUse 和 PreToolUse 目前僅支援 Bash 工具攔截；該功能被視為有用的護欄而非完整執行邊界，因為模型仍可繞過此限制。UserPromptSubmit 和 Stop 事件不支援 matcher。SessionStart 事件的 matcher 應用於啟動來源（startup 或 resume）。

輸入與輸出介面

每個命令 hook 在 stdin 接收一個 JSON 物件，包含共同欄位如 session_id、transcript_path、cwd、hook_event_name 和 model。輸出支援 continue、stopReason、systemMessage 和 suppressOutput 等共同欄位，但不同事件的支援程度有異。PreToolUse 目前僅支援 systemMessage；PostToolUse 和 Stop 支援更多輸出欄位。

超時與執行環境

timeout 預設為 600 秒（支援 timeoutSec 別名）。命令以工作階段的當前工作目錄執行。對於專案本地 hook，建議從 git 根目錄解析路徑而非使用相對路徑，以避免 Codex 從子目錄啟動時產生的不穩定性。statusMessage 是可選項，exit 0 無輸出視為成功。