Integraciones del Gateway para aplicaciones externas

Las aplicaciones externas se comunican con OpenClaw mediante el protocolo del Gateway: transporte WebSocket y métodos RPC. Úselo cuando un script, panel, trabajo de CI, extensión de IDE u otro proceso necesite iniciar ejecuciones de agentes, transmitir eventos, esperar resultados, cancelar trabajo o inspeccionar recursos del Gateway.

Qué está disponible actualmente

Se está desarrollando internamente un futuro paquete de biblioteca cliente, pero todavía no constituye una superficie pública de instalación. Trátelo como un detalle de implementación preliminar hasta que una versión anuncie un paquete publicado y versionado.

Ruta recomendada

1. Ejecute o detecte un Gateway.
2. Conéctese mediante el protocolo del Gateway.
3. Llame a los métodos RPC documentados en la referencia RPC del Gateway.
4. Fije la versión de OpenClaw con la que realiza las pruebas.
5. Vuelva a consultar la referencia RPC al actualizar OpenClaw.

Para las ejecuciones de agentes, comience con el RPC agent y combínelo con agent.wait para obtener un resultado terminal. Para mantener un estado de conversación persistente, use los métodos sessions.*. Para integraciones de interfaz de usuario, suscríbase a los eventos del Gateway y represente únicamente las familias de eventos que su aplicación comprenda.

Suspensión cooperativa del host

Los controladores de alojamiento que congelan o crean una instantánea de un proceso en ejecución pueden usar la negociación de suspensión independiente del host:

1. Deje de admitir el tráfico entrante externo controlado por el host.
2. Llame a gateway.suspend.prepare con un requestId estable y único.
3. Si la respuesta es busy, mantenga el proceso en ejecución y vuelva a intentarlo más tarde.
4. Si es ready, guarde el suspensionId devuelto y, a continuación, congele el proceso o cree una instantánea antes de expiresAtMs.
5. Tras reactivarlo, o si se abandona la suspensión, llame a gateway.suspend.resume con ese suspensionId mediante el WebSocket existente o la ruta de control HTTP de administración.

Un Gateway preparado rechaza nuevas negociaciones WebSocket. Un controlador WebSocket debe mantener abierta su conexión autenticada durante la operación del host. Si esto no puede garantizarse, habilite y use el Plugin RPC HTTP de administración antes de realizar la preparación. Si se pierde la ruta de control, espere a que caduque la concesión de dos minutos antes de volver a conectarse; la caducidad reabre automáticamente la admisión.

El contrato RPC es:

• gateway.suspend.prepare — operator.admin; parámetros { "requestId": "stable-host-operation-id" }
• gateway.suspend.status — operator.read; parámetros { "suspensionId": "id-from-prepare" }
• gateway.suspend.resume — operator.admin; parámetros { "suspensionId": "id-from-prepare" }

Se eliminan los espacios de los extremos de los identificadores, estos deben contener un carácter que no sea un espacio en blanco y están limitados a 128 caracteres. Un resultado de preparación ocupado tiene status: "busy", reason, retryAfterMs, activeCount y blockers. Un resultado listo tiene esta estructura:

{  "status": "ready",  "suspensionId": "2c3f...",  "expiresAtMs": 1770000000000,  "activeCount": 0,  "blockers": []}

El estado devuelve {"status":"running"} o un resultado listo con expiresAtMs. La reanudación devuelve {"ok":true,"status":"running","resumed":true}; si se repite tras una reanudación correcta, devuelve resumed: false.

Un identificador de solicitud competidor o un fallo transitorio al reanudar el planificador devuelve el error reintentable UNAVAILABLE con retryAfterMs. Durante la recuperación del planificador, la preparación, el estado y la reanudación devuelven ese error, el Gateway permanece no preparado y cerrado ante fallos, y el host no debe congelarlo ni crear una instantánea. OpenClaw vuelve a intentar la operación del planificador automáticamente y solo reabre la admisión cuando la recuperación se completa correctamente. Un identificador de reanudación que no coincida devuelve INVALID_REQUEST. La preparación comparte el presupuesto de escritura del plano de control del Gateway de tres intentos por minuto; respete la demora de reintento devuelta. Los clientes WebSocket se agrupan por dispositivo y dirección IP. Los controladores HTTP de administración se agrupan por la dirección IP resuelta del cliente, por lo que los controladores situados detrás de un mismo proxy pueden compartir un presupuesto.

La preparación solo puede rechazar: OpenClaw cierra la admisión de nuevas operaciones raíz, de sesión y de comandos, pausa los ciclos automáticos de Cron e inspecciona el trabajo de forma síncrona. Si hay alguna actividad, reanuda el planificador y reabre la admisión antes de devolver busy; no interrumpe ni vacía ese trabajo. Una concesión lista dura dos minutos. Repetir prepare con el mismo requestId la renueva; al caducar, reanuda el planificador antes de reabrir la admisión. La emisión de reinicio cuyo plazo venza durante una concesión lista espera hasta que esta se reanude; un reinicio en curso hace que la preparación devuelva busy.

Mientras está listo, /healthz permanece activo y /readyz devuelve 503. Las respuestas de disponibilidad locales o autenticadas incluyen gateway-draining; las sondas remotas no autenticadas reciben únicamente { "ready": false }. La sonda de estado HTTP, los métodos de suspensión en conexiones WebSocket existentes y una ruta RPC HTTP de administración ya habilitada permanecen disponibles. Los demás RPC devuelven el error reintentable UNAVAILABLE. Las rutas HTTP integradas para trabajo de usuario y las rutas HTTP ordinarias de Plugins, incluidas las API compatibles con OpenAI, las operaciones de herramientas y sesiones, la supervisión de Nodes y los hooks configurados, devuelven 503 con error.code: "gateway_unavailable". Las nuevas actualizaciones de WebSocket propiedad de Plugins también devuelven 503; esto abarca la propiedad de la actualización, no el trabajo realizado posteriormente mediante un socket de Plugin ya establecido.

Esta negociación no conserva los mensajes entrantes, no detiene los transportes de canales de terceros ni controla la plataforma de alojamiento. El host debe bloquear su tráfico entrante antes de la preparación y sigue siendo responsable de la activación, la instantánea o congelación y la detención. activeCount es el recuento agregado de trabajo supervisado, mientras que blockers contiene los recuentos de categorías distintos de cero y detalles limitados de las tareas. Esto no es una barrera general de inactividad del proceso. Un bloqueo background-exec solo es agregado: el texto de los comandos, los identificadores de procesos, la salida y los identificadores de sesión o ámbito nunca atraviesan el protocolo. El estado de los canales, el mantenimiento, la actualización de la caché, las sesiones WebSocket de Plugins establecidas y el trabajo en segundo plano no registrado propiedad de Plugins pueden permanecer activos. La plataforma de alojamiento debe congelar o crear una instantánea de forma coherente de todo el árbol de procesos y de su sistema de archivos; este primer contrato no puede demostrar que el trabajo no registrado esté inactivo.

Código de aplicaciones frente a código de Plugins

Use RPC del Gateway cuando el código se encuentre fuera de OpenClaw:

• Scripts de Node que inician u observan ejecuciones de agentes
• Trabajos de CI que llaman a un Gateway
• Paneles y paneles de administración
• Extensiones de IDE
• Puentes externos que no necesitan convertirse en Plugins de canal
• Pruebas de integración con transportes del Gateway simulados o reales

Use el SDK de Plugin cuando el código se ejecute dentro de OpenClaw:

• Plugins de proveedores
• Plugins de canales
• Hooks de herramientas o del ciclo de vida
• Plugins del entorno de ejecución de agentes
• Utilidades de confianza del entorno de ejecución

Las aplicaciones externas no deben importar openclaw/plugin-sdk/*; esas subrutas están destinadas a los Plugins cargados por OpenClaw.

Contenido relacionado

• Protocolo del Gateway
• Referencia RPC del Gateway
• Comando de agente de la CLI
• Comando de mensajes de la CLI
• Bucle del agente
• Entornos de ejecución de agentes
• Sesiones
• Tareas en segundo plano
• Agentes ACP
• Descripción general del SDK de Plugin