管理员 HTTP RPC 插件

​

启用前

• 调用方受信任，可以操作 Gateway 网关。
• 调用方无法使用 WebSocket RPC 客户端。
• 仅可通过环回地址、tailnet 或经过身份验证的私有入口访问该路由。
• 你已审查允许的方法，并确认它们与计划运行的自动化相符。

​

启用

openclaw plugins enable admin-http-rpc
openclaw gateway restart

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

openclaw plugins disable admin-http-rpc
openclaw gateway restart

​

验证路由

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

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

​

身份验证

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

​

安全模型

• 启用插件会有意在 /api/v1/admin/rpc 提供对允许列表中管理员 RPC 方法的访问权限。
• 该插件声明了保留的 contracts.gatewayMethodDispatch: ["authenticated-request"] 清单契约，因此其通过 Gateway 网关身份验证的 HTTP 路由能够在进程内分派控制平面方法。这并非沙箱：该契约可防止意外使用保留的 SDK 辅助函数，但可信插件仍在 Gateway 网关进程中运行。
• 共享密钥持有者身份验证（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 网关 UNAVAILABLE 响应。
• 请将此路由限制在环回地址、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（任意类型，可选）：特定于方法的参数。

​

响应

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

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

​

允许的方法

• 发现：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
• 任务：tasks.list、tasks.get、tasks.cancel
• 诊断：doctor.memory.status、update.status

​

WebSocket 对比

​

故障排查

​

相关内容

• 操作员权限范围
• Gateway 安全
• 远程访问
• 插件清单
• SDK 子路径