Cara Setting OpenClaw (Moltbot/Clawdbot) di Raspberry Pi

OpenClaw bergerak cepat: dari turbulensi penamaan Moltbot ke Clawdbot menuju identitas yang stabil dan adopsi komunitas yang berkembang pesat. Jika Anda di sini, Anda kemungkinan besar menginginkan satu hasil praktis: node OpenClaw yang andal berjalan di Raspberry Pi yang dapat Anda percaya di rumah atau di tepi jaringan.

Panduan ini ditujukan untuk pengembang teknis mendalam. Anda akan menyiapkan OpenClaw dengan:

dependensi sistem yang dapat direproduksi,
isolasi layanan,
pemeriksaan kesehatan berbasis detak jantung (prioritaskan pemeriksaan murah terlebih dahulu),
pemanggilan model selektif,
pola sandboxing aman opsional,
dan observabilitas tingkat API.

Sepanjang panduan ini, saya akan menunjukkan di mana Apidog membantu: memvalidasi endpoint OpenClaw, membangun pengujian regresi, dan mendokumentasikan antarmuka API lokal Anda untuk penggunaan tim.

tombol

1) Keputusan arsitektur sebelum Anda menginstal

Sebelum menyentuh apt, putuskan bagaimana Pi Anda akan menjalankan alur kerja inferensi.

Opsi A: Pi sebagai orkestrator, model dialihkan

Terbaik untuk Raspberry Pi 4/5 dengan RAM terbatas.

OpenClaw menjalankan orkestrasi, penjadwalan, plugin, dan detak jantung secara lokal.
Inferensi LLM yang berat diarahkan ke penyedia jarak jauh atau server model LAN.
Beban termal lebih rendah, uptime lebih baik.

Opsi B: Pi hanya untuk model lokal yang ringan

Baik untuk privasi ketat dan tugas offline.

Gunakan model ringkas (terkuantisasi, jendela konteks kecil).
Batasi pipeline berat dan rantai panjang.
Harapkan kompromi latensi.

Opsi C: Perutean Hibrida

Arsitektur paling praktis.

Prioritaskan pemeriksaan deterministik yang murah.
Hanya eskalasi ke panggilan model saat diperlukan.
Arahkan tugas berisiko rendah secara lokal, kompleksitas tinggi secara jarak jauh.

Pola "pemeriksaan murah terlebih dahulu, model hanya jika diperlukan" ini telah menjadi strategi keandalan inti OpenClaw karena mengontrol biaya, tekanan termal, dan lonjakan latensi.

2) Dasar Perangkat Keras dan OS

Perangkat keras yang direkomendasikan

Raspberry Pi 5 (8GB) disarankan
Raspberry Pi 4 (4GB+) berfungsi untuk beban kerja yang lebih ringan
NVMe atau SSD berkualitas tinggi dibandingkan microSD untuk daya tahan
Catu daya stabil dan pendinginan aktif

Sistem Operasi

Gunakan Raspberry Pi OS Lite (64-bit) atau Ubuntu Server 24.04 untuk ARM64.

Kemudian perbarui:

sudo apt update && sudo apt upgrade -y sudo reboot

Atur hostname dan sinkronisasi waktu (penting untuk log dan kadaluarsa token):

sudo hostnamectl set-hostname openclaw-pi sudo timedatectl set-ntp true

3) Instal dependensi runtime

Tumpukan OpenClaw umumnya menggunakan pekerja Python dan/atau Node tergantung pada plugin. Instal keduanya untuk tetap kompatibel dengan modul yang berkembang.

sudo apt install -y   git curl wget jq build-essential pkg-config   python3 python3-venv python3-pip   nodejs npm   redis-server sqlite3

Periksa versi:

python3 --version node --version npm --version redis-server --version

Mengapa Redis + SQLite?

Redis: antrean/pensinyalan status latensi rendah.
SQLite: persistensi lokal ringan untuk pengaturan node tunggal.

Untuk multi-node nanti, migrasikan persistensi ke Postgres.

4) Buat pengguna layanan khusus

Hindari menjalankan agen sebagai pi atau root.

sudo useradd -m -s /bin/bash openclaw sudo usermod -aG sudo openclaw sudo mkdir -p /opt/openclaw sudo chown -R openclaw:openclaw /opt/openclaw

Ganti pengguna:

sudo su - openclaw cd /opt/openclaw

5) Kloning dan Konfigurasi OpenClaw

git clone https://github.com//.git app cd app

Ganti dengan jalur repo resmi saat ini dari halaman proyek OpenClaw.

Buat lingkungan Python:

python3 -m venv .venv source .venv/bin/activate pip install --upgrade pip pip install -r requirements.txt

Jika ada layanan Node:

npm ci

Salin template lingkungan:

cp .env.example .env

Bentuk .env yang umum:

OPENCLAW_HOST=0.0.0.0 OPENCLAW_PORT=8080 OPENCLAW_LOG_LEVEL=info
STATE_BACKEND=redis REDIS_URL=redis://127.0.0.1:6379 DB_URL=sqlite:////opt/openclaw/app/data/openclaw.db
MODEL_ROUTER=hybrid LOCAL_MODEL_ENABLED=true REMOTE_MODEL_ENABLED=true REMOTE_MODEL_API_KEY=your_key_here
HEARTBEAT_INTERVAL_SEC=15 HEARTBEAT_TIMEOUT_SEC=5 CHEAP_CHECKS_ENABLED=true
SANDBOX_MODE=on SANDBOX_PROVIDER=process

Gunakan chmod 600 .env untuk melindungi rahasia.

6) Tambahkan layanan systemd untuk keandalan

Buat /etc/systemd/system/openclaw.service:

[Unit] Description=OpenClaw Agent Service After=network-online.target redis.service Wants=network-online.target

[Service] Type=simple User=openclaw WorkingDirectory=/opt/openclaw/app Environment="PYTHONUNBUFFERED=1" ExecStart=/opt/openclaw/app/.venv/bin/python -m openclaw.server Restart=always RestartSec=3 TimeoutStartSec=30 TimeoutStopSec=20

# Pengerasan dasar
NoNewPrivileges=true PrivateTmp=true ProtectSystem=full ProtectHome=true ReadWritePaths=/opt/openclaw/app/data /opt/openclaw/app/logs

[Install] WantedBy=multi-user.target

Aktifkan dan mulai:

sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclaw sudo systemctl status openclaw

Lihat log terakhir:

journalctl -u openclaw -f

7) Terapkan strategi detak jantung (prioritaskan pemeriksaan murah)

Pelajaran komunitas yang berulang: jangan menghabiskan token model untuk mendeteksi kegagalan yang jelas.

Detak jantung berlapis yang direkomendasikan

Pemeriksaan proses L0: layanan hidup, port terbuka.
Pemeriksaan dependensi L1: Redis/DB dapat dijangkau, lag antrean dapat diterima.
Pemeriksaan tugas deterministik L2: jalankan skrip validasi statis.
Probe yang didukung model L3: hanya jika pemeriksaan sebelumnya berhasil tetapi kepercayaan diri rendah.

Contoh konfigurasi semu:

heartbeat: interval_sec: 15 timeout_sec: 5 stages: - name: process type: tcp target: 127.0.0.1:8080 - name: deps type: internal checks: [redis_ping, db_read] - name: deterministic type: task command: "python scripts/selfcheck.py" - name: model_probe type: llm enabled_on: degraded_only

Pola ini mengurangi biaya dan alarm palsu sekaligus melindungi uptime pada perangkat keras yang terbatas.

8) Eksekusi Aman dengan Batasan Sandbox

Jika OpenClaw menjalankan alat (shell, browser, penulisan file), isolasi eksekusi.

Dasar minimum pada Pi:

jalankan alat di bawah pengguna non-privilege,
tolak penulisan sistem file yang luas,
daftar putih direktori,
atur batas waktu subproses dan batas memori.

Jika tumpukan Anda mendukung sandbox yang diperkuat (serupa dengan model sandbox agen aman), gunakan itu untuk panggilan alat yang tidak tepercaya.

Pembatas praktis:

TOOL_EXEC_TIMEOUT_MS=12000 TOOL_MAX_STDOUT_KB=256 TOOL_ALLOWED_PATHS=/opt/openclaw/app/workdir TOOL_BLOCK_NETWORK_BY_DEFAULT=true

Untuk alat yang mendukung jaringan, hanya izinkan daftar host eksplisit.

9) Validasi API OpenClaw dengan Apidog

Setelah OpenClaw aktif, perlakukan seperti produk API lainnya: definisikan kontrak, uji perilaku, dan lacak regresi.

Mengapa Apidog di sini

Anda dapat menggunakan Apidog untuk:

mengimpor atau merancang spesifikasi OpenAPI OpenClaw Anda,
menjalankan pengujian otomatis terhadap endpoint Pi lokal,
membuat asersi visual untuk payload detak jantung,
membuat mock dependensi hilir untuk debugging offline,
mempublikasikan dokumen interaktif untuk rekan tim.

Contoh pengujian endpoint kesehatan

Asumsikan endpoint:

GET /healthz

Respons yang diharapkan:

{ "status": "ok", "checks": { "redis": "ok", "db": "ok", "queue_lag_ms": 12 } }

Di Apidog, buat skenario pengujian:

Pastikan HTTP 200.
Pastikan status == ok.
Pastikan checks.queue_lag_ms < 100.
Tambahkan lingkungan negatif di mana Redis dihentikan; harapkan status terdegradasi.

Ini mengubah “sepertinya baik-baik saja” menjadi gerbang kualitas API yang dapat diulang.

10) Penyetelan kinerja pada Raspberry Pi

Kontrol CPU dan termal

Pantau:

vcgencmd measure_temp uptime top

Jika suhu melebihi batas aman yang berkelanjutan, latensi inferensi akan melonjak karena pembatasan.

Tekanan memori

Aktifkan zram atau swap moderat jika diperlukan, tetapi hindari beban kerja yang banyak menggunakan swap untuk alur waktu nyata.

Antrean dan konkurensi

Mulai secara konservatif:

WORKER_CONCURRENCY=1 MAX_INFLIGHT_TASKS=4

Kemudian tingkatkan setelah mengamati latensi p95 dan tingkat kesalahan.

Rotasi log

Cegah keausan SD/SSD:

sudo apt install -y logrotate

Tambahkan aturan rotasi untuk /opt/openclaw/app/logs/*.log.

11) Panduan pemecahan masalah

Layanan sering restart setiap beberapa detik

Periksa kunci env yang salah atau kunci API yang hilang.
Jalankan aplikasi secara manual di dalam venv untuk melihat traceback lengkap.

sudo su - openclaw cd /opt/openclaw/app source .venv/bin/activate python -m openclaw.server

Koneksi Redis ditolak

sudo systemctl status redis redis-cli ping

Jika bukan PONG, perbaiki Redis sebelum men-debug OpenClaw.

Latensi tinggi setelah beberapa menit

Kemungkinan pembatasan termal atau tekanan memori.

kurangi konteks model,
turunkan konkurensi pekerja,
pindahkan panggilan berat ke model jarak jauh.

Detak jantung berhasil tetapi tugas gagal

Pemeriksaan Anda terlalu dangkal. Tambahkan probe tugas deterministik yang meniru alur kerja nyata (baca file, parse, rangkum, encode respons).

12) Daftar periksa pengerasan untuk penggunaan edge mendekati produksi

Pengguna khusus (openclaw), tidak ada runtime root
Kebijakan restart systemd dan batasan sumber daya
Rahasia dalam .env dengan izin ketat
Terminasi TLS melalui reverse proxy (Caddy/Nginx)
Daftar izin firewall (hanya LAN/VPN)
Tingkatan detak jantung dengan eskalasi probe model
Pembatasan sandbox alat
Pengujian kontrak API di Apidog
Jalankan pengujian otomatis di CI/CD untuk perubahan konfigurasi

Jika Anda berkolaborasi dengan tim backend, QA, dan frontend, masukkan spesifikasi API OpenClaw ke ruang kerja Apidog bersama. Anda akan menjaga perubahan skema, pengujian, mock, dan dokumen tetap sinkron daripada tersebar di berbagai alat.

13) Contoh peta endpoint yang harus Anda ekspos

Pertahankan permukaan yang kecil dan eksplisit:

GET /healthz — kesehatan dasar
GET /readyz — kesiapan dependensi
GET /metrics — metrik kompatibel Prometheus
POST /v1/tasks — kirim tugas
GET /v1/tasks/{id} — polling status
POST /v1/chat/completions — endpoint kompatibilitas opsional

Dokumentasikan ini di OpenAPI. Kemudian gunakan alur kerja schema-first Apidog untuk menegakkan konsistensi respons dan menghindari kerusakan pada konsumen saat modul OpenClaw berkembang.

Kesimpulan

Menjalankan OpenClaw di Raspberry Pi sangat mungkin dilakukan jika Anda merancang dengan mempertimbangkan batasan:

orkestrasi secara lokal, inferensi secara selektif,
gunakan lapisan detak jantung dengan pemeriksaan murah terlebih dahulu,
eksekusi alat dalam sandbox,
perlakukan agen lokal Anda sebagai layanan API nyata dengan pengujian dan dokumentasi.

Kombinasi tersebut memberi Anda node yang terjangkau, pribadi, dan cukup stabil untuk otomatisasi harian.

Jika Anda menginginkan langkah selanjutnya yang jelas, impor endpoint OpenClaw Anda ke Apidog dan buat tiga pengujian otomatis hari ini: healthz, readyz, dan satu alur tugas end-to-end. Anda akan menangkap regresi lebih awal dan menjaga penyebaran Pi Anda dapat dipercaya seiring pertumbuhan tumpukan agen Anda.

tombol