Langsung ke konten utama

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

openclaw doctor adalah alat perbaikan + migrasi untuk OpenClaw. Alat ini memperbaiki konfigurasi/status yang usang, memeriksa kesehatan, dan menyediakan langkah perbaikan yang dapat ditindaklanjuti.

​
Mulai cepat

openclaw doctor

​
Mode headless dan otomasi

openclaw doctor --yes
Terima default tanpa prompt (termasuk langkah perbaikan restart/layanan/sandbox jika berlaku).
Jika Anda ingin meninjau perubahan sebelum menulis, buka file konfigurasi terlebih dahulu: 
cat ~/.openclaw/openclaw.json

​
Yang dilakukan (ringkasan)

  • Pembaruan pra-jalan opsional untuk instalasi git (hanya interaktif).
  • Pemeriksaan kesegaran protokol UI (membangun ulang Control UI saat skema protokol lebih baru).
  • Pemeriksaan kesehatan + prompt restart.
  • Ringkasan status Skills (memenuhi syarat/hilang/diblokir) dan status plugin.
  • Normalisasi konfigurasi untuk nilai lama.
  • Migrasi konfigurasi Talk dari field talk.* datar lama ke talk.provider + talk.providers.<provider>.
  • Pemeriksaan migrasi browser untuk konfigurasi ekstensi Chrome lama dan kesiapan Chrome MCP.
  • Peringatan override penyedia OpenCode (models.providers.opencode / models.providers.opencode-go).
  • Peringatan shadowing OAuth Codex (models.providers.openai-codex).
  • Pemeriksaan prasyarat TLS OAuth untuk profil OAuth OpenAI Codex.
  • Peringatan allowlist plugin/alat saat plugins.allow bersifat restriktif tetapi kebijakan alat masih meminta wildcard atau alat milik plugin.
  • Migrasi status lama di disk (sessions/agent dir/auth WhatsApp).
  • Migrasi kunci kontrak manifes plugin lama (speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders, webSearchProviders → contracts).
  • Migrasi penyimpanan cron lama (jobId, schedule.cron, field delivery/payload tingkat atas, payload provider, job fallback webhook notify: true sederhana).
  • Pembersihan kebijakan runtime seluruh agen lama; kebijakan runtime penyedia/model adalah pemilih rute aktif.
  • Pembersihan konfigurasi plugin usang saat plugin diaktifkan; saat plugins.enabled=false, referensi plugin usang diperlakukan sebagai konfigurasi penahanan inert dan dipertahankan.
  • Inspeksi file kunci sesi dan pembersihan kunci usang.
  • Perbaikan transkrip sesi untuk cabang penulisan ulang prompt duplikat yang dibuat oleh build 2026.4.24 yang terdampak.
  • Deteksi tombstone pemulihan restart subagen yang macet, dengan dukungan --fix untuk menghapus flag pemulihan dibatalkan yang usang agar startup tidak terus memperlakukan anak sebagai dibatalkan restart.
  • Pemeriksaan integritas status dan izin (sesi, transkrip, direktori status).
  • Pemeriksaan izin file konfigurasi (chmod 600) saat berjalan secara lokal.
  • Kesehatan auth model: memeriksa kedaluwarsa OAuth, dapat menyegarkan token yang hampir kedaluwarsa, dan melaporkan status cooldown/dinonaktifkan profil auth.
  • Deteksi direktori workspace tambahan (~/openclaw).
  • Perbaikan image sandbox saat sandboxing diaktifkan.
  • Migrasi layanan lama dan deteksi gateway tambahan.
  • Migrasi status lama channel Matrix (dalam mode --fix / --repair).
  • Pemeriksaan runtime Gateway (layanan terpasang tetapi tidak berjalan; label launchd yang di-cache).
  • Peringatan status channel (diprobe dari gateway yang sedang berjalan).
  • Pemeriksaan izin spesifik channel berada di bawah openclaw channels capabilities; misalnya, izin channel suara Discord diaudit dengan openclaw channels capabilities --channel discord --target channel:<channel-id>.
  • Pemeriksaan responsivitas WhatsApp untuk kesehatan event-loop Gateway yang menurun dengan klien TUI lokal yang masih berjalan; --fix hanya menghentikan klien TUI lokal yang terverifikasi.
  • Perbaikan rute Codex untuk ref model openai-codex/* lama dalam model utama, fallback, override heartbeat/subagen/compaction, hook, override model channel, dan pin rute sesi; --fix menulis ulangnya ke openai/*, menghapus pin runtime sesi/seluruh agen yang usang, dan membiarkan ref agen OpenAI kanonis pada harness Codex default.
  • Audit konfigurasi supervisor (launchd/systemd/schtasks) dengan perbaikan opsional.
  • Pembersihan lingkungan proxy tertanam untuk layanan gateway yang menangkap nilai shell HTTP_PROXY / HTTPS_PROXY / NO_PROXY saat instalasi atau pembaruan.
  • Pemeriksaan praktik terbaik runtime Gateway (Node vs Bun, path pengelola versi).
  • Diagnostik tabrakan port Gateway (default 18789).
  • Peringatan keamanan untuk kebijakan DM terbuka.
  • Pemeriksaan auth Gateway untuk mode token lokal (menawarkan pembuatan token saat tidak ada sumber token; tidak menimpa konfigurasi token SecretRef).
  • Deteksi masalah pairing perangkat (permintaan pairing pertama kali yang tertunda, peningkatan peran/cakupan yang tertunda, drift cache token perangkat lokal yang usang, dan drift auth catatan yang dipasangkan).
  • Pemeriksaan linger systemd di Linux.
  • Pemeriksaan ukuran file bootstrap workspace (peringatan pemotongan/hampir batas untuk file konteks).
  • Pemeriksaan kesiapan Skills untuk agen default; melaporkan skill yang diizinkan dengan bin, env, konfigurasi, atau persyaratan OS yang hilang, dan --fix dapat menonaktifkan skill yang tidak tersedia di skills.entries.
  • Pemeriksaan status penyelesaian shell dan pemasangan/peningkatan otomatis.
  • Pemeriksaan kesiapan penyedia embedding pencarian memori (model lokal, kunci API jarak jauh, atau biner QMD).
  • Pemeriksaan instalasi sumber (ketidakcocokan workspace pnpm, aset UI hilang, biner tsx hilang).
  • Menulis konfigurasi yang diperbarui + metadata wizard.

​
Backfill dan reset UI Dreams

Scene Dreams Control UI menyertakan tindakan Backfill, Reset, dan Clear Grounded untuk alur kerja dreaming grounded. Tindakan ini menggunakan metode RPC bergaya doctor gateway, tetapi bukan bagian dari perbaikan/migrasi CLI openclaw doctor. Yang dilakukan:
  • Backfill memindai file historis memory/YYYY-MM-DD.md di workspace aktif, menjalankan pass diarI REM grounded, dan menulis entri backfill yang dapat dibalik ke DREAMS.md.
  • Reset hanya menghapus entri diari backfill bertanda tersebut dari DREAMS.md.
  • Clear Grounded hanya menghapus entri jangka pendek khusus grounded yang sudah distage, yang berasal dari replay historis dan belum mengumpulkan recall live atau dukungan harian.
Yang tidak dilakukan sendiri:
  • tindakan ini tidak mengedit MEMORY.md
  • tindakan ini tidak menjalankan migrasi doctor penuh
  • tindakan ini tidak otomatis men-stage kandidat grounded ke penyimpanan promosi jangka pendek live kecuali Anda secara eksplisit menjalankan jalur CLI staged terlebih dahulu
Jika Anda ingin replay historis grounded memengaruhi lane promosi mendalam normal, gunakan alur CLI sebagai gantinya: 
openclaw memory rem-backfill --path ./memory --stage-short-term
Itu men-stage kandidat durable grounded ke penyimpanan dreaming jangka pendek sambil mempertahankan DREAMS.md sebagai permukaan peninjauan.

​
Perilaku dan alasan terperinci

Jika ini adalah checkout git dan doctor berjalan secara interaktif, doctor menawarkan pembaruan (fetch/rebase/build) sebelum menjalankan doctor.
Jika konfigurasi berisi bentuk nilai lama (misalnya messages.ackReaction tanpa override spesifik channel), doctor menormalkannya ke skema saat ini.Itu mencakup field datar Talk lama. Konfigurasi speech Talk publik saat ini adalah talk.provider + talk.providers.<provider>, dan konfigurasi suara realtime adalah talk.realtime.*. Doctor menulis ulang bentuk talk.voiceId / talk.voiceAliases / talk.modelId / talk.outputFormat / talk.apiKey lama ke peta penyedia, dan menulis ulang pemilih realtime tingkat atas lama (talk.mode, talk.transport, talk.brain, talk.model, talk.voice) ke talk.realtime.Doctor juga memperingatkan saat plugins.allow tidak kosong dan kebijakan alat menggunakan entri alat wildcard atau milik plugin. tools.allow: ["*"] hanya cocok dengan alat dari plugin yang benar-benar dimuat; itu tidak melewati allowlist plugin eksklusif. Doctor menulis plugins.bundledDiscovery: "compat" untuk konfigurasi allowlist lama yang dimigrasikan guna mempertahankan perilaku penyedia bundled yang ada, lalu menunjuk ke pengaturan "allowlist" yang lebih ketat.
Saat konfigurasi berisi kunci usang, perintah lain menolak berjalan dan meminta Anda menjalankan openclaw doctor.Doctor akan:
  • Menjelaskan kunci lama mana yang ditemukan.
  • Menampilkan migrasi yang diterapkan.
  • Menulis ulang ~/.openclaw/openclaw.json dengan skema yang diperbarui.
Startup Gateway menolak format konfigurasi lama dan meminta Anda menjalankan openclaw doctor --fix; startup tidak menulis ulang openclaw.json. Migrasi penyimpanan job Cron juga ditangani oleh openclaw doctor --fix.Migrasi saat ini:
  • routing.allowFrom → channels.whatsapp.allowFrom
  • routing.groupChat.requireMention → channels.whatsapp/telegram/imessage.groups."*".requireMention
  • routing.groupChat.historyLimit → messages.groupChat.historyLimit
  • routing.groupChat.mentionPatterns → messages.groupChat.mentionPatterns
  • channels.telegram.requireMention → channels.telegram.groups."*".requireMention
  • konfigurasi channel terkonfigurasi yang tidak memiliki kebijakan balasan terlihat → messages.groupChat.visibleReplies: "message_tool"
  • routing.queue → messages.queue
  • routing.bindings → bindings tingkat teratas
  • routing.agents/routing.defaultAgentId → agents.list + agents.list[].default
  • talk.voiceId/talk.voiceAliases/talk.modelId/talk.outputFormat/talk.apiKey lama → talk.provider + talk.providers.<provider>
  • pemilih Talk realtime tingkat teratas lama (talk.mode/talk.transport/talk.brain/talk.model/talk.voice) + talk.provider/talk.providers → talk.realtime
  • routing.agentToAgent → tools.agentToAgent
  • routing.transcribeAudio → tools.media.audio.models
  • messages.tts.<provider> (openai/elevenlabs/microsoft/edge) → messages.tts.providers.<provider>
  • messages.tts.provider: "edge" dan messages.tts.providers.edge → messages.tts.provider: "microsoft" dan messages.tts.providers.microsoft
  • channels.discord.voice.tts.<provider> (openai/elevenlabs/microsoft/edge) → channels.discord.voice.tts.providers.<provider>
  • channels.discord.accounts.<id>.voice.tts.<provider> (openai/elevenlabs/microsoft/edge) → channels.discord.accounts.<id>.voice.tts.providers.<provider>
  • plugins.entries.voice-call.config.tts.<provider> (openai/elevenlabs/microsoft/edge) → plugins.entries.voice-call.config.tts.providers.<provider>
  • plugins.entries.voice-call.config.tts.provider: "edge" dan plugins.entries.voice-call.config.tts.providers.edge → provider: "microsoft" dan providers.microsoft
  • plugins.entries.voice-call.config.provider: "log" → "mock"
  • plugins.entries.voice-call.config.twilio.from → plugins.entries.voice-call.config.fromNumber
  • plugins.entries.voice-call.config.streaming.sttProvider → plugins.entries.voice-call.config.streaming.provider
  • plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold → plugins.entries.voice-call.config.streaming.providers.openai.*
  • bindings[].match.accountID → bindings[].match.accountId
  • Untuk channel dengan accounts bernama tetapi masih memiliki nilai channel tingkat teratas akun tunggal yang tersisa, pindahkan nilai bercakupan akun tersebut ke akun yang dipromosikan yang dipilih untuk channel itu (accounts.default untuk sebagian besar channel; Matrix dapat mempertahankan target bernama/default cocok yang sudah ada)
  • identity → agents.list[].identity
  • agent.* → agents.defaults + tools.* (tools/elevated/exec/sandbox/subagents)
  • agent.model/allowedModels/modelAliases/modelFallbacks/imageModelFallbacks → agents.defaults.models + agents.defaults.model.primary/fallbacks + agents.defaults.imageModel.primary/fallbacks
  • hapus agents.defaults.llm; gunakan models.providers.<id>.timeoutSeconds untuk timeout provider/model lambat
  • browser.ssrfPolicy.allowPrivateNetwork → browser.ssrfPolicy.dangerouslyAllowPrivateNetwork
  • browser.profiles.*.driver: "extension" → "existing-session"
  • hapus browser.relayBindHost (pengaturan relay ekstensi lama)
  • models.providers.*.api: "openai" lama → "openai-completions" (startup gateway juga melewati provider yang api-nya disetel ke nilai enum mendatang atau tidak dikenal alih-alih gagal tertutup)
  • hapus plugins.entries.codex.config.codexDynamicToolsProfile; server aplikasi Codex selalu mempertahankan alat workspace native Codex tetap native
Peringatan doctor juga mencakup panduan default akun untuk channel multi-akun:
  • Jika dua atau lebih entri channels.<channel>.accounts dikonfigurasi tanpa channels.<channel>.defaultAccount atau accounts.default, doctor memperingatkan bahwa perutean fallback dapat memilih akun yang tidak terduga.
  • Jika channels.<channel>.defaultAccount disetel ke ID akun yang tidak dikenal, doctor memperingatkan dan mencantumkan ID akun yang dikonfigurasi.
Jika Anda menambahkan models.providers.opencode, opencode-zen, atau opencode-go secara manual, itu akan menggantikan katalog bawaan OpenCode dari @earendil-works/pi-ai. Hal itu dapat memaksa model ke API yang salah atau mengosongkan biaya. Doctor memperingatkan agar Anda dapat menghapus penggantian tersebut dan memulihkan perutean API + biaya per model.
Jika konfigurasi browser Anda masih mengarah ke path ekstensi Chrome yang telah dihapus, doctor menormalkannya ke model attach Chrome MCP host-lokal saat ini:
  • browser.profiles.*.driver: "extension" menjadi "existing-session"
  • browser.relayBindHost dihapus
Doctor juga mengaudit path Chrome MCP host-lokal saat Anda menggunakan defaultProfile: "user" atau profil existing-session yang dikonfigurasi:
  • memeriksa apakah Google Chrome terinstal pada host yang sama untuk profil auto-connect default
  • memeriksa versi Chrome yang terdeteksi dan memperingatkan jika lebih rendah dari Chrome 144
  • mengingatkan Anda untuk mengaktifkan remote debugging di halaman inspect browser (misalnya chrome://inspect/#remote-debugging, brave://inspect/#remote-debugging, atau edge://inspect/#remote-debugging)
Doctor tidak dapat mengaktifkan pengaturan sisi Chrome untuk Anda. Chrome MCP host-lokal tetap memerlukan:
  • browser berbasis Chromium 144+ pada host gateway/node
  • browser berjalan secara lokal
  • remote debugging diaktifkan di browser tersebut
  • menyetujui prompt persetujuan attach pertama di browser
Kesiapan di sini hanya tentang prasyarat attach lokal. Existing-session mempertahankan batas rute Chrome MCP saat ini; rute lanjutan seperti responsebody, ekspor PDF, intersepsi unduhan, dan aksi batch masih memerlukan browser terkelola atau profil CDP mentah.Pemeriksaan ini tidak berlaku untuk Docker, sandbox, remote-browser, atau alur headless lainnya. Semua itu tetap menggunakan CDP mentah.
Saat profil OAuth OpenAI Codex dikonfigurasi, doctor memeriksa endpoint otorisasi OpenAI untuk memverifikasi bahwa stack TLS Node/OpenSSL lokal dapat memvalidasi rantai sertifikat. Jika pemeriksaan gagal dengan error sertifikat (misalnya UNABLE_TO_GET_ISSUER_CERT_LOCALLY, sertifikat kedaluwarsa, atau sertifikat self-signed), doctor mencetak panduan perbaikan khusus platform. Pada macOS dengan Node dari Homebrew, perbaikannya biasanya brew postinstall ca-certificates. Dengan --deep, pemeriksaan berjalan meskipun gateway sehat.
Jika sebelumnya Anda menambahkan pengaturan transport OpenAI lama di bawah models.providers.openai-codex, pengaturan itu dapat menutupi path provider OAuth Codex bawaan yang digunakan secara otomatis oleh rilis yang lebih baru. Doctor memperingatkan saat melihat pengaturan transport lama tersebut bersama OAuth Codex agar Anda dapat menghapus atau menulis ulang penggantian transport usang itu dan mendapatkan kembali perilaku perutean/fallback bawaan. Proxy kustom dan penggantian khusus header tetap didukung dan tidak memicu peringatan ini.
Doctor memeriksa ref model openai-codex/* lama. Perutean harness native Codex menggunakan ref model kanonis openai/*; giliran agen OpenAI melewati harness server aplikasi Codex, bukan path OpenClaw PI OpenAI.Dalam mode --fix / --repair, doctor menulis ulang ref default-agent dan per-agent yang terpengaruh, termasuk model primer, fallback, penggantian heartbeat/subagent/compaction, hook, penggantian model channel, dan state rute sesi persisten yang usang:
  • openai-codex/gpt-* menjadi openai/gpt-*.
  • Intent Codex berpindah ke entri agentRuntime.id: "codex" bercakupan provider/model untuk ref model agen yang diperbaiki sehingga profil auth openai-codex:... masih dapat dipilih setelah ref model menjadi openai/*.
  • Konfigurasi runtime seluruh agen yang usang dan pin runtime sesi persisten dihapus karena pemilihan runtime bercakupan provider/model.
  • Kebijakan runtime provider/model yang sudah ada dipertahankan kecuali ref model lama yang diperbaiki memerlukan perutean Codex untuk mempertahankan path auth lama.
  • Daftar fallback model yang sudah ada dipertahankan dengan entri lamanya ditulis ulang; pengaturan per-model yang disalin berpindah dari kunci lama ke kunci kanonis openai/*.
  • modelProvider/providerOverride, model/modelOverride, pemberitahuan fallback, dan pin auth-profile sesi persisten diperbaiki di seluruh store sesi agen yang ditemukan.
  • /codex ... berarti “mengontrol atau mengikat percakapan native Codex dari chat.”
  • /acp ... atau runtime: "acp" berarti “menggunakan adaptor ACP/acpx eksternal.”
Doctor juga memindai store sesi agen yang ditemukan untuk state rute auto-created yang usang setelah Anda memindahkan model atau runtime terkonfigurasi menjauh dari rute milik Plugin seperti Codex.openclaw doctor --fix dapat menghapus state usang auto-created seperti pin model modelOverrideSource: "auto", metadata model runtime, ID harness yang dipin, binding sesi CLI, dan penggantian auth-profile otomatis saat rute pemiliknya tidak lagi dikonfigurasi. Pilihan model pengguna eksplisit atau sesi lama dilaporkan untuk peninjauan manual dan dibiarkan tidak tersentuh; alihkan dengan /model ..., /new, atau reset sesi saat rute itu tidak lagi dimaksudkan.
Doctor dapat memigrasikan tata letak lama di disk ke struktur saat ini:
  • Store sesi + transkrip:
    • dari ~/.openclaw/sessions/ ke ~/.openclaw/agents/<agentId>/sessions/
  • Direktori agen:
    • dari ~/.openclaw/agent/ ke ~/.openclaw/agents/<agentId>/agent/
  • State auth WhatsApp (Baileys):
    • dari ~/.openclaw/credentials/*.json lama (kecuali oauth.json)
    • ke ~/.openclaw/credentials/whatsapp/<accountId>/... (ID akun default: default)
Migrasi ini bersifat best-effort dan idempoten; doctor akan mengeluarkan peringatan saat meninggalkan folder lama sebagai cadangan. Gateway/CLI juga otomatis memigrasikan sesi lama + direktori agen saat startup sehingga riwayat/auth/model masuk ke path per-agen tanpa menjalankan doctor secara manual. Normalisasi provider/peta-provider Talk kini membandingkan berdasarkan kesetaraan struktural, sehingga diff yang hanya berupa urutan kunci tidak lagi memicu perubahan no-op doctor --fix berulang.
Doctor memindai semua manifes Plugin yang terinstal untuk kunci capability tingkat teratas yang sudah tidak digunakan (speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders, webSearchProviders). Jika ditemukan, doctor menawarkan untuk memindahkannya ke objek contracts dan menulis ulang file manifes di tempat. Migrasi ini idempoten; jika kunci contracts sudah memiliki nilai yang sama, kunci lama dihapus tanpa menduplikasi data.
Doctor juga memeriksa store job Cron (~/.openclaw/cron/jobs.json secara default, atau cron.store saat diganti) untuk bentuk job lama yang masih diterima scheduler demi kompatibilitas.Pembersihan Cron saat ini meliputi:
  • jobId → id
  • schedule.cron → schedule.expr
  • bidang payload tingkat atas (message, model, thinking, …) → payload
  • bidang pengiriman tingkat atas (deliver, channel, to, provider, …) → delivery
  • alias pengiriman provider payload → delivery.channel eksplisit
  • tugas fallback webhook notify: true lama yang sederhana → delivery.mode="webhook" eksplisit dengan delivery.to=cron.webhook
Doctor hanya memigrasikan otomatis tugas notify: true ketika dapat melakukannya tanpa mengubah perilaku. Jika sebuah tugas menggabungkan fallback notify lama dengan mode pengiriman non-webhook yang sudah ada, doctor memperingatkan dan membiarkan tugas itu untuk ditinjau manual.Di Linux, doctor juga memperingatkan ketika crontab pengguna masih memanggil ~/.openclaw/bin/ensure-whatsapp.sh lama. Skrip lokal host itu tidak dipelihara oleh OpenClaw saat ini dan dapat menulis pesan Gateway inactive palsu ke ~/.openclaw/logs/whatsapp-health.log ketika cron tidak dapat menjangkau bus pengguna systemd. Hapus entri crontab usang dengan crontab -e; gunakan openclaw channels status --probe, openclaw doctor, dan openclaw gateway status untuk pemeriksaan kesehatan saat ini.
Doctor memindai setiap direktori sesi agen untuk mencari file kunci tulis yang usang — file yang tertinggal ketika sesi keluar secara abnormal. Untuk setiap file kunci yang ditemukan, doctor melaporkan: jalur, PID, apakah PID masih hidup, usia kunci, dan apakah dianggap usang (PID mati, lebih lama dari 30 menit, atau PID hidup yang dapat dibuktikan milik proses non-OpenClaw). Dalam mode --fix / --repair, doctor menghapus file kunci usang secara otomatis; jika tidak, doctor mencetak catatan dan menginstruksikan Anda untuk menjalankan ulang dengan --fix.
Doctor memindai file JSONL sesi agen untuk mencari bentuk cabang terduplikasi yang dibuat oleh bug penulisan ulang transkrip prompt 2026.4.24: giliran pengguna yang ditinggalkan dengan konteks runtime internal OpenClaw plus saudara aktif yang berisi prompt pengguna terlihat yang sama. Dalam mode --fix / --repair, doctor mencadangkan setiap file yang terdampak di sebelah file asli dan menulis ulang transkrip ke cabang aktif sehingga riwayat gateway dan pembaca memori tidak lagi melihat giliran duplikat.
Direktori status adalah batang otak operasional. Jika direktori itu hilang, Anda kehilangan sesi, kredensial, log, dan konfigurasi (kecuali Anda memiliki cadangan di tempat lain).Doctor memeriksa:
  • Direktori status hilang: memperingatkan tentang kehilangan status yang katastrofik, meminta untuk membuat ulang direktori, dan mengingatkan Anda bahwa data yang hilang tidak dapat dipulihkan.
  • Izin direktori status: memverifikasi kemampuan tulis; menawarkan untuk memperbaiki izin (dan mengeluarkan petunjuk chown ketika ketidakcocokan pemilik/grup terdeteksi).
  • Direktori status tersinkron cloud macOS: memperingatkan ketika status terselesaikan di bawah iCloud Drive (~/Library/Mobile Documents/com~apple~CloudDocs/...) atau ~/Library/CloudStorage/... karena jalur yang didukung sinkronisasi dapat menyebabkan I/O lebih lambat dan race kunci/sinkronisasi.
  • Direktori status SD atau eMMC Linux: memperingatkan ketika status terselesaikan ke sumber mount mmcblk*, karena I/O acak yang didukung SD atau eMMC dapat lebih lambat dan lebih cepat aus akibat penulisan sesi dan kredensial.
  • Direktori sesi hilang: sessions/ dan direktori penyimpanan sesi diperlukan untuk mempertahankan riwayat dan menghindari crash ENOENT.
  • Ketidakcocokan transkrip: memperingatkan ketika entri sesi terbaru memiliki file transkrip yang hilang.
  • Sesi utama “JSONL 1 baris”: menandai ketika transkrip utama hanya memiliki satu baris (riwayat tidak terakumulasi).
  • Beberapa direktori status: memperingatkan ketika beberapa folder ~/.openclaw ada di berbagai direktori home atau ketika OPENCLAW_STATE_DIR menunjuk ke tempat lain (riwayat dapat terpecah antarinstalasi).
  • Pengingat mode jarak jauh: jika gateway.mode=remote, doctor mengingatkan Anda untuk menjalankannya di host jarak jauh (status berada di sana).
  • Izin file konfigurasi: memperingatkan jika ~/.openclaw/openclaw.json dapat dibaca oleh grup/dunia dan menawarkan untuk memperketatnya ke 600.
Doctor memeriksa profil OAuth di penyimpanan auth, memperingatkan ketika token akan kedaluwarsa/sudah kedaluwarsa, dan dapat menyegarkannya ketika aman. Jika profil OAuth/token Anthropic sudah usang, doctor menyarankan kunci API Anthropic atau jalur token penyiapan Anthropic. Prompt penyegaran hanya muncul ketika berjalan secara interaktif (TTY); --non-interactive melewati upaya penyegaran.Ketika penyegaran OAuth gagal secara permanen (misalnya refresh_token_reused, invalid_grant, atau provider memberi tahu Anda untuk masuk lagi), doctor melaporkan bahwa auth ulang diperlukan dan mencetak perintah openclaw models auth login --provider ... yang persis untuk dijalankan.Doctor juga melaporkan profil auth yang untuk sementara tidak dapat digunakan karena:
  • cooldown singkat (batas laju/timeout/kegagalan auth)
  • penonaktifan lebih lama (kegagalan penagihan/kredit)
Jika hooks.gmail.model ditetapkan, doctor memvalidasi referensi model terhadap katalog dan allowlist serta memperingatkan ketika referensi itu tidak akan terselesaikan atau tidak diizinkan.
Ketika sandboxing diaktifkan, doctor memeriksa image Docker dan menawarkan untuk membangun atau beralih ke nama lama jika image saat ini hilang.
Doctor menghapus status staging dependensi plugin lama yang dihasilkan OpenClaw dalam mode openclaw doctor --fix / openclaw doctor --repair. Ini mencakup root dependensi yang dihasilkan dan sudah usang, direktori tahap instal lama, sisa lokal paket dari kode perbaikan dependensi plugin bawaan sebelumnya, serta salinan npm terkelola dari plugin @openclaw/* bawaan yang yatim atau dipulihkan yang dapat menutupi manifes bawaan saat ini. Doctor juga menautkan ulang paket host openclaw ke plugin npm terkelola yang mendeklarasikan peerDependencies.openclaw, sehingga impor runtime lokal paket seperti openclaw/plugin-sdk/* tetap terselesaikan setelah pembaruan atau perbaikan npm.Doctor juga dapat menginstal ulang plugin unduhan yang hilang ketika konfigurasi merujuknya tetapi registry plugin lokal tidak dapat menemukannya. Contohnya meliputi plugins.entries material, pengaturan channel/provider/search yang dikonfigurasi, dan runtime agen yang dikonfigurasi. Selama pembaruan paket, doctor menghindari menjalankan perbaikan plugin package-manager saat paket inti sedang diganti; jalankan openclaw doctor --fix lagi setelah pembaruan jika plugin yang dikonfigurasi masih perlu dipulihkan. Startup Gateway dan pemuatan ulang konfigurasi tidak menjalankan package manager; instalasi plugin tetap menjadi pekerjaan doctor/install/update yang eksplisit.
Doctor mendeteksi layanan gateway lama (launchd/systemd/schtasks) dan menawarkan untuk menghapusnya serta menginstal layanan OpenClaw menggunakan port gateway saat ini. Doctor juga dapat memindai layanan tambahan yang mirip gateway dan mencetak petunjuk pembersihan. Layanan gateway OpenClaw bernama profil dianggap kelas utama dan tidak ditandai sebagai “ekstra.”Di Linux, jika layanan gateway tingkat pengguna hilang tetapi layanan gateway OpenClaw tingkat sistem ada, doctor tidak menginstal layanan tingkat pengguna kedua secara otomatis. Periksa dengan openclaw gateway status --deep atau openclaw doctor --deep, lalu hapus duplikatnya atau tetapkan OPENCLAW_SERVICE_REPAIR_POLICY=external ketika supervisor sistem memiliki siklus hidup gateway.
Ketika akun channel Matrix memiliki migrasi status lama yang tertunda atau dapat ditindaklanjuti, doctor (dalam mode --fix / --repair) membuat snapshot pra-migrasi lalu menjalankan langkah migrasi upaya terbaik: migrasi status Matrix lama dan persiapan status terenkripsi lama. Kedua langkah tidak fatal; kesalahan dicatat dan startup berlanjut. Dalam mode hanya baca (openclaw doctor tanpa --fix), pemeriksaan ini dilewati sepenuhnya.
Doctor sekarang memeriksa status penyandingan perangkat sebagai bagian dari pemeriksaan kesehatan normal.Yang dilaporkan:
  • permintaan penyandingan pertama kali yang tertunda
  • peningkatan peran yang tertunda untuk perangkat yang sudah disandingkan
  • peningkatan scope yang tertunda untuk perangkat yang sudah disandingkan
  • perbaikan ketidakcocokan kunci publik ketika id perangkat masih cocok tetapi identitas perangkat tidak lagi cocok dengan catatan yang disetujui
  • catatan tersanding yang tidak memiliki token aktif untuk peran yang disetujui
  • token tersanding yang scope-nya bergeser di luar baseline penyandingan yang disetujui
  • entri token perangkat cache lokal untuk mesin saat ini yang lebih lama dari rotasi token sisi gateway atau membawa metadata scope usang
Doctor tidak menyetujui otomatis permintaan penyandingan atau memutar otomatis token perangkat. Doctor mencetak langkah berikutnya yang persis sebagai gantinya:
  • periksa permintaan tertunda dengan openclaw devices list
  • setujui permintaan persis dengan openclaw devices approve <requestId>
  • putar token baru dengan openclaw devices rotate --device <deviceId> --role <role>
  • hapus dan setujui ulang catatan usang dengan openclaw devices remove <deviceId>
Ini menutup celah umum “sudah disandingkan tetapi masih mendapat pesan perlu penyandingan”: doctor sekarang membedakan penyandingan pertama kali dari peningkatan peran/scope yang tertunda dan dari drift token/identitas perangkat yang usang.
Doctor mengeluarkan peringatan ketika provider terbuka untuk DM tanpa allowlist, atau ketika kebijakan dikonfigurasi dengan cara yang berbahaya.
Jika berjalan sebagai layanan pengguna systemd, doctor memastikan lingering diaktifkan agar gateway tetap hidup setelah logout.
Doctor mencetak ringkasan status workspace untuk agen default:
  • Status Skills: menghitung Skills yang eligible, missing-requirements, dan diblokir allowlist.
  • Direktori workspace lama: memperingatkan ketika ~/openclaw atau direktori workspace lama lainnya ada berdampingan dengan workspace saat ini.
  • Status Plugin: menghitung plugin yang diaktifkan/dinonaktifkan/bererror; mencantumkan ID plugin untuk error apa pun; melaporkan kapabilitas plugin bundle.
  • Peringatan kompatibilitas Plugin: menandai plugin yang memiliki masalah kompatibilitas dengan runtime saat ini.
  • Diagnostik Plugin: menampilkan peringatan atau error waktu muat apa pun yang dikeluarkan oleh registry plugin.
Doctor memeriksa apakah file bootstrap workspace (misalnya AGENTS.md, CLAUDE.md, atau file konteks lain yang diinjeksikan) mendekati atau melebihi anggaran karakter yang dikonfigurasi. Doctor melaporkan jumlah karakter mentah vs. terinjeksi per file, persentase pemotongan, penyebab pemotongan (max/file atau max/total), dan total karakter terinjeksi sebagai fraksi dari total anggaran. Ketika file dipotong atau mendekati batas, doctor mencetak kiat untuk menyetel agents.defaults.bootstrapMaxChars dan agents.defaults.bootstrapTotalMaxChars.
Ketika openclaw doctor --fix menghapus plugin channel yang hilang, doctor juga menghapus konfigurasi berscope channel yang menggantung yang merujuk plugin itu: entri channels.<id>, target heartbeat yang menamai channel tersebut, dan override agents.*.models["<channel>/*"]. Ini mencegah loop boot Gateway ketika runtime channel sudah hilang tetapi konfigurasi masih meminta gateway untuk mengikat ke runtime itu.
Doctor memeriksa apakah pelengkapan tab terinstal untuk shell saat ini (zsh, bash, fish, atau PowerShell):
  • Jika profil shell menggunakan pola penyelesaian dinamis yang lambat (source <(openclaw completion ...)), doctor memutakhirkannya ke varian file cache yang lebih cepat.
  • Jika penyelesaian dikonfigurasi di profil tetapi file cache tidak ada, doctor membuat ulang cache secara otomatis.
  • Jika tidak ada penyelesaian yang dikonfigurasi sama sekali, doctor meminta pemasangannya (hanya mode interaktif; dilewati dengan --non-interactive).
Jalankan openclaw completion --write-state untuk membuat ulang cache secara manual.
Doctor memeriksa kesiapan autentikasi token Gateway lokal.
  • Jika mode token memerlukan token dan tidak ada sumber token, doctor menawarkan untuk membuatnya.
  • Jika gateway.auth.token dikelola SecretRef tetapi tidak tersedia, doctor memperingatkan dan tidak menimpanya dengan teks biasa.
  • openclaw doctor --generate-gateway-token memaksa pembuatan hanya ketika tidak ada SecretRef token yang dikonfigurasi.
Beberapa alur perbaikan perlu memeriksa kredensial yang dikonfigurasi tanpa melemahkan perilaku fail-fast runtime.
  • openclaw doctor --fix sekarang menggunakan model ringkasan SecretRef hanya-baca yang sama seperti perintah keluarga status untuk perbaikan konfigurasi yang ditargetkan.
  • Contoh: perbaikan Telegram allowFrom / groupAllowFrom @username mencoba menggunakan kredensial bot yang dikonfigurasi saat tersedia.
  • Jika token bot Telegram dikonfigurasi melalui SecretRef tetapi tidak tersedia di jalur perintah saat ini, doctor melaporkan bahwa kredensial sudah dikonfigurasi-tetapi-tidak-tersedia dan melewati resolusi otomatis alih-alih crash atau salah melaporkan token sebagai hilang.
Doctor menjalankan pemeriksaan kesehatan dan menawarkan untuk me-restart Gateway ketika tampak tidak sehat.
Doctor memeriksa apakah penyedia embedding pencarian memori yang dikonfigurasi siap untuk agen default. Perilakunya bergantung pada backend dan penyedia yang dikonfigurasi:
  • Backend QMD: memeriksa apakah biner qmd tersedia dan dapat dijalankan. Jika tidak, mencetak panduan perbaikan termasuk paket npm dan opsi jalur biner manual.
  • Penyedia lokal eksplisit: memeriksa file model lokal atau URL model jarak jauh/yang dapat diunduh yang dikenali. Jika hilang, menyarankan beralih ke penyedia jarak jauh.
  • Penyedia jarak jauh eksplisit (openai, voyage, dll.): memverifikasi bahwa kunci API ada di lingkungan atau penyimpanan auth. Mencetak petunjuk perbaikan yang dapat ditindaklanjuti jika hilang.
  • Penyedia otomatis: memeriksa ketersediaan model lokal terlebih dahulu, lalu mencoba setiap penyedia jarak jauh dalam urutan pemilihan otomatis.
Ketika hasil probe Gateway yang di-cache tersedia (Gateway sehat pada saat pemeriksaan), doctor mencocokkan silang hasilnya dengan konfigurasi yang terlihat oleh CLI dan mencatat setiap ketidaksesuaian. Doctor tidak memulai ping embedding baru di jalur default; gunakan perintah status memori mendalam ketika Anda menginginkan pemeriksaan penyedia langsung.Gunakan openclaw memory status --deep untuk memverifikasi kesiapan embedding saat runtime.
Jika Gateway sehat, doctor menjalankan probe status channel dan melaporkan peringatan beserta saran perbaikan.
Doctor memeriksa konfigurasi supervisor yang terpasang (launchd/systemd/schtasks) untuk default yang hilang atau usang (misalnya, dependensi systemd network-online dan jeda restart). Ketika menemukan ketidaksesuaian, doctor merekomendasikan pembaruan dan dapat menulis ulang file layanan/tugas ke default saat ini.Catatan:
  • openclaw doctor meminta konfirmasi sebelum menulis ulang konfigurasi supervisor.
  • openclaw doctor --yes menerima prompt perbaikan default.
  • openclaw doctor --repair menerapkan perbaikan yang direkomendasikan tanpa prompt.
  • openclaw doctor --repair --force menimpa konfigurasi supervisor kustom.
  • OPENCLAW_SERVICE_REPAIR_POLICY=external membuat doctor hanya-baca untuk siklus hidup layanan Gateway. Doctor tetap melaporkan kesehatan layanan dan menjalankan perbaikan non-layanan, tetapi melewati pemasangan/start/restart/bootstrap layanan, penulisan ulang konfigurasi supervisor, dan pembersihan layanan lama karena supervisor eksternal memiliki siklus hidup tersebut.
  • Di Linux, doctor tidak menulis ulang metadata perintah/entrypoint saat unit Gateway systemd yang cocok aktif. Doctor juga mengabaikan unit tambahan mirip Gateway non-legacy yang tidak aktif selama pemindaian layanan duplikat sehingga file layanan pendamping tidak membuat kebisingan pembersihan.
  • Jika auth token memerlukan token dan gateway.auth.token dikelola SecretRef, pemasangan/perbaikan layanan doctor memvalidasi SecretRef tetapi tidak menyimpan nilai token teks biasa yang terselesaikan ke metadata lingkungan layanan supervisor.
  • Doctor mendeteksi nilai lingkungan layanan yang dikelola .env/berbasis SecretRef yang sebelumnya disematkan inline oleh pemasangan LaunchAgent, systemd, atau Windows Scheduled Task lama dan menulis ulang metadata layanan sehingga nilai tersebut dimuat dari sumber runtime alih-alih definisi supervisor.
  • Doctor mendeteksi ketika perintah layanan masih mematok --port lama setelah gateway.port berubah dan menulis ulang metadata layanan ke port saat ini.
  • Jika auth token memerlukan token dan SecretRef token yang dikonfigurasi belum terselesaikan, doctor memblokir jalur pemasangan/perbaikan dengan panduan yang dapat ditindaklanjuti.
  • Jika gateway.auth.token dan gateway.auth.password sama-sama dikonfigurasi dan gateway.auth.mode belum diatur, doctor memblokir pemasangan/perbaikan hingga mode diatur secara eksplisit.
  • Untuk unit user-systemd Linux, pemeriksaan drift token doctor sekarang menyertakan sumber Environment= dan EnvironmentFile= saat membandingkan metadata auth layanan.
  • Perbaikan layanan doctor menolak menulis ulang, menghentikan, atau me-restart layanan Gateway dari biner OpenClaw yang lebih lama ketika konfigurasi terakhir ditulis oleh versi yang lebih baru. Lihat Pemecahan masalah Gateway.
  • Anda selalu dapat memaksa penulisan ulang penuh melalui openclaw gateway install --force.
Doctor memeriksa runtime layanan (PID, status keluar terakhir) dan memperingatkan ketika layanan terpasang tetapi tidak benar-benar berjalan. Doctor juga memeriksa tabrakan port pada port Gateway (default 18789) dan melaporkan kemungkinan penyebabnya (Gateway sudah berjalan, tunnel SSH).
Doctor memperingatkan ketika layanan Gateway berjalan di Bun atau jalur Node yang dikelola versi (nvm, fnm, volta, asdf, dll.). Channel WhatsApp + Telegram memerlukan Node, dan jalur pengelola versi dapat rusak setelah upgrade karena layanan tidak memuat init shell Anda. Doctor menawarkan migrasi ke instalasi Node sistem ketika tersedia (Homebrew/apt/choco).LaunchAgent macOS yang baru dipasang atau diperbaiki menggunakan PATH sistem kanonis (/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin) alih-alih menyalin PATH shell interaktif, sehingga biner sistem yang dikelola Homebrew tetap tersedia sementara Volta, asdf, fnm, pnpm, dan direktori pengelola versi lain tidak mengubah Node mana yang diselesaikan oleh proses anak. Layanan Linux tetap mempertahankan root lingkungan eksplisit (NVM_DIR, FNM_DIR, VOLTA_HOME, ASDF_DATA_DIR, BUN_INSTALL, PNPM_HOME) dan direktori user-bin yang stabil, tetapi direktori fallback pengelola versi yang ditebak hanya ditulis ke PATH layanan ketika direktori tersebut ada di disk.
Doctor menyimpan perubahan konfigurasi apa pun dan memberi cap metadata wizard untuk merekam proses doctor.
Doctor menyarankan sistem memori workspace saat hilang dan mencetak tips cadangan jika workspace belum berada di bawah git.Lihat /concepts/agent-workspace untuk panduan lengkap tentang struktur workspace dan cadangan git (disarankan GitHub atau GitLab pribadi).

​
Terkait