Toegang op afstand

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• Voor operators (jij / de macOS-app): 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 aan loopback op je geconfigureerde poort (standaard 18789).
• Voor gebruik op afstand forward je die loopback-poort over SSH (of gebruik je een tailnet/VPN en tunnel je minder).

​

Veelvoorkomende VPN- en tailnet-set-ups

​

Altijd actieve Gateway in je tailnet

• Beste UX: houd gateway.bind: "loopback" aan en gebruik Tailscale Serve voor de Control UI.
• Fallback: houd loopback aan plus een SSH-tunnel vanaf elke machine die toegang nodig heeft.
• Voorbeelden: exe.dev (eenvoudige VM) of Hetzner (productie-VPS).

​

Thuisdesktop draait de Gateway

• Gebruik de modus Remote over SSH van de macOS-app (Instellingen → Algemeen → OpenClaw draait).
• De app opent en beheert de tunnel, zodat WebChat en health checks gewoon werken.

​

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.

​

Commandostroom (wat draait waar)

• Telegram-bericht komt aan 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 geeft het resultaat terug; Gateway antwoordt weer naar Telegram.

• Nodes draaien de gateway-service niet. Er mag slechts één gateway per host draaien, tenzij je bewust geïsoleerde profielen draait (zie Meerdere gateways).
• “node-modus” in de macOS-app is gewoon 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 de geforwarde URL ook targeten via --url wanneer nodig.

​

Externe standaardinstellingen voor de CLI

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

​

Credential-prioriteit

• Expliciete credentials (--token, --password of tool gatewayToken) winnen altijd op call-paden die expliciete auth accepteren.
• Veiligheid bij URL-overschrijvingen:
  • CLI-URL-overschrijvingen (--url) hergebruiken nooit impliciete config/env-credentials.
  • Env-URL-overschrijvingen (OPENCLAW_GATEWAY_URL) mogen alleen env-credentials 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 van Node-host: gateway.remote.token / gateway.remote.password worden genegeerd.
• Tokenchecks voor remote probe/status zijn standaard strikt: ze gebruiken alleen gateway.remote.token (geen fallback naar lokaal token) wanneer remote-modus wordt getarget.
• Gateway-env-overschrijvingen gebruiken alleen OPENCLAW_GATEWAY_*.

​

Chat-UI over SSH

• Forward 18789 over SSH (zie hierboven) en verbind clients vervolgens met ws://127.0.0.1:18789.
• Op macOS heeft de modus “Remote over SSH” van de app de voorkeur; die beheert de tunnel automatisch.

​

macOS-app Remote over SSH

​

Beveiligingsregels (remote/VPN)

• Loopback + SSH/Tailscale Serve is de veiligste standaard (geen publieke blootstelling).
• Plaintext ws:// is standaard alleen loopback. Voor vertrouwde privénetwerken stel je OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 in op het clientproces als noodoptie. Er is geen openclaw.json-equivalent; dit moet de procesomgeving zijn voor de client die de WebSocket-verbinding maakt.
• Niet-loopback binds (lan/tailnet/custom, of auto wanneer loopback niet beschikbaar is) moeten gateway-auth gebruiken: token, wachtwoord of een identity-aware reverse proxy met gateway.auth.mode: "trusted-proxy".
• gateway.remote.token / .password zijn bronnen voor clientcredentials. Ze configureren op zichzelf geen server-auth.
• Lokale call-paden kunnen gateway.remote.* alleen als fallback gebruiken wanneer gateway.auth.* niet is ingesteld.
• Als gateway.auth.token / gateway.auth.password expliciet via SecretRef is geconfigureerd en niet kan worden opgelost, faalt de resolutie gesloten (geen remote fallback die dit maskeert).
• gateway.remote.tlsFingerprint pint het externe TLS-certificaat bij gebruik van wss://.
• Tailscale Serve kan Control UI/WebSocket-verkeer authenticeren via identity headers wanneer gateway.auth.allowTailscale: true; HTTP API-eindpunten gebruiken die Tailscale-headerauth niet en volgen in plaats daarvan de normale HTTP auth-modus van de gateway. Deze tokenloze stroom gaat ervan uit dat de gateway-host vertrouwd is. Zet dit op false als je overal shared-secret-auth wilt.
• Trusted-proxy-auth verwacht standaard niet-loopback identity-aware proxy-set-ups. Same-host loopback reverse proxies vereisen expliciet gateway.auth.trustedProxy.allowLoopback = true.
• Behandel browserbediening als operatortoegang: alleen tailnet + bewuste node-koppeling.

​

macOS: persistente SSH-tunnel via LaunchAgent

​

Stap 1: SSH-config 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-set-up