Arquitectura del gateway

Última actualización: 2026-01-22

Visión general

  • Un único Gateway de larga duración gestiona 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, UI web, automatizaciones) se conectan al Gateway a través de WebSocket en el host de enlace configurado (por defecto 127.0.0.1:18789).
  • Los Nodos (macOS/iOS/Android/headless) también se conectan por 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 host de canvas es servido por el servidor HTTP del Gateway bajo:
    • /__openclaw__/canvas/ (HTML/CSS/JS editable por el agente)
    • /__openclaw__/a2ui/ (host A2UI) Usa el mismo puerto que el Gateway (por defecto 18789).

Componentes y flujos

Gateway (daemon)

  • Mantiene las conexiones con providers.
  • Expone una API WS tipada (requests, responses, eventos push del servidor).
  • Valida frames entrantes contra JSON Schema.
  • Emite eventos como agent, chat, presence, health, heartbeat, cron.

Clientes (app de macOS / CLI / admin web)

  • Una conexión WS por cliente.
  • Envían requests (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 emparejamiento es basado en dispositivo (rol node) y la aprobación reside en el almacén de emparejamiento 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 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 (un cliente)

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 red (resumen)

  • Transporte: WebSocket, frames de texto con payloads JSON.
  • El primer frame debe ser connect.
  • Después del handshake:
    • Requests: {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.
  • Las claves de idempotencia son obligatorias para métodos con efectos secundarios (send, agent) para reintentar de forma segura; el servidor mantiene una caché de deduplicación de corta duración.
  • Los nodos deben incluir role: "node" más caps/commands/permissions en connect.

Emparejamiento + confianza local

  • Todos los clientes WS (operadores + nodos) incluyen una identidad de dispositivo en connect.
  • Los nuevos IDs de dispositivo requieren aprobación de emparejamiento; el Gateway emite un token de dispositivo para conexiones posteriores.
  • Las conexiones locales (loopback o la dirección tailnet propia del host del gateway) pueden ser auto-aprobadas para mantener fluida la UX en el mismo host.
  • Todas las conexiones deben firmar el nonce connect.challenge.
  • El payload de firma v3 también vincula platform + deviceFamily; el gateway fija los metadatos emparejados en la reconexión y requiere re-emparejamiento para cambios de metadatos.
  • Las conexiones no locales aún requieren aprobación explícita.
  • La autenticación del Gateway (gateway.auth.*) sigue aplicándose a todas las conexiones, locales o remotas.

Detalles: Protocolo del Gateway, Emparejamiento, Seguridad.

Tipado del protocolo y codegen

  • 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 aplican a través del túnel.

  • TLS + pinning opcional pueden habilitarse para WS en configuraciones remotas.

Resumen operativo

  • Iniciar: openclaw gateway (en primer plano, logs a stdout).
  • Salud: health vía WS (también incluido en hello-ok).
  • Supervisión: launchd/systemd para auto-reinicio.

Invariantes

  • Exactamente un Gateway controla una única sesión de Baileys por host.
  • El handshake es obligatorio; cualquier frame no JSON o no connect como primer frame cierra la conexión.
  • Los eventos no se reenvían; los clientes deben refrescar ante vacíos.
arrow_back
Anterior
Pi
Siguiente
Agent
arrow_forward