English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Bundled plugin guides

관리자 HTTP RPC Plugin

번들된 admin-http-rpc Plugin은 일반 Gateway WebSocket RPC 클라이언트를 사용할 수 없는 신뢰된 호스트 자동화를 위해 선택된 Gateway 제어 평면 메서드를 HTTP로 노출합니다.

이 Plugin은 OpenClaw에 포함되어 있지만 기본적으로 꺼져 있습니다. 비활성화되어 있으면 라우트가 등록되지 않습니다. 활성화하면 다음이 추가됩니다.

  • POST /api/v1/admin/rpc
  • Gateway와 동일한 리스너: http://<gateway-host>:<port>/api/v1/admin/rpc

비공개 호스트 도구, tailnet 자동화, 또는 신뢰된 내부 인그레스에만 활성화하세요. 이 라우트를 공개 인터넷에 직접 노출하지 마세요.

활성화하기 전에

관리자 HTTP RPC는 전체 운영자 제어 평면 표면입니다. Gateway HTTP 인증을 통과하는 모든 호출자는 이 페이지의 허용 목록에 있는 메서드를 호출할 수 있습니다.

다음이 모두 참일 때 사용하세요.

  • 호출자가 Gateway를 운영하도록 신뢰됩니다.
  • 호출자가 WebSocket RPC 클라이언트를 사용할 수 없습니다.
  • 라우트가 loopback, tailnet, 또는 비공개 인증 인그레스에서만 도달 가능합니다.
  • 허용된 메서드를 검토했으며 실행하려는 자동화와 일치합니다.

Gateway WebSocket 연결을 열어 둘 수 있는 OpenClaw 클라이언트와 대화형 도구에는 WebSocket RPC 경로를 사용하세요.

활성화

번들된 Plugin을 활성화합니다.

CLI

bash
openclaw plugins enable admin-http-rpcopenclaw gateway restart

Config

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

라우트는 Plugin 시작 중에 등록됩니다. Plugin 설정을 변경한 뒤 Gateway를 다시 시작하세요.

HTTP 표면이 더 이상 필요하지 않으면 비활성화하세요.

bash
openclaw plugins disable admin-http-rpcopenclaw 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"  }}

Plugin이 비활성화되어 있으면 라우트가 등록되지 않았으므로 404를 반환합니다.

인증

Plugin 라우트는 Gateway HTTP 인증을 사용합니다.

일반적인 인증 경로:

  • 공유 시크릿 인증(gateway.auth.mode="token" 또는 "password"): Authorization: Bearer <token-or-password>
  • 신뢰된 ID 포함 HTTP 인증(gateway.auth.mode="trusted-proxy"): 구성된 ID 인식 프록시를 통해 라우팅하고 필요한 ID 헤더를 주입하게 합니다
  • 비공개 인그레스 개방 인증(gateway.auth.mode="none"): 인증 헤더가 필요하지 않습니다

보안 모델

이 Plugin을 전체 Gateway 운영자 표면으로 취급하세요.

  • Plugin을 활성화하면 /api/v1/admin/rpc에서 허용 목록에 있는 관리자 RPC 메서드에 대한 접근을 의도적으로 제공합니다.
  • Plugin은 예약된 contracts.gatewayMethodDispatch: ["authenticated-request"] 매니페스트 계약을 선언하므로, Gateway 인증 HTTP 라우트가 프로세스 내에서 제어 평면 메서드를 디스패치할 수 있습니다.
  • 공유 시크릿 bearer 인증은 gateway 운영자 시크릿의 보유를 증명합니다.
  • token 및 password 인증의 경우 더 좁은 x-openclaw-scopes 헤더는 무시되고 일반적인 전체 운영자 기본값이 복원됩니다.
  • 신뢰된 ID 포함 HTTP 모드는 x-openclaw-scopes가 있을 때 이를 존중합니다.
  • gateway.auth.mode="none"은 Plugin이 활성화되어 있으면 이 라우트가 인증되지 않음을 의미합니다. 완전히 신뢰하는 비공개 인그레스 뒤에서만 사용하세요.
  • 요청은 Plugin 라우트 인증을 통과한 뒤 WebSocket RPC와 동일한 Gateway 메서드 핸들러 및 범위 검사를 통해 디스패치됩니다.
  • 이 라우트를 loopback, tailnet, 또는 비공개 신뢰 인그레스에 유지하세요. 공개 인터넷에 직접 노출하지 마세요.
  • Plugin 매니페스트 계약은 샌드박스가 아닙니다. 예약된 SDK 헬퍼의 우발적 사용을 막지만, 신뢰된 Plugin은 여전히 Gateway 프로세스에서 실행됩니다.

호출자가 신뢰 경계를 넘는 경우 별도의 gateway를 사용하세요.

요청

http
POST /api/v1/admin/rpcAuthorization: Bearer <gateway-token>Content-Type: application/json
json
{  "id": "optional-request-id",  "method": "health",  "params": {}}

필드:

  • id(문자열, 선택 사항): 응답에 복사됩니다. 생략하면 UUID가 생성됩니다.
  • method(문자열, 필수): 허용된 Gateway 메서드 이름입니다.
  • params(any, 선택 사항): 메서드별 params입니다.

기본 최대 요청 본문 크기는 1 MB입니다.

응답

성공 응답은 Gateway RPC 형태를 사용합니다.

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

Gateway 메서드 오류는 다음을 사용합니다.

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

가능한 경우 HTTP 상태는 Gateway 오류를 따릅니다. 예를 들어 INVALID_REQUEST는 400을 반환하고, UNAVAILABLE은 503을 반환합니다.

허용된 메서드

  • 탐색: commands.list 이 Plugin에서 허용하는 HTTP RPC 메서드 이름을 반환합니다.
  • 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

다른 Gateway 메서드는 의도적으로 추가될 때까지 차단됩니다.

WebSocket 비교

일반 Gateway WebSocket RPC 경로는 OpenClaw 클라이언트에 권장되는 제어 평면 API로 유지됩니다. 요청/응답 HTTP 표면이 필요한 호스트 도구에만 관리자 HTTP RPC를 사용하세요.

신뢰된 장치 ID가 없는 공유 토큰 WebSocket 클라이언트는 연결 중에 관리자 범위를 스스로 선언할 수 없습니다. 관리자 HTTP RPC는 기존의 신뢰된 HTTP 운영자 모델을 의도적으로 따릅니다. Plugin이 활성화되어 있으면 공유 시크릿 bearer 인증은 이 관리자 표면에 대한 전체 운영자 접근으로 취급됩니다.

문제 해결

404 Not Found

: Plugin이 비활성화되어 있거나, 활성화한 뒤 Gateway가 다시 시작되지 않았거나, 요청이 다른 Gateway 프로세스로 가고 있습니다.

401 Unauthorized

: 요청이 Gateway HTTP 인증을 충족하지 못했습니다. bearer 토큰 또는 trusted-proxy ID 헤더를 확인하세요.

400 INVALID_REQUEST

: 요청 본문이 유효한 JSON이 아니거나, method 필드가 누락되었거나, 메서드가 Plugin 허용 목록에 없습니다.

503 UNAVAILABLE

: Gateway 메서드 핸들러를 사용할 수 없습니다. Gateway 로그를 확인하고 Gateway 시작이 완료된 뒤 다시 시도하세요.

관련 항목

Was this useful?
On this page

On this page