Перейти до основного вмісту
openclaw doctor — це інструмент ремонту + міграції для OpenClaw. Він виправляє застарілі конфігурацію/стан, перевіряє справність і надає дієві кроки для ремонту.

​
Швидкий старт

openclaw doctor

​
Режими без інтерфейсу та автоматизації

openclaw doctor --yes
Приймати типові значення без запитів (включно з кроками ремонту перезапуску/сервісу/пісочниці, коли застосовно).
Якщо хочете переглянути зміни перед записом, спочатку відкрийте файл конфігурації: 
cat ~/.openclaw/openclaw.json

​
Режим lint лише для читання

openclaw doctor --lint — це дружній до автоматизації споріднений режим openclaw doctor --fix. Обидва використовують перевірки справності doctor, але їхня позиція відрізняється:
РежимЗапитиЗаписує конфігурацію/станВивідВикористовуйте для
openclaw doctorтакнідружній звіт справностіперевірки стану людиною
openclaw doctor --fixінодітак, за політикою ремонтудружній журнал ремонтузастосування схвалених ремонтів
openclaw doctor --lintнініструктуровані знахідкиCI, попередніх перевірок і review-гейтів
Модернізовані перевірки справності можуть надавати необов’язкову реалізацію repair(). doctor --fix застосовує ці ремонти, коли вони існують, і продовжує використовувати наявний потік ремонту doctor для перевірок, які ще не мігровано. Структурований контракт ремонту також відокремлює звітування про ремонт від виявлення: detect() повідомляє про поточні знахідки, тоді як repair() може повідомляти про зміни, відмінності конфігурації/файлів і нефайлові побічні ефекти. Це залишає шлях міграції відкритим для майбутніх doctor --fix --dry-run і виводу відмінностей, не змушуючи lint-перевірки планувати мутації. Приклади: 
openclaw doctor --lint
openclaw doctor --lint --severity-min warning
openclaw doctor --lint --json
openclaw doctor --lint --all
openclaw doctor --lint --only core/doctor/gateway-config --json
Вивід JSON містить:
  • ok: чи будь-яка видима знахідка досягла вибраного порога серйозності
  • checksRun: кількість виконаних перевірок справності
  • checksSkipped: перевірки, пропущені вибраним профілем, --only або --skip
  • findings: структуровані діагностичні дані з checkId, severity, message та необов’язковими path, line, column, ocPath і fixHint
Коди виходу:
  • 0: немає знахідок на вибраному порозі або вище
  • 1: одна або більше знахідок досягли вибраного порога
  • 2: помилка команди/середовища виконання до того, як можна було вивести lint-знахідки
Використовуйте --severity-min info|warning|error, щоб керувати і тим, що друкується, і тим, що спричиняє ненульовий код виходу lint. Використовуйте --all, щоб запустити повний інвентар lint, включно з глибшими opt-in перевірками, виключеними з типового набору автоматизації. Використовуйте --only <id> для вузьких попередніх гейтів і --skip <id>, щоб тимчасово виключити шумну перевірку, зберігаючи решту lint-запуску активною. Параметри lint-виводу, як-от --json, --severity-min, --all, --only і --skip, мають використовуватися разом із --lint; звичайні запуски doctor і ремонту відхиляють їх.

​
Що він робить (підсумок)

  • Необов’язкове попереднє оновлення для git-встановлень (лише інтерактивно).
  • Перевірка актуальності UI-протоколу (перезбирає Control UI, коли схема протоколу новіша).
  • Перевірка справності + запит на перезапуск.
  • Підсумок стану Skills (придатні/відсутні/заблоковані) і стан Plugin.
  • Нормалізація конфігурації для застарілих значень.
  • Міграція конфігурації Talk із застарілих плоских полів talk.* у talk.provider + talk.providers.<provider>.
  • Перевірки міграції браузера для застарілих конфігурацій розширення Chrome і готовності Chrome MCP.
  • Попередження про перевизначення провайдера OpenCode (models.providers.opencode / models.providers.opencode-go).
  • Міграція застарілого провайдера/профілю OpenAI Codex (openai-codex → openai) і попередження про затінення для застарілих models.providers.openai-codex.
  • Перевірка передумов OAuth TLS для профілів OpenAI Codex OAuth.
  • Попередження allowlist Plugin/інструментів, коли plugins.allow обмежувальний, але політика інструментів усе ще просить wildcard або інструменти, якими володіє Plugin.
  • Міграція застарілого стану на диску (sessions/agent dir/автентифікація WhatsApp).
  • Міграція застарілих ключів контракту маніфесту Plugin (speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders, webSearchProviders → contracts).
  • Міграція застарілого сховища cron (jobId, schedule.cron, поля доставки/навантаження верхнього рівня, payload provider, резервні webhook-завдання notify: true).
  • Очищення застарілої runtime-політики всього агента; runtime-політика провайдера/моделі є активним селектором маршруту.
  • Очищення застарілої конфігурації Plugin, коли plugins увімкнено; коли plugins.enabled=false, застарілі посилання Plugin трактуються як інертна конфігурація стримування й зберігаються.
  • Перевірка файлів блокування сесій і очищення застарілих блокувань.
  • Ремонт транскриптів сесій для дубльованих гілок переписування промптів, створених ураженими збірками 2026.4.24.
  • Виявлення tombstone для відновлення після перезапуску завислого subagent, з підтримкою --fix для очищення застарілих aborted recovery flags, щоб startup не продовжував трактувати child як restart-aborted.
  • Перевірки цілісності стану та дозволів (сесії, транскрипти, каталог стану).
  • Перевірки дозволів файлу конфігурації (chmod 600) під час локального запуску.
  • Справність автентифікації моделі: перевіряє строк дії OAuth, може оновлювати токени, строк яких спливає, і повідомляє про стани cooldown/disabled auth-профілю.
  • Ремонт образу пісочниці, коли sandboxing увімкнено.
  • Міграція застарілого сервісу та виявлення додаткових gateway.
  • Міграція застарілого стану каналу Matrix (у режимі --fix / --repair).
  • Runtime-перевірки Gateway (сервіс встановлено, але не запущено; кешована launchd-мітка).
  • Попередження про стан каналу (пробуються із запущеного gateway).
  • Перевірки дозволів для конкретних каналів містяться в openclaw channels capabilities; наприклад, дозволи голосового каналу Discord перевіряються за допомогою openclaw channels capabilities --channel discord --target channel:<channel-id>.
  • Перевірки чутливості WhatsApp для погіршеного стану event-loop Gateway із локальними TUI-клієнтами, що все ще працюють; --fix зупиняє лише перевірені локальні TUI-клієнти.
  • Ремонт маршруту Codex для застарілих refs моделей openai-codex/* в основних моделях, fallback-моделях, моделях генерації зображень/відео, перевизначеннях heartbeat/subagent/compaction, hooks, перевизначеннях моделей каналів і pins маршрутів сесій; --fix переписує їх на openai/*, мігрує auth-профілі/порядок openai-codex:* до openai:*, видаляє застарілі runtime pins сесії/всього агента та залишає канонічні refs агентів OpenAI на типовому Codex harness.
  • Аудит конфігурації супервізора (launchd/systemd/schtasks) з необов’язковим ремонтом.
  • Очищення середовища вбудованого proxy для gateway-сервісів, які захопили значення shell HTTP_PROXY / HTTPS_PROXY / NO_PROXY під час встановлення або оновлення.
  • Перевірки найкращих практик runtime Gateway (Node проти Bun, шляхи version-manager).
  • Діагностика конфліктів порту Gateway (типово 18789).
  • Попередження безпеки для відкритих політик DM.
  • Перевірки автентифікації Gateway для режиму локального токена (пропонує генерацію токена, коли немає джерела токена; не перезаписує конфігурації token SecretRef).
  • Виявлення проблем pairing пристрою (очікувані запити першого pairing, очікувані оновлення ролі/обсягу, дрейф застарілого кешу локального device-token і дрейф автентифікації paired-record).
  • Перевірка systemd linger у Linux.
  • Перевірка розміру bootstrap-файлу робочого простору (попередження про обрізання/наближення до ліміту для context-файлів).
  • Перевірка готовності Skills для типового агента; повідомляє дозволені skills із відсутніми bins, env, config або вимогами ОС, а --fix може вимкнути недоступні skills у skills.entries.
  • Перевірка стану shell completion і автоматичне встановлення/оновлення.
  • Перевірка готовності провайдера embeddings для пошуку пам’яті (локальна модель, ключ віддаленого API або QMD-бінарник).
  • Перевірки встановлення з вихідного коду (невідповідність pnpm workspace, відсутні UI assets, відсутній tsx-бінарник).
  • Записує оновлену конфігурацію + метадані wizard.

​
Backfill і reset у Dreams UI

Сцена Control UI Dreams містить дії Backfill, Reset і Clear Grounded для grounded dreaming workflow. Ці дії використовують RPC-методи в стилі gateway doctor, але вони не є частиною ремонту/міграції CLI openclaw doctor. Що вони роблять:
  • Backfill сканує історичні файли memory/YYYY-MM-DD.md в активному робочому просторі, запускає grounded REM diary pass і записує оборотні backfill-записи в DREAMS.md.
  • Reset видаляє з DREAMS.md лише ці позначені backfill diary entries.
  • Clear Grounded видаляє лише staged grounded-only short-term entries, які походять з історичного replay і ще не накопичили live recall або daily support.
Чого вони не роблять самі по собі:
  • вони не редагують MEMORY.md
  • вони не запускають повні міграції doctor
  • вони не додають автоматично grounded candidates у live short-term promotion store, якщо ви явно не запустите спочатку staged CLI path
Якщо хочете, щоб grounded historical replay впливав на звичайну deep promotion lane, натомість використовуйте CLI-потік: 
openclaw memory rem-backfill --path ./memory --stage-short-term
Це додає grounded durable candidates у short-term dreaming store, залишаючи DREAMS.md поверхнею для review.

​
Детальна поведінка та обґрунтування

Якщо це git checkout і doctor запускається інтерактивно, він пропонує оновитися (fetch/rebase/build) перед запуском doctor.
Якщо конфігурація містить застарілі форми значень (наприклад, messages.ackReaction без перевизначення для конкретного каналу), doctor нормалізує їх у поточну схему.Це включає застарілі плоскі поля Talk. Поточна публічна конфігурація мовлення Talk — це talk.provider + talk.providers.<provider>, а realtime voice config — talk.realtime.*. Doctor переписує старі форми talk.voiceId / talk.voiceAliases / talk.modelId / talk.outputFormat / talk.apiKey у карту провайдера, а також переписує застарілі realtime-селектори верхнього рівня (talk.mode, talk.transport, talk.brain, talk.model, talk.voice) у talk.realtime.Діагностика також попереджає, коли plugins.allow непорожній, а політика інструментів використовує wildcard або записи інструментів, що належать Plugin. tools.allow: ["*"] відповідає лише інструментам із Plugin, які фактично завантажуються; він не обходить ексклюзивний список дозволених Plugin.
Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися й просять вас виконати openclaw doctor.Діагностика:
  • Пояснить, які застарілі ключі знайдено.
  • Покаже міграцію, яку вона застосувала.
  • Перезапише ~/.openclaw/openclaw.json з оновленою схемою.
Запуск Gateway відхиляє застарілі формати конфігурації та просить вас виконати openclaw doctor --fix; він не перезаписує openclaw.json під час запуску. Міграції сховища завдань Cron також обробляються через openclaw doctor --fix.Поточні міграції:
  • 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
  • видалення виведених з ужитку channels.webchat і gateway.webchat
  • routing.queue → messages.queue
  • routing.bindings → bindings верхнього рівня
  • routing.agents/routing.defaultAgentId → agents.list + agents.list[].default
  • застарілі talk.voiceId/talk.voiceAliases/talk.modelId/talk.outputFormat/talk.apiKey → talk.provider + talk.providers.<provider>
  • застарілі селектори Talk realtime верхнього рівня (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" і messages.tts.providers.edge → messages.tts.provider: "microsoft" і messages.tts.providers.microsoft
  • поля вибору мовця TTS (voice/voiceName/voiceId) → speakerVoice/speakerVoiceId
  • 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" і plugins.entries.voice-call.config.tts.providers.edge → provider: "microsoft" і 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
  • Для каналів з іменованими accounts, але залишковими значеннями каналу верхнього рівня для одного облікового запису, переміщення цих значень, прив’язаних до облікового запису, у підвищений обліковий запис, вибраний для цього каналу (accounts.default для більшості каналів; Matrix може зберегти наявну відповідну іменовану/типову ціль)
  • 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
  • видалення agents.defaults.llm; використовуйте models.providers.<id>.timeoutSeconds для тайм-аутів повільного постачальника/моделі та тримайте тайм-аут агента/запуску вище цього значення, коли весь запуск має тривати довше
  • browser.ssrfPolicy.allowPrivateNetwork → browser.ssrfPolicy.dangerouslyAllowPrivateNetwork
  • browser.profiles.*.driver: "extension" → "existing-session"
  • видалення browser.relayBindHost (застаріле налаштування ретранслятора розширення)
  • застаріле models.providers.*.api: "openai" → "openai-completions" (запуск Gateway також пропускає постачальників, у яких api встановлено на майбутнє або невідоме значення enum, замість аварійного закриття)
  • видалення plugins.entries.codex.config.codexDynamicToolsProfile; сервер застосунку Codex завжди залишає нативні інструменти робочого простору Codex нативними
Попередження діагностики також містять поради щодо типового облікового запису для каналів із кількома обліковими записами:
  • Якщо два або більше записів channels.<channel>.accounts налаштовано без channels.<channel>.defaultAccount або accounts.default, діагностика попереджає, що резервна маршрутизація може вибрати неочікуваний обліковий запис.
  • Якщо channels.<channel>.defaultAccount встановлено на невідомий ID облікового запису, діагностика попереджає та перелічує налаштовані ID облікових записів.
Якщо ви вручну додали models.providers.opencode, opencode-zen або opencode-go, це перевизначає вбудований каталог OpenCode з openclaw/plugin-sdk/llm. Це може примусово спрямувати моделі на неправильний API або обнулити витрати. Діагностика попереджає, щоб ви могли видалити перевизначення й відновити маршрутизацію API та витрати для кожної моделі.
Якщо ваша конфігурація браузера все ще вказує на видалений шлях розширення Chrome, діагностика нормалізує її до поточної моделі підключення Chrome MCP на локальному хості:
  • browser.profiles.*.driver: "extension" стає "existing-session"
  • browser.relayBindHost видаляється
Діагностика також перевіряє шлях Chrome MCP на локальному хості, коли ви використовуєте defaultProfile: "user" або налаштований профіль existing-session:
  • перевіряє, чи встановлено Google Chrome на тому самому хості для типових профілів автоматичного підключення
  • перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144
  • нагадує ввімкнути віддалене налагодження на сторінці інспектування браузера (наприклад, chrome://inspect/#remote-debugging, brave://inspect/#remote-debugging або edge://inspect/#remote-debugging)
Діагностика не може ввімкнути налаштування на боці Chrome замість вас. Chrome MCP на локальному хості все ще потребує:
  • браузера на основі Chromium 144+ на хості gateway/node
  • локально запущеного браузера
  • увімкненого віддаленого налагодження в цьому браузері
  • підтвердження першого запиту згоди на підключення в браузері
Готовність тут стосується лише локальних передумов підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от responsebody, експорт PDF, перехоплення завантажень і пакетні дії, усе ще потребують керованого браузера або профілю raw CDP.Ця перевірка не застосовується до Docker, sandbox, remote-browser або інших headless-потоків. Вони й надалі використовують raw CDP.
Коли налаштовано профіль OpenAI Codex OAuth, діагностика перевіряє кінцеву точку авторизації OpenAI, щоб підтвердити, що локальний стек Node/OpenSSL TLS може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад UNABLE_TO_GET_ISSUER_CERT_LOCALLY, прострочений сертифікат або самопідписаний сертифікат), діагностика друкує платформозалежні поради щодо виправлення. На macOS із Homebrew Node виправленням зазвичай є brew postinstall ca-certificates. З --deep перевірка виконується навіть тоді, коли gateway справний.
Якщо раніше ви додали застарілі налаштування транспорту OpenAI у models.providers.openai-codex, вони можуть затіняти вбудований шлях постачальника Codex OAuth, який новіші випуски використовують автоматично. Діагностика попереджає, коли бачить ці старі налаштування транспорту поруч із Codex OAuth, щоб ви могли видалити або переписати застаріле перевизначення транспорту й повернути вбудовану маршрутизацію/резервну поведінку. Користувацькі проксі та перевизначення лише заголовків усе ще підтримуються й не спричиняють цього попередження.
Діагностика перевіряє наявність застарілих посилань на моделі openai-codex/*. Нативна маршрутизація harness Codex використовує канонічні посилання на моделі openai/*; ходи агента OpenAI проходять через harness сервера застосунку Codex замість шляху постачальника OpenAI в OpenClaw.У режимі --fix / --repair діагностика переписує зачеплені посилання типового агента та окремих агентів, зокрема основні моделі, резервні моделі, моделі генерації зображень/відео, перевизначення heartbeat/subagent/compaction, hooks, перевизначення моделей каналів і застарілий збережений стан маршрутів сеансів:
  • openai-codex/gpt-* стає openai/gpt-*.
  • Намір Codex переноситься до записів agentRuntime.id: "codex" в області постачальника/моделі для відновлених посилань на моделі агента.
  • Застаріла конфігурація runtime для всього агента та збережені прив’язки runtime сеансів видаляються, оскільки вибір runtime прив’язаний до постачальника/моделі.
  • Наявна політика runtime постачальника/моделі зберігається, якщо відновлене застаріле посилання на модель не потребує маршрутизації Codex, щоб зберегти старий шлях автентифікації.
  • Наявні списки резервних моделей зберігаються з переписаними застарілими записами; скопійовані налаштування окремих моделей переносяться із застарілого ключа до канонічного ключа openai/*.
  • Збережені сеансові modelProvider/providerOverride, model/modelOverride, сповіщення про резервні варіанти та прив’язки профілів автентифікації відновлюються в усіх виявлених сховищах сеансів агентів.
  • /codex ... означає “керувати або прив’язати нативну розмову Codex із чату.”
  • /acp ... або runtime: "acp" означає “використовувати зовнішній адаптер ACP/acpx.”
Діагностика також сканує виявлені сховища сеансів агентів на застарілий автоматично створений стан маршрутів після того, як ви переміщуєте налаштовані моделі або runtime подалі від маршруту, що належить Plugin, наприклад Codex.openclaw doctor --fix може очистити автоматично створений застарілий стан, як-от прив’язки моделей modelOverrideSource: "auto", метадані runtime моделей, закріплені ID harness, прив’язки сеансів CLI та автоматичні перевизначення профілів автентифікації, коли їхній власний маршрут більше не налаштований. Явні користувацькі або застарілі вибори моделей сеансу повідомляються для ручної перевірки й залишаються без змін; перемкніть їх за допомогою /model ..., /new або скиньте сеанс, коли цей маршрут більше не потрібен.
Діагностика може мігрувати старіші структури на диску до поточної структури:
  • Сховище сеансів + транскрипти:
    • з ~/.openclaw/sessions/ до ~/.openclaw/agents/<agentId>/sessions/
  • Каталог агента:
    • з ~/.openclaw/agent/ до ~/.openclaw/agents/<agentId>/agent/
  • Стан автентифікації WhatsApp (Baileys):
    • із застарілих ~/.openclaw/credentials/*.json (крім oauth.json)
    • до ~/.openclaw/credentials/whatsapp/<accountId>/... (ID типового облікового запису: default)
Ці міграції виконуються за принципом найкращих зусиль і є ідемпотентними; діагностика виводитиме попередження, коли залишає будь-які застарілі папки як резервні копії. Gateway/CLI також автоматично мігрує застарілі сеанси + каталог агента під час запуску, щоб історія/автентифікація/моделі потрапили до шляху окремого агента без ручного запуску діагностики. Автентифікація WhatsApp навмисно мігрується лише через openclaw doctor. Нормалізація постачальника/мапи постачальників Talk тепер порівнює за структурною рівністю, тому відмінності лише в порядку ключів більше не запускають повторні noop-зміни doctor --fix.
Doctor сканує всі встановлені маніфести Plugin на наявність застарілих ключів можливостей верхнього рівня (speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders, webSearchProviders). Коли їх знайдено, він пропонує перемістити їх в об’єкт contracts і перезаписати файл маніфесту на місці. Ця міграція є ідемпотентною; якщо ключ contracts уже має ті самі значення, застарілий ключ видаляється без дублювання даних.
Doctor також перевіряє сховище завдань Cron (~/.openclaw/cron/jobs.json за замовчуванням або cron.store, якщо перевизначено) на наявність старих форм завдань, які планувальник усе ще приймає для сумісності.Поточні очищення Cron включають:
  • jobId → id
  • schedule.cron → schedule.expr
  • поля корисного навантаження верхнього рівня (message, model, thinking, …) → payload
  • поля доставки верхнього рівня (deliver, channel, to, provider, …) → delivery
  • псевдоніми доставки provider у корисному навантаженні → явний delivery.channel
  • застарілі резервні завдання Webhook із notify: true → явна доставка Webhook з cron.webhook, коли задано; завдання оголошень зберігають свою доставку в чат і отримують delivery.completionDestination. Коли cron.webhook не задано, інертний маркер верхнього рівня notify видаляється для завдань без цілі (наявна доставка, включно з оголошеннями, зберігається), оскільки доставка під час виконання ніколи його не читає
Gateway також санітизує некоректні рядки Cron під час завантаження, щоб коректні завдання продовжували виконуватися. Сирі некоректні рядки копіюються до jobs-quarantine.json поруч з активним сховищем перед видаленням із jobs.json; doctor повідомляє про рядки в карантині, щоб ви могли переглянути або виправити їх вручну.Запуск Gateway нормалізує проєкцію часу виконання й ігнорує маркер верхнього рівня notify, але залишає збережену конфігурацію Cron для виправлення doctor. Коли cron.webhook не задано, doctor видаляє інертний маркер для завдань без цілі міграції (delivery.mode none/відсутній, непридатна ціль Webhook або наявна доставка оголошення/чату), залишаючи наявну доставку без змін, тому повторні запуски doctor --fix більше не попереджають про те саме завдання. Якщо cron.webhook задано, але це не коректна URL-адреса HTTP(S), doctor усе одно попереджає й залишає маркер, щоб ви могли виправити URL.У Linux doctor також попереджає, коли crontab користувача все ще викликає застарілий ~/.openclaw/bin/ensure-whatsapp.sh. Цей локальний для хоста сценарій не підтримується поточним OpenClaw і може записувати хибні повідомлення Gateway inactive до ~/.openclaw/logs/whatsapp-health.log, коли Cron не може дістатися до користувацької шини systemd. Видаліть застарілий запис crontab за допомогою crontab -e; використовуйте openclaw channels status --probe, openclaw doctor і openclaw gateway status для поточних перевірок працездатності.
Doctor сканує кожен каталог сеансу агента на наявність застарілих файлів блокування запису — файлів, що залишилися після аварійного завершення сеансу. Для кожного знайденого файлу блокування він повідомляє: шлях, PID, чи PID досі активний, вік блокування та чи вважається воно застарілим (мертвий PID, некоректні метадані власника, старше 30 хвилин або активний PID, для якого можна довести, що він належить процесу не OpenClaw). У режимі --fix / --repair він автоматично видаляє блокування з мертвими, осиротілими, повторно використаними, некоректними старими або не OpenClaw власниками. Старі блокування, якими все ще володіє активний процес OpenClaw, повідомляються, але залишаються на місці, щоб doctor не обірвав активний записувач транскрипту.
Doctor сканує JSONL-файли сеансів агентів на дубльовану форму гілки, створену помилкою переписування транскрипту prompt від 2026.4.24: покинутий користувацький хід із внутрішнім контекстом часу виконання OpenClaw плюс активний sibling із тим самим видимим користувацьким prompt. У режимі --fix / --repair doctor створює резервну копію кожного зачепленого файлу поруч з оригіналом і переписує транскрипт до активної гілки, щоб історія Gateway і читачі пам’яті більше не бачили дубльованих ходів.
Каталог стану — це операційний стовбур мозку. Якщо він зникне, ви втратите сеанси, облікові дані, журнали й конфігурацію (якщо не маєте резервних копій деінде).Doctor перевіряє:
  • Каталог стану відсутній: попереджає про катастрофічну втрату стану, пропонує повторно створити каталог і нагадує, що не може відновити відсутні дані.
  • Дозволи каталогу стану: перевіряє можливість запису; пропонує виправити дозволи (і виводить підказку chown, коли виявлено невідповідність власника/групи).
  • Синхронізований із хмарою каталог стану macOS: попереджає, коли стан розміщується в iCloud Drive (~/Library/Mobile Documents/com~apple~CloudDocs/...) або ~/Library/CloudStorage/..., бо шляхи з синхронізацією можуть спричиняти повільніший I/O і перегони блокування/синхронізації.
  • Каталог стану Linux на SD або eMMC: попереджає, коли стан розміщується на джерелі монтування mmcblk*, бо випадковий I/O на SD або eMMC може бути повільнішим і швидше зношувати носій під час записів сеансів та облікових даних.
  • Волатильний каталог стану Linux: попереджає, коли стан розміщується на tmpfs або ramfs, бо сеанси, облікові дані, конфігурація та стан SQLite з його супровідними файлами WAL/журналу зникнуть після перезавантаження. Монтування Docker overlay навмисно не позначаються, бо їхні записувані шари зберігаються після перезавантажень хоста, доки контейнер залишається.
  • Каталоги сеансів відсутні: sessions/ і каталог сховища сеансів потрібні для збереження історії та уникнення збоїв ENOENT.
  • Невідповідність транскрипту: попереджає, коли нещодавні записи сеансів мають відсутні файли транскриптів.
  • Головний сеанс “1-line JSONL”: позначає, коли головний транскрипт має лише один рядок (історія не накопичується).
  • Кілька каталогів стану: попереджає, коли кілька папок ~/.openclaw існують у різних домашніх каталогах або коли OPENCLAW_STATE_DIR вказує в інше місце (історія може розділитися між інсталяціями).
  • Нагадування про віддалений режим: якщо gateway.mode=remote, doctor нагадує запустити його на віддаленому хості (стан живе там).
  • Дозволи файлу конфігурації: попереджає, якщо ~/.openclaw/openclaw.json доступний для читання групі/всім, і пропонує звузити дозволи до 600.
Doctor перевіряє профілі OAuth у сховищі автентифікації, попереджає, коли токени скоро завершаться або вже завершилися, і може оновити їх, коли це безпечно. Якщо профіль Anthropic OAuth/токена застарів, він пропонує API-ключ Anthropic або шлях setup-token Anthropic. Запити на оновлення з’являються лише під час інтерактивного запуску (TTY); --non-interactive пропускає спроби оновлення.Коли оновлення OAuth завершується остаточною невдачею (наприклад, refresh_token_reused, invalid_grant або провайдер повідомляє, що потрібно ввійти знову), doctor повідомляє, що потрібна повторна автентифікація, і друкує точну команду openclaw models auth login --provider ..., яку слід виконати.Doctor також повідомляє про профілі автентифікації, які тимчасово непридатні через:
  • короткі cooldowns (обмеження частоти/тайм-аути/збої автентифікації)
  • довші вимкнення (збої білінгу/кредитів)
Застарілі профілі Codex OAuth, чиї токени живуть у macOS Keychain (старіше onboarding до файлового sidecar layout), виправляються лише doctor. Запустіть openclaw doctor --fix один раз з інтерактивного термінала, щоб мігрувати застарілі токени з Keychain безпосередньо в auth-profiles.json; після цього вбудовані ходи (Telegram, Cron, dispatch під-агента) розв’язують їх як канонічні профілі OpenAI OAuth.
Якщо hooks.gmail.model задано, doctor перевіряє посилання на модель за каталогом і allowlist та попереджає, коли воно не розв’яжеться або заборонене.
Коли sandboxing увімкнено, doctor перевіряє образи Docker і пропонує зібрати або перемкнутися на застарілі назви, якщо поточного образу бракує.
Doctor видаляє застарілий створений OpenClaw проміжний стан залежностей Plugin у режимі openclaw doctor --fix / openclaw doctor --repair. Це охоплює застарілі згенеровані корені залежностей, старі каталоги етапу встановлення, локальні для пакета залишки від попереднього коду виправлення залежностей bundled-plugin, а також осиротілі або відновлені керовані npm-копії bundled @openclaw/* plugins, які можуть затіняти поточний bundled маніфест. Doctor також повторно зв’язує хостовий пакет openclaw у керовані npm plugins, які оголошують peerDependencies.openclaw, щоб локальні для пакета імпорти часу виконання, як-от openclaw/plugin-sdk/*, продовжували розв’язуватися після оновлень або виправлень npm.Doctor також може перевстановлювати відсутні завантажувані plugins, коли конфігурація посилається на них, але локальний реєстр Plugin не може їх знайти. Приклади включають матеріальні plugins.entries, налаштовані параметри каналу/провайдера/пошуку та налаштовані середовища виконання агентів. Під час оновлень пакета doctor уникає запуску виправлення Plugin через package manager, доки core package замінюється; запустіть openclaw doctor --fix знову після оновлення, якщо налаштований Plugin усе ще потребує відновлення. Запуск Gateway і перезавантаження конфігурації не запускають package managers; встановлення Plugin залишаються явною роботою doctor/install/update.
Doctor виявляє застарілі служби Gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити службу OpenClaw з поточним портом Gateway. Він також може сканувати додаткові служби, схожі на Gateway, і друкувати підказки з очищення. Служби Gateway OpenClaw, названі за профілем, вважаються першокласними й не позначаються як “extra.”У Linux, якщо служба Gateway рівня користувача відсутня, але існує служба Gateway OpenClaw системного рівня, doctor не встановлює другу службу рівня користувача автоматично. Перевірте за допомогою openclaw gateway status --deep або openclaw doctor --deep, потім видаліть дублікат або задайте OPENCLAW_SERVICE_REPAIR_POLICY=external, коли системний supervisor володіє життєвим циклом Gateway.
Коли обліковий запис каналу Matrix має очікувану або придатну до дії застарілу міграцію стану, doctor (у режимі --fix / --repair) створює знімок перед міграцією, а потім виконує best-effort кроки міграції: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки журналюються, і запуск продовжується. У режимі лише читання (openclaw doctor без --fix) ця перевірка повністю пропускається.
Doctor тепер перевіряє стан сполучення пристроїв як частину звичайного проходу перевірки працездатності.Що він повідомляє:
  • очікувані запити першого сполучення
  • очікувані підвищення ролі для вже сполучених пристроїв
  • очікувані підвищення scope для вже сполучених пристроїв
  • виправлення невідповідності public-key, коли id пристрою все ще збігається, але ідентичність пристрою більше не відповідає схваленому запису
  • сполучені записи, яким бракує активного токена для схваленої ролі
  • сполучені токени, чиї scopes відхиляються від схваленої базової лінії сполучення
  • локальні кешовані записи device-token для поточної машини, які передують ротації токена на боці Gateway або містять застарілі метадані scope
Doctor не схвалює автоматично запити на сполучення і не ротує device tokens автоматично. Натомість він друкує точні наступні кроки:
  • переглянути очікувані запити за допомогою openclaw devices list
  • схвалити точний запит за допомогою openclaw devices approve <requestId>
  • ротувати свіжий токен за допомогою openclaw devices rotate --device <deviceId> --role <role>
  • видалити й повторно схвалити застарілий запис за допомогою openclaw devices remove <deviceId>
Це закриває поширену прогалину “вже спарено, але все ще отримується вимога спарювання”: doctor тепер відрізняє перше спарювання від очікуваних підвищень ролі/області дії та від застарілого дрейфу токена/ідентичності пристрою.
Doctor видає попередження, коли provider відкритий для DM без списку дозволених, або коли політику налаштовано небезпечним способом.
Якщо працює як користувацький сервіс systemd, doctor перевіряє, що linger увімкнено, щоб gateway залишався активним після виходу з системи.
Doctor друкує підсумок стану робочої області для типового агента:
  • Стан Skills: рахує eligible, missing-requirements і allowlist-blocked skills.
  • Стан Plugin: рахує enabled/disabled/errored plugins; перелічує ID plugins для будь-яких помилок; повідомляє можливості bundle plugin.
  • Попередження сумісності Plugin: позначає plugins, які мають проблеми сумісності з поточним runtime.
  • Діагностика Plugin: показує будь-які попередження або помилки під час завантаження, видані реєстром plugin.
  • Відновлення TaskFlow: показує підозрілі керовані TaskFlows, які потребують ручної перевірки або скасування.
Doctor перевіряє, чи bootstrap-файли робочої області (наприклад AGENTS.md, CLAUDE.md або інші інжектовані файли контексту) наближаються до налаштованого бюджету символів або перевищують його. Він повідомляє для кожного файлу сирі та інжектовані кількості символів, відсоток обрізання, причину обрізання (max/file або max/total) і загальну кількість інжектованих символів як частку від загального бюджету. Коли файли обрізано або вони близькі до ліміту, doctor друкує поради щодо налаштування agents.defaults.bootstrapMaxChars і agents.defaults.bootstrapTotalMaxChars.
Коли openclaw doctor --fix видаляє відсутній channel plugin, він також видаляє завислу конфігурацію з областю дії каналу, яка посилалася на цей plugin: записи channels.<id>, цілі Heartbeat, які називали канал, і перевизначення agents.*.models["<channel>/*"]. Це запобігає циклам завантаження Gateway, коли runtime каналу зник, але конфігурація все ще просить gateway прив’язатися до нього.
Doctor перевіряє, чи встановлено автодоповнення Tab для поточного shell (zsh, bash, fish або PowerShell):
  • Якщо профіль shell використовує повільний динамічний шаблон автодоповнення (source <(openclaw completion ...)), doctor оновлює його до швидшого варіанта з кешованим файлом.
  • Якщо автодоповнення налаштовано в профілі, але файл кешу відсутній, doctor автоматично регенерує кеш.
  • Якщо автодоповнення взагалі не налаштовано, doctor пропонує встановити його (лише інтерактивний режим; пропускається з --non-interactive).
Запустіть openclaw completion --write-state, щоб регенерувати кеш вручну.
Doctor перевіряє готовність локальної token auth gateway.
  • Якщо режим токена потребує токена, а джерела токена немає, doctor пропонує згенерувати його.
  • Якщо gateway.auth.token керується SecretRef, але недоступний, doctor попереджає й не перезаписує його відкритим текстом.
  • openclaw doctor --generate-gateway-token примусово генерує токен лише тоді, коли не налаштовано SecretRef токена.
Деякі потоки ремонту мають перевіряти налаштовані облікові дані, не послаблюючи runtime-поведінку fail-fast.
  • openclaw doctor --fix тепер використовує ту саму модель підсумку SecretRef лише для читання, що й команди сімейства status, для цільових ремонтів конфігурації.
  • Приклад: ремонт Telegram allowFrom / groupAllowFrom @username намагається використати налаштовані облікові дані бота, коли вони доступні.
  • Якщо токен бота Telegram налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає автоматичне розв’язання замість аварійного завершення або хибного повідомлення, що токен відсутній.
Doctor запускає перевірку працездатності та пропонує перезапустити gateway, коли він виглядає несправним.
Doctor перевіряє, чи налаштований provider embedding для пошуку пам’яті готовий для типового агента. Поведінка залежить від налаштованого backend і provider:
  • Backend QMD: перевіряє, чи доступний і запускний binary qmd. Якщо ні, друкує вказівки для виправлення, зокрема npm package і опцію ручного шляху до binary.
  • Явний локальний provider: перевіряє наявність локального файлу моделі або розпізнаної URL віддаленої/завантажуваної моделі. Якщо бракує, пропонує перемкнутися на віддалений provider.
  • Явний віддалений provider (openai, voyage тощо): перевіряє, що API key наявний у середовищі або auth store. Друкує дієві підказки для виправлення, якщо його бракує.
  • Застарілий auto provider: трактує memorySearch.provider: "auto" як OpenAI, перевіряє готовність OpenAI, а doctor --fix переписує це на provider: "openai".
Коли доступний кешований результат probe gateway (gateway був справний на момент перевірки), doctor зіставляє його результат із конфігурацією, видимою для CLI, і зазначає будь-яку розбіжність. Doctor не запускає свіжий embedding ping у типовому шляху; використовуйте команду глибокого статусу пам’яті, коли потрібна жива перевірка provider.Використовуйте openclaw memory status --deep, щоб перевірити готовність embedding під час runtime.
Якщо gateway справний, doctor запускає probe стану каналу та повідомляє попередження із запропонованими виправленнями.
Doctor перевіряє встановлену конфігурацію supervisor (launchd/systemd/schtasks) на відсутні або застарілі типові значення (наприклад, залежності systemd від network-online і затримку перезапуску). Коли знаходить невідповідність, рекомендує оновлення й може переписати файл сервісу/завдання до поточних типових значень.Примітки:
  • openclaw doctor запитує підтвердження перед переписуванням конфігурації supervisor.
  • openclaw doctor --yes приймає типові запити на ремонт.
  • openclaw doctor --fix застосовує рекомендовані виправлення без запитів (--repair є псевдонімом).
  • openclaw doctor --fix --force перезаписує власні конфігурації supervisor.
  • OPENCLAW_SERVICE_REPAIR_POLICY=external зберігає doctor у режимі лише для читання для життєвого циклу сервісу gateway. Він усе ще повідомляє про працездатність сервісу й запускає ремонти, не пов’язані із сервісом, але пропускає install/start/restart/bootstrap сервісу, переписування конфігурації supervisor і очищення legacy service, оскільки цей життєвий цикл належить зовнішньому supervisor.
  • У Linux doctor не переписує command/entrypoint metadata, доки відповідний systemd gateway unit активний. Він також ігнорує неактивні non-legacy додаткові gateway-like units під час сканування duplicate-service, щоб супутні service files не створювали шум очищення.
  • Якщо token auth потребує токена, а gateway.auth.token керується SecretRef, install/repair сервісу doctor перевіряє SecretRef, але не зберігає розв’язані plaintext token values у metadata середовища supervisor service.
  • Doctor виявляє керовані значення середовища сервісу на основі .env/SecretRef, які старіші встановлення LaunchAgent, systemd або Windows Scheduled Task вбудували inline, і переписує metadata сервісу так, щоб ці значення завантажувалися з runtime source замість визначення supervisor.
  • Doctor виявляє, коли command сервісу все ще фіксує старий --port після зміни gateway.port, і переписує metadata сервісу на поточний порт.
  • Якщо token auth потребує токена, а налаштований токен SecretRef не розв’язано, doctor блокує шлях install/repair з дієвими вказівками.
  • Якщо одночасно налаштовано gateway.auth.token і gateway.auth.password, а gateway.auth.mode не встановлено, doctor блокує install/repair, доки режим не буде встановлено явно.
  • Для Linux user-systemd units перевірки дрейфу токена doctor тепер включають джерела і Environment=, і EnvironmentFile= під час порівняння auth metadata сервісу.
  • Ремонти сервісу doctor відмовляються переписувати, зупиняти або перезапускати сервіс gateway зі старішого binary OpenClaw, коли конфігурацію востаннє записала новіша версія. Див. Усунення несправностей Gateway.
  • Ви завжди можете примусово виконати повне переписування через openclaw gateway install --force.
Doctor перевіряє runtime сервісу (PID, останній exit status) і попереджає, коли сервіс встановлено, але він фактично не запущений. Він також перевіряє конфлікти портів на порту gateway (типово 18789) і повідомляє ймовірні причини (gateway уже запущено, SSH tunnel).
Doctor попереджає, коли сервіс gateway працює на Bun або шляху Node, керованому версіями (nvm, fnm, volta, asdf тощо). Канали WhatsApp + Telegram потребують Node, а шляхи менеджера версій можуть ламатися після оновлень, бо сервіс не завантажує ваш shell init. Doctor пропонує мігрувати на системне встановлення Node, коли воно доступне (Homebrew/apt/choco).Нововстановлені або відремонтовані macOS LaunchAgents використовують канонічний системний PATH (/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin) замість копіювання PATH інтерактивного shell, тож системні binary, керовані Homebrew, залишаються доступними, тоді як каталоги Volta, asdf, fnm, pnpm та інших менеджерів версій не змінюють, який Node розв’язують дочірні процеси. Сервіси Linux все ще зберігають явні корені середовища (NVM_DIR, FNM_DIR, VOLTA_HOME, ASDF_DATA_DIR, BUN_INSTALL, PNPM_HOME) і стабільні user-bin directories, але вгадані fallback directories менеджера версій записуються до PATH сервісу лише тоді, коли ці каталоги існують на диску.
Doctor зберігає будь-які зміни конфігурації та ставить штамп metadata майстра, щоб записати запуск doctor.
Doctor пропонує систему пам’яті робочої області, коли її бракує, і друкує пораду щодо резервного копіювання, якщо робоча область ще не перебуває під git.Див. /concepts/agent-workspace для повного посібника зі структури робочої області та резервного копіювання git (рекомендовано приватний GitHub або GitLab).

​
Пов’язане