​

OpenClaw macOS Yardımcı Uygulaması (menü çubuğu + gateway broker)

​

Ne yapar

• Menü çubuğunda yerel bildirimleri ve durumu gösterir.
• TCC istemlerinin (Bildirimler, Erişilebilirlik, Ekran Kaydı, Mikrofon, Konuşma Tanıma, Otomasyon/AppleScript) sahipliğini üstlenir.
• Gateway’i çalıştırır veya ona bağlanır (yerel veya uzak).
• macOS’e özgü araçları açığa çıkarır (Canvas, Kamera, Ekran Kaydı, system.run).
• Yerel düğüm ana makinesi hizmetini remote modda (launchd) başlatır ve local modda durdurur.
• İsteğe bağlı olarak UI otomasyonu için PeekabooBridge barındırır.
• İstek üzerine npm/pnpm aracılığıyla global CLI’yi (openclaw) kurar (Gateway çalışma zamanı için bun önerilmez).

​

Yerel vs uzak mod

• Local (varsayılan): uygulama, mevcutsa çalışan yerel bir Gateway’e bağlanır; aksi halde launchd hizmetini openclaw gateway install üzerinden etkinleştirir.
• Remote: uygulama, SSH/Tailscale üzerinden bir Gateway’e bağlanır ve asla yerel bir süreç başlatmaz. Uzak Gateway’in bu Mac’e erişebilmesi için yerel düğüm ana makinesi hizmetini başlatır. Uygulama, Gateway’i alt süreç olarak başlatmaz.

​

Launchd denetimi

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

​

Düğüm yetenekleri (mac)

• Canvas: canvas.present, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.*
• Kamera: camera.snap, camera.clip
• Ekran: screen.record
• Sistem: system.run, system.notify

• Başsız düğüm ana makinesi hizmeti çalıştığında (remote mod), Gateway WS’ye bir düğüm olarak bağlanır.
• system.run, macOS uygulamasında (UI/TCC bağlamı) yerel bir Unix soketi üzerinden çalışır; istemler ve çıktı uygulama içinde kalır.

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

​

Exec onayları (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" }]
    }
  }
}

• allowlist girdileri, çözümlenmiş ikili dosya yolları için glob desenleridir.
• İstemde “Her Zaman İzin Ver” seçilmesi, bu komutu izin listesine ekler.
• system.run ortam geçersiz kılmaları filtrelenir (PATH, DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT bırakılır) ve ardından uygulamanın ortamıyla birleştirilir.

​

Derin bağlantılar

​

openclaw://agent

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

• message (gerekli)
• sessionKey (isteğe bağlı)
• thinking (isteğe bağlı)
• deliver / to / channel (isteğe bağlı)
• timeoutSeconds (isteğe bağlı)
• key (isteğe bağlı, gözetimsiz mod anahtarı)

• key olmadan, uygulama onay ister.
• key olmadan uygulama, onay istemi için kısa bir mesaj sınırı uygular ve deliver / to / channel alanlarını yok sayar.
• Geçerli bir key ile çalıştırma gözetimsizdir (kişisel otomasyonlar için tasarlanmıştır).

​

Onboarding akışı (tipik)

1. OpenClaw.app’i kurun ve başlatın.
2. İzinler kontrol listesini tamamlayın (TCC istemleri).
3. Local modun etkin olduğundan ve Gateway’in çalıştığından emin olun.
4. Terminal erişimi istiyorsanız CLI’yi kurun.

​

Build & geliştirme iş akışı (yerel)

• cd apps/macos && swift build
• swift run OpenClaw (veya Xcode)
• Uygulamayı paketleme: scripts/package-mac-app.sh

​

Gateway bağlantısını hata ayıklama (macOS CLI)

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

• --url <ws://host:port>: yapılandırmayı geçersiz kıl
• --mode <local|remote>: yapılandırmadan çözümle (varsayılan: yapılandırma veya yerel)
• --probe: yeni bir sağlık yoklaması zorla
• --timeout <ms>: istek zaman aşımı (varsayılan: 15000)
• --json: karşılaştırma için yapılandırılmış çıktı

• --include-local: “yerel” olarak filtrelenecek gateway’leri dahil et
• --timeout <ms>: genel keşif penceresi (varsayılan: 2000)
• --json: karşılaştırma için yapılandırılmış çıktı

​

Uzak bağlantı tesisatı (SSH tünelleri)

​

Denetim tüneli (Gateway WebSocket portu)

• Amaç: sağlık kontrolleri, durum, Web Chat, yapılandırma ve diğer kontrol düzlemi çağrıları.
• Yerel port: Gateway portu (varsayılan 18789), her zaman sabit.
• Uzak port: uzak ana makinedeki aynı Gateway portu.
• Davranış: rastgele yerel port yoktur; uygulama mevcut sağlıklı bir tüneli yeniden kullanır veya gerekirse yeniden başlatır.
• SSH şekli: BatchMode + ExitOnForwardFailure + keepalive seçenekleriyle ssh -N -L <local>:127.0.0.1:<remote>.
• IP raporlama: SSH tüneli loopback kullanır, bu nedenle gateway düğüm IP’sini 127.0.0.1 olarak görür. Gerçek istemci IP’sinin görünmesini istiyorsanız Direct (ws/wss) taşımasını kullanın (bkz. macOS remote access).

​

İlgili belgeler

• Gateway runbook
• Gateway (macOS)
• macOS permissions
• Canvas