---
read_when:
    - Trabajando en el protocolo del gateway, clientes o transportes
summary: Arquitectura del gateway WebSocket, componentes y flujos de clientes
title: Arquitectura del Gateway
x-i18n:
    generated_at: "2026-04-05T12:39:25Z"
    model: gpt-5.4
    provider: openai
    source_hash: 2b12a2a29e94334c6d10787ac85c34b5b046f9a14f3dd53be453368ca4a7547d
    source_path: concepts/architecture.md
    workflow: 15
---

# 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:

- [Gateway protocol](/gateway/protocol)

### 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)

```mermaid
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 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](/gateway/protocol), [Pairing](/channels/pairing),
[Security](/gateway/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

  ```bash
  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](/concepts/agent-loop) — ciclo detallado de ejecución del agente
- [Gateway Protocol](/gateway/protocol) — contrato del protocolo WebSocket
- [Queue](/concepts/queue) — cola de comandos y concurrencia
- [Security](/gateway/security) — modelo de confianza y endurecimiento
