관리자 HTTP RPC Plugin

번들 admin-http-rpc Plugin은 Gateway WebSocket 연결을 계속 열어 둘 수 없는 신뢰할 수 있는 호스트 자동화를 위해, 허용 목록에 포함된 Gateway 제어 영역 메서드 집합을 HTTP를 통해 제공합니다.

이 Plugin은 OpenClaw와 함께 제공되지만 기본적으로 비활성화되어 있으며, 비활성화된 상태에서는 경로가 등록되지 않습니다. 활성화하면 Gateway와 동일한 리스너에 POST /api/v1/admin/rpc가 추가됩니다(http://<gateway-host>:<port>/api/v1/admin/rpc).

비공개 호스트 도구, tailnet 자동화 또는 신뢰할 수 있는 내부 인그레스에만 활성화하세요. 이 경로를 공개 인터넷에 직접 노출해서는 안 됩니다.

활성화하기 전에

관리자 HTTP RPC는 완전한 운영자 제어 영역 표면입니다. Gateway HTTP 인증을 통과한 모든 호출자는 아래의 허용 목록에 포함된 메서드를 호출할 수 있습니다. 다음 조건을 모두 충족하는 경우에만 활성화하세요.

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

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

활성화

번들 Plugin을 활성화합니다.

openclaw plugins enable admin-http-rpcopenclaw gateway restart

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

경로는 Plugin 시작 중에 등록되므로 Plugin 구성을 변경한 후 Gateway를 다시 시작하세요.

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

openclaw plugins disable admin-http-rpcopenclaw gateway restart

경로 확인

가장 작고 안전한 요청으로 health를 사용하세요.

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가 포함됩니다.

{  "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 경로가 프로세스 내에서 제어 영역 메서드를 디스패치할 수 있습니다. 이는 샌드박스가 아닙니다. 이 계약은 예약된 SDK 도우미의 우발적인 사용을 방지하지만, 신뢰할 수 있는 Plugin은 여전히 Gateway 프로세스에서 실행됩니다.
• 공유 비밀 전달자 인증(token/password 모드)은 Gateway 운영자 비밀을 보유하고 있음을 증명합니다. 이 경로에서는 더 제한적인 x-openclaw-scopes 헤더가 무시되고 일반적인 전체 운영자 기본값이 복원됩니다.
• 신뢰할 수 있는 ID 포함 HTTP 인증(trusted-proxy 모드)은 x-openclaw-scopes가 있으면 이를 적용합니다.
• gateway.auth.mode="none"은 Plugin이 활성화된 경우 이 경로가 인증되지 않음을 의미합니다. 완전히 신뢰할 수 있는 비공개 인그레스 뒤에서만 사용하세요.
• 요청은 Plugin 경로 인증을 통과한 후 WebSocket RPC와 동일한 Gateway 메서드 처리기 및 범위 검사를 통해 디스패치됩니다.
• 준비된 일시 중단 리스 중에도 경로에 접근할 수 있습니다. 제한된 요청 검증과 로컬 commands.list 검색 응답은 계속 사용할 수 있습니다. Gateway로 디스패치되는 메서드 중 허용이 차단된 동안 실행할 수 있는 것은 gateway.suspend.prepare, gateway.suspend.status, gateway.suspend.resume뿐이며, 허용 목록의 다른 메서드는 일반적인 재시도 가능한 Gateway UNAVAILABLE 응답을 반환합니다.
• 이 경로는 loopback, tailnet 또는 신뢰할 수 있는 비공개 인그레스에 두세요. 공개 인터넷에 직접 노출하지 마세요. 호출자가 신뢰 경계를 넘는 경우 별도의 Gateway를 사용하세요.

요청

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

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

필드:

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

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

응답

성공 응답은 Gateway RPC 형식을 사용합니다.

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

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

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

HTTP 상태는 오류 코드를 따릅니다.

허용된 메서드

• 검색: commands.list 이 Plugin이 허용하는 HTTP RPC 메서드 이름을 반환합니다.
• Gateway: health, status, logs.tail, usage.status, usage.cost, gateway.restart.request, gateway.suspend.prepare, gateway.suspend.status, gateway.suspend.resume
• 구성: config.get, config.schema, config.schema.lookup, config.set, config.patch, config.apply
• 채널: channels.status, channels.start, channels.stop, channels.logout
• 웹: web.login.start, web.login.wait
• 모델: models.list, models.authStatus
• 에이전트: agents.list, agents.create, agents.update, agents.delete
• 승인: 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
• 기기: device.pair.list, device.pair.approve, device.pair.reject, device.pair.remove
• Node: node.list, node.describe, node.pair.list, node.pair.approve, node.pair.reject, node.pair.remove, node.rename
• 작업: tasks.list, tasks.get, tasks.cancel
• 진단: doctor.memory.status, update.status

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

WebSocket 비교

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

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

문제 해결

404 Not Found

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

401 Unauthorized

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

405 Method Not Allowed

: 요청에서 POST 이외의 메서드를 사용했습니다.

413 Payload Too Large

: 요청 본문이 1MB 제한을 초과했습니다.

400 INVALID_REQUEST

: 요청 본문이 유효한 JSON이 아니거나, method 필드가 누락되었거나, 메서드가 Plugin 허용 목록에 없거나, 일시 중단 재개 ID가 활성 리스와 일치하지 않습니다.

503 UNAVAILABLE

: Gateway 메서드가 시작 중이거나, 속도 제한을 받거나, 일시 중단되었거나, 경합하는 일시 중단/재개 작업을 기다리고 있습니다. error.details가 있으면 확인하고, 재시도하기 전에 error.retryAfterMs를 준수하세요.

관련 항목

• 운영자 범위
• Gateway 보안
• 원격 접근
• Plugin 매니페스트
• SDK 하위 경로