​

Application compagnon macOS OpenClaw (barre de menus + courtier de passerelle)

​

Ce qu’elle fait

• Affiche des notifications natives et l’état dans la barre de menus.
• Gère les invites TCC (Notifications, Accessibilité, Enregistrement de l’écran, Microphone, Reconnaissance vocale, Automation/AppleScript).
• Exécute ou se connecte à la Gateway (passerelle) (locale ou distante).
• Expose des outils spécifiques à macOS (Canvas, Camera, Screen Recording, system.run).
• Démarre le service hôte de nœud local en mode remote, et l’arrête en mode local.
• Peut héberger PeekabooBridge pour l’automatisation de l’interface utilisateur.
• Installe le CLI global (openclaw) via npm/pnpm sur demande (bun non recommandé pour l’exécution de la Gateway).

​

Mode local vs mode distant

• Local (par défaut) : l’application s’attache à une Gateway locale en cours d’exécution si elle existe ; sinon, elle active le service launchd via openclaw gateway install.
• Remote : l’application se connecte à une Gateway via SSH/Tailscale et ne démarre jamais de processus local. L’application démarre le service hôte de nœud local afin que la Gateway distante puisse atteindre ce Mac. L’application ne lance pas la Gateway comme processus enfant.

​

Contrôle launchd

launchctl kickstart -k gui/$UID/bot.molt.gateway
launchctl bootout gui/$UID/bot.molt.gateway

​

Capacités du nœud (mac)

• Canvas : canvas.present, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.*
• Camera : camera.snap, camera.clip
• Screen : screen.record
• System : system.run, system.notify

• Lorsque le service hôte de nœud sans interface est en cours d’exécution (mode remote), il se connecte au WS de la Gateway en tant que nœud.
• system.run s’exécute dans l’application macOS (contexte UI/TCC) via un socket Unix local ; les invites et les sorties restent dans l’application.

Gateway -> Node Service (WS)
                 |  IPC (UDS + token + HMAC + TTL)
                 v
             Mac App (UI + TCC + system.run)

​

Approbations d’exécution (system.run)

~/.openclaw/exec-approvals.json

{
  "version": 1,
  "defaults": {
    "security": "deny",
    "ask": "on-miss"
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }]
    }
  }
}

• Les entrées allowlist sont des motifs glob pour les chemins de binaires résolus.
• Choisir « Toujours autoriser » dans l’invite ajoute cette commande à la liste d’autorisation.
• Les surcharges d’environnement system.run sont filtrées (suppression de PATH, DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT) puis fusionnées avec l’environnement de l’application.

​

Liens profonds

​

openclaw://agent

open 'openclaw://agent?message=Hello%20from%20deep%20link'

• message (obligatoire)
• sessionKey (optionnel)
• thinking (optionnel)
• deliver / to / channel (optionnel)
• timeoutSeconds (optionnel)
• key (clé optionnelle de mode non supervisé)

• Sans key, l’application demande une confirmation.
• Sans key, l’application impose une limite courte de message pour l’invite de confirmation et ignore deliver / to / channel.
• Avec un key valide, l’exécution est non supervisée (destinée aux automatisations personnelles).

​

Flux de prise en main (typique)

1. Installer et lancer OpenClaw.app.
2. Compléter la liste de vérification des autorisations (invites TCC).
3. Vérifier que le mode Local est actif et que la Gateway est en cours d’exécution.
4. Installer le CLI si vous souhaitez un accès via le terminal.

​

Flux de build et de développement (natif)

• cd apps/macos && swift build
• swift run OpenClaw (ou Xcode)
• Empaquetage de l’application : scripts/package-mac-app.sh

​

Déboguer la connectivité de la Gateway (CLI macOS)

cd apps/macos
swift run openclaw-mac connect --json
swift run openclaw-mac discover --timeout 3000 --json

• --url <ws://host:port> : remplacer la configuration
• --mode <local|remote> : résoudre depuis la configuration (par défaut : config ou local)
• --probe : forcer une nouvelle sonde d’état
• --timeout <ms> : délai d’expiration de la requête (par défaut : 15000)
• --json : sortie structurée pour la comparaison

• --include-local : inclure les passerelles qui seraient filtrées comme « locales »
• --timeout <ms> : fenêtre globale de découverte (par défaut : 2000)
• --json : sortie structurée pour la comparaison

​

Mécanique de connexion distante (tunnels SSH)

​

Tunnel de contrôle (port WebSocket de la Gateway)

• Objectif : contrôles d’état, statut, Web Chat, configuration et autres appels du plan de contrôle.
• Port local : le port de la Gateway (par défaut 18789), toujours stable.
• Port distant : le même port de la Gateway sur l’hôte distant.
• Comportement : aucun port local aléatoire ; l’application réutilise un tunnel sain existant ou le redémarre si nécessaire.
• Forme SSH : ssh -N -L <local>:127.0.0.1:<remote> avec BatchMode + ExitOnForwardFailure + options de keepalive.
• Rapport d’IP : le tunnel SSH utilise le loopback, la Gateway verra donc l’IP du nœud comme 127.0.0.1. Utilisez le transport Direct (ws/wss) si vous souhaitez que la véritable IP cliente apparaisse (voir accès distant macOS).

​

Documentation associée

• Runbook de la Gateway
• Gateway (macOS)
• Autorisations macOS
• Canvas