Fernzugriff

• Operatoren (Sie oder die macOS-App): Eine direkte LAN-/Tailnet-WebSocket-Verbindung ist am einfachsten, wenn der Gateway erreichbar ist; SSH-Tunneling ist die universelle Ausweichlösung.
• Nodes (iOS/Android und andere Geräte): Stellen eine Verbindung zum WebSocket des Gateways her (LAN/Tailnet oder SSH-Tunnel).

​

Das Grundprinzip

​

Topologieoptionen

​

Befehlsablauf (was wo ausgeführt wird)

1. Die Telegram-Nachricht trifft beim Gateway ein.
2. Der Gateway führt den Agent aus, der entscheidet, ob ein Node-Tool aufgerufen werden soll.
3. Der Gateway ruft den Node über den Gateway-WebSocket auf (node.invoke-RPC).
4. Der Node gibt das Ergebnis zurück; der Gateway antwortet über Telegram.

​

SSH-Tunnel (CLI + Tools)

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

​

Remote-Standardeinstellungen der CLI

{
  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",
    },
  },
}

​

Rangfolge der Anmeldedaten

• Explizite Anmeldedaten (--token, --password oder gatewayToken eines Tools) haben auf Aufrufpfaden, die explizite Authentifizierung akzeptieren, immer Vorrang.
• Sicherheit bei URL-Überschreibungen:
  • CLI---url verwendet niemals implizite Anmeldedaten aus Konfiguration oder Umgebung erneut.
  • Umgebungsvariable OPENCLAW_GATEWAY_URL darf nur Umgebungs-Anmeldedaten verwenden (OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).
• Standardeinstellungen des lokalen Modus:
  • Token: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token (Remote-Ausweichwert nur, wenn das lokale Token nicht gesetzt ist)
  • Passwort: OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password (Remote-Ausweichwert nur, wenn das lokale Passwort nicht gesetzt ist)
• Standardeinstellungen des Remote-Modus:
  • Token: gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
  • Passwort: OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
• Ausnahme des lokalen Modus für Node-Hosts: gateway.remote.token / gateway.remote.password werden ignoriert.
• Token-Prüfungen für Remote-Prüfungen und -Status sind standardmäßig strikt: Beim Ansprechen des Remote-Modus verwenden sie ausschließlich gateway.remote.token (kein Rückgriff auf ein lokales Token).
• Umgebungsüberschreibungen des Gateways verwenden ausschließlich OPENCLAW_GATEWAY_*.

​

Remote-Zugriff auf die Chat-Benutzeroberfläche

• Leiten Sie 18789 über SSH weiter (siehe oben) und verbinden Sie die Clients anschließend mit ws://127.0.0.1:18789.
• Verbinden Sie Clients im direkten LAN-/Tailnet-Modus mit der konfigurierten privaten URL ws:// oder der sicheren URL wss://.
• Unter macOS verwaltet der Remote-Modus der App den ausgewählten Transport automatisch.

​

Remote-Modus der macOS-App

​

Sicherheitsregeln (Remote/VPN)

• Loopback + SSH/Tailscale Serve ist die sicherste Standardeinstellung (keine öffentliche Erreichbarkeit).
• Unverschlüsseltes ws:// wird für Loopback, private/LAN-Adressen (RFC 1918), Link-Local-Adressen, CGNAT sowie Hosts unter .local und .ts.net akzeptiert. Öffentliche Remote-Hosts müssen wss:// verwenden.
• Nicht-Loopback-Bindungen (lan/tailnet/custom oder auto, wenn Loopback nicht verfügbar ist) müssen eine Gateway-Authentifizierung verwenden: Token, Passwort oder einen identitätsbewussten Reverse-Proxy mit gateway.auth.mode: "trusted-proxy".
• gateway.remote.token / .password sind Quellen für Client-Anmeldedaten; sie konfigurieren nicht eigenständig die Serverauthentifizierung.
• Lokale Aufrufpfade dürfen nur dann ersatzweise gateway.remote.* verwenden, wenn gateway.auth.* nicht gesetzt ist.
• Wenn gateway.auth.token / gateway.auth.password explizit über SecretRef konfiguriert ist und nicht aufgelöst werden kann, schlägt die Auflösung geschlossen fehl (keine Verschleierung durch einen Remote-Ausweichwert).
• gateway.remote.tlsFingerprint fixiert das Remote-TLS-Zertifikat für wss://, einschließlich des Operator-/Steuerungsverkehrs und des begleitenden Nodes im direkten macOS-Modus. Ohne gespeicherte Fixierung fixiert macOS das Zertifikat bei der ersten Verwendung erst, nachdem die normale Systemvertrauensprüfung bestanden wurde; Gateways mit selbst signierten Zertifikaten oder privater CA benötigen einen expliziten Fingerabdruck oder „Remote über SSH“.
• Tailscale Serve kann den Datenverkehr der Control UI und des WebSockets über Identitätsheader authentifizieren, wenn gateway.auth.allowTailscale: true. HTTP-API-Endpunkte verwenden diese Header-Authentifizierung nicht, sondern folgen dem normalen HTTP-Authentifizierungsmodus des Gateways. Dieser tokenlose Ablauf setzt voraus, dass der Gateway-Host vertrauenswürdig ist; legen Sie den Wert auf false fest, um überall die Authentifizierung über ein gemeinsames Geheimnis zu verwenden.
• Die Trusted-Proxy-Authentifizierung erwartet standardmäßig einen identitätsbewussten Proxy außerhalb von Loopback. Loopback-Reverse-Proxys auf demselben Host erfordern ausdrücklich gateway.auth.trustedProxy.allowLoopback = true.
• Behandeln Sie die Browser-Steuerung wie Operatorzugriff: ausschließlich über das Tailnet und mit bewusster Node-Kopplung.

​

macOS: persistenter SSH-Tunnel über LaunchAgent

​

Schritt 1: SSH-Konfiguration hinzufügen

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

​

Schritt 2: SSH-Schlüssel kopieren (einmalig)

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

​

Schritt 3: Gateway-Token konfigurieren

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

​

Schritt 4: LaunchAgent erstellen

<?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>

​

Schritt 5: LaunchAgent laden

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

​

Fehlerbehebung

# Prüfen, ob der Tunnel ausgeführt wird
ps aux | grep "ssh -N remote-gateway" | grep -v grep
lsof -i :18789

# Tunnel neu starten
launchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel

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

​

Verwandte Themen

• Tailscale
• Authentifizierung
• Einrichtung eines Remote-Gateways