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

# Gateway-architectuur

## Overzicht

* Eén langlevende **Gateway** beheert alle berichtinterfaces (WhatsApp via
  Baileys, Telegram via grammY, Slack, Discord, Signal, iMessage, WebChat).
* Besturingsvlakclients (macOS-app, CLI, webinterface, 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 mogelijkheden/opdrachten.
* Eén Gateway per host; dit is de enige plek die een WhatsApp-sessie opent.
* De **canvas-host** wordt aangeboden door de HTTP-server van de Gateway onder:
  * `/__openclaw__/canvas/` (door agent bewerkbare HTML/CSS/JS)
  * `/__openclaw__/a2ui/` (A2UI-host)
    Deze gebruikt dezelfde poort als de Gateway (standaard `18789`).

## Componenten en stromen

### Gateway (daemon)

* Onderhoudt providerverbindingen.
* Biedt een getypeerde WS-API (verzoeken, antwoorden, server-pushgebeurtenissen).
* Valideert inkomende frames tegen JSON Schema.
* Verzendt gebeurtenissen zoals `agent`, `chat`, `presence`, `health`, `heartbeat`, `cron`.

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

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

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

* Verbinden met dezelfde **WS-server** met `role: node`.
* Geven een apparaatidentiteit op in `connect`; koppeling is **apparaatgebaseerd** (rol `node`) en
  goedkeuring leeft in de opslag voor apparaatkoppelingen.
* Bieden opdrachten zoals `canvas.*`, `camera.*`, `screen.record`, `location.get`.

Protocoldetails:

* [Gateway-protocol](/nl/gateway/protocol)

### WebChat

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

## Verbindingslevenscyclus (één 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: 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}
```

## Wireprotocol (samenvatting)

* Transport: WebSocket, tekstframes met JSON-payloads.
* Eerste frame **moet** `connect` zijn.
* Na handshake:
  * Verzoeken: `{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`
  * Gebeurtenissen: `{type:"event", event, payload, seq?, stateVersion?}`
* `hello-ok.features.methods` / `events` zijn ontdekkingsmetadata, geen
  gegenereerde dump van elke aanroepbare hulproute.
* Authenticatie met gedeeld geheim gebruikt `connect.params.auth.token` of
  `connect.params.auth.password`, afhankelijk van de geconfigureerde Gateway-authenticatiemodus.
* Modi met identiteit, zoals Tailscale Serve
  (`gateway.auth.allowTailscale: true`) of niet-loopback
  `gateway.auth.mode: "trusted-proxy"` voldoen aan authenticatie via verzoekheaders
  in plaats van `connect.params.auth.*`.
* Privé-ingress `gateway.auth.mode: "none"` schakelt authenticatie met gedeeld geheim
  volledig uit; houd die modus uitgeschakeld voor publieke/onvertrouwde ingress.
* Idempotentiesleutels zijn vereist voor methoden met neveneffecten (`send`, `agent`) om
  veilig opnieuw te proberen; de server bewaart een kortlevende deduplicatiecache.
* Nodes moeten `role: "node"` plus mogelijkheden/opdrachten/rechten opnemen in `connect`.

## Koppeling + lokaal vertrouwen

* Alle WS-clients (operators + nodes) nemen een **apparaatidentiteit** op bij `connect`.
* Nieuwe apparaat-ID's vereisen koppelingsgoedkeuring; de Gateway geeft een **apparaat-token**
  uit voor latere verbindingen.
* Directe local loopback-verbindingen kunnen automatisch worden goedgekeurd om de gebruikerservaring op dezelfde host
  soepel te houden.
* OpenClaw heeft ook een smal backend-/containerlokaal zelfverbindingspad voor
  vertrouwde hulpstromen met gedeeld geheim.
* Tailnet- en LAN-verbindingen, inclusief tailnet-binds op dezelfde host, vereisen nog steeds
  expliciete koppelingsgoedkeuring.
* Alle verbindingen moeten de `connect.challenge`-nonce ondertekenen.
* Handtekeningpayload `v3` bindt ook `platform` + `deviceFamily`; de gateway
  pint gekoppelde metadata bij opnieuw verbinden en vereist herstelkoppeling voor metadatawijzigingen.
* **Niet-lokale** verbindingen vereisen nog steeds expliciete goedkeuring.
* Gateway-authenticatie (`gateway.auth.*`) geldt nog steeds voor **alle** verbindingen, lokaal of
  extern.

Details: [Gateway-protocol](/nl/gateway/protocol), [Koppeling](/nl/channels/pairing),
[Beveiliging](/nl/gateway/security).

## Protocoltypering en codegeneratie

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

## Externe toegang

* 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 + authenticatietoken gelden via de tunnel.

* TLS + optionele pinning kunnen voor WS worden ingeschakeld in externe opstellingen.

## Operationele momentopname

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

## Invarianten

* Exact één Gateway beheert één Baileys-sessie per host.
* Handshake is verplicht; elk niet-JSON of niet-connect eerste frame leidt tot een harde sluiting.
* Gebeurtenissen worden niet opnieuw afgespeeld; clients moeten vernieuwen bij hiaten.

## Gerelateerd

* [Agentlus](/nl/concepts/agent-loop) — gedetailleerde uitvoeringscyclus van de agent
* [Gateway-protocol](/nl/gateway/protocol) — WebSocket-protocolcontract
* [Wachtrij](/nl/concepts/queue) — opdrachtenwachtrij en gelijktijdigheid
* [Beveiliging](/nl/gateway/security) — vertrouwensmodel en hardening