OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

快速开始

面向外部应用的 Gateway 网关集成

外部应用通过 Gateway 协议与 OpenClaw 通信：使用 WebSocket 传输和 RPC 方法。当脚本、仪表板、CI 作业、IDE 扩展或其他进程需要启动智能体运行、流式接收事件、等待 结果、取消工作或检查 Gateway 网关资源时，请使用它。

当前可用内容

接口 状态 用途
Gateway 协议 可用 WebSocket 传输、连接握手、身份验证权限范围、协议版本管理和事件。
Gateway RPC 参考 可用 当前用于智能体、会话、任务、模型、工具、制品和审批的 Gateway 网关方法。
openclaw agent 可用 当通过 shell 调用 CLI 已足够时，用于一次性脚本集成。
openclaw message 可用 从脚本发送消息或执行渠道操作。

未来的客户端库软件包正在内部开发中，但目前尚不是 公开安装接口。在发布版本化软件包的发布公告之前，请将其视为预览版实现细节。

推荐路径

  1. 运行或发现一个 Gateway 网关。
  2. 通过 Gateway 协议连接。
  3. 调用 Gateway RPC 参考中记录的 RPC 方法。
  4. 固定你测试时所使用的 OpenClaw 版本。
  5. 升级 OpenClaw 时重新查看 RPC 参考。

对于智能体运行，请从 agent RPC 开始，并配合 agent.wait 获取 终止结果。对于持久化的对话状态，请使用 sessions.* 方法。 对于 UI 集成，请订阅 Gateway 网关事件，并且只渲染你的应用 能够理解的事件系列。

协作式主机挂起

冻结或快照正在运行的进程的托管控制器可以使用 与主机无关的挂起握手：

  1. 停止接收由主机控制的外部入口流量。
  2. 使用稳定且唯一的 requestId 调用 gateway.suspend.prepare。
  3. 如果响应为 busy，请保持进程运行并稍后重试。
  4. 如果响应为 ready，请保存返回的 suspensionId，然后在 expiresAtMs 之前冻结进程或创建其快照。
  5. 解冻后，或放弃挂起时，通过现有 WebSocket 或 Admin HTTP 控制 路径，使用该 suspensionId 调用 gateway.suspend.resume。

已准备挂起的 Gateway 网关会拒绝新的 WebSocket 握手。WebSocket 控制器 必须在主机操作期间保持其已通过身份验证的连接处于打开状态。如果无法 保证这一点，请在准备挂起之前启用并使用 Admin HTTP RPC 插件。如果控制路径丢失， 请等待两分钟的租约过期后再重新连接；租约过期会自动重新开放接入。

RPC 契约如下：

  • gateway.suspend.prepare — operator.admin；参数 { "requestId": "stable-host-operation-id" }
  • gateway.suspend.status — operator.read；参数 { "suspensionId": "id-from-prepare" }
  • gateway.suspend.resume — operator.admin；参数 { "suspensionId": "id-from-prepare" }

ID 会去除首尾空白，必须包含至少一个非空白字符，且长度限制为 128 个字符。繁忙的准备结果包含 status: "busy"、reason、 retryAfterMs、activeCount 和 blockers。就绪结果的结构如下：

json
{  "status": "ready",  "suspensionId": "2c3f...",  "expiresAtMs": 1770000000000,  "activeCount": 0,  "blockers": []}

状态查询返回 {"status":"running"}，或包含 expiresAtMs 的就绪结果。 恢复操作返回 {"ok":true,"status":"running","resumed":true}；成功恢复后 再次调用会返回 resumed: false。

相互竞争的请求 ID 或暂时性的调度器恢复失败会返回可重试的 UNAVAILABLE，其中包含 retryAfterMs。调度器恢复期间，准备、状态查询 和恢复操作都会返回该错误，Gateway 网关会保持未就绪并以故障关闭方式运行， 主机不得冻结或快照该进程。OpenClaw 会自动重试调度器恢复，并且仅在恢复成功后 重新开放接入。使用不匹配的恢复 ID 会返回 INVALID_REQUEST。准备操作与 Gateway 网关共享控制平面每分钟三次尝试的写入预算；请遵守返回的重试延迟。 WebSocket 客户端按设备和 IP 分桶。Admin HTTP 控制器按解析出的客户端 IP 分桶，因此位于同一代理后的控制器可能共享预算。

准备操作只会拒绝新工作：OpenClaw 会关闭新的根级/会话/命令接入， 暂停自动 cron 触发，并同步检查工作。如果存在任何活动工作，它会恢复调度器 并重新开放接入，然后返回 busy；它不会中断或排空这些工作。就绪租约持续 两分钟。使用相同 requestId 重复调用 prepare 会续订租约；租约过期时会先 恢复调度器，再重新开放接入。 在就绪租约期间到期的重启触发会等待租约恢复后再执行；正在进行的重启会使准备操作返回 busy。

处于就绪状态时，/healthz 保持存活，而 /readyz 返回 503。本地或 已通过身份验证的就绪响应包含 gateway-draining；未经身份验证的远程探针 仅收到 { "ready": false }。HTTP 健康探针、现有 WebSocket 连接上的挂起方法， 以及已启用的 Admin HTTP RPC 路由仍然可用。其他 RPC 返回可重试的 UNAVAILABLE。内置 HTTP 用户工作路由和普通插件 HTTP 路由，包括 OpenAI 兼容 API、工具/会话操作、节点监视和已配置的 Hooks，均返回 503， 并包含 error.code: "gateway_unavailable"。新的插件自有 WebSocket 升级 也返回 503；这涵盖升级过程的所有权，不涵盖之后通过已建立的插件套接字 执行的工作。

此握手不会持久化传入消息、停止第三方渠道传输，也不会控制托管平台。 主机必须在准备前隔离其入口流量，并继续负责唤醒、快照/冻结和停止操作。 activeCount 是受跟踪工作的总计数，而 blockers 包含非零类别计数和 有界的任务详情。这不是通用的进程静止屏障。background-exec 阻塞项 仅提供汇总信息：命令文本、进程 ID、输出，以及会话或权限范围标识符绝不会 通过协议传输。渠道健康检查、维护、缓存刷新、已建立的插件 WebSocket 会话， 以及未注册的插件自有后台工作仍可能保持活动状态。 托管平台必须以一致方式冻结或快照完整的进程树及其文件系统；首版契约 无法证明未注册工作处于空闲状态。

应用代码与插件代码

当代码位于 OpenClaw 外部时，请使用 Gateway RPC：

  • 启动或观察智能体运行的 Node 脚本
  • 调用 Gateway 网关的 CI 作业
  • 仪表板和管理面板
  • IDE 扩展
  • 无需成为渠道插件的外部桥接器
  • 使用模拟或真实 Gateway 网关传输的集成测试

当代码在 OpenClaw 内部运行时，请使用插件 SDK：

  • 提供商插件
  • 渠道插件
  • 工具钩子或生命周期钩子
  • Agent harness plugins
  • 可信运行时辅助程序

外部应用不应导入 openclaw/plugin-sdk/*；这些子路径供 OpenClaw 加载的插件使用。

相关内容

Was this useful?
On this page

On this page