# 策展 · X (Twitter) 🔥

> 作者：Peter Gostev (SF: 29 Mar - 3 Apr) (@petergostev) · 平台：X (Twitter) · 日期：2026-03-27

> 原始來源：https://x.com/petergostev/status/2037544433931915771

## 中文摘要

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 無輸出視為成功。

## 標籤

Codex, Agent, 功能更新, OpenAI