OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Plugin guides

Beheer-HTTP-RPC-plugin

De gebundelde Plugin admin-http-rpc stelt via HTTP een allowlist van Gateway-controlplanemethoden beschikbaar voor vertrouwde hostautomatisering die geen Gateway-WebSocketverbinding open kan houden.

Deze wordt met OpenClaw meegeleverd, maar is standaard uitgeschakeld; wanneer deze is uitgeschakeld, wordt de route niet geregistreerd. Wanneer deze is ingeschakeld, wordt POST /api/v1/admin/rpc toegevoegd aan dezelfde listener als de Gateway (http://<gateway-host>:<port>/api/v1/admin/rpc).

Schakel deze alleen in voor privéhosttools, automatisering op een tailnet of een vertrouwde interne ingress. Stel deze route nooit rechtstreeks bloot aan het openbare internet.

Voordat u deze inschakelt

Admin HTTP RPC is een volledig operator-controlplaneoppervlak: elke aanroeper die slaagt voor Gateway-HTTP-authenticatie kan de hieronder opgenomen methoden aanroepen. Schakel dit alleen in wanneer aan al deze voorwaarden is voldaan:

  • De aanroeper wordt vertrouwd om de Gateway te beheren.
  • De aanroeper kan de WebSocket-RPC-client niet gebruiken.
  • De route is alleen bereikbaar via local loopback, een tailnet of een privé-ingress met authenticatie.
  • U hebt de toegestane methoden beoordeeld en deze komen overeen met de automatisering die u wilt uitvoeren.

Gebruik in plaats daarvan WebSocket-RPC voor OpenClaw-clients en interactieve tools die een Gateway-WebSocketverbinding open kunnen houden.

Inschakelen

Schakel de gebundelde Plugin in:

CLI

bash
openclaw plugins enable admin-http-rpcopenclaw gateway restart

Configuratie

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

De route wordt tijdens het opstarten van de Plugin geregistreerd. Start daarom de Gateway opnieuw nadat u de Plugin-configuratie hebt gewijzigd.

Schakel deze uit wanneer u het HTTP-oppervlak niet meer nodig hebt:

bash
openclaw plugins disable admin-http-rpcopenclaw gateway restart

De route verifiëren

Gebruik health als het kleinste veilige verzoek:

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

Een geslaagd antwoord heeft ok: true:

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

Wanneer de Plugin is uitgeschakeld, retourneert de route 404, omdat deze niet is geregistreerd.

Authenticatie

De Plugin-route gebruikt Gateway-HTTP-authenticatie.

Veelgebruikte authenticatiemethoden:

  • authenticatie met een gedeeld geheim (gateway.auth.mode="token" of "password"): Authorization: Bearer <token-or-password>
  • vertrouwde identiteitsdragende HTTP-authenticatie (gateway.auth.mode="trusted-proxy"): leid de route door de geconfigureerde identiteitsbewuste proxy en laat deze de vereiste identiteitsheaders invoegen
  • open authenticatie via een privé-ingress (gateway.auth.mode="none"): geen authenticatieheader vereist

Beveiligingsmodel

Behandel deze Plugin als een volledig Gateway-operatoroppervlak.

  • Als u de Plugin inschakelt, biedt u bewust toegang tot de beheer-RPC-methoden op de allowlist via /api/v1/admin/rpc.
  • De Plugin declareert het gereserveerde manifestcontract contracts.gatewayMethodDispatch: ["authenticated-request"], waardoor de met Gateway geauthenticeerde HTTP-route controlplanemethoden binnen het proces kan dispatchen. Dit is geen sandbox: het contract voorkomt onbedoeld gebruik van gereserveerde SDK-helpers, maar vertrouwde Plugins worden nog steeds in het Gateway-proces uitgevoerd.
  • Bearer-authenticatie met een gedeeld geheim (modi token/password) bewijst het bezit van het Gateway-operatorgeheim; beperktere x-openclaw-scopes-headers worden op dat pad genegeerd en de normale standaardinstellingen voor volledige operatortoegang worden hersteld.
  • Vertrouwde identiteitsdragende HTTP-authenticatie (modus trusted-proxy) respecteert x-openclaw-scopes wanneer deze aanwezig is.
  • gateway.auth.mode="none" betekent dat deze route niet is geauthenticeerd als de Plugin is ingeschakeld. Gebruik dit alleen achter een privé-ingress die u volledig vertrouwt.
  • Nadat de authenticatie van de Plugin-route is geslaagd, worden verzoeken gedispatcht via dezelfde Gateway-methodehandlers en bereikcontroles als WebSocket-RPC.
  • De route blijft bereikbaar tijdens een voorbereide opschortingslease. Begrensde verzoekvalidatie en het lokale discovery-antwoord van commands.list blijven beschikbaar. Van de methoden die naar de Gateway worden gedispatcht, mogen alleen gateway.suspend.prepare, gateway.suspend.status en gateway.suspend.resume worden uitgevoerd zolang de toelating is gesloten; andere methoden op de allowlist retourneren het normale, opnieuw te proberen Gateway-antwoord UNAVAILABLE.
  • Houd deze route op local loopback, een tailnet of een vertrouwde privé-ingress. Stel deze niet rechtstreeks bloot aan het openbare internet. Gebruik afzonderlijke Gateways wanneer aanroepers vertrouwensgrenzen overschrijden.

Verzoek

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

Velden:

  • id (tekenreeks, optioneel): wordt naar het antwoord gekopieerd. Er wordt een UUID gegenereerd wanneer dit veld wordt weggelaten.
  • method (tekenreeks, vereist): naam van een toegestane Gateway-methode.
  • params (willekeurig type, optioneel): methodespecifieke parameters.

De standaard maximale grootte van de verzoekbody is 1 MB.

Antwoord

Geslaagde antwoorden gebruiken de Gateway-RPC-structuur:

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

Gateway-methodefouten gebruiken:

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

De HTTP-status volgt de foutcode:

Foutcode HTTP-status
INVALID_REQUEST 400
APPROVAL_NOT_FOUND 404
NOT_LINKED, NOT_PAIRED 409
UNAVAILABLE 503
AGENT_TIMEOUT 504
elke andere code 500

Toegestane methoden

  • discovery: commands.list Retourneert de namen van de HTTP-RPC-methoden die door deze Plugin zijn toegestaan.
  • Gateway: health, status, logs.tail, usage.status, usage.cost, gateway.restart.request, gateway.suspend.prepare, gateway.suspend.status, gateway.suspend.resume
  • configuratie: config.get, config.schema, config.schema.lookup, config.set, config.patch, config.apply
  • kanalen: channels.status, channels.start, channels.stop, channels.logout
  • web: web.login.start, web.login.wait
  • modellen: models.list, models.authStatus
  • agents: agents.list, agents.create, agents.update, agents.delete
  • goedkeuringen: 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
  • apparaten: 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
  • taken: tasks.list, tasks.get, tasks.cancel
  • diagnostiek: doctor.memory.status, update.status

Andere Gateway-methoden worden geblokkeerd totdat ze bewust worden toegevoegd.

Vergelijking met WebSocket

Het normale Gateway-WebSocket-RPC-pad blijft de voorkeurs-API voor het controlplane voor OpenClaw-clients. Gebruik Admin HTTP RPC alleen voor hosttools die een HTTP-verzoek/antwoordoppervlak nodig hebben.

WebSocket-clients met een gedeelde token zonder vertrouwde apparaatidentiteit kunnen tijdens het verbinden niet zelf beheerbereiken declareren. Admin HTTP RPC volgt bewust het bestaande model voor vertrouwde HTTP-operators: wanneer de Plugin is ingeschakeld, wordt bearer-authenticatie met een gedeeld geheim voor dit beheeroppervlak behandeld als volledige operatortoegang.

Probleemoplossing

404 Not Found

: De Plugin is uitgeschakeld, de Gateway is niet opnieuw gestart nadat deze is ingeschakeld, of het verzoek gaat naar een ander Gateway-proces.

401 Unauthorized

: Het verzoek voldeed niet aan de Gateway-HTTP-authenticatie. Controleer het bearer-token of de identiteitsheaders van de vertrouwde proxy.

405 Method Not Allowed

: Voor het verzoek is iets anders dan POST gebruikt.

413 Payload Too Large

: De verzoekbody overschreed de limiet van 1 MB.

400 INVALID_REQUEST

: De verzoekbody is geen geldige JSON, het veld method ontbreekt, de methode staat niet op de allowlist van de Plugin of een hervattings-ID voor een opschorting komt niet overeen met de actieve lease.

503 UNAVAILABLE

: De Gateway-methode wordt gestart, is beperkt door een snelheidslimiet, is opgeschort of wacht op een concurrerende opschortings- of hervattingsbewerking. Controleer error.details wanneer dit aanwezig is en wacht error.retryAfterMs voordat u het opnieuw probeert.

Gerelateerd

Was this useful?
On this page

On this page