Saltar al contenido principal

​
Arquitectura del gateway

​
Resumen

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

​
Componentes y flujos

​
Gateway (daemon)

  • Mantiene las conexiones de los proveedores.
  • Expone una API WS tipada (solicitudes, respuestas, eventos push del servidor).
  • Valida los frames entrantes con JSON Schema.
  • Emite eventos como agent, chat, presence, health, heartbeat, cron.

​
Clientes (app de macOS / CLI / administración web)

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

​
Nodos (macOS / iOS / Android / headless)

  • Se conectan al mismo servidor WS con role: node.
  • Proporcionan una identidad de dispositivo en connect; el pairing está basado en dispositivo (rol node) y la aprobación vive en el almacén de pairing de dispositivos.
  • Exponen comandos como canvas.*, camera.*, screen.record, location.get.
Detalles del protocolo:

​
WebChat

  • UI estática que usa la API WS del Gateway para el historial del chat y los envíos.
  • En configuraciones remotas, se conecta mediante el mismo túnel SSH/Tailscale que otros clientes.

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

​
Protocolo wire (resumen)

  • Transporte: WebSocket, frames de texto con carga útil JSON.
  • El primer frame debe ser connect.
  • Después del handshake:
    • Solicitudes: {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
    • Eventos: {type:"event", event, payload, seq?, stateVersion?}
  • hello-ok.features.methods / events son metadatos de descubrimiento, no un volcado generado de cada ruta auxiliar invocable.
  • La autenticación con secreto compartido usa connect.params.auth.token o connect.params.auth.password, según el modo de autenticación del gateway configurado.
  • Los modos con identidad, como Tailscale Serve (gateway.auth.allowTailscale: true) o gateway.auth.mode: "trusted-proxy" en interfaces no loopback, satisfacen la autenticación a partir de los encabezados de la solicitud en lugar de connect.params.auth.*.
  • gateway.auth.mode: "none" en ingreso privado desactiva por completo la autenticación con secreto compartido; mantén ese modo desactivado en ingresos públicos o no confiables.
  • Las claves de idempotencia son obligatorias para métodos con efectos secundarios (send, agent) para poder reintentar con seguridad; el servidor mantiene una caché de deduplicación de corta duración.
  • Los nodos deben incluir role: "node" más capacidades/comandos/permisos en connect.

​
Pairing + confianza local

  • Todos los clientes WS (operadores + nodos) incluyen una identidad de dispositivo en connect.
  • Los nuevos ID de dispositivo requieren aprobación de pairing; el Gateway emite un token de dispositivo para conexiones posteriores.
  • Las conexiones directas por local loopback pueden aprobarse automáticamente para mantener fluida la UX en el mismo host.
  • OpenClaw también tiene una ruta limitada de autoconnexión local de backend/contenedor para flujos auxiliares confiables con secreto compartido.
  • Las conexiones de tailnet y LAN, incluidas las vinculaciones tailnet del mismo host, siguen requiriendo aprobación explícita de pairing.
  • Todas las conexiones deben firmar el nonce connect.challenge.
  • La carga útil de firma v3 también vincula platform + deviceFamily; el gateway fija los metadatos emparejados al reconectar y requiere repair pairing para cambios de metadatos.
  • Las conexiones no locales siguen requiriendo aprobación explícita.
  • La autenticación del gateway (gateway.auth.*) sigue aplicándose a todas las conexiones, locales o remotas.
Detalles: Gateway protocol, Pairing, Security.

​
Tipado del protocolo y generación de código

  • Los esquemas TypeBox definen el protocolo.
  • JSON Schema se genera a partir de esos esquemas.
  • Los modelos 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 + token de autenticación se aplican a través del túnel.
  • Se pueden habilitar TLS + pinning opcional para WS en configuraciones remotas.

​
Resumen de operaciones

  • Inicio: openclaw gateway (en primer plano, logs a stdout).
  • Estado: health mediante 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 no JSON o que no sea connect provoca un cierre inmediato.
  • Los eventos no se reproducen de nuevo; los clientes deben refrescar en caso de huecos.

​
Relacionado

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