Admin HTTP RPC plugin

Admin HTTP RPC plugin 문서는 OpenClaw 공식 문서(plugins/admin-http-rpc)를 한국어로 정리한 가이드입니다. Expose selected Gateway control-plane methods through the bundled, opt-in admin-http-rpc plugin 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Expose selected Gateway control-plane methods through the bundled, opt-in admin-http-rpc plugin

한국어 가이드 범위: plugins/admin-http-rpc 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Before you enable it
Enable
Verify the route
인증
Security model
Request
Response
Allowed methods
WebSocket comparison
트러블슈팅
관련 문서

상세 내용

본문

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.

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.

Enable

The route is registered during plugin startup, so restart the Gateway after changing plugin config.

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

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":{}}'

{
  "id": "generated-request-id",
  "ok": true,
  "payload": {
    "status": "ok"
  }
}

인증

주요 항목:

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.
The route remains reachable during a prepared suspension lease. Bounded request validation and the local commands.list discovery response remain available. Of the methods dispatched into the Gateway, only gateway.suspend.prepare, gateway.suspend.status, and gateway.suspend.resume may run while admission is closed; other allowlisted methods return the normal retryable Gateway UNAVAILABLE response.
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

The default max request body size is 1 MB.

주요 항목:

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.

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

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

Response

Success responses use the Gateway RPC shape:

Error code	HTTP status
`INVALID_REQUEST`	400
`APPROVAL_NOT_FOUND`	404
`NOT_LINKED`, `NOT_PAIRED`	409
`UNAVAILABLE`	503
`AGENT_TIMEOUT`	504
any other code	500

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

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

Allowed methods

Returns the HTTP RPC method names allowed by this plugin.

주요 항목:

discovery: commands.list
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
tasks: tasks.list, tasks.get, tasks.cancel
diagnostics: doctor.memory.status, update.status

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.

트러블슈팅

: The plugin is disabled, the Gateway has not restarted since enabling it, or the request is going to a different Gateway process.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/plugins/admin-http-rpc
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

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

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

Admin HTTP RPC plugin

핵심 요약

Expose selected Gateway control-plane methods through the bundled, opt-in admin-http-rpc plugin

한국어 가이드 범위: plugins/admin-http-rpc 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Before you enable it
Enable
Verify the route
인증
Security model
Request
Response
Allowed methods
WebSocket comparison
트러블슈팅
관련 문서

상세 내용

본문

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.

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.

Enable

The route is registered during plugin startup, so restart the Gateway after changing plugin config.

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

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":{}}'

{
  "id": "generated-request-id",
  "ok": true,
  "payload": {
    "status": "ok"
  }
}

인증

주요 항목:

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.
The route remains reachable during a prepared suspension lease. Bounded request validation and the local commands.list discovery response remain available. Of the methods dispatched into the Gateway, only gateway.suspend.prepare, gateway.suspend.status, and gateway.suspend.resume may run while admission is closed; other allowlisted methods return the normal retryable Gateway UNAVAILABLE response.
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

The default max request body size is 1 MB.

주요 항목:

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.

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

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

Response

Success responses use the Gateway RPC shape:

Error code	HTTP status
`INVALID_REQUEST`	400
`APPROVAL_NOT_FOUND`	404
`NOT_LINKED`, `NOT_PAIRED`	409
`UNAVAILABLE`	503
`AGENT_TIMEOUT`	504
any other code	500

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

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

Allowed methods

Returns the HTTP RPC method names allowed by this plugin.

주요 항목:

discovery: commands.list
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
tasks: tasks.list, tasks.get, tasks.cancel
diagnostics: doctor.memory.status, update.status

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.

트러블슈팅

: The plugin is disabled, the Gateway has not restarted since enabling it, or the request is going to a different Gateway process.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/plugins/admin-http-rpc
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

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

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

Admin HTTP RPC plugin

핵심 요약

문서 구성

상세 내용

본문

Before you enable it

Enable

Verify the route

인증

Security model

Request

Response

Allowed methods

WebSocket comparison

트러블슈팅

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Admin HTTP RPC plugin

핵심 요약

문서 구성

상세 내용

본문

Before you enable it

Enable

Verify the route

인증

Security model

Request

Response

Allowed methods

WebSocket comparison

트러블슈팅

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드