---
summary: "在配对节点上启用工作线程会话托管、选择设备并隔离容器中的工作线程"
read_when:
  - "在配对节点上启用隔离的 OpenClaw 会话托管"
  - "在新会话中选择设备或自动放置"
  - "隔离容器中的托管工作会话"
title: "在节点上托管 OpenClaw 会话"
sidebarTitle: "会话主持"
---

## <a id="host-openclaw-sessions"></a> 主机 OpenClaw 会话

macOS 菜单栏应用程序和无头节点主机可以选择使用相同的节点本地设置进行完整的 OpenClaw 会话托管：

```json5
{
  nodeHost: {
    workerRuns: { enabled: true },
  },
}
```

<Warning>
仅在您信任作为共享网关基础设施的计算机上启用会话托管。托管同意适用于设备，而不适用于个人对其的所有权。现有的会话授权仍然控制谁可以分派工作。
</Warning>

在保留输入或启动工作程序之前，网关将插件 `before_agent_run` 策略应用于 OpenClaw 节点轮次。被阻止的轮次仅保留经过编辑的块消息，并使节点可用于下一轮。该钩子可以查看网关输入和历史记录；节点本地系统上下文稍后组装，并且不包括在内。参见 [hook 边界 ](/plugins/hooks#choose-a-hook)。

启用此设置后重新启动应用程序或节点主机。 macOS应用程序拥有一个配对节点身份，并使用共享节点运行时进行会话托管；不要为同一台 Mac 启动第二个 CLI 节点。其原生相机、屏幕和桌面功能仍保留在该身份上。如果共享运行时无法启动，本机功能仍然可用，但会话托管不可用。

在连接的主机上批准更新的功能表面会自动刷新其会话托管声明和当前工作插槽。网关等待新的声明，然后再使主机再次可用；应用程序或节点主机进程不需要重新启动。

当会话首先需要当前的工作程序构建时，网关会将其密封的工作程序工件发送到配对的主机。节点验证确切的内容哈希，自动发布工件，并在执行模式支持时对其进行预热。该工件包含其完整的 JavaScript 依赖闭包；该节点不安装包或执行生命周期脚本。运行时块被密封并使用工件进行验证，冷工作人员在加载轮次运行时之前完成准入。安装属于会话请求并接收其取消信号。重新连接维护不会安装或预热工作程序构建。

安装后，即使没有会话，持久节点也会为每个网关命名空间保留一个当前工作工件。仅当实时或可恢复的布局需要旧版本时才会保留它们；正常维护会删除未引用的构建。每个新的调度仍然会验证已安装的工件并在有效时重用它，从而避免再次下载。云注册节点保留其自己的特定于执行模式的安装和保留生命周期。

`openclaw devices join-code` 打印的命令通过 `openclaw connect <join-url> --service --session-host` 一步注册并启用服务主机。对于仅命令节点服务，省略 `--session-host`。

要在已配对的无头节点上启用托管，请在该设备上运行：

```bash
openclaw config set nodeHost.workerRuns.enabled true
openclaw node install --force
```

对于进程范围的主机，请使用 `openclaw connect <join-url> --session-host` 在前台注册。连接件 URL 为一次性使用；该过程停止后，使用 `openclaw node run --session-host` 重新启动主机，这将重新使用保存的配对。请参阅 [ 重新连接配对节点 ](/cli/connect#reconnect-a-paired-node)。

主机重新启动后，当节点保存的启动启动标识与当前 OS 启动标识不同时，节点会释放中断的本机工作插槽并记录中断的轮次。节点重新连接后，下一回合即可正常启动。较旧的启动记录和无法读取启动标识的主机保留现有的保守清理检查。容器工作人员仍然需要他们的容器引擎来确认清理，包括当该引擎在另一台主机上运行时。

在 Control UI 新会话中，写范围操作员选择特定的配对设备或 **Auto**。如果没有明确的项目或文件夹选择，**New 工作区** 会启动一个空的隔离工作区，而不需要用户 Git 存储库。选定的 GitHub 存储库或网关 Git 签出仍然是可选源。 OpenClaw 创建会话拥有的托管工作区，使用确切的 `deviceId` 或 `autoDevice: true` 对其进行分派，并仅在所选设备布局变为活动状态后发送第一轮。新会话不绑定 `execNode` 或浏览设备文件系统。

所选模型的 **harness** 也必须支持所选设备。使用 Codex harness的 OpenAI 模型需要该节点上的官方 Codex 插件；仅将其安装在网关上是不够的。在节点上运行：

```bash
openclaw plugins install @openclaw/codex
openclaw node restart
```

如果插件已安装但已禁用，请在重新启动之前使用 `openclaw plugins enable codex` 显式启用它。批准网关上节点更新的命令界面。选择器将保持设备对 Codex 不可用，直到它通告命令并完成批准。或者，选择使用 OpenClaw harness的模型；当您启用会话托管时，OpenClaw 不会静默切换harness或安装 Codex。

在 POSIX 主机上，OpenClaw 将其托管工作区目录保持私有 （`0700`），包括当主机使用 umask `0002` 时。重新打开时，现有节点拥有的工作区祖先会被收紧，因此更新后传输可以恢复，而无需更改主机的 umask。传输的工作区中的文件保留其清单权限。

设备页面显示节点元数据中经过验证的网关拥有的工作线程版本。如果当前工件丢失或验证失败，设备会显示 **worker Missing** 警告；显式新会话会安装当前包。此状态是观察性的和重新连接范围的：启动仍然需要确切的持久收据和当前节点权限。

Node 主机必须支持当前专用工作人员-主管方言，然后才能托管会话。旧的连接主机仍然可见，但在会话选择器中被禁用。更新该设备上的 OpenClaw 并重新连接；对于无头节点，运行 `openclaw update`，然后运行 ​​`openclaw node restart`。网关不会回退到节点的本地 OpenClaw 包或较旧的主管方言。

OpenClaw 工作线程还需要一个支持网关捕获的执行策略的节点。如果您先更新网关，旧节点将显示 **OpenClaw 会话需要更新**，直到您更新并重新连接它们。他们的 Codex 远程执行和其他批准的节点命令保留了现有的要求。首先更新节点仍与旧网关兼容；仅当网关理解时，节点才会通告此支持。

当更新 `2026.9.8` 网关之前的节点时，该节点会为其提供的工作程序包保留该网关的 Skill Workshop 启动绑定。普通归因聊天轮流继续工作，无需同时更新双方。

当网关和节点主机都支持 `node-worker-status-wait-v1` 时，轮次完成使用有界状态等待。一旦记录了确切回合的最终结果，节点就会唤醒等待的请求；成绩单结算和工人清理所有权保持不变。此可选功能支持混合 Gateway/node 版本：首先更新任一侧，较旧的节点主机继续使用状态轮询。较新的节点仅将 `workerHost.statusWait: 1` 通告给通告该功能的网关。重新连接重新协商支持。

托管轮次使用与网关本地轮次相同的准备工具表面和 agent/session 策略。工作区文件和流程工具在节点上执行；网关拥有的工具，包括网络搜索、内存和会话发现，通过轮流的实时权限和工具挂钩在网关上执行。工具定义带有其执行位置，因此新的网关工具不需要单独的节点白名单。

面向模型的工具使用与本地轮流相同的代码模式或工具搜索演示，包括网关的解析模型设置和限制。代码模式在节点上运行，并在其声明的执行位置调用每个目录工具。它的目录和待处理单元属于当前回合；保留的工人在下一个回合会收到新的演示文稿。 Node 工作人员使用 `dispatch_action` 进行工具搜索，包括配置目录模式时。

并发网关工具调用会等待现有的传输预算，因此较大的模型工具批次不会丢失调用。取消和心跳保持独立。

仅当节点声明其功能时才提供本地放置工具。不可用的放置或传输功能会记录在网关日志中。在节点上更新 OpenClaw 并重新启动它以启用更新的本地工具。网关操作使用匹配的下载的工作包，并且不依赖于安装的管理程序识别其工具名称。更新的节点继续通告旧网关所需的网关工具，并在节点首次更新时保留这些工具。

此设置允许受监督的会话打开配对设备，包括网关拥有的工作区传输和结果协调。网关在工作人员开始使用工具之前准备工具定义和文件系统策略。托管轮次遵循全局和特定于代理的 `tools.fs.workspaceOnly`、`tools.exec.applyPatch.enabled` 和 `tools.exec.applyPatch.allowModels`，具有与本地轮次相同的会话权限模式优先级。工作空间包含使用分配的节点工作空间。模型读取预算和图像清理也来自网关；工作人员不会从空配置中重建它们。网关在每一轮的工作进程准入响应中都包含此工具目录和策略，包括在重用热工作进程时。保留的进程接收当前回合的目录和生成，因此回合不需要单独的发现请求。这使用了现有的构建绑定工作器工具功能：工作器和网关必须运行相同的包。经过身份验证的准入响应使用与工作器推理相同的协商有效负载预算，因此完整的工具目录不受较小的控制帧限制的限制。过大的目录会显式失败而不是被截断。该目录不授予执行权；每个网关工具调用仍然会检查实时转向声明。

在工作区协调之前，通过节点传输复制指定工作区内的工作人员回复附件。相对和绝对 `MEDIA:` 路径使用工作人员的字节，包括已完成的实时回复。该工作空间之外的原始路径会产生远程文件附件错误；允许的托管媒体引用和 HTTP URL 保留其现有的传送策略。最终聊天完成仍需等待协调并包括任何冲突摘要。

默认情况下，每个节点的每个可用 CPU 核心都有一个工作插槽。使用 `nodeHost.workerRuns.capacity` 配置插槽数。超出容量启动时，最多需要等待 10 秒才能获得持久插槽。仅被空闲worker占用的slot可以被回收用于新的work；活动回合和后台命令保留其插槽。当没有剩余空闲或可回收时隙时，该节点保持可用于状态和取消，但不会被选择用于新的会话轮次。

容量、主机状态和技能箱更新不会中断活动节点的工作或更改其配对权限。此行为需要更新的网关；节点配置和存储的配对保持不变。

轮次稳定后，OpenClaw 可以保留其工作进程最多两分钟，因此立即跟进可以避免再次加载运行时。计时器在工作人员确认轮次清理完成后启动。每个节点最多保留两个空闲worker，受其配置容量限制；当需要空间时，它首先让最近最少闲置的工人退休。空闲工作线程仍然使用内存：即使对于小型会话，每个保留工作线程及其监督进程也预计有数百个 MiB，在大量工作后可能会出现更大的堆。工作人员是轮流启动的，而不仅仅是激活一个安置。

空闲重用需要网关、节点和已安装的工作程序包通过 `node-worker-idle-retention-v1` 功能提供支持。较旧的组合保留其现有的后台命令保留行为。每个重复使用的轮次仍然会获得新的凭证、准入、历史记录、执行策略和轮次配置文件。输入idle会关闭轮次连接，加入其可写清理，并删除已完成的轮次的临时配置文件。后台命令仍然受到保护，免受空闲驱逐和超时的影响；他们的现有环境和凭证生命周期将一直适用，直至完成。

在进程和容器模式下，空闲保留使用与后台命令保留相同的工作区协调合同。两个合约都不会暂停工作进程。工作区清单的捕获、验证、更新和最终验证检测并发更改；冲突或失败的栅栏使用现有的协调和恢复流程。保留一个固定的运行时间并不授予它进行另一回合的权力。

断开连接、节点关闭、更新暂停或放置拆卸会通过正常的进程树或容器清理来淘汰空闲工作人员。重新连接会等待清理，然后再发布新容量。如果空闲清理失败，正在运行的 Supervisor 将保留其插槽并在两分钟后重试。停止、移动和回收保留其确切的展示位置所有权检查；崩溃或重新启动后，空闲的工作人员永远不会恢复。聊天 **Stop** 取消活动工作，并且在没有轮流运行时不会刷新空闲工作人员。使用placement Stop或reclaim立即释放。没有单独的怠速保持设置。

即使工作人员在停止时遇到错误，停止活动的托管轮次也会记录已接受的取消。工作器诊断单独保留关闭故障。仅当其进程树或容器完成清理后，工作槽才可用。

当应用程序工作线程或节点主机崩溃且网关提供的工作线程包支持进程沿袭时，当前的 Linux 和 macOS 节点主机还会保留清理所有权。更新网关并更新并重新启动节点主机以接收此保护；单独安装新的工作包不会更新节点的管理程序。当前一个所有者完成停止其命令时，恢复会保持容量被占用。升级后的节点主机会保留已发布的启动消息以及旧工作包的分离进程组所有权。

安装的节点主机单独打包 POSIX 启动帮助程序，以减少每轮启动工作。更新并重新启动节点主机即可获得此改进。工作进程在开始轮流之前仍然等待其持久启动收据，并且清理继续保留其工作进程槽，直到进程树消失。

选择器从 `environments.list` 派生每个设备行。每个选定的运行时都需要一个可用的、已连接的配对会话主机。 OpenClaw 工作线程还需要捕获的执行策略支持和有效的精确工作线程槽位，以及至少一个空闲或可回收的空闲槽位。 Codex 配对设备执行直接启动其执行服务器，因此它不消耗或不需要工作槽。其所需的命令必须出现在节点的有效 `invocableCommands` 中，而不仅仅是其声明的功能。仅当批准的配对和网关命令白名单都对其进行授权时，声明的命令才可用。连接的非主机、不合格或饱和的主机、需要更新的设备和不可用的主机仍然可见，但由于可操作的原因而被禁用。会话选择器和命令选项板显示这些计算机的警告图标和 **Unavailable**。聚焦或点击该行可了解其无法举办会话的原因；命令选项板显示一个不可用的行，而不是重复项目选择。对于已配对的无头节点，启用 `nodeHost.workerRuns.enabled` 并运行 `openclaw node install --force`，如上所示。需要更新的主机必须在选择之前升级并重新启动。

当节点清单刷新时，或者如果刷新失败，选择器将保持已知设备可见，但禁用远程选择和启动，直到新清单到达。本地仍然可以选择；缓存的工作槽永远不会授权新的远程会话。

选择 **Auto** 让网关选择合格的配对、连接的会话主机。对于 OpenClaw 工作轮次，它首先优先选择相对于工作人员容量而言承认工作较少的主机。然后，在考虑仍在启动的调度后，它会比较空闲和可回收的空闲工作线程槽位，并通过设备 ID 中断剩余的连接。会话的放置本身并不保留工作槽位。不消耗工作线程槽的运行时会选择具有最低设备 ID 的合格主机。

如果选定的主机在工作区准备开始之前变得不合格，则网关会在确认所有失败的分配已被清除后，尝试下一个排名的主机，总共最多三台主机。其他调度失败立即返回；自动永远不会重播工作区准备工作或已开始的工作。一旦工作区准备被允许，另一轮填补主持人的空位并不会取消它；当会话启动轮次时，节点检查物理容量。 Node 身份和命令授权在整个准备过程中保持检查。

如果没有符合条件的主机，该错误会解释是否没有设备启用会话托管、主机已断开连接或已满、主机需要更新或所选运行时不受支持。当前的配对、连接和命令错误优先于之前通告的工作插槽。调度响应标识所选择的设备。

当已知会话主机断开连接时，其配对设备记录仅保留最后接受的当前 v6 托管同意。脱机行保持可见并禁用，状态为不可用。当前禁用或空的 v6 发布记录 false；较旧的 v1-v5 和需要更新的方言不会覆盖最后的当前事实。连接的库存总是胜过存储的历史记录，丢失的存储值意味着错误，并且确切的工作插槽永远不会保留或显示为离线容量。

如果设备离线，其活动放置仍保持活动状态：可用性是进程当前的，而不是终端放置状态。 `sessions.list` 和 `sessions.describe` 项目 `runner: { kind: "device", status: "offline" }` 直到确切的当前 v6 节点运行程序重新连接。因此，网关重新启动会将活动设备放置显示为离线，直到重新连接为止；然后，当前库存将投影更改为 `available` 并发出会话刷新。精确的工作槽位仅对运行时消耗工作槽位的新展示位置进行门控；它们不会影响 Codex 远程执行或现有会话的可用性。

Control UI 显示 **设备离线** 并默认等待，不放弃放置、工作空间或权限。设备返回后重试下一轮。 **在网关上继续…** 是一个单独的破坏性选择：它隔离设备所有者并从最后一个网关同步工作区继续，而不重播中断的回合。未同步的设备文件和正在进行的工作可能会丢失。配对节点在准确记录的断开连接后将保持休眠状态 14 天；在该边界，其旧工作环境被视为已消失，并且会话放置正常协调。配对本身仍然存在，因此稍后重新连接可以提供新的环境。没有确切节点断开历史记录的旧配对将保留故障安全状态，而不是因不相关的设备活动而过期。删除设备配对、静默修剪被取代的配对或仅删除其节点角色会首先使客户端失效，然后运行目标环境和位置协调；显式删除在返回成功之前等待凭证围栏，并且定期扫描重试失败的提供程序或放置清理。

当设备运行程序不可用时（包括禁用会话托管之后），网关会暂停咨询磁盘空间检查并保留该放置的最后一个示例。当前跑步者重新连接后，检查将在下一次计划的扫描中恢复。禁用托管不会放弃会话的工作区。

网关对包含放置的远程工作区的卷进行采样。新的展示位置、展示位置活动和跑步者可用性更改会在下一次维护阶段刷新示例。未更改的空闲放置可重复使用其成功样本最多 15 分钟。示例是建议性的，不会阻止轮流或工作区写入。

有关 Control UI 行为和存储源，请参阅 [Anthropic：跨计算机的 Claude 会话](/providers/anthropic#claude-sessions-across-computers)。

### <a id="work-in-an-existing-device-folder"></a> 在现有设备文件夹中工作

默认情况下，会话托管允许现有文件夹。要将会话限制到特定目录根，请配置配对设备：

```json5
{
  nodeHost: {
    workerRuns: {
      enabled: true,
      folders: ["~/Projects"],
    },
  },
}
```

`nodeHost.workerRuns.folders`共有三种模式：

- Unset：允许任何现有目录，但文件系统根目录和与私有工作存储重叠的目录除外。该节点通告现有文件夹支持。
- A 非空列表：仅允许那些根目录及其子目录。
- `[]`：现有文件夹会话已禁用，节点不通告支持。

路径必须是绝对路径或相对于主目录的路径 （`~/`）。该节点解析符号链接并在每次使用时检查目录；符号链接无法转义已配置的根。更改设置后重新启动节点主机。

此默认值使用现有的会话主机信任边界：操作员已经可以在节点上使用 exec 运行代理。文件夹限制是可选的护栏，而不是执行沙箱。仅在受信任的设备上启用会话托管；如果您不希望不受限制的就地文件夹选择，请使用狭窄的根列表或 `[]`。所选文件夹将成为会话工作区根目录，因此包含 `operator.write` 与 `tools.fs.workspaceOnly` 会话的部署还应设置根列表。

对于通告 `workerHost.deviceFolders: true` 的特定配对设备，请在工作区选取器中选择 **设备上的现有文件夹**，然后输入该设备上的绝对路径。此选项不适用于 **Auto**、云工作线程、没有工作轮流执行的运行时或不公布该功能的设备。设备验证文件夹；网关不会在本地浏览或解析此路径。

会话记录 `deviceFolder: { deviceId, path }` 并分派到该确切设备。请勿将 `deviceFolder` 与项目、存储库、托管工作树或网关 `cwd` 组合。工作人员就地使用现有文件夹：OpenClaw 不会创建工作树、传输工作空间或将其文件协调回网关。在授予代理写入权限之前备份重要文件。会话显示保留设备和文件夹路径。删除会话不会删除现有文件夹。

设备文件夹会话无法移动到其他设备或在网关上继续。这些会话不支持附件暂存；当您需要上传附件时，请使用托管工作区。网关文件面板和工作区显示对于设备文件夹会话不可用；请改用所选设备上代理的文件工具。网关文件操作拒绝这些会话，而不是读取或写入类似名称的本地工作区。

### <a id="isolate-hosted-worker-sessions-in-containers"></a> 隔离容器中托管的工作线程会话

默认情况下，托管 OpenClaw 工作会话直接在配对节点上运行。在该节点上将 `nodeHost.workerRuns.isolation` 设置为 `"container"` 以在其自己的容器内运行每个工作线程：

```json5
{
  nodeHost: {
    workerRuns: {
      enabled: true,
      isolation: "container",
      // Optional: use a digest-pinned, private-registry, or preloaded image.
      // containerImage: "registry.example.com/openclaw/node:24.21.0-slim",
    },
  },
}
```

更改任一设置后重新启动节点主机。隔离默认为 `"none"`，保留现有的直接进程行为。此设置在节点本地强制执行；网关无法默默地禁用它或回退到未隔离的工作线程。

Linux和macOS节点主机支持容器隔离； Windows 不受支持，因为本机 Windows 路径无法安装在容器内的原始路径上。该节点必须具有工作的 Docker- 兼容容器引擎。 OpenClaw 首先尝试 `docker` CLI，包括 Docker- 支持的 OrbStack 安装，然后是 `podman`。当节点主机启动时会检查所选的引擎和守护程序，并在创建每个容器之前再次检查。如果平台不受支持，则两个引擎都无法工作，或者守护程序发生更改，会话托管或受影响的启动将明显失败，而不是回退到未隔离的工作线程。安装或启动引擎，验证`docker version`或`podman version`，然后重新启动节点主机。

在每个容器启动之前，守护进程身份重新验证最多允许 30 秒。如果引擎命令超时，启动错误会命名引擎和操作（例如，`docker info`）及其截止时间。它省略了命令参数和环境值。在重试之前，根据所选守护程序检查该操作。

默认图片为`node:24.21.0-slim`；当它尚不存在时，引擎会在第一次使用时拉动它。设置 `nodeHost.workerRuns.containerImage` 以选择摘要固定映像、私有注册表映像或引擎已可用的映像。映像必须在其标准可执行搜索路径上提供受支持的 Node.js 24.16+ 或 26.1+ 运行时。如果无法拉取映像、无法访问映像或未提供合适的 Node.js 运行时，则会话启动会明显失败；它永远不会作为裸主机进程重试。在脱机或受限节点上托管会话之前预加载映像或配置注册表访问。当 OpenClaw 更新其依赖项时，默认映像可以前进。在升级离线节点之前，请预加载新的默认映像或将 `nodeHost.workerRuns.containerImage` 设置为该节点上已缓存的受支持映像。例如，缓存的 `node:24.19.0-slim` 仍然受支持并且可以显式选择。保留现有的显式图像设置；在升级 OpenClaw 之前替换不受支持的 Node 映像。 Worker 启动需要受支持的运行时；在运行时诊断运行之前，旧版本可能会失败。

每个工作容器将其已验证的工作包根挂载为只读，并将其分配的会话工作空间挂载为读写。当工作线程的私有 HOME 与该工作空间不同时，它会收到 HOME 的第三个读写挂载。对于现有文件夹会话，此私有 HOME 属于 OpenClaw 的命名空间会话生成存储，并遵循其租用和保留生命周期；它不是节点用户的主目录。收集该私有状态不会删除用户拥有的现有文件夹。

这些目录安装在其原始绝对主机路径上，因此密封包和工作空间描述符仍然有效；会话工作空间也是容器工作目录。 OpenClaw 仅通过现有的冻结、非秘密工作环境白名单，并且不添加其他主机挂载。容器隔离保护主机文件系统的其余部分并分离工作进程，但工作进程仍然可以修改其分配的工作空间和私有 HOME 并连接到网关。

容器使用引擎的正常出站网络，并且必须能够到达网关工作线程 WebSocket 端点。在节点主机上工作的网关地址（例如 `127.0.0.1` 或 `localhost`）在工作程序使用时会指向容器；配置可从容器网络访问的网关地址。如果网关需要自定义证书颁发机构，则 `NODE_EXTRA_CA_CERTS` 必须指向已安装的捆绑包或会话工作区中已有的证书； OpenClaw 不会为其挂载另一个主机路径。容器隔离会话不支持需要访问仅主机浏览器状态的浏览器分配。

取消和防护会终止容器本身，而不仅仅是容器引擎客户端。节点主机记录容器的持久引擎和容器身份，在重新启动协调期间检查该身份，并删除标记为同一网关的孤立工作容器。如果节点主机进程意外退出，正在运行的容器可以存活到下一次节点主机启动；如果清理窗口必须保持较短，请将节点主机置于重新启动的服务下。