Plugin RPC HTTP de administración

​

Antes de habilitarlo

• El llamador es de confianza para operar Gateway.
• El llamador no puede usar el cliente RPC WebSocket.
• La ruta solo es accesible en loopback, una tailnet o una entrada privada autenticada.
• Has revisado los métodos permitidos y coinciden con la automatización que planeas ejecutar.

​

Habilitar

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

​

Verificar la ruta

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

​

Autenticación

• autenticación de secreto compartido (gateway.auth.mode="token" o "password"): Authorization: Bearer <token-or-password>
• autenticación HTTP con identidad de confianza (gateway.auth.mode="trusted-proxy"): enruta a través del proxy configurado con reconocimiento de identidad y deja que inyecte los encabezados de identidad requeridos
• autenticación abierta de entrada privada (gateway.auth.mode="none"): no se requiere encabezado de autenticación

​

Modelo de seguridad

• Habilitar el plugin ofrece intencionalmente acceso a los métodos RPC de administración permitidos en /api/v1/admin/rpc.
• El plugin declara el contrato de manifiesto reservado contracts.gatewayMethodDispatch: ["authenticated-request"], que es lo que permite que su ruta HTTP autenticada por Gateway despache métodos del plano de control en el proceso. Esto no es un sandbox: el contrato evita el uso accidental de helpers reservados del SDK, pero los plugins de confianza siguen ejecutándose en el proceso de Gateway.
• La autenticación bearer de secreto compartido (modos token/password) prueba la posesión del secreto del operador de Gateway; los encabezados x-openclaw-scopes más restringidos se ignoran en esa ruta y se restauran los valores predeterminados normales de operador completo.
• La autenticación HTTP con identidad de confianza (modo trusted-proxy) respeta x-openclaw-scopes cuando están presentes.
• gateway.auth.mode="none" significa que esta ruta no está autenticada si el plugin está habilitado. Usa eso solo detrás de una entrada privada en la que confíes plenamente.
• Las solicitudes se despachan a través de los mismos handlers de métodos de Gateway y comprobaciones de alcance que RPC WebSocket, después de que la autenticación de la ruta del plugin se supere.
• Mantén esta ruta en loopback, tailnet o una entrada privada de confianza. No la expongas directamente a internet público. Usa gateways separados cuando los llamadores crucen límites de confianza.

​

Solicitud

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

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

• id (cadena, opcional): se copia en la respuesta. Se genera un UUID cuando se omite.
• method (cadena, obligatorio): nombre de método de Gateway permitido.
• params (cualquier valor, opcional): parámetros específicos del método.

​

Respuesta

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

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

​

Métodos permitidos

• descubrimiento: commands.list Devuelve los nombres de métodos RPC HTTP permitidos por este plugin.
• gateway: health, status, logs.tail, usage.status, usage.cost, gateway.restart.request
• configuración: config.get, config.schema, config.schema.lookup, config.set, config.patch, config.apply
• canales: channels.status, channels.start, channels.stop, channels.logout
• web: web.login.start, web.login.wait
• modelos: models.list, models.authStatus
• agentes: agents.list, agents.create, agents.update, agents.delete
• aprobaciones: 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
• dispositivos: device.pair.list, device.pair.approve, device.pair.reject, device.pair.remove
• nodos: node.list, node.describe, node.pair.list, node.pair.approve, node.pair.reject, node.pair.remove, node.rename
• tareas: tasks.list, tasks.get, tasks.cancel
• diagnósticos: doctor.memory.status, update.status

​

Comparación con WebSocket

​

Solución de problemas

​

Relacionado

• Alcances de operador
• Seguridad de Gateway
• Acceso remoto
• Manifiesto de Plugin
• Subrutas de SDK