Accesso remoto

• Per gli operatori (tu / l’app macOS): WebSocket LAN/Tailnet diretto è la soluzione più semplice quando il gateway è raggiungibile; il tunneling SSH è il fallback universale.
• Per i nodi (iOS/Android e dispositivi futuri): connettiti al WebSocket del Gateway (LAN/tailnet o tunnel SSH secondo necessità).

​

L’idea centrale

• Il WebSocket del Gateway di solito si associa al loopback sulla porta configurata (predefinita: 18789).
• Per l’uso remoto, esponilo tramite Tailscale Serve o un binding LAN/Tailnet attendibile, oppure inoltra la porta loopback tramite SSH.

​

Configurazioni VPN e tailnet comuni

​

Gateway sempre attivo nella tua tailnet

• Migliore UX: mantieni gateway.bind: "loopback" e usa Tailscale Serve per l’UI di controllo.
• LAN/Tailnet attendibile: associa il gateway a un’interfaccia privata e connettiti direttamente con gateway.remote.transport: "direct".
• Fallback: mantieni il loopback più un tunnel SSH da qualsiasi macchina che necessita di accesso.
• Esempi: exe.dev (VM semplice) o Hetzner (VPS di produzione).

​

Il desktop domestico esegue il Gateway

• Usa la modalità remota dell’app macOS (Settings → General → OpenClaw runs).
• L’app si connette direttamente quando il gateway è raggiungibile su LAN/Tailnet, oppure apre e gestisce un tunnel SSH quando scegli SSH.

​

Il laptop esegue il Gateway

• Tunnel SSH verso il laptop da altre macchine, oppure
• Tailscale Serve per l’UI di controllo e mantieni il Gateway solo su loopback.

​

Flusso dei comandi (cosa viene eseguito dove)

• Il messaggio Telegram arriva al Gateway.
• Il Gateway esegue l’agente e decide se chiamare uno strumento del nodo.
• Il Gateway chiama il nodo tramite il WebSocket del Gateway (node.* RPC).
• Il nodo restituisce il risultato; il Gateway risponde su Telegram.

• I nodi non eseguono il servizio gateway. Deve essere eseguito un solo gateway per host, a meno che tu non esegua intenzionalmente profili isolati (vedi Gateway multipli).
• La “modalità nodo” dell’app macOS è solo un client nodo tramite il WebSocket del Gateway.

​

Tunnel SSH (CLI + strumenti)

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

• openclaw health e openclaw status --deep ora raggiungono il gateway remoto tramite ws://127.0.0.1:18789.
• openclaw gateway status, openclaw gateway health, openclaw gateway probe e openclaw gateway call possono anche puntare all’URL inoltrato tramite --url quando necessario.

​

Predefiniti remoti della 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",
    },
  },
}

​

Precedenza delle credenziali

• Le credenziali esplicite (--token, --password o lo strumento gatewayToken) hanno sempre la precedenza sui percorsi di chiamata che accettano autenticazione esplicita.
• Sicurezza dell’override URL:
  • Gli override URL della CLI (--url) non riutilizzano mai credenziali implicite da config/env.
  • Gli override URL env (OPENCLAW_GATEWAY_URL) possono usare solo credenziali env (OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).
• Predefiniti della modalità locale:
  • token: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token (il fallback remoto si applica solo quando l’input del token auth locale non è impostato)
  • password: OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password (il fallback remoto si applica solo quando l’input della password auth locale non è impostato)
• Predefiniti della modalità remota:
  • token: gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
  • password: OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
• Eccezione della modalità locale di node-host: gateway.remote.token / gateway.remote.password vengono ignorati.
• I controlli token remoti probe/status sono rigorosi per impostazione predefinita: usano solo gateway.remote.token (nessun fallback al token locale) quando puntano alla modalità remota.
• Gli override env del Gateway usano solo OPENCLAW_GATEWAY_*.

​

Accesso remoto all’UI chat

• Inoltra 18789 tramite SSH (vedi sopra), quindi connetti i client a ws://127.0.0.1:18789.
• Per la modalità diretta LAN/Tailnet, connetti i client all’URL privato ws:// o sicuro wss:// configurato.
• Su macOS, preferisci la modalità remota dell’app, che gestisce automaticamente il trasporto selezionato.

​

Modalità remota dell’app macOS

​

Regole di sicurezza (remoto/VPN)

• Loopback + SSH/Tailscale Serve è il predefinito più sicuro (nessuna esposizione pubblica).
• ws:// in chiaro è accettato per loopback, LAN, link-local, .local, .ts.net e host Tailscale CGNAT. Gli host remoti pubblici devono usare wss://.
• I bind non-loopback (lan/tailnet/custom, o auto quando il loopback non è disponibile) devono usare l’autenticazione gateway: token, password o un reverse proxy identity-aware con gateway.auth.mode: "trusted-proxy".
• gateway.remote.token / .password sono fonti di credenziali client. Non configurano da soli l’autenticazione server.
• I percorsi di chiamata locali possono usare gateway.remote.* come fallback solo quando gateway.auth.* non è impostato.
• Se gateway.auth.token / gateway.auth.password è configurato esplicitamente tramite SecretRef e non risolto, la risoluzione fallisce in modo chiuso (nessun mascheramento tramite fallback remoto).
• gateway.remote.tlsFingerprint vincola il certificato TLS remoto quando si usa wss://, inclusa la modalità diretta macOS. Senza un pin configurato o precedentemente archiviato, macOS vincola un certificato al primo utilizzo solo dopo che la normale attendibilità di sistema è riuscita; i gateway autofirmati o con CA privata che macOS non considera già attendibili richiedono un fingerprint esplicito o Remote over SSH.
• Tailscale Serve può autenticare il traffico UI di controllo/WebSocket tramite header di identità quando gateway.auth.allowTailscale: true; gli endpoint API HTTP non usano quell’autenticazione tramite header Tailscale e seguono invece la normale modalità auth HTTP del gateway. Questo flusso senza token presuppone che l’host gateway sia attendibile. Impostalo su false se vuoi autenticazione con segreto condiviso ovunque.
• L’autenticazione trusted-proxy si aspetta per impostazione predefinita configurazioni proxy identity-aware non-loopback. I reverse proxy loopback sullo stesso host richiedono gateway.auth.trustedProxy.allowLoopback = true esplicito.
• Tratta il controllo dal browser come accesso operatore: solo tailnet + pairing deliberato dei nodi.

​

macOS: tunnel SSH persistente tramite LaunchAgent

​

Passaggio 1: aggiungi la configurazione SSH

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

​

Passaggio 2: copia la chiave SSH (una tantum)

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

​

Passaggio 3: configura il token del gateway

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

​

Passaggio 4: crea il 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>

​

Passaggio 5: carica il LaunchAgent

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

​

Risoluzione dei problemi

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

​

Correlati

• Tailscale
• Autenticazione
• Configurazione del gateway remoto