Hoppa till huvudinnehåll

​
Gateway-arkitektur

Senast uppdaterad: 2026-01-22

​
Översikt

  • En enda långlivad Gateway äger alla meddelandeytor (WhatsApp via Baileys, Telegram via grammY, Slack, Discord, Signal, iMessage, WebChat).
  • Kontrollplansklienter (macOS-app, CLI, webb-UI, automationer) ansluter till Gateway via WebSocket på den konfigurerade bind-värden (standard 127.0.0.1:18789).
  • Noder (macOS/iOS/Android/headless) ansluter också via WebSocket, men deklarerar role: node med explicita capabiliteter/kommandon.
  • En Gateway per värd; det är den enda platsen som öppnar en WhatsApp-session.
  • En canvas-värd (standard 18793) serverar agent-redigerbar HTML och A2UI.
    • /__openclaw__/canvas/ (agentredigerbar HTML/CSS/JS)
    • /__openclaw__/a2ui/ (A2UI-värd) Den använder samma port som Gateway (standard 18789).

​
Komponenter och flöden

​
Gateway (daemon)

  • Upprätthåller leverantörsanslutningar.
  • Exponerar ett typat WS-API (förfrågningar, svar, server‑push‑händelser).
  • Validerar inkommande ramar mot JSON Schema.
  • Sänder händelser som agent, chat, presence, health, heartbeat, cron.

​
Klienter (mac-app / CLI / webbadmin)

  • En WS-anslutning per klient.
  • Skickar förfrågningar (health, status, send, agent, system-presence).
  • Prenumererar på händelser (tick, agent, presence, shutdown).

​
Noder (macOS / iOS / Android / headless)

  • Ansluter till samma WS-server med role: node.
  • Tillhandahåller en enhetsidentitet i connect; parning är enhetsbaserad (roll node) och godkännandet lagras i enhetens parningslager.
  • Exponerar kommandon som canvas.*, camera.*, screen.record, location.get.
Protokolldetaljer:

​
WebChat

  • Statisk UI som använder Gateway WS-API för chattlogg och sändningar.
  • I fjärrinstallationer ansluter den via samma SSH-/Tailscale-tunnel som andra klienter.

​
Anslutningslivscykel (enskild klient)

​
Trådprotokoll (sammanfattning)

  • Transport: WebSocket, textramar med JSON-payloads.
  • Första ramen måste vara connect.
  • Efter handskakning:
    • Förfrågningar: {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
    • Händelser: {type:"event", event, payload, seq?, stateVersion?}
  • Om OPENCLAW_GATEWAY_TOKEN (eller --token) är satt, connect.params.auth.token måste matcha annars stängs socketen.
  • Idempotensnycklar krävs för metoder med sidoeffekter (send, agent) för säker omförsök; servern håller en kortlivad dedupliceringscache.
  • Noder måste inkludera role: "node" samt capabiliteter/kommandon/behörigheter i connect.

​
Parning + lokal tillit

  • Alla WS-klienter (operatörer + noder) inkluderar en enhetsidentitet i connect.
  • Nya enhets-ID:n kräver parningsgodkännande; Gateway utfärdar en enhetstoken för efterföljande anslutningar.
  • Lokala anslutningar (loopback eller gateway-värdens egen tailnet-adress) kan auto‑godkännas för att hålla UX smidig på samma värd.
  • Icke‑lokala anslutningar måste signera connect.challenge-nonce och kräver explicit godkännande.
  • Gateway-autentisering (gateway.auth.*) gäller fortfarande för alla anslutningar, lokala eller fjärranslutna.
Detaljer: Gateway-protokoll, Parning, Säkerhet.

​
Protokolltypning och kodgenerering

  • TypeBox-scheman definierar protokollet.
  • JSON Schema genereras från dessa scheman.
  • Swift-modeller genereras från JSON Schema.

​
Fjärråtkomst

  • Föredragen: Tailscale eller VPN.
  • Alternativ: SSH-tunnel 
    ssh -N -L 18789:127.0.0.1:18789 user@host
  • Samma handskakning + autentiseringstoken gäller över tunneln.
  • TLS + valfri pinning kan aktiveras för WS i fjärrinstallationer.

​
Driftöversikt

  • Start: openclaw gateway (förgrund, loggar till stdout).
  • Hälsa: health via WS (ingår också i hello-ok).
  • Övervakning: launchd/systemd för automatisk omstart.

​
Invarianter

  • Exakt en Gateway kontrollerar en enskild Baileys-session per värd.
  • Handskakning är obligatorisk; alla icke‑JSON- eller icke‑connect‑första ramar stänger hårt.
  • Händelser spelas inte upp igen; klienter måste uppdatera vid glapp.