远程放置

本文档介绍 Codex 会话如何将原生执行放置在 Gateway 之外，而应用服务器、模型连接和会话记录仍由 Gateway 持有。本文是 Codex 工具链 指南的一部分；各章节迁移位置 列出了每一节。

在配对设备上运行 Codex¶

Codex 会话可以将原生命令、文件系统、能力发现和 HTTP 执行放置在符合条件的配对设备上，而 Codex 应用服务器、模型推理、提供商身份验证和会话记录仍保留在 Gateway 上。这是会话级的 remote-exec 放置，不是 node_exec 或 tools.exec.host: "node"。

在 Gateway 的配置和配对节点自身的本地配置中均安装并启用 Codex 插件。如果任一机器使用 plugins.allow，请在该机器的允许列表中加入 codex。在 Gateway 上，显式允许该高风险节点命令：

{
  gateway: {
    nodes: {
      commands: {
        allow: ["codex.exec-server.stdio.v1"],
      },
    },
  },
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}

配对节点必须启用会话托管，并通告 codex.exec-server 能力和 codex.exec-server.stdio.v1 命令。如果启用插件改变了现有节点的命令面，请重新连接该节点，检查 openclaw nodes pending，并使用 openclaw nodes approve <requestId> 批准更新后的配对。持久化命令允许列表不能替代启动授权。关键提示提供两种批准范围：

• 允许一次（Allow once）：授权一次 exec-server 启动。
• 始终允许（Allow always）：仅当相同的会话放置在同一节点、配对代次、环境、所有者纪元、放置代次、命令风险和当前工作目录上保持活动时，才授权后续启动。

Gateway 仅在当前进程中保留常驻放置授权，并在每次节点传输调度之前立即重新验证。因此，重启 Gateway 会回到正常提示，而不会迁移或重新加载批准状态。移动或回收会话、替换环境、在新配对下重新连接、更改工作区或达到 30 天最大生命周期，也会使复用失效。如果 Gateway 无法推算出确切的放置权限，它只提供允许一次。拒绝则不启动任何进程。

显式选择的会话完全访问（Full access）只能在确切获准的回合和放置期间替代该提示，且仅当节点自身的 tools.exec 策略和 exec-approvals 下限都允许完全（full）或关闭（off）执行时。节点本地拒绝始终会阻止。本地询问或允许列表限制需要人工决策；完全访问并不能消除这些限制。如果完全启动被本地策略拒绝，请使用普通会话权限模式请求批准，或有意更改节点本地策略并重新连接它。启动准备期间的策略收紧会拒绝过时的启动。

Codex 直接启动其节点 exec-server，而不是启动 OpenClaw 工作进程，因此即使所有工作进程槽位都被占用，配对主机仍然符合条件。该命令仍然必须实际可调用：仅声明该命令而没有经过批准的配对面和 Gateway 允许列表是不够的。

批准授予对节点操作系统账户可访问的任何进程或文件的访问权。经验证的放置工作区设置工作目录和同步范围；它不会对该访问进行沙箱化或限制。请只配对受信任的设备，并在需要隔离时以单独的、最小权限的操作系统账户运行节点。

在 Control UI 的 Place 选择器中选择配对设备，或显式调度现有的托管工作树会话：

openclaw gateway call sessions.dispatch \
  --params '{"key":"agent:main:device-work","deviceId":"<paired-device-id>"}'

节点在放置工作区中启动相同的、固定版本的托管 Codex 二进制文件，参数为 codex exec-server --listen stdio。节点会等待原生进程开始监听后再宣布执行就绪，因此冷磁盘启动不会消耗 Codex 的初始化握手预算。启动过程仍可通过现有的尝试生命周期取消。Gateway 通过现有的经过身份验证、受批准门控的双向节点通道中继完整的 Codex JSON-RPC 消息，每条消息限制为 64 MiB。它不会启动 OpenClaw 工作进程子进程、打开反向隧道，也不会将提供商、云或 GitHub 凭据复制到设备上。经过身份验证的远程 HTTP 不可用：Gateway 在将请求发送到节点之前，会拒绝包含 Bearer/OAuth 授权、Cookie、API 密钥或其他敏感身份验证头的请求。请在 Gateway 上运行经过身份验证的 HTTP，或使用故意不包含凭据的端点。节点进程使用全新的私有 HOME 和 CODEX_HOME，这些目录在尝试结束后会被移除；其启动环境和所请求的子进程环境都经过净化处理。已完成的文件系统更改会同步到 Gateway 持有的托管工作树中，或对于仅仓库（repository-only）会话，同步到 Gateway 保留的不可变检查点中。

在 Codex 的默认环境策略下，原生任务进程会继承 exec-server 启动时的 RUST_LOG 过滤器。当程序需要不同的日志级别时，请在命令中显式设置 RUST_LOG。

断开节点、关闭应用服务器连接、取消回合或停用插件，都会明确结束该 Codex 尝试，并终止其远程 exec-server 进程。每次配对设备尝试都拥有一个独立的 Gateway 应用服务器客户端，从而防止远程环境注册在多次尝试之间累积。重新连接同一配对设备会允许新的尝试；它绝不会恢复已断开的 stdio 连接或其进程。常规 Codex 回合受支持，但 /btw 附带问题尚未绑定到配对设备放置，会失败并给出可操作的说明。请参阅 云工作进程与配对设备放置 和 节点命令策略。

在云工作器上运行 Codex¶

捆绑的 Crabbox 提供程序同时支持 OpenClaw worker-turn 和 Codex remote-exec，因此一个已配置的云工作器配置文件可供任一执行框架选用。在选择 Codex 模型后，请在新会话或移动会话中选择相同的 云 · 配置文件 目标。配置文件放置需要 operator.admin。可以从 GitHub 仓库 URL 和可选 ref 开始，而无需 Gateway 检出；也可以放置现有的 Gateway 托管工作树会话。仅仓库会话会在所选节点上获取并固定其源代码。仓库会话需要托管节点；仅 SSH 的提供程序无法创建它们。

启用受信任的 Codex 插件安装，并在 Gateway 上显式允许 codex.exec-server.stdio.v1，如 在配对设备上运行 Codex 所示。Crabbox 会根据正在运行的 Gateway 的内置安装自动引导云节点，包括 Codex 插件及其固定的原生依赖项。引导会为云机器的操作系统和 CPU 安装依赖项，然后在节点的隔离状态中启用插件。保持配置文件设置专注于机器先决条件和项目工具，包括受支持的 Node.js 版本和 npm。有关构建和注册表访问要求，请参阅 捆绑安装。

Gateway 在启动 Codex 进程之前会检查云节点的当前配对状态和实际可调用的命令。相同的放置范围批准或显式选择的“完全访问”规则均适用，包括云节点的本地执行策略和批准下限。

Codex 通过已登记节点的经过身份验证的出站连接运行其托管 exec-server，而无需启动 OpenClaw worker 子进程或占用 worker 插槽。其 app-server、模型连接、提供程序身份验证和记录仍归 Gateway 所有。进程和文件系统访问依旧沿用节点操作系统账户的权限，并且仅转发不含凭据的 HTTP。工作区更改会回写协调到 Gateway 拥有的工作树或不可变的仓库检查点。失败或断开的尝试是终态性的，需要重新尝试；它绝不会恢复远程进程，也不会回退到 Gateway 本地或 SSH 执行。

请参阅 云工作器 了解配置文件配置、放置生命周期和清理。