Plugin RPC HTTP quản trị

• POST /api/v1/admin/rpc
• cùng listener với Gateway: http://<gateway-host>:<port>/api/v1/admin/rpc

​

Trước khi bạn bật nó

• Caller được tin cậy để vận hành Gateway.
• Caller không thể dùng ứng dụng khách RPC WebSocket.
• Tuyến chỉ có thể truy cập trên loopback, tailnet, hoặc một ingress riêng tư đã xác thực.
• Bạn đã rà soát các phương thức được phép và chúng khớp với tự động hóa bạn định chạy.

​

Bật

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

​

Xác minh tuyến

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"
  }
}

​

Xác thực

• xác thực bí mật dùng chung (gateway.auth.mode="token" hoặc "password"): Authorization: Bearer <token-or-password>
• xác thực HTTP mang danh tính đáng tin cậy (gateway.auth.mode="trusted-proxy"): định tuyến qua proxy nhận biết danh tính đã cấu hình và để nó chèn các header danh tính bắt buộc
• xác thực mở qua ingress riêng tư (gateway.auth.mode="none"): không cần header xác thực

​

Mô hình bảo mật

• Bật Plugin là chủ ý cung cấp quyền truy cập vào các phương thức RPC quản trị trong allowlist tại /api/v1/admin/rpc.
• Plugin khai báo hợp đồng manifest dành riêng contracts.gatewayMethodDispatch: ["authenticated-request"] để tuyến HTTP đã xác thực bởi Gateway của nó có thể dispatch các phương thức mặt phẳng điều khiển trong tiến trình.
• Xác thực bearer bằng bí mật dùng chung chứng minh quyền sở hữu bí mật của người vận hành Gateway.
• Với xác thực token và password, các header x-openclaw-scopes hẹp hơn bị bỏ qua và các mặc định đầy đủ thông thường của người vận hành được khôi phục.
• Các chế độ HTTP mang danh tính đáng tin cậy tôn trọng x-openclaw-scopes khi có mặt.
• gateway.auth.mode="none" nghĩa là tuyến này không được xác thực nếu Plugin được bật. Chỉ dùng chế độ đó phía sau một ingress riêng tư mà bạn hoàn toàn tin cậy.
• Yêu cầu dispatch qua cùng các handler phương thức Gateway và kiểm tra phạm vi như RPC WebSocket sau khi xác thực tuyến Plugin vượt qua.
• Giữ tuyến này trên loopback, tailnet, hoặc một ingress riêng tư đáng tin cậy. Không để lộ trực tiếp nó ra internet công cộng.
• Hợp đồng manifest Plugin không phải là sandbox. Chúng ngăn việc vô tình dùng các helper SDK dành riêng; các Plugin đáng tin cậy vẫn chạy trong tiến trình Gateway.

​

Yêu cầu

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

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

• id (chuỗi, tùy chọn): được sao chép vào phản hồi. Một UUID được tạo khi bỏ qua.
• method (chuỗi, bắt buộc): tên phương thức Gateway được phép.
• params (bất kỳ, tùy chọn): tham số riêng cho phương thức.

​

Phản hồi

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

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

​

Phương thức được phép

• khám phá: commands.list Trả về tên các phương thức RPC HTTP được Plugin này cho phép.
• gateway: health, status, logs.tail, usage.status, usage.cost, gateway.restart.request
• cấu hình: config.get, config.schema, config.schema.lookup, config.set, config.patch, config.apply
• kênh: channels.status, channels.start, channels.stop, channels.logout
• web: web.login.start, web.login.wait
• mô hình: models.list, models.authStatus
• tác nhân: agents.list, agents.create, agents.update, agents.delete
• phê duyệt: 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
• thiết bị: device.pair.list, device.pair.approve, device.pair.reject, device.pair.remove
• nút: node.list, node.describe, node.pair.list, node.pair.approve, node.pair.reject, node.pair.remove, node.rename
• tác vụ: tasks.list, tasks.get, tasks.cancel
• chẩn đoán: doctor.memory.status, update.status

​

So sánh WebSocket

​

Khắc phục sự cố

​

Liên quan

• Phạm vi người vận hành
• Bảo mật Gateway
• Truy cập từ xa
• Manifest Plugin
• Đường dẫn con SDK