Appearance
Admin HTTP RPC 插件适用于必须用 HTTP 请求/响应模式、无法保持 WebSocket 连接的宿主自动化场景。启用后通过 POST /api/v1/admin/rpc 暴露选定的网关控制面方法，但必须仅在 loopback、tailnet 或受信私有入口下使用。关键限制：插件默认关闭，启用后需重启网关；仅有 Authorization: Bearer <token> 等几种认证方式；请求体最大 1 MB。
OpenClaw Admin HTTP RPC 插件启用与排查指南
内置的 admin-http-rpc 插件在 OpenClaw 中可选启用，它通过 HTTP 暴露部分网关控制面方法，供无法使用标准 WebSocket RPC 客户端的宿主工具使用。
插件默认禁用。启用后会在网关监听端口上注册路由：
POST /api/v1/admin/rpc- 地址：
http://<gateway-host>:<port>/api/v1/admin/rpc
只应在私有宿主工具、tailnet 自动化或受信内部入口内使用。不要直接暴露到公网。
启用前提
Admin HTTP RPC 是一个完整的操作员控制面。任何通过网关 HTTP 认证的调用者都可以调用本文列出的允许列表方法。
仅在以下条件全部满足时使用：
- 调用者被信任可以操作网关。
- 调用者无法使用 WebSocket RPC 客户端。
- 路由仅在 loopback、tailnet 或私有认证入口上可达。
- 已审查允许的方法列表与你的自动化需求匹配。
对于能保持 WebSocket 连接的 OpenClaw 客户端和交互式工具，应优先使用 WebSocket RPC。
怎么启用 Admin HTTP RPC
启用内置插件：
CLI
```bash
openclaw plugins enable admin-http-rpc
openclaw gateway restart
```
Config
```json5
{
plugins: {
entries: {
"admin-http-rpc": { enabled: true },
},
},
}
```
路由在插件启动时注册。修改插件配置后必须重启网关。
不再需要 HTTP 表面时，禁用并重启：
bash
openclaw plugins disable admin-http-rpc
openclaw gateway restart怎么验证路由
使用 health 方法进行最小安全的测试请求：
bash
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：
json
{
"id": "generated-request-id",
"ok": true,
"payload": {
"status": "ok"
}
}插件禁用时，路由返回 404（因为未注册）。
认证方式
插件路由使用网关 HTTP 认证。
常见认证路径：
- 共享密钥认证（
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"]清单合约，使其经过网关认证的 HTTP 路由可以在进程内分发控制面方法。 - 共享密钥 Bearer 认证证明持有网关操作员密钥。
- 对于
token和password认证模式，更窄的x-openclaw-scopes头被忽略，恢复为常规完全操作员权限。 - 受信身份承载 HTTP 模式在
x-openclaw-scopes存在时予以尊重。 gateway.auth.mode="none"意味着如果启用插件，该路由未经认证。仅在你完全信任的私有入口后面使用。- 请求在经过插件路由认证后，通过相同的网关方法处理器和作用域检查分发（与 WebSocket RPC 相同）。
- 保持此路由在 loopback、tailnet 或私有受信入口上。不要直接暴露到公网。
- 插件清单合约不是沙箱。它们防止意外使用保留的 SDK 辅助工具；受信插件仍在网关进程中运行。
当调用者跨越信任边界时，使用独立的网关。
请求格式
http
POST /api/v1/admin/rpc
Authorization: Bearer <gateway-token>
Content-Type: application/jsonjson
{
"id": "optional-request-id",
"method": "health",
"params": {}
}字段说明：
id（字符串，可选）：会原样复制到响应中。省略时生成 UUID。method（字符串，必填）：允许的网关方法名。params（任意，可选）：方法特定参数。
默认请求体最大 1 MB。
响应格式
成功响应使用网关 RPC 格式：
json
{
"id": "optional-request-id",
"ok": true,
"payload": {}
}网关方法错误使用：
json
{
"id": "optional-request-id",
"ok": false,
"error": {
"code": "INVALID_REQUEST",
"message": "bad params"
}
}HTTP 状态码尽可能对应网关错误：例如 INVALID_REQUEST 返回 400，UNAVAILABLE 返回 503。
允许调用的方法
- 发现：
commands.list返回此插件允许的 HTTP RPC 方法名。 - 网关：
health、status、logs.tail、usage.status、usage.cost、gateway.restart.request - 配置：
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：
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 RPC 对比
正常的网关 WebSocket RPC 路径仍是 OpenClaw 客户端首选的控制面 API。仅当宿主工具需要 HTTP 请求/响应模式时才使用 Admin HTTP RPC。
共享令牌的 WebSocket 客户端如果在连接时没有可信设备身份，不能自行声明管理员作用域。Admin HTTP RPC 刻意遵循现有的受信 HTTP 操作员模型：启用插件后，共享密钥 Bearer 认证被视为此管理表面的完全操作员访问权限。
常见问题
为什么 curl 请求返回 404 Not Found？
插件未启用、启用后未重启网关，或者请求发到了不同的网关进程。检查插件状态：openclaw plugins list，并确认已执行 openclaw gateway restart。
401 Unauthorized 怎么解决？
请求未通过网关 HTTP 认证。检查 Bearer token 是否正确，或受信代理是否注入了所需身份头。如果 gateway.auth.mode 设置为 "none"，则无需认证头，但请确保路由在完全受信的私有入口后。
请求体超过 1 MB 怎么办？
默认最大请求体大小为 1 MB。此限制不可通过 Admin HTTP RPC 插件配置。如果宿主工具需要传输更大负载，应改用 WebSocket RPC 或分片处理。