> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway-architectuur

# Gateway-architectuur

Laatst bijgewerkt: 2026-01-22

## Overzicht

* Eén enkele langlevende **Gateway** beheert alle berichtoppervlakken (WhatsApp via
  Baileys, Telegram via grammY, Slack, Discord, Signal, iMessage, WebChat).
* Control-plane-clients (macOS-app, CLI, web-UI, automatiseringen) verbinden met de
  Gateway via **WebSocket** op de geconfigureerde bind-host (standaard
  `127.0.0.1:18789`).
* **Nodes** (macOS/iOS/Android/headless) verbinden ook via **WebSocket**, maar
  declareren `role: node` met expliciete caps/opdrachten.
* Eén Gateway per host; dit is de enige plek die een WhatsApp-sessie opent.
* De **canvas host** wordt door de Gateway HTTP-server aangeboden onder:
  * `/__openclaw__/canvas/` (door de agent bewerkbare HTML/CSS/JS)
  * `/__openclaw__/a2ui/` (A2UI-host)
    Het gebruikt dezelfde poort als de Gateway (standaard `18789`).

## Componenten en stromen

### Gateway (daemon)

* Onderhoudt providerverbindingen.
* Stelt een getypeerde WS-API beschikbaar (requests, responses, server-push-events).
* Valideert inkomende frames tegen JSON Schema.
* Zendt events uit zoals `agent`, `chat`, `presence`, `health`, `heartbeat`, `cron`.

### Clients (mac-app / CLI / webbeheer)

* Eén WS-verbinding per client.
* Verzenden requests (`health`, `status`, `send`, `agent`, `system-presence`).
* Abonneren zich op events (`tick`, `agent`, `presence`, `shutdown`).

### Nodes (macOS / iOS / Android / headless)

* Verbinden met **dezelfde WS-server** met `role: node`.
* Leveren een apparaatidentiteit in `connect`; koppeling is **apparaat‑gebaseerd** (rol `node`) en
  goedkeuring leeft in de apparaatkoppelingsopslag.
* Stellen opdrachten beschikbaar zoals `canvas.*`, `camera.*`, `screen.record`, `location.get`.

Protocoldetails:

* [Gateway protocol](/gateway/protocol)

### WebChat

* Statische UI die de Gateway WS-API gebruikt voor chatgeschiedenis en verzenden.
* In remote-opstellingen verbindt via dezelfde SSH/Tailscale-tunnel als andere
  clients.

## Verbindingslevenscyclus (enkele client)

```mermaid theme={"theme":{"light":"min-light","dark":"min-dark"}}
sequenceDiagram
    participant Client
    participant Gateway

    Client->>Gateway: req:connect
    Gateway-->>Client: res (ok)
    Note right of Gateway: of 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-protocol (samenvatting)

* Transport: WebSocket, tekstframes met JSON-payloads.
* Eerste frame **moet** `connect` zijn.
* Na de handshake:
  * Requests: `{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`
  * Events: `{type:"event", event, payload, seq?, stateVersion?}`
* Als `OPENCLAW_GATEWAY_TOKEN` (of `--token`) is ingesteld, `connect.params.auth.token`
  moet overeenkomen, anders sluit de socket.
* Idempotentiesleutels zijn vereist voor methoden met neveneffecten (`send`, `agent`) om
  veilig te kunnen herhalen; de server houdt een kortlevende deduplicatiecache bij.
* Nodes moeten `role: "node"` opnemen plus caps/opdrachten/rechten in `connect`.

## Koppeling + lokaal vertrouwen

* Alle WS-clients (operators + nodes) nemen een **apparaatidentiteit** op in `connect`.
* Nieuwe apparaat-ID’s vereisen koppelingsgoedkeuring; de Gateway geeft een **apparaat-token**
  uit voor volgende verbindingen.
* **Lokale** verbindingen (loopback of het eigen tailnet-adres van de Gateway-host) kunnen
  automatisch worden goedgekeurd om de UX op dezelfde host soepel te houden.
* **Niet-lokale** verbindingen moeten de `connect.challenge`-nonce ondertekenen en vereisen
  expliciete goedkeuring.
* Gateway-auth (`gateway.auth.*`) blijft van toepassing op **alle** verbindingen, lokaal of
  op afstand.

Details: [Gateway protocol](/gateway/protocol), [Pairing](/channels/pairing),
[Security](/gateway/security).

## Protocoltypering en codegeneratie

* TypeBox-schema’s definiëren het protocol.
* JSON Schema wordt gegenereerd uit die schema’s.
* Swift-modellen worden gegenereerd uit het JSON Schema.

## Toegang op afstand

* Voorkeur: Tailscale of VPN.

* Alternatief: SSH-tunnel

  ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
  ssh -N -L 18789:127.0.0.1:18789 user@host
  ```

* Dezelfde handshake + auth-token zijn van toepassing over de tunnel.

* TLS + optionele pinning kan worden ingeschakeld voor WS in remote-opstellingen.

## Operationeel overzicht

* Starten: `openclaw gateway` (foreground, logt naar stdout).
* Health: `health` via WS (ook opgenomen in `hello-ok`).
* Supervisie: launchd/systemd voor automatisch herstarten.

## Invarianten

* Precies één Gateway beheert één enkele Baileys-sessie per host.
* Handshake is verplicht; elk niet-JSON- of niet-connect-eerste frame resulteert in een harde sluiting.
* Events worden niet opnieuw afgespeeld; clients moeten bij hiaten verversen.