Arquitectura de Gateway OpenClaw: Guía de integración

¿Alguna vez has intentado gestionar varias plataformas de mensajería a la vez y has terminado con un caos de conexiones? Mantener la sincronización entre WhatsApp, Slack y Telegram sin que el sistema se rompa es un reto técnico que requiere una estructura clara.

En este artículo vamos a ver cómo el Gateway organiza estas comunicaciones para que tú solo tengas que preocuparte de construir tu lógica.

Resumen general

• Un solo Gateway de larga duración controla todas las superficies de mensajería (WhatsApp vía Baileys, Telegram vía grammY, Slack, Discord, Signal, iMessage, WebChat).
• Los clientes del plano de control (app de macOS, CLI, interfaz web, automatizaciones) se conectan al Gateway mediante WebSocket en el host configurado (por defecto 127.0.0.1:18789).
• Los Nodes (macOS/iOS/Android/headless) también se conectan por WebSocket, pero declaran role: node con capacidades y comandos explícitos.
• Solo hay un Gateway por host; es el único lugar que abre una sesión de WhatsApp.
• El canvas host es servido por el servidor HTTP del Gateway bajo:
  • /__openclaw__/canvas/ (HTML/CSS/JS editable por el agente)
  • /__openclaw__/a2ui/ (host de A2UI) Usa el mismo puerto que el Gateway (por defecto 18789).

Componentes y flujos

Gateway (daemon)

• Mantiene las conexiones de los proveedores.
• Expone una WS API tipada con peticiones y respuestas, además de eventos server‑push.
• Valida los frames entrantes contra JSON Schema.
• Emite eventos como agent, chat, presence, health, heartbeat y cron.

Clients (mac app / CLI / web admin)

• Una conexión WS por cliente.
• Envían peticiones (health, status, send, agent, system-presence).
• Se suscriben a eventos (tick, agent, presence, shutdown).

Nodes (macOS / iOS / Android / headless)

• Se conectan al mismo servidor WS con role: node.
• Proporcionan una identidad de dispositivo en connect; la vinculación se basa en el dispositivo (rol node) y la aprobación reside en el almacén de vinculación de dispositivos.
• Exponen comandos como canvas.*, camera.*, screen.record y location.get.

Detalles del protocolo:

• Gateway protocol

WebChat

• Interfaz estática que usa la Gateway WS API para el historial de chat y envíos.
• En configuraciones remotas, se conecta a través del mismo túnel SSH/Tailscale que otros clientes.

Ciclo de vida de la conexión (cliente único)

sequenceDiagram
    participant Client
    participant Gateway

    Client->>Gateway: req:connect
    Gateway-->>Client: res (ok)
    Note right of Gateway: or res error + close
    Note left of Client: payload=hello-ok<br>snapshot: presence + health

    Gateway-->>Client: event:presence
    Gateway-->>Client: event:tick

    Client->>Gateway: req:agent
    Gateway-->>Client: res:agent<br>ack {runId, status:"accepted"}
    Gateway-->>Client: event:agent<br>(streaming)
    Gateway-->>Client: res:agent<br>final {runId, status, summary}

Protocolo de comunicación (resumen)

• Transporte: WebSocket, frames de texto con payloads JSON.
• El primer frame debe ser connect.
• Después del handshake:
  • Peticiones: {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
  • Eventos: {type:"event", event, payload, seq?, stateVersion?}
• Si OPENCLAW_GATEWAY_TOKEN (o --token) está configurado, connect.params.auth.token debe coincidir o el socket se cierra.
• Se requieren claves de idempotencia para métodos con efectos secundarios (send, agent) para reintentar de forma segura; el servidor mantiene un caché de deduplicación de corta duración.
• Los Nodes deben incluir role: "node" junto con sus capacidades, comandos y permisos en connect.

Vinculación y confianza local

• Todos los clientes WS (operadores + nodes) incluyen una identidad de dispositivo al conectar.
• Los nuevos IDs de dispositivo requieren aprobación de vinculación; el Gateway emite un token de dispositivo para conexiones posteriores.
• Las conexiones locales (loopback o la dirección de tailnet del propio host del gateway) pueden auto‑aprobarse para que la experiencia de usuario en el mismo host sea fluida.
• Todas las conexiones deben firmar el nonce connect.challenge.
• El payload de firma v3 también vincula platform + deviceFamily; el gateway fija los metadatos vinculados al reconectar y requiere reparar la vinculación si hay cambios en los metadatos.
• Las conexiones no locales siguen requiriendo aprobación explícita.
• La autenticación del Gateway (gateway.auth.*) se aplica a todas las conexiones, ya sean locales o remotas.

Detalles: Gateway protocol, Pairing, Security.

Tipado del protocolo y generación de código

• Los esquemas de TypeBox definen el protocolo.
• El JSON Schema se genera a partir de esos esquemas.
• Los modelos de Swift se generan a partir del JSON Schema.

Acceso remoto

• Preferido: Tailscale o VPN.

• Alternativa: Túnel SSH

  ssh -N -L 18789:127.0.0.1:18789 user@host

• El mismo handshake y token de autenticación se aplican sobre el túnel.

• Se puede habilitar TLS y pinning opcional para WS en configuraciones remotas.

Instantánea de operaciones

• Inicio: openclaw gateway (en primer plano, logs a stdout).
• Salud: health sobre WS (también incluido en hello-ok).
• Supervisión: launchd/systemd para reinicio automático.

Invariantes

• Exactamente un Gateway controla una única sesión de Baileys por host.
• El handshake es obligatorio; cualquier primer frame que no sea JSON o connect provoca un cierre inmediato.
• Los eventos no se repiten; los clientes deben refrescar si detectan vacíos en la información.

Relacionado

• Agent Loop — ciclo de ejecución detallado del agente
• Gateway Protocol — contrato del protocolo WebSocket
• Queue — cola de comandos y concurrencia
• Security — modelo de confianza y endurecimiento de seguridad

Siguientes pasos

• Explora el Gateway Protocol para entender los mensajes a bajo nivel.
• Configura la Seguridad para proteger tus conexiones remotas.

AI Setup Assistant