Codex 監督

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 的模型與工具框架

Control UI 與閘道使用該外掛所擁有的服務。它們不會直接讀取 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 側邊欄群組接管的聊天是例外：其私有監督繫結會讓來源讀取、標準分支建立與後續回合持續使用監督連線。即時狀態與擁有權仍限於程序本機；OpenClaw 監督程序未知的執行緒會是 notLoaded，即使 Codex Desktop 正在主動執行該執行緒亦然。

Codex 有一個實驗性的標準本機常駐程式，具備獨立、由安裝程式管理的啟動合約。此功能不得隱含地啟動、宣稱擁有或假設該常駐程式存在。

目錄流程

通用閘道方法 sessions.catalog.list 會分派至 codex 目錄提供者；該提供者一律請求 archived: false，並讓 App Server 套用其互動式來源預設值：cli、vscode、Atlas 與 ChatGPT。它會合併：

1. 來自監督 App Server 的閘道本機 thread/list 結果；該伺服器預設使用受管理的使用者主目錄 stdio。
2. 來自每個已連線且選擇加入之節點的 codex.appServer.threads.list.v1 結果。

逐字記錄選取在本機使用 thread/turns/list 搭配 itemsView: "full"，或在所選節點上使用有版本控管的 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 分支。它不會傳回逐字記錄預覽、回合、推出路徑、Codex 主目錄路徑、Git 遠端、提交 SHA、原始端點或原始 App Server 錯誤。逐字記錄回應僅包含明確請求的 App Server 項目頁面及其不透明游標。

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

Control UI 會請求漸進式目錄更新。每個本機或配對主機會在其自身的 App Server 清單完成後出現；彙總回應仍作為相容性與復原快照。可見頁面會在連線狀態變更後、取得焦點時，以及至多每 30 秒進行一次調和，並在變更後加快執行。因此，在其他用戶端建立的原生 Codex 工作階段最終會被探索到，而無須匯入 OpenClaw 儲存空間。

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

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

操作者命令列介面邊界

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

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 目的地。任何命令都不接受已封存／包含已封存選項。只有 sessions 可以指定配對主機；continue 與 archive 一律傳送 hostId: "gateway:local"，且封存需要明確的確認旗標。

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

本機繼續

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

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

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

使用者介面會使用該工作階段金鑰導向一般聊天。此時尚不存在標準工具框架執行緒。在第一個一般聊天回合中，工具框架會安裝真正的 Codex 核准、引導提問、事件與傳遞處理常式，然後：

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

在第一次對話輪次之前，Chat 是一個鎖定的待處理分支，並具有可見的 歷史記錄鏡像；此後，每個模型輪次都會透過監督連線上的標準 Codex 控制框架執行緒執行。此分支不是完整的原生 推出複本：來源推理、工具呼叫及工具結果會刻意 省略。若快照固定或標準執行緒建立失敗，待處理 分支仍可重試。繫結競爭、停用監督，或監督連線 無法使用或不相符時，會在輪次執行前採取失敗關閉， 而不會退回一般的 agent-home 控制框架。

這可確保選擇由 Codex 掌控，而非保留來源的 歷史模型。分支所傳回的配對會用於啟動標準執行緒， 且 Codex 會保存該執行緒的原生模型與提供者。後續恢復時 會省略 OpenClaw 模型與提供者覆寫，因此 Codex 會還原已保存的配對。 若另一個原生 Codex 控制項變更標準執行緒，OpenClaw 會接受 該原生保存的選擇。外層 OpenClaw 模型與備援鏈 絕不會取代它。

對於受監督且模型鎖定的 Chat，模型變更、工作階段刪除，以及工作階段重設／新增操作 都會採取失敗關閉。 變更 /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 的工作階段後方建立或允許一般執行緒。 因此，保留維護會保存模型鎖定的項目，即使它們 超過一般的存留時間、數量或磁碟預算限制。停用或解除安裝 擁有該項目的外掛，也會保留鎖定與外掛擁有權標記。Chat 會維持 無法使用並採取失敗關閉，直到再次啟用同一外掛；清理作業絕不會 將其轉換成一般模型工作階段。

此動作絕不會恢復或變更來源。暫時分支會固定 快照；它不是持久的接續執行緒。在第一次輪次啟動獨立的 標準控制框架執行緒，可避免 OpenClaw 僅因程序本機狀態未能看到 由 Desktop 掌控的輪次，就成為競爭性的來源寫入者。可見歷史記錄鏡像與固定快照可能會省略 使用中來源內尚未完成的工作。原始命令列介面、VS Code、 Atlas 或 ChatGPT 來源仍可同時列入原生與 OpenClaw 目錄。 標準分支在監督儲存區中仍是原生 Codex 執行緒， 但原生用戶端可能會篩選其 appServer 來源種類，因此 Codex Desktop 可見性並非合約保證。

封存行為

對於已儲存或閒置的閘道本機資料列，搭配 catalogId: "codex" 的 sessions.catalog.archive 需要 明確的 confirmNoOtherRunner: true，並會重新讀取目前程序本機 狀態，僅在狀態為 idle 或 notLoaded 時繼續、呼叫原生 thread/archive， 且只在 Codex 接受操作後才傳回成功。之後該資料列會離開 未封存目錄。

重新讀取所得的使用中或錯誤狀態會拒絕封存。來源中 正在初始化或待處理的受監督分支亦然：第一次 Chat 輪次 必須先具體化其標準分支，才能封存來源。若確切目標存在 已知使用中的 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 月的目錄 UI、閘道方法、節點能力及命令列介面註冊 尚未以舊外掛 ID 發布。它們會直接移轉至 codex 擁有， 不會建立第二個執行階段外觀層。

未來工作

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

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

驗收測試

• 啟用監督功能後，會列出未封存的本機工作階段。
• 已封存的工作階段絕不會出現在目錄回應或 UI 中。
• 當另一部主機發生故障時，健康的主機仍會保持可見；無法使用的主機 不會虛構離線工作階段狀態，而是不傳回任何新資料列。
• 已儲存或閒置的本機資料列會建立一個僅鎖定 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 設定格式。
• 舊版清單預設僅會載入，已儲存項目的列舉會遵守各端點的 上限，且相容性傳送絕不會啟動或繼續執行閒置的執行緒。