Pemecahan Masalah

Ini adalah panduan operasional mendalam. Mulailah dari /help/troubleshooting untuk mengikuti alur triase cepat terlebih dahulu.

Urutan perintah

Jalankan dalam urutan berikut:

openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

Indikator kondisi sehat:

• openclaw gateway status menampilkan Runtime: running, Connectivity probe: ok, dan baris Capability: ....
• openclaw doctor melaporkan tidak ada masalah konfigurasi/layanan yang menghambat.
• openclaw channels status --probe menampilkan status transportasi langsung per akun dan, jika didukung, works atau audit ok.

Setelah pembaruan

Gunakan ketika pembaruan selesai, tetapi Gateway tidak aktif, channel kosong, atau panggilan model gagal dengan 401.

openclaw status --allopenclaw update status --jsonopenclaw gateway status --deepopenclaw doctor --fixopenclaw gateway restart

Periksa:

• Update restart dalam openclaw status / openclaw status --all. Serah terima yang tertunda atau gagal menyertakan perintah berikutnya yang harus dijalankan.
• plugin load failed: dependency tree corrupted; run openclaw doctor --fix pada Channels: konfigurasi channel masih ada, tetapi pendaftaran plugin gagal sebelum channel dapat dimuat.
• 401 dari penyedia setelah autentikasi ulang: openclaw doctor --fix memeriksa bayangan autentikasi OAuth per agen yang sudah usang dan menghapus salinan lama agar semua agen menggunakan profil bersama saat ini.

Instalasi yang tidak sinkron dan perlindungan konfigurasi yang lebih baru

Gunakan ketika layanan Gateway berhenti secara tidak terduga setelah pembaruan, atau log menunjukkan bahwa satu biner openclaw lebih lama daripada versi yang terakhir menulis openclaw.json.

OpenClaw menandai penulisan konfigurasi dengan meta.lastTouchedVersion. Perintah hanya-baca dapat memeriksa konfigurasi yang ditulis oleh OpenClaw versi lebih baru, tetapi mutasi proses dan layanan tidak dapat dijalankan dari biner yang lebih lama. Tindakan yang diblokir: memulai/menghentikan/memulai ulang/menghapus instalasi layanan Gateway, instalasi ulang layanan secara paksa, memulai Gateway dalam mode layanan, dan pembersihan port gateway --force.

which openclawopenclaw --versionopenclaw gateway status --deepopenclaw config get meta.lastTouchedVersion

openclaw gateway install --forceopenclaw gateway restart

Ketidakcocokan protokol setelah rollback

Gunakan ketika log terus menampilkan protocol mismatch setelah penurunan versi atau rollback. Gateway yang lebih lama sedang berjalan, tetapi proses klien lokal yang lebih baru masih mencoba menyambung kembali dengan rentang protokol yang tidak didukung oleh Gateway lama.

openclaw --versionwhich -a openclawopenclaw gateway status --deepopenclaw doctor --deepopenclaw logs --follow

Periksa:

• protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n> dalam log Gateway.
• Established clients: dalam openclaw gateway status --deep atau Gateway clients dalam openclaw doctor --deep: klien TCP aktif yang terhubung ke port Gateway, beserta PID dan baris perintah jika diizinkan oleh OS.
• Proses klien dengan baris perintah yang mengarah ke instalasi atau wrapper OpenClaw lebih baru yang menjadi asal rollback.

Perbaikan:

1. Hentikan atau mulai ulang proses klien OpenClaw usang yang ditampilkan oleh gateway status --deep.
2. Mulai ulang aplikasi atau wrapper yang menyematkan OpenClaw: dasbor lokal, editor, pembantu server aplikasi, atau shell openclaw logs --follow yang berjalan lama.
3. Jalankan kembali openclaw gateway status --deep atau openclaw doctor --deep dan pastikan PID klien usang sudah tidak ada.

Jangan membuat Gateway lama menerima protokol baru yang tidak kompatibel. Peningkatan versi protokol melindungi kontrak komunikasi; pemulihan rollback merupakan masalah pembersihan proses/versi.

Symlink Skills dilewati karena keluar dari jalur

Gunakan ketika log mencakup:

Melewati jalur Skills yang keluar dari root yang dikonfigurasi: ... reason=symlink-escape

Setiap root Skills merupakan batas penampungan. Symlink di bawah ~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills, atau ~/.openclaw/skills dilewati jika target sebenarnya mengarah ke luar root tersebut, kecuali target secara eksplisit dipercaya.

Periksa tautan:

ls -l ~/.agents/skills/<name>realpath ~/.agents/skills/<name>openclaw config get skills.load

Jika target memang disengaja, konfigurasikan root Skills langsung dan target symlink yang diizinkan:

{  skills: {    load: {      extraDirs: ["~/Projects/manager/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],    },  },}

Kemudian mulai sesi baru atau tunggu pemantau Skills dimuat ulang. Mulai ulang Gateway jika proses yang sedang berjalan dimulai sebelum perubahan konfigurasi.

Jangan gunakan target luas seperti ~, /, atau seluruh folder proyek yang disinkronkan. Batasi cakupan allowSymlinkTargets pada root Skills sebenarnya yang berisi direktori SKILL.md tepercaya.

Jika penerapan Skill Workshop juga harus menulis melalui jalur Skills ruang kerja bersymlink yang tepercaya tersebut, aktifkan skills.workshop.allowSymlinkTargetWrites. Biarkan tetap dinonaktifkan untuk root Skills bersama yang hanya-baca.

Terkait:

• Konfigurasi Skills
• Contoh konfigurasi

Penggunaan tambahan Anthropic 429 diperlukan untuk konteks panjang

Gunakan ketika log/kesalahan mencakup: HTTP 429: rate_limit_error: Extra usage is required for long context requests.

openclaw logs --followopenclaw models statusopenclaw config get agents.defaults.models

Periksa:

• Model Anthropic yang dipilih adalah model Claude 4.x 1M yang mendukung GA (Opus 4.6/4.7/4.8, Sonnet 4.6), atau konfigurasi model masih memuat params.context1m: true lama.
• Kredensial Anthropic saat ini tidak memenuhi syarat untuk penggunaan konteks panjang.
• Permintaan hanya gagal pada sesi panjang/eksekusi model yang memerlukan jalur konteks 1M.

Opsi perbaikan:

Terkait:

• Anthropic
• Penggunaan dan biaya token
• Mengapa saya melihat HTTP 429 dari Anthropic?

Respons 403 yang diblokir upstream

Gunakan ketika penyedia LLM upstream mengembalikan 403 generik seperti Your request was blocked.

Jangan berasumsi bahwa hal ini selalu merupakan masalah konfigurasi OpenClaw. Respons dapat berasal dari lapisan keamanan upstream seperti CDN, WAF, aturan pengelolaan bot, atau proksi terbalik di depan endpoint yang kompatibel dengan OpenAI.

openclaw statusopenclaw gateway statusopenclaw logs --follow

Periksa:

• Beberapa model dari penyedia yang sama gagal dengan cara yang sama.
• HTML atau teks keamanan generik, bukan kesalahan API penyedia normal.
• Peristiwa keamanan di sisi penyedia untuk waktu permintaan yang sama.
• Probe langsung curl yang sangat kecil berhasil, sedangkan permintaan normal berbentuk SDK gagal.

Perbaiki pemfilteran di sisi penyedia terlebih dahulu jika bukti mengarah pada pemblokiran WAF/CDN. Utamakan aturan pengizinan atau pelewatan yang dibatasi secara ketat untuk jalur API yang digunakan OpenClaw, dan hindari menonaktifkan perlindungan untuk seluruh situs.

Terkait:

• Endpoint yang kompatibel dengan OpenAI
• Konfigurasi penyedia
• Log

Backend lokal yang kompatibel dengan OpenAI lolos probe langsung, tetapi eksekusi agen gagal

Gunakan ketika:

• curl ... /v1/models berfungsi.
• Panggilan langsung /v1/chat/completions yang sangat kecil berfungsi.
• Eksekusi model OpenClaw hanya gagal pada giliran agen normal.

curl http://127.0.0.1:1234/v1/modelscurl http://127.0.0.1:1234/v1/chat/completions \  -H 'content-type: application/json' \  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'openclaw infer model run --model <provider/model> --prompt "hi" --jsonopenclaw logs --follow

Periksa:

• Panggilan langsung yang sangat kecil berhasil, tetapi eksekusi OpenClaw hanya gagal pada prompt yang lebih besar.
• Kesalahan model_not_found atau 404 meskipun /v1/chat/completions langsung berfungsi dengan ID model polos yang sama.
• Kesalahan backend tentang messages[].content yang mengharapkan string.
• Peringatan incomplete turn detected ... stopReason=stop payloads=0 berselang-seling dengan backend lokal yang kompatibel dengan OpenAI.
• Backend mengalami crash yang hanya muncul dengan jumlah token prompt lebih besar atau prompt runtime agen lengkap.

Terkait:

• Konfigurasi
• Model lokal
• Endpoint yang kompatibel dengan OpenAI

Tidak ada balasan

Jika saluran aktif tetapi tidak ada yang menjawab, periksa perutean dan kebijakan sebelum menyambungkan kembali apa pun.

openclaw statusopenclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw config get channelsopenclaw logs --follow

Cari:

• Pemasangan tertunda untuk pengirim DM.
• Pembatasan penyebutan grup (requireMention, mentionPatterns).
• Ketidakcocokan daftar yang diizinkan untuk saluran/grup.

Pola umum:

• drop guild message (mention required → pesan grup diabaikan hingga ada penyebutan.
• pairing request → pengirim memerlukan persetujuan.
• blocked / allowlist → pengirim/saluran difilter oleh kebijakan.

Terkait:

• Pemecahan masalah saluran
• Grup
• Pemasangan

Konektivitas UI kontrol dasbor

Jika dasbor/UI kontrol tidak dapat terhubung, validasi URL, mode autentikasi, dan asumsi konteks aman.

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --json

Cari:

• URL pemeriksaan dan URL dasbor yang benar.
• Ketidakcocokan mode autentikasi/token antara klien dan gateway.
• Penggunaan HTTP saat identitas perangkat diwajibkan.

Jika peramban lokal tidak dapat terhubung ke 127.0.0.1:18789 setelah pembaruan, pulihkan layanan Gateway lokal terlebih dahulu dan pastikan layanan tersebut menyajikan dasbor:

openclaw gateway restartlsof -i :18789curl http://127.0.0.1:18789

Jika curl mengembalikan HTML OpenClaw, Gateway berfungsi dan masalah yang tersisa kemungkinan adalah cache peramban, tautan dalam lama, atau status tab yang usang. Buka http://127.0.0.1:18789 secara langsung dan navigasikan dari dasbor. Jika layanan tidak tetap berjalan setelah dimulai ulang, jalankan openclaw gateway start dan periksa kembali openclaw gateway status.

Peta ringkas kode detail autentikasi

Gunakan error.details.code dari respons connect yang gagal untuk menentukan tindakan berikutnya:

Pemeriksaan migrasi autentikasi perangkat v2:

openclaw --versionopenclaw doctoropenclaw gateway status

Jika log menunjukkan kesalahan nonce/tanda tangan, perbarui klien yang terhubung dan verifikasi:

Jika openclaw devices rotate / revoke / remove ditolak secara tidak terduga:

• Sesi token perangkat terpasang hanya dapat mengelola perangkat miliknya sendiri, kecuali pemanggil juga memiliki operator.admin.
• openclaw devices rotate --scope ... hanya dapat meminta cakupan operator yang sudah dimiliki oleh sesi pemanggil.

Terkait:

• Konfigurasi (mode autentikasi gateway)
• UI Kontrol
• Perangkat
• Akses jarak jauh
• Autentikasi proksi tepercaya

Layanan Gateway tidak berjalan

Gunakan ketika layanan terpasang tetapi proses tidak tetap aktif.

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep   # juga pindai layanan tingkat sistem

Cari:

• Runtime: stopped dengan petunjuk keluar.
• Ketidakcocokan konfigurasi layanan (Config (cli) vs Config (service)).
• Konflik port/listener.
• Instalasi launchd/systemd/schtasks tambahan saat --deep digunakan.
• Petunjuk pembersihan Other gateway-like services detected (best effort).

Terkait:

• Eksekusi latar belakang dan alat proses
• Konfigurasi
• Doctor

Gateway macOS berhenti merespons tanpa pemberitahuan, lalu kembali merespons saat Anda menyentuh dasbor

Gunakan ketika channel (Telegram, WhatsApp, dll.) pada host macOS tidak merespons selama beberapa menit hingga beberapa jam, dan Gateway tampak kembali aktif begitu Anda membuka Control UI, masuk melalui SSH, atau berinteraksi dengan host dengan cara lain. Biasanya tidak ada gejala yang jelas di openclaw status karena saat Anda memeriksanya, Gateway sudah aktif kembali.

ls ~/.openclaw/logs/stability/ | tail -5openclaw gateway stability --bundle latestpmset -g log | grep -iE "sleep|wake|maintenance" | tail -50launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"

Periksa:

• Satu atau beberapa bundel *-uncaught_exception.json di ~/.openclaw/logs/stability/ dengan error.code yang ditetapkan ke kode jaringan sementara seperti ENETDOWN, ENETUNREACH, EHOSTUNREACH, atau ECONNREFUSED.
• Baris pmset -g log seperti Entering Sleep state due to 'Maintenance Sleep' atau en0 driver is slow (msg: WillChangeState to 0) yang waktunya selaras dengan stempel waktu crash. Power Nap / Maintenance Sleep secara singkat menempatkan driver Wi-Fi ke status 0; setiap connect() keluar yang terjadi dalam rentang waktu tersebut dapat gagal dengan ENETDOWN, bahkan pada host yang selain itu memiliki konektivitas jaringan penuh.
• Output launchctl print yang menampilkan state = not running dengan beberapa runs terbaru dan kode keluar, terutama ketika jeda antara crash dan peluncuran berikutnya sekitar satu jam, bukan beberapa detik. launchd macOS menerapkan gerbang perlindungan respawn yang tidak terdokumentasi setelah serangkaian crash, yang dapat berhenti mematuhi KeepAlive=true hingga pemicu eksternal seperti login interaktif, koneksi dasbor, atau launchctl kickstart mengaktifkannya kembali.

Pola umum:

• Bundel stabilitas dengan error.code berupa ENETDOWN atau kode sejenis, dengan tumpukan panggilan yang mengarah ke Node net lookupAndConnect / Socket.connect. OpenClaw 2026.5.26 dan yang lebih baru mengklasifikasikannya sebagai kesalahan jaringan sementara yang tidak berbahaya sehingga tidak lagi diteruskan ke handler uncaught tingkat atas; jika Anda menggunakan rilis yang lebih lama, lakukan upgrade terlebih dahulu.
• Periode hening yang panjang dan berakhir seketika saat Anda terhubung ke Control UI atau masuk ke host melalui SSH: aktivitas yang terlihat oleh pengguna itulah yang mengaktifkan kembali gerbang respawn launchd, bukan tindakan apa pun yang dilakukan dasbor terhadap Gateway.
• Jumlah runs bertambah sepanjang hari tanpa baris received SIG*; shutting down yang sesuai di ~/Library/Logs/openclaw/gateway.log: penghentian bersih mencatat sinyal; crash sementara tidak.

Yang harus dilakukan:

1. Upgrade Gateway jika Anda menjalankan rilis sebelum 2026.5.26. Setelah upgrade, kesalahan ENETDOWN berikutnya dicatat sebagai peringatan, bukan menghentikan proses.

2. Kurangi aktivitas maintenance sleep pada host Mac mini / desktop yang dimaksudkan untuk berjalan sebagai server yang selalu aktif:

   sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0

   Ini secara signifikan mengurangi, tetapi tidak sepenuhnya menghilangkan, gangguan driver yang mendasarinya. Sistem masih dapat menjalankan beberapa maintenance sleep untuk pemeliharaan TCP keepalive dan mDNS terlepas dari flag ini.

3. Tambahkan watchdog keaktifan agar serangkaian crash mendatang yang ditahan oleh launchd dapat dideteksi dengan cepat:

   # Contoh pemeriksaan keaktifan yang memahami launchd, cocok untuk cron atau LaunchAgent setiap 5 menitstate=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')if [ "$state" != "running" ]; then  launchctl kickstart -k gui/$UID/ai.openclaw.gatewayfi

   Tujuannya adalah mengaktifkan kembali gerbang respawn secara eksternal; KeepAlive=true saja tidak cukup di macOS setelah serangkaian crash.

Terkait:

• Catatan platform macOS
• Pencatatan log
• Doctor

Loop supervisor launchd macOS dengan LaunchAgent Gateway/Node duplikat

Gunakan ini ketika instalasi macOS terus dimulai ulang setiap beberapa detik, pemeriksaan kesehatan openclaw berganti-ganti antara sehat dan tidak tersedia, serta pengiriman channel terhenti meskipun layanan tampak berjalan.

Hal ini diamati pada instalasi lama ketika ai.openclaw.gateway dan ai.openclaw.node LaunchAgent sama-sama aktif dan masing-masing menyuntikkan OPENCLAW_LAUNCHD_LABEL. Dalam keadaan tersebut, OpenClaw dapat mendeteksi supervisi launchd, mencoba menyerahkan kembali proses mulai ulang kepada launchd, lalu masuk ke loop cepat EADDRINUSE/respawn alih-alih menjalankan satu proses Gateway yang stabil.

for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done openclaw gateway status --deepopenclaw node statuslaunchctl print gui/$UID/ai.openclaw.gateway | grep -E 'state|last exit|runs'tail -n 80 ~/Library/Logs/openclaw/gateway.log

Periksa:

• Lebih dari satu PID Gateway selama sampel 30 detik, bukan satu proses yang stabil.
• EADDRINUSE, another gateway instance is already listening, atau baris mulai ulang/serah-terima berulang di gateway.log.
• ~/Library/LaunchAgents/ai.openclaw.gateway.plist dan ~/Library/LaunchAgents/ai.openclaw.node.plist dimuat secara bersamaan pada host yang seharusnya hanya menjalankan satu layanan Gateway terkelola.

Yang harus dilakukan:

1. Jika host ini seharusnya hanya menjalankan layanan Gateway, hapus layanan Node terkelola melalui OpenClaw. Lewati langkah ini jika Anda secara aktif mengandalkan layanan Node untuk fitur Node jarak jauh; menghapus instalasinya akan menghentikan fitur tersebut pada host ini:

   openclaw node uninstall

2. Instal wrapper Gateway persisten yang menghapus penanda launchd yang diwariskan sebelum memulai OpenClaw. Gunakan opsi --wrapper yang didukung; jangan mengedit berkas yang dihasilkan di bawah ~/.openclaw/service-env/, karena instalasi ulang layanan, pembaruan, dan perbaikan Doctor akan membuat ulang berkas tersebut:

   mkdir -p ~/.local/bincat >~/.local/bin/openclaw-launchd-workaround <<'EOF'#!/bin/shset -euunset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || trueexec openclaw "$@"EOFchmod 700 ~/.local/bin/openclaw-launchd-workaround openclaw gateway install \  --wrapper ~/.local/bin/openclaw-launchd-workaround \  --force

   gateway install mempertahankan path wrapper saat instalasi ulang paksa, pembaruan, dan perbaikan Doctor.

3. Verifikasi bahwa Gateway stabil dan melayani RPC, bukan sekadar mendengarkan:

   openclaw gateway status --deep --require-rpc for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done

   Sampel PID seharusnya menampilkan satu proses stabil, bukan sekumpulan PID yang terus berganti, dan pengiriman channel masuk seharusnya berlanjut kembali.

4. Setelah melakukan upgrade ke rilis yang telah memperbaiki loop dua LaunchAgent yang mendasarinya, hapus solusi sementara dan instal ulang layanan terkelola normal:

   OPENCLAW_WRAPPER= openclaw gateway install --forcerm ~/.local/bin/openclaw-launchd-workaround

Terkait:

• Catatan platform macOS
• Doctor
• CLI Gateway

Gateway berhenti saat penggunaan memori tinggi

Gunakan ketika Gateway menghilang saat menerima beban, supervisor melaporkan mulai ulang bergaya OOM, atau log menyebutkan critical memory pressure bundle written.

openclaw gateway status --deepopenclaw logs --followopenclaw gateway stability --bundle latestopenclaw gateway diagnostics export

Periksa:

• Reason: diagnostic.memory.pressure.critical dalam bundel stabilitas terbaru.
• Memory pressure: dengan critical/rss_threshold, critical/heap_threshold, atau critical/rss_growth.
• Nilai V8 heap: mendekati batas heap.
• Entri Largest session files: seperti agents/<agent>/sessions/<session>.jsonl atau sessions/<session>.jsonl.
• Penghitung memori cgroup Linux ketika Gateway berjalan di dalam container atau layanan dengan batas memori.

Pola umum:

• critical memory pressure bundle written muncul sesaat sebelum mulai ulang → OpenClaw merekam bundel stabilitas pra-OOM. Periksa dengan openclaw gateway stability --bundle latest.
• memory pressure: level=critical muncul di log Gateway → OpenClaw mendeteksi tekanan memori kritis dan mencatat fakta memori dalam proses yang tersedia.
• Largest session files: mengarah ke path transkrip tersamarkan yang sangat besar → kurangi riwayat sesi yang dipertahankan, periksa pertumbuhan sesi, atau pindahkan transkrip lama keluar dari penyimpanan aktif sebelum memulai ulang.
• Byte V8 heap: yang digunakan mendekati batas heap → kurangi tekanan prompt/sesi atau pekerjaan bersamaan terlebih dahulu. Untuk layanan terkelola, periksa Gateway heap: di openclaw gateway status; jika tertulis not set, buat ulang metadata layanan lama dengan openclaw gateway install --force. NODE_OPTIONS shell sekitar sengaja diabaikan. Gunakan penggantian batas heap eksplisit pada tingkat supervisor hanya setelah memastikan beban kerja berkelanjutan dan menyisakan ruang memori native yang cukup.
• Memory pressure: critical/rss_growth → memori bertambah dengan cepat dalam satu rentang pengambilan sampel. Periksa log terbaru untuk impor besar, output alat yang tidak terkendali, percobaan ulang berulang, atau sekumpulan pekerjaan agen yang mengantre.
• Tekanan memori kritis muncul di log tetapi tidak ada bundel → rekam openclaw gateway diagnostics export setelah kejadian untuk mendapatkan bukti operasional yang tersedia.

Bundel stabilitas tidak berisi payload. Bundel ini mencakup bukti operasional memori dan path berkas relatif yang disamarkan, bukan teks pesan, isi Webhook, kredensial, token, cookie, atau ID sesi mentah. Lampirkan ekspor diagnostik ke laporan bug alih-alih menyalin log mentah.

Terkait:

• Kesehatan Gateway
• Ekspor diagnostik
• Sesi

Gateway menolak konfigurasi yang tidak valid

Gunakan ketika startup Gateway gagal dengan Invalid config atau log hot reload menyatakan bahwa pengeditan yang tidak valid dilewati.

openclaw logs --followopenclaw config fileopenclaw config validateopenclaw doctor

Periksa:

• Invalid config at ...
• config reload skipped (invalid config): ...
• Config write rejected: ...
• Berkas openclaw.json.rejected.* berstempel waktu di samping konfigurasi aktif.
• Berkas openclaw.json.clobbered.* berstempel waktu jika doctor --fix memperbaiki pengeditan langsung yang rusak.
• OpenClaw menyimpan 32 berkas .clobbered.* terbaru untuk setiap path konfigurasi dan merotasi berkas yang lebih lama.

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

Terkait:

• Konfigurasi
• Konfigurasi: muat ulang langsung
• Konfigurasi: validasi ketat
• Doctor

Peringatan pemeriksaan Gateway

Gunakan ketika openclaw gateway probe berhasil menjangkau sesuatu, tetapi masih mencetak blok peringatan.

openclaw gateway probeopenclaw gateway probe --jsonopenclaw gateway probe --ssh user@gateway-host

Cari:

• warnings[].code dan primaryTargetId dalam keluaran JSON.
• Apakah peringatan berkaitan dengan fallback SSH, beberapa gateway, cakupan yang tidak ada, atau referensi autentikasi yang belum terselesaikan.

Pola umum:

• SSH tunnel failed to start; falling back to direct probes. → penyiapan SSH gagal, tetapi perintah masih mencoba target langsung yang dikonfigurasi/loopback.
• multiple reachable gateway identities detected → beberapa gateway yang berbeda merespons, atau OpenClaw tidak dapat membuktikan bahwa target yang dapat dijangkau adalah gateway yang sama. Terowongan SSH, URL proksi, atau URL jarak jauh yang dikonfigurasi ke gateway yang sama diperlakukan sebagai satu gateway dengan beberapa transportasi, bahkan ketika port transportasi berbeda.
• Read-probe diagnostics are limited by gateway scopes (missing operator.read) → koneksi berhasil, tetapi RPC detail dibatasi oleh cakupan; pasangkan identitas perangkat atau gunakan kredensial dengan operator.read.
• Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → koneksi berhasil, tetapi rangkaian lengkap RPC diagnostik kehabisan waktu atau gagal. Perlakukan ini sebagai Gateway yang dapat dijangkau dengan diagnostik yang menurun; bandingkan connect.ok dan connect.rpcOk dalam keluaran --json.
• Capability: pairing-pending atau gateway closed (1008): pairing required → gateway merespons, tetapi klien ini masih memerlukan pemasangan/persetujuan sebelum akses operator normal.
• Teks peringatan SecretRef gateway.auth.* / gateway.remote.* yang belum terselesaikan → materi autentikasi tidak tersedia dalam jalur perintah ini untuk target yang gagal.

Terkait:

• Gateway
• Beberapa gateway pada host yang sama
• Akses jarak jauh

Kanal terhubung, pesan tidak mengalir

Jika status kanal terhubung tetapi aliran pesan terhenti, fokuslah pada kebijakan, izin, dan aturan pengiriman khusus kanal.

openclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw status --deepopenclaw logs --followopenclaw config get channels

Cari:

• Kebijakan DM (pairing, allowlist, open, disabled).
• Daftar yang diizinkan untuk grup dan persyaratan penyebutan.
• Izin/cakupan API kanal yang tidak ada.

Pola umum:

• mention required → pesan diabaikan oleh kebijakan penyebutan grup.
• pairing / jejak persetujuan tertunda → pengirim belum disetujui.
• missing_scope, not_in_channel, Forbidden, 401/403 → masalah autentikasi/izin kanal.

Terkait:

• Pemecahan masalah kanal
• Discord
• Telegram
• WhatsApp

Pengiriman Cron dan Heartbeat

Jika Cron atau Heartbeat tidak berjalan atau tidak mengirim, verifikasi status penjadwal terlebih dahulu, lalu target pengiriman.

openclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --follow

Cari:

• Cron diaktifkan dan waktu bangun berikutnya tersedia.
• Status riwayat eksekusi tugas (ok, skipped, error).
• Alasan Heartbeat dilewati (quiet-hours, requests-in-flight, cron-in-progress, lanes-busy, alerts-disabled, empty-heartbeat-file, no-tasks-due).

Terkait:

• Heartbeat
• Tugas terjadwal
• Tugas terjadwal: pemecahan masalah

Node terpasang, alat gagal

Jika Node telah dipasangkan tetapi alat gagal, pisahkan status latar depan, izin, dan persetujuan.

openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw approvals get --node <idOrNameOrIp>openclaw logs --followopenclaw status

Cari:

• Node daring dengan kemampuan yang diharapkan.
• Pemberian izin OS untuk kamera/mikrofon/lokasi/layar.
• Persetujuan eksekusi dan status daftar yang diizinkan.

Pola umum:

• NODE_BACKGROUND_UNAVAILABLE → aplikasi Node harus berada di latar depan.
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → izin OS tidak ada.
• SYSTEM_RUN_DENIED: approval required → persetujuan eksekusi tertunda.
• SYSTEM_RUN_DENIED: allowlist miss → perintah diblokir oleh daftar yang diizinkan.

Terkait:

• Persetujuan eksekusi
• Pemecahan masalah Node
• Node

Alat peramban gagal

Gunakan ketika tindakan alat peramban gagal meskipun gateway itu sendiri sehat.

openclaw browser statusopenclaw browser start --browser-profile openclawopenclaw browser profilesopenclaw logs --followopenclaw doctor

Cari:

• Apakah plugins.allow diatur dan menyertakan browser.
• Jalur berkas eksekusi peramban yang valid.
• Keterjangkauan profil CDP.
• Ketersediaan Chrome lokal untuk profil existing-session / user.

Terkait:

• Peramban (dikelola OpenClaw)
• Pemecahan masalah peramban

Jika Anda melakukan peningkatan dan sesuatu tiba-tiba rusak

Sebagian besar kerusakan setelah peningkatan disebabkan oleh penyimpangan konfigurasi atau default yang lebih ketat dan kini diberlakukan.

openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw config get gateway.auth.mode

openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw logs --follow

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

Jika konfigurasi layanan dan runtime masih tidak sesuai setelah pemeriksaan, instal ulang metadata layanan dari direktori profil/status yang sama:

openclaw gateway install --forceopenclaw gateway restart

Terkait:

• Autentikasi
• Eksekusi latar belakang dan alat proses
• Pemasangan Node

Terkait

• Doctor
• Tanya jawab umum
• Panduan operasional Gateway