Codex 监督
Codex 监督是官方 codex 插件的一项可选(opt-in)能力。它会在正常会话侧边栏和 Chat 面板中展示来自 Gateway 计算机以及已选择加入的配对计算机上的未归档 Codex CLI、VS Code、Atlas 和 ChatGPT 源会话。
支持的操作取决于源主机及其能力:
- 已存储或空闲的本地会话可以基于其有界的持久化用户和助手历史记录创建模型锁定的 OpenClaw Chat。第一条消息会启动一个原生快照分叉,然后以 Codex App Server 为该分叉选定的确切模型和提供商启动完整的 Codex harness 线程。后续轮次会恢复规范原生线程的持久化配对,同时受监督的绑定可防止 OpenClaw 替换其他运行时、模型或回退。独立的原生 Codex 控制仍可更改该持久化配对。已创建的分支会打开其现有 Chat。
- 从另一个 Codex 进程发现的已存储本地会话具有未知的实时活动。它可以分支,或者只有在操作员确认没有其他 Codex 客户端正在使用它之后才能归档。
- 活动源保持可见,但在当前轮次完成之前无法创建分支或归档。如果它已经有受监督的 Chat,Open Chat 仍然可用。
- 配对节点上的会话通过有界、游标分页的 App Server 读取来暴露其持久化记录。当节点允许所需的 catalog 和 CLI-resume 命令,且操作员拥有
operator.admin权限时,已存储或空闲的交互式会话也可以在 Chat 中继续。后续消息将恢复该节点上的确切原生线程,而不是 Gateway 本地分支。配对节点的归档仍不可用。 - 已归档的会话不会列出。已存储或空闲的本地会话只有在操作员确认没有其他 Codex 客户端正在使用它之后才能归档。
开始之前¶
- 在 Gateway 上安装官方
@openclaw/codex插件。当你启用 Codex 功能时,OpenClaw macOS 应用可以安装它。CLI 安装可以运行openclaw plugins install @openclaw/codex。 - 在每台你想要列出其会话的计算机上安装并登录 Codex Desktop 或 Codex CLI。
- 将远程计算机配对为 OpenClaw 节点。每台计算机必须在本地选择加入。仅在 Gateway 上启用监督并不会授权另一个节点。
- 使用所有者控制的 Gateway。会话标题、工作目录和 Git 分支可能泄露敏感的项目信息。
启用监督¶
引导式 openclaw onboard 和 macOS 首次运行设置会在检测到原生 Codex 安装并成功激活所选推理后端后,尝试安装并启用 Codex 监督。Codex 不必是主要后端。当这种机会性插件激活成功时,监督即可用。App Server 可用性会在监督首次连接时检查。显式禁用 Codex 插件或策略阻止会阻止机会性激活,而现有的显式 supervision.enabled: false 会禁用面向代理的监督工具。只要 Codex 插件处于活动状态,操作员目录就会保持注册,除非 sessionCatalog.enabled: false 禁用它。这个独立开关会保持 Codex 提供商、harness 和面向代理的监督策略不变,同时还会从此主机移除配对节点的 catalog 列表/读取命令。现有安装可以手动启用相同能力:
{
plugins: {
entries: {
codex: {
enabled: true,
config: {
supervision: {
enabled: true,
},
},
},
},
},
}
如果存在 plugins.allow,请包含 codex。Gateway 插件激活在默认的混合重载模式下自动应用;请参阅应用更改并检查。
在未设置显式 appServer 连接设置的情况下,监督使用受管理的 stdio 连接来连接可用的本地 Codex 存储。目录会将进程用户的 CODEX_HOME 与已配置的 OpenClaw 代理目录下现有的 codex-home 存储合并,对规范路径进行去重,并为每个存储分配一个不透明的本地主机 ID。每个存储都有自己的 App Server 连接。其路径绝不会在目录中暴露。列表、读取、继续、归档、采用(adopt)和终端恢复会保留所选源,同时保持显式 OpenClaw 路由代理作为所有者。普通的 Codex harness 默认仍以代理为作用域。如果 harness 也应共享原生 Codex 状态,请显式设置 appServer.homeScope: "user"。监督会遵循显式的 appServer 连接设置,而不是用其本地用户主目录默认值替换它们。
若要共享正在运行的本地守护进程及其现有的 config.toml 和登录状态,请使用本地 Codex 配置设置。
目录读取使用所选存储的原生 Codex 身份验证,包括当该存储位于 OpenClaw 代理目录下时。浏览已存储的会话不需要将原生凭据导入 OpenClaw。普通的受管理代理运行保留其自身的凭据导入和身份验证要求。
从 Codex 侧边栏组中采用的 Gateway 本地 Chat 不是普通的 harness 会话。其私有监督绑定使用监督连接进行源读取、规范分支创建、历史注入以及后续每一轮。使用默认本地连接时,这会保留原生用户 Codex 主目录、身份验证和提供商配置,同时不更改其他会话的默认设置。受监视的已采用 Chat 也参与会话状态感知。
对于默认的本地监督连接,存储与原生 Codex 客户端共享。OpenClaw 不会假设另一个客户端共享同一个实时 App Server 进程,并且原生状态所有权是进程本地的。因此,它会将监督 App Server 报告为 notLoaded 的线程视为已存储 / 活动未知,而不是空闲。
对希望其会话出现在目录中的每个无头节点主机应用相同的选择加入机制。
原生 OpenClaw macOS 应用在向配对 Gateway 通告其 Codex 目录时使用本地 sessionCatalog.enabled 设置;无需启用面向 agent 的 supervision 工具。显式的 sessionCatalog.enabled: false 会使目录保持禁用状态,包括选择加入之前的 macOS 首次运行默认状态。该配对的原生 Mac 目录仅支持默认或显式的 appServer.transport: "stdio",且 appServer.homeScope 未设置或显式设置为 "user"。该 stdio 进程会遵从 command、args 和 clearEnv。如果 Mac 配置选择了 "unix"、"websocket" 或 homeScope: "agent",应用不会通告目录能力或命令,过时的直接调用会失败,而不会暴露用户的 Codex 主目录或启动另一个本地 stdio App Server。
无头节点默认使用其原生用户主目录 stdio 目录:CODEX_HOME,若未设置则为 ~/.codex。原生列出、记录读取、终端恢复和 Chat 续接都使用该节点自有存储。在更新后的原生节点上,即使节点有多个 agent 且没有默认所有者,也不需要存在 Gateway agent。
Gateway 保留可选的 agentId 字段,以与仍需要该字段的已发布节点互操作。更新后的原生读取器仅将该字段视为路由上下文。显式的 agent 作用域或非 stdio 目录配置保留其现有的源选择契约:请求的所有者选择配置的节点源,缺失或已移除的所有者会导致失败,而不会回退到原生用户主目录。请同时升级节点和 Gateway,以获得与 agent 无关的原生发现能力。
新通告的节点命令会改变节点已批准的命令表面。请从 Gateway 主机批准该更新:
未归档的 Codex 会话也会出现在主 Control UI 侧边栏中,按主机分组。选择其中一个即可读取其持久化的记录。每个请求最多返回 50 条记录项(调用者省略 limit 时为 20 条),在需要满足 20 MiB 传输安全上限时使用更小的分页。受支持的存储使用 Codex thread/items/list。较旧的存储和节点读取器保留 thread/turns/list,并在轮次内进行分页。向上滚动可加载更早的页面。已加载的页面按时间顺序呈现。
Control UI 将工具结果显示为 500 字符预览,并标记缩短的输出。预览不会重写原生记录,也不会移除通用的 raw 数据。目录文本使用共享的每项 512 KiB 限制。查看器永远不会加载无上限的 thread/read 历史。超过传输上限的旧版轮次响应或单个项仍会明显失败。请在 Codex 中打开该会话以查看其完整输出。
在常规会话侧边栏中打开 Codex 组。它会按主机列出相同的会话。加载更多会话 会从每个有更早行的主机追加下一页,这些追加的行会在侧边栏的定期刷新后保留。每个主机会在其常驻目录就绪后立即出现。可见页面会在节点连接状态变化后、重新获得焦点时以及最多每 30 秒进行一次对账。发生变化的结果会获得一次更快的后续扫描。在 Codex Desktop、CLI 或其他原生客户端中创建的会话会在主机后台目录对账后出现。原生事件会更新由该 Gateway 驱动的线程,无需等待定期扫描。
在主目录适合内存时,搜索和分页使用常驻行。保留的 20,000 行窗口永远不会限制发现:较早的页面和作用域搜索会回退到仅限原生数据库的分页,并使用不透明续传令牌来处理有界的部分结果。空的部分搜索结果页仍可能包含续传令牌。精确线程访问还会对照权威来源验证较早的 ID,而不是将淘汰视为不存在。第一页遵循最近顺序,在时间戳相同的情况下保持原生顺序,并使用稳定的线程键进行分页。新创建的原生 fork 仍然可以通过 ID 读取,但在其第一个自己的用户轮次之前可能不会出现在这些列表中。参见 目录水合与边界。
主机可用性和线程状态是分开的。离线 或 不可用 描述的是主机刷新状态。不可用的主机不会返回新的会话行,也不会将线程的原生状态更改为 offline。会话行使用 Codex 状态,例如 idle、active、notLoaded 或错误。失败的主机不会隐藏来自健康主机的结果。
同一本地主目录的所有查询共享一个常驻索引。初始原生水合使用现有的源失败退避机制;已完成的行保留在内存中,并保留在可重建的 SQLite 快照中。常规列表请求在 TTL 之后绝不会重新启动发现。渐进式侧边栏列表会为相同查询复用上次发布的配对节点页面,并在后台刷新它。没有匹配页面的节点最多有 250 毫秒来响应;此后其主机会被标记为待处理,保留可见行,直到现有的主机更新事件到达。节点断开、重新连接、配置更改以及更新的发布都会使保留的页面失效。较早的刷新不能替换较新的发布。一次性列表、特定主机查找和分页仍会在现有的八秒响应截止时间内等待新节点数据。
当没有可见会话时,侧边栏会隐藏 Codex 组,包括发现失败时。常规发现刷新会继续,因此当会话可用时组会出现。当另一个主机失败时,已有内容的组仍保持可见。
侧边栏警告包含目录错误代码和安全的底层 Gateway 错误。打开侧边栏的 筛选和排序 > 会话源… 菜单,或 设置 > 外观 > 会话源,然后关闭 显示 Codex 会话,即可在不禁用 Codex 的情况下禁用发现。对于 NODE_LIST_FAILED,请对比 openclaw nodes list 和 设置 > 设备。详细原因会标识需要修复的配对存储、节点注册表、权限或 Gateway 生命周期故障。
启动新的原生 Codex CLI¶
在 Codex 旁选择 +,选择一个原生主机和文件夹,然后按 在终端中启动 或 Enter。这会启动一个新的交互式 Codex CLI,而不是模型锁定的 OpenClaw Chat 或已采用的原生线程。Codex 拥有其原生账户、模型、配置和会话身份。可选的 prompt 以文本形式传递,绝不作为 CLI 选项传递。本地目录源会保留其选定的 Codex 主目录,包括不透明的次级本地主机 ID。
创建终端需要 operator.admin、gateway.cliAgents.enabled、已安装的 CLI 以及活动的目录插件。终端默认启用。
gateway.terminal.enabled: false 会阻止创建。
它不需要符合条件的 OpenClaw 模型。配对的无头节点必须
通告并允许 codex.terminal.start.v1。现有的
codex.terminal.resume.v1 单独并不支持全新启动。节点选择
其自身安装的 Codex 可执行文件和原生账户/配置。Gateway
代理仍然是授权上下文。它无需存在于节点的
OpenClaw 配置中。
本地启动支持 Gateway 文件夹/工作树选择器。节点启动要求 该节点上存在一个现有的绝对目录,并且如果该目录消失,绝不会替换为节点的主目录。命令仅接受 cwd、可选的 prompt 以及终端尺寸,不接受调用方提供的可执行文件、argv、环境变量或凭据。 关闭终端会取消其节点调用。断开连接以及过期的配对 或连接代际由与恢复相同的终端中继处理。 在终端中打开现有会话还需要一个本地 stdio 源,或 一个通告终端恢复的配对节点。Unix 和 WebSocket 目录 直接连接到 Gateway 时仍可用于浏览和 Chat 继续。对于终端访问,请打开为该服务器配置的原生客户端。 请参阅 原生 CLI 创建 了解 UI 控件 和先决条件。现有的目录查看、恢复和 Chat 继续保留 其各自的所有权契约。
使用操作员 CLI¶
终端 CLI 公开相同的未归档目录以及 Gateway 本地的分支和归档操作:
openclaw codex sessions [--agent <id>] [--search <text>] [--host <id>] [--limit <count>] [--cursor <cursor>] [--json] [--url <url>] [--token <token>] [--timeout <ms>] [--expect-final]
openclaw codex continue <thread-id> [--agent <id>] [--host <id>] [--json] [--url <url>] [--token <token>] [--timeout <ms>] [--expect-final]
openclaw codex archive <thread-id> --confirm-no-other-runner [--agent <id>] [--host <id>] [--json] [--url <url>] [--token <token>] [--timeout <ms>] [--expect-final]
openclaw codex sessions 选项:
--agent <id>在多代理 Gateway 中选择 OpenClaw 所有者。--search <text>不区分大小写地搜索会话标题。--host <id>将响应限制为一个稳定的目录主机,例如gateway:local、一个不透明的gateway:local:<source-id>,或node:<node-id>。--limit <count>设置每个主机 1 到 100 行。默认值为 50。--cursor <cursor>继续一个主机页面,因此需要--host。--json打印结构化的 Gateway 响应。
所有三个命令都接受 --agent <id>,并从 Gateway 客户端继承 --url、--token 和 --timeout <ms>。
会话列表默认值为 75,000 毫秒,以便冷配对节点
目录能够完成。Continue 和 archive 默认值为 30,000 毫秒。它们还公开共享的
--expect-final 开关,该开关不会改变这些一元监督 RPC。
每个 shell 命令请求 operator.write Gateway 范围。
每个子命令都提供标准的 -h, --help 输出。
没有 archived 或 include-archived 选项。sessions 可以列出配对
主机。continue 和 archive 默认为 gateway:local。传递列出的
不透明本地 --host id 以指向另一个本地 Codex 存储。shell
continue 命令仅请求 operator.write。传递节点主机不会
请求配对节点继续所需的 operator.admin 范围。除非
Gateway 单独将该范围授予已认证身份,否则
请求会被拒绝。对于配对节点继续,请使用下文描述的经管理员授权的 Control UI 流程。archive 保持 Gateway 本地,并且始终需要
--confirm-no-other-runner。
这些 shell 命令与聊天中的 /codex 运行时命令不同。
/codex threads [filter] 列出当前会话连接可用的 App Server 线程。/codex sessions --host <node> 列出单个节点上可恢复的 Codex
CLI 会话文件,而不是监督集群目录。/codex
resume 和 /codex bind 会附加当前会话,而不是创建
安全的受监督分支,并且模型锁定的受监督 Chat 会拒绝这些
绑定变更。没有 /codex continue 或 /codex archive 运行时
命令。
从本地会话分支¶
在 Codex 侧边栏中从 Gateway 计算机打开一个已存储或空闲会话, 并从其会话查看器发送一条消息。OpenClaw 创建一个模型锁定的 Chat 条目,镜像有界的用户和助手历史,直到源的最后 一个终端持久化轮次(已完成、已中断或失败),记录一个待处理的 harness 分支,并将你的消息转发到 Chat。通用模型选择器 保持锁定。 分支准备不会恢复源或启动规范 harness 线程;转发的消息会启动该工作。继续同一源 会打开其现有 Chat,而不是创建另一个分支。
镜像保留符合所有三个限制的最新可见尾部:最多 200
条用户或助手消息、总共 512 KiB 的 UTF-8 文本,以及每条
64 KiB。超大消息会被截断并带有标记,达到上限时较旧的消息会被
省略。图像或本地图像输入会变成字面量
[Image attachment] 占位符。图像数据和本地路径不会被复制。
第一条转发的消息开始工作。Codex harness 安装
真实的审批、征询、事件和交付处理器。它使用监督连接上的临时
原生 fork 来固定源快照,而不提供模型或提供商覆盖。Codex App Server 从其
当前原生配置中选择两者,并返回实际选择。OpenClaw 在创建规范分支之前确认
该检查的订阅已释放。
该检查永远不会成为存储历史或归档产物。在同一
连接上,OpenClaw 在其 cwd 和运行时策略下,使用恰好返回的该对,启动规范 appServer 源完整 harness 线程,注入
有界的可见历史,并提交分支绑定。规范线程
具有完整的 OpenClaw harness 工具表面。这是一个可见历史分支,而不是
完整的原生 rollout 克隆:源推理、工具调用和工具结果会被
省略。此轮次以及之后的每一轮次都保持在受监督的 Codex 连接上,
而不是另一个 OpenClaw 模型运行时或普通 agent-home harness。
返回的选择不是源历史模型的证明。如果当前原生配置与源上一轮记录的模型不同,Codex 会发出其正常的模型差异警告。OpenClaw 使用返回的配对作为规范线程的起始。Codex 会持久化该规范线程的原生模型和提供商,后续恢复会保留它们,因为 OpenClaw 省略了模型和提供商覆盖。如果规范线程通过另一个原生 Codex 控制被更改,OpenClaw 会接受 Codex 持久化的选择。OpenClaw 从不替换其外部模型或回退链。
受监督的模型锁定 Chat 不能被删除、切换模型、使用 /new 或 /reset、调用 Gateway 会话重置操作,或使用通用的 Fork session 操作。修改 /codex model <model>、/codex bind、/codex resume(包括带有 --bind here 的节点会话)以及 /codex detach 或 /codex unbind 也会被拒绝,因为它们会替换或清除已锁定的原生绑定。/codex model 查询以及 /codex fast、/codex permissions 和 /codex threads 仍然可用。当你想要不同模型或新线程时,请启动另一个普通会话。
Fork from here 保留源连接和模型锁定框架,而不更改原始源或父级 Chat。原始导入消息和规范对话消息使用不同的原生流程。参见 在受监督的 Chat 中分叉消息。
请保持此 Chat 的监督启用。如果监督被禁用,或其存储的连接绑定变得不可用或不一致,该轮次会失败关闭,而不是切换到普通 agent-home 会话。
新的采用会将原生标题快照为修剪后的显示名称,上限为 500 个 UTF-16 码元,且不拆分代理对。原生标题可能重复或为空。它们不声明唯一的 OpenClaw 标签。显式本地标签优先于存储的显示名称。重新打开或恢复 Chat 会保留其现有标签和标题快照,包括较早自动分配的标签。重命名原生源不会重新同步这两个字段。Fork from here 不会继承原生响应的标题作为显示名称或本地标签。
禁用或卸载 codex 插件不会释放该所有权,也不会使 Chat 有资格用于另一个模型。锁定的 Chat 仍会被保留但不可用。重新安装或重新启用同一插件,确认运行时应用,然后恢复它。这种刻意的失败关闭行为可防止保留清理或临时插件故障静默地孤立原生绑定。
codex_threads 代理工具遵循相同的边界。它不能附加不同的分叉,也不能归档 Chat 绑定的原生线程。列表和仅元数据读取仍然可用。原始转录读取需要 allowRawTranscripts。当原始访问被禁用时,codex_threads 也会拒绝列表搜索,因为原生搜索包含转录预览。Control UI 和 operator CLI 仍提供有界的仅标题搜索。重命名、取消归档、分离分叉以及归档无关的未拥有线程需要 allowWriteControls。这两个选项都不会绕过锁定绑定。
OpenClaw 在仅列出源线程或显示待处理 Chat 时,不会订阅或回答审批请求。在第一轮启动一个独立的规范框架线程,可以让另一个 Codex 进程继续拥有源,而不会创建竞争的 rollout 写入者。
原始 CLI、VS Code、Atlas 或 ChatGPT 源对原生客户端和 OpenClaw 目录仍然可见。规范分支作为原生 Codex 线程存储,但其源类型为 appServer。Codex Desktop 或其他原生客户端可能会过滤该源类型,因此该分支本身不保证出现在每个原生历史视图中。
OpenClaw 的 App Server 报告的活跃行不能启动新分支。请等待当前轮次完成并刷新目录。Codex App Server 在一个进程内序列化变更,但它不提供独占的跨进程运行器或审批所有者租约。
对于 Stored / activity unknown 行,Chat 镜像和首轮快照固定使用 Codex 截至最后一个已持久化的终止轮次的状态。源线程不会被恢复、中断或归档。如果另一个进程有进行中的轮次,其最新的在途工作可能不存在于分支中。
在受监督的 Chat 中分叉消息¶
分叉原始导入的用户消息会保留原始源流程:源必须仍然可读,并且子线程的第一轮会实例化其有界的导入历史。
分叉在规范 OpenClaw 对话中创建的用户消息则会立即创建原生子线程,在该原生轮次之前截断。Codex 保留其原始历史,包括最初注入的前缀,而无需再次导入历史。本地 Chat 仅复制所选消息之前经过验证的显示前缀,并保留原始源链接。活动监控从保留的原生前缀之后开始,因此继承的消息不会显示为新的用户输入。此规范截断不要求原始导入源保持可用。
新的规范用户轮次会在 Codex 接受提示后,在现有 Chat 消息上记录原生提示溯源。这会保留消息 ID、文本、时间戳、发送者元数据和位置。缺少此溯源的较早规范轮次仍然无法验证:匹配的文本或相邻的助手回复无法确定缺失的原生边界。后续经过验证的轮次不会修复较早的无法验证的前缀。从原始源启动一个新的 Chat,或者在该源仍然可用时分叉一个原始导入消息,然后创建新的规范轮次。OpenClaw 不会回填旧行。
规范消息分叉使用随附的 Codex App Server 的 developer-message API。OpenClaw 在原生线程配置中保留完整的当前通用指令,并追加一条开发者消息,以替换较早的 OpenClaw 提供的通用策略,包括已移除的章节或显式空策略。独立的原生托管、守护、安全、协作和项目指令保留其权威。这是文本层面的取代。它不会删除较早的历史,也不会更改原生权限执行。
刷新是在下一个原生用户轮次之前记录的会话配置。 它可以包含该请求的提示词钩子输出,并且即使该用户轮次被拒绝或从未开始,也会保留在原生历史中。 从此处分叉 会排除所选的原生用户轮次。它不会擦除在该轮次之前记录的配置更新。 刷新不会创建用户消息或额外的模型轮次。
规范消息分叉需要 Codex 0.153.0 或更高版本以及原生模型元数据。 当源线程在所选 App Server 中已加载时,它们使用该源线程的当前模型选择; 当未加载时,使用其最近一次持久化的选择。如果 Codex 无法报告该选择, 请更新 Codex,或改为分叉一条原始导入消息。
在发布子线程之前,OpenClaw 会验证原生切分、所选模型和提供商、不可变工具目录、 本地显示前缀以及确切的创建所有者。在初始化期间,它会拒绝源 rollout 或所选模型的任何更改。 其自动原生订阅会在就绪之前释放。 准备阶段不会运行提示词钩子,也不会配置执行环境或请求方 MCP 资源。 源的实际原生声明必须与新子线程的声明相匹配。创建过程不会重建假设运行中的工具。 如果某个子线程的原生策略或元数据无法验证,则会拒绝创建,并提供原始消息替代方案。 显示副本限制为 200 条消息和 512 KiB 的序列化消息数据。
继承的声明不会授予执行工具的权限。每个被接纳的轮次都会独立构建其当前可用的工具和审批。 对非所有者或已关闭运行不可用的工具仍保持不可用,而原生后代会在轮次和重启之间保留其目录和历史。
创建者必需沙箱需要主机预置的环境,因此不符合此直接规范分叉的条件。 仅 Codex workspace-write 无法满足该隔离要求。
后续轮次在应用当前 harness 配置之前,需要原生卸载证据。 仅退订确认不足以证明线程已卸载。一旦配置得到证明,OpenClaw 会在开始轮次之前刷新完整的通用策略。 如果无法验证配置应用,请停止竞争的原生工作并重新连接。绑定的会话会被保留。 不确定的刷新也会保留会话,并使其连接退役,而不是重放该操作。清理未经验证的失败新子线程仍保持未就绪,无法检查。
新的初始实例化已经提供通用指令,无需额外的策略刷新。普通非受管会话保持其现有的恢复和热复用行为。 独立的冷压缩、审查和目标操作不会重建上一次运行中由钩子派生的通用策略。 下一个被接纳的受管运行会提供当前配置并刷新它。
归档本地会话¶
在已存储或空闲的 Gateway 本地行上选择 归档,然后确认没有其他 Codex 客户端或 OpenClaw 运行器正在使用该线程或其生成的后代。
OpenClaw 会重新读取进程本地状态,仅在 idle 或 notLoaded 时继续,调用原生 Codex 归档操作,并将该会话从未归档列表中移除。
原生 Codex 还会尝试归档该线程生成的后代,并停止通过原生协作恢复的已归档后代。
当最新读取报告会话处于活动状态或错误状态、它属于配对节点,或者新创建的受管 Chat 仍具有来自该源的待处理分支时,归档不可用。 在归档源之前,发送该 Chat 的第一条消息以实例化其规范分支。 当 OpenClaw 知道某个活动绑定拥有确切的目标线程或任何生成的后代(包括已归档后代)时,归档也会被阻止。 OpenClaw 会检查两个后代集合中的活动工作,并在一个共享边界内跟踪实验性 Codex 后代查询的每一页。 无效响应、请求失败、重复的游标或线程,或安全限制耗尽都会拒绝归档。
读取、后代枚举和归档请求并非一个条件操作,因此它们之间仍可能开始一个轮次。 App Server 状态也不会在独立进程之间共享。 因此,确认是未知客户端和该竞态的安全边界:在确认之前,请退出或以其他方式验证所有其他客户端。 使用 Codex Desktop、Codex CLI 或所有者授权的原生线程管理流程恢复已归档的线程。 取消归档后,它会重新出现。
了解配对节点限制¶
配对节点公开版本化的只读
codex.appServer.threads.list.v1 和
codex.appServer.thread.turns.list.v1 命令。具有可用 Codex CLI 的原生节点主机还会公开允许列表中的
codex.terminal.resume.v1 命令。Gateway 接收规范化元数据和明确请求的有界转录页面,而不会接收原始 App Server 端点。
在操作员终端中打开一行会在拥有主机上运行 codex resume <thread-id>,并中继该命令的 PTY。
它不会公开通用 shell 或 Gateway 提供的 argv。
Chat 续接是与终端中继不同的能力。它需要
operator.admin,以及一个已连接且同时宣告并允许以下全部三个命令的节点:
codex.appServer.threads.list.v1codex.appServer.thread.turns.list.v1codex.cli.session.resume
该节点还必须宣告支持恢复所选目录源。 配对节点 Chat 续接要求该源使用本地 stdio;Unix 和 WebSocket 源仍可浏览,但不能通过节点 CLI 续接。 如果 OpenClaw 请求升级,请更新节点并批准其刷新后的能力。 较旧的节点仍可用于浏览;现有 Chat 会被保留。 恢复节点原生用户主目录的旧版 CLI 绑定保持其现有行为。
新的配对节点 Chat 会固定所选的规范 Codex home,以及节点和线程。更改节点的目录源无法重定向现有 Chat,即使替换 home 中包含具有相同 ID 的已复制线程也是如此。恢复原始源以继续该 Chat,或在目录中选择替换源,将其采用到单独的 Chat 中。 OpenClaw 会为当前配置捕获每个源的物理路径;重新指向目录别名会在配置重新加载后生效。
旧版本采用的 Chat 未记录其源 home。其历史记录仍然可用,但原生继续需要从目录中重新采用。OpenClaw 会创建一个单独的固定 Chat 并保留旧 Chat;它不会根据节点的当前配置推断旧 Chat 的 home。
CLI-resume 命令是一个危险的节点命令:它需要显式的 Gateway 命令允许列表(gateway.nodes.commands.allow),以及节点命令面的批准。拒绝规则仍会阻止它。仅原生 macOS 目录和终端中继无法提供它,尽管 Mac 应用的内嵌节点工作进程可以通告额外命令。请检查实际通告和允许的命令,而不仅仅是主机平台。仅暴露 list、transcript 和 terminal 命令的节点仍可在不进行 Chat 继续的情况下保持可读。
在 Control UI 的 Chat 窗格中打开一个符合条件的未归档交互行,并发送一条文本消息。继续操作会重新检查源是否为 idle 或 notLoaded,创建或重新打开一个模型锁定的 Chat,并将其绑定到拥有节点上的确切原生线程。新 Chat 会从最新的转录页面镜像有界的用户和助手历史。目录操作本身不会分叉或恢复原生线程。然后 UI 会将你的草稿转发到已绑定的 Chat。该消息及后续轮次会在节点上使用其原生 CLI 配置运行 codex exec resume,并返回其最终文本。此文本提示路径不会创建 Gateway 本地分支,也不会转发完整的 App Server harness 事件、审批、工具调用或结构化附件。已绑定的轮次仍需要 owner/admin 权限,并在 OpenClaw 沙箱激活期间被阻止。
在使用此 Chat 时,避免在另一个 Codex 客户端中运行同一线程。节点会防止其自身进程中针对同一线程和规范存储的重叠 OpenClaw resume 轮次,但
notLoaded 并不能证明另一个原生客户端处于空闲状态,也没有跨进程 runner 租约。配对节点 Archive 仍不可用,
无论是否具有继续或终端功能。
元数据与权限¶
目录行可能包括:
- 线程和会话标识符
- 标题和工作目录
- 当前状态和激活等待标志
- 创建、更新和活动时间戳
- 源、模型提供商、Codex CLI 版本和 Git 分支
目录投影排除转录预览、轮次、rollout 路径、
Codex home 路径、Git 远程、commit SHA 和原始 App Server 错误。目录
访问和 Control UI 转录读取需要 operator.write Gateway
范围,因为 fleet 聚合使用标准 node.invoke 路径,尽管
两个目录节点命令都是只读的。配对节点继续
额外需要 operator.admin。后续已绑定轮次会强制
原生执行 owner/admin 检查。
supervision.allowRawTranscripts 和 supervision.allowWriteControls 控制
自主代理和独立 MCP 工具。两者默认均为 false。启用
监督后,codex_threads 会从列表和仅元数据读取结果中移除转录预览和轮次,除非允许原始转录。包含
轮次的读取会失败关闭。每个分叉、重命名、归档和取消归档
都需要写入控制。这些选项不会限制已认证的 Control UI
转录查看,也不会绕过绑定、主机、状态或确认检查。
兼容性工具¶
官方 codex 插件为现有代理和独立 MCP 客户端保留了五个随附的 Supervisor 工具名称:
codex_endpoint_probecodex_sessions_listcodex_session_readcodex_session_sendcodex_session_interrupt
codex_sessions_list 默认仅加载。没有 loaded_only
参数。设置 include_stored: true 以同时从 Codex 的状态数据库读取未归档的已存储行。可选的 max_stored_sessions 上限默认为 200,
每个端点接受 1 到 1,000 行。它不会限制已加载行。
没有原始转录权限时,列表结果会省略由转录派生的名称、
预览和详细端点错误。
codex_session_read 需要 allowRawTranscripts。include_turns: true
会额外向 Codex 请求轮次。
codex_session_send 和 codex_session_interrupt 需要
allowWriteControls。Send 接受 mode: "auto" | "start" | "steer",但
"start" 始终被拒绝,且 "auto" 和 "steer" 都只能引导可读的活动
轮次。空闲线程会被拒绝,并提示使用 Codex
Sessions,在那里完整 harness 会在继续之前安装审批和工具处理器。Interrupt 同样需要活动可读轮次。这些工具
不会恢复或启动空闲源线程。
openclaw doctor --fix 会将已退役的 codex-supervisor 条目、其端点
和权限字段,以及插件允许/拒绝策略引用移动到官方
codex 插件中,而不会覆盖显式的规范设置。独立
兼容性 MCP 适配器会继续从该插件加载相同的五个工具。旧策略
环境变量仅在该受信任适配器内部适用。
有关每个监督配置字段,请参阅 Codex harness 参考。
故障排查¶
未显示会话: 请验证 @openclaw/codex 已安装,插件和
supervision.enabled 均为 true,当前插件允许列表允许
codex,并且会话未归档。Gateway 激活更改会热应用;
完成后刷新目录。如果节点的本地激活
更改未刷新其通告的能力,请重启该节点。
Continue 已禁用或被拒绝: 未映射的行处于活动状态或不符合资格的状态,其主机离线,或另一个操作正在等待。对于配对节点行,还需验证 operator.admin,并且所有三个继续命令均已通告并允许。仅终端访问不足。从 Gateway 本地存储或空闲会话查看器发送,以创建单独分支。继续一个已有受监督 Chat 的源会打开该 Chat。
无法验证会话资格: 对于基于文件系统的本地源,transcript、Continue、Archive 和终端操作会直接验证所选线程,检查非归档原生索引成员资格,并在所选 Codex 主目录中验证其 rollout 元数据。这些检查共享一个请求预算,并且不会扫描完整目录。缺失、不可读、不一致或 OpenClaw 管理的元数据均不被接受。刷新目录,在其原生 Codex 主目录中验证会话,然后重试。此错误并不能证明该线程不存在。普通发现保持其现有行为。远程源继续使用新的原生目录验证,包括当请求的 ID 仍然驻留或已被逐出时。远程和配对节点验证都不会在固定的目录页面数处停止;现有的请求截止时间仍限制该操作。
Archive 已禁用: Archive 在确认没有其他运行器后可用于存储/活动状态未知和空闲的 Gateway 本地行。活动、错误、离线、配对节点、待处理分支以及已知精确绑定所有者行对 Archive 保持只读。
已归档会话消失: 这是预期行为。监督页面没有归档视图。运行 codex unarchive <thread-id> 或使用 Codex Desktop 再次显示它。
旧的 codex-supervisor 配置仍然存在: 运行 openclaw doctor --fix。Doctor 将已弃用的插件条目和相关插件策略引用移动到 plugins.entries.codex.config.supervision,而不会覆盖显式 Codex 设置。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw