openclaw worker¶

openclaw worker 是 Gateway 拥有的启动器在已准备好的云端或配对节点 worker 环境中启动时使用的受限运行时入口点。它不是用于手动 worker 注册的通用命令。

Gateway 通过已注册节点的经过身份验证的连接安装匹配的 OpenClaw 捆绑包。worker 启动器使用准备好的分配启动此命令，然后 worker 通过其自己的经过身份验证的出站 WebSocket 以专用的 worker 角色连接回 Gateway。

启动契约¶

该命令从标准输入读取恰好一个有界的 JSON 启动信封。信封携带 Gateway worker 端点、铸造的 worker 凭证、捆绑包和协议身份、所有者纪元、单个分配的会话和轮次，以及为该轮次授权的精确 worker 本地工具名称。Gateway 在交接之前从当前策略解析此最终工具集；原始配置和计划所有者身份永远不会进入 worker 信封。凭证永远不会通过命令行参数接受，并且此页面故意不提供凭证或手工编写的信封示例。

节点监督器使用私有的受管入口点，可以在后台进程保持的同时将连续的轮次接纳到同一环境中。每个轮次仍然接收一个新的有界信封、Gateway 连接和工具权限。上述独立命令仍然是单轮次入口点。

停止节点 worker 环境会取消待处理的接纳，并尝试清理其工作区进程、受管 worker 和持久启动所有者。一个清理所有者中的故障不会跳过其他所有者。停止报告在这些尝试完成后的清理错误；清理仍未确认的启动在恢复成功之前保持其容量预留。在 Stop 等待跟踪的 worker 清理稳定时，同一环境不能接纳另一个轮次。如果初始化失败，独立的清理仍然可以完成，但节点在初始化成功之前不会通告空闲容量。

在当前 Linux 和 macOS 节点主机上，启动日志识别 worker 的进程所有者；应用程序 worker.mjs 作为其子进程运行。所有者在应用程序崩溃后存活，并在释放容量之前保留嵌套命令清理。节点主机重启后，恢复短暂观察该确切的所有者而不终止其清理观察者。未完成的清理保持其槽位预留，而其他空闲槽位保持可用。节点监督器继续观察该清理，并在记录的谱系完成和物理进程树灭绝后自动返回槽位。关闭监督器会放弃并加入其观察而不释放未完成的所有权。状态、启动重放和取消在保留轮次收据时共享相同的恢复；已完成的轮次结果保持不变。此保护需要更新的节点主机以及当前的 worker 捆绑包；仅更新 Gateway 不会替换旧节点的监督路径。

启动必须在每个完整序列化形式中适合 25 MiB：节点调用事件和受管 worker 输入行，包括节点的连接端点。Gateway 在需要时修剪较旧的完整轮次，而不丢弃最新的提供商重放检查点。如果该重放单元无法适合，轮次在交接之前以可见的重试指令失败。受管行限制排除其最终换行符；独立 stdin 计算每个字节。

如果信封无效、凭证被拒绝、捆绑包或协议功能不匹配，或会话和所有者纪元不再当前，接纳会失败关闭。缺失、重复或未知的工具名称也会使信封无效。操作员应通过云端 worker 编排器启动 worker，而不是直接调用此入口点。

如果接纳用尽其 120 秒重试预算，终端错误包括尝试次数、Gateway 主机和端口（或本地套接字路径）以及最后故障。connect failed 表示 WebSocket 未打开；检查可达性和 TLS。no hello within deadline 表示它已打开但 Gateway 未完成 worker 接纳。可重试的接纳拒绝保留其原因。这些有界的、凭证脱敏的详细信息出现在节点启动日志和轮次错误中。

容器启动在创建每个容器之前重新验证固定的守护程序身份。此检查允许繁忙的守护程序 30 秒；超时仍然使启动失败并命名命令。更改的守护程序身份仍然是硬故障。

运行时边界¶

进程使用受限后端运行正常的嵌入式 agent 循环：

• 当 Gateway 颁发的轮次权限中存在时，read、write、edit、apply_patch、exec 和 process 编码工具在 worker 工作区中本地运行。空权限使用无工具的模型运行。
• 模型调用使用 gateway 推理代理。不加载本地模型身份验证配置文件。
• 转录写入使用 gateway 转录提交 RPC。
• 流式传输和工具生命周期更新使用 gateway 实时事件 RPC。
• 仅接受分配的会话和轮次。

Worker 模式不会启动超出分配会话工具集的通道、Gateway HTTP 表面或插件自动启动。它使用一次性状态目录，没有模型提供商凭证。当 Gateway 的有效共享 GitHub 身份可用时，worker 在其私有启动信封中接收轮次绑定的访问令牌。令牌在一次性状态目录内的私有每轮次配置文件中实例化，在下一个绑定之前删除较早的配置文件，并在删除该目录时清除。密封的 worker 启动器将其绑定到每个 exec 子进程。必须在 worker 主机上安装 GitHub CLI；捆绑包包括启动器，不包括 gh。

实例化的技能文件是私有目录中的临时轮次输入，与 worker 状态及其 GitHub 凭证分开。其目录限定于会话和工作区，每个技能路径使用其名称、源和已验证内容的摘要的短可读名称。 未更改的交付以确定性提示顺序重新创建相同的路径，因此后续轮次可以重用提供商的提示前缀，并从较早的轮次读取引用而无需重写转录历史。更改的技能内容接收新路径。worker 通过清理持有文件系统锁；另一个活动轮次不能替换其输入，崩溃恢复仅回收确定死亡的所有者。 失败的每轮次删除记录 Materialized skill cleanup failed。节点 Claude 技能会话单独报告 Node Claude skill session cleanup failed 用于临时 Workshop 配置。这些 有界的、脱敏的警告标识可能保留的文件。在检查权限并手动删除报告的目录之前，等待 worker 或 会话及其拥有的进程停止。仅完成的轮次不意味着受管 worker 已停止。这些文件系统删除故障保留原始成功、错误、 取消或超时，而不会重放工作或声称删除成功。 Worker 状态删除，包括 GitHub 凭证清理，仍然在失败时拒绝。 进程排空、权限撤销、数据库关闭和传输或 MCP 关闭 保留其现有故障行为。无效的技能完整性或交付限制 仍然拒绝轮次。

工作进程通过有界引导加载器加载工作区 AGENTS.md，并将 Gateway 提供的系统指令作为字面文本追加。它不会从工作区或代理状态目录中发现 SYSTEM.md 或 APPEND_SYSTEM.md。

此模式下不暴露工作进程之间的会话分发。放置和分发仍由 Gateway 负责：操作员可以通过 Gateway 分发一个现有的本地、受管 worktree 会话，而工作进程不能分发自身或另一个工作进程。

准备好的任务分配携带转录上下文、已接受的基叶、提交序列和实时事件游标。当工作进程 WebSocket 重连时，进程使用相同的凭证和所有者纪元重新准入，保留已接受的转录基线，重放其未确认的实时事件尾部，并以相同身份重新附加一个进行中的推理轮次。如果错过了流式增量，则终端推理消息是权威的。一个取代的所有者纪元会隔离该进程并导致干净退出。

stale-base-leaf 转录拒绝会故障停止当前运行。工作进程模式不会针对不同的叶重试被拒绝的序列，因此不会产生重复提交；该运行中任何仍未提交的内存尾部都会丢失。重新启动属于 放置，它必须 从 Gateway 的权威转录和提交账本创建一个新的任务分配。同样，Gateway 进程重启会以 provider 错误终止一个待处理的推理轮次；只有工作进程 WebSocket 重连才能 重新附加到同一进程的活动推理流。

Gateway 在确认推理准入之前持久化该准入，并在发布终端消息之前持久化完成。Gateway 关闭和会话生命周期排空也会等待已接受的 provider 和存储工作，包括取消开始时仍在等待的准入。 如果原生存储结算未知，Gateway 会保留该失败，并且不会重试终端写入或重放受影响的推理身份。 独立的关闭清理仍会在报告失败之前运行。

参见 Gateway 协议 了解 封闭的工作进程 RPC 接口，以及 云工作进程 了解 架构和安全模型。