​

OpenClaw macOS Companion (pasek menu + broker gateway)

​

Co robi

• Wyświetla natywne powiadomienia i status na pasku menu.
• Zarządza monitami TCC (Powiadomienia, Dostępność, Nagrywanie ekranu, Mikrofon, Rozpoznawanie mowy, Automatyzacja/AppleScript).
• Uruchamia lub łączy się z Gateway (lokalnie lub zdalnie).
• Udostępnia narzędzia dostępne tylko na macOS (Canvas, Camera, Screen Recording, system.run).
• Uruchamia lokalną usługę hosta węzła w trybie remote (launchd) i zatrzymuje ją w trybie local.
• Opcjonalnie hostuje PeekabooBridge do automatyzacji UI.
• Na żądanie instaluje globalne CLI (openclaw) przez npm/pnpm (bun niezalecany dla środowiska uruchomieniowego Gateway).

​

Tryb local vs remote

• Local (domyślny): aplikacja dołącza do działającego lokalnie Gateway, jeśli jest obecny; w przeciwnym razie włącza usługę launchd przez openclaw gateway install.
• Remote: aplikacja łączy się z Gateway przez SSH/Tailscale i nigdy nie uruchamia lokalnego procesu. Aplikacja uruchamia lokalną usługę hosta węzła, aby zdalny Gateway mógł dotrzeć do tego Maca. Aplikacja nie uruchamia Gateway jako procesu potomnego.

​

Sterowanie launchd

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

​

Możliwości węzła (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

• Gdy bezgłowa usługa hosta węzła działa (tryb remote), łączy się z Gateway WS jako węzeł.
• system.run wykonuje się w aplikacji macOS (kontekst UI/TCC) przez lokalne gniazdo Unix; monity i wyjście pozostają w aplikacji.

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

​

Zatwierdzanie wykonania (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" }]
    }
  }
}

• Wpisy allowlist to wzorce glob dla rozwiązywanych ścieżek binarnych.
• Wybranie „Always Allow” w monicie dodaje to polecenie do listy dozwolonych.
• Nadpisania środowiska system.run są filtrowane (odrzuca PATH, DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT), a następnie łączone ze środowiskiem aplikacji.

​

Głębokie linki

​

openclaw://agent

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

• message (wymagane)
• sessionKey (opcjonalne)
• thinking (opcjonalne)
• deliver / to / channel (opcjonalne)
• timeoutSeconds (opcjonalne)
• key (opcjonalny klucz trybu bezobsługowego)

• Bez key aplikacja prosi o potwierdzenie.
• Bez key aplikacja wymusza krótki limit wiadomości dla monitu potwierdzenia i ignoruje deliver / to / channel.
• Z prawidłowym key uruchomienie jest bezobsługowe (przeznaczone do osobistych automatyzacji).

​

Przepływ onboardingu (typowy)

1. Zainstaluj i uruchom OpenClaw.app.
2. Ukończ listę kontrolną uprawnień (monity TCC).
3. Upewnij się, że aktywny jest tryb Local i Gateway działa.
4. Zainstaluj CLI, jeśli chcesz mieć dostęp z terminala.

​

Build & dev workflow (natywny)

• cd apps/macos && swift build
• swift run OpenClaw (lub Xcode)
• Pakowanie aplikacji: scripts/package-mac-app.sh

​

Debugowanie łączności gateway (macOS CLI)

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

• --url <ws://host:port>: nadpisanie konfiguracji
• --mode <local|remote>: rozwiązywanie z konfiguracji (domyślnie: config lub local)
• --probe: wymuszenie świeżego sondowania stanu
• --timeout <ms>: limit czasu żądania (domyślnie: 15000)
• --json: wyjście strukturalne do porównań

• --include-local: uwzględnij gatewaye, które byłyby filtrowane jako „local”
• --timeout <ms>: całkowite okno wykrywania (domyślnie: 2000)
• --json: wyjście strukturalne do porównań

​

Instalacja połączenia zdalnego (tunele SSH)

​

Tunel sterujący (port WebSocket Gateway)

• Cel: testy zdrowia, status, Web Chat, konfiguracja i inne wywołania płaszczyzny sterowania.
• Port lokalny: port Gateway (domyślnie 18789), zawsze stały.
• Port zdalny: ten sam port Gateway na hoście zdalnym.
• Zachowanie: brak losowego portu lokalnego; aplikacja ponownie używa istniejącego, zdrowego tunelu lub restartuje go w razie potrzeby.
• Kształt SSH: ssh -N -L <local>:127.0.0.1:<remote> z BatchMode + ExitOnForwardFailure + opcjami keepalive.
• Raportowanie IP: tunel SSH używa loopback, więc gateway zobaczy IP węzła jako 127.0.0.1. Użyj transportu Direct (ws/wss), jeśli chcesz, aby pojawiło się prawdziwe IP klienta (zobacz macOS remote access).

​

Powiązana dokumentacja

• Gateway runbook
• Gateway (macOS)
• Uprawnienia macOS
• Canvas