Toegang op afstand

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.

• Voor operators (jij / de macOS-app): SSH-tunneling is de universele fallback.
• Voor nodes (iOS/Android en toekomstige apparaten): verbind met de Gateway WebSocket (LAN/tailnet of SSH-tunnel indien nodig).

​

Het kernidee

• De Gateway WebSocket bindt aan loopback op je geconfigureerde poort (standaard 18789).
• Voor gebruik op afstand forward je die loopback-poort via SSH (of gebruik je een tailnet/VPN en tunnel je minder).

​

Veelvoorkomende VPN- en tailnet-setups

​

Always-on 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 Remote over SSH-modus van de macOS-app (Instellingen → Algemeen → OpenClaw draait).
• De app opent en beheert de tunnel, zodat WebChat en healthchecks gewoon werken.

​

Laptop draait de Gateway

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

​

Commandostroom (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 slechts éé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 remote 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 geforwarde URL targeten via --url.

​

Remote-standaarden 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-override:
  • CLI-URL-overrides (--url) hergebruiken nooit impliciete config-/env-credentials.
  • Env-URL-overrides (OPENCLAW_GATEWAY_URL) mogen alleen env-credentials gebruiken (OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).
• Standaarden voor local mode:
  • 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-passwordinvoer niet is ingesteld)
• Standaarden voor remote mode:
  • token: gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
  • password: OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
• Local-mode-uitzondering voor Node-host: gateway.remote.token / gateway.remote.password worden genegeerd.
• Tokencontroles voor remote probe/status zijn standaard strikt: ze gebruiken alleen gateway.remote.token (geen lokale token-fallback) wanneer ze remote mode targeten.
• Gateway-env-overrides gebruiken alleen OPENCLAW_GATEWAY_*.

​

Chat-UI via SSH

• Forward 18789 via SSH (zie hierboven) en verbind clients daarna met ws://127.0.0.1:18789.
• Op macOS heeft de “Remote over SSH”-modus 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 break-glass. Er is geen equivalent in openclaw.json; dit moet de procesomgeving zijn voor de client die de WebSocket-verbinding maakt.
• Non-loopback binds (lan/tailnet/custom, of auto wanneer loopback niet beschikbaar is) moeten gateway-auth gebruiken: token, password 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 resolutie gesloten (geen maskering door remote fallback).
• gateway.remote.tlsFingerprint pint het remote TLS-certificaat bij gebruik van wss://.
• Tailscale Serve kan Control UI-/WebSocket-verkeer authenticeren via identity headers wanneer gateway.auth.allowTailscale: true; HTTP API-endpoints gebruiken die Tailscale-headerauth niet en volgen in plaats daarvan de normale HTTP auth mode van de gateway. Deze flow zonder token 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 non-loopback identity-aware proxy-setups. Same-host loopback reverse proxies vereisen expliciet gateway.auth.trustedProxy.allowLoopback = true.
• Behandel browsercontrole als operator-toegang: alleen tailnet + bewuste node-pairing.

​

macOS: persistente SSH-tunnel via LaunchAgent

​

Stap 1: voeg SSH-config toe

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

​

Stap 2: kopieer de SSH-sleutel (eenmalig)

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

​

Stap 3: configureer het gateway-token

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

​

Stap 4: maak de LaunchAgent

<?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: laad de LaunchAgent

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