​

OpenClaw macOS Yardımcısı (menü çubuğu + Gateway aracısı)

​

Ne yapar

• Menü çubuğunda yerel bildirimleri ve durumu gösterir.
• TCC istemlerini yönetir (Bildirimler, Erişilebilirlik, Ekran Kaydı, Mikrofon, Konuşma Tanıma, Otomasyon/AppleScript).
• Gateway’i çalıştırır veya ona bağlanır (yerel ya da uzak).
• Yalnızca macOS’a özgü araçları sunar (Canvas, Camera, Screen Recording, system.run).
• Yerel düğüm ana hizmetini remote modda başlatır (launchd) ve local modda durdurur.
• İsteğe bağlı olarak UI otomasyonu için PeekabooBridge barındırır.
• Genel CLI’ı (openclaw) istek üzerine npm, pnpm veya bun aracılığıyla kurar (uygulama önce npm’i, sonra pnpm’i, sonra bun’ı tercih eder; önerilen Gateway çalışma zamanı ise hâlâ Node’dur).

​

Yerel ve uzak mod

• Local (varsayılan): uygulama, varsa çalışan bir yerel Gateway’e bağlanır; yoksa launchd hizmetini openclaw gateway install ile etkinleştirir.
• Remote: uygulama, SSH/Tailscale üzerinden bir Gateway’e bağlanır ve asla yerel bir süreç başlatmaz. Uygulama, uzak Gateway’in bu Mac’e erişebilmesi için yerel node host service hizmetini başlatır. Uygulama, Gateway’i alt süreç olarak başlatmaz. Gateway bulma artık ham tailnet IP’leri yerine Tailscale MagicDNS adlarını tercih eder, böylece tailnet IP’leri değiştiğinde Mac uygulaması daha güvenilir şekilde toparlanır.

​

Launchd denetimi

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

​

Düğüm yetenekleri (mac)

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

• Başsız düğüm ana hizmeti çalışırken (remote mod), Gateway WS’ye bir düğüm olarak bağlanır.
• system.run, yerel bir Unix soketi üzerinden macOS uygulamasında (UI/TCC bağlamı) yürütülü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)

​

Yürütme 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.
• Kabuk denetimi veya genişletme söz dizimi içeren ham kabuk komut metni (&&, ||, ;, |, `, $, <, >, (, )) izin listesi kaçırması olarak değerlendirilir ve açık onay gerektirir (veya kabuk ikilisinin izin listesine alınmasını).
• İstemde “Always Allow” seçildiğinde, bu komut izin listesine eklenir.
• system.run ortam değişkeni geçersiz kılmaları filtrelenir (PATH, DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT, SHELLOPTS, PS4 çıkarılır) ve ardından uygulamanın ortamıyla birleştirilir.
• Kabuk sarmalayıcıları için (bash|sh|zsh ... -c/-lc), istek kapsamlı ortam geçersiz kılmaları küçük ve açık bir izin listesine indirgenir (TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR).
• İzin listesi modunda her zaman izin ver kararları için, bilinen yönlendirme sarmalayıcıları (env, nice, nohup, stdbuf, timeout) sarmalayıcı yolları yerine iç yürütülebilir dosya yollarını kalıcılaştırır. Sarmalayıcının açılması güvenli değilse, otomatik olarak hiçbir izin listesi girdisi kalıcılaştırılmaz.

​

Derin bağlantılar

​

openclaw://agent

• message (zorunlu)
• 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 değerlerini yok sayar.
• Geçerli bir key ile çalıştırma gözetimsiz olur (kişisel otomasyonlar için tasarlanmıştır).

​

İlk kurulum akışı (tipik)

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

​

Durum dizini yerleşimi (macOS)

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

​

Derleme ve 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ı ayıklama (macOS CLI)

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

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

​

Uzak bağlantı altyapısı (SSH tünelleri)

​

Denetim tüneli (Gateway WebSocket portu)

• Amaç: sağlık denetimleri, durum, Web Chat, yapılandırma ve diğer kontrol düzlemi çağrıları.
• Yerel port: Gateway portu (varsayılan 18789), her zaman sabittir.
• Uzak port: uzak ana makinedeki aynı Gateway portu.
• Davranış: rastgele yerel port yoktur; uygulama mevcut sağlıklı tüneli yeniden kullanır veya gerekirse yeniden başlatır.
• SSH biçimi: BatchMode + ExitOnForwardFailure + keepalive seçenekleri ile ssh -N -L <local>:127.0.0.1:<remote>.
• IP raporlama: SSH tüneli loopback kullandığından, 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