Naar hoofdinhoud gaan

​
OpenClaw macOS Companion (menubalk + gateway-broker)

De macOS-app is de menubalk-companion voor OpenClaw. De app beheert rechten, beheert/maakt lokaal verbinding met de Gateway (launchd of handmatig) en stelt macOS‑mogelijkheden beschikbaar aan de agent als een node.

​
Wat het doet

  • Toont native meldingen en status in de menubalk.
  • Beheert TCC-prompts (Meldingen, Toegankelijkheid, Schermopname, Microfoon, Spraakherkenning, Automatisering/AppleScript).
  • Start of verbindt met de Gateway (lokaal of op afstand).
  • Stelt macOS‑specifieke tools beschikbaar (Canvas, Camera, Schermopname, system.run).
  • Start de lokale node-hostservice in remote modus (launchd) en stopt deze in local modus.
  • Host optioneel PeekabooBridge voor UI-automatisering.
  • Installeert op verzoek de globale CLI (openclaw) via npm/pnpm (bun wordt niet aanbevolen voor de Gateway-runtime).

​
Lokale vs. remote modus

  • Local (standaard): de app maakt verbinding met een draaiende lokale Gateway indien aanwezig; anders schakelt deze de launchd-service in via openclaw gateway install.
  • Remote: de app verbindt met een Gateway via SSH/Tailscale en start nooit een lokaal proces. De app start de lokale node-hostservice zodat de remote Gateway deze Mac kan bereiken. De app start de Gateway niet als een childprocess.

​
Launchd-besturing

De app beheert een per-gebruiker LaunchAgent met label bot.molt.gateway (of bot.molt.<profile> bij gebruik van --profile/OPENCLAW_PROFILE; legacy com.openclaw.* wordt nog steeds ontladen). 
launchctl kickstart -k gui/$UID/bot.molt.gateway
launchctl bootout gui/$UID/bot.molt.gateway
Vervang het label door bot.molt.<profile> bij het uitvoeren van een benoemd profiel. Als de LaunchAgent niet is geïnstalleerd, schakel deze in vanuit de app of voer openclaw gateway install uit.

​
Node-mogelijkheden (mac)

De macOS-app presenteert zichzelf als een node. Veelgebruikte opdrachten:
  • Canvas: canvas.present, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.*
  • Camera: camera.snap, camera.clip
  • Scherm: screen.record
  • Systeem: system.run, system.notify
De node rapporteert een permissions-map zodat agents kunnen bepalen wat is toegestaan. Node-service + app IPC:
  • Wanneer de headless node-hostservice draait (remote modus), verbindt deze als node met de Gateway WS.
  • system.run wordt uitgevoerd in de macOS-app (UI/TCC-context) via een lokale Unix-socket; prompts + uitvoer blijven in de app.
Diagram (SCI): 
Gateway -> Node Service (WS)
                 |  IPC (UDS + token + HMAC + TTL)
                 v
             Mac App (UI + TCC + system.run)

​
Uitvoeringsgoedkeuringen (system.run)

system.run wordt beheerd via Exec approvals in de macOS-app (Instellingen → Exec approvals). Beveiliging + bevestiging + toegestane lijst worden lokaal op de Mac opgeslagen in: 
~/.openclaw/exec-approvals.json
Voorbeeld: 
{
  "version": 1,
  "defaults": {
    "security": "deny",
    "ask": "on-miss"
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }]
    }
  }
}
Notities:
  • allowlist-items zijn globpatronen voor opgeloste binaire paden.
  • Het kiezen van “Always Allow” in de prompt voegt die opdracht toe aan de toegestane lijst.
  • system.run-omgevingsoverschrijvingen worden gefilterd (verwijdert PATH, DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT) en vervolgens samengevoegd met de omgeving van de app.
De app registreert het URL-schema openclaw:// voor lokale acties.

​
openclaw://agent

Activeert een Gateway-agent-verzoek. 
open 'openclaw://agent?message=Hello%20from%20deep%20link'
Queryparameters:
  • message (vereist)
  • sessionKey (optioneel)
  • thinking (optioneel)
  • deliver / to / channel (optioneel)
  • timeoutSeconds (optioneel)
  • key (optionele sleutel voor onbeheerde modus)
Veiligheid:
  • Zonder key vraagt de app om bevestiging.
  • Zonder key hanteert de app een korte berichtlimiet voor de bevestigingsprompt en negeert deliver / to / channel.
  • Met een geldige key is de uitvoering onbeheerd (bedoeld voor persoonlijke automatiseringen).

​
Onboardingflow (typisch)

  1. Installeer en start OpenClaw.app.
  2. Voltooi de rechtenchecklist (TCC-prompts).
  3. Zorg dat Local modus actief is en dat de Gateway draait.
  4. Installeer de CLI als je terminaltoegang wilt.

​
Build- & dev-workflow (native)

  • cd apps/macos && swift build
  • swift run OpenClaw (of Xcode)
  • App verpakken: scripts/package-mac-app.sh

​
Gateway-connectiviteit debuggen (macOS CLI)

Gebruik de debug-CLI om dezelfde Gateway WebSocket-handshake en discovery‑logica te testen die de macOS-app gebruikt, zonder de app te starten. 
cd apps/macos
swift run openclaw-mac connect --json
swift run openclaw-mac discover --timeout 3000 --json
Verbindingsopties:
  • --url <ws://host:port>: config overschrijven
  • --mode <local|remote>: oplossen vanuit config (standaard: config of lokaal)
  • --probe: een nieuwe health-probe afdwingen
  • --timeout <ms>: time-out voor verzoeken (standaard: 15000)
  • --json: gestructureerde uitvoer voor diffing
Discovery-opties:
  • --include-local: gateways opnemen die als “local” zouden worden gefilterd
  • --timeout <ms>: totale discovery-venster (standaard: 2000)
  • --json: gestructureerde uitvoer voor diffing
Tip: vergelijk met openclaw gateway discover --json om te zien of de discovery-pijplijn van de macOS-app (NWBrowser + tailnet DNS‑SD-fallback) afwijkt van de dns-sd-gebaseerde discovery van de Node CLI.

​
Remote verbindingsarchitectuur (SSH-tunnels)

Wanneer de macOS-app in Remote modus draait, opent deze een SSH-tunnel zodat lokale UI‑componenten met een remote Gateway kunnen communiceren alsof deze op localhost draait.

​
Control-tunnel (Gateway WebSocket-poort)

  • Doel: healthchecks, status, Web Chat, config en andere control-plane-aanroepen.
  • Lokale poort: de Gateway-poort (standaard 18789), altijd stabiel.
  • Remote poort: dezelfde Gateway-poort op de remote host.
  • Gedrag: geen willekeurige lokale poort; de app hergebruikt een bestaande gezonde tunnel of start deze opnieuw indien nodig.
  • SSH-vorm: ssh -N -L <local>:127.0.0.1:<remote> met BatchMode + ExitOnForwardFailure + keepalive-opties.
  • IP-rapportage: de SSH-tunnel gebruikt loopback, dus de gateway ziet het node‑IP als 127.0.0.1. Gebruik Direct (ws/wss) transport als je het echte client‑IP wilt laten verschijnen (zie macOS remote access).
Voor installatiestappen, zie macOS remote access. Voor protocoldetails, zie Gateway protocol.

​
Gerelateerde documentatie