openclaw 可执行文件,使用
Gateway 网关 WebSocket 协议作为其控制平面,并将子进程视为
可替换的运行时。这样可明确进程所有权、就绪状态、故障恢复
和升级,而无须依赖 OpenClaw 的私有状态布局。
有关客户端身份验证和重连状态,请阅读
构建 Gateway 客户端。
使用嵌入预设启动子进程
使用真实的node_modules 安装并生成软件包可执行文件。对于负责
设备发现、重启和渠道生命周期的宿主,一个实用的基准配置是:
PATH 中存在项目本地的 openclaw 二进制文件。该示例
继承输出,因此子进程不会因 stdout 或 stderr 管道已满而阻塞。如果宿主
改为捕获这些流,请在生成子进程后立即附加使用方。
--allow-unconfigured 仅绕过 gateway.mode=local 启动保护。
它不会写入配置或修复无效文件。当嵌入应用通过新手引导、配置 CLI
或 Gateway RPC 提供常规本地配置时,请省略此项。
Electron shell 快照警告
Shell 快照捕获会从登录 shell 运行process.execPath -e <script>。在
普通 Node 进程中,process.execPath 是 Node 可执行文件。在 Electron 下,
它是 Electron 二进制文件,可能会将调用解释为应用启动,
并显示“Unable to find Electron app”弹窗。请在 Gateway 网关子进程的
环境中设置 OPENCLAW_EXEC_SHELL_SNAPSHOT=0,而不只是在渲染器进程中设置。
出于同样的原因,hostNodeExecutable 必须指向真实的 Node 运行时,
而不是 Electron 的 process.execPath。
按退出代码处理无效配置
对于配置类启动失败(包括无效配置),Gateway 网关启动使用退出代码78(EX_CONFIG)。应根据退出代码进行分支处理,
而不是抓取供人阅读的 stderr:
- 针对与 Gateway 网关子进程相同的配置和
状态环境运行
openclaw doctor --fix --yes --non-interactive。 - Doctor 成功退出后,重试一次 Gateway 网关启动。
- 如果子进程再次以
78退出,请停止修复循环,并向用户显示配置 失败。
等待协议就绪
使用 WebSocket 信号,而不是日志子字符串:- 打开 Gateway 网关 WebSocket。
- 等待
connect.challenge事件。它证明监听器已接受 WebSocket,并且可以开始质询握手。 - 发送带有质询绑定设备签名的
connect。 - 将
hello-ok视为已通过身份验证的 RPC 的应用就绪信号。
connect 会返回可重试的 UNAVAILABLE 错误,其中包含
details.reason: "startup-sidecars"、有界的 retryAfterMs,然后使用代码
1013 和原因 gateway starting 关闭。
使用来自 @openclaw/gateway-protocol/startup-unavailable 的
resolveGatewayStartupRetryAfterMs 或参考客户端的内置
策略,然后重新连接。
解释重启和关闭
在有序关闭之前,Gateway 网关会广播一个包含reason
和 restartExpectedMs 的 shutdown 事件。非空的 restartExpectedMs
表示预期进行进程内或受监管的重启;null 表示最终关闭。
这两种情况下,后续 WebSocket 关闭代码都是 1012。
普通客户端的关闭原因在两种情况下也都是 service restart,因此关闭代码和
原因都无法区分重启与关闭。当先前的 shutdown 载荷到达时,请将其保留,
并结合宿主自身的停止意图和子进程退出状态进行判断。如果连接在没有该事件的情况下
消失,请使用常规的有界重连和子进程监管策略。
使用 RPC,而不是状态文件
让 Gateway 网关成为 OpenClaw 状态的唯一所有者。常见的嵌入操作 已有相应的 RPC 方法:config.get 会在返回快照前隐去敏感值和 SecretRef 标识符。
写入方法也会返回已隐去敏感信息的配置。客户端必须将隐去标记视为不透明值,
并使用文档记录的配置写入契约;绝不能期望 Gateway 网关返回明文密钥。
不要通过读取或修改 ~/.openclaw 下的文件、SQLite 表、对话记录文件
或缓存目录来实现应用功能。这些布局是私有运行时实现细节,
可以在不保持协议兼容性的情况下移动或更改。
安装;不要扁平化
根openclaw 软件包不是单文件内嵌目标。dist/extensions
下的内置运行时文件保留 openclaw/plugin-sdk/* 等裸自引用导入,
而 npm 软件包会有意排除每个扩展的 node_modules 目录树。
通过 npm、pnpm 或其他常规 Node 软件包安装方式安装 OpenClaw,以便
Node 能解析软件包导出和根依赖树。生成已安装的 openclaw
可执行文件。不要只复制 dist,不要将软件包扁平化到应用
捆绑包中,也不要内嵌选定的扩展文件。