Gateway di macOS

OpenClaw.app tidak lagi membundel Node/Bun atau runtime Gateway. Aplikasi macOS mengharapkan instalasi CLI openclaw eksternal, tidak menjalankan Gateway sebagai proses anak, dan mengelola layanan launchd per pengguna agar Gateway tetap berjalan (atau terhubung ke Gateway lokal yang sudah ada jika sudah berjalan).

Penyiapan otomatis

Pada Mac baru, pilih Mac Ini selama onboarding. Aplikasi menjalankan installer bertanda tangan yang dibundel sebelum wizard Gateway, memasang runtime Node ruang pengguna dan CLI openclaw yang cocok di bawah ~/.openclaw, lalu memasang dan memulai layanan launchd per pengguna. Jalur ini tidak memerlukan Terminal, Homebrew, atau akses administrator.

Aplikasi membundel skrip installer, bukan payload Node atau Gateway. Karena itu, penyiapan memerlukan koneksi internet untuk mengunduh runtime dan paket OpenClaw yang cocok.

Pemulihan manual

Node 24 direkomendasikan untuk instalasi manual. Node 22 LTS, saat ini 22.19+, juga berfungsi. Lalu pasang openclaw secara global:

npm install -g openclaw@<version>

Gunakan Coba lagi penyiapan setelah penyiapan otomatis gagal. Jika masih gagal, pasang CLI secara manual dengan perintah di atas, lalu pilih Periksa lagi di onboarding. Node tetap menjadi runtime Gateway yang direkomendasikan.

Launchd (Gateway sebagai LaunchAgent)

Label:

• ai.openclaw.gateway (atau ai.openclaw.<profile>; com.openclaw.* lama mungkin tetap ada)

Lokasi plist (per pengguna):

• ~/Library/LaunchAgents/ai.openclaw.gateway.plist (atau ~/Library/LaunchAgents/ai.openclaw.<profile>.plist)

Pengelola:

• Aplikasi macOS memiliki pemasangan/pembaruan LaunchAgent dalam mode Lokal.
• CLI juga dapat memasangnya: openclaw gateway install.

Perilaku:

• "OpenClaw Aktif" mengaktifkan/menonaktifkan LaunchAgent.
• Keluar dari aplikasi tidak menghentikan gateway (launchd menjaganya tetap hidup).
• Jika Gateway sudah berjalan pada port yang dikonfigurasi, aplikasi terhubung ke sana alih-alih memulai yang baru.

Logging:

• stdout launchd: ~/Library/Logs/openclaw/gateway.log (profil menggunakan gateway-<profile>.log)
• stderr launchd: disembunyikan

Kompatibilitas versi

Aplikasi macOS memeriksa versi Gateway terhadap versinya sendiri. Onboarding secara otomatis menjalankan penyiapan terkelola ketika CLI yang ada tidak ada atau tidak kompatibel. Gunakan Coba lagi penyiapan untuk mengulang instalasi atau Periksa lagi setelah memperbaiki CLI eksternal.

Direktori status di macOS

Simpan status OpenClaw pada disk lokal yang tidak disinkronkan. Hindari iCloud Drive dan folder lain yang disinkronkan ke cloud karena latensi sinkronisasi dan kunci file dapat memengaruhi sesi, kredensial, dan status Gateway.

Tetapkan OPENCLAW_STATE_DIR ke path lokal hanya ketika Anda memerlukan override. openclaw doctor memperingatkan tentang path status umum yang disinkronkan ke cloud dan merekomendasikan pemindahan kembali ke penyimpanan lokal. Lihat variabel lingkungan dan Doctor.

Debug konektivitas aplikasi

Gunakan CLI debug macOS dari checkout sumber untuk menjalankan handshake WebSocket Gateway dan logika penemuan yang sama dengan yang digunakan aplikasi:

cd apps/macosswift run openclaw-mac connect --jsonswift run openclaw-mac discover --timeout 3000 --json

connect menerima --url, --token, --timeout, dan --json. discover menerima --timeout, --json, dan --include-local. Bandingkan output penemuan dengan openclaw gateway discover --json ketika Anda perlu memisahkan penemuan CLI dari masalah koneksi sisi aplikasi.

Pemeriksaan smoke

openclaw --version OPENCLAW_SKIP_CHANNELS=1 \OPENCLAW_SKIP_CANVAS_HOST=1 \openclaw gateway --port 18999 --bind loopback

Lalu:

openclaw gateway call health --url ws://127.0.0.1:18999 --timeout 3000

Terkait

• aplikasi macOS
• Runbook Gateway