> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # Codex 監督 # Codex 監督 ## 目標 Codex 監督讓 OpenClaw 操作者能探索原生 Codex 工作階段，並在安全的情況下，透過一般的 OpenClaw 聊天介面建立本機分支。Codex App Server 仍是執行緒與模型迴圈的擁有者。OpenClaw 提供機群目錄、經過驗證的操作者使用者介面、工作階段繫結與頻道傳遞。 此功能屬於官方 `codex` 外掛。沒有獨立的 Supervisor 外掛或第二套 Codex 通訊協定實作。 ## 產品邊界 只要 Codex 外掛處於啟用狀態，目錄就會註冊，除非使用下列設定明確停用原生工作階段探索： ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} plugins.entries.codex.config.sessionCatalog.enabled = false ``` 使用下列設定啟用代理程式可用的監督工具： ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 用戶端。 預設的本機拓撲如下： ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 命令： ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} 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` 目的地。任何命令都不接受已封存／包含已封存選項。只有 `sessions` 可以指定配對主機；`continue` 與 `archive` 一律傳送 `hostId: "gateway:local"`，且封存需要明確的確認旗標。 Shell 命名空間不是聊天內的 `/codex` 執行階段命名空間。具體而言，`/codex sessions --host ` 會列出一個節點上的 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 `、`/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 設定格式。 * 舊版清單預設僅會載入，已儲存項目的列舉會遵守各端點的 上限，且相容性傳送絕不會啟動或繼續執行閒置的執行緒。