Codex harness
Codex 測試框架執行階段
Codex 控制框架回合的執行階段契約。關於設定與路由，請參閱 Codex 控制框架。關於設定欄位，請參閱 Codex 控制框架參考。
概覽
Codex 負責原生模型迴圈、原生執行緒續接、原生工具延續，以及原生壓縮。OpenClaw 負責頻道路由、工作階段檔案、可見訊息傳遞、OpenClaw 動態工具、核准、媒體傳遞，以及該邊界周圍的逐字稿鏡像。
提示詞路由依循所選的執行階段，而不只是提供者字串。原生 Codex 回合會取得 Codex app-server 開發者指示；明確的 OpenClaw 相容性路由即使使用 Codex 形式的 OpenAI 驗證或傳輸方式，仍會保留一般的 OpenClaw 系統提示詞。
OpenClaw 啟動及續接原生 Codex 執行緒時，會停用 Codex 的內建人格（personality: "none"），使工作區人格檔案與 OpenClaw 代理程式身分保持權威性。除此之外，原生 Codex 仍會保留由 Codex 管理的基礎／模型指示及專案文件載入。輕量級 OpenClaw 執行（例如排程）仍會停用專案文件載入。
OpenClaw 開發者指示涵蓋 OpenClaw 執行階段相關事項：來源頻道傳遞、OpenClaw 動態工具、ACP 委派、配接器情境，以及目前代理程式工作區的設定檔案。Skills 目錄與經工具路由的 MEMORY.md 指標，會投射為限於該回合的協作開發者指示。記憶工具無法使用時，使用中的 BOOTSTRAP.md 內容與完整的 MEMORY.md 會改以純文字回合輸入情境提供。
多數 OpenClaw 動態工具使用可搜尋的 openclaw 命名空間。標記為 catalogMode: "direct-only" 的工具使用 openclaw_direct；Codex 會將其保持為模型可直接看到的 DirectModelOnly，而不會將其暴露給巢狀的程式碼模式執行。
執行緒繫結與模型變更
當 OpenClaw 工作階段連接至現有的 Codex 執行緒時，下一個回合會將目前選取的模型、核准原則、沙箱、核准審查者及服務層級重新傳送至 app-server。從 openai/gpt-5.5 切換至 openai/gpt-5.2 會保留執行緒繫結，但要求 Codex 使用新選取的模型繼續執行。
受監督的繫結是例外。OpenClaw 模型選擇器會保持鎖定，且續接時會省略模型與提供者覆寫，使 Codex 還原標準執行緒中保存的模型與提供者。另一個原生 Codex 控制端可以變更這組保存的配對，而初始快照可能會產生 Codex 一般的模型差異警告；外層 OpenClaw 模型與後援鏈絕不會取代其中任一項。
監督與安全續接
Codex 監督是同一個 codex 外掛中需選擇啟用的功能。它透過獨立連線探索原生執行緒，且只將未封存的工作階段投射至閘道目錄。若未明確設定 appServer 連線，該連線會使用受管理的使用者家目錄標準輸入輸出，而一般控制框架仍限定於代理程式範圍。列出項目與讀取中繼資料均為被動操作：它們不會續接執行緒、不會讓 OpenClaw 訂閱其即時事件，也不會回應其核准要求。
對於閘道電腦上已儲存或閒置的工作階段，Continue as branch 會建立一般且模型鎖定的聊天，並鏡像有界的使用者與助理歷程，直到來源最後一個已保存的終止回合。第一個一般聊天回合會安裝真正的核准處理常式，並使用臨時原生分支固定快照，而不覆寫模型或提供者。Codex App Server 使用目前的原生設定並傳回所選配對；若該模型與來源最後記錄的模型不同，便會發出一般警告。在同一個監督連線上，OpenClaw 會依該標準 appServer 來源的工作目錄及執行階段原則啟動 Codex 控制框架執行緒，初次啟動時精確使用傳回的模型與提供者、注入有界的可見歷程，並封存臨時分支。來源永遠不會被續接。標準執行緒具備完整的 OpenClaw 控制框架工具介面；來源中的推理、工具呼叫及工具結果不會複製至其中。私有連線範圍會在待處理及已提交的繫結狀態中持續存在，因此後續每個回合都會留在該連線上，並使用原生驗證與提供者設定。若監督遭停用，或繫結／連線發生偏移，系統會以關閉方式失敗，而不會切換至一般的代理程式家目錄控制框架。
原始命令列介面或 VS Code 來源仍可出現在兩個目錄中。標準分支是原生 Codex 執行緒，但其來源種類為 appServer；原生用戶端可能會篩除該來源種類，因此不保證它會出現在 Codex Desktop 中。
使用中的來源無法啟動新分支或封存；現有的受監督聊天仍可開啟。notLoaded 表示活動狀態未知，而非閒置；只有在明確確認沒有其他執行者，並重新讀取程序本機狀態後，OpenClaw 才允許封存本機的 idle 或 notLoaded 資料列。Codex 會在單一 App Server 程序內依序執行執行緒異動，但不提供跨程序的獨占執行者或核准擁有者租約，因此該讀取操作無法證明其他程序未使用此執行緒。對於精確目標，或 Codex 分頁式後代查詢傳回的任何未封存衍生後代，OpenClaw 會封鎖已知的使用中繫結擁有者。列舉錯誤、循環及安全限制耗盡時，系統會以關閉方式失敗。原生封存仍可能與另一個程序中的新回合發生競爭，因此確認範圍包含未知用戶端，以及狀態讀取與封存之間的空窗期。受監督且模型鎖定的聊天在保護原生繫結期間無法刪除。
配對節點目錄在初始版本中只提供中繼資料。目前的節點叫用邊界採用請求／回應模式，無法承載真正 Codex 控制框架繫結所需的長時間回合事件、核准要求或串流輸出。因此，即使資料列處於閒置狀態，遠端 Continue 與 Archive 仍不可用。
關於操作人員設定及可見的 Control UI 行為，請參閱 Codex 監督。
可見回覆與心跳偵測
透過 Codex 控制框架進行的直接／來源聊天回合，預設會將最終助理回覆自動傳遞至內部 WebChat 介面，與 Pi 控制框架契約一致：代理程式正常回覆，而 OpenClaw 會將最終文字張貼至來源對話。設定 messages.visibleReplies: "message_tool" 可讓最終助理文字保持非公開，除非代理程式呼叫 message(action="send")。
Codex 心跳偵測回合預設會在可搜尋的 OpenClaw 工具目錄中取得 heartbeat_respond，讓代理程式記錄此次喚醒應保持安靜或發出通知。心跳偵測主動性指引會作為限定於心跳偵測回合的 Codex 協作模式開發者指示傳送；一般聊天回合則維持 Codex 預設模式。當 HEARTBEAT.md 非空白時，心跳偵測指示會引導 Codex 讀取該檔案，而非將其內容直接內嵌。
鉤子邊界
| 層級 | 擁有者 | 用途 |
|---|---|---|
| OpenClaw 外掛鉤子 | OpenClaw | 維持 OpenClaw 與 Codex 控制框架之間的產品／外掛相容性。 |
| Codex app-server 擴充中介軟體 | OpenClaw 隨附外掛 | 圍繞 OpenClaw 動態工具提供每回合的配接器行為。 |
| Codex 原生鉤子 | Codex | 由 Codex 設定控制的低階 Codex 生命週期與原生工具原則。 |
OpenClaw 不會使用專案或全域 Codex hooks.json 檔案來路由外掛行為。對於原生工具與權限橋接，OpenClaw 會為每個執行緒注入 PreToolUse、PostToolUse、PermissionRequest 及 Stop 的 Codex 設定。
啟用 Codex app-server 核准時（approvalPolicy 不為 "never"），預設注入的原生鉤子設定會省略 PermissionRequest，使 Codex 的 app-server 審查者與 OpenClaw 核准橋接在審查後處理實際的權限提升。若仍要強制使用相容性轉送，請將 permission_request 加入 nativeHookRelay.events。其他 Codex 鉤子（例如 SessionStart 與 UserPromptSubmit）仍屬 Codex 層級控制；在 v1 契約中，它們不會公開為 OpenClaw 外掛鉤子。
對於 OpenClaw 動態工具，OpenClaw 會在 Codex 要求呼叫後執行工具，因此外掛與中介軟體行為會在控制框架配接器中執行。對於 Codex 原生工具，Codex 擁有標準工具記錄；OpenClaw 可以鏡像所選事件，但除非 Codex 透過 app-server 或原生鉤子回呼公開該功能，否則無法改寫原生執行緒。
Codex app-server 報告模式的 PreToolUse 事件會將外掛核准延後至相符的 app-server 核准。若 OpenClaw before_tool_call 鉤子傳回 requireApproval，而原生承載資料將 openclaw_approval_mode 設為 "report"，原生鉤子轉送會記錄外掛核准要求，且不傳回原生決策。Codex 稍後為同一次工具使用傳送 app-server 核准要求時，OpenClaw 會開啟外掛核准提示，並將決策映射回 Codex。Codex PermissionRequest 事件是獨立的核准路徑；設定使用該橋接時，仍可透過 OpenClaw 核准進行路由。
Codex app-server 項目通知也會為原生 PostToolUse 轉送尚未涵蓋的原生工具完成事件，提供非同步 after_tool_call 觀察。這些內容僅供遙測／相容性用途；無法封鎖、延遲或修改原生工具呼叫。
壓縮與 LLM 生命週期投射來自 Codex app-server 通知及 OpenClaw 配接器狀態，而非原生 Codex 鉤子命令。before_compaction、after_compaction、llm_input 及 llm_output 是配接器層級的觀察，而不是逐位元組擷取 Codex 的內部請求或壓縮承載資料。
Codex 原生 hook/started 與 hook/completed app-server 通知會投射為 codex_app_server.hook 代理程式事件，以供軌跡記錄與偵錯。它們不會叫用 OpenClaw 外掛鉤子。
V1 支援契約
Codex 執行階段 v1 支援：
| 介面 | 支援狀態 | 原因 |
|---|---|---|
| 透過 Codex 執行的 OpenAI 模型迴圈 | 支援 | Codex app-server 負責 OpenAI 輪次、原生執行緒續接及原生工具接續執行。 |
| OpenClaw 頻道路由與傳遞 | 支援 | Telegram、Discord、Slack、WhatsApp、iMessage 及其他頻道均位於模型執行階段之外。 |
| OpenClaw 動態工具 | 支援 | Codex 要求 OpenClaw 執行這些工具，因此 OpenClaw 會留在執行路徑中。 |
| 提示詞與情境外掛 | 支援 | OpenClaw 將 OpenClaw 專屬提示詞／情境投射至 Codex 輪次，同時讓 Codex 所擁有的基礎提示詞、模型提示詞及已設定的專案文件提示詞留在原生 Codex 路徑中。OpenClaw 會停用原生執行緒的 Codex 內建人格，讓代理程式工作區的人格檔案維持權威來源。原生 Codex 開發者指示僅接受明確限定於 codex_app_server 的命令指引；舊版全域命令提示仍適用於非 Codex 提示詞介面。 |
| 情境引擎生命週期 | 支援 | 組裝、擷取及輪次後維護會在 Codex 輪次前後執行。情境引擎不會取代原生 Codex 壓縮。 |
| 動態工具鉤子 | 支援 | before_tool_call、after_tool_call 及工具結果中介軟體會在 OpenClaw 所擁有的動態工具前後執行。 |
| 生命週期鉤子 | 支援作為轉接器觀測事件 | llm_input、llm_output、agent_end、before_compaction 及 after_compaction 會以真實的 Codex 模式承載資料觸發。 |
| 最終答案修訂閘門 | 透過原生鉤子轉送提供支援 | Codex Stop 會轉送至 before_agent_finalize；revise 會要求 Codex 在完成最終處理前再執行一次模型輪次。 |
| 原生殼層、修補及 MCP 封鎖或觀測 | 透過原生鉤子轉送提供支援 | Codex PreToolUse 與 PostToolUse 會針對已提交的原生工具介面進行轉送，包括 Codex app-server 0.142.0 或更新版本上的 MCP 承載資料。支援封鎖，但不支援改寫引數。 |
| 原生權限政策 | 透過 Codex app-server 核准及相容性原生鉤子轉送提供支援 | Codex 審查後，Codex app-server 的核准請求會經由 OpenClaw 路由。原生核准模式必須選擇啟用 PermissionRequest 原生鉤子轉送，因為 Codex 會在守護程式審查前發出該事件。 |
| App-server 軌跡擷取 | 支援 | OpenClaw 會記錄其傳送給 app-server 的請求，以及從 app-server 收到的通知。 |
Codex 執行階段 v1 不支援：
| 介面 | V1 邊界 | 未來方向 |
|---|---|---|
| 原生工具引數修改 | Codex 原生工具執行前鉤子可以封鎖，但 OpenClaw 不會改寫 Codex 原生工具引數。 | 需要 Codex 鉤子／結構描述支援替換工具輸入。 |
| 可編輯的 Codex 原生逐字記錄歷史 | Codex 擁有標準原生執行緒歷史。OpenClaw 擁有其鏡像並可投射未來情境，但不應修改未受支援的內部資料。 | 若需要對原生執行緒進行精細修改，請新增明確的 Codex app-server API。 |
Codex 原生工具記錄的 tool_result_persist |
該鉤子會轉換 OpenClaw 所擁有的逐字記錄寫入內容，而非 Codex 原生工具記錄。 | 可以鏡像轉換後的記錄，但標準記錄的改寫需要 Codex 支援。 |
| 豐富的原生壓縮中繼資料 | OpenClaw 可以要求原生壓縮，但不會收到穩定的保留／捨棄清單、權杖差異、完成摘要或摘要承載資料。 | 需要更豐富的 Codex 壓縮事件。 |
| 壓縮介入 | OpenClaw 不允許外掛或情境引擎否決、改寫或取代原生 Codex 壓縮。 | 若外掛需要否決或改寫原生壓縮，請新增 Codex 壓縮前／後鉤子。 |
| 逐位元組的模型 API 請求擷取 | OpenClaw 可以擷取 app-server 請求與通知，但 Codex 核心會在內部建構最終的 OpenAI API 請求。 | 需要 Codex 模型請求追蹤事件或偵錯 API。 |
原生權限與 MCP 誘導請求
針對 PermissionRequest，只有在政策作出決定時，OpenClaw 才會傳回明確的允許或拒絕
決定。沒有決定的結果並不等同允許：Codex
會將其視為鉤子未作決定，並轉入自身的守護程式或使用者
核准路徑。
Codex app-server 核准模式預設會略過此原生鉤子。除非
在 nativeHookRelay.events 中明確加入 permission_request，或由相容性執行階段安裝該鉤子，
否則均適用此規則。
當操作人員針對 Codex 原生權限請求選擇 allow-always 時，
OpenClaw 會在有限的工作階段時間範圍內記住該提供者／工作階段／工具輸入／cwd
指紋的精確組合。刻意將記住的決定限制為僅精確相符：命令、引數、工具承載資料或
cwd 如有變更，就會建立新的核准請求。
當 Codex 將 _meta.codex_approval_kind 標記為 "mcp_tool_call" 時，Codex MCP 工具核准誘導請求會經由 OpenClaw 的外掛核准
流程路由。Codex
request_user_input 提示會傳回原始聊天，而下一則排入佇列的後續訊息會回覆該原生伺服器請求，
不會被引導為額外情境。其他 MCP 誘導請求會以封閉方式失敗。
如需了解承載這些提示的一般外掛核准流程，請參閱 外掛權限請求。
佇列引導
執行中的佇列引導會對應至 Codex app-server turn/steer。使用預設的
messages.queue.mode: "steer" 時，OpenClaw 會在已設定的靜默時間範圍內批次彙整引導模式的聊天
訊息，並依抵達順序將其作為單一 turn/steer
請求傳送。
Codex 審查與手動壓縮回合可能會拒絕同一回合的引導。在此情況下，OpenClaw 會等待進行中的執行完成，再開始處理提示。若訊息預設應進入佇列而非用於引導，請使用 /queue followup 或 /queue collect。請參閱引導佇列。
Codex 意見回饋上傳
在原生 Codex 控制框架上，當工作階段的 /diagnostics [note] 獲得核准時，OpenClaw 也會針對相關 Codex 執行緒呼叫 Codex app-server 的 feedback/upload，其中包括每個列出執行緒的日誌，以及可用時由其衍生的 Codex 子執行緒日誌。
上傳會透過 Codex 的一般意見回饋路徑傳送至 OpenAI 伺服器。如果該 app-server 已停用 Codex 意見回饋，此命令會傳回 app-server 錯誤。完成的診斷回覆會列出已傳送執行緒的頻道、OpenClaw 工作階段 ID、Codex 執行緒 ID，以及本機 codex resume <thread-id> 命令。
如果您拒絕或忽略核准要求，OpenClaw 不會顯示這些 Codex ID，也不會傳送 Codex 意見回饋。此上傳不會取代本機閘道診斷匯出。關於核准、隱私權、本機套件組合及群組聊天行為，請參閱診斷匯出。
只有當您想要針對目前附加的執行緒上傳 Codex 意見回饋，而不需要完整的閘道診斷套件組合時，才使用 /codex diagnostics [note]。
壓縮與逐字稿鏡像
當選取的模型使用 Codex 控制框架時，原生執行緒壓縮由 Codex app-server 負責。OpenClaw 不會對 Codex 回合執行預檢壓縮、不會以內容引擎壓縮取代 Codex 壓縮，也不會在無法啟動原生壓縮時改用 OpenClaw 或公開的 OpenAI 摘要功能。OpenClaw 會保留逐字稿鏡像，以供頻道記錄、搜尋、/new、/reset，以及日後切換模型或控制框架時使用。
明確的壓縮要求（例如 /compact 或由外掛要求的手動壓縮操作）會使用 thread/compact/start 啟動原生 Codex 壓縮。OpenClaw 會讓要求與共用用戶端租約保持開啟，直到 Codex 發出相符的 contextCompaction 完成項目，然後將壓縮回合回報為已完成。如果該終止回合超過已設定的壓縮逾時時間，OpenClaw 會要求中斷原生回合。租約與每個執行緒的壓縮柵欄會持續保持鎖定，直到 Codex 回報終止狀態或確認中斷 RPC。如果 Codex 未在中斷寬限期內確認，OpenClaw 會先停用連線，再釋放柵欄。遠端連線也會解除相符的執行緒繫結，避免後續工作與未確認的遠端回合重疊。已停用連線上的其他回合會失敗，並可使用新的用戶端重試。用戶端關閉、要求取消或壓縮回合失敗，都會傳回失敗的操作。因內容壓力而自動壓縮是 Codex 的職責；OpenClaw 只會針對手動要求的觸發條件啟動原生壓縮。
當內容引擎要求進行 Codex 執行緒啟動投影時，OpenClaw 會將工具呼叫名稱與 ID、輸入結構，以及經過遮蔽的工具結果內容投影至新的 Codex 執行緒。它不會將原始工具呼叫引數值複製至該投影。
此鏡像包含使用者提示、助理最終文字，以及 app-server 發出時的輕量 Codex 推理或計畫記錄。OpenClaw 會記錄原生壓縮的開始與終止狀態，但不會公開人類可讀的壓縮摘要，也不會提供可稽核的清單來顯示 Codex 在壓縮後保留了哪些項目。
由於 Codex 擁有標準的原生執行緒，tool_result_persist 不會重寫 Codex 原生工具結果記錄。它只會在 OpenClaw 寫入由 OpenClaw 擁有的工作階段逐字稿工具結果時套用。
媒體與傳遞
OpenClaw 仍負責媒體傳遞與媒體供應商選擇。圖片、影片、音樂、PDF、TTS 與媒體理解功能會使用相符的供應商／模型設定，例如 agents.defaults.imageGenerationModel、videoGenerationModel、pdfModel 和 messages.tts。
文字、圖片、影片、音樂、TTS、核准要求與訊息工具輸出，仍會透過一般 OpenClaw 傳遞路徑處理；媒體生成不需要舊版執行階段。當 Codex 發出含有 savedPath 的原生圖片生成項目時，即使 Codex 回合沒有助理文字，OpenClaw 仍會透過一般回覆媒體路徑轉送該確切檔案。
