管理 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。
启用¶
启用随附插件:
启用操作会自动应用到正在运行的 Gateway。如果 Gateway 处于离线状态,请启动它以注册该路由。在默认的混合重载模式下,插件配置和加载路径的更改也会自动应用。修改源码或清单后,运行 openclaw plugins reload admin-http-rpc。参见应用更改并检查。
当你不再需要该 HTTP 接口时,请禁用它:
验证路由¶
使用 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:
当插件被禁用时,由于路由未注册,该路由会返回 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上白名单 Admin 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可以运行;安全、未指定目标以及其他白名单方法将返回正常的可重试 GatewayUNAVAILABLE响应。 - 请将此路由保留在 loopback、tailnet 或私有可信入口中。不要直接将其暴露到公共互联网。当调用者跨越信任边界时,请使用独立的 Gateway。
请求¶
字段:
id(string,可选):会复制到响应中。省略时生成 UUID。method(string,必填):允许的 Gateway 方法名。params(any,可选):特定于方法的参数。
默认最大请求体大小为 1 MB。
响应¶
成功响应使用 Gateway RPC 结构:
Gateway 方法错误使用以下结构:
{
"id": "optional-request-id",
"ok": false,
"error": {
"code": "INVALID_REQUEST",
"message": "bad params"
}
}
HTTP 状态码遵循错误码:
| 错误码 | HTTP 状态码 |
|---|---|
INVALID_REQUEST |
400 |
APPROVAL_NOT_FOUND |
404 |
NOT_LINKED, NOT_PAIRED |
409 |
UNAVAILABLE |
503 |
AGENT_TIMEOUT |
504 |
| 任何其他错误码 | 500 |
允许的方法¶
- discovery:
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:
config.get,config.schema,config.schema.lookup,config.set,config.patch,config.apply - channels:
channels.status,channels.start,channels.stop,channels.logout - web:
web.login.start,web.login.wait - models:
models.list,models.authStatus - agents:
agents.list,agents.create,agents.update,agents.delete - approvals:
exec.approvals.get,exec.approvals.set,exec.approvals.node.get,exec.approvals.node.set - cron:
cron.status,cron.list,cron.get,cron.runs,cron.add,cron.update,cron.remove,cron.run - devices:
device.pair.list,device.pair.approve,device.pair.reject,device.pair.remove - nodes:
node.list,node.describe,node.pair.list,node.pair.approve,node.pair.reject,node.pair.remove,node.rename - diagnostics:
doctor.memory.status,update.status
其他 Gateway 方法在明确添加之前均会被阻止。
WebSocket 对比¶
常规的 Gateway WebSocket RPC 路径仍然是 OpenClaw 客户端首选的控制平面 API。仅当主机工具需要请求/响应式 HTTP 接口时,才使用管理 HTTP RPC。
没有可信设备身份的共享 token WebSocket 客户端无法在连接期间自行声明管理员作用域。管理 HTTP RPC 有意遵循现有的可信 HTTP 操作员模型:启用插件后,共享密钥 bearer 认证在此管理接口上被视为完整操作员访问权限。
故障排查¶
404 Not Found 插件已禁用、运行时应用失败,或者请求发往了另一个 Gateway 进程。检查启用结果并检查插件。
401 Unauthorized 请求未满足 Gateway HTTP 认证。检查 bearer token 或可信代理身份头。
405 Method Not Allowed 请求使用了 POST 以外的方法。
413 Payload Too Large 请求体超过了 1 MB 限制。
400 INVALID_REQUEST 请求体不是有效 JSON,缺少 method 字段,方法不在插件允许列表中,或者暂停恢复 ID 与活动租约不匹配。
503 UNAVAILABLE Gateway 方法正在启动、受到速率限制、已暂停,或者正在等待竞争性的暂停/恢复操作。如果存在 error.details,请检查它,并在重试前遵循 error.retryAfterMs。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw