Pemecahan Masalah

• model_not_found dengan server lokal bergaya MLX/vLLM → verifikasi baseUrl menyertakan /v1, api adalah "openai-completions" untuk backend /v1/chat/completions, dan models.providers.<provider>.models[].id adalah id lokal provider polos. Pilih dengan prefiks provider satu kali, misalnya mlx/mlx-community/Qwen3-30B-A3B-6bit; pertahankan entri katalog sebagai mlx-community/Qwen3-30B-A3B-6bit.
• messages[...].content: invalid type: sequence, expected a string → backend menolak bagian konten Chat Completions terstruktur. Perbaikan: tetapkan models.providers.<provider>.models[].compat.requiresStringContent: true.
• incomplete turn detected ... stopReason=stop payloads=0 → backend menyelesaikan permintaan Chat Completions tetapi tidak mengembalikan teks assistant yang terlihat pengguna untuk giliran tersebut. OpenClaw mencoba ulang giliran kosong yang kompatibel dengan OpenAI dan aman untuk diputar ulang satu kali; kegagalan persisten biasanya berarti backend mengeluarkan konten kosong/non-teks atau menyembunyikan teks jawaban akhir.
• permintaan langsung kecil berhasil, tetapi proses agent OpenClaw gagal dengan crash backend/model (misalnya Gemma pada beberapa build inferrs) → transport OpenClaw kemungkinan sudah benar; backend gagal pada bentuk prompt runtime agent yang lebih besar.
• kegagalan berkurang setelah menonaktifkan tools tetapi tidak hilang → skema tool merupakan bagian dari tekanan, tetapi masalah yang tersisa masih pada kapasitas model/server upstream atau bug backend.

1. Tetapkan compat.requiresStringContent: true untuk backend Chat Completions yang hanya menerima string.
2. Tetapkan compat.supportsTools: false untuk model/backend yang tidak dapat menangani permukaan skema tool OpenClaw dengan andal.
3. Kurangi tekanan prompt jika memungkinkan: bootstrap workspace yang lebih kecil, riwayat sesi yang lebih pendek, model lokal yang lebih ringan, atau backend dengan dukungan konteks panjang yang lebih kuat.
4. Jika permintaan langsung kecil tetap berhasil sementara giliran agent OpenClaw masih crash di dalam backend, perlakukan ini sebagai batasan server/model upstream dan ajukan repro di sana dengan bentuk payload yang diterima.

• device identity required → konteks tidak aman atau auth perangkat hilang.
• origin not allowed → Origin browser tidak ada di gateway.controlUi.allowedOrigins (atau Anda terhubung dari origin browser non-loopback tanpa allowlist eksplisit).
• device nonce required / device nonce mismatch → client tidak menyelesaikan alur auth perangkat berbasis challenge (connect.challenge + device.nonce).
• device signature invalid / device signature expired → client menandatangani payload yang salah (atau timestamp usang) untuk handshake saat ini.
• AUTH_TOKEN_MISMATCH dengan canRetryWithDeviceToken=true → client dapat melakukan satu percobaan ulang tepercaya dengan token perangkat yang di-cache.
• Percobaan ulang token yang di-cache itu menggunakan kembali kumpulan scope yang di-cache dan disimpan bersama token perangkat yang dipairing. Pemanggil deviceToken eksplisit / scopes eksplisit tetap menggunakan kumpulan scope yang dimintanya.
• Di luar jalur percobaan ulang tersebut, prioritas auth koneksi adalah token/password bersama eksplisit terlebih dahulu, lalu deviceToken eksplisit, lalu token perangkat tersimpan, lalu token bootstrap.
• Pada jalur UI Kontrol Tailscale Serve asinkron, percobaan gagal untuk {scope, ip} yang sama diserialisasi sebelum limiter mencatat kegagalan. Karena itu, dua percobaan ulang buruk yang bersamaan dari client yang sama dapat memunculkan retry later pada percobaan kedua, bukan dua ketidakcocokan biasa.
• too many failed authentication attempts (retry later) dari client loopback origin browser → kegagalan berulang dari Origin ternormalisasi yang sama dikunci sementara; origin localhost lain menggunakan bucket terpisah.
• unauthorized berulang setelah percobaan ulang tersebut → token bersama/token perangkat bergeser; segarkan konfigurasi token dan setujui ulang/rotasi token perangkat jika diperlukan.
• gateway connect failed: → target host/port/url salah.

• Gateway start blocked: set gateway.mode=local atau existing config is missing gateway.mode → mode Gateway lokal tidak diaktifkan, atau file konfigurasi tertimpa dan kehilangan gateway.mode. Perbaikan: atur gateway.mode="local" dalam konfigurasi Anda, atau jalankan ulang openclaw onboard --mode local / openclaw setup untuk membubuhkan kembali konfigurasi mode lokal yang diharapkan. Jika Anda menjalankan OpenClaw melalui Podman, jalur konfigurasi default adalah ~/.openclaw/openclaw.json.
• refusing to bind gateway ... without auth → bind non-loopback tanpa jalur auth Gateway yang valid (token/kata sandi, atau trusted-proxy jika dikonfigurasi).
• another gateway instance is already listening / EADDRINUSE → konflik port.
• Other gateway-like services detected (best effort) → unit launchd/systemd/schtasks usang atau paralel ada. Sebagian besar penyiapan sebaiknya mempertahankan satu Gateway per mesin; jika Anda memang memerlukan lebih dari satu, isolasikan port + konfigurasi/status/ruang kerja. Lihat /gateway#multiple-gateways-same-host.
• System-level OpenClaw gateway service detected dari doctor → unit sistem systemd ada sementara layanan tingkat pengguna tidak ada. Hapus atau nonaktifkan duplikat sebelum mengizinkan doctor memasang layanan pengguna, atau atur OPENCLAW_SERVICE_REPAIR_POLICY=external jika unit sistem adalah supervisor yang dimaksudkan.
• Gateway service port does not match current gateway config → supervisor terpasang masih mengunci --port lama. Jalankan openclaw doctor --fix atau openclaw gateway install --force, lalu mulai ulang layanan Gateway.

• Konfigurasi tidak lolos validasi saat startup, hot reload, atau penulisan yang dimiliki OpenClaw.
• Startup Gateway gagal tertutup alih-alih menulis ulang openclaw.json.
• Hot reload melewati edit eksternal yang tidak valid dan mempertahankan konfigurasi runtime saat ini tetap aktif.
• Penulisan yang dimiliki OpenClaw menolak payload tidak valid/destruktif sebelum commit dan menyimpan .rejected.*.
• openclaw doctor --fix memiliki perbaikan. Ini dapat menghapus prefiks non-JSON atau memulihkan salinan terakhir yang diketahui baik sambil mempertahankan payload yang ditolak sebagai .clobbered.*.

CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
openclaw config validate
openclaw doctor

• .clobbered.* ada → doctor mempertahankan edit eksternal yang rusak saat memperbaiki konfigurasi aktif.
• .rejected.* ada → penulisan konfigurasi yang dimiliki OpenClaw gagal pada pemeriksaan skema atau clobber sebelum commit.
• Config write rejected: → penulisan mencoba menghapus bentuk yang diperlukan, mengecilkan file secara tajam, atau mempertahankan konfigurasi tidak valid.
• config reload skipped (invalid config): → edit langsung gagal validasi dan diabaikan oleh Gateway yang sedang berjalan.
• Invalid config at ... → startup gagal sebelum layanan Gateway boot.
• missing-meta-vs-last-good, gateway-mode-missing-vs-last-good, atau size-drop-vs-last-good:* → penulisan yang dimiliki OpenClaw ditolak karena kehilangan field atau ukuran dibandingkan cadangan terakhir yang diketahui baik.
• Config last-known-good promotion skipped → kandidat berisi placeholder rahasia yang disunting seperti ***.

1. Jalankan openclaw doctor --fix agar doctor memperbaiki konfigurasi berprefiks/tertindih atau memulihkan terakhir yang diketahui baik.
2. Salin hanya kunci yang dimaksud dari .clobbered.* atau .rejected.*, lalu terapkan dengan openclaw config set atau config.patch.
3. Jalankan openclaw config validate sebelum memulai ulang.
4. Jika Anda mengedit manual, pertahankan konfigurasi JSON5 penuh, bukan hanya objek parsial yang ingin Anda ubah.

• cron: scheduler disabled; jobs will not run automatically → Cron dinonaktifkan.
• cron: timer tick failed → tick scheduler gagal; periksa kesalahan file/log/runtime.
• heartbeat skipped dengan reason=quiet-hours → di luar jendela jam aktif.
• heartbeat skipped dengan reason=empty-heartbeat-file → HEARTBEAT.md ada tetapi hanya berisi baris kosong / header markdown, sehingga OpenClaw melewati pemanggilan model.
• heartbeat skipped dengan reason=no-tasks-due → HEARTBEAT.md berisi blok tasks:, tetapi tidak ada tugas yang jatuh tempo pada tick ini.
• heartbeat: unknown accountId → id akun tidak valid untuk target pengiriman Heartbeat.
• heartbeat skipped dengan reason=dm-blocked → target Heartbeat diselesaikan ke tujuan bergaya DM sementara agents.defaults.heartbeat.directPolicy (atau override per agen) diatur ke block.

• unknown command "browser" atau unknown command 'browser' → Plugin browser bawaan dikecualikan oleh plugins.allow.
• alat browser hilang / tidak tersedia saat browser.enabled=true → plugins.allow mengecualikan browser, sehingga Plugin tidak pernah dimuat.
• Failed to start Chrome CDP on port → proses browser gagal diluncurkan.
• browser.executablePath not found → path yang dikonfigurasi tidak valid.
• browser.cdpUrl must be http(s) or ws(s) → URL CDP yang dikonfigurasi menggunakan skema yang tidak didukung seperti file: atau ftp:.
• browser.cdpUrl has invalid port → URL CDP yang dikonfigurasi memiliki port yang buruk atau di luar rentang.
• Playwright is not available in this gateway build; '<feature>' is unsupported. → instalasi Gateway saat ini tidak memiliki dependensi runtime browser inti; instal ulang atau perbarui OpenClaw, lalu mulai ulang Gateway. Snapshot ARIA dan tangkapan layar halaman dasar masih dapat berfungsi, tetapi navigasi, snapshot AI, tangkapan layar elemen selector CSS, dan ekspor PDF tetap tidak tersedia.

• Could not find DevToolsActivePort for chrome → existing-session Chrome MCP belum dapat melampirkan ke direktori data browser yang dipilih. Buka halaman inspect browser, aktifkan remote debugging, biarkan browser tetap terbuka, setujui prompt attach pertama, lalu coba lagi. Jika status masuk tidak diperlukan, pilih profil openclaw yang dikelola.
• No Chrome tabs found for profile="user" → profil attach Chrome MCP tidak memiliki tab Chrome lokal yang terbuka.
• Remote CDP for profile "<name>" is not reachable → endpoint CDP jarak jauh yang dikonfigurasi tidak dapat dijangkau dari host Gateway.
• Browser attachOnly is enabled ... not reachable atau Browser attachOnly is enabled and CDP websocket ... is not reachable → profil attach-only tidak memiliki target yang dapat dijangkau, atau endpoint HTTP merespons tetapi WebSocket CDP tetap tidak dapat dibuka.

• fullPage is not supported for element screenshots → permintaan tangkapan layar mencampur --full-page dengan --ref atau --element.
• element screenshots are not supported for existing-session profiles; use ref from snapshot. → panggilan tangkapan layar Chrome MCP / existing-session harus menggunakan capture halaman atau --ref snapshot, bukan CSS --element.
• existing-session file uploads do not support element selectors; use ref/inputRef. → hook unggahan Chrome MCP memerlukan ref snapshot, bukan selector CSS.
• existing-session file uploads currently support one file at a time. → kirim satu unggahan per panggilan pada profil Chrome MCP.
• existing-session dialog handling does not support timeoutMs. → hook dialog pada profil Chrome MCP tidak mendukung override timeout.
• existing-session type does not support timeoutMs overrides. → hilangkan timeoutMs untuk act:type pada profil profile="user" / existing-session Chrome MCP, atau gunakan profil browser terkelola/CDP saat timeout kustom diperlukan.
• existing-session evaluate does not support timeoutMs overrides. → hilangkan timeoutMs untuk act:evaluate pada profil profile="user" / existing-session Chrome MCP, atau gunakan profil browser terkelola/CDP saat timeout kustom diperlukan.
• response body is not supported for existing-session profiles yet. → responsebody masih memerlukan browser terkelola atau profil CDP mentah.
• override viewport / mode gelap / locale / offline yang kedaluwarsa pada profil attach-only atau CDP jarak jauh → jalankan openclaw browser stop --browser-profile <name> untuk menutup sesi kontrol aktif dan melepas status emulasi Playwright/CDP tanpa memulai ulang seluruh Gateway.

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

Yang perlu diperiksa:

• Jika gateway.mode=remote, panggilan CLI mungkin menargetkan remote sementara layanan lokal Anda baik-baik saja.
• Panggilan eksplisit --url tidak fallback ke kredensial tersimpan.

Signature umum:

• gateway connect failed: → target URL salah.
• unauthorized → endpoint dapat dijangkau tetapi autentikasi salah.

openclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

Yang perlu diperiksa:

• Bind non-loopback (lan, tailnet, custom) memerlukan jalur autentikasi Gateway yang valid: autentikasi token/kata sandi bersama, atau deployment trusted-proxy non-loopback yang dikonfigurasi dengan benar.
• Kunci lama seperti gateway.token tidak menggantikan gateway.auth.token.

Signature umum:

• refusing to bind gateway ... without auth → bind non-loopback tanpa jalur autentikasi Gateway yang valid.
• Connectivity probe: failed sementara runtime sedang berjalan → Gateway hidup tetapi tidak dapat diakses dengan auth/url saat ini.

openclaw devices list
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
openclaw doctor

Yang perlu diperiksa:

• Persetujuan perangkat tertunda untuk dashboard/Node.
• Persetujuan pairing DM tertunda setelah perubahan kebijakan atau identitas.

Signature umum:

• device identity required → autentikasi perangkat belum terpenuhi.
• pairing required → pengirim/perangkat harus disetujui.