Externe toegang

• Voor operators (jij / de macOS-app): directe LAN/Tailnet-WebSocket is het eenvoudigst wanneer de gateway bereikbaar is; SSH-tunneling is de universele fallback.
• Voor nodes (iOS/Android en toekomstige apparaten): maak verbinding met de Gateway WebSocket (LAN/tailnet of SSH-tunnel waar nodig).

​

Het kernidee

• De Gateway WebSocket bindt meestal aan loopback op je geconfigureerde poort (standaard 18789).
• Voor extern gebruik maak je die beschikbaar via Tailscale Serve of een vertrouwde LAN/Tailnet-binding, of stuur je de loopback-poort door via SSH.

​

Veelvoorkomende VPN- en tailnet-configuraties

​

Altijd actieve Gateway in je tailnet

• Beste UX: houd gateway.bind: "loopback" aan en gebruik Tailscale Serve voor de Control UI.
• Vertrouwd LAN/Tailnet: bind de gateway aan een privé-interface en verbind direct met gateway.remote.transport: "direct".
• Fallback: houd loopback plus een SSH-tunnel aan vanaf elke machine die toegang nodig heeft.
• Voorbeelden: exe.dev (eenvoudige VM) of Hetzner (productie-VPS).

​

Thuisdesktop draait de Gateway

• Gebruik de externe modus van de macOS-app (Instellingen → Algemeen → OpenClaw runs).
• De app verbindt direct wanneer de gateway bereikbaar is op LAN/Tailnet, of opent en beheert een SSH-tunnel wanneer je SSH kiest.

​

Laptop draait de Gateway

• SSH-tunnel naar de laptop vanaf andere machines, of
• Tailscale Serve voor de Control UI en houd de Gateway alleen op loopback.

​

Commandoflow (wat waar draait)

• Telegram-bericht komt binnen bij de Gateway.
• Gateway draait de agent en beslist of een node-tool moet worden aangeroepen.
• Gateway roept de node aan via de Gateway WebSocket (node.* RPC).
• Node retourneert het resultaat; Gateway antwoordt terug naar Telegram.

• Nodes draaien de gateway-service niet. Er mag maar één gateway per host draaien, tenzij je bewust geïsoleerde profielen draait (zie Meerdere gateways).
• macOS-app “node mode” is alleen een node-client via de Gateway WebSocket.

​

SSH-tunnel (CLI + tools)

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

• openclaw health en openclaw status --deep bereiken nu de externe gateway via ws://127.0.0.1:18789.
• openclaw gateway status, openclaw gateway health, openclaw gateway probe en openclaw gateway call kunnen indien nodig ook de doorgestuurde URL targeten via --url.

​

Externe CLI-standaarden

{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://127.0.0.1:18789",
      token: "your-token",
    },
  },
}

{
  gateway: {
    mode: "remote",
    remote: {
      transport: "direct",
      url: "ws://192.168.0.202:18789",
      token: "your-token",
    },
  },
}

​

Prioriteit van credentials

• Expliciete referenties (--token, --password of tool gatewayToken) hebben altijd voorrang op aanroeppaden die expliciete auth accepteren.
• Veiligheid bij URL-overschrijvingen:
  • CLI-URL-overschrijvingen (--url) hergebruiken nooit impliciete config/env-referenties.
  • Env-URL-overschrijvingen (OPENCLAW_GATEWAY_URL) mogen alleen env-referenties gebruiken (OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).
• Standaarden voor lokale modus:
  • token: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token (remote fallback geldt alleen wanneer lokale auth-tokeninvoer niet is ingesteld)
  • password: OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password (remote fallback geldt alleen wanneer lokale auth-wachtwoordinvoer niet is ingesteld)
• Standaarden voor remote modus:
  • token: gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
  • password: OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
• Uitzondering voor lokale modus op Node-host: gateway.remote.token / gateway.remote.password worden genegeerd.
• Remote probe/status-tokencontroles zijn standaard strikt: ze gebruiken alleen gateway.remote.token (geen lokale token-fallback) wanneer remote modus wordt gebruikt.
• Gateway-env-overschrijvingen gebruiken alleen OPENCLAW_GATEWAY_*.

​

Remote toegang tot Chat-UI

• Forward 18789 via SSH (zie hierboven) en verbind clients daarna met ws://127.0.0.1:18789.
• Voor directe LAN-/Tailnet-modus verbindt u clients met de geconfigureerde private ws://- of beveiligde wss://-URL.
• Geef op macOS de voorkeur aan de remote modus van de app, die het geselecteerde transport automatisch beheert.

​

Remote modus van macOS-app

​

Beveiligingsregels (remote/VPN)

• Loopback + SSH/Tailscale Serve is de veiligste standaard (geen publieke blootstelling).
• Plaintext ws:// wordt geaccepteerd voor loopback, LAN, link-local, .local, .ts.net en Tailscale CGNAT-hosts. Publieke remote hosts moeten wss:// gebruiken.
• Niet-loopback-binds (lan/tailnet/custom, of auto wanneer loopback niet beschikbaar is) moeten gateway-auth gebruiken: token, wachtwoord of een identiteitsbewuste reverse proxy met gateway.auth.mode: "trusted-proxy".
• gateway.remote.token / .password zijn bronnen voor clientreferenties. Ze configureren niet zelf server-auth.
• Lokale aanroeppaden kunnen gateway.remote.* alleen als fallback gebruiken wanneer gateway.auth.* niet is ingesteld.
• Als gateway.auth.token / gateway.auth.password expliciet is geconfigureerd via SecretRef en niet kan worden opgelost, faalt resolutie gesloten (geen maskering door remote fallback).
• gateway.remote.tlsFingerprint pint het remote TLS-certificaat bij gebruik van wss://, inclusief directe macOS-modus. Zonder een geconfigureerde of eerder opgeslagen pin pint macOS een certificaat bij eerste gebruik alleen nadat normale systeemvertrouwen slaagt; self-signed gateways of gateways met private CA die macOS nog niet vertrouwt, hebben een expliciete fingerprint of Remote over SSH nodig.
• Tailscale Serve kan Control UI-/WebSocket-verkeer authenticeren via identiteitsheaders wanneer gateway.auth.allowTailscale: true; HTTP API-endpoints gebruiken die Tailscale-headerauth niet en volgen in plaats daarvan de normale HTTP-authmodus van de gateway. Deze tokenloze flow gaat ervan uit dat de gateway-host vertrouwd is. Stel dit in op false als u overal shared-secret-auth wilt.
• Trusted-proxy-auth verwacht standaard niet-loopback identiteitsbewuste proxy-setups. Reverse proxies op loopback op dezelfde host vereisen expliciet gateway.auth.trustedProxy.allowLoopback = true.
• Behandel browserbesturing als operatortoegang: alleen tailnet + doelbewuste node-koppeling.

​

macOS: permanente SSH-tunnel via LaunchAgent

​

Stap 1: SSH-configuratie toevoegen

Host remote-gateway
    HostName <REMOTE_IP>
    User <REMOTE_USER>
    LocalForward 18789 127.0.0.1:18789
    IdentityFile ~/.ssh/id_rsa

​

Stap 2: SSH-sleutel kopiëren (eenmalig)

ssh-copy-id -i ~/.ssh/id_rsa <REMOTE_USER>@<REMOTE_IP>

​

Stap 3: gateway-token configureren

openclaw config set gateway.remote.token "<your-token>"

​

Stap 4: LaunchAgent maken

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>ai.openclaw.ssh-tunnel</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/ssh</string>
        <string>-N</string>
        <string>remote-gateway</string>
    </array>
    <key>KeepAlive</key>
    <true/>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

​

Stap 5: LaunchAgent laden

launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist

​

Probleemoplossing

ps aux | grep "ssh -N remote-gateway" | grep -v grep
lsof -i :18789

launchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel

launchctl bootout gui/$UID/ai.openclaw.ssh-tunnel

​

Gerelateerd

• Tailscale
• Authenticatie
• Remote gateway-setup