OpenClaw Gateway Architektur: WebSocket API einrichten

Kennst du das? Du versuchst, eine Handvoll Messaging-APIs zu bändigen, und plötzlich verbringst du mehr Zeit mit dem Debugging von Verbindungsabbrüchen als mit dem eigentlichen Feature-Bau. Es ist frustrierend, wenn jeder Dienst seine eigene Logik erzwingt und dein Backend im State-Chaos versinkt.

Hier kommt die Gateway-Architektur ins Spiel. Wir haben das System so entworfen, dass es die Komplexität wegkapselt und dir eine saubere, einheitliche Schnittstelle bietet. In diesem Guide erfährst du, wie das Gateway als zentrales Nervensystem für deine Messaging-Oberflächen fungiert.

Übersicht

• Ein einzelnes, langlebiges Gateway verwaltet alle Messaging-Oberflächen (WhatsApp via Baileys, Telegram via grammY, Slack, Discord, Signal, iMessage, WebChat).
• Control-Plane-Clients (macOS App, CLI, Web-UI, Automatisierungen) verbinden sich mit dem Gateway über WebSocket auf dem konfigurierten Bind-Host (Standard ist 127.0.0.1:18789).
• Nodes (macOS/iOS/Android/headless) verbinden sich ebenfalls über WebSocket, deklarieren aber role: node mit expliziten Caps/Commands.
• Es gibt nur ein Gateway pro Host; dies ist der einzige Ort, der eine WhatsApp-Session öffnet.
• Der Canvas-Host wird vom Gateway-HTTP-Server bereitgestellt unter:
  • /__openclaw__/canvas/ (vom Agenten editierbares HTML/CSS/JS)
  • /__openclaw__/a2ui/ (A2UI-Host) Er nutzt denselben Port wie das Gateway (Standard 18789).

Komponenten und Abläufe

Gateway (Daemon)

• Hält die Verbindungen zu den Providern aufrecht.
• Stellt eine typisierte WS API bereit (Requests, Responses, Server-Push-Events).
• Validiert eingehende Frames gegen das JSON Schema.
• Emittiert Events wie agent, chat, presence, health, heartbeat und cron.

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 mit dem gleichen WS-Server mit der Rolle role: node.
• Geben beim connect eine Device-Identity an; das Pairing ist gerätebasiert (Rolle node) und die Freigabe wird im Device-Pairing-Store gespeichert.
• Stellen Commands wie canvas.*, camera.*, screen.record und location.get zur Verfügung.

Protokoll-Details:

• Gateway protocol

WebChat

• Statische UI, die die Gateway WS API für den Chat-Verlauf und das Senden nutzt.
• Verbindet sich in Remote-Setups durch denselben SSH/Tailscale-Tunnel wie andere Clients.

Verbindungszyklus (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 übereinstimmen, sonst schließt sich der Socket.
• Idempotency-Keys sind für Methoden mit Seiteneffekten (send, agent) erforderlich, um Retries sicher durchzuführen; der Server nutzt einen kurzlebigen Deduplizierungs-Cache.
• Nodes müssen role: "node" sowie Caps/Commands/Permissions im connect mitsenden.

Pairing + lokales Vertrauen

• Alle WS-Clients (Operatoren + Nodes) senden beim connect eine Device-Identity mit.
• Neue Device-IDs erfordern eine Pairing-Zustimmung; das Gateway stellt ein Device-Token für nachfolgende Verbindungen aus.
• Lokale Verbindungen (Loopback oder die eigene Tailnet-Adresse des Gateway-Hosts) können automatisch genehmigt werden, um die UX auf demselben Host einfach zu halten.
• Alle Verbindungen müssen die connect.challenge Nonce signieren.
• Die Signatur-Payload v3 bindet auch platform + deviceFamily; das Gateway pinnt die gepaarten Metadaten beim Reconnect und erfordert ein Repair-Pairing bei Änderungen der Metadaten.
• Nicht-lokale Verbindungen erfordern weiterhin eine explizite Zustimmung.
• Die Gateway-Auth (gateway.auth.*) gilt weiterhin für alle Verbindungen, egal ob lokal oder remote.

Details: Gateway protocol, Pairing, Security.

Protokoll-Typisierung und Codegen

• TypeBox-Schemas definieren das Protokoll.
• Das 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 + Auth-Token gelten auch über den Tunnel.

• TLS + optionales Pinning können für WS in Remote-Setups aktiviert werden.

Betriebs-Snapshot

• Start: openclaw gateway (Vordergrund, Logs nach stdout).
• Health: health über WS (auch in hello-ok enthalten).
• Überwachung: launchd/systemd für automatischen Neustart.

Invarianten

• Genau ein Gateway kontrolliert eine einzelne Baileys-Session pro Host.
• Der Handshake ist obligatorisch; jeder erste Frame, der kein JSON oder kein connect ist, führt zum sofortigen Schließen der Verbindung.
• Events werden nicht wiederholt; Clients müssen den Zustand bei Lücken aktualisieren.

Verwandte Themen

• Agent Loop — detaillierter Ausführungszyklus des Agenten
• Gateway Protocol — WebSocket-Protokoll-Spezifikation
• Queue — Befehlswarteschlange und Concurrency
• Security — Vertrauensmodell und Hardening

Nächste Schritte

• Schau dir das Gateway Protocol an, um eigene Clients zu bauen.
• Erfahre mehr über Security, um dein Setup abzusichern.

Hast du Fragen zur Architektur? Frag unseren AI Setup Assistant.