Architektura Gateway¶

Ostatnia aktualizacja: 2026-01-22

Przegląd¶

• Jeden długotrwały Gateway posiada wszystkie powierzchnie komunikacyjne (WhatsApp przez Baileys, Telegram przez grammY, Slack, Discord, Signal, iMessage, WebChat).
• Klienci płaszczyzny sterowania (aplikacja na macOS, CLI, interfejs webowy, automatyzacje) łączą się z Gateway przez WebSocket na skonfigurowanym hoście bindowania (domyślnie 127.0.0.1:18789).
• Węzły (macOS/iOS/Android/headless) również łączą się przez WebSocket, ale deklarują role: node z jawnymi uprawnieniami/komendami.
• Jeden Gateway na host; jest to jedyne miejsce, które otwiera sesję WhatsApp.
• Host canvas (domyślnie 18793) serwuje edytowalny przez agenta HTML oraz A2UI.

Komponenty i przepływy¶

Gateway (demon)¶

• Utrzymuje połączenia z dostawcami.
• Udostępnia typowany interfejs API WS (żądania, odpowiedzi, zdarzenia push z serwera).
• Waliduje przychodzące ramki względem JSON Schema.
• Emituje zdarzenia takie jak agent, chat, presence, health, heartbeat, cron.

Klienci (aplikacja na macOS / CLI / panel webowy)¶

• Jedno połączenie WS na klienta.
• Wysyłają żądania (health, status, send, agent, system-presence).
• Subskrybują zdarzenia (tick, agent, presence, shutdown).

Węzły (macOS / iOS / Android / headless)¶

• Łączą się z tym samym serwerem WS z role: node.
• Dostarczają tożsamość urządzenia w connect; parowanie jest oparte na urządzeniu (rola node), a zatwierdzenie jest przechowywane w magazynie parowania urządzeń.
• Udostępniają komendy takie jak canvas.*, camera.*, screen.record, location.get.

Szczegóły protokołu:

• Gateway protocol

WebChat¶

• Statyczny interfejs, który używa API WS Gateway do historii czatu i wysyłania wiadomości.
• W konfiguracjach zdalnych łączy się przez ten sam tunel SSH/Tailscale co inne klienty.

Cykl życia połączenia (pojedynczy klient)¶

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#ffffff',
    'primaryTextColor': '#000000',
    'primaryBorderColor': '#000000',
    'lineColor': '#000000',
    'secondaryColor': '#f9f9fb',
    'tertiaryColor': '#ffffff',
    'clusterBkg': '#f9f9fb',
    'clusterBorder': '#000000',
    'nodeBorder': '#000000',
    'mainBkg': '#ffffff',
    'edgeLabelBackground': '#ffffff'
  }
}}%%
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}

Protokół „na drucie” (podsumowanie)¶

• Transport: WebSocket, ramki tekstowe z ładunkami JSON.
• Pierwsza ramka musi być connect.
• Po uzgodnieniu:
• Żądania: {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
• Zdarzenia: {type:"event", event, payload, seq?, stateVersion?}
• Jeśli ustawiono OPENCLAW_GATEWAY_TOKEN (lub --token), connect.params.auth.token musi się zgadzać, w przeciwnym razie gniazdo jest zamykane.
• Klucze idempotencji są wymagane dla metod wywołujących skutki uboczne (send, agent), aby umożliwić bezpieczne ponawianie; serwer utrzymuje krótkotrwałą pamięć podręczną deduplikacji.
• Węzły muszą dołączyć role: "node" oraz uprawnienia/komendy/pozwolenia w connect.

Parowanie + lokalne zaufanie¶

• Wszyscy klienci WS (operatorzy + węzły) dołączają tożsamość urządzenia w connect.
• Nowe identyfikatory urządzeń wymagają zatwierdzenia parowania; Gateway wydaje token urządzenia do kolejnych połączeń.
• Połączenia lokalne (local loopback lub własny adres tailnet hosta gateway) mogą być automatycznie zatwierdzane, aby zachować płynne UX na tym samym hoście.
• Połączenia nielokalne muszą podpisać nonce connect.challenge i wymagają jawnego zatwierdzenia.
• Uwierzytelnianie Gateway (gateway.auth.*) nadal obowiązuje dla wszystkich połączeń, lokalnych i zdalnych.

Szczegóły: Gateway protocol, Pairing, Security.

Typowanie protokołu i generowanie kodu¶

• Schematy TypeBox definiują protokół.
• JSON Schema jest generowany z tych schematów.
• Modele Swift są generowane z JSON Schema.

Dostęp zdalny¶

• Preferowane: Tailscale lub VPN.

• Alternatywa: tunel SSH

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

• To samo uzgodnienie + token uwierzytelniania obowiązują przez tunel.

• TLS + opcjonalne pinning można włączyć dla WS w konfiguracjach zdalnych.

Migawka operacyjna¶

• Start: openclaw gateway (na pierwszym planie, logi do stdout).
• Zdrowie: health przez WS (również zawarte w hello-ok).
• Nadzór: launchd/systemd do automatycznego restartu.

Niezmienniki¶

• Dokładnie jeden Gateway kontroluje jedną sesję Baileys na hosta.
• Uzgodnienie jest obowiązkowe; każda pierwsza ramka nie‑JSON lub inna niż connect skutkuje natychmiastowym zamknięciem.
• Zdarzenia nie są odtwarzane; klienci muszą odświeżać stan po wystąpieniu luk.