OpenClaw 外部应用集成指南Gateway 协议、RPC 客户端与主机协同挂起【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw外部脚本、Dashboard、CI 任务、IDE 插件以及各种独立进程都可以通过 OpenClaw 的 Gateway 协议与 Agent 运行时通信——它基于 WebSocket 传输加 RPC 方法用于启动 Agent 运行、订阅事件流、等待结果、取消任务或检视 Gateway 资源。本文以 docs/gateway/external-apps.md 为主线完整讲解外部应用的集成路径选择、RPC 调用策略、agent.wait语义以及面向托管平台云函数、容器快照、冷启动的**协同主机挂起Cooperative Host Suspension**握手协议并结合仓库源码说明其实现原理与边界。集成前的路线选择外部应用 vs 插件代码写代码之前先回答一个问题代码运行在 OpenClaw 进程之外还是之内这决定了你该使用 Gateway RPC 还是 Plugin SDK两者不可混用。运行在 OpenClaw 进程外部的代码走 Gateway RPC启动或观察 Agent 运行的 Node 脚本调用 Gateway 的 CI 任务Dashboard 与后台管理面板IDE 扩展不需要变成频道插件的外部桥接程序使用真实或伪造 Gateway 传输的集成测试运行在 OpenClaw 进程内部的代码走 Plugin SDKProvider 插件频道Channel插件工具Tool或生命周期Lifecycle钩子Agent harness 插件受信任的运行时辅助代码外部应用不应导入openclaw/plugin-sdk/*子路径这些子路径只面向被 OpenClaw 加载的插件正确的插件入口见 Plugin SDK 总览。区分这两种形态是本文后续所有内容的前提。今日可用的集成表面Surface官方文档对当前可用的集成入口做了一个清单按“表面Surface、状态、用途”三列组织表面状态用途Gateway 客户端指南稳定包npm 包、认证、重连、历史、事件、审批与版本策略嵌入 OpenClawRelease train子进程环境、就绪性、生命周期、恢复、RPC 所有权与打包Gateway 协议ReadyWebSocket 传输、连接握手、认证范围、协议版本与事件Gateway 协议 RPC 方法ReadyAgent、会话、任务、模型、工具、产物与审批的现行 Gateway 方法openclaw agentReady当“shell 出去调用 CLI”就够用时的一次性脚本集成openclaw messageReady从脚本发送消息或频道动作其中“稳定包”指 Gateway 客户端指南 钉住了经验证的稳定版2026.8.1npm 包并解释了包版本与线路wire版本如何影响兼容性。如果你的应用把 Gateway 作为子进程来监管还需要阅读 嵌入 OpenClaw。推荐集成路径五步走官方推荐的接入流程可以概括为五步运行或发现一个 Gateway。通过 Gateway 协议 建立连接WebSocket 传输 连接握手 认证范围。调用 Gateway 协议 RPC 方法 中已文档化的 RPC 方法。钉住你测试所用的 OpenClaw 版本。升级 OpenClaw 时重新核对 RPC 参考。对于 Agent 运行从agentRPC 入手并搭配agent.wait获取终态结果对于持久会话状态使用sessions.*方法对于 UI 集成订阅 Gateway 事件只渲染你的应用能理解的事件族。agent.wait的语义陷阱agent.wait可能在排队时返回status: pending。一个没有终态元数据的超时响应意味着等待已过期继续等待或消费生命周期事件。终态的status: error可能代表取消其中stopReason: superseded表示一个新的会话写入者取代了本次运行。呈现结果时请保留该原因不要把它吞掉。这一约定与 Agent loop 概念、Agent runtimes 概念 中的运行生命周期是一致的设计外部应用不应假设“返回了就是成功”。协同主机挂起Cooperative Host Suspension这是本文的技术核心托管平台hosting controller在冻结或快照一个正在运行的进程之前可以调用一套与宿主环境无关host-neutral的挂起握手让 Gateway 先收敛自己的工作再被安全地快照。典型场景云函数 / Serverless 平台、容器编排平台在冷启动、迁移或发布更新时冻结进程macOS/iOS/Android 节点被系统挂起。Gateway 需要一种“先确认无活跃工作、再冻结”的机制避免在写一半状态时被快照导致损坏。挂起握手五步协议停止由宿主控制的外部入口ingress放行——这一步由宿主负责Gateway 不代管。调用gateway.suspend.prepare携带稳定且唯一的requestId。如果返回busy保持进程运行稍后重试。若要一边保持入口关闭、一边等已接纳的工作收尾请求可选的drain 模式并轮询gateway.suspend.status。如果返回ready保存返回的suspensionId然后在expiresAtMs之前冻结或快照进程。解冻后或放弃挂起时调用gateway.suspend.resume并携带该suspensionId通过现有或重新认证的 WebSocket 发送。CLI 等价命令是openclaw gateway suspend与openclaw gateway resume suspensionId详见 CLI gateway 查询命令。RPC 契约四个方法方法所需 scope参数说明gateway.suspend.prepareoperator.admin{ requestId: stable-host-operation-id, terminalPolicy: preserve, drain: true }准备挂起可带 drain 与终端策略gateway.suspend.statusoperator.read{ suspensionId: id-from-prepare }轮询租约状态与活跃工作gateway.suspend.resumeoperator.admin{ suspensionId: id-from-prepare }解冻后恢复调度与入口gateway.suspend.handoffoperator.admin{ suspensionId: id-from-prepare, target: { pid: 123, processInstanceId: id-from-system-info } }显式授权中断剩余工作并武装重启清理源码佐证见 src/gateway/methods/core-descriptors.tsgateway.suspend.prepare声明于协议版本2026.7scope 为operator.admin并带startup: true与controlPlaneWrite: true标记gateway.suspend.status为operator.readgateway.suspend.resume注释明确写着“Resume 是安全逃生口不能放在写速率限制之后”gateway.suspend.handoff于2026.9加入同为operator.admin且计入控制面写入预算。方法注册表位于 src/gateway/methods/core-descriptors.ts对应的since版本约束由 src/gateway/methods/core-descriptors.since.test.ts 测试固化。参数细节与 ID 约束terminalPolicy与drain都是可选参数。terminalPolicy只接受preserve或terminate默认preservepreserve开放的终端会话会阻塞挂起。适用于必须保留运行进程的主机冻结/快照操作。terminate进程内开放的终端会话不阻塞挂起。适用于将重启 Gateway 的发布更新。注意准备阶段不会关闭终端真正让 PTY 与命令结束的是 Gateway 重启本身。drain默认false。终端策略对“立即准备”和“drain 模式”同样生效。挂起的待落盘的最终聊天状态写入terminal-persistence以及所有其他被追踪的工作在任何策略下都阻塞准备。ID 会被 trim必须包含至少一个非空白字符长度限制128 字符。响应形状busy 结果status: busy附带reason、retryAfterMs、activeCount、blockers。ready 结果{ status: ready, suspensionId: 2c3f..., expiresAtMs: 1770000000000, activeCount: 0, blockers: [] }drain: true 且发现活跃工作准备会获取一个可续租的租约暂停新的自动 cron 调度关闭与无关新工作的入口返回{ status: draining, suspensionId: 2c3f..., expiresAtMs: 1770000000000, retryAfterMs: 20000, activeCount: 2, blockers: [ { kind: root-request, count: 1, message: 1 active request }, { kind: terminal-session, count: 1, message: 1 open terminal session } ] }blockers里是非零的类别计数与有界的任务细节activeCount是聚合的追踪工作总数。这不是一个通用的进程静默屏障频道健康、维护、缓存刷新、已建立的插件 WebSocket 会话以及未注册的插件自有后台工作都可能保持活跃。托管平台必须对整个进程树及其文件系统做一致的冻结/快照——未注册的工作无法被这套第一版契约证明为空闲。drain 模式下的准入Admission行为在 drain 或 prepared 状态下Gateway 仍接受经过认证的 operator WebSocket 连接让控制器可以重连、检查、续租或释放自己的租约但新的 node 与 worker 连接保持围栏fenced。prepared 状态会围栏除gateway.suspend.*之外的所有方法唯一例外是“恰好一个、绑定前驱predecessor-bound的重启”——该例外要求一次非 safe的gateway.restart.request其target必须匹配当前存活的 Gateway locksafe 与无目标的重启请求仍被围栏。在 Gateway 仍处于 draining 时该重启 RPC 例外不可用。控制器可以在解冻后重连并调用 resume。完全无法讲 WebSocket 的宿主仍可使用 Admin HTTP RPC 插件——该插件在 prepared 租约期间仍可路由gateway.suspend.prepare、gateway.suspend.status、gateway.suspend.resume与精确目标的非 safegateway.restart.request见 docs/plugins/admin-http-rpc.md。如果所有控制路径都丢失两分钟租约到期会自动重开准入不会永久卡死。就绪性与健康探针行为挂起期间draining 或 ready/healthz保持存活/readyz返回503。本地或已认证的就绪响应包含gateway-draining未认证的远程探针只收到{ ready: false }。HTTP 健康探针、已认证 operator WebSocket 上的挂起方法、已启用的 Admin HTTP RPC 路由保持可用其余无关 RPC 返回可重试的UNAVAILABLE。内置 HTTP 用户工作路由与普通插件 HTTP 路由含 OpenAI 兼容 API、工具/会话操作、node 监听、已配置的 hooks返回503且error.code: gateway_unavailable新建的插件自有 WebSocket 升级同样返回503。租约生命周期续租、冲突与到期挂起租约的预算、续租与恢复语义非常明确控制器必须精确遵守两种租约draining 与 ready共享两分钟预算从工作检查开始前起算准备阶段耗尽预算会恢复调度并失败而不是返回一个过期租约。时钟回拨不会延长预算。在expiresAtMs之前用相同的requestId、相同的终端策略、相同的 drain 模式重复prepare可以续租同一个suspensionId除非已武装了重启 handoff改动其中任何一项都会与现有租约冲突。常规轮询请用status把prepare留给续租避免消耗写预算。显式 resume 与租约到期都会在重开准入之前恢复调度。租约仅存于内存Gateway 进程退出即消失。在 ready 租约期间到期的重启发射restart emission会等待租约恢复进行中的重启会让 prepare 返回busy。轮询gateway.suspend.status时请遵守返回的retryAfterMs只要 blockers 还在status 返回status: draining并附带expiresAtMs、retryAfterMs、activeCount、blockers每次 status 调用都会刷新活跃工作快照所有 blocker 结束后同一租约转为{status:ready,expiresAtMs:...}。未持有挂起时 status 返回{status:running}查询另一个活跃租约会返回冲突且不暴露其标识符。resume 成功返回{ok:true,status:running,resumed:true}重复调用已成功的 resume 返回resumed: false。竞争性 requestId 或瞬时调度器恢复失败返回可重试的UNAVAILABLE及retryAfterMs不匹配的 resume ID 返回INVALID_REQUEST。调度器恢复期间prepare/status/resume 都返回该错误Gateway 保持 not-ready 且 fail-closed宿主不得冻结或快照它OpenClaw 自动重试调度器恢复成功后才重开准入。prepare受 Gateway控制面写入限制每分钟 30 次请遵守返回的重试延迟。WebSocket 客户端按“设备 IP”分桶Admin HTTP 控制器按解析后的客户端 IP 分桶——同一个代理后面的多个控制器共享一个预算。非 drain 模式纯拒绝refuse-only不带drain: true时准备是纯拒绝语义OpenClaw 关闭新的 root/session/command 准入暂停自动 cron 滴答并同步检查工作。若发现任何活跃项就在返回busy前恢复调度器并重开准入——不会中断或排空该工作。带drain: true时同一挂起所有者改为保持准入关闭、cron 调度暂停直到现有工作 settle已归属的 cron 完成与对账继续执行。发布更新场景与 handoff 武装官方给出了一个贴合实际的分步示例**发布更新release update**用同样的握手但terminalPolicy: terminate避免开放终端无限期拖住 drainopenclaw gateway call gateway.suspend.prepare \ --params {requestId:release-update-1,terminalPolicy:terminate,drain:true} \ --json等待租约变为ready后再执行受检重启。终端命令与回滚缓冲区scrollback在重启后不会恢复参见 重启恢复 的 “What is not resumed” 一节。如果外部部署控制器在自己的优雅 drain 预算之后显式授权中断剩余工作可以调用gateway.suspend.handofftarget必须匹配挂起前从system.info拿到的pid与processInstanceId。这为该确切租约 该主机迭代的下一次SIGTERM武装重启清理不会发送信号也不会创建继任者——原生服务重启仍由控制器负责。成功响应为{ status: armed, suspensionId: ..., expiresAtMs: ... }。武装随租约到期而失效重复 prepare 或 handoff不会延长武装权限resume、替换、另一个被接受的周期动作或主机退役都会使其失效。待决的最终聊天持久化会拒绝武装并在SIGTERM消耗该武装时再次检查若检查拒绝Gateway 记录日志并保留普通优雅停止行为。被接受的 handoff 走现有的重启恢复与中止清理然后为外部控制器退出没有武装的普通停止仍会等待活跃工作。控制器必须对不支持的方法或被拒绝的 handoff 保持克制draining 租约本身绝不授权中断。源码中的校验逻辑位于 src/gateway/server-methods/suspend.tshandoff 处理器会核对params.target.pid ! process.pid或processInstanceId不匹配时返回UNAVAILABLE“gateway process changed after preflight”并要求宿主持有进程退出所有权否则拒绝。完整的参数 schema 校验器validateGatewaySuspend*Params从 packages/gateway-protocol 导入——协议定义与实现分离外部客户端可以直接复用这套 TypeBox schema。状态可观测性hello 快照、事件与 Control UIhello 快照包含suspension: { phase }gateway.suspension事件在准入变化时立即发布。phase 取值为accepting、preparing、draining、prepared两个表面都不暴露挂起 ID。Control UI 左下角连接指示器在准备或 drain 期间显示Suspending…prepared 期间显示SuspendedSettings 里也一样它在准入重开时清除而不是在请求成功时清除离线和重启指示器优先级更高。调度器恢复期间会一直保持挂起指示器直到准入真正重开没有单独的“resuming”阶段。平台责任与边界必须遵守的约束这套握手不会持久化传入消息、不会停止第三方频道传输、也不控制托管平台本身。宿主必须在准备之前围栏自己的入口并始终对唤醒、快照/冻结、停止负责。activeCount是聚合追踪计数blockers是非零类别计数进程注册表的background-exec条目只是聚合值持久后台执行任务也使用background-exec并保留其有界的task元数据其他任务类型保持task同一进程可同时贡献两个计数——该分类不改变activeCount或就绪性也不新增命令文本、输出、OS 进程 ID、会话或作用域标识符。另外关闭 Gateway 会取消由 operator 重连排队的后台工作无需等待挂起到期但关闭仍会等待已在运行的工作完成。对于主机唤醒调度官方给出建议把面向 OpenClaw 的部分放进进程内插件把幂等的完整快照投影到外部宿主适配器托管控制器不应导入 Plugin SDK也不应从事件增量重建 cron 状态。参见 Safe external cron projection。测试与验证仓库为这套挂起协议提供了完整的测试覆盖可作为外部实现者的行为参考src/gateway/server-methods/suspend.test.ts参数校验、busy/ready 分支、status 轮询、stale ID、resume ID 不匹配等场景。src/gateway/server/plugins-http.suspension-admission.test.ts验证插件 HTTP 路由在 prepared 租约下的准入行为包括prepare → status → resume全链路。src/gateway/methods/core-descriptors.since.test.ts固化四个挂起方法各自的since版本防止协议演进时破坏旧客户端。相关发布说明 docs/releases/2026.9.2.md 记载了gateway.suspend.handoff等新增能力的版本背景。相关文档构建 Gateway 客户端嵌入 OpenClawGateway 协议Gateway 协议 RPC 方法CLI agent 命令CLI message 命令Agent loop 概念Agent runtimes 概念Sessions 概念后台任务ACP agentsPlugin SDK 总览【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考