Codex hooks讓harness成真

截至Codex 0.150.1（2026年8月27日），Codex hooks已註冊十二個生命週期事件，在您審查並信任其確切定義之前，拒絕執行任何非受管理的hook，而且預設啟用。這項在5月14日的發布組合中隨ChatGPT行動應用程式達到正式開放的功能，如今已成熟為一個治理介面：PreToolUse可以在工具呼叫執行前加以阻擋或改寫，PermissionRequest可以直接決定一次核准，PostToolUse可以替換模型看到的結果，Stop則可以拒絕讓回合結束。²³

Codex不再像一個守在單一終端機裡等待的程式碼助理。它更像一層作業層，讓工作跨越機器、核准、專案、對話、差異、測試、截圖、外掛、憑證與本地工具。⁴

Codex hooks讓harness成真。一旦代理能從手機工作、連上遠端開發環境並執行生命週期hooks，團隊就需要在模型外圍建立控制系統：證據、核准、Git保管、來源紀律與品味。

TL;DR

Codex支援代理團隊一直在私下打造的工作流程形態：長時間執行的工作、遠端執行、行動引導、核准、hooks、限定範圍的憑證與稽核訊號。²⁴⁵ 0.150.0的hooks引擎註冊十二個事件，每個非受管理的hook在您信任其目前的雜湊之前都保持略過，hooks可從hooks.json檔案或config.toml中的行內[hooks]表格載入。³⁷ 實務問題不是「我們該如何提示Codex？」而是「Codex必須先證明什麼，我們才信任結果？」團隊應透過hooks與設定，把審查關卡、安全邊界、公開寫作標準與發布紀律寫進流程。私有機制保持私有，只公開模式、驗收條件與已驗證的成果。

重點整理

對工程團隊： - 把Codex hooks當作流程基礎設施，而非裝飾。信任審查流程是這套基礎設施的一部分，不是可以繞過的摩擦。 - 先建立證據、核准、Git保管與發布檢查，再加入聰明的自動化。

對代理工具建構者： - 圍繞Codex真正的介面來建構：行動控制、Remote SSH主機、沙箱模式、核准政策、專案指示、hooks、遙測與版本控制。 - 移植要完成的任務，不要移植舊式斜線指令的外形。

對公開寫作者： - 以learn.chatgpt.com的官方文件確認Codex目前的行為，文件落後於版本時改查引擎原始碼。 - 把私有實務標示為作者分析，並讓私有提示、hook內容、檔案路徑、來源清單、憑證與評分內部規則留在公開文案之外。

Codex hooks從哪裡來？

OpenAI於2026年5月14日發表「Work with Codex from anywhere」（隨處使用Codex）。¹ 文件變更日誌在該日期的條目記錄了這次發布組合：Codex可以透過連上一台執行Codex應用程式的Mac，從ChatGPT行動應用程式使用；hooks達到正式開放；供受信任自動化使用的Codex存取權杖也同時登場。² Codex從連線的主機上執行，因此同樣的專案、檔案、憑證、外掛、技能與設定都能從手機取用。²

遠端連線讓觸角延伸到單一書桌之外。公告中的Remote SSH能力在文件中落地為SSH主機：ChatGPT桌面應用程式可以從SSH主機加入遠端專案，並針對遠端檔案系統與shell執行對話。文件的說法很具體：「Remote access uses the connected host’s projects, chats, files, credentials, permissions, plugins, Computer Use, browser setup, and local tools.」（遠端存取使用連線主機的專案、對話、檔案、憑證、權限、外掛、Computer Use、瀏覽器設定與本地工具。）⁴

hooks本身在這次發布前就以實驗形式存在，之後又持續成長。文件把它們定義為在代理迴圈中執行指令碼或MCP工具的擴充框架，並直白列出用途：把對話送進記錄引擎、攔下不小心貼上的API金鑰、把對話摘要成持久記憶、在回合停止時執行驗證檢查，以及依目錄客製提示。³ hooks現在預設啟用；config.toml中的features.hooks可作為總開關，features.codex_hooks只以已棄用的別名形式存在。³⁶

這些細節之所以重要，是因為它們讓代理工作從一場聊天交換，變成受治理的營運。

Codex hooks在設定中長什麼樣子？

談hooks的文章應該展示一個hook。Codex會在作用中的設定層旁邊尋找hooks，最實用的位置是~/.codex/hooks.json、<repo>/.codex/hooks.json，或任一層config.toml中的行內表格；當多個來源同時存在時，所有相符的hooks都會載入並執行。³ 一個最小的hooks.json，包含一個工具關卡與一個完成關卡：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^Bash$",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/pre_tool_use_policy.py",
            "timeout": 30,
            "statusMessage": "Checking Bash command"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/evidence_gate.py"
          }
        ]
      }
    ]
  }
}

同樣的形狀改寫成config.toml的行內版本：

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "python3 ~/.codex/hooks/pre_tool_use_policy.py"
timeout = 30
statusMessage = "Checking Bash command"

每個hook都由三層組成：一個事件、一個決定事件何時適用的matcher群組，以及一個或多個處理器（command或mcp_tool）。³ 目前的事件如下，以引擎的十二項清單為準：³⁷

線上的hooks文件目前仍只記載其中十一個事件，還沒有Interrupt的章節。0.150.0的變更日誌條目（#40511）與引擎原始碼rust-v0.150.0中的HOOK_EVENT_NAMES: [&str; 12]承載著第十二個。²⁷ 當頁面與引擎不一致時，以引擎為準。

hooks實際上看得到哪些工具呼叫？

早期版本的文件警告PreToolUse除了shell與MCP呼叫之外幾乎不涵蓋其他工具。目前的文件把範圍放寬：「PreToolUse and PostToolUse can observe more than shell and MCP calls. Most local function tools use the same hook path,」（PreToolUse與PostToolUse能觀察的不只shell與MCP呼叫。多數本地函式工具走同一條hook路徑），因此matcher可以直接指名update_plan這類工具，spawn_agent也會以Agent比對。³ shell指令以Bash比對，apply_patch檔案編輯以apply_patch、Edit或Write比對，MCP工具則比對像mcp__filesystem__read_file這樣的名稱。³

託管工具仍在範圍之外：WebSearch與同類工具永遠不會經過本地函式工具的hook路徑。³ 文件保留了一句值得整段引用的緩和警語：「Some specialized tool paths can opt out of the default hook path. Treat tool hooks as a useful guardrail, not a complete enforcement boundary.」（某些特殊的工具路徑可以退出預設的hook路徑。把工具hooks當作有用的護欄，而不是完整的強制邊界。）³ 硬邊界仍由沙箱負責；hooks負責的是邊界之內的審查與引導。

Codex如何決定哪些hooks可以執行？

hooks是會引導代理的程式碼，所以Codex連hooks本身也要治理。環繞模型的控制系統從這裡開始。

任何非受管理的hook執行之前，Codex都要求您先審查並信任其確切定義。信任是針對hook目前的雜湊記錄的，因此新的或被修改過的hook會被標記為待審查，在再次獲得信任之前一律略過。³ CLI中的/hooks指令會開啟審查介面：檢視hook來源、審查新的或變更過的hooks、信任它們，或停用個別項目。啟動時若有hooks需要審查，Codex會印出指向/hooks的警告。³

來自系統、MDM、雲端或requirements.toml來源的受管理hooks位於這套流程之上：它們依政策受信任，且無法從使用者的hook瀏覽器中停用。³ 外掛則位於流程之內：安裝或啟用外掛並不會信任其隨附的hooks，這些hooks和其他hooks一樣，在審查之前保持略過。³ 專案本機hooks只在專案的.codex/層受信任時載入；不受信任的專案仍會載入您的使用者層與系統層hooks。³

自動化也適用同一條規則。codex exec執行時沒有審查UI，因此未受信任的hook會被靜默略過，直到您先在互動式工作階段中信任它；文件還沒有把這件事寫出來，但引擎的啟動審查介面只存在於互動式TUI中。⁷ 對於已在別處審核hook來源的管線，--dangerously-bypass-hook-trust能讓已啟用的hooks在那一次呼叫中執行，而不寫入持久信任。³ 請刻意地完成信任，否則就等著看您的關卡沒有觸發：harness會在任何程式碼執行之前，先決定哪些程式碼可以引導代理。

hook阻擋時會發生什麼？何時已經太遲？

時機決定一個hook還能改變什麼。多數hooks同步執行，預設逾時600秒；SessionEnd與Interrupt預設1秒、上限3秒：SessionEnd在工作階段收尾拆除時觸發，Interrupt則在使用者等待時觸發。³⁷

PreToolUse在任何事情發生之前行動，因此握有最強的牌：拒絕該呼叫，或回傳permissionDecision: "allow"搭配updatedInput加以改寫。拒絕的形狀如下：

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by hook."
  }
}

以結束代碼2搭配stderr上的理由同樣能阻擋。³

PostToolUse在工具執行之後才行動，因此無法復原副作用。decision: "block"會把工具結果替換成您的回饋，讓模型從那則訊息繼續，既能修正方向，又不假裝指令從未發生。³ Stop把一次拒絕變成一次接續：擋下完成，Codex就繼續工作，您的理由成為新的提示。³

對於永遠不該卡在關鍵路徑上的檢查，在command處理器上設定async = true。背景hooks在Codex繼續工作的同時執行，在下一個安全點交付輸出，並且明確地不能阻擋、核准或改寫任何東西；工具政策、權限決定、提示拒絕與回合接續請保持同步。³

0.149與0.150升級了什麼？

8月下旬的兩個穩定版本收緊了治理故事。

Codex CLI 0.149.0（2026年8月20日）淘汰了untrusted核准政策（#39630）；仍寫著這個值的設定現在會失敗，並給出要求移除該設定的可操作錯誤。²⁷ Codex CLI 0.150.0（2026年8月26日）新增了Interrupt hook事件（#40511）：「New Interrupt hooks can run commands or MCP handlers when an active top-level turn is interrupted.」（新的Interrupt hooks可以在進行中的頂層回合被中斷時執行指令或MCP處理器。）Interrupt hooks永遠不會為子代理執行。²⁷ 同一版本也讓不受信任的專案不再能提供專案層級的AGENTS.md指示（#39837），這與既有規則相互呼應：專案本機hooks只從受信任的.codex/層載入。²³

方向是一致的：不受信任的目錄，對走進它的代理擁有越來越少的權限。指示、hooks與核准捷徑，如今全都要經過明確的信任決定。

為什麼hooks比行動存取更重要？

行動存取改變的是人可以介入的地點。hooks改變的是系統可以強制執行的內容。

手機讓操作者在離開書桌時也能回答問題。hook則能在高風險動作之前、檔案編輯之後、完成之前，或發布檢查期間攔住代理。手機解決延遲。hook解決標準。

Codex在沙箱與核准方面已有第一方控制介面。安全文件把沙箱模式與核准政策配成一對：前者定義代理技術上能做什麼，後者定義Codex何時必須停下來先問。⁵ 代理預設在關閉網路存取的狀態下執行，預設的本機workspace-write模式除非使用者啟用，否則保持網路關閉。⁵ hooks位於這些控制項旁邊，是審查與引導層，不是沙箱的替代品。

hooks能讓本地標準變得可執行：

模型可能忘記規則。hook能在規則真正要緊的那一刻，把規則再跑一次。

harness擁有什麼是供應商沒有的？

代理harness是環繞模型的作業層：權限、記憶、工具、hooks、來源檢查、發布關卡、審查包與回滾紀律。這個詞聽起來也許私有或華麗，但它的工作很樸素。這一層把意圖變成可問責的工作。

Codex現在公開了足夠的官方介面，讓這一層得以明確化。遠端連線承載主機環境。沙箱模式與核准政策定義行動邊界。設定檔定義模型、專案、權限、MCP伺服器、技能、hooks、遙測與功能。⁶ OpenTelemetry匯出維持選擇性加入且預設關閉；啟用後，Codex會發出結構化事件，涵蓋對話、API請求、串流活動、使用者提示（預設遮蔽）、工具核准決定與工具結果。⁵⁸

這組介面創造了一個有用的分工：

供應商應持續改進執行環境。判斷仍屬於團隊。

團隊應該先把什麼寫進系統？

從四個關卡開始。它們立刻回本。

證據關卡

Codex最初的發表文章強調可驗證的證據：終端機記錄、測試輸出，以及任務完成過程中可追溯的步驟。⁹ 把這個期待變成不可協商的要求。一次有意義的完成，應指名變更的檔案、執行的指令、觀察到的行為、失敗的檢查與剩餘的缺口。

對公開工作而言，證據包括來源連結，以及主張與來源的對齊。對網頁發布而言，證據包括渲染後的路由、中繼資料、schema、可發現性檔案、部署狀態、快取新鮮度與線上變更標記。對翻譯而言，證據包括語系涵蓋率、品質關卡、儲存列或快取檔案，以及必要時的母語審閱狀態。

核准關卡

不要用同一種核准姿態對待所有動作。核准文件目前的組合表從Auto預設（workspace-write沙箱搭配on-request核准）一路排到安全的唯讀瀏覽、唯讀的非互動式CI、自動審查模式與危險的完全存取。⁵ 其中一列落後於現實：untrusted政策仍出現在頁面上，但0.149.0已將它淘汰，明確寫出的設定現在會報錯。²⁵ 想在今天採用永遠詢問的姿態，請把read-only沙箱與on-request核准搭配使用。一套強健的本地政策維持同樣的形狀：低風險讀取安靜通過，有副作用的工作接受審查，破壞性或對外可見的工作需要明確證據。

Git保管關卡

代理工作需要回滾把手。Codex自己的安全文件說Codex在版本控制下運作得最好：委派前保持狀態乾淨、頻繁提交、執行針對性驗證、審查差異，並在提交訊息中記錄決定。⁵

這些建議應該變成流程。在連貫且驗證過的存檔點之後提交。以精確路徑暫存。依可獨立還原的關注點拆分提交。除非發布流程已授予發布權限，否則推送前先詢問。不要因為代理剛好看到了無關的髒檔案，就把它們掃進提交。

品味關卡

AI寫程式讓實作變便宜。實作越便宜，品味就越值錢。

品味不是裝飾性的偏好。它是指工作讓整個產品變好。它是指代理能拒絕一條技術上可行、卻會削弱成果的路。它是指公開寫作避開私有機制、無憑據的主張與贅語。它是指只要使用者可見的路徑仍然壞著，一個正確的本地修補仍可能不及格。

品味關卡應該問：

Mozilla的Firefox工作證明了什麼？

Mozilla在5月7日發表的文章講述以Claude Mythos Preview強化Firefox，從另一個技術棧得出同樣的結論。團隊表示，早期的LLM程式碼稽核嘗試展現了潛力，但誤報太多而無法擴展。代理式harness改變了經濟學，因為它們能建立並執行可重現的測試案例，動態驗證錯誤假設。¹⁰

Mozilla最重要的那句話與模型本身無關。團隊說，發現是必要的，但不充分。有用的系統必須整合進完整的安全錯誤生命週期：目標、去重、錯誤追蹤、分級、修復與發布。¹⁰ 作者們也說，這條管線反映了Firefox程式碼庫的語意、工具與流程。¹⁰

這就是給Codex的一課。更好的模型當然重要。但環繞模型的營運系統，決定了工作能否成為受信任的產出。

什麼應該留在公開文案之外？

一篇公開的Codex文章，不該把私有的工作系統傾倒出來。

以下內容請留在公開文案之外：

• 私有提示與hook內容；
• 敏感的本地路徑；
• 精確的來源對照與評分內部規則；
• 帳號識別碼與憑證處理方式；
• 私有的工作流程捷徑；
• 未發布的外掛行為；
• 任何有助於陌生人重建內部營運的資訊。

改為發表模式：這個關卡保護什麼、要求什麼證據、攔下哪種失敗，以及團隊如何用官方Codex介面實作這個想法。

這條線保護信任。它也讓文字更好。私有機制讀起來通常像鄉野傳說。公開的驗收條件則幫助其他團隊思考自己的系統。

最小的Codex harness地圖長什麼樣子？

建立能證明有用工作的最小控制地圖。

從明確開始。跑一個真實任務。記錄關卡在哪裡幫了忙、在哪裡礙了事。只把改善使用者可見成果的部分升級為常設做法。

快速總結

Codex hooks、Remote SSH、行動控制、沙箱、核准、設定、遙測與版本控制指向同一個方向：程式碼代理需要環繞它們的作業系統。²⁴⁵⁶ 代理能寫程式。harness決定什麼算是工作。

最好的團隊不會靠產出最多的代理輸出獲勝。他們會靠讓代理工作可檢視、可回滾、有來源、有品味、值得發布來獲勝。

常見問題

什麼是Codex hooks？

Codex hooks在代理迴圈中執行指令碼或MCP工具，從hooks.json檔案或config.toml中的行內[hooks]表格載入。文件把用途說得直白：把對話送進記錄引擎、攔下不小心貼上的API金鑰、把對話摘要成持久記憶、在回合停止時執行驗證，以及依目錄客製提示。³ 0.150.0的引擎註冊十二個事件，從PreToolUse、PermissionRequest、PostToolUse到Stop與新的Interrupt；文件頁面在跟上進度之前仍列出十一個。³⁷

為什麼Codex hooks重要？

hooks讓團隊把標準放在決策點上，而不是只依賴提示。hook可以在代理行動或嘗試結束時，檢查證據、來源品質、git狀態或發布就緒度。

為什麼我的hook沒有執行？

最常見的答案是信任。Codex會略過任何您尚未審查其目前雜湊的非受管理hook，在互動式工作階段印出啟動警告，在codex exec自動化中則靜默略過。⁷ 開啟/hooks審查並信任它，或只在已於別處審核hook來源的管線中傳入--dangerously-bypass-hook-trust。³

Codex行動版會取代本地代理工作流程嗎？

不會。行動控制讓使用者在離開書桌時引導工作，但連線的主機仍然提供專案、對話、檔案、憑證、權限、外掛與本地工具。⁴ 團隊仍需要本地政策、安全的憑證、版本控制與驗證。

Codex harness應該先包含什麼？

從專案指示、沙箱與核准姿態、機密邊界、證據停止關卡、精確路徑的Git保管、公開主張的來源驗證，以及針對使用者可見工作的發布關卡開始。

團隊應該公開自己的Codex hooks嗎？

公開模式與驗收條件，而不是私有的hook內容或敏感的工作流程細節。一篇有用的公開文章可以說明hook的職責，而不暴露私有路徑、來源對照、提示、憑證或評分規則。

參考資料