Codex 監督

目標

Codex 監督讓 OpenClaw 操作者能探索原生 Codex 工作階段，並在安全時，透過一般的 OpenClaw 聊天介面建立本機分支。Codex App Server 仍是執行緒與模型迴圈的擁有者。OpenClaw 提供機群目錄、已驗證的操作者介面、工作階段繫結，以及頻道傳遞。

此功能屬於官方 codex 外掛。沒有獨立的 Supervisor 外掛，也沒有第二套 Codex 通訊協定實作。

產品邊界

只要 Codex 外掛處於啟用狀態，目錄就會註冊，除非使用以下設定明確停用原生工作階段探索：

plugins.entries.codex.config.sessionCatalog.enabled = false

使用以下設定啟用面向代理程式的監督工具：

plugins.entries.codex.config.supervision.enabled = true

目前啟用的初始產品範圍刻意小於長期機群計畫：

• 僅列出未封存的 Codex 執行緒。
• 依穩定的主機身分，將本機與已選擇加入的配對節點資料列分組。
• 從已儲存或閒置的閘道本機執行緒建立一般且鎖定模型的聊天分支、在第一次互動時啟動其完整的 Codex 控制框架執行緒，或開啟先前分支所建立的聊天。
• 只有在明確確認沒有其他執行器後，才封存已儲存或閒置的閘道本機執行緒。
• 顯示使用中的本機來源，但不提供建立新分支或封存控制項，同時仍允許開啟現有的受監督聊天。
• 在主側邊欄顯示每部主機最新的資料列、在工作階段頁面保留完整目錄，並為本機與配對節點資料列提供有界限、以游標分頁的逐字記錄讀取。
• 依主機隔離目錄故障。

目錄是未封存項目的集合。其中的資料列仍可具有閒置、使用中、notLoaded 或錯誤的互動狀態。

面向代理程式的監督功能仍須選擇加入。引導式上手流程會在原生 Codex 安裝偵測成功，且所選推論後端通過即時檢查後，嘗試安裝並啟用此功能，而不受使用者選擇哪個主要後端影響。只有在這項機會性外掛設定成功時，監督功能才會啟用。明確停用的外掛、政策封鎖或 supervision.enabled: false 對監督工具仍具有最高決定權，但不會停用操作者工作階段目錄。sessionCatalog.enabled: false 會停用操作者探索與配對節點目錄命令；Codex 提供者與控制框架仍保持啟用。

擁有權

codex 外掛擁有所有 Codex App Server 行為：

• 端點探索與連線生命週期
• 通訊協定初始化與版本檢查
• 執行緒列出、讀取、繼續、封存及事件處理
• 核准與使用者輸入橋接
• 原生執行緒與 OpenClaw 工作階段的繫結
• 繼續後強制執行僅限 Codex 的模型與控制框架

控制介面與閘道會使用此外掛擁有的服務。它們不會直接讀取 Codex 推出檔案，也不會實作另一個 App Server 用戶端。

預設的本機拓撲為：

Codex Desktop -> 私有 stdio App Server -> 使用者 Codex 主目錄                                             ^OpenClaw Codex 外掛 -> 監督 App Server 連線  （預設為受管理的使用者主目錄 stdio；明確的 appServer 設定會受到遵循）  -> 被動來源目錄與讀取  -> 快照固定 -> 標準 appServer 來源分支  -> 可見歷程注入及之後的每次受監督聊天互動 一般 OpenClaw Codex 工作階段 -> 預設為受管理的代理程式主目錄 stdio  -> 一般完整控制框架執行緒 -> OpenClaw 聊天與頻道傳遞

啟用監督功能不會改變一般 Codex 控制框架：預設仍以代理程式為範圍。獨立的監督連線預設使用受管理的使用者主目錄 stdio，因此其目錄與快照操作可以看見原生儲存的執行緒。明確的 appServer 連線設定會受到遵循。當 homeScope 未設定時，監督連線會將其解析為 stdio 或 Unix 的 "user"，以及 WebSocket 的 "agent"。只有當一般控制框架也應共用原生 Codex 主目錄時，才明確設定 appServer.homeScope: "user"。從 Codex 側邊欄群組接管的聊天是例外：其私有監督繫結會讓來源讀取、標準分支建立及之後的互動持續使用監督連線。即時狀態與擁有權仍限於處理程序本機；即使 Codex Desktop 正在主動執行某個執行緒，只要 OpenClaw 的監督處理程序不知道該執行緒，它就是 notLoaded。

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 次已持久化的互動，以及不透明的向前／向後游標。控制介面會要求由新到舊的頁面、按時間順序呈現每個頁面，並將較舊頁面前置。它絕不會退回使用無界限的 thread/read。OpenClaw 也會在任何序列化項目頁面跨越節點或閘道傳輸之前，拒絕超過 20 MiB 的頁面。

原生 macOS 配對節點實作僅支援未設定／預設或明確的 appServer.transport: "stdio"，並搭配未設定／預設的監督範圍或明確的 appServer.homeScope: "user"。它會將已設定的 command、args 及正規化的 clearEnv 傳入子處理程序。使用 "unix"、"websocket" 或明確的 homeScope: "agent" 時，它不會公布目錄能力或命令；直接叫用也會以封閉方式失敗。它絕不可為代理程式範圍設定公開使用者 Codex 主目錄，也不可用本機 stdio 取代明確端點。

目錄投影會正規化識別碼、標題、cwd、狀態、使用中等待旗標、時間戳記、來源、模型提供者、Codex 版本及 Git 分支。它不會傳回逐字記錄預覽、互動、推出路徑、Codex 主目錄路徑、Git 遠端、提交 SHA、原始端點或原始 App Server 錯誤。逐字記錄回應只包含明確要求的 App Server 項目頁面及其不透明游標。

主機故障只會影響各自的主機結果。離線節點或無法使用的本機 App Server 不會從頁面移除健康的主機。連線能力是主機屬性，而不是執行緒狀態：失敗的主機結果不包含新的工作階段資料列，也不會將 offline 投影至原生執行緒。

目錄探索是被動的。列出或讀取中繼資料時，不得呼叫 thread/resume、讓 OpenClaw 用戶端訂閱即時執行緒要求，或回應核准。

搜尋僅限標題，且不區分大小寫。對於每個傳回的目錄頁面，閘道與配對的 Mac 會掃描有界限數量的原生頁面，而不將查詢傳給 App Server，因為原生搜尋也可能比對到逐字記錄預覽。傳回的原生游標可讓呼叫端繼續掃描。

操作者命令列介面邊界

此外掛會註冊三個由閘道支援的殼層命令：

openclaw codex sessions [--search <text>] [--host <id>] [--limit <count>] [--cursor <cursor>] [--json] [gateway-options]openclaw codex continue <thread-id> [--json] [gateway-options]openclaw codex archive <thread-id> --confirm-no-other-runner [--json] [gateway-options]

[gateway-options] 是 --url <url>、--token <token>、--timeout <ms>，以及繼承的 --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"，而封存要求明確的確認旗標。

殼層命名空間不是聊天內的 /codex 執行階段命名空間。具體而言，/codex sessions --host <node> 會列出單一節點上的 Codex 命令列介面工作階段檔案，/codex threads 會列出目前對話連線的 App Server 執行緒，而 /codex resume 或 /codex bind 會變更該對話的繫結。這些命令不會取代 sessions.catalog.continue，而且不存在 /codex continue 或 /codex archive 執行階段命令。

本機繼續

對於已儲存或閒置的閘道本機資料列，介面會使用 catalogId: "codex" 加上主機與執行緒 ID 呼叫 sessions.catalog.continue。此外掛會：

1. 當來源已有受監督聊天時，重複使用該聊天。
2. 否則，將有界限的使用者與助理歷程，投影至來源最後一次已持久化的終止互動（已完成、已中斷或失敗），放入新的 OpenClaw 聊天，並記錄待處理的控制框架分支。
3. 儲存待處理且僅限 Codex 的模型鎖定政策，而不是具體模型或提供者選擇，並儲存私有監督連線範圍，然後傳回 OpenClaw sessionKey。

歷程投影會選取最新一段可見的使用者與助理訊息，硬性限制為 200 則訊息、UTF-8 文字總計 512 KiB，以及每則訊息 64 KiB。它會將圖片與本機圖片輸入取代為 [Image attachment]，絕不複製圖片承載資料或路徑，並省略推理、工具呼叫及工具結果。

介面會使用該工作階段金鑰導向一般聊天。此時尚不存在標準控制框架執行緒。在第一次一般聊天互動中，控制框架會安裝真正的 Codex 核准、引導輸入、事件及傳遞處理常式，然後：

1. 使用監督連線呼叫原生 thread/fork，不覆寫模型或提供者，並固定已持久化的來源快照。Codex 目前的 ConfigManager 狀態會選取模型與提供者，而分支回應會回報實際配對。如果模型與來源中最後記錄的模型不同，Codex 會發出一般的模型差異警告。
2. 在相同連線上，使用 threadSource: "appServer"、OpenClaw 的 cwd、政策、設定、環境、完整的 OpenClaw 控制框架工具介面，以及該分支為此次初始啟動傳回的確切模型與提供者，啟動標準的完整 Codex 控制框架執行緒。
3. 透過該連線注入有界限的可見使用者與助理歷程、提交標準繫結而不捨棄其監督範圍、執行互動，並封存暫時分支。

在第一次回合之前，聊天是一個鎖定的待處理分支，並具有可見的歷程鏡像；之後，每個模型回合都會透過監督連線上的標準 Codex 控制框架執行緒執行。此分支並非完整的原生執行過程複本：來源推理、工具呼叫和工具結果均刻意省略。若快照固定或標準執行緒建立失敗，待處理分支仍可重試。若發生繫結競爭、監督已停用，或監督連線無法使用或不相符，系統會在回合執行前採取封閉式失敗，而不會回退至一般的代理程式主目錄控制框架。

這可保證由 Codex 擁有選擇權，而非保留來源的歷史模型。分叉所傳回的配對會用於啟動標準執行緒，而 Codex 會持久保存該執行緒的原生模型和提供者。後續繼續執行時會省略 OpenClaw 模型和提供者覆寫，因此 Codex 會還原已持久保存的配對。若另一個原生 Codex 控制項變更了標準執行緒，OpenClaw 會接受該原生持久保存的選擇。外層 OpenClaw 模型和備援鏈永遠不會取代它。

對於受監督且模型已鎖定的聊天，模型變更、工作階段刪除，以及工作階段重設／新建操作都會採取封閉式失敗。變更 /codex model <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 可以附加至相同的執行過程，而每一個 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 月的目錄 UI、閘道方法、節點能力和命令列介面註冊，尚未以舊外掛 ID 發布。它們會直接移交給 codex 擁有，而不會加入第二個執行階段外觀層。

未來工作

• 用於遠端繼續執行的節點端串流執行者和事件橋接器
• 用於同步用戶端移交的明確執行者和核准擁有者租約
• 在執行者擁有權租約或同等隔離機制存在後提供遠端封存
• 中斷和更豐富的作用中工作階段觀察
• 在 Codex Desktop、命令列介面和 OpenClaw 之間進行經稽核的移交

封存瀏覽不屬於規劃中的監督側邊欄。原生 Codex 介面仍是封存執行緒的復原路徑。

驗收測試

• 啟用監督後，會列出未封存的本機工作階段。
• 已封存的工作階段絕不會出現在目錄回應或使用者介面中。
• 當另一部主機發生故障時，健康的主機仍維持可見；無法使用的主機 不會虛構離線工作階段狀態，而是不傳回任何新資料列。
• 已儲存或閒置的本機資料列會建立僅鎖定 Codex 模型／執行階段的 Chat 鏡像；第一輪會固定暫時快照並啟動 標準完整框架執行緒，而重複選擇 Continue 會開啟現有的 Chat。
• 第一輪在快照分支上省略模型／供應商覆寫，並將 標準啟動固定為 Codex 傳回的確切配對，即使 Codex 警告 其目前模型與來源最後記錄的模型不同。
• 待處理與已提交的受監督繫結會使用監督連線進行 來源存取、建立標準分支及後續每一輪；一般 Codex 工作階段仍限定於代理程式範圍。
• 後續恢復會省略 OpenClaw 模型／供應商覆寫、保留 Codex 已標準化保存的選擇、接受該執行緒個別的原生變更， 且絕不以外層 OpenClaw 模型或後援鏈取代。
• 停用監督或失去繫結／連線生命週期時，會採取封閉式失敗， 而不會將 Chat 移至一般代理程式主目錄框架。
• 受監督且模型鎖定的 Chat 在保護原生 繫結期間無法刪除。
• Chat 最多鏡像 200 則使用者與助理訊息，總計 512 KiB，且 每則訊息 64 KiB。圖片會變成預留位置；來源推理、工具呼叫、 工具結果、圖片承載資料及本機路徑不會被複製。
• 分支流程絕不會恢復來源執行緒。
• 原始來源仍符合兩種目錄的資格。標準原生 分支使用 appServer 來源種類，且不保證會出現在 Codex Desktop 中。
• 作用中的本機來源無法建立分支或封存；現有的 受監督 Chat 仍可開啟。
• 活動狀態未知的資料列可在不經確認的情況下建立分支；封存則需要 明確確認沒有其他執行器。
• 具有正在初始化或待處理之受監督分支的來源無法封存， 直到第一輪 Chat 將標準分支具體化。
• 若確切目標或任何未封存的衍生後代有已知的作用中繫結擁有者， 將阻止封存；後代列舉失敗時會採取封閉式失敗，而 明確確認仍需負責處理未知用戶端及 從狀態判定到封存之間的競爭狀況。
• 經確認的已儲存或閒置本機封存，會在原生操作成功後移除該資料列。
• 配對節點的資料列即使沒有 Continue 或 Archive 仍維持可見。
• 被動列出絕不會訂閱或回覆執行緒核准。
• 舊版 Supervisor 設定會移轉為標準 Codex 設定格式。
• 舊版清單預設僅載入，已儲存項目的列舉會遵守其各端點 上限，而相容性傳送絕不會啟動或恢復閒置執行緒。