​

Pendamping OpenClaw untuk macOS (bilah menu + broker Gateway)

​

Apa yang dilakukan

• Menampilkan notifikasi native dan status di bilah menu.
• Menangani prompt TCC (Notifikasi, Aksesibilitas, Perekaman Layar, Mikrofon, Pengenalan Ucapan, Otomatisasi/AppleScript).
• Menjalankan atau terhubung ke Gateway (lokal atau jarak jauh).
• Mengekspos tool khusus macOS (Canvas, Kamera, Perekaman Layar, system.run).
• Memulai layanan host node lokal dalam mode remote (launchd), dan menghentikannya dalam mode local.
• Secara opsional meng-host PeekabooBridge untuk otomatisasi UI.
• Menginstal CLI global (openclaw) atas permintaan melalui npm, pnpm, atau bun (aplikasi memprioritaskan npm, lalu pnpm, lalu bun; Node tetap menjadi runtime Gateway yang direkomendasikan).

​

Mode local vs remote

• Local (default): aplikasi terhubung ke Gateway lokal yang sedang berjalan jika ada; jika tidak, aplikasi mengaktifkan layanan launchd melalui openclaw gateway install.
• Remote: aplikasi terhubung ke Gateway melalui SSH/Tailscale dan tidak pernah memulai proses lokal. Aplikasi memulai layanan host node lokal agar Gateway jarak jauh dapat menjangkau Mac ini. Aplikasi tidak men-spawn Gateway sebagai proses anak. Discovery Gateway sekarang memprioritaskan nama Tailscale MagicDNS dibanding IP tailnet mentah, sehingga aplikasi Mac pulih dengan lebih andal saat IP tailnet berubah.

​

Kontrol launchd

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

​

Kemampuan Node (mac)

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

• Saat layanan host node headless berjalan (mode remote), layanan tersebut terhubung ke Gateway WS sebagai node.
• system.run dijalankan di aplikasi macOS (konteks UI/TCC) melalui socket Unix lokal; prompt + output tetap di dalam aplikasi.

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

​

Persetujuan 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" }]
    }
  }
}

• Entri allowlist adalah pola glob untuk path biner yang telah di-resolve.
• Teks perintah shell mentah yang berisi sintaks kontrol atau ekspansi shell (&&, ||, ;, |, `, $, <, >, (, )) diperlakukan sebagai allowlist miss dan memerlukan persetujuan eksplisit (atau menambahkan biner shell ke allowlist).
• Memilih “Always Allow” di prompt akan menambahkan perintah tersebut ke allowlist.
• Override environment system.run difilter (menghapus PATH, DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT, SHELLOPTS, PS4) lalu digabungkan dengan environment aplikasi.
• Untuk wrapper shell (bash|sh|zsh ... -c/-lc), override environment dengan cakupan permintaan dikurangi menjadi allowlist eksplisit kecil (TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR).
• Untuk keputusan selalu-izinkan dalam mode allowlist, wrapper dispatch yang dikenal (env, nice, nohup, stdbuf, timeout) menyimpan path executable internal, bukan path wrapper. Jika unwrap tidak aman, tidak ada entri allowlist yang disimpan secara otomatis.

​

Deep link

​

openclaw://agent

• message (wajib)
• sessionKey (opsional)
• thinking (opsional)
• deliver / to / channel (opsional)
• timeoutSeconds (opsional)
• key (opsional, kunci mode tanpa pengawasan)

• Tanpa key, aplikasi meminta konfirmasi.
• Tanpa key, aplikasi menerapkan batas pesan singkat untuk prompt konfirmasi dan mengabaikan deliver / to / channel.
• Dengan key yang valid, proses berjalan tanpa pengawasan (ditujukan untuk otomatisasi pribadi).

​

Alur onboarding (umum)

1. Instal dan jalankan OpenClaw.app.
2. Selesaikan daftar periksa izin (prompt TCC).
3. Pastikan mode Local aktif dan Gateway berjalan.
4. Instal CLI jika Anda ingin akses terminal.

​

Penempatan direktori state (macOS)

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

​

Workflow build & pengembangan (native)

• cd apps/macos && swift build
• swift run OpenClaw (atau Xcode)
• Paketkan aplikasi: scripts/package-mac-app.sh

​

Debug konektivitas gateway (CLI macOS)

• --url <ws://host:port>: override config
• --mode <local|remote>: resolve dari config (default: config atau local)
• --probe: paksa health probe baru
• --timeout <ms>: request timeout (default: 15000)
• --json: output terstruktur untuk diffing

• --include-local: sertakan gateway yang seharusnya difilter sebagai “local”
• --timeout <ms>: jendela discovery keseluruhan (default: 2000)
• --json: output terstruktur untuk diffing

​

Plumbing koneksi remote (tunnel SSH)

​

Tunnel kontrol (port WebSocket Gateway)

• Tujuan: health check, status, Web Chat, config, dan panggilan control-plane lainnya.
• Port lokal: port Gateway (default 18789), selalu stabil.
• Port remote: port Gateway yang sama pada host remote.
• Perilaku: tidak ada port lokal acak; aplikasi menggunakan kembali tunnel sehat yang ada atau memulainya ulang jika diperlukan.
• Bentuk SSH: ssh -N -L <local>:127.0.0.1:<remote> dengan opsi BatchMode + ExitOnForwardFailure + keepalive.
• Pelaporan IP: tunnel SSH menggunakan loopback, sehingga gateway akan melihat IP node sebagai 127.0.0.1. Gunakan transport Direct (ws/wss) jika Anda ingin IP klien yang sebenarnya muncul (lihat akses remote macOS).

​

Dokumen terkait

• Runbook Gateway
• Gateway (macOS)
• Izin macOS
• Canvas