Skip to main content
The bundled admin-http-rpc plugin exposes an allowlisted set of Gateway control-plane methods over HTTP, for trusted host automation that cannot keep a Gateway WebSocket connection open. It ships with OpenClaw but is disabled by default; when disabled, the route is not registered. When enabled, it adds POST /api/v1/admin/rpc on the same listener as the Gateway (http://<gateway-host>:<port>/api/v1/admin/rpc). Enable it only for private host tooling, tailnet automation, or a trusted internal ingress. Never expose this route directly to the public internet.

​
Before you enable it

Admin HTTP RPC is a full operator control-plane surface: any caller that passes Gateway HTTP auth can invoke the allowlisted methods below. Enable it only when all of these are true:
  • The caller is trusted to operate the Gateway.
  • The caller cannot use the WebSocket RPC client.
  • The route is reachable only on loopback, a tailnet, or a private authenticated ingress.
  • You have reviewed the allowed methods and they match the automation you plan to run.
For OpenClaw clients and interactive tools that can keep a Gateway WebSocket connection open, use WebSocket RPC instead.

​
Enable

Enable the bundled plugin: 
openclaw plugins enable admin-http-rpc
openclaw gateway restart
The route is registered during plugin startup, so restart the Gateway after changing plugin config. Disable it when you no longer need the HTTP surface: 
openclaw plugins disable admin-http-rpc
openclaw gateway restart

​
Verify the route

Use health as the smallest safe request: 
curl -sS http://<gateway-host>:<port>/api/v1/admin/rpc \
  -H 'Authorization: Bearer <gateway-token>' \
  -H 'Content-Type: application/json' \
  -d '{"method":"health","params":{}}'
A successful response has ok: true: 
{
  "id": "generated-request-id",
  "ok": true,
  "payload": {
    "status": "ok"
  }
}
When the plugin is disabled, the route returns 404 because it is not registered.

​
Authentication

The plugin route uses Gateway HTTP auth. Common authentication paths:
  • shared-secret auth (gateway.auth.mode="token" or "password"): Authorization: Bearer <token-or-password>
  • trusted identity-bearing HTTP auth (gateway.auth.mode="trusted-proxy"): route through the configured identity-aware proxy and let it inject the required identity headers
  • private-ingress open auth (gateway.auth.mode="none"): no auth header required

​
Security model

Treat this plugin as a full Gateway operator surface.
  • Enabling the plugin intentionally offers access to the allowlisted admin RPC methods at /api/v1/admin/rpc.
  • The plugin declares the reserved contracts.gatewayMethodDispatch: ["authenticated-request"] manifest contract, which is what lets its Gateway-authenticated HTTP route dispatch control-plane methods in process. This is not a sandbox: the contract prevents accidental use of reserved SDK helpers, but trusted plugins still run in the Gateway process.
  • Shared-secret bearer auth (token/password modes) proves possession of the gateway operator secret; narrower x-openclaw-scopes headers are ignored on that path and normal full operator defaults are restored.
  • Trusted identity-bearing HTTP auth (trusted-proxy mode) honors x-openclaw-scopes when present.
  • gateway.auth.mode="none" means this route is unauthenticated if the plugin is enabled. Use that only behind a private ingress you fully trust.
  • Requests dispatch through the same Gateway method handlers and scope checks as WebSocket RPC, after the plugin route auth passes.
  • Keep this route on loopback, tailnet, or a private trusted ingress. Do not expose it directly to the public internet. Use separate gateways when callers cross trust boundaries.

​
Request

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

{
  "id": "optional-request-id",
  "method": "health",
  "params": {}
}
Fields:
  • id (string, optional): copied into the response. A UUID is generated when omitted.
  • method (string, required): allowed Gateway method name.
  • params (any, optional): method-specific params.
The default max request body size is 1 MB.

​
Response

Success responses use the Gateway RPC shape: 
{
  "id": "optional-request-id",
  "ok": true,
  "payload": {}
}
Gateway method errors use: 
{
  "id": "optional-request-id",
  "ok": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "bad params"
  }
}
HTTP status follows the error code:
Error codeHTTP status
INVALID_REQUEST400
APPROVAL_NOT_FOUND404
NOT_LINKED, NOT_PAIRED409
UNAVAILABLE503
AGENT_TIMEOUT504
any other code500

​
Allowed methods

  • discovery: commands.list Returns the HTTP RPC method names allowed by this plugin.
  • gateway: health, status, logs.tail, usage.status, usage.cost, gateway.restart.request
  • 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
  • tasks: tasks.list, tasks.get, tasks.cancel
  • diagnostics: doctor.memory.status, update.status
Other Gateway methods are blocked until they are intentionally added.

​
WebSocket comparison

The normal Gateway WebSocket RPC path remains the preferred control-plane API for OpenClaw clients. Use admin HTTP RPC only for host tooling that needs a request/response HTTP surface. Shared-token WebSocket clients without a trusted device identity cannot self-declare admin scopes during connect. Admin HTTP RPC deliberately follows the existing trusted HTTP operator model: when the plugin is enabled, shared-secret bearer auth is treated as full operator access for this admin surface.

​
Troubleshooting

404 Not Found : The plugin is disabled, the Gateway has not restarted since enabling it, or the request is going to a different Gateway process. 401 Unauthorized : The request did not satisfy Gateway HTTP auth. Check the bearer token or the trusted-proxy identity headers. 405 Method Not Allowed : The request used something other than POST. 413 Payload Too Large : The request body exceeded the 1 MB limit. 400 INVALID_REQUEST : The request body is not valid JSON, the method field is missing, or the method is not in the plugin allowlist. 503 UNAVAILABLE : The Gateway method handler is unavailable. Check Gateway logs and retry after the Gateway finishes startup.