Accesso remoto

• Operatori (tu o l’app macOS): una connessione WebSocket diretta tramite LAN/Tailnet è la soluzione più semplice quando il Gateway è raggiungibile; il tunnel SSH è l’alternativa universale.
• Nodi (iOS/Android e altri dispositivi): si connettono al WebSocket del Gateway (tramite LAN/tailnet o tunnel SSH).

​

Il concetto fondamentale

​

Opzioni di topologia

​

Flusso dei comandi (cosa viene eseguito e dove)

1. Il messaggio Telegram arriva al Gateway.
2. Il Gateway esegue l’agente, che decide se chiamare uno strumento del nodo.
3. Il Gateway chiama il nodo tramite il WebSocket del Gateway (RPC node.invoke).
4. Il nodo restituisce il risultato; il Gateway risponde su Telegram.

​

Tunnel SSH (CLI + strumenti)

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

​

Impostazioni remote predefinite 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 il gatewayToken di uno strumento) hanno sempre la precedenza nei percorsi di chiamata che accettano un’autenticazione esplicita.
• Sicurezza della sostituzione dell’URL:
  • Il parametro CLI --url non riutilizza mai credenziali implicite provenienti dalla configurazione o dall’ambiente.
  • La variabile d’ambiente OPENCLAW_GATEWAY_URL può utilizzare solo credenziali dell’ambiente (OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).
• Valori predefiniti della modalità locale:
  • token: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token (alternativa remota solo quando il token locale non è impostato)
  • password: OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password (alternativa remota solo quando la password locale non è impostata)
• Valori 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 dell’host del nodo: gateway.remote.token / gateway.remote.password vengono ignorati.
• Per impostazione predefinita, i controlli del token per verifica e stato remoti sono rigorosi: quando la destinazione è in modalità remota, utilizzano solo gateway.remote.token (senza ricorrere al token locale).
• Le sostituzioni tramite variabili d’ambiente del Gateway utilizzano solo OPENCLAW_GATEWAY_*.

​

Accesso remoto all’interfaccia di chat

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

​

Modalità remota dell’app macOS

​

Regole di sicurezza (remoto/VPN)

• Loopback + SSH/Tailscale Serve è l’impostazione predefinita più sicura (nessuna esposizione pubblica).
• Il protocollo ws:// non crittografato è accettato per host loopback, privati/LAN (RFC 1918), link-local, CGNAT, .local e .ts.net. Gli host remoti pubblici devono utilizzare wss://.
• Le associazioni non loopback (lan/tailnet/custom oppure auto quando il loopback non è disponibile) devono utilizzare l’autenticazione del Gateway: token, password oppure un proxy inverso sensibile all’identità con gateway.auth.mode: "trusted-proxy".
• gateway.remote.token / .password sono origini delle credenziali del client; da sole non configurano l’autenticazione del server.
• I percorsi di chiamata locali possono utilizzare gateway.remote.* come alternativa solo quando gateway.auth.* non è impostato.
• Se gateway.auth.token / gateway.auth.password è configurato esplicitamente tramite SecretRef e non può essere risolto, la risoluzione si interrompe in modo sicuro (senza che l’alternativa remota mascheri il problema).
• gateway.remote.tlsFingerprint vincola il certificato TLS remoto per wss://, inclusa la modalità diretta di macOS. Senza un’impronta salvata, macOS esegue il vincolo al primo utilizzo solo dopo il superamento della normale verifica di attendibilità del sistema; i Gateway autofirmati o con CA privata richiedono un’impronta esplicita oppure la modalità remota tramite SSH.
• Tailscale Serve può autenticare il traffico dell’interfaccia di controllo/WebSocket tramite intestazioni di identità quando gateway.auth.allowTailscale: true. Gli endpoint dell’API HTTP non utilizzano questa autenticazione tramite intestazioni e seguono invece la normale modalità di autenticazione HTTP del Gateway. Questo flusso senza token presuppone che l’host del Gateway sia attendibile; impostalo su false per utilizzare ovunque l’autenticazione con segreto condiviso.
• L’autenticazione tramite proxy attendibile richiede per impostazione predefinita un proxy sensibile all’identità non associato al loopback. I proxy inversi loopback sullo stesso host richiedono l’impostazione esplicita gateway.auth.trustedProxy.allowLoopback = true.
• Considera il controllo tramite browser equivalente all’accesso dell’operatore: solo nella tailnet e con associazione intenzionale dei nodi.

​

macOS: tunnel SSH persistente tramite LaunchAgent

​

Passaggio 1: aggiungere 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: copiare la chiave SSH (una sola volta)

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

​

Passaggio 3: configurare il token del Gateway

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

​

Passaggio 4: creare 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: caricare il LaunchAgent

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

​

Risoluzione dei problemi

# Check if the tunnel is running
ps aux | grep "ssh -N remote-gateway" | grep -v grep
lsof -i :18789

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

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

​

Argomenti correlati

• Tailscale
• Autenticazione
• Configurazione del Gateway remoto