Pemecahan Masalah OpenClaw di Zeabur

OpenClaw berjalan lancar di Zeabur, sampai tiba-tiba berhenti.

Ini bukan skenario hipotetis. Dalam tiga minggu terakhir, kami menangani lebih dari 40 tiket dukungan terkait OpenClaw. Beberapa masalah bisa diselesaikan sendiri dalam lima menit, namun beberapa lainnya membuat orang terjebak berhari-hari.

Artikel ini mengumpulkan masalah yang paling sering terjadi, dilengkapi dengan solusi yang dirangkum dari kasus nyata. Lain kali ketika Anda menghadapinya, tidak perlu menunggu balasan dari layanan pelanggan.

Apa yang Anda lihat?

---

Pelajari ini dulu: Mode Penyelamatan

Apa pun masalah crash yang Anda hadapi, alur ini hampir selalu bisa menyelamatkannya. Hafalkan dulu, karena akan sering digunakan di bawah.

Versi yang diinstal setelah 2026/2/22 (dengan halaman bantuan)

Ketika Gateway crash, membuka URL layanan akan otomatis menampilkan halaman bantuan, yang berisi catatan error dan petunjuk perbaikan.

1. Lihat catatan error di halaman bantuan (catatan lengkap bisa dilihat di tab Log di Zeabur Dashboard)
2. Buka tab File di Zeabur Dashboard, temukan /home/node/.openclaw/openclaw.json dan perbaiki masalahnya
3. Klik Restart di Zeabur Dashboard

Setelah layanan pulih, halaman bantuan akan otomatis menghilang.

Versi yang diinstal sebelum 2026/2/22 (tanpa halaman bantuan)

Versi lama tidak memiliki halaman bantuan, perlu masuk ke container secara manual untuk memperbaiki.

1. Buka Zeabur Dashboard, temukan layanan OpenClaw Anda
2. Buka tab Log untuk melihat pesan error
3. Buka Pengaturan → Perintah, ubah perintah startup menjadi sleep 3600, lalu Restart — ini membuat container tetap berjalan, memberi Anda kesempatan untuk masuk dan memperbaiki
4. Buka tab File, temukan /home/node/.openclaw/openclaw.json dan perbaiki masalahnya
5. Ubah perintah startup kembali ke /opt/openclaw/startup.sh && /opt/openclaw/start_gateway.sh, lalu restart layanan

Ingin mengaktifkan halaman bantuan? Cukup deploy ulang dari template OpenClaw.

---

Masalah 1: Layanan crash setelah mengubah konfigurasi, terus restart

Ini adalah masalah yang paling sering terjadi saat ini, mencakup hampir setengah dari tiket dukungan.

Gejala: Status layanan menunjukkan CRASHED atau CrashLoopBackOff, log menampilkan error seperti ini:

Penyebab: Ada key yang tidak dikenali OpenClaw di file konfigurasi. Skenario umum: menambahkan field yang tidak ada saat mengedit manual, meminta OpenClaw mengubah konfigurasi tapi hasilnya rusak, field konfigurasi lama dihapus atau diganti namanya setelah upgrade versi. File konfigurasi disimpan di penyimpanan persisten, dan ketika menemukan key yang tidak dikenali, layanan langsung menolak untuk start.

Solusi:

Situasi A: Layanan masih bisa start (log menampilkan petunjuk Doctor)

Masuk ke tab Perintah dan jalankan openclaw doctor --fix, yang akan otomatis menghapus key yang tidak dikenali.

Situasi B: Layanan sudah crash, tidak bisa masuk ke shell

Ini adalah situasi yang paling umum. Gunakan Mode Penyelamatan di atas untuk masuk ke container, buka /home/node/.openclaw/openclaw.json, cocokkan dengan key yang tercantum di log (misalnya gateway.cool di atas), hapus key tersebut, lalu restart layanan.

---

Masalah 2: Layanan terjebak di "Memulai", startup probe timeout

Gejala: Layanan terus menunjukkan STARTING, tidak pernah menjadi RUNNING. Log mungkin menampilkan:

Penyebab: OpenClaw membutuhkan waktu startup yang cukup lama (terkadang lebih dari 60 detik), startup probe default mungkin terlalu cepat. Penyebab umum lainnya adalah file konfigurasi rusak (sama seperti Masalah 1).

Solusi:

1. Tunggu beberapa menit hingga inisialisasi selesai
2. Jika terus gagal, periksa log apakah ada error terkait config
3. Pastikan memori minimal 4GB
4. Jika log menunjukkan config invalid, tangani dengan Mode Penyelamatan

---

Masalah 3: Sudah terhubung ke AI Hub tapi bot tidak merespons

Gejala: Mengirim pesan ke bot di Telegram, bot menunjukkan typing tapi tidak pernah membalas, atau sama sekali tidak bereaksi.

Penyebab: Biasanya masalah pengaturan API Key, atau koneksi model gagal. Kesalahan paling umum yang kami temui adalah Key dan Provider tidak cocok.

Solusi:

1. Pastikan variabel lingkungan diatur dengan benar:

   • ZEABUR_AI_HUB_API_KEY — saat menggunakan Zeabur AI Hub
   • ANTHROPIC_API_KEY — saat menggunakan Claude secara langsung
   • OPENAI_API_KEY — saat menggunakan OpenAI (juga digunakan untuk Memory Search dan TTS)

2. Buka Web UI untuk memeriksa pengaturan model, pastikan model yang dipilih cocok dengan API Key Anda

3. Setelah mengatur variabel lingkungan, ingat untuk restart layanan, jika tidak perubahan tidak akan berlaku

Kesalahan umum: Sudah mengatur AI Hub Key tapi OpenClaw secara default mencoba terhubung ke Anthropic, menyebabkan No API key found for provider "anthropic". Pastikan pengaturan Provider sesuai dengan Key Anda.

---

Masalah 4: Ingin mengganti model, tidak tahu cara mengaturnya

Gejala: Model default kurang memuaskan, ingin beralih ke Claude Sonnet atau model lainnya.

Solusi:

1. Masuk ke OpenClaw Web UI (temukan tautan Web UI (with token) dari tab Instruksi di Zeabur Dashboard)
2. Buka halaman Config
3. Di pengaturan model, pilih model yang Anda inginkan

Jika menggunakan Zeabur AI Hub, Anda bisa beralih antara berbagai model dengan satu Key:

• claude-sonnet-4-6 — Direkomendasikan, seimbang antara kualitas dan kecepatan
• claude-haiku-4-5 — Lebih cepat, lebih murah
• gpt-5-mini — Pilihan OpenAI

Ingin menggunakan Provider lain? Tambahkan API Key yang sesuai di tab Variabel Lingkungan, lalu restart layanan untuk menggunakannya:

Untuk Provider lainnya, silakan lihat dokumentasi resmi OpenClaw.

---

Masalah 5: 502 SERVICE_UNAVAILABLE

Gejala: Membuka URL OpenClaw dan melihat error 502.

Penyebab: Ada tiga penyebab umum:

1. Layanan belum selesai startup (port belum ready)
2. Port di pengaturan jaringan Zeabur bukan port yang sebenarnya didengarkan OpenClaw (default 18789)
3. Setelah menghapus openclaw.json, OpenClaw kembali ke pengaturan default, bind menjadi loopback, koneksi dari luar tidak bisa masuk

Solusi:

1. Pastikan status layanan adalah RUNNING
2. Pastikan port yang diatur di tab Jaringan Zeabur Dashboard adalah 18789 (sesuai dengan variabel lingkungan OPENCLAW_GATEWAY_PORT)
3. Pastikan nilai variabel lingkungan OPENCLAW_GATEWAY_BIND adalah lan (template Zeabur secara default sudah mengaturnya, tapi bisa hilang jika pernah dihapus atau direset secara manual)
4. Jika baru saja mereset file konfigurasi, periksa juga gateway.bind di openclaw.json, pastikan nilainya lan bukan loopback
5. Tunggu beberapa menit agar routing berlaku
6. Jika 502 terus berlanjut, restart layanan

---

Masalah 6: Alat browser tidak bisa digunakan

Gejala: Meminta OpenClaw untuk mencari informasi di internet atau mengontrol browser, tapi dikatakan browser tidak aktif atau tidak bisa digunakan, lalu beralih menggunakan Web Fetch.

Penyebab: Di lingkungan container, headless Chrome memerlukan layanan sandbox tambahan agar bisa berfungsi. Hanya men-deploy OpenClaw tidak akan otomatis menyertakan browser.

Solusi:

Deploy template OpenClaw Sandbox Browser, yang akan otomatis mengonfigurasi headless Chrome. Setelah di-deploy, Anda perlu mengatur remote Profile di Config OpenClaw agar mengarah ke sandbox.

Untuk sekadar membaca konten halaman web (misalnya merangkum artikel), Web Fetch biasanya sudah cukup dan tidak selalu memerlukan kontrol browser penuh.

---

Masalah 7: Izin tidak cukup, tidak bisa menginstal paket

Gejala: Ingin bot menginstal pip, Homebrew, atau alat lainnya, tapi menampilkan error izin.

Penyebab: Container Docker Zeabur berjalan sebagai pengguna non-root (node), tidak bisa langsung menginstal paket tingkat sistem. Homebrew juga tidak tersedia di lingkungan container.

Solusi: Ini adalah keputusan desain — isolasi container melindungi keamanan data Anda. Alternatifnya:

• Gunakan sistem skill OpenClaw, banyak fungsi sudah memiliki skill bawaan (lebih dari 50)
• Jika memerlukan lingkungan pengembangan lengkap (pip, apt, dll.), Anda bisa men-deploy Zeabur Devbox sebagai sandbox OpenClaw, membiarkannya menjalankan perintah di dalamnya

---

Masalah 8: Gateway restart gagal

Gejala: Menjalankan openclaw gateway restart menampilkan:

Penyebab: Lingkungan container tidak memiliki systemd.

Solusi: Di Zeabur, Anda tidak perlu menggunakan openclaw gateway restart. Cukup buka Dashboard dan restart seluruh layanan.

---

Masalah 9: Tidak bisa menemukan file konfigurasi openclaw.json

Gejala: Ingin mengedit konfigurasi secara manual, tapi tidak tahu di mana filenya.

Solusi: File konfigurasi terletak di dalam container:

Anda bisa melihat dan mengeditnya melalui tab File atau Perintah di Zeabur Dashboard.

Namun disarankan untuk menggunakan halaman Config di Web UI terlebih dahulu untuk mengubah pengaturan, karena lebih tidak mudah merusak format JSON. Merusak JSON secara manual adalah salah satu penyebab umum Masalah 1 (crash).

---

Masalah 10: Cara yang benar untuk mengubah konfigurasi

Metode 1: Web UI (Direkomendasikan)

Gunakan halaman Settings → Config di Web UI untuk mengubah pengaturan. Ini akan membantu memvalidasi format, sehingga lebih tidak mudah merusak JSON.

Metode 2: Minta OpenClaw mengubahnya untuk Anda

Langsung beritahu OpenClaw di percakapan apa yang ingin Anda ubah, dan ia bisa membantu mengubah openclaw.json. Tapi perhatikan dua hal:

• Berikan konteks yang cukup — jelaskan dengan jelas apa yang ingin diubah dan menjadi apa, jangan hanya bilang "tolong ubah pengaturan"
• Gunakan model yang cukup mampu — model sederhana mungkin mengubah format dengan salah atau menambahkan field yang tidak ada, disarankan menggunakan claude-sonnet-4-6 atau gpt-5 ke atas untuk mengoperasikan pengaturan

Metode 3: Edit manual

1. Buka tab File atau Perintah di Zeabur Dashboard
2. Edit /home/node/.openclaw/openclaw.json
3. Setelah selesai mengedit, restart layanan

Perhatian: Apa pun metode yang digunakan, jangan menambahkan key yang tidak dikenali OpenClaw, jika tidak akan memicu crash seperti pada Masalah 1.

---

Masalah 11: Cara yang benar untuk upgrade OpenClaw

Cara yang benar:

1. Buka Zeabur Dashboard, masuk ke layanan OpenClaw
2. Di pengaturan layanan, ubah tag Docker image
3. Misalnya dari 2026.2.19 menjadi 2026.2.23
4. Setelah disimpan, layanan akan otomatis restart dan menggunakan versi baru

Saran sebelum upgrade: Buka halaman Config di Web UI terlebih dahulu dan ekspor cadangan pengaturan yang ada, untuk berjaga-jaga jika versi baru menghapus beberapa field pengaturan.

Setelah upgrade: Versi baru mungkin mengubah atau menghapus beberapa field pengaturan, menyebabkan error Unrecognized key saat startup yang membuat layanan crash. Jika layanan tidak bisa start setelah upgrade, lihat Masalah 1 dan Mode Penyelamatan.

Yang tidak boleh dilakukan:

• Jangan mengubah image menjadi selain ghcr.io/openclaw/openclaw
• Jangan menjalankan openclaw update atau npm i -g openclaw di dalam container — ini adalah cara upgrade untuk instalasi lokal, di Zeabur cukup ubah image tag saja
• Jangan gunakan tag latest — layanan akan menarik versi terbaru setiap kali restart, yang bisa meng-upgrade tanpa sepengetahuan Anda dan menyebabkan masalah. Gunakan nomor versi tetap (misalnya 2026.2.23) dan ubah secara manual saat perlu upgrade

---

Masalah 12: Pencadangan dan pemulihan

Zeabur memiliki fitur pencadangan bawaan yang bisa mencadangkan secara otomatis dan berkala, disarankan untuk mengaturnya terlebih dahulu. Berikut cara pencadangan manual.

Pencadangan manual:

Buka tab Perintah di Zeabur Dashboard dan jalankan:

File cadangan akan dihasilkan di /home/node/ (misalnya backup-1430.tar.gz), buka tab File, temukan filenya, dan klik tombol Download di sebelah kanan untuk menyimpannya ke komputer.

Jika versi lama tidak memiliki perintah backup:

Pemulihan:

1. Buka tab File, masuk ke /home/node/, klik tombol Upload di pojok kanan atas untuk mengunggah file cadangan
2. Buka tab Perintah dan jalankan:

3. Restart layanan

Jika file cadangan dihasilkan dari Zeabur Backup Service, tambahkan --strip 2:

Kapan harus mencadangkan: Setelah pengaturan awal selesai, sebelum upgrade, sebelum mengubah pengaturan besar-besaran.

---

Masalah 13: Telegram tidak bisa terhubung setelah upgrade 2026.2.17

Gejala: Setelah upgrade ke 2026.2.17 atau versi yang lebih baru, Telegram bot tidak bisa terhubung atau tidak merespons.

Penyebab: Versi 2026.2.17 mengubah perilaku default koneksi jaringan, yang pada beberapa lingkungan container menyebabkan kegagalan koneksi ke Telegram API.

Solusi:

Buka tab Variabel Lingkungan di Zeabur Dashboard, tambahkan:

Restart layanan dan masalah selesai.

---

Masalah 14: Log Telegram terus menampilkan 409 Conflict

Gejala: Log terus menampilkan error berikut, Telegram bot sama sekali tidak merespons:

Penyebab: Telegram Bot API memiliki dua cara untuk menerima pesan: Polling (mengambil secara aktif) dan Webhook (Telegram mendorong ke Anda). Keduanya saling eksklusif, tidak bisa digunakan bersamaan.

Error 409 ini berarti bot sebelumnya pernah diatur dengan webhook, tapi sekarang OpenClaw mencoba menerima pesan dengan cara polling, dan Telegram menolaknya. Penyebab umum:

• Sebelumnya ada layanan atau lingkungan lain yang mengatur webhook untuk bot ini
• Bot beralih kembali ke mode polling sebelum membersihkan webhook

Solusi:

Buka tab Perintah di Zeabur Dashboard, jalankan perintah berikut untuk membersihkan webhook (ganti <TOKEN> dengan token bot Anda):

Jika Anda melihat {"ok":true,"result":true} berarti pembersihan berhasil. Restart layanan dan bot akan bisa menerima pesan secara normal.

---

Masalah 15: Web UI tidak bisa dibuka setelah upgrade ke 2026.2.23

Gejala: Setelah upgrade ke 2026.2.23, Web UI menampilkan halaman kosong atau error CORS dan tidak bisa dimuat dengan benar.

Penyebab: Mulai dari 2026.2.23, Control UI memberlakukan pemeriksaan allowedOrigins. Di Zeabur, domain pengguna dihasilkan secara dinamis, sehingga Gateway tidak bisa secara otomatis menentukan origin mana yang sah, menyebabkan permintaan ditolak.

Solusi:

Buka tab File di Zeabur Dashboard, edit /home/node/.openclaw/openclaw.json, dan tambahkan berikut ini di bagian gateway.controlUi:

Restart layanan dan seharusnya berfungsi.

Jika layanan sudah crash dan tidak bisa diakses, gunakan Mode Penyelamatan untuk mengedit file konfigurasi.

---

Masih belum terselesaikan?

Jika semua cara di atas sudah dicoba tapi masih tidak berhasil:

1. Buka halaman log dan ambil screenshot pesan error
2. Buka Zeabur Forum dan buat tiket dukungan, sertakan screenshot

---

Jika ada kesalahan atau informasi yang sudah usang dalam artikel ini, silakan laporkan di Zeabur Forum.