​

Pendamping macOS OpenClaw (menu bar + broker gateway)

​

Yang dilakukan

• Menampilkan notifikasi native dan status di menu bar.
• Memiliki prompt TCC (Notifikasi, Accessibility, Screen Recording, Microphone, Speech Recognition, Automation/AppleScript).
• Menjalankan atau terhubung ke Gateway (lokal atau remote).
• Mengekspos tool khusus macOS (Canvas, Camera, Screen Recording, 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) sesuai permintaan melalui npm, pnpm, atau bun (app lebih memilih npm, lalu pnpm, lalu bun; Node tetap menjadi runtime Gateway yang direkomendasikan).

​

Mode lokal vs remote

• Local (default): app terhubung ke Gateway lokal yang sedang berjalan jika ada; jika tidak, app mengaktifkan layanan launchd melalui openclaw gateway install.
• Remote: app terhubung ke Gateway melalui SSH/Tailscale dan tidak pernah memulai proses lokal. App memulai layanan host node lokal agar Gateway remote dapat menjangkau Mac ini. App tidak menjalankan Gateway sebagai child process. Discovery Gateway sekarang lebih mengutamakan nama Tailscale MagicDNS daripada IP tailnet mentah, sehingga app 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

​

Kapabilitas node (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

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

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

​

Exec approvals (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 jalur binary yang sudah di-resolve.
• Teks perintah shell mentah yang berisi sintaks kontrol atau ekspansi shell (&&, ||, ;, |, `, $, <, >, (, )) diperlakukan sebagai kegagalan allowlist dan memerlukan persetujuan eksplisit (atau memasukkan binary shell ke allowlist).
• Memilih “Always Allow” pada prompt 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 app.
• Untuk shell wrapper (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 allow-always dalam mode allowlist, wrapper dispatch yang dikenal (env, nice, nohup, stdbuf, timeout) menyimpan jalur executable bagian dalam, bukan jalur wrapper. Jika unwrapping tidak aman, tidak ada entri allowlist yang disimpan 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, app meminta konfirmasi.
• Tanpa key, app menerapkan batas pesan singkat untuk prompt konfirmasi dan mengabaikan deliver / to / channel.
• Dengan key yang valid, eksekusi berjalan tanpa pengawasan (ditujukan untuk otomatisasi pribadi).

​

Alur onboarding (umum)

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

​

Penempatan state dir (macOS)

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

​

Alur build & dev (native)

• cd apps/macos && swift build
• swift run OpenClaw (atau Xcode)
• Package app: 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>: timeout permintaan (default: 15000)
• --json: output terstruktur untuk diffing

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

​

Plumbing koneksi remote (tunnel SSH)

​

Control tunnel (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; app menggunakan kembali tunnel sehat yang sudah ada atau me-restart-nya bila perlu.
• Bentuk SSH: ssh -N -L <local>:127.0.0.1:<remote> dengan opsi BatchMode + ExitOnForwardFailure + keepalive.
• Pelaporan IP: tunnel SSH menggunakan loopback, jadi gateway akan melihat IP node sebagai 127.0.0.1. Gunakan transport Direct (ws/wss) jika Anda ingin IP klien asli terlihat (lihat akses remote macOS).

​

Dokumen terkait

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