OpenClaw admin-http-rpc 插件：用 HTTP 管理 Gateway

> 来源: OpenClaw v2026.5.18 内置插件

> 日期: 2026-05-19

> 评分: ★★★★☆ (4/5) — 小巧、安全设计到位，但使用场景有限

一句话版本

admin-http-rpc 是 OpenClaw v2026.5.18 新增的内置插件，让你可以用 HTTP POST 请求调用 Gateway 的管理方法——查状态、改配置、启停频道、管理 Agent、操作审批流、跑 cron 任务、管理设备节点等，适合脚本和自动化场景。默认关闭，需要手动启用。

项目概况

为什么需要这个插件

OpenClaw 的管理接口（RPC）默认走 WebSocket 协议。这对交互式客户端很好，但有些场景用不了 WebSocket：

• CI/CD 脚本：想 deploy 后调 openclaw gateway restart 或检查 health
• 监控告警：定时 curl 查 Gateway 状态
• 自定义自动化：改配置、启停频道、管理 cron
• Web 后台：通过 HTTP 统一暴露管理能力

admin-http-rpc 就是给这些场景用的——纯 HTTP 请求/响应，无状态，随调随走。

启用方式

# 启用
openclaw plugins enable admin-http-rpc
openclaw gateway restart

# 停用
openclaw plugins disable admin-http-rpc
openclaw gateway restart

或者直接在配置文件里加：

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

可用方法（13 类，50+ 个）

使用示例

最简单的请求——查健康

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

响应：

{
  "id": "自动生成的UUID",
  "ok": true,
  "payload": { "status": "ok" }
}

查支持的 method 列表

curl -sS http://localhost:8080/api/v1/admin/rpc \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"method":"commands.list"}'

改配置并重启

curl -sS http://localhost:8080/api/v1/admin/rpc \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"method":"config.set", "params": {"model": "gpt-4"}}'

请求/响应格式

请求

POST /api/v1/admin/rpc + JSON body：

{
  "id": "可选，不传自动UUID",
  "method": "health",
  "params": {}
}

Body 大小限制：1MB。

响应

成功：

{
  "id": "请求ID",
  "ok": true,
  "payload": {}
}

失败：

{
  "id": "请求ID",
  "ok": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "bad params"
  }
}

HTTP Status 映射：

插件禁用时路由不存在 → 404。

安全模型

认证

三种方式，取决于 gateway.auth.mode：

核心安全原则

> 别暴露到公网。永远。

文档用了大幅篇幅强调这三点：

1. 只用在本机、tailnet 或私有可信 ingress

2. 共享 token 的 WebSocket 客户端本来不能自行声明 admin scope，但 HTTP RPC 走的是不同的信任模型——有 token = 全权限操作

3. gateway.auth.mode="none" + 开了这个插件 = 路由无认证。这种配置只适合在你完全信任的私有内网背后

白名单限制

methods.ts 里有一个硬编码的 ADMIN_HTTP_RPC_ALLOWED_METHODS 白名单 Set。只有写在这的 50+ 个方法能通过 HTTP 调用。其他 Gateway RPC 方法被拦截，需要手动扩增。

代码架构

extensions/admin-http-rpc/
├── openclaw.plugin.json    # 插件清单（onStartup: false, contracts配置）
├── package.json            # 包定义
├── tsconfig.json           # TypeScript 配置
├── index.ts                # 插件入口：路由注册到 /api/v1/admin/rpc
├── index.test.ts           # 测试（验证路由注册、activation 开关）
└── src/
    ├── handler.ts          # HTTP 请求处理（JSON 解析、校验、分发）
    └── methods.ts          # 白名单列表（13 类 50+ 方法）

核心流程

HTTP POST → readJsonBody(解析JSON, 1MB限制)
         → readRpcRequestBody(校验method字段)
         → isAdminHttpRpcAllowedMethod(白名单检查)
         → commands.list? 直接返回列表
         → dispatchGatewayMethod(转发给Gateway处理器)
         → rpcHttpStatus(错误码→HTTP status)
         → sendJson(返回RPC响应)

认证在 registerHttpRoute({ auth: "gateway" }) 阶段由 Gateway 框架处理，插件层只处理业务逻辑。

和 Control UI 的关系

Control UI 用的是 WebSocket RPC，不是 admin-http-rpc

OpenClaw 的 Control UI（Web 管理界面）不用 admin-http-rpc 插件。Control UI 的 GatewayBrowserClient（ui/src/ui/gateway.ts）直接通过 WebSocket 连接 Gateway：

浏览器 → new WebSocket("ws://gateway:port") → 发送 connect 帧（含设备签名/nonce）
       → Gateway 认证通过 → 双向通信
       → client.request("health", {}) → 发 {type:"req", id, method, params} 帧
       → Gateway 返回 {type:"res", id, ok, payload} 帧

每个控制器（health.ts, agents.ts, config.ts…）都调 client.request() 走这个 WebSocket 通道，同时还能收 event 推送（presence、health 变更等）。

两者的对比如下

管理界面登录（Web QR）

有趣的是，admin-http-rpc 中有一个 web.login.start 和 web.login.wait 方法，用于Web QR 扫码登录流程——这个功能是 Control UI 的 WebSocket 通道做不到的，因为 QR 流转需要：

1. 用户在浏览器打开二维码页面 → 调用 web.login.start 获取 QR 码

2. 手机扫描 QR → Gateway 收到登录确认

3. 浏览器轮询/长轮询 → web.login.wait 直到登录完成

这个场景不适合 WebSocket（用户在扫码前可能还没连上 Gateway），所以通过 HTTP RPC 做反而是自然的。

小结

• Control UI 走 WebSocket RPC，功能全、能收推送、有完整重连
• admin-http-rpc 暴露同一套 RPC 方法但走 HTTP，给脚本和自动化用，方法更受限
• 两者共享底层 dispatchGatewayMethod 处理器管道

适用场景

✅ 适合用

• CI/CD 脚本里检查 openclaw gateway restart 后的健康状态
• 写一个简单的 Web 管理后台，用 HTTP RPC 控制 OpenClaw
• 监控告警系统定时拉取 Gateway 状态
• 自动化配置更新（config.set / config.patch）
• 定时 cron 任务的外部管理

❌ 不适合用

• 正常 OpenClaw 客户端交互（应该用 WebSocket RPC）
• 直接暴露在公网上
• 需要细粒度 scope 限制的共享 token 场景
• 不能保持 WebSocket 连接的短生命周期工具之外的场景

评分表

资源链接

• 文档: https://docs.openclaw.ai/plugins/admin-http-rpc
• 插件源码: extensions/admin-http-rpc/（OpenClaw 仓库内）
• 相关: Operator scopes, Gateway security