--- read_when: - 設計 Codex 工作階段探索、續接或封存行為 - 變更原生工作階段目錄使用者介面或閘道 RPC - 將 Codex 監督擴展至配對節點 summary: 從 OpenClaw 監督原生 Codex 工作階段的架構與產品邊界。 title: Codex 監督 x-i18n: generated_at: "2026-07-12T14:50:29Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 15 provider: openai source_hash: 78528afd31c18fc84e0adb6479a688da7df6d0a5c04e539d253c84d3a17a5f53 source_path: specs/codex-supervision.md workflow: 16 --- # Codex 監督 ## 目標 Codex 監督讓 OpenClaw 操作者探索原生 Codex 工作階段，並在安全的情況下，透過一般的 OpenClaw Chat 介面建立本機分支。Codex App Server 仍是對話串與模型迴圈的擁有者。OpenClaw 提供機群目錄、經過驗證的操作者介面、工作階段繫結，以及頻道傳遞。 此功能屬於官方 `codex` 外掛。沒有獨立的 Supervisor 外掛，也沒有第二套 Codex 通訊協定實作。 ## 產品邊界 只要 Codex 外掛處於啟用狀態，就會註冊目錄。使用以下設定啟用面向代理程式的監督工具： ```text plugins.entries.codex.config.supervision.enabled = true ``` 目前啟用的初始產品刻意縮小了長期機群計畫的範圍： - 僅列出未封存的 Codex 對話串。 - 依穩定的主機身分，將本機與已選擇加入的配對節點資料列分組。 - 從已儲存或閘道本機的閒置對話串建立一般且鎖定模型的 Chat 分支，在第一次互動時啟動其完整 Codex 控制框架對話串，或開啟先前分支所建立的 Chat。 - 僅在明確確認沒有其他執行器後，封存已儲存或閘道本機的閒置對話串。 - 顯示使用中的本機來源，但不提供新分支或封存控制項，同時仍允許開啟現有的受監督 Chat。 - 在主要側邊欄顯示每台主機最新的資料列、在工作階段頁面保留完整目錄，並為本機與配對節點資料列提供有界且以游標分頁的逐字記錄讀取功能。 - 依主機隔離目錄失敗。 目錄是未封存項目的集合。其中的資料列仍可具有閒置、使用中、`notLoaded` 或錯誤的互動狀態。 面向代理程式的監督功能仍須選擇加入。引導式初始設定會在原生 Codex 安裝偵測成功，且所選推論後端通過即時檢查後，嘗試安裝並啟用此功能，而不受使用者所選主要後端影響。只有當這個機會性外掛設定成功時，監督功能才會啟用。明確停用的外掛、政策封鎖或 `supervision.enabled: false` 對監督工具仍具有決定性，但不會停用操作者工作階段目錄。 ## 擁有權 `codex` 外掛擁有所有 Codex App Server 行為： - 端點探索與連線生命週期 - 通訊協定初始化與版本檢查 - 對話串列出、讀取、繼續、封存與事件處理 - 核准與使用者輸入橋接 - 原生對話串與 OpenClaw 工作階段的繫結 - 繼續後強制使用僅限 Codex 的模型與控制框架 Control UI 與閘道使用此外掛擁有的服務。它們不會直接讀取 Codex rollout 檔案，也不會實作另一個 App Server 用戶端。 預設本機拓撲為： ```text Codex Desktop -> 私有 stdio App Server -> 使用者 Codex 主目錄 ^ OpenClaw Codex 外掛 -> 監督 App Server 連線 （預設為受管理的使用者主目錄 stdio；明確的 appServer 設定會受到尊重） -> 被動來源目錄與讀取 -> 快照固定 -> 標準 appServer 來源分支 -> 可見歷程注入，以及後續每次受監督的 Chat 互動 一般 OpenClaw Codex 工作階段 -> 預設為受管理的代理程式主目錄 stdio -> 一般完整控制框架對話串 -> OpenClaw Chat 與頻道傳遞 ``` 啟用監督不會變更一般 Codex 控制框架：其預設仍以代理程式為範圍。獨立的監督連線預設使用受管理的使用者主目錄 stdio，因此其目錄與快照作業可以看到原生已儲存的對話串。明確的 `appServer` 連線設定會受到尊重。當 `homeScope` 未設定時，監督連線會將 stdio 或 Unix 的範圍解析為 `"user"`，將 WebSocket 的範圍解析為 `"agent"`。只有在一般控制框架也應共用原生 Codex 主目錄時，才明確設定 `appServer.homeScope: "user"`。從 Codex 側邊欄群組採用的 Chat 是例外：其私有監督繫結會讓來源讀取、標準分支建立及後續互動維持在監督連線上。即時狀態與擁有權仍侷限於處理程序本機；OpenClaw 監督處理程序不認識的對話串即為 `notLoaded`，即使 Codex Desktop 正在執行該對話串亦然。 Codex 有一個實驗性的標準本機常駐程式，具備獨立的安裝程式管理啟動合約。此功能不得隱含啟動、宣稱擁有或假設該常駐程式存在。 ## 目錄流程 通用閘道方法 `sessions.catalog.list` 會分派至 `codex` 目錄提供者，後者一律要求 `archived: false`，以及互動式 `cli` 和 `vscode` 來源種類。它會合併： 1. 來自監督 App Server 的閘道本機 `thread/list` 結果；預設使用受管理的使用者主目錄 stdio。 2. 來自每個已連線且已選擇加入之節點的 `codex.appServer.threads.list.v1` 結果。 逐字記錄選取會在本機使用具有 `itemsView: "full"` 的 `thread/turns/list`，或在所選節點上使用具版本的 `codex.appServer.thread.turns.list.v1` 命令。每個回應最多包含 20 個已保存的互動，以及不透明的向前／向後游標。Control UI 會要求最新項目優先的頁面、按時間順序呈現每一頁，並將較舊頁面加到前面。它絕不會退回使用無界的 `thread/read`。OpenClaw 也會拒絕任何超過 20 MiB 的序列化項目頁面，避免其跨越節點或閘道傳輸。 原生 macOS 配對節點實作僅支援未設定／預設或明確的 `appServer.transport: "stdio"`，搭配未設定／預設的監督範圍或明確的 `appServer.homeScope: "user"`。它會將設定的 `command`、`args` 與正規化後的 `clearEnv` 傳入子處理程序。使用 `"unix"`、`"websocket"` 或明確的 `homeScope: "agent"` 時，它既不會公告目錄能力，也不會公告命令；直接叫用也會採取失敗關閉。它絕不能在代理程式範圍的設定下公開使用者 Codex 主目錄，也不能以本機 stdio 取代明確指定的端點。 目錄投影會正規化識別碼、標題、cwd、狀態、使用中的等待旗標、時間戳記、來源、模型提供者、Codex 版本與 Git 分支。它不會傳回逐字記錄預覽、互動、rollout 路徑、Codex 主目錄路徑、Git 遠端、提交 SHA、原始端點或原始 App Server 錯誤。逐字記錄回應只包含明確要求的 App Server 項目頁面及其不透明游標。 主機失敗會侷限於各自的主機結果。離線節點或無法使用的本機 App Server 不會從頁面上移除健康的主機。連線能力是主機屬性，而不是對話串狀態：失敗的主機結果不包含新的工作階段資料列，也不會將 `offline` 投影到原生對話串。 目錄探索是被動的。列出或讀取中繼資料時，不得呼叫 `thread/resume`、讓 OpenClaw 用戶端訂閱即時對話串要求，或回應核准要求。 搜尋僅比對標題，且不區分大小寫。對於每個傳回的目錄頁面，閘道與配對的 Mac 會掃描有限數量的原生頁面，而不將查詢傳給 App Server，因為原生搜尋也可能比對逐字記錄預覽。傳回的原生游標可讓呼叫端繼續掃描。 ## 操作者命令列介面邊界 此外掛會註冊三個由閘道支援的 shell 命令： ```text openclaw codex sessions [--search ] [--host ] [--limit ] [--cursor ] [--json] [gateway-options] openclaw codex continue [--json] [gateway-options] openclaw codex archive --confirm-no-other-runner [--json] [gateway-options] ``` `[gateway-options]` 是 `--url `、`--token `、`--timeout `，以及繼承的 `--expect-final` 開關。工作階段列出的預設逾時為 75,000 ms；繼續與封存的預設逾時為 30,000 ms；`--expect-final` 對這些一元 RPC 沒有額外作用。工作階段搜尋僅比對標題，且不區分大小寫；每個回應都會掃描有限的原生頁面鏈，而 `--cursor` 會繼續取得較舊的結果。每台主機的限制預設為 50，接受範圍為 1 到 100；使用游標時，必須指定一個穩定的 `--host` 目的地。所有命令均不接受 archived/include-archived 選項。只有 `sessions` 可以指定配對主機；`continue` 與 `archive` 一律傳送 `hostId: "gateway:local"`，而封存需要明確的確認旗標。 shell 命名空間不是 Chat 內的 `/codex` 執行階段命名空間。具體而言，`/codex sessions --host ` 會列出一個節點上的 Codex 命令列介面工作階段檔案、`/codex threads` 會列出目前對話連線的 App Server 對話串，而 `/codex resume` 或 `/codex bind` 會變更該對話的繫結。這些命令不會取代 `sessions.catalog.continue`，且不存在 `/codex continue` 或 `/codex archive` 執行階段命令。 ## 本機繼續 對於已儲存或閘道本機的閒置資料列，UI 會使用 `catalogId: "codex"` 加上主機和對話串識別碼，呼叫 `sessions.catalog.continue`。此外掛會： 1. 當來源已有受監督的 Chat 時，重複使用該 Chat。 2. 否則，將有界的使用者與助理歷程投影到新的 OpenClaw Chat，範圍涵蓋來源最後一個終止的已保存互動（已完成、中斷或失敗），並記錄待處理的控制框架分支。 3. 儲存待處理的僅限 Codex 模型鎖定政策，而非具體模型或提供者選擇，加上私有監督連線範圍，並傳回 OpenClaw `sessionKey`。 歷程投影會選取可見使用者與助理訊息的最新尾端，硬性限制為 200 則訊息、總計 512 KiB 的 UTF-8 文字，以及每則訊息 64 KiB。它會以 `[Image attachment]` 取代圖片與本機圖片輸入，絕不複製圖片承載資料或路徑，並省略推理、工具呼叫與工具結果。 UI 會使用該工作階段金鑰導向一般 Chat。此時尚不存在標準控制框架對話串。在第一次一般 Chat 互動時，控制框架會安裝真正的 Codex 核准、引導提問、事件與傳遞處理常式，接著： 1. 使用監督連線呼叫原生 `thread/fork`，不覆寫模型或提供者，並固定已保存的來源快照。Codex 目前的 `ConfigManager` 狀態會選取模型與提供者，而分支回應會回報實際配對。如果模型與來源中最後記錄的模型不同，Codex 會發出其一般的模型差異警告。 2. 在同一個連線上，以 `threadSource: "appServer"`、OpenClaw 的 cwd、政策、設定、環境、完整 OpenClaw 控制框架工具介面，以及分支針對這次初始啟動所傳回的確切模型與提供者，啟動標準的完整 Codex 控制框架對話串。 3. 透過該連線注入有界的可見使用者與助理歷程，在不捨棄監督範圍的情況下提交標準繫結、執行互動，並封存暫時分支。 第一次互動前，Chat 是具有可見歷程鏡像的鎖定待處理分支；之後，每次模型互動都會透過監督連線上的標準 Codex 控制框架對話串執行。此分支並非完整的原生 rollout 複本：來源推理、工具呼叫與工具結果會刻意省略。如果快照固定或標準對話串建立失敗，待處理分支仍可重試。若發生繫結競爭、監督已停用，或監督連線無法使用或不相符，系統會在互動執行前採取失敗關閉，而不會退回使用一般的代理程式主目錄控制框架。 這可保證由 Codex 選取，而不是保留來源的歷史模型。分支傳回的配對會用於標準對話串啟動，而 Codex 會保存該對話串的原生模型與提供者。後續繼續時會省略 OpenClaw 模型與提供者覆寫，因此 Codex 會還原已保存的配對。如果另一個原生 Codex 控制項變更標準對話串，OpenClaw 會接受該原生保存的選擇。外層 OpenClaw 模型與備援鏈絕不會取代它。 模型變更、工作階段刪除，以及工作階段重設／新增操作，對受監督且鎖定模型的聊天一律採取失敗關閉。修改 `/codex model `、`/codex bind`、`/codex resume`（包括節點的 `--bind here`），以及 `/codex detach` 或 `/codex unbind` 也會失敗關閉，因為這些操作會取代或清除繫結。`/codex model` 查詢以及 `/codex fast`、`/codex permissions` 和 `/codex threads` 仍可使用。`codex_threads` 代理程式工具無法附加新的分支，也無法封存已繫結的原生執行緒。清單和僅限中繼資料的讀取仍可使用；逐字記錄欄位需要 `supervision.allowRawTranscripts`，而重新命名、取消封存、建立已分離分支，以及封存不相關執行緒，則需要 `supervision.allowWriteControls`。這兩個選項都無法取代鎖定的繫結。刪除或重設 OpenClaw 項目，原本會捨棄原生繫結，並在看似 Codex 的工作階段背後建立或允許一般執行緒。因此，保留維護作業會保留鎖定模型的項目，即使它們超過一般的存留時間、數量或磁碟預算限制。停用或解除安裝擁有該項目的外掛時，也會保留鎖定和外掛擁有權標記。聊天會持續無法使用並採取失敗關閉，直到重新啟用同一個外掛；清理作業絕不會將它轉換成一般模型工作階段。 此動作絕不會恢復或修改來源。暫時分支會固定一份快照；它不是持久的接續執行緒。在第一輪啟動不同的標準控管器執行緒，可防止 OpenClaw 僅因程序區域狀態未偵測到由 Desktop 擁有的回合，就成為相互競爭的來源寫入者。可見歷程鏡像和固定快照可能會省略作用中來源裡尚未完成的工作。原始命令列介面或 VS Code 來源仍符合原生和 OpenClaw 目錄的收錄資格。標準分支在監督儲存區中仍是原生 Codex 執行緒，但原生用戶端可能會篩除其 `appServer` 來源種類，因此不保證能在 Codex Desktop 中看見。 ## 封存行為 對於已儲存或閒置的閘道本機資料列，使用 `catalogId: "codex"` 呼叫 `sessions.catalog.archive` 時，需要明確設定 `confirmNoOtherRunner: true`、重新讀取目前的程序區域狀態、僅在狀態為 `idle` 或 `notLoaded` 時繼續、呼叫原生 `thread/archive`，而且只有在 Codex 接受操作後才會傳回成功。之後，該資料列會離開未封存目錄。 重新讀取後若狀態為作用中或錯誤，封存會遭到拒絕。來源若有正在初始化或待處理的受監督分支，也會遭到拒絕：第一個聊天回合必須先具體建立其標準分支，之後才能封存來源。若已知有作用中的 OpenClaw 繫結擁有者正好對應目標，或存在任何尚未封存的衍生後代，也會拒絕封存。OpenClaw 會分頁查詢 Codex 的實驗性 `thread/list ancestorThreadId` 關係，並在請求或回應錯誤、游標或執行緒循環，以及用盡安全限制時採取失敗關閉。原生封存可能會關閉已載入的父項和後代工作，因此封存不是中斷捷徑。讀取、列舉後代和封存呼叫並非不可分割。獨立用戶端仍可能擁有看似閒置或在本機顯示為 `notLoaded` 的資料列，或在該資料列上啟動工作。在 Codex 提供條件式封存或跨程序租約之前，無其他執行者確認涵蓋未知用戶端及此競爭條件。禁止封存已配對節點。 Codex 目錄中沒有已封存檢視。在另一個經擁有者授權的 Codex 介面中，透過 `thread/unarchive` 還原的執行緒，會再次符合未封存目錄的收錄資格。 ## 作用中執行緒安全性 Codex 會在同一個 App Server 的用戶端之間，依序處理某個執行緒的修改，但不會公開排他的跨程序執行者租約或核准擁有者租約。各自獨立的 stdio App Server 可以附加至同一個推出項目，但每個伺服器只能看見自身的記憶體內狀態。核准請求也能送達同一伺服器的每個訂閱者，並由第一個有效回應完成該請求。 因此： - 被動目錄用戶端不會訂閱核准，也不會自動拒絕核准 - 目前回報為作用中的資料列既不會公開新分支，也不會公開封存 - 未對應的來源會成為可見歷程分支，而其標準控管器執行緒絕不會恢復來源 - `notLoaded` 會顯示為活動狀態不明，而且只有在知情確認沒有其他執行者後才能封存 - 本機封存需要該項確認，並重新讀取到 `idle` 或 `notLoaded`，同時承認讀取與封存之間存在通訊協定競爭條件 中斷和多用戶端交接是未來的產品決策。顯示作用中的資料列並不代表支援這些功能。 ## 已配對節點邊界 節點叫用目前僅支援請求／回應。它可以安全傳回有界限的目錄中繼資料和逐字記錄回合頁面，但無法承載 Codex 控管器執行所需的長時間事件串流、核准請求、工具呼叫、取消和助理增量內容。 因此，節點合約支援清單和逐字記錄回合頁面。遠端資料列仍可讀取，但無論是否處於閒置狀態，都無法使用**繼續**和**封存**。真正的遠端接續需要節點端執行者和串流橋接器，並維持與本機控管器相同的核准與繫結不變條件。 ## 權限 每台電腦都在本機自行選擇加入。啟用閘道並不會授權其他節點讀取其 Codex 中繼資料。節點功能必須通過一般配對和命令原則核准。 機群清單和逐字記錄檢視會使用 `operator.write` 閘道範圍，因為它們會叫用已配對節點。本機接續和封存是經驗證的操作員動作，仍受主機和狀態檢查限制。 自主代理程式和獨立 MCP 存取是另一回事。已發布的 `codex_endpoint_probe`、`codex_sessions_list`、`codex_session_read`、`codex_session_send` 和 `codex_session_interrupt` 工具合約仍由 `codex` 外掛擁有。啟用監督時，原始 `codex_threads` 逐字記錄讀取和衍生自逐字記錄的清單欄位也需要 `supervision.allowRawTranscripts`；每個 `codex_threads` 分支、重新命名、封存或取消封存操作都需要 `supervision.allowWriteControls`。這兩項原則預設皆為停用。 ## 相容性 `openclaw doctor --fix` 會遷移已發布的 `plugins.entries.codex-supervisor` 設定，包括端點、逐字記錄／寫入原則，以及外掛允許／拒絕參照，並將它們移至 `plugins.entries.codex.config.supervision`。發生衝突時，明確的標準目的地值優先。遷移後，執行階段程式碼僅使用標準的 `codex` 外掛結構。 官方外掛恰好保留五個 Supervisor 相容性工具： `codex_endpoint_probe`、`codex_sessions_list`、`codex_session_read`、 `codex_session_send` 和 `codex_session_interrupt`。工作階段清單預設僅包含已載入項目；沒有 `loaded_only` 參數。`include_stored: true` 會加入未封存的狀態資料庫資料列，每個端點受 `max_stored_sessions` 限制（預設為 200，可接受範圍為 1 至 1,000）；已載入資料列不受該設定限制。衍生自逐字記錄的欄位和讀取仍受 `allowRawTranscripts` 管制；傳送和中斷仍受 `allowWriteControls` 管制。 相容性傳送絕不會啟動或恢復閒置執行緒。`mode: "start"` 一律遭到拒絕；`"auto"` 和 `"steer"` 只會引導可讀取的作用中回合。同樣地，中斷也需要可讀取的作用中回合。閒置接續會路由至原生 Codex 目錄，讓完整控管器擁有核准、工具和繫結。獨立的舊版 MCP 轉接器會從官方外掛解析相同工具，而且只有此路徑會遵循保留的舊版原則環境變數。 7 月的目錄使用者介面、閘道方法、節點功能和命令列介面註冊，尚未以舊外掛 ID 發布。它們會直接移交給 `codex` 擁有，不會加入第二個執行階段外觀介面。 ## 未來工作 - 用於遠端接續的節點端串流執行者和事件橋接器 - 用於同時進行用戶端交接的明確執行者租約和核准擁有者租約 - 在具備執行者擁有權租約或同等防護機制後支援遠端封存 - 中斷和更豐富的作用中工作階段觀察 - Codex Desktop、命令列介面和 OpenClaw 之間經稽核的交接 已封存瀏覽不屬於規劃中的監督側邊欄。原生 Codex 介面仍是已封存執行緒的復原路徑。 ## 驗收測試 - 啟用監督後會列出未封存的本機工作階段。 - 已封存的工作階段絕不會出現在目錄回應或使用者介面中。 - 當另一台主機失敗時，健康的主機仍保持可見；無法使用的主機不會虛構離線工作階段狀態，而是不傳回任何新資料列。 - 已儲存或閒置的本機資料列會建立具有僅限 Codex 模型／執行階段鎖定的聊天鏡像；第一個回合會固定暫時快照並啟動標準完整控管器執行緒，而重複選擇「繼續」會開啟現有聊天。 - 第一個回合會在快照分支上省略模型／提供者覆寫，並將標準啟動固定為 Codex 傳回的確切配對，即使 Codex 警告其目前模型與來源上次記錄的模型不同。 - 待處理和已提交的受監督繫結，會使用監督連線進行來源存取、建立標準分支和執行之後的每個回合；一般 Codex 工作階段仍限定於代理程式範圍。 - 後續恢復會省略 OpenClaw 模型／提供者覆寫、保留 Codex 的標準持久化選擇、接受該執行緒上獨立進行的原生變更，而且絕不會改用外層 OpenClaw 模型或備援鏈。 - 停用監督或失去繫結／連線生命週期時會採取失敗關閉，而不是將聊天移至一般的代理程式主目錄控管器。 - 受監督且鎖定模型的聊天在保護原生繫結期間無法刪除。 - 聊天最多鏡像 200 則使用者和助理訊息，總計 512 KiB，每則訊息最多 64 KiB。圖片會變成預留位置；來源推理、工具呼叫、工具結果、圖片承載資料和本機路徑不會被複製。 - 分支流程絕不會恢復來源執行緒。 - 原始來源仍符合兩個目錄的收錄資格。標準原生分支使用 `appServer` 來源種類，不保證會出現在 Codex Desktop 中。 - 作用中的本機來源無法建立分支或封存；現有的受監督聊天仍可開啟。 - 活動狀態不明的資料列可以在不確認的情況下建立分支；封存則需要明確確認沒有其他執行者。 - 來源若有正在初始化或待處理的受監督分支，在第一個聊天回合具體建立標準分支之前無法封存。 - 若已知有作用中的繫結擁有者正好對應目標，或存在任何尚未封存的衍生後代，封存會遭到阻擋；列舉後代失敗時會採取失敗關閉，而明確確認仍須負責處理未知用戶端以及從狀態讀取到封存之間的競爭條件。 - 經確認的已儲存或閒置本機封存會在原生操作成功後移除資料列。 - 已配對節點資料列仍保持可見，但不提供「繼續」或「封存」。 - 被動列出項目時，絕不會訂閱或回應執行緒核准。 - 舊版 Supervisor 設定會遷移至標準 Codex 設定結構。 - 舊版清單預設僅包含已載入項目，已儲存項目的列舉會遵守每個端點的上限，而相容性傳送絕不會啟動或恢復閒置執行緒。