Plugin RPC HTTP de administración

El plugin admin-http-rpc incluido expone mediante HTTP un conjunto permitido de métodos del plano de control del Gateway, para la automatización de hosts de confianza que no puede mantener abierta una conexión WebSocket con el Gateway.

Se distribuye con OpenClaw, pero está deshabilitado de forma predeterminada; cuando está deshabilitado, la ruta no se registra. Cuando se habilita, añade POST /api/v1/admin/rpc en el mismo listener que el Gateway (http://<gateway-host>:<port>/api/v1/admin/rpc).

Habilítelo únicamente para herramientas privadas del host, automatización de la tailnet o un ingreso interno de confianza. Nunca exponga esta ruta directamente a la Internet pública.

Antes de habilitarlo

RPC de administración mediante HTTP es una superficie completa del plano de control del operador: cualquier cliente que supere la autenticación HTTP del Gateway puede invocar los métodos permitidos que se indican a continuación. Habilítelo únicamente cuando se cumplan todas estas condiciones:

• El cliente es de confianza para operar el Gateway.
• El cliente no puede utilizar el cliente RPC de WebSocket.
• Solo se puede acceder a la ruta mediante loopback, una tailnet o un ingreso privado autenticado.
• Ha revisado los métodos permitidos y coinciden con la automatización que planea ejecutar.

Para los clientes de OpenClaw y las herramientas interactivas que puedan mantener abierta una conexión WebSocket con el Gateway, utilice RPC de WebSocket.

Habilitar

Habilite el plugin incluido:

openclaw plugins enable admin-http-rpcopenclaw gateway restart

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

La ruta se registra durante el inicio del plugin, por lo que debe reiniciar el Gateway después de cambiar la configuración del plugin.

Deshabilítelo cuando ya no necesite la superficie HTTP:

openclaw plugins disable admin-http-rpcopenclaw gateway restart

Verificar la ruta

Utilice health como la solicitud segura más pequeña:

curl -sS http://<gateway-host>:<port>/api/v1/admin/rpc \  -H 'Authorization: Bearer <gateway-token>' \  -H 'Content-Type: application/json' \  -d '{"method":"health","params":{}}'

Una respuesta correcta tiene ok: true:

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

Cuando el plugin está deshabilitado, la ruta devuelve 404 porque no está registrada.

Autenticación

La ruta del plugin utiliza la autenticación HTTP del Gateway.

Métodos de autenticación habituales:

• autenticación mediante secreto compartido (gateway.auth.mode="token" o "password"): Authorization: Bearer <token-or-password>
• autenticación HTTP de confianza que incluye identidad (gateway.auth.mode="trusted-proxy"): enrute la solicitud mediante el proxy configurado con reconocimiento de identidad y permita que este inyecte los encabezados de identidad necesarios
• autenticación abierta mediante ingreso privado (gateway.auth.mode="none"): no se requiere ningún encabezado de autenticación

Modelo de seguridad

Trate este plugin como una superficie completa de operador del Gateway.

• Habilitar el plugin proporciona intencionadamente 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 permite que su ruta HTTP autenticada por el Gateway despache métodos del plano de control dentro del proceso. Esto no es un entorno aislado: el contrato impide el uso accidental de asistentes reservados del SDK, pero los plugins de confianza siguen ejecutándose en el proceso del Gateway.
• La autenticación con portador mediante secreto compartido (modos token/password) demuestra la posesión del secreto de operador del Gateway; los encabezados x-openclaw-scopes más restrictivos se ignoran en esa ruta y se restauran los valores predeterminados normales de operador completo.
• La autenticación HTTP de confianza que incluye identidad (modo trusted-proxy) respeta x-openclaw-scopes cuando está presente.
• gateway.auth.mode="none" significa que esta ruta no está autenticada si el plugin está habilitado. Utilícelo únicamente detrás de un ingreso privado en el que confíe plenamente.
• Las solicitudes se despachan mediante los mismos controladores de métodos y comprobaciones de ámbito del Gateway que el RPC de WebSocket, una vez superada la autenticación de la ruta del plugin.
• La ruta sigue siendo accesible durante una concesión de suspensión preparada. La validación acotada de solicitudes y la respuesta local de descubrimiento commands.list siguen estando disponibles. De los métodos despachados al Gateway, solo gateway.suspend.prepare, gateway.suspend.status y gateway.suspend.resume pueden ejecutarse mientras la admisión está cerrada; los demás métodos permitidos devuelven la respuesta normal reintentable UNAVAILABLE del Gateway.
• Mantenga esta ruta en loopback, una tailnet o un ingreso privado de confianza. No la exponga directamente a la Internet pública. Utilice gateways independientes cuando los clientes atraviesen límites de confianza.

Solicitud

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

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

Campos:

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

El tamaño máximo predeterminado del cuerpo de la solicitud es de 1 MB.

Respuesta

Las respuestas correctas utilizan la estructura RPC del Gateway:

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

Los errores de métodos del Gateway utilizan:

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

El estado HTTP depende del código de error:

Métodos permitidos

• descubrimiento: commands.list Devuelve los nombres de los métodos RPC HTTP permitidos por este plugin.
• gateway: health, status, logs.tail, usage.status, usage.cost, gateway.restart.request, gateway.suspend.prepare, gateway.suspend.status, gateway.suspend.resume
• 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

Los demás métodos del Gateway están bloqueados hasta que se añadan intencionadamente.

Comparación con WebSocket

La ruta RPC normal de WebSocket del Gateway sigue siendo la API de plano de control preferida para los clientes de OpenClaw. Utilice RPC de administración mediante HTTP únicamente para herramientas del host que necesiten una superficie HTTP de solicitud y respuesta.

Los clientes WebSocket con token compartido que no tengan una identidad de dispositivo de confianza no pueden declarar por sí mismos ámbitos de administración durante la conexión. RPC de administración mediante HTTP sigue deliberadamente el modelo existente de operador HTTP de confianza: cuando el plugin está habilitado, la autenticación con portador mediante secreto compartido se trata como acceso completo de operador para esta superficie de administración.

Solución de problemas

404 Not Found

: El plugin está deshabilitado, el Gateway no se ha reiniciado desde que se habilitó o la solicitud se dirige a otro proceso del Gateway.

401 Unauthorized

: La solicitud no cumplió los requisitos de autenticación HTTP del Gateway. Compruebe el token de portador o los encabezados de identidad del proxy de confianza.

405 Method Not Allowed

: La solicitud utilizó algo distinto de POST.

413 Payload Too Large

: El cuerpo de la solicitud superó el límite de 1 MB.

400 INVALID_REQUEST

: El cuerpo de la solicitud no es JSON válido, falta el campo method, el método no se encuentra en la lista permitida del plugin o un identificador de reanudación de suspensión no coincide con la concesión activa.

503 UNAVAILABLE

: El método del Gateway se está iniciando, tiene limitada la frecuencia, está suspendido o está esperando una operación de suspensión o reanudación concurrente. Inspeccione error.details cuando esté presente y respete error.retryAfterMs antes de volver a intentarlo.

Contenido relacionado

• Ámbitos del operador
• Seguridad del Gateway
• Acceso remoto
• Manifiesto del plugin
• Subrutas del SDK