Gateway-Architektur

Zuletzt aktualisiert: 22.01.2026

Ueberblick

• Ein einzelnes langlebendes Gateway verwaltet alle Messaging-Oberflaechen (WhatsApp ueber Baileys, Telegram ueber grammY, Slack, Discord, Signal, iMessage, WebChat).
• Control-Plane-Clients (macOS-App, CLI, Web-UI, Automatisierungen) verbinden sich ueber WebSocket mit dem Gateway auf dem konfigurierten Bind-Host (Standard 127.0.0.1:18789).
• Nodes (macOS/iOS/Android/Headless) verbinden sich ebenfalls ueber WebSocket, deklarieren aber role: node mit expliziten Caps/Commands.
• Ein Gateway pro Host; es ist der einzige Ort, der eine WhatsApp-Sitzung oeffnet.
• Der Canvas-Host wird vom Gateway-HTTP-Server unter folgenden Pfaden bereitgestellt:
  • /__openclaw__/canvas/ (vom Agenten bearbeitbares HTML/CSS/JS)
  • /__openclaw__/a2ui/ (A2UI-Host) Er nutzt denselben Port wie das Gateway (Standard 18789).

Komponenten und Ablaeufe

Gateway (Daemon)

• Haelt Provider-Verbindungen aufrecht.
• Stellt eine typisierte WS-API bereit (Requests, Responses, Server-Push-Events).
• Validiert eingehende Frames gegen JSON-Schema.
• Gibt Events wie agent, chat, presence, health, heartbeat, cron aus.

Clients (Mac-App / CLI / Web-Admin)

• Eine WS-Verbindung pro Client.
• Senden Requests (health, status, send, agent, system-presence).
• Abonnieren Events (tick, agent, presence, shutdown).

Nodes (macOS / iOS / Android / Headless)

• Verbinden sich zum selben WS-Server mit role: node.
• Liefern eine Geraeteidentitaet beim connect; das Pairing ist geraetebasiert (Rolle node) und die Genehmigung liegt im Geraete-Pairing-Store.
• Stellen Befehle bereit wie canvas.*, camera.*, screen.record, location.get.

Protokolldetails:

• Gateway-Protokoll

WebChat

• Statische UI, die die Gateway-WS-API fuer Chat-Verlauf und Sends nutzt.
• Bei Remote-Setups verbindet sie sich ueber denselben SSH/Tailscale-Tunnel wie andere Clients.

Verbindungs-Lebenszyklus (einzelner Client)

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}

Wire-Protokoll (Zusammenfassung)

• Transport: WebSocket, Text-Frames mit JSON-Payloads.
• Der erste Frame muss connect sein.
• Nach dem Handshake:
  • Requests: {type:"req", id, method, params} -> {type:"res", id, ok, payload|error}
  • Events: {type:"event", event, payload, seq?, stateVersion?}
• Wenn OPENCLAW_GATEWAY_TOKEN (oder --token) gesetzt ist, muss connect.params.auth.token uebereinstimmen, sonst wird der Socket geschlossen.
• Idempotenz-Schluessel sind fuer seiteneffektbehaftete Methoden (send, agent) erforderlich, um sicheres Wiederholen zu ermoeglichen; der Server haelt einen kurzlebigen Dedupe-Cache.
• Nodes muessen role: "node" plus Caps/Commands/Permissions in connect mitliefern.

Pairing und lokales Vertrauen

• Alle WS-Clients (Operatoren und Nodes) liefern eine Geraeteidentitaet beim connect.
• Neue Geraete-IDs erfordern eine Pairing-Genehmigung; das Gateway gibt ein Geraete-Token fuer nachfolgende Connects aus.
• Lokale Connects (Loopback oder die eigene Tailnet-Adresse des Gateway-Hosts) koennen automatisch genehmigt werden, damit die UX auf demselben Host reibungslos bleibt.
• Alle Connects muessen die connect.challenge-Nonce signieren.
• Signatur-Payload v3 bindet auch platform und deviceFamily; das Gateway fixiert die gepairten Metadaten beim Reconnect und verlangt Repair-Pairing bei Metadaten-Aenderungen.
• Nicht-lokale Connects erfordern weiterhin eine explizite Genehmigung.
• Gateway-Auth (gateway.auth.*) gilt fuer alle Verbindungen, lokal oder remote.

Details: Gateway-Protokoll, Pairing, Sicherheit.

Protokoll-Typisierung und Codegen

• TypeBox-Schemas definieren das Protokoll.
• JSON-Schema wird aus diesen Schemas generiert.
• Swift-Modelle werden aus dem JSON-Schema generiert.

Remote-Zugriff

• Bevorzugt: Tailscale oder VPN.

• Alternative: SSH-Tunnel

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

• Derselbe Handshake und Auth-Token gelten auch ueber den Tunnel.

• TLS und optionales Pinning koennen fuer WS in Remote-Setups aktiviert werden.

Betriebs-Snapshot

• Start: openclaw gateway (Vordergrund, loggt auf stdout).
• Health: health ueber WS (auch in hello-ok enthalten).
• Supervision: launchd/systemd fuer automatischen Neustart.

Invarianten

• Genau ein Gateway kontrolliert eine einzelne Baileys-Sitzung pro Host.
• Der Handshake ist Pflicht; jeder Nicht-JSON- oder Nicht-Connect-erste-Frame fuehrt zu einem harten Close.
• Events werden nicht wiederholt; Clients muessen bei Luecken aktualisieren.