管理 HTTP RPC 插件

捆绑的 admin-http-rpc 插件通过 HTTP 暴露一组允许列表中的 Gateway 控制平面方法，适用于无法保持 Gateway WebSocket 连接打开的可信主机自动化。

它随 OpenClaw 一起提供，但默认禁用；禁用时，该路由不会注册。启用时，它会在 Gateway 的同一监听器上添加 POST /api/v1/admin/rpc（http://<gateway-host>:<port>/api/v1/admin/rpc）。

仅对私有主机工具、tailnet 自动化或可信的内部入口启用它。切勿将此路由直接暴露到公共互联网。

启用前¶

Admin HTTP RPC 是完整的操作员控制平面接口：任何通过 Gateway HTTP 认证的调用方都可以调用以下允许列表中的方法。仅当以下所有条件都成立时，才启用它：

• 调用方被信任可以操作 Gateway。
• 调用方无法使用 WebSocket RPC 客户端。
• 该路由仅可通过 loopback、tailnet 或私有认证入口访问。
• 您已审查允许的方法，并且它们与您计划运行的自动化相匹配。

对于能够保持 Gateway WebSocket 连接打开的 OpenClaw 客户端和交互式工具，请改用 WebSocket RPC。

启用¶

启用捆绑插件：

openclaw plugins enable admin-http-rpc

{
  plugins: {
    entries: {
      "admin-http-rpc": { enabled: true },
    },
  },
}

启用状态会自动应用于正在运行的 Gateway。如果 Gateway 离线，请启动它以注册该路由。在默认的混合重载模式下，插件配置和加载路径更改也会自动应用。在编辑源代码或清单后，运行 openclaw plugins reload admin-http-rpc。参见 应用更改并检查。

当不再需要 HTTP 接口时，禁用它：

openclaw plugins disable admin-http-rpc

验证路由¶

使用 health 作为最小的安全请求：

curl -sS http://<gateway-host>:<port>/api/v1/admin/rpc \
  -H 'Authorization: Bearer <gateway-token>' \
  -H 'Content-Type: application/json' \
  -d '{"method":"health","params":{}}'

成功响应包含 ok: true：

{
  "id": "generated-request-id",
  "ok": true,
  "payload": {
    "status": "ok"
  }
}

当插件禁用时，该路由返回 404，因为它未注册。

认证¶

插件路由使用 Gateway HTTP 认证。

常见认证路径：

• 共享密钥认证（gateway.auth.mode="token" 或 "password"）：Authorization: Bearer <token-or-password>
• 可信身份承载 HTTP 认证（gateway.auth.mode="trusted-proxy"）：通过已配置的身份感知代理进行路由，并让其注入所需的身份头
• 私有入口开放认证（gateway.auth.mode="none"）：无需认证头

安全模型¶

将此插件视为完整的 Gateway 操作员接口。

• 启用该插件会故意提供对 /api/v1/admin/rpc 上允许列表中的管理员 RPC 方法的访问。
• 该插件声明保留的 contracts.gatewayMethodDispatch: ["authenticated-request"] 清单契约，正是该契约使其经过 Gateway 认证的 HTTP 路由能够在进程内分发控制平面方法。这不是沙箱：该契约可防止意外使用保留的 SDK 辅助函数，但可信插件仍在 Gateway 进程中运行。
• 共享密钥 Bearer 认证（token/password 模式）证明持有 Gateway 操作员密钥；在该路径上，更窄的 x-openclaw-scopes 头会被忽略，并恢复正常的完整操作员默认值。
• 可信身份承载 HTTP 认证（trusted-proxy 模式）在存在时遵循 x-openclaw-scopes。
• gateway.auth.mode="none" 表示如果启用该插件，则此路由未认证。仅在您完全信任的私有入口之后使用它。
• 在插件路由认证通过后，请求通过 WebSocket RPC 相同的 Gateway 方法处理程序和范围检查进行分发。
• 在已准备的暂停租约期间，该路由仍可访问。有界请求验证和本地 commands.list 发现响应仍可用。在分发到 Gateway 的方法中，gateway.suspend.prepare、gateway.suspend.status、gateway.suspend.resume 以及精确目标非安全的 gateway.restart.request 可以在准入关闭时运行；安全、无目标以及其他允许列表中的方法返回正常的可重试 Gateway UNAVAILABLE 响应。
• 将此路由保留在 loopback、tailnet 或私有可信入口上。不要直接将其暴露到公共互联网。当调用方跨越信任边界时，请使用单独的 Gateway。

请求¶

POST /api/v1/admin/rpc
Authorization: Bearer <gateway-token>
Content-Type: application/json

{
  "id": "optional-request-id",
  "method": "health",
  "params": {}
}

字段：

• id（字符串，可选）：复制到响应中。省略时会生成 UUID。
• method（字符串，必填）：允许的 Gateway 方法名称。
• params（任意，可选）：特定于方法的参数。

默认最大请求体大小为 1 MB。

响应¶

成功响应使用 Gateway RPC 格式：

{
  "id": "optional-request-id",
  "ok": true,
  "payload": {}
}

Gateway 方法错误使用：

{
  "id": "optional-request-id",
  "ok": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "bad params"
  }
}

HTTP 状态遵循错误代码：

允许的方法¶

• 发现：commands.list 返回此插件允许的 HTTP RPC 方法名称。
• Gateway：health、status、logs.tail、usage.status、usage.cost、gateway.restart.request、gateway.suspend.prepare、gateway.suspend.status、gateway.suspend.resume
• 配置：config.get、config.schema、config.schema.lookup、config.set、config.patch、config.apply
• 频道：channels.status、channels.start、channels.stop、channels.logout
• Web：web.login.start、web.login.wait
• 模型：models.list、models.authStatus
• 代理：agents.list、agents.create、agents.update、agents.delete
• 审批：exec.approvals.get、exec.approvals.set、exec.approvals.node.get、exec.approvals.node.set
• 定时任务：cron.status、cron.list、cron.get、cron.runs、cron.add、cron.update、cron.remove、cron.run
• 设备：device.pair.list、device.pair.approve、device.pair.reject、device.pair.remove
• 节点：node.list、node.describe、node.pair.list、node.pair.approve、node.pair.reject、node.pair.remove、node.rename
• 诊断：doctor.memory.status、update.status

其他 Gateway 方法在未被有意添加之前均会被阻止。

WebSocket 对比¶

常规的 Gateway WebSocket RPC 路径仍然是 OpenClaw 客户端首选的控制平面 API。仅当主机工具需要请求/响应式 HTTP 接口时，才使用管理 HTTP RPC。

没有可信设备身份的共享令牌 WebSocket 客户端无法在连接期间自行声明管理员作用域。管理 HTTP RPC 有意遵循现有的可信 HTTP 操作员模型：启用插件后，共享密钥 Bearer 认证在此管理接口上被视为完整操作员访问权限。

故障排查¶

404 Not Found 插件已禁用、运行时应用失败，或请求发往了另一个 Gateway 进程。请检查启用结果并检查插件。

401 Unauthorized 请求未满足 Gateway HTTP 认证。请检查 Bearer 令牌或可信代理身份头。

405 Method Not Allowed 请求使用了 POST 以外的方法。

413 Payload Too Large 请求体超过了 1 MB 限制。

400 INVALID_REQUEST 请求体不是有效 JSON，缺少 method 字段，方法不在插件允许列表中，或暂停恢复 ID 与活动租约不匹配。

503 UNAVAILABLE Gateway 方法正在启动、受到速率限制、已暂停，或正在等待竞争性的暂停/恢复操作。如存在 error.details，请检查它，并在重试前遵循 error.retryAfterMs。

相关¶

• 操作员作用域
• Gateway 安全
• 远程访问
• 插件清单
• SDK 子路径