Integraciones del Gateway para aplicaciones externas

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

Qué está disponible actualmente

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 de RPC del Gateway.
4. Fije la versión de OpenClaw con la que realiza las pruebas.
5. Vuelva a consultar la referencia de 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 conservar el estado de las conversaciones, utilice los métodos sessions.*. Para las integraciones de interfaz de usuario, suscríbase a los eventos del Gateway y represente únicamente las familias de eventos que la aplicación comprenda.

Suspensión cooperativa del host

Los controladores de alojamiento que congelan o capturan una instantánea de un proceso en ejecución pueden utilizar 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 valor suspensionId devuelto y, a continuación, congele o capture una instantánea del proceso antes de expiresAtMs.
5. Después de 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 no se puede garantizar, habilite y utilice el Plugin RPC HTTP de administración antes de 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 la admisión automáticamente.

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

Los identificadores se recortan, 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 contiene status: "busy", reason, retryAfterMs, activeCount y blockers. Un resultado listo tiene esta forma:

{  "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}; repetirla después de una reanudación correcta devuelve resumed: false.

Un identificador de solicitud en conflicto 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 disponible y en modo de fallo cerrado, y el host no debe congelarlo ni capturar una instantánea. OpenClaw reintenta la recuperació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 el retraso de reintento devuelto. Los clientes WebSocket se agrupan por dispositivo e IP. Los controladores HTTP de administración se agrupan por la IP resuelta del cliente, por lo que los controladores detrás de un mismo proxy pueden compartir un presupuesto.

La preparación solo permite rechazar: OpenClaw cierra la admisión de nuevas operaciones raíz, sesiones y comandos, pausa las activaciones automáticas 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 espera a que finalice ese trabajo. Una concesión lista dura dos minutos. Repetir prepare con el mismo requestId la renueva; al caducar, se reanuda el planificador antes de reabrir la admisión. Una emisión de reinicio cuyo momento llegue durante una concesión lista espera hasta que se reanude la concesión; 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; los sondeos remotos no autenticados reciben únicamente { "ready": false }. El sondeo de estado HTTP, los métodos de suspensión de las conexiones WebSocket existentes y una ruta RPC HTTP de administración ya habilitada permanecen disponibles. Otros RPC devuelven el error reintentable UNAVAILABLE. Las rutas HTTP integradas de trabajo del usuario y las rutas HTTP habituales de los Plugins, incluidas las API compatibles con OpenAI, las operaciones de herramientas y sesiones, las observaciones de nodos y los hooks configurados, devuelven 503 con error.code: "gateway_unavailable". Las nuevas actualizaciones 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 captura de instantáneas 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 bloqueador background-exec es únicamente agregado: el texto de los comandos, los identificadores de procesos, la salida y los identificadores de sesiones o ámbitos 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 capturar una instantánea de todo el árbol de procesos y su sistema de archivos de forma coherente; este primer contrato no puede demostrar que el trabajo no registrado esté inactivo.

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

Utilice RPC del Gateway cuando el código resida 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 canales
• Pruebas de integración con transportes del Gateway simulados o reales

Utilice el SDK de Plugins cuando el código se ejecute dentro de OpenClaw:

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

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

Temas relacionados

• Crear un cliente del Gateway
• Integrar OpenClaw
• Protocolo del Gateway
• Referencia de 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 Plugins