Penyiapan

TL;DR

Pilih alur kerja penyiapan berdasarkan seberapa sering Anda menginginkan pembaruan dan apakah Anda ingin menjalankan Gateway sendiri:

• Penyesuaian berada di luar repo: simpan konfigurasi dan workspace Anda di ~/.openclaw/openclaw.json dan ~/.openclaw/workspace/ agar pembaruan repo tidak menyentuhnya.
• Alur kerja stabil (direkomendasikan untuk sebagian besar pengguna): instal aplikasi macOS dan biarkan aplikasi menjalankan Gateway bawaan.
• Alur kerja bleeding edge (dev): jalankan Gateway sendiri melalui pnpm gateway:watch, lalu biarkan aplikasi macOS terhubung dalam mode Lokal.

Prasyarat (dari sumber)

• Node 24 direkomendasikan (Node 22 LTS, saat ini 22.19+, masih didukung)
• pnpm diperlukan untuk checkout sumber. OpenClaw memuat Plugin bawaan dari paket workspace pnpm extensions/* dalam mode dev, sehingga npm install di root tidak menyiapkan seluruh pohon sumber.
• Docker (opsional; hanya untuk penyiapan/e2e berbasis kontainer - lihat Docker)

Strategi penyesuaian (agar pembaruan tidak merusak)

Jika Anda menginginkan "100% disesuaikan untuk saya" dan pembaruan yang mudah, simpan kustomisasi Anda di:

• Konfigurasi: ~/.openclaw/openclaw.json (mirip JSON/JSON5)
• Workspace: ~/.openclaw/workspace (skills, prompt, memori; jadikan repo git privat)

Bootstrap satu kali:

openclaw setup

Dari dalam repo ini, gunakan entri CLI lokal:

openclaw setup

Jika Anda belum memiliki instalasi global, jalankan melalui pnpm openclaw setup.

Jalankan Gateway dari repo ini

Setelah pnpm build, Anda dapat menjalankan CLI terpaket secara langsung:

node openclaw.mjs gateway --port 18789 --verbose

Alur kerja stabil (aplikasi macOS lebih dulu)

1. Instal + luncurkan OpenClaw.app (menu bar).
2. Selesaikan checklist onboarding/izin (prompt TCC).
3. Pastikan Gateway Lokal dan berjalan (aplikasi mengelolanya).
4. Tautkan surface (contoh: WhatsApp):

openclaw channels login

5. Pemeriksaan kewajaran:

openclaw health

Jika onboarding tidak tersedia dalam build Anda:

• Jalankan openclaw setup, lalu openclaw channels login, lalu mulai Gateway secara manual (openclaw gateway).

Alur kerja bleeding edge (Gateway di terminal)

Tujuan: bekerja pada Gateway TypeScript, mendapatkan hot reload, dan menjaga UI aplikasi macOS tetap terhubung.

0) (Opsional) Jalankan juga aplikasi macOS dari sumber

Jika Anda juga menginginkan aplikasi macOS pada bleeding edge:

./scripts/restart-mac.sh

1) Mulai Gateway dev

pnpm install# First run only (or after resetting local OpenClaw config/workspace)pnpm openclaw setuppnpm gateway:watch

gateway:watch memulai atau memulai ulang proses watch Gateway dalam sesi tmux bernama dan otomatis terhubung dari terminal interaktif. Shell non-interaktif tetap terlepas dan mencetak tmux attach -t openclaw-gateway-watch-main; gunakan OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch agar proses interaktif tetap terlepas, atau pnpm gateway:watch:raw untuk mode watch foreground. Watcher memuat ulang pada perubahan sumber, konfigurasi, dan metadata Plugin bawaan yang relevan. Jika Gateway yang diawasi keluar saat startup, gateway:watch menjalankan openclaw doctor --fix --non-interactive satu kali dan mencoba ulang; tetapkan OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 untuk menonaktifkan langkah perbaikan khusus dev tersebut. pnpm openclaw setup adalah langkah inisialisasi konfigurasi/workspace lokal satu kali untuk checkout baru. pnpm gateway:watch tidak membangun ulang dist/control-ui, jadi jalankan ulang pnpm ui:build setelah perubahan ui/ atau gunakan pnpm ui:dev saat mengembangkan UI Kontrol.

2) Arahkan aplikasi macOS ke Gateway yang sedang berjalan

Di OpenClaw.app:

• Mode Koneksi: Lokal Aplikasi akan terhubung ke gateway yang sedang berjalan pada port yang dikonfigurasi.

3) Verifikasi

• Status Gateway di dalam aplikasi seharusnya menampilkan "Menggunakan gateway yang ada …"
• Atau melalui CLI:

openclaw health

Kesalahan umum

• Port salah: WS Gateway default ke ws://127.0.0.1:18789; pastikan aplikasi + CLI menggunakan port yang sama.
• Lokasi state:
  • State channel/provider: ~/.openclaw/credentials/
  • Profil auth model: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Sesi: ~/.openclaw/agents/<agentId>/sessions/
  • Log: /tmp/openclaw/

Peta penyimpanan kredensial

Gunakan ini saat men-debug auth atau memutuskan apa yang perlu dicadangkan:

• WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• Token bot Telegram: konfigurasi/env atau channels.telegram.tokenFile (hanya file biasa; symlink ditolak)
• Token bot Discord: konfigurasi/env atau SecretRef (provider env/file/exec)
• Token Slack: konfigurasi/env (channels.slack.*)
• Allowlist pairing:
  • ~/.openclaw/credentials/<channel>-allowFrom.json (akun default)
  • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json (akun non-default)
• Profil auth model: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• Payload rahasia berbasis file (opsional): ~/.openclaw/secrets.json
• Impor OAuth legacy: ~/.openclaw/credentials/oauth.json Detail lebih lanjut: Keamanan.

Memperbarui (tanpa merusak penyiapan Anda)

• Perlakukan ~/.openclaw/workspace dan ~/.openclaw/ sebagai "milik Anda"; jangan masukkan prompt/konfigurasi pribadi ke repo openclaw.
• Memperbarui sumber: git pull + pnpm install + terus gunakan pnpm gateway:watch.

Linux (layanan pengguna systemd)

Instalasi Linux menggunakan layanan pengguna systemd. Secara default, systemd menghentikan layanan pengguna saat logout/idle, yang mematikan Gateway. Onboarding mencoba mengaktifkan lingering untuk Anda (mungkin meminta sudo). Jika masih nonaktif, jalankan:

sudo loginctl enable-linger $USER

Untuk server always-on atau multi-pengguna, pertimbangkan layanan sistem alih-alih layanan pengguna (tidak perlu lingering). Lihat Runbook Gateway untuk catatan systemd.

Dokumen terkait

• Runbook Gateway (flag, supervisi, port)
• Konfigurasi Gateway (skema konfigurasi + contoh)
• Discord dan Telegram (tag balasan + pengaturan replyToMode)
• Penyiapan asisten OpenClaw
• Aplikasi macOS (siklus hidup gateway)