Codex 监督¶
目标¶
Codex 监督允许 OpenClaw 操作员发现原生 Codex 会话, 创建 Gateway 本地分支,或通过常规 OpenClaw Chat 界面 继续符合条件的配对节点线程。 Codex App Server 仍然是线程和模型循环的所有者。OpenClaw 提供 集群目录、已认证的操作员 UI、会话绑定和通道投递。
该功能属于官方 codex 插件。没有单独的
Supervisor 插件或第二个 Codex 协议实现。
本规范使用以下阶段名称:
- Gateway 本地分支:OpenClaw 从已存储或空闲的本地 Codex 源创建的 新的受监督 Chat,而不是恢复该源线程。
- 待定 harness 分支:该分支在其第一个轮次之前,当有界 历史已被投影但尚不存在规范 Codex 线程时。
- Chat 镜像(可见历史镜像):投影到 Chat 中的可见用户和 助手消息的有界副本。
- 可见历史分支:未映射的 Gateway 本地源,仅承载 该镜像历史,因此其规范 harness 线程永不恢复源。
- 规范 appServer 源分支:插件在固定源快照后使用
threadSource: "appServer"创建的原生 Codex 线程。 - 规范完整 Codex harness 线程:该规范线程一旦使用 OpenClaw 的完整 harness 工具界面运行;之后每个模型轮次都在其上运行。
- 受监督的模型锁定 Chat:绑定到受监督线程的 OpenClaw Chat, 处于仅限 Codex 的模型和运行时锁下。
产品边界¶
只要 Codex 插件处于活动状态,目录就会注册,除非使用以下配置显式禁用原生会话发现:
使用以下配置启用面向代理的监督工具:
当前产品支持:
- 仅列出未归档的 Codex 线程。
- 按稳定的主机身份对本地和已选择加入的配对节点行进行分组。
- 从已存储或空闲的 Gateway 本地线程创建常规、模型锁定的 Chat 分支, 在第一个轮次启动其完整 Codex harness 线程,或打开为较早分支创建的 Chat。
- 当节点的目录和 CLI 恢复命令已通告且可调用,并且调用者具有
operator.admin时,通过模型锁定的 Chat 继续已存储或空闲的配对节点线程。 后续消息会在其节点上恢复该确切的原生线程,而不是创建下文所述的 Gateway 本地分支。 - 仅在明确确认没有其他运行器后,归档已存储或空闲的 Gateway 本地线程。
- 显示活动本地源,但不提供新建分支或归档控件,同时仍允许打开现有的受监督 Chat。
- 在主侧边栏中显示每个主机的最新行,在会话页面上保留完整目录, 并为本地和配对节点行提供有界的、游标分页的转录读取。
- 按主机隔离目录故障。
目录是未归档集合。其中的行仍可能具有空闲、活动、notLoaded 或错误轮次状态。
面向代理的监督仍为可选加入。引导式入门会在原生 Codex 安装检测成功且所选推理后端通过其实时检查后,
尝试安装并启用它,这与用户选择哪个主后端无关。
只有当该机会性插件设置成功时,监督才会激活。显式禁用的插件、策略阻止或
supervision.enabled: false 对监督工具仍具有权威性,但不会禁用操作员会话目录。
sessionCatalog.enabled: false 会禁用操作员发现和配对节点目录命令;
Codex 提供程序和 harness 保持活动。
所有权¶
codex 插件拥有所有 Codex App Server 行为:
- 端点发现和连接生命周期
- 协议初始化和版本检查
- 线程列表、读取、恢复、归档和事件处理
- 审批和用户输入桥接
- 原生线程到 OpenClaw 会话的绑定
- 继续后仅限 Codex 的模型和 harness 强制
Control UI 和 Gateway 消费该插件拥有的服务。它们不直接读取 Codex rollout 文件,也不实现另一个 App Server 客户端。
默认本地拓扑为:
Codex Desktop -> private stdio App Server -> user Codex home
^
OpenClaw Codex plugin -> supervision App Server connection
(defaults to managed user-home stdio; explicit appServer settings are honored)
-> passive source catalog and read
-> snapshot pin -> canonical appServer-source branch
-> visible-history injection and every later supervised Chat turn
Ordinary OpenClaw Codex sessions -> managed agent-home stdio by default
-> ordinary full harness threads -> OpenClaw Chat and channel delivery
启用监督不会改变常规 Codex harness:它默认仍为代理范围。
独立的监督连接默认使用受管理的用户主目录 stdio,因此其目录和快照操作可以看到原生存储线程。
显式的 appServer 连接设置会被遵循。当 homeScope 未设置时,
监督连接会将其解析为 stdio 或 Unix 的 "user",以及 WebSocket 的 "agent"。
仅当常规 harness 也应共享原生 Codex 主目录时,才显式设置
appServer.homeScope: "user"。从 Codex 侧边栏组采用的 Gateway 本地 Chat 是例外:
其私有监督绑定会将源读取、规范分支创建和后续轮次保留在监督连接上。
实时状态和所有权保持进程本地;对 OpenClaw 监督进程未知的线程即使
Codex Desktop 正在积极运行它,也是 notLoaded。
目录读取和固定源租约显式选择原生身份验证。 它们不会导入或替换 OpenClaw 身份验证存储或所选 Codex 主目录中的凭据。 这也适用于配置为代理主目录范围的主目录源:其物理主目录和连接指纹保持不变。 常规受管理推理保留其代理身份验证预检。
Codex 具有一个实验性的规范本地守护进程,并带有独立的由安装程序管理的引导契约。此功能不得隐式地引导、声明或假定该守护进程。
目录流程¶
通用 Gateway 方法 sessions.catalog.list 会分发到 codex 目录提供程序,该提供程序始终请求 archived: false,并让 App Server 应用其交互式来源默认值:cli、vscode、Atlas 和 ChatGPT。它组合了:
- 来自监督 App Server 的 Gateway 本地
thread/list结果,其默认使用受管理的用户主目录 stdio。 - 来自每个已连接且已选择加入的节点的
codex.appServer.threads.list.v1结果。
转录选择在本地使用带有 itemsView: "full" 的 thread/turns/list,或在所选节点上使用带版本的 codex.appServer.thread.turns.list.v1 命令。每个响应最多包含 20 个已持久化轮次,外加不透明的向前/向后游标。Control UI 请求最新优先的页面,按时间顺序渲染每个页面,并在前面插入较早的页面。它从不回退到无限制的 thread/read。OpenClaw 还会拒绝任何超过 20 MiB 的序列化项页面,使其无法跨越节点或 Gateway 传输。
原生 macOS 配对节点实现仅支持未设置/默认或显式 appServer.transport: "stdio",并且监督范围为未设置/默认或显式 appServer.homeScope: "user"。它将配置的 command、args 和规范化后的 clearEnv 带入子进程。对于 "unix"、"websocket" 或显式 homeScope: "agent",它既不宣告目录能力,也不宣告命令;直接调用也会失败关闭。对于代理作用域配置,它绝不能暴露用户 Codex 主目录,也不能用本地 stdio 替代显式端点。
无头节点目录默认使用节点原生的 CODEX_HOME 或 ~/.codex,独立于 Gateway 的路由代理和节点的代理名册。原生读取器保留配置的命令、参数和已清除的环境变量。目录读取和原生终端恢复使用与节点现有 CLI 会话列表和继续命令相同的主目录。
Gateway 仍会为已发布节点发送其可选代理 id:v2026.9.4 在相同命令名称下将其用作严格的本地来源选择器。更新后的原生读取器仅将该字段验证为无操作的路由上下文。显式的代理作用域和非 stdio 来源配置保留其随附的本地所有者选择,包括拒绝缺失或已移除的所有者。两条路径都不会静默替换为不同来源。仅通过带版本的节点来源契约以及针对这些已配置读取器的升级过渡来退役此兼容性。
目录投影会规范化标识符、标题、cwd、状态、活动等待标志、时间戳、来源、模型提供程序、Codex 版本和 Git 分支。它不返回转录预览、轮次、rollout 路径、Codex 主目录路径、Git 远程、提交 SHA、原始端点或原始 App Server 错误。转录响应仅包含明确请求的 App Server 项页面及其不透明游标。
主机故障保持为每个主机结果的本地属性。离线节点或不可用的本地 App Server 不会从页面中移除健康主机。连接性是主机属性,而不是线程状态:失败的主机结果不包含新的会话行,也不会将 offline 投影到原生线程上。
空目录不会创建侧边栏部分,即使它存在错误或继续游标。当健康的游标主机在当前所有者筛选器下没有可见行时,现有数据所有者会在每次刷新之间为每个目录推进一页。已接受的页面保留其游标和页面深度进度;后续遍历继续该搜索,而不是从同一第一页重新开始。发现过程在隐藏时暂停,并在错误或游标循环时停止推进。包含可见会话的目录在另一主机失败时仍然存在。
Control UI 请求渐进式目录更新。每个本地或配对主机在其自身 App Server 列表稳定后出现;聚合响应仍然是兼容性和恢复快照。可见页面在连接性变化后、获得焦点时以及最多每 30 秒进行一次协调,并在变化后进行更快的遍历。因此,在另一客户端中创建的原生 Codex 会话最终会被发现,而无需将它们导入 OpenClaw 存储。
目录发现是被动的。列出或读取元数据不得调用 thread/resume、将 OpenClaw 客户端订阅到实时线程请求,或响应审批。
搜索仅针对标题且不区分大小写。对于每个返回的目录页面,Gateway 和配对 Mac 会扫描有限数量的原生页面,而不会将查询传递给 App Server,因为原生搜索也可能匹配转录预览。返回的原生游标允许调用者继续扫描。
操作员 CLI 边界¶
该插件注册了三个由 Gateway 支持的 shell 命令:
openclaw codex sessions [--agent <id>] [--search <text>] [--host <id>] [--limit <count>] [--cursor <cursor>] [--json] [gateway-options]
openclaw codex continue <thread-id> [--agent <id>] [--host <id>] [--json] [gateway-options]
openclaw codex archive <thread-id> --confirm-no-other-runner [--agent <id>] [--host <id>] [--json] [gateway-options]
[gateway-options] 是 --url <url>、--token <token>、--timeout <ms> 以及继承的 --expect-final 开关。会话列表默认为 75,000 毫秒;continue 和 archive 默认为 30,000 毫秒;对于这些一元 RPC,--expect-final 没有额外效果。会话搜索仅针对标题且不区分大小写;每个响应扫描一条有界的原生页面链,并且 --cursor 继续较早的结果。限制默认每个主机为 50,接受 1 到 100,并且游标需要一个稳定的 --host 目标。没有任何命令接受 archived/include-archived 选项。三个命令都接受 --agent <id> 和 --host <id>。continue 和 archive 默认为 gateway:local;列表中不透明的本地主机 id 会选择另一个本地存储。shell 命令仅请求 operator.write,因此向 continue 传递节点主机本身并不满足配对节点提供程序的 operator.admin 要求。除非 Gateway 单独将该范围授予已认证身份,否则会被拒绝。推荐的配对节点继续界面是下文描述的经管理员授权的 Control UI 路径。Archive 保持为 Gateway 本地,并且需要显式确认标志。
Shell 命名空间不是聊天内 /codex 运行时命名空间。具体而言,/codex sessions --host <node> 列出某个节点上的 Codex CLI 会话文件,/codex threads 列出当前会话连接对应的 App Server 线程,而 /codex resume 或 /codex bind 会修改该会话的绑定。这些命令不会替代 sessions.catalog.continue,也不存在 /codex continue 或 /codex archive 运行时命令。
规范消息分叉¶
消息切分路由会在读取原始来源之前,对选中的本地用户行进行分类。原始导入来源仍然要求该来源的精确切分。规范来源会针对当前私有绑定的原生线程进行检查,独立于原始来源是否可用。重复文本不能标识一个回合:原生回合/项目标识以及保留的镜像证明才能做到。只有显式由主机记录的已阻止用户输入,才可以从已交付输入匹配中排除。
当 Gateway 已经持久化当前用户回合时,原生接受会通过主机能力对该确切的记录器拥有事件进行标注。插件只提供已有的原生来源字段;主机会在锚定写入事务内再次验证实时操作实例、记录器、会话/写入者声明、活动锚点以及未变更内容。相同来源是空操作;冲突、删节不匹配、已确认转向以及已撤销所有者会失败关闭。标注使用普通的转录生成失效,并在发布前刷新同一记录器准入。它绝不会为较早的未标注规范行建立来源。这样的前缀需要一个新的原始来源分支,而不是推断映射或历史修复。
规范创建使用主机的 SessionInitialization 生命周期。其狭窄的原生工具策略检查会固定子身份、来源修订、注册表和配置,而不会构造工具、为请求方配置 MCP 资源,或注册实时钩子。原生来源拥有其不可变声明。经过身份检查且有界的 SessionMeta.dynamic_tools 必须与全新子项的实际元数据匹配,其中仅省略的 deferLoading: false 会根据原生 serde 进行规范化。来源绑定摘要会检测其自身元数据的漂移;子指纹从已验证的子数据和当前子配置计算得出。
恢复的受监督回合会保留这些原生声明。当前由主机拥有的执行器、审批和钩子仍保持独立围栏,不可用调用会报告 executionStarted: false。现有物理客户端拥有一个仅包含数据的有界元数据缓存;关闭或线程退役会将其丢弃。不存在并行持久化目录或保留的执行器。配置、执行环境、MCP 和原生策略更改仍会通过其现有生命周期检查,外部/手动采用保持不变。
只读发布适配器会观察最新的持久化模型/提供方对:匹配的会话元数据会设置提供方,设置已应用事件会设置两者,回合上下文会设置模型。回滚不会重置这些标量设置。精确的普通文件优先于其 .zst 同级文件。描述符/根身份以及大小/时间戳会被验证;符号链接、硬链接、替换、格式错误记录和预算耗尽会失败关闭。界限为 64 KiB 读取、1 MiB 记录、256 字节标量、8 MiB 向后扫描和五秒。压缩输入限制为 8 MiB,输出/窗口限制为 32 MiB。这是一个已验证快照,而不是实时内存选择或元数据缓存。
子项使用带有 beforeTurnId 和所观察对的直接 thread/fork,然后进行精确切分读回。它从不导入投影历史,也从不重新注入继承的前缀。确定性子配置共享开始/恢复渲染器;全新的钩子中继代际具有静态命令,但没有实时注册。第一个实际被接受的运行仍拥有提示钩子和回调注册。规范 SDK 追加会复制冻结的显示消息及其原始证明/幂等身份,并使用新的目标事件 ID 和父级。公共链接保留原始来源身份和引用;私有绑定指向新的原生子项。其活动标记描述已验证的保留原生切分,包括当没有剩余回合时的空基线,因此第一次轮询不会将继承的回合误认为新的人类输入。
精确的主机创建或回滚断言会到达每个物理分叉/归档写入,包括原生配置围栏或过载重试之后的写入。精确的物理分叉订阅通过验证被声明,并在就绪之前释放。如果权限在清理能够归档全新子项之前关闭,则捕获的物理客户端会与新的获取分离,并在同级租约排空后退役。订阅退役不会授予归档权限;普通归档通知已经释放其订阅声明。后续受监督恢复在接受配置应用之前,需要原生 notLoaded 证据,以保留对任意外部线程采用的单独限制。竞争订阅或失败关闭不能通过取消订阅确认转换为成功配置。
已发布的 Codex App Server 通过 thread/inject_items 支持交接。经过验证的原生 forkedFromId 和精确的私有监督绑定会分类谱系;缺失的可空来源并不等同于 null。不需要自定义 initialize 能力、二进制补丁或额外操作员选项。
在原生切分、目录、模型、应用和来源验证之后,创建会追加恰好一条原始开发者消息,其中包含有界的取代通知和完整的最终通用 developerInstructions 主体。具有已证明配置所有权的已接受冷恢复,在绑定 CAS 和 turn/start 之前,会对受监督规范线程执行相同操作,包括最初从原始来源实例化的线程。精确的最终通用主体仍作为原生配置,用于压缩和原生子项继承。完整钩子替换和显式空主体保留其现有含义;钩子后诊断仍是该主体的一部分。
本通知仅取代先前的 OpenClaw 通用策略。独立的托管、守护、安全、协作和原生项目指令仍具有权威性。取代是文本层面的,而非机器强制删除。追加内容是会话配置历史:之后被拒绝的用户回合不会将其回滚,独占的用户回合截断会保留先前的配置更新,包括为被排除请求计算的 hook 输出。刷新没有客户端分配的项目 ID、用户回合注释、镜像条目或模型回合。
每次物理刷新写入和过载重试都会重新验证其确切的主机、配置、source/binding、信号和物理客户端所有者;交接在确认后会再次检查它们。已接受的恢复失败永远不会将绑定轮换到新的线程。不确定的投递会使确切的物理客户端退役,并且不能触发启动或整个 fork 重放。现有原生历史会被保留。对于新的子项,不确定性会在提交前拒绝本地删除,并防止在未证明静默的情况下归档;现有的非就绪初始化结果仍可供检查。
侧边问题将其当前问题、非延续、非变更以及继承工具/审批仅引用规则放入通用 fork 配置和相同的受保护开发者刷新中。它们不再注入合成用户边界。清理只拥有确切的侧边子项,并且不会中断从未开始的回合。
新启动和初始导入历史物化不需要额外刷新。普通非受监督的冷、温和无痕路径保留其现有行为和排除项。手动压缩、原生审查和目标保留其现有配置所有者;独立冷操作没有权威的最近一次运行通用主体可供刷新。未来被接受的受监督运行会提供当前配置和策略交接。策略存储、回执、历史扫描、保留标志或额外用户回合都不会填补该缺口。
就绪状态会固化创建权限。在就绪之前,已注册的删除所有者仅补偿确切的子项状态和一个已验证的新原生工件;source/successor 状态会被保留。丢失的原生响应不会授权孤儿 ID 猜测,就绪后的发布错误也不能删除子项。
本地继续¶
对于已存储或空闲的 Gateway 本地行,UI 会调用 sessions.catalog.continue,并附带 catalogId: "codex" 以及 host 和 thread ID。插件:
- 当 source 已经有一个时,复用现有的受监督 Chat。
- 否则,将受限的用户和助手历史投影到 source 的最后一个终端持久化回合(已完成、被中断或失败)为止的新 OpenClaw Chat 中,并记录一个待处理的 harness 分支。
- 存储待处理的仅限 Codex 的模型锁定策略,而不是具体的模型或 provider 选择,外加私有监督连接范围,并返回 OpenClaw
sessionKey。
历史投影会选择可见用户和助手消息的最新尾部,硬性限制为 200 条消息、总共 512 KiB 的 UTF-8 文本,以及每条消息 64 KiB。它会将图像和本地图像输入替换为 [Image attachment],从不复制图像负载或路径,并省略推理、工具调用和工具结果。
UI 会使用该 session key 导航到普通 Chat。此时尚不存在规范 harness 线程。在第一个普通 Chat 回合中,harness 会安装真实的 Codex 审批、征询、事件和投递处理器,然后:
- 使用监督连接调用原生
thread/fork,并设置ephemeral: true和excludeTurns: true,不带模型或 provider 覆盖,并固定已持久化的 source 快照。Codex 当前的ConfigManager状态会选择模型和 provider,fork 响应会报告实际配对。如果模型与 source 中记录的最后一个模型不同,Codex 会发出其正常的模型差异警告。harness 会在创建规范线程之前,在该确切检查和物理连接上确认thread/unsubscribe。该检查永远不会被持久化或归档。 - 在同一连接上,以
threadSource: "appServer"、OpenClaw 的 cwd、策略、配置、环境、完整的 OpenClaw harness 工具面,以及 fork 为本次初始启动返回的确切模型和 provider,启动规范的完整 Codex harness 线程。 - 通过该连接注入受限的可见用户和助手历史,提交规范绑定而不丢弃其监督范围,并运行该回合。
在第一个回合之前,Chat 是一个带可见历史镜像的锁定待处理分支;之后,每个模型回合都会通过监督连接上的规范 Codex harness 线程运行。该分支不是完整的原生 rollout 克隆:source 推理、工具调用和工具结果被有意省略。如果快照固定或规范线程创建失败,待处理分支仍可重试。绑定竞争、监督被禁用,或监督连接不可用或不匹配,会在回合运行前失败关闭,而不是回退到普通 agent-home harness。
这保证的是 Codex 拥有的选择,而不是保留 source 的历史模型。fork 返回的配对用于规范线程启动,Codex 会持久化该线程的原生模型和 provider。后续恢复会省略 OpenClaw 模型和 provider 覆盖,因此 Codex 会恢复已持久化的配对。如果另一个原生 Codex 控制更改了规范线程,OpenClaw 会接受该原生持久化选择。外层 OpenClaw 模型和回退链永远不会替代它。
对于受监督的模型锁定 Chat,模型更改、会话删除以及会话重置/新建操作都会失败关闭。变更 /codex model <model>、/codex bind、/codex resume(包括 node --bind here)以及 /codex detach 或 /codex unbind 也会失败关闭,因为它们会替换或清除绑定。/codex model 查询以及 /codex fast、/codex permissions 和 /codex threads 仍然可用。codex_threads agent 工具不能附加新的 fork 或归档已绑定的原生线程。列表和仅元数据读取仍然可用;transcript 字段需要 supervision.allowRawTranscripts,而重命名、取消归档、分离 fork 以及归档无关线程需要 supervision.allowWriteControls。这两个选项都不能替换锁定的绑定。否则,删除或重置 OpenClaw 条目会丢弃原生绑定,并在看似 Codex 的会话背后创建或允许一个通用线程。因此,保留维护会保留模型锁定条目,即使它们超过普通的年龄、数量或磁盘预算限制。禁用或卸载拥有该条目的插件也会保留锁和插件所有权标记。Chat 会保持不可用并失败关闭,直到重新启用同一插件;清理永远不会将其转换为普通模型会话。
此操作永远不会恢复或修改源。临时分叉固定一个快照;它不是持久续接线程。在第一轮启动一个不同的规范 harness 线程,可防止 OpenClaw 仅仅因为进程本地状态未能看到 Desktop 拥有的轮次而成为竞争性的源写入者。可见历史镜像和固定快照可能会遗漏活动源中尚未完成的工作。原始 CLI、VS Code、Atlas 或 ChatGPT 源仍然符合原生和 OpenClaw 目录的资格。规范分支仍然是监督存储中的原生 Codex 线程,但原生客户端可能会过滤其 appServer 源类型,因此 Codex Desktop 可见性不是契约。
归档行为¶
对于已存储或空闲的 Gateway 本地行,带有 catalogId: "codex" 的 sessions.catalog.archive 需要显式 confirmNoOtherRunner: true,会重新读取当前进程本地状态,仅对 idle 或 notLoaded 继续,调用原生 thread/archive,并且只有在 Codex 接受该操作后才返回成功。随后该行离开未归档目录。
新读取得到的活动或错误状态会拒绝归档。来自源的正在初始化或待处理的受监督分支也会拒绝归档:在源可以被归档之前,第一个 Chat 轮次必须生成其规范分支。针对精确目标或任何未归档生成后代的已知活动 OpenClaw 绑定所有者也会拒绝归档。OpenClaw 会分页读取 Codex 的实验性 thread/list ancestorThreadId 关系,并在请求或响应错误、游标或线程循环以及安全限制耗尽时失败关闭。原生归档可能会关闭已加载的父级和后代工作,因此归档不是中断快捷方式。读取、后代枚举和归档调用不是原子的。独立客户端仍可能拥有或开始处理本地显示为空闲或 notLoaded 的行。无其他运行者确认会覆盖未知客户端以及该竞态,直到 Codex 拥有条件归档或跨进程租约。配对节点归档被禁止。
Codex 目录中没有已归档视图。通过 thread/unarchive 在另一个所有者授权的 Codex 界面中恢复的线程,会重新符合未归档目录的资格。
活动线程安全¶
Codex 会在一个 App Server 的客户端之间串行化对线程的变更,但它不暴露独占的跨进程运行者或审批所有者租约。独立的 stdio App Server 可以追加到同一 rollout,而每个服务器只能看到自己的内存状态。审批请求也可能到达一个服务器的每个订阅者,第一个有效响应会完成该请求。
因此:
- 被动目录客户端不会订阅或自动拒绝审批
- 当前报告为活动的行既不会暴露新分支,也不会暴露归档
- 未映射的 Gateway 本地源会成为可见历史分支,其规范 harness 线程永远不会恢复源
notLoaded显示为活动状态未知,并且只有在知情的无其他运行者确认之后才能归档- 本地归档需要该确认以及一次新的
idle或notLoaded读取,同时承认读取与归档之间的协议竞态
中断和多客户端交接是未来的产品决策。显示活动行并不意味着这些功能。
配对节点边界¶
配对节点续接使用现有的请求/响应式 Codex CLI 恢复命令,而不是远程 App Server harness 流。节点必须已连接,并且所有三个命令都必须被 Gateway 的节点调用策略通告并允许:
codex.appServer.threads.list.v1codex.appServer.thread.turns.list.v1codex.cli.session.resume
恢复命令具有危险性,除了节点已批准的命令面之外,还需要显式的 gateway.nodes.commands.allow 授权;gateway.nodes.commands.deny 仍然优先。仅原生 macOS 目录和终端中继不会通告此 CLI 恢复命令,但 Mac 应用可以合并其嵌入式节点工作器中的额外命令。资格取决于实时命令集,而不是主机平台。
sessions.catalog.continue 在加入任何待处理采用之前需要 operator.admin。它会重新检查实时节点能力,并在未归档目录中重新定位源。只有交互式 idle 或 notLoaded 行符合条件;活动、错误、已归档、不可用或非交互式源会被拒绝。对于新 Chat,它会读取一页最多 50 个最新轮次的有界页面,并导入该页面中直到最后一个终端轮次的可见用户和助手历史,使用与本地续接相同的历史大小限制。
插件会创建或复用一个具备 agent 资格且模型锁定的 Chat,并返回一个 codex-cli-node-session 会话绑定,其中包含精确的线程 id、节点 id、所属 agent 和 cwd。Gateway 会在插件完成或取消隐藏 Chat 之前安装该绑定。在此目录操作期间不会发生原生分叉或恢复。后续授权消息会在所属节点上针对该精确原生线程运行 codex exec resume,提示词通过 stdin 传入,并使用节点的原生 CLI 配置返回最终文本。它们不会启动 Gateway 本地规范分支,也不会转发完整的 App Server 审批、工具和增量流或结构化附件。绑定轮次保留所有者/管理员检查,并在 OpenClaw 沙箱激活期间被阻止。
节点运行者会拒绝同一线程在其进程内重叠的 OpenClaw 恢复轮次;它不提供跨原生 Codex 客户端的租约。操作员必须避免在其他地方并发使用该线程。缺少所需能力的节点仍保持可读,但不提供 Chat 续接。配对节点归档仍被禁止;终端中继不会改变任一门控。
权限¶
每台计算机都在本地选择加入。启用 Gateway 不会授权另一个节点读取其 Codex 元数据。节点能力必须通过正常的配对和命令策略审批。
Fleet 列表、转录查看、本地续接和归档使用
operator.write Gateway 作用域。配对节点续接额外要求
operator.admin,后续绑定轮次保留原生执行所有者/管理员授权检查。这两个作用域均不会绕过节点连接、
命令审批、调用策略或来源资格检查。
自主代理和独立 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 目录,使完整 harness 拥有审批、工具和绑定。
独立旧版 MCP 适配器从官方插件解析这些相同工具,并且是唯一遵循保留的旧版策略环境变量的路径。
2026.8.1 目录 UI、Gateway 方法、节点能力和 CLI 注册此前未以旧插件 ID 发布。它们直接迁移到 codex 所有权下,不再引入第二个运行时门面。
未来工作¶
- 超出当前 CLI 恢复路径的完整远程 App Server harness 流式传输
- 用于同时客户端交接的显式 runner 和审批所有者租约
- 在存在 runner 所有权租约或等效隔离机制后支持远程归档
- 中断以及更丰富的活动会话观察
- Codex Desktop、CLI 和 OpenClaw 之间的可审计交接
归档浏览不属于计划中的监督侧边栏。原生 Codex 界面仍是归档线程的恢复路径。
验收测试¶
- 启用监督会列出未归档的本地会话。
- 归档会话绝不会出现在目录响应或 UI 中。
- 当另一个主机失败时,健康主机仍保持可见;不可用主机不会返回新行,也不会虚构离线会话状态。
- 存储或空闲的本地行会创建一个带有仅限 Codex 的模型/运行时锁的 Chat 镜像;第一轮会固定一个临时快照并启动规范的完整 harness 线程,重复继续会打开现有 Chat。
- 第一轮在快照分叉上省略模型/提供方覆盖,并将规范启动固定为 Codex 返回的精确配对,即使 Codex 警告其当前模型与来源最后记录的模型不同。
- 待处理和已提交的受监督绑定使用监督连接进行来源访问、规范分支创建以及后续每一轮;普通 Codex 会话仍保持代理作用域。
- 后续恢复会省略 OpenClaw 模型/提供方覆盖,保留 Codex 的规范持久化选择,接受对该线程的独立原生更改,并且绝不替换外层 OpenClaw 模型或回退链。
- 禁用监督或失去绑定/连接生命周期时会失败关闭,而不是将 Chat 移动到普通代理主目录 harness。
- 受监督的模型锁定 Chat 在保护原生绑定期间不能被删除。
- Chat 最多镜像 200 条用户和助手消息,总计 512 KiB,每条消息 64 KiB。图像变为占位符;来源推理、工具调用、工具结果、图像负载和本地路径不会被克隆。
- 分支流程永远不会恢复来源线程。
- 原始来源仍对两个目录保持资格。规范原生分支使用
appServer来源类型,并且不保证会出现在 Codex Desktop 中。 - 活动本地来源不能创建分支或归档;现有受监督 Chat 仍可打开。
- 活动未知行可以在不确认的情况下分支;归档需要显式确认没有其他 runner。
- 具有正在初始化或待处理受监督分支的来源,在第一个 Chat 轮次实例化规范分支之前不能被归档。
- 对于确切目标或任何未归档生成后代的已知活动绑定所有者会阻止归档;后代枚举失败会失败关闭,并且显式确认仍负责未知客户端以及状态到归档的竞态条件。
- 已确认的存储或空闲本地归档会在原生成功后删除该行。
- 配对节点续接要求一个已连接节点,该节点已广播并可调用全部三个命令,一个交互式
idle或notLoaded来源,以及operator.admin;缺少权限会在采用去重之前被拒绝。 - 配对节点续接会创建或复用一个具有有限历史的模型锁定 Chat,并在最终确定可见性之前安装其会话绑定。后续授权消息会在其节点上恢复精确的原生线程,而不是会话族兄弟线程或 Gateway 本地分支。
- 没有续接能力的配对节点行仍保持可读,并且任何配对节点行都不提供归档。
- 被动列表从不订阅或响应线程审批。
- 旧版 Supervisor 配置迁移到规范 Codex 配置结构。
- 旧版列表默认仅包含已加载项,存储枚举遵守其每端点上限,并且兼容发送永远不会启动或恢复空闲线程。
相关¶
- Codex supervision - 本规范的用户指南
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw