Jika Anda mencoba menjalankan OpenClaw (sering disebut dalam fork atau paket komunitas sebagai Moltbot/Clawdbot) secara lokal, bagian sulitnya biasanya bukanlah mengkloning repositori—melainkan menangani versi runtime, variabel lingkungan, dan masalah build spesifik platform.
Panduan ini memberikan Anda jalur instalasi praktis, lintas platform, dengan langkah-langkah debugging yang membantu ketika terjadi masalah.
Apa yang umumnya melibatkan penyiapan OpenClaw
Sebagian besar distribusi OpenClaw mengikuti bentuk penyebaran yang sama:
- Kloning kode sumber dari Git.
- Instal dependensi bahasa/runtime.
- Konfigurasi file
.env(token, DB, kunci API). - Inisialisasi penyimpanan (SQLite/Postgres/Redis tergantung pada build).
- Jalankan skrip migrasi/bootstrap.
- Mulai layanan dan validasi endpoint kesehatan.
Meskipun fork spesifik Anda berbeda, daftar periksa ini berlaku untuk hampir setiap instalasi.
Prasyarat (semua sistem operasi)
Sebelum langkah-langkah spesifik OS, konfirmasi dasar-dasar ini:
- Git: untuk mengkloning dan menarik pembaruan.
- Runtime: umumnya Node.js (LTS) atau Python (3.10+), tergantung pada fork.
- Manajer paket: npm/pnpm/yarn untuk Node, pip/poetry untuk Python.
- Database (opsional): SQLite untuk memulai cepat secara lokal, Postgres untuk penggunaan tim/staging.
- Shell terminal: PowerShell (Windows), zsh/bash (macOS/Linux).
Verifikasi alat Anda
bash git --version node -v npm -v python3 --version pip --version
Jika dokumen proyek Anda menentukan versi yang tepat, gunakan versi tersebut sekarang. Perbedaan versi adalah penyebab #1 kegagalan instalasi "berfungsi di mesin saya".
Instal OpenClaw di macOS/Linux
Di macOS atau Linux, jalankan penginstal terpadu:
curl -fsSL https://openclaw.ai/install.sh | bash
Untuk metode instalasi alternatif dan persyaratan sistem terperinci, lihat bagian Instalasi.
1. Jalankan Wizard Orientasi
openclaw onboard --install-daemon
Wizard ini menyiapkan autentikasi, konfigurasi gateway, dan saluran pesan opsional (WhatsApp, Telegram, dll.).
Untuk panduan lengkap, lihat dokumentasi Wizard Orientasi.
2. Verifikasi Gateway
Jika Anda menginstal layanan latar belakang (daemon), seharusnya sudah berjalan. Periksa statusnya dengan:
openclaw gateway status
3. Buka UI Kontrol
Luncurkan dasbor:
openclaw dashboard
Anda sekarang dapat mengakses instans OpenClaw Anda melalui UI kontrol berbasis browser.
Instal OpenClaw di Windows
Di Windows (dengan PowerShell), jalankan penginstal terpadu:
iwr -useb https://openclaw.ai/install.ps1 | iexUntuk metode instalasi alternatif dan persyaratan sistem terperinci, lihat bagian Instalasi.
1. Jalankan Wizard Orientasi
openclaw onboard --install-daemon
Wizard ini menyiapkan autentikasi, konfigurasi gateway, dan saluran pesan opsional (WhatsApp, Telegram, dll.).
Untuk panduan lengkap, lihat dokumentasi Wizard Orientasi.
2. Verifikasi Gateway
Jika Anda menginstal layanan latar belakang (daemon), seharusnya sudah berjalan. Periksa statusnya dengan:
openclaw gateway status
3. Buka UI Kontrol
Luncurkan dasbor:
openclaw dashboard
Anda sekarang dapat mengakses instans OpenClaw Anda melalui UI kontrol berbasis browser.
Instalasi berbasis Docker (direkomendasikan untuk konsistensi)
Jika Anda menginginkan lebih sedikit masalah dependensi tingkat host, jalankan OpenClaw dengan Docker Compose.
Pola docker-compose.yml contoh:
yaml version: '3.9' services: app: build: . ports: - "3000:3000" env_file: - .env depends_on: - db - redis
db: image: postgres:15 environment: POSTGRES_USER: openclaw POSTGRES_PASSWORD: openclaw POSTGRES_DB: openclaw ports: - "5432:5432"
redis: image: redis:7 ports: - "6379:6379"
Mulai:
bash docker compose up --build
Pendekatan ini memberikan lingkungan yang dapat direproduksi di macOS, Windows, dan Linux, terutama untuk tim.
Kesalahan instalasi umum dan perbaikannya
1) MODULE_NOT_FOUND atau kesalahan impor
Penyebab: dependensi tidak terinstal, lockfile salah, atau runtime tidak kompatibel.
Perbaikan:
- Hapus
node_modulesdan instal ulang dengannpm ci. - Sesuaikan runtime dengan dokumen proyek (
.nvmrc,pyproject.toml,runtime.txt). - Jangan mencampur manajer paket kecuali repositori mendukungnya.
2) Koneksi database ditolak
Penyebab: Layanan DB mati atau DATABASE_URL salah.
Perbaikan:
- Konfirmasi status layanan (
systemctl status postgresql,brew services list). - Validasi nama host/port/pengguna/kata sandi/db.
- Uji koneksi secara independen dengan
psql.
3) Port sudah digunakan
Perbaikan: temukan dan hentikan proses yang berkonflik.
macOS/Linux:
bash lsof -i :3000 kill -9
Windows:
powershell netstat -ano | findstr :3000 taskkill /PID /F
4) Izin ditolak di Linux/macOS
Penyebab: skrip tidak memiliki izin eksekusi.
bash chmod +x ./scripts/*.sh
Hindari menjalankan perintah aplikasi dengan sudo kecuali benar-benar diperlukan.
5) Variabel lingkungan tidak dimuat
Perbaikan:
- Pastikan
.envberada di root proyek. - Mulai ulang proses setelah perubahan
.env. - Verifikasi paket loader (
dotenv) diinisialisasi lebih awal.
Daftar periksa pengerasan pasca-instalasi
Setelah OpenClaw berhasil dimulai, lakukan hal-hal berikut sebelum berbagi dengan rekan tim:
- Rotasi rahasia default.
- Tegakkan token API yang kuat.
- Batasi URL CORS dan callback.
- Atur level log yang aman untuk produksi.
- Tambahkan probe kesehatan/kesiapan.
- Konfigurasi strategi pencadangan untuk volume DB.
Jika Anda mengeksposnya di luar localhost, letakkan di belakang reverse proxy (Nginx/Caddy) dengan TLS.
Validasi dan uji API OpenClaw dengan cepat
Setelah instalasi, Anda harus memverifikasi perilaku endpoint—tidak hanya startup proses.
Pola cepat:
- Impor file OpenAPI OpenClaw (jika disediakan).
- Buat variabel lingkungan untuk URL lokal/staging.
- Buat pemeriksaan regresi untuk endpoint autentikasi, CRUD, dan webhook.
Di sinilah Apidog membantu mengurangi friksi. Anda dapat merancang, men-debug, menguji, dan mendokumentasikan API dalam satu ruang kerja, sehingga validasi penyiapan tidak menyebar ke berbagai alat.
Alur kerja praktis di Apidog:
- Impor skema dan hasilkan koleksi permintaan.
- Tambahkan pengujian otomatis dengan pernyataan berbasis skenario.
- Mengejek dependensi yang hilang dengan respons dinamis.
- Bagikan dokumen interaktif dengan tim Anda setelah stabil.
Jika Anda menguji fork OpenClaw dengan perubahan yang sering, alur kerja tunggal itu lebih cepat daripada memelihara skrip secara manual ditambah dokumen terpisah.
Strategi peningkatan untuk fork OpenClaw
Fork bot/alat open-source berkembang pesat. Gunakan jalur pembaruan yang dapat diulang:
bash git fetch origin git checkout main git pull npm ci npm run migrate npm test npm run dev
Untuk build Python:
bash pip install -r requirements.txt python manage.py migrate pytest
Gunakan pengujian berbasis cabang sebelum menggabungkan perubahan hulu. Jika tim Anda menggunakan kontrak API, pemeriksaan perbedaan skema mencegah perubahan yang merusak secara diam-diam.
Pikiran terakhir
Menginstal OpenClaw (Moltbot/Clawdbot) di macOS, Windows, atau Linux adalah hal yang mudah setelah Anda mengendalikan tiga variabel: versi runtime, konfigurasi lingkungan, dan dependensi layanan.
Jika Anda menginstal untuk tim, Docker Compose biasanya merupakan dasar yang paling andal. Jika Anda menginstal untuk pengembangan lokal, penyiapan asli tidak masalah—cukup kunci versi dan terapkan skrip orientasi.
Setelah OpenClaw berjalan, perlakukan validasi API sebagai bagian dari instalasi yang benar. Anda dapat mengimpor dan menguji endpoint di Apidog, membuat pemeriksaan otomatis, dan menjaga dokumentasi tetap sinkron seiring perkembangan fork Anda.
Cobalah secara gratis—tidak perlu kartu kredit—dan gunakan untuk mengunci alur kerja API OpenClaw Anda dari boot pertama hingga pengujian regresi.