Contrôle à distance

Ce flux permet à l’app macOS de servir de télécommande complète pour un Gateway OpenClaw exécuté sur un autre hôte (ordinateur de bureau/serveur). L’app se connecte directement aux URL de Gateway approuvées du réseau local/Tailnet, ou gère un tunnel SSH lorsque le Gateway distant est accessible uniquement en local loopback. Les contrôles d’intégrité, le transfert de l’activation vocale et le chat web réutilisent la même configuration distante depuis Settings -> General.

Modes

• Local (ce Mac) : tout s’exécute sur l’ordinateur portable ; SSH n’intervient pas.
• Distant via SSH (par défaut) : les commandes OpenClaw s’exécutent sur l’hôte distant. L’app ouvre une connexion SSH avec -o BatchMode, l’identité ou la clé choisie et une redirection de port locale.
• Distant direct (ws/wss) : aucun tunnel SSH ; l’app se connecte directement à l’URL du Gateway (réseau local, Tailscale, Tailscale Serve ou proxy inverse HTTPS public).

Transports distants

• Tunnel SSH (par défaut) : utilise ssh -N -L ... pour rediriger le port du Gateway vers localhost. Le Gateway voit l’adresse IP du Node comme 127.0.0.1, car le tunnel est en local loopback.
• Direct (ws/wss) : se connecte directement à l’URL du Gateway. Le Gateway voit l’adresse IP réelle du client.

L’app désactive la mutualisation des connexions SSH et le passage en arrière-plan après authentification pour ses propres processus SSH, afin de pouvoir surveiller et redémarrer le processus exact, même si l’alias sélectionné active ControlMaster ou ForkAfterAuthentication.

La vérification de la clé d’hôte SSH est stricte par défaut, car les identifiants du Gateway transitent par ce tunnel. Pour adopter le comportement d’approbation propre à un alias SSH géré, définissez --ssh-host-key-policy openssh avec openclaw-mac configure-remote, ou définissez directement gateway.remote.sshHostKeyPolicy sur "openssh". Vérifiez l’alias ainsi que toute configuration Host * correspondante ou configuration système avant d’activer cette option. La modification de la cible SSH (dans l’app ou avec configure-remote) rétablit la politique strict, sauf si vous réactivez explicitement cette option pour la nouvelle cible.

En mode tunnel SSH, les noms d’hôte du réseau local/Tailnet détectés sont enregistrés dans gateway.remote.sshTarget. L’app conserve gateway.remote.url sur le point de terminaison du tunnel local (par exemple ws://127.0.0.1:18789), afin que la CLI, le chat web et le service local d’hébergement du Node utilisent tous le même transport local loopback. Lorsque la détection renvoie à la fois des adresses IP Tailnet brutes et des noms d’hôte stables, l’app privilégie les noms Tailscale MagicDNS ou du réseau local afin que les connexions résistent mieux aux changements d’adresse. Si le port du tunnel local diffère de celui du Gateway distant, définissez gateway.remote.remotePort sur le port de l’hôte distant.

En mode distant, l’automatisation du navigateur relève de l’hôte de Node de la CLI, et non du Node natif de l’app macOS. L’app démarre si possible le service d’hébergement du Node installé ; pour activer le contrôle du navigateur depuis ce Mac, installez-le et démarrez-le avec openclaw node install ... et openclaw node start (ou exécutez openclaw node run ... au premier plan), puis ciblez ce Node doté de fonctionnalités de navigateur.

Prérequis sur l’hôte distant

1. Installez Node + pnpm, puis compilez et installez la CLI OpenClaw (pnpm install && pnpm build && pnpm link --global).
2. Vérifiez que openclaw figure dans PATH pour les interpréteurs de commandes non interactifs (créez si nécessaire un lien symbolique dans /usr/local/bin ou /opt/homebrew/bin).
3. Pour le transport SSH : configurez l’authentification SSH par clé. Les adresses IP Tailscale sont recommandées pour garantir une accessibilité stable hors du réseau local.

Configuration de l’app macOS

Pour préconfigurer l’app sans passer par le processus d’accueil, via SSH :

openclaw-mac configure-remote \  --ssh-target user@gateway-host \  --local-port 18789 \  --remote-port 18789 \  --token "$OPENCLAW_GATEWAY_TOKEN"

Ou, pour un Gateway déjà accessible sur un réseau local ou un Tailnet approuvé, ignorez entièrement SSH :

openclaw-mac configure-remote \  --direct-url ws://192.168.0.202:18789 \  --token "$OPENCLAW_GATEWAY_TOKEN"

Les deux formes écrivent dans ~/.openclaw/openclaw.json, marquent l’intégration comme terminée et permettent à l’app de prendre en charge le transport sélectionné au prochain démarrage. --local-port/--remote-port utilisent 18789 par défaut. Autres options : --password, --identity <path>, --ssh-host-key-policy <strict|openssh>, --project-root <path>, --cli-path <path>, --json. Exécutez openclaw-mac configure-remote --help pour obtenir la référence complète.

Pour effectuer plutôt la configuration depuis l’interface :

1. Ouvrez Settings -> General.
2. Sous OpenClaw runs, sélectionnez Remote, puis définissez :
   • Transport : SSH tunnel ou Direct (ws/wss).
   • SSH target : user@host (:port facultatif). Si le Gateway se trouve sur le même réseau local et s’annonce via Bonjour, sélectionnez-le dans la liste des appareils détectés pour remplir automatiquement ce champ.
   • Gateway URL (mode Direct uniquement) : wss://gateway.example.ts.net (ou ws://... pour une connexion locale/sur le réseau local).
   • Identity file (avancé) : chemin d’accès à votre clé.
   • Project root (avancé) : chemin d’accès distant utilisé pour les commandes.
   • CLI path (avancé) : chemin facultatif vers un point d’entrée ou un binaire openclaw exécutable (rempli automatiquement lorsqu’il est annoncé).
3. Cliquez sur Test remote. Une réussite signifie que la commande distante openclaw status --json s’est exécutée correctement. Les échecs indiquent généralement des problèmes liés à PATH ou à la CLI ; le code de sortie 127 signifie que la CLI est introuvable sur l’hôte distant.
4. Les contrôles d’intégrité et le chat web utilisent désormais automatiquement le transport sélectionné.

Chat web

• Tunnel SSH : se connecte au Gateway via le port de contrôle WebSocket redirigé (18789 par défaut).
• Direct (ws/wss) : se connecte directement à l’URL configurée du Gateway.
• Il n’existe aucun serveur HTTP distinct pour le chat web.

Autorisations

• L’hôte distant nécessite les mêmes autorisations TCC que l’hôte local (automatisation, accessibilité, enregistrement de l’écran, microphone, reconnaissance vocale, notifications). Exécutez une fois l’intégration sur cette machine pour les accorder.
• Les Nodes annoncent l’état de leurs autorisations via node.list / node.describe, afin que les agents sachent ce qui est disponible.

Remarques de sécurité

• Privilégiez les liaisons local loopback sur l’hôte distant et connectez-vous via SSH, Tailscale Serve ou une URL directe approuvée du Tailnet/réseau local.
• Par défaut, la tunnellisation SSH exige une clé d’hôte déjà approuvée. Approuvez d’abord la clé d’hôte (ajoutez-la au fichier des hôtes connus configuré), ou définissez explicitement gateway.remote.sshHostKeyPolicy: "openssh" pour un alias géré dont vous acceptez la politique d’approbation OpenSSH.
• Si vous liez le Gateway à une interface autre que local loopback, exigez une authentification valide du Gateway : jeton, mot de passe ou proxy inverse tenant compte de l’identité avec gateway.auth.mode: "trusted-proxy".
• Consultez Sécurité et Tailscale.

Processus de connexion à WhatsApp (distant)

• Exécutez openclaw channels login --channel whatsapp --verbose sur l’hôte distant. Scannez le code QR avec WhatsApp sur votre téléphone.
• Relancez la connexion sur cet hôte si l’authentification expire. Le contrôle d’intégrité signale les problèmes de liaison.

Dépannage

Sons de notification

Choisissez un son pour chaque notification depuis des scripts avec openclaw nodes notify, par exemple :

openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass

L’application ne propose aucun réglage global du son par défaut ; les appelants choisissent un son (ou aucun) pour chaque requête.

Voir aussi

• Application macOS
• Accès à distance