​

App complementare OpenClaw per macOS (barra dei menu + broker del gateway)

​

Cosa fa

• Mostra notifiche native e stato nella barra dei menu.
• Gestisce i prompt TCC (Notifiche, Accessibilità, Registrazione dello schermo, Microfono, Riconoscimento vocale, Automazione/AppleScript).
• Esegue o si connette al Gateway (locale o remoto).
• Espone strumenti solo macOS (Canvas, Fotocamera, Registrazione dello schermo, system.run).
• Avvia il servizio host del nodo locale in modalità remote (launchd), e lo arresta in modalità local.
• Facoltativamente ospita PeekabooBridge per l’automazione UI.
• Installa la CLI globale (openclaw) su richiesta tramite npm, pnpm o bun (l’app preferisce npm, poi pnpm, poi bun; Node resta il runtime Gateway consigliato).

​

Modalità locale vs remota

• Local (predefinita): l’app si collega a un Gateway locale in esecuzione se presente; altrimenti abilita il servizio launchd tramite openclaw gateway install.
• Remote: l’app si connette a un Gateway tramite SSH/Tailscale e non avvia mai un processo locale. L’app avvia il servizio host del nodo locale così il Gateway remoto può raggiungere questo Mac. L’app non genera il Gateway come processo figlio. Il rilevamento del Gateway ora preferisce i nomi Tailscale MagicDNS agli IP tailnet grezzi, quindi l’app Mac si ripristina in modo più affidabile quando gli IP tailnet cambiano.

​

Controllo launchd

launchctl kickstart -k gui/$UID/ai.openclaw.gateway
launchctl bootout gui/$UID/ai.openclaw.gateway

​

Capacità del nodo (Mac)

• Canvas: canvas.present, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.*
• Fotocamera: camera.snap, camera.clip
• Schermo: screen.record
• Sistema: system.run, system.notify

• Quando il servizio host del nodo headless è in esecuzione (modalità remota), si connette al Gateway WS come nodo.
• system.run viene eseguito nell’app macOS (contesto UI/TCC) tramite un socket Unix locale; prompt + output restano nell’app.

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

​

Approvazioni exec (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" }]
    }
  }
}

• Le voci allowlist sono pattern glob per i percorsi binari risolti.
• Il testo del comando shell grezzo che contiene sintassi di controllo o espansione della shell (&&, ||, ;, |, `, $, <, >, (, )) viene trattato come una mancata corrispondenza dell’allowlist e richiede approvazione esplicita (oppure l’inserimento nell’allowlist del binario della shell).
• Scegliere “Always Allow” nel prompt aggiunge quel comando all’allowlist.
• Gli override dell’ambiente system.run vengono filtrati (elimina PATH, DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT, SHELLOPTS, PS4) e poi uniti con l’ambiente dell’app.
• Per i wrapper shell (bash|sh|zsh ... -c/-lc), gli override dell’ambiente con ambito richiesta vengono ridotti a una piccola allowlist esplicita (TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR).
• Per le decisioni always-allow in modalità allowlist, i wrapper di dispatch noti (env, nice, nohup, stdbuf, timeout) mantengono i percorsi eseguibili interni invece dei percorsi dei wrapper. Se l’unwrapping non è sicuro, nessuna voce di allowlist viene mantenuta automaticamente.

​

Deep link

​

openclaw://agent

• message (obbligatorio)
• sessionKey (facoltativo)
• thinking (facoltativo)
• deliver / to / channel (facoltativo)
• timeoutSeconds (facoltativo)
• key (facoltativo, chiave per modalità non presidiata)

• Senza key, l’app richiede conferma.
• Senza key, l’app applica un limite breve al messaggio per il prompt di conferma e ignora deliver / to / channel.
• Con una key valida, l’esecuzione è non presidiata (pensata per automazioni personali).

​

Flusso di onboarding (tipico)

1. Installa e avvia OpenClaw.app.
2. Completa la checklist dei permessi (prompt TCC).
3. Assicurati che la modalità Local sia attiva e che il Gateway sia in esecuzione.
4. Installa la CLI se vuoi l’accesso dal terminale.

​

Posizionamento della directory di stato (macOS)

• ~/Library/Mobile Documents/com~apple~CloudDocs/...
• ~/Library/CloudStorage/...

​

Flusso di build e sviluppo (nativo)

• cd apps/macos && swift build
• swift run OpenClaw (o Xcode)
• Impacchetta l’app: scripts/package-mac-app.sh

​

Debug della connettività gateway (CLI macOS)

• --url <ws://host:port>: override della configurazione
• --mode <local|remote>: risoluzione dalla configurazione (predefinito: configurazione o local)
• --probe: forza un nuovo health probe
• --timeout <ms>: timeout della richiesta (predefinito: 15000)
• --json: output strutturato per il confronto delle differenze

• --include-local: include i gateway che verrebbero filtrati come “local”
• --timeout <ms>: finestra complessiva di rilevamento (predefinito: 2000)
• --json: output strutturato per il confronto delle differenze

​

Infrastruttura delle connessioni remote (tunnel SSH)

​

Tunnel di controllo (porta WebSocket Gateway)

• Scopo: health check, stato, Web Chat, configurazione e altre chiamate del piano di controllo.
• Porta locale: la porta Gateway (predefinita 18789), sempre stabile.
• Porta remota: la stessa porta Gateway sull’host remoto.
• Comportamento: nessuna porta locale casuale; l’app riusa un tunnel esistente e sano oppure lo riavvia se necessario.
• Forma SSH: ssh -N -L <local>:127.0.0.1:<remote> con opzioni BatchMode + ExitOnForwardFailure + keepalive.
• Reporting IP: il tunnel SSH usa loopback, quindi il gateway vedrà l’IP del nodo come 127.0.0.1. Usa il trasporto Direct (ws/wss) se vuoi che compaia il vero IP del client (vedi accesso remoto macOS).

​

Documentazione correlata

• Runbook del Gateway
• Gateway (macOS)
• Permessi macOS
• Canvas