# Pemecahan Masalah OpenClaw di Zeabur

> Solusi yang disusun dari catatan layanan pelanggan nyata, agar Anda bisa menyelesaikannya sendiri dalam lima menit.

<AIHubShutdownNotice />

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?

| Gejala | Lihat |
|---|---|
| Layanan menunjukkan CRASHED, terus restart | [Masalah 1](#p1) |
| Layanan terjebak di STARTING, tidak pernah menjadi RUNNING | [Masalah 2](#p2) |
| Telegram bot menunjukkan typing tapi tidak membalas | [Masalah 3](#p3) |
| Ingin mengganti model tapi tidak tahu cara mengaturnya | [Masalah 4](#p4) |
| Membuka URL dan melihat error 502 | [Masalah 5](#p5) |
| Alat browser dikatakan tidak aktif | [Masalah 6](#p6) |
| Menginstal paket menunjukkan error izin | [Masalah 7](#p7) |
| `openclaw gateway restart` error | [Masalah 8](#p8) |
| Tidak tahu di mana file konfigurasi | [Masalah 9](#p9) |
| Crash setelah mengedit konfigurasi secara manual | [Masalah 10](#p10) |
| Ingin upgrade OpenClaw | [Masalah 11](#p11) |
| Masalah setelah upgrade | [Masalah 11](#p11) |
| Ingin mencadangkan atau memulihkan data | [Masalah 12](#p12) |
| Telegram tidak bisa terhubung setelah upgrade 2026.2.17 | [Masalah 13](#p13) |
| Log Telegram menunjukkan `409: Conflict` | [Masalah 14](#p14) |
| Web UI tidak bisa dibuka setelah upgrade ke 2026.2.23 | [Masalah 15](#p15) |
| Log menunjukkan `Unrecognized key` | [Masalah 1](#p1) + [Mode Penyelamatan](#rescue) |
| `No API key found for provider` | [Masalah 3](#p3) |
| `connection refused on port 18789` | [Masalah 2](#p2) |
| `systemctl ENOENT` | [Masalah 8](#p8) |

---

<div id="rescue" />

## 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](https://zeabur.com/id-ID/templates/VTZ4FX).

---

<div id="p1" />

## 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:

```
Invalid config at /home/node/.openclaw/openclaw.json:
- gateway: Unrecognized key: "cool"

◇  Unknown config keys ─╮
│                       │
│  - gateway.cool       │
│                       │
├───────────────────────╯

◇  Doctor ────────────────────────────────────────────╮
│                                                     │
│  Run "openclaw doctor --fix" to remove these keys.  │
│                                                     │
├─────────────────────────────────────────────────────╯
Config invalid
File: ~/.openclaw/openclaw.json
Problem:
  - gateway: Unrecognized key: "cool"

Run: openclaw doctor --fix
```

**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**](#rescue) 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.

---

<div id="p2" />

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

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

```
Startup probe failed: dial tcp 10.0.5.87:18789: connect: connection refused
```

**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**

---

<div id="p3" />

## 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.

---

<div id="p4" />

## 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:

| Provider | Variabel Lingkungan |
|---|---|
| Zeabur AI Hub | `ZEABUR_AI_HUB_API_KEY` |
| OpenAI | `OPENAI_API_KEY` |
| Anthropic | `ANTHROPIC_API_KEY` |
| Google Gemini | `GEMINI_API_KEY` |
| xAI (Grok) | `XAI_API_KEY` |
| Mistral | `MISTRAL_API_KEY` |
| OpenRouter | `OPENROUTER_API_KEY` |
| Groq | `GROQ_API_KEY` |
| Moonshot (Kimi) | `MOONSHOT_API_KEY` |
| Z.AI (GLM) | `ZAI_API_KEY` |

Untuk Provider lainnya, silakan lihat [dokumentasi resmi OpenClaw](https://docs.openclaw.ai/providers).

---

<div id="p5" />

## 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

---

<div id="p6" />

## 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.

<TemplateCTA
  code="H8L4G1"
  title="Deploy Sandbox Browser"
  description="Tambahkan kemampuan kontrol browser ke OpenClaw."
  buttonText="Deploy Sekali Klik"
/>

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

---

<div id="p7" />

## 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

<TemplateCTA
  code="ZBVZNH"
  title="Deploy Devbox"
  description="Tambahkan lingkungan pengembangan lengkap ke OpenClaw."
  buttonText="Deploy Sekali Klik"
/>

---

<div id="p8" />

## Masalah 8: Gateway restart gagal

**Gejala:** Menjalankan `openclaw gateway restart` menampilkan:

```
Gateway service check failed: Error: systemctl --user unavailable: spawn systemctl ENOENT
```

**Penyebab:** Lingkungan container tidak memiliki systemd.

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

---

<div id="p9" />

## 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:

```
/home/node/.openclaw/openclaw.json
```

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).

---

<div id="p10" />

## 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.

---

<div id="p11" />

## 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](#p1) dan [Mode Penyelamatan](#rescue).

**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

---

<div id="p12" />

## Masalah 12: Pencadangan dan pemulihan

Zeabur memiliki [fitur pencadangan](https://zeabur.com/docs/data-management/backup) 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:

```
backup
```

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`:

```
cd /home/node && tar -czvf backup.tar.gz .openclaw
```

**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:

```
restore backup-1430.tar.gz
```

3. **Restart layanan**

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

```
restore backup-xxxxx.tar.gz --strip 2
```

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

---

<div id="p13" />

## 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:

```
OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=true
```

**Restart layanan** dan masalah selesai.

---

<div id="p14" />

## Masalah 14: Log Telegram terus menampilkan 409 Conflict

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

```
[telegram] getUpdates conflict: Call to 'getUpdates' failed! (409: Conflict: terminated by other getUpdates request; make sure that only one bot instance is running)
```

**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):

```
curl https://api.telegram.org/bot<TOKEN>/deleteWebhook
```

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

---

<div id="p15" />

## 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`:

```json
{
  "gateway": {
    "controlUi": {
      "dangerouslyAllowHostHeaderOriginFallback": true
    }
  }
}
```

**Restart layanan** dan seharusnya berfungsi.

Jika layanan sudah crash dan tidak bisa diakses, gunakan [**Mode Penyelamatan**](#rescue) 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](https://zeabur.com/forum) dan buat tiket dukungan, sertakan screenshot

---

Jika ada kesalahan atau informasi yang sudah usang dalam artikel ini, silakan laporkan di [Zeabur Forum](https://zeabur.com/forum).