Plugin RPC HTTP di amministrazione

• POST /api/v1/admin/rpc
• lo stesso listener del Gateway: http://<gateway-host>:<port>/api/v1/admin/rpc

​

Prima di attivarlo

• Il chiamante è attendibile per operare il Gateway.
• Il chiamante non può usare il client RPC WebSocket.
• La rotta è raggiungibile solo su loopback, una tailnet o un ingresso privato autenticato.
• Hai esaminato i metodi consentiti e corrispondono all’automazione che intendi eseguire.

​

Attivazione

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

​

Verificare la rotta

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

​

Autenticazione

• autenticazione con segreto condiviso (gateway.auth.mode="token" o "password"): Authorization: Bearer <token-or-password>
• autenticazione HTTP con identità attendibile (gateway.auth.mode="trusted-proxy"): instrada attraverso il proxy configurato con consapevolezza dell’identità e lascia che inietti gli header di identità richiesti
• autenticazione aperta su ingresso privato (gateway.auth.mode="none"): nessun header di autenticazione richiesto

​

Modello di sicurezza

• Attivare il plugin offre intenzionalmente accesso ai metodi RPC di amministrazione in allowlist su /api/v1/admin/rpc.
• Il plugin dichiara il contratto di manifest riservato contracts.gatewayMethodDispatch: ["authenticated-request"] affinché la sua rotta HTTP autenticata dal Gateway possa eseguire metodi del control plane nel processo.
• L’autenticazione bearer con segreto condiviso prova il possesso del segreto operatore del gateway.
• Per l’autenticazione token e password, gli header x-openclaw-scopes più ristretti vengono ignorati e vengono ripristinate le normali impostazioni predefinite da operatore completo.
• Le modalità HTTP con identità attendibile rispettano x-openclaw-scopes quando presente.
• gateway.auth.mode="none" significa che questa rotta non è autenticata se il plugin è attivato. Usalo solo dietro un ingresso privato di cui ti fidi pienamente.
• Le richieste vengono indirizzate tramite gli stessi gestori dei metodi del Gateway e controlli di ambito dell’RPC WebSocket dopo il superamento dell’autenticazione della rotta del plugin.
• Mantieni questa rotta su loopback, tailnet o un ingresso privato attendibile. Non esporla direttamente a internet pubblico.
• I contratti del manifest del plugin non sono una sandbox. Impediscono l’uso accidentale di helper SDK riservati; i plugin attendibili vengono comunque eseguiti nel processo del Gateway.

​

Richiesta

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

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

• id (string, facoltativo): copiato nella risposta. Un UUID viene generato quando omesso.
• method (string, obbligatorio): nome del metodo Gateway consentito.
• params (any, facoltativo): parametri specifici del metodo.

​

Risposta

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

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

​

Metodi consentiti

• discovery: commands.list Restituisce i nomi dei metodi HTTP RPC consentiti da questo 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

​

Confronto con WebSocket

​

Risoluzione dei problemi

​

Correlati

• Ambiti operatore
• Sicurezza del Gateway
• Accesso remoto
• Manifest del plugin
• Sottopercorsi SDK