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

​
Швидкий початок

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

Прийняти типові параметри без запитів (зокрема кроки перезапуску, відновлення служби та пісочниці, коли це застосовно).
Щоб переглянути зміни перед записом, спочатку відкрийте файл конфігурації:

​
Режим перевірки лише для читання

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

​
Що він робить (стисло)

  • Необов’язкова попередня перевірка оновлення для інсталяцій із git (лише інтерактивно).
  • Перевірка актуальності протоколу інтерфейсу (повторно збирає Control UI, якщо схема протоколу новіша).
  • Перевірка працездатності та запит на перезапуск.
  • Примітки лише про проблемні Skills і плагіни; перелік справних компонентів залишається в openclaw skills check і openclaw plugins list.
  • Нормалізація конфігурації для застарілих форм значень.
  • Міграція конфігурації розмови із застарілих плоских полів talk.* до talk.provider + talk.providers.<provider>.
  • Перевірки міграції браузера для застарілих конфігурацій розширення Chrome та готовності Chrome MCP.
  • Попередження про перевизначення провайдера OpenCode (models.providers.opencode / opencode-zen / opencode-go).
  • Міграція застарілого провайдера/профілю OpenAI Codex (openai-codex → openai) і попередження про перекриття через застарілий models.providers.openai-codex.
  • Перевірка передумов TLS для профілів OAuth OpenAI Codex.
  • Попередження про списки дозволених плагінів/інструментів, коли plugins.allow має обмеження, але політика інструментів усе ще запитує символ узагальнення або інструменти, що належать плагінам.
  • Міграція застарілого стану на диску (сеанси/каталог агента/автентифікація WhatsApp).
  • Міграція застарілих ключів контракту маніфесту плагіна (speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders, webSearchProviders → contracts).
  • Міграція застарілого сховища Cron (jobId, schedule.cron, поля доставлення/корисного навантаження верхнього рівня, provider корисного навантаження, резервні завдання Webhook notify: true).
  • Виправлення фіксації середовища виконання Codex CLI (agentRuntime.id: "codex-cli" → "codex") у agents.defaults, agents.list[] і models.providers.* (зокрема записи для окремих моделей).
  • Очищення застарілої конфігурації плагінів, коли плагіни ввімкнені; коли plugins.enabled=false, застарілі посилання на плагіни зберігаються як неактивна ізоляційна конфігурація.
  • Перевірка файлів блокування сеансів та очищення застарілих блокувань.
  • Відновлення журналів сеансів із дубльованими гілками переписування запитів, створеними ураженими збірками 2026.4.24.
  • Виявлення маркерів відновлення після перезапуску завислих підагентів із підтримкою --fix для очищення застарілих прапорців перерваного відновлення, щоб під час запуску дочірній процес не вважався й надалі перерваним через перезапуск.
  • Перевірки цілісності стану та дозволів (сеанси, журнали, каталог стану).
  • Перевірки дозволів файла конфігурації (chmod 600) під час локального запуску.
  • Стан автентифікації моделі: перевіряє завершення строку дії OAuth, може оновлювати токени, строк дії яких завершується, і повідомляє про стани затримки/вимкнення профілю автентифікації.
  • Відновлення образу пісочниці, коли ізоляцію ввімкнено.
  • Міграція застарілих служб і виявлення додаткових Gateway.
  • Міграція застарілого стану каналу Matrix (у режимі --fix / --repair).
  • Перевірки середовища виконання Gateway (службу встановлено, але не запущено; кешована мітка launchd).
  • Попередження про стан каналів (отримані через перевірку запущеного Gateway).
  • Перевірки дозволів для окремих каналів містяться в openclaw channels capabilities; наприклад, дозволи голосового каналу Discord перевіряються за допомогою openclaw channels capabilities --channel discord --target channel:<channel-id>.
  • Перевірки швидкості відгуку WhatsApp для погіршеного стану циклу подій Gateway, коли локальні клієнти TUI ще працюють; --fix зупиняє лише перевірені локальні клієнти TUI.
  • Виправлення маршрутів Codex для застарілих посилань на моделі openai-codex/* в основних моделях, резервних варіантах, моделях генерації зображень/відео, перевизначеннях Heartbeat/підагентів/Compaction, хуках, перевизначеннях моделей каналів і фіксаціях маршрутів сеансів; --fix переписує їх на openai/*, переносить профілі/порядок автентифікації openai-codex:* до openai:*, видаляє застарілі фіксації середовища виконання для сеансу/всього агента та дає виправленому ефективному маршруту визначити сумісність Codex.
  • Аудит конфігурації супервізора (launchd/systemd/schtasks) із необов’язковим виправленням.
  • Очищення змінних середовища вбудованого проксі для служб Gateway, які зберегли значення оболонки HTTP_PROXY / HTTPS_PROXY / NO_PROXY під час встановлення чи оновлення.
  • Перевірки середовища виконання Gateway (непідтримувані застарілі служби Bun, шляхи менеджера версій).
  • Діагностика конфліктів портів Gateway (типово 18789).
  • Попередження безпеки для відкритих політик особистих повідомлень.
  • Перевірки автентифікації Gateway для локального режиму токена (пропонує згенерувати токен, якщо джерела токена немає; не перезаписує конфігурації SecretRef токена).
  • Виявлення проблем зі сполученням пристроїв (очікувані запити на перше сполучення, очікувані оновлення ролі/області, розбіжність застарілого локального кешу токенів пристроїв і розбіжність автентифікації в записах сполучення).
  • Перевірка linger systemd у Linux.
  • Перевірка розміру файлів початкового налаштування робочого простору (попередження про обрізання/наближення до обмеження для файлів контексту).
  • Перевірка готовності Skills для типового агента; повідомляє про дозволені навички, для яких бракує виконуваних файлів, змінних середовища, конфігурації або вимог ОС, а --fix може вимкнути недоступні навички в skills.entries.
  • Перевірка стану автодоповнення оболонки та автоматичне встановлення/оновлення.
  • Перевірка готовності провайдера векторних подань для пошуку в пам’яті (локальна модель, ключ віддаленого API або виконуваний файл QMD).
  • Перевірки інсталяції з вихідного коду (невідповідність робочого простору pnpm, відсутні ресурси інтерфейсу, відсутній виконуваний файл tsx).
  • Записує оновлену конфігурацію та метадані майстра.

​
Заповнення та скидання інтерфейсу Dreams

Сцена Dreams в Control UI містить дії Backfill, Reset і Clear Grounded для робочого процесу grounded dreaming. Вони використовують RPC-методи Gateway у стилі doctor, але не є частиною відновлення або міграції CLI openclaw doctor. Жодна з цих дій не редагує MEMORY.md, не запускає повні міграції doctor і самостійно не додає grounded-кандидатів до активного сховища просування короткострокової пам’яті. Щоб спрямувати grounded-історичне відтворення до звичайного конвеєра глибокого просування, натомість скористайтеся CLI:
Це додає grounded-кандидатів для тривалого зберігання до короткострокового сховища dreaming, тоді як DREAMS.md залишається поверхнею для перевірки.

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

Якщо це робоча копія git і doctor працює інтерактивно, перед запуском doctor він пропонує виконати оновлення (fetch/rebase/build).
Doctor нормалізує застарілі форми значень відповідно до поточної схеми. Поточна конфігурація мовлення Talk — це talk.provider + talk.providers.<provider>, а конфігурація голосу в реальному часі розташована в talk.realtime.*. Doctor перетворює старі форми talk.voiceId / talk.voiceAliases / talk.modelId / talk.outputFormat / talk.apiKey на мапу провайдерів, а застарілі селектори реального часу верхнього рівня (talk.mode, talk.transport, talk.brain, talk.model, talk.voice) — на talk.realtime.Doctor також попереджає, коли plugins.allow не порожній, а політика інструментів використовує символ підстановки або записи інструментів, що належать плагінам. tools.allow: ["*"] зіставляє лише інструменти з плагінів, які фактично завантажуються; він не обходить ексклюзивний список дозволених плагінів.
Якщо конфігурація містить застарілий ключ з активною міграцією, інші команди відмовляються запускатися та просять виконати openclaw doctor. Doctor пояснює, які застарілі ключі знайдено, показує застосовану міграцію та перезаписує ~/.openclaw/openclaw.json за оновленою схемою. Під час запуску Gateway відхиляє застарілі формати конфігурації та просить виконати openclaw doctor --fix; він не перезаписує openclaw.json під час запуску. Міграції сховища завдань Cron також виконує openclaw doctor --fix.
Doctor підтримує автоматичні міграції лише протягом приблизно двох місяців після вилучення ключа. Для давніших застарілих ключів (наприклад, початкових routing.queue, routing.bindings, routing.agents/defaultAgentId, routing.transcribeAudio, верхньорівневого agent.* або верхньорівневого identity з форми конфігурації до запровадження кількох агентів) шлях міграції більше не передбачений; конфігурація з ними тепер не проходить перевірку замість перезаписування. Виправте ці ключі вручну відповідно до поточної довідки з конфігурації, перш ніж doctor зможе продовжити.
Активні міграції:
Наведені вище рядки plugins.entries.voice-call.config.* нормалізує сам плагін Voice Call під час кожного завантаження конфігурації, а не openclaw doctor. Плагін також записує під час запуску попередження з посиланням на openclaw doctor --fix, але наразі doctor не перезаписує openclaw.json для цих ключів; зміну під час виконання застосовує власна нормалізація плагіна.
Настанови щодо облікового запису за замовчуванням для каналів із кількома обліковими записами:
  • Якщо налаштовано два або більше записів channels.<channel>.accounts без channels.<channel>.defaultAccount або accounts.default, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний обліковий запис.
  • Якщо для channels.<channel>.defaultAccount задано невідомий ідентифікатор облікового запису, doctor попереджає про це та перелічує ідентифікатори налаштованих облікових записів.
Якщо ви вручну додали models.providers.opencode, opencode-zen або opencode-go, це перевизначає вбудований каталог OpenCode з openclaw/plugin-sdk/llm. Через це моделі можуть використовувати неправильний API, а їхня вартість може обнулитися. Doctor попереджає про це, щоб можна було видалити перевизначення та відновити маршрутизацію API й вартість для кожної моделі.
Якщо конфігурація браузера досі вказує на видалений шлях розширення Chrome, doctor нормалізує її відповідно до поточної моделі локального для хоста підключення Chrome MCP (browser.profiles.*.driver: "extension" → "existing-session"; browser.relayBindHost видалено).Doctor також перевіряє локальний для хоста шлях Chrome MCP, коли використовується defaultProfile: "user" або налаштований профіль existing-session:
  • перевіряє, чи встановлено Google Chrome на тому самому хості для стандартних профілів автоматичного підключення
  • перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144
  • нагадує ввімкнути віддалене налагодження на сторінці перевірки браузера (наприклад, chrome://inspect/#remote-debugging, brave://inspect/#remote-debugging або edge://inspect/#remote-debugging)
Doctor не може ввімкнути параметр на боці Chrome замість вас. Для локального для хоста Chrome MCP усе одно потрібен браузер на основі Chromium версії 144+ на хості gateway/node, запущений локально, з увімкненим віддаленим налагодженням і підтвердженим у браузері першим запитом згоди на підключення.Готовність тут охоплює лише передумови локального підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; для розширених маршрутів, як-от responsebody, експорту PDF, перехоплення завантажень і пакетних дій, усе ще потрібен керований браузер або профіль необробленого CDP. Ця перевірка не застосовується до Docker, пісочниці, віддаленого браузера чи інших безголових сценаріїв, які й надалі використовують необроблений CDP.
Коли налаштовано профіль OAuth OpenAI Codex, doctor перевіряє кінцеву точку авторизації OpenAI, щоб переконатися, що локальний стек TLS Node/OpenSSL може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад, UNABLE_TO_GET_ISSUER_CERT_LOCALLY, прострочений або самопідписаний сертифікат), doctor виводить інструкції з виправлення для відповідної платформи. У macOS із Node, установленим через Homebrew, зазвичай допомагає brew postinstall ca-certificates. З --deep перевірка виконується, навіть якщо gateway справний.
Якщо раніше ви додали застарілі параметри транспорту OpenAI у models.providers.openai-codex, вони можуть затінити вбудований шлях провайдера OAuth Codex. Doctor попереджає, коли бачить ці старі параметри транспорту разом з OAuth Codex, щоб можна було видалити або переписати застаріле перевизначення транспорту й відновити поточну поведінку маршрутизації. Власні проксі та перевизначення лише заголовків залишаються підтримуваними й не спричиняють цього попередження, але такі явно задані маршрути запитів не придатні для неявного вибору Codex.
Doctor перевіряє наявність застарілих посилань на моделі openai-codex/*. Нативна маршрутизація середовища Codex використовує канонічні посилання на моделі openai/*, але сам префікс ніколи не вибирає Codex. Якщо політику середовища виконання не задано або встановлено auto, придатним є лише точний офіційний HTTPS-маршрут Platform Responses або ChatGPT Responses без явно заданого перевизначення запиту. Див. неявне агентне середовище виконання OpenAI.У режимі --fix / --repair doctor переписує відповідні посилання стандартного агента й окремих агентів, зокрема основні моделі, резервні моделі, моделі генерації зображень і відео, перевизначення heartbeat/підагентів/compaction, хуки, перевизначення моделей каналів і застарілий збережений стан маршруту сеансу:
  • openai-codex/gpt-* стає openai/gpt-*.
  • Намір Codex переноситься до записів agentRuntime.id: "codex" з областю провайдера/моделі для виправлених посилань на моделі агентів.
  • Застарілу конфігурацію середовища виконання всього агента та збережені фіксації середовища виконання сеансу видалено, оскільки вибір середовища виконання здійснюється в області провайдера/моделі.
  • Наявна політика середовища виконання провайдера/моделі зберігається, якщо тільки виправлене застаріле посилання на модель не потребує маршрутизації Codex для збереження старого шляху автентифікації.
  • Наявні списки резервних моделей зберігаються з переписаними застарілими записами; скопійовані параметри окремих моделей переносяться із застарілого ключа до канонічного ключа openai/*.
  • Збережені сеансові modelProvider/providerOverride, model/modelOverride, сповіщення про резервні моделі та фіксації профілів автентифікації виправляються в усіх виявлених сховищах сеансів агентів.
  • Doctor окремо виправляє застарілі фіксації agentRuntime.id: "codex-cli" (окремий застарілий ідентифікатор середовища виконання) на "codex" у записах моделей agents.defaults, agents.list[] та models.providers.*.
  • /codex ... означає «керувати нативною розмовою Codex або прив’язати її з чату».
  • /acp ... або runtime: "acp" означає «використовувати зовнішній адаптер ACP/acpx».
Doctor також сканує виявлені сховища сеансів агентів на наявність застарілого автоматично створеного стану маршруту після переміщення налаштованих моделей або середовища виконання з маршруту, що належить Plugin, наприклад Codex.openclaw doctor --fix може очистити автоматично створений застарілий стан, зокрема фіксації моделей modelOverrideSource: "auto", метадані моделі середовища виконання, зафіксовані ідентифікатори середовища, прив’язки сеансів CLI й автоматичні перевизначення профілю автентифікації, якщо маршрут-власник більше не налаштовано. Явно вибрані користувачем або застарілі моделі сеансів позначаються для ручної перевірки й залишаються без змін; перемкніть їх за допомогою /model ..., /new або скиньте сеанс, якщо цей маршрут більше не потрібен.
Doctor може мігрувати старіші структури на диску до поточної:
  • Сховище сеансів і транскрипти: з ~/.openclaw/sessions/ до ~/.openclaw/agents/<agentId>/sessions/
  • Каталог агента: з ~/.openclaw/agent/ до ~/.openclaw/agents/<agentId>/agent/
  • Стан автентифікації WhatsApp (Baileys): із застарілого ~/.openclaw/credentials/*.json (крім oauth.json) до ~/.openclaw/credentials/whatsapp/<accountId>/... (стандартний ідентифікатор облікового запису: default)
Ці міграції виконуються за можливості та є ідемпотентними; doctor виводить попередження, якщо залишає застарілі папки як резервні копії. Gateway/CLI також автоматично мігрує застарілі сеанси й каталог агента під час запуску, щоб історія, автентифікація та моделі потрапили до шляху окремого агента без ручного запуску doctor. Автентифікація WhatsApp навмисно мігрується лише через openclaw doctor. Нормалізація провайдера Talk/карти провайдерів порівнює структурну рівність, тому відмінності лише в порядку ключів більше не спричиняють повторних змін 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-файли сеансів агентів на наявність дубльованої структури гілок, створеної помилкою переписування транскрипту запиту від 2026.4.24: покинутий хід користувача з внутрішнім контекстом середовища виконання OpenClaw і активний сусідній елемент із тим самим видимим запитом користувача. У режимі --fix / --repair doctor створює резервну копію кожного пошкодженого файла поруч з оригіналом і переписує транскрипт до активної гілки, щоб засоби читання історії Gateway і пам’яті більше не бачили дубльованих ходів.
Каталог стану — це операційний стовбур мозку. Якщо він зникне, ви втратите сеанси, облікові дані, журнали та конфігурацію, якщо їхні резервні копії не зберігаються деінде.Doctor перевіряє:
  • Відсутній каталог стану: попереджає про катастрофічну втрату стану, пропонує повторно створити каталог і нагадує, що відновити відсутні дані неможливо.
  • Дозволи каталогу стану: перевіряє можливість запису; пропонує виправити дозволи (і виводить підказку chown, коли виявлено невідповідність власника або групи).
  • Синхронізований із хмарою каталог стану в macOS: попереджає, коли стан розміщено в iCloud Drive (~/Library/Mobile Documents/com~apple~CloudDocs/...) або ~/Library/CloudStorage/..., оскільки шляхи із синхронізацією можуть спричиняти повільніше введення-виведення та конфлікти блокування й синхронізації.
  • Каталог стану на SD або eMMC у Linux: попереджає, коли стан розміщено на джерелі монтування mmcblk*, оскільки довільне введення-виведення на SD/eMMC може бути повільнішим, а носій — швидше зношуватися під час записування сеансів і облікових даних.
  • Енергозалежний каталог стану в Linux: попереджає, коли стан розміщено в tmpfs або ramfs, оскільки сеанси, облікові дані, конфігурація та стан SQLite (із супровідними файлами WAL/журналу) зникають після перезавантаження. Монтування Docker overlay навмисно не позначаються, оскільки їхні доступні для запису шари зберігаються після перезавантаження хоста, доки контейнер існує.
  • Відсутні каталоги сеансів: sessions/ і каталог сховища сеансів необхідні для збереження історії та запобігання аварійним завершенням ENOENT.
  • Невідповідність транскрипту: попереджає, коли для нещодавніх записів сеансів відсутні файли транскриптів.
  • Основний сеанс «1-рядковий JSONL»: позначає випадок, коли основний транскрипт містить лише один рядок (історія не накопичується).
  • Кілька каталогів стану: попереджає, коли в домашніх каталогах існує кілька папок ~/.openclaw або коли OPENCLAW_STATE_DIR вказує на інше місце (історія може розділитися між інсталяціями).
  • Нагадування про віддалений режим: якщо gateway.mode=remote, doctor нагадує запустити його на віддаленому хості (стан зберігається там).
  • Дозволи файлу конфігурації: попереджає, якщо ~/.openclaw/openclaw.json доступний для читання групі або всім користувачам, і пропонує обмежити дозволи до 600.
Doctor перевіряє профілі OAuth у сховищі автентифікації, попереджає про токени, строк дії яких завершується або вже завершився, і може безпечно оновити їх. Якщо профіль OAuth/токена Anthropic застарів, він пропонує ключ API Anthropic або шлях із токеном налаштування Anthropic. Запити на оновлення з’являються лише під час інтерактивного запуску (TTY); --non-interactive пропускає спроби оновлення.Коли оновлення OAuth завершується невиправною помилкою (наприклад, refresh_token_reused, invalid_grant або постачальник вимагає повторно ввійти), doctor повідомляє про необхідність повторної автентифікації та виводить точну команду openclaw models auth login --provider ..., яку потрібно виконати.Doctor також повідомляє про профілі автентифікації, які тимчасово недоступні через короткі періоди очікування (обмеження частоти, перевищення часу очікування або помилки автентифікації) чи триваліші вимкнення (проблеми з оплатою або кредитами).Застарілі профілі OAuth Codex, токени яких зберігаються у Зв’язці ключів macOS (старіше початкове налаштування до появи файлової структури супровідних файлів), відновлюються лише за допомогою doctor. Один раз виконайте openclaw doctor --fix в інтерактивному терміналі, щоб перенести застарілі токени зі Зв’язки ключів безпосередньо до auth-profiles.json; після цього вбудовані звернення (Telegram, cron, передавання завдань підагентам) розпізнаватимуть їх як канонічні профілі OAuth OpenAI.
Якщо задано hooks.gmail.model, doctor перевіряє посилання на модель за каталогом і списком дозволених моделей та попереджає, коли його неможливо буде розпізнати або модель заборонено.
Коли ізоляцію в пісочниці ввімкнено, doctor перевіряє образи Docker і пропонує зібрати образ або перейти на застарілі назви, якщо поточний образ відсутній.
Doctor у режимі openclaw doctor --fix / openclaw doctor --repair видаляє застарілий, згенерований OpenClaw проміжний стан залежностей Plugin: застарілі згенеровані корені залежностей, старі каталоги етапів інсталяції, локальні для пакетів залишки попереднього коду відновлення залежностей вбудованих Plugin, а також осиротілі або відновлені керовані npm-копії вбудованих Plugin @openclaw/*, які можуть затіняти поточний вбудований маніфест. Doctor також повторно прив’язує пакет хоста openclaw до керованих npm-плагінів, що оголошують peerDependencies.openclaw, щоб локальні для пакетів імпорти середовища виконання, як-от openclaw/plugin-sdk/*, і надалі розпізнавалися після оновлень або відновлення npm.Doctor також може повторно встановити відсутні завантажувані Plugin, коли на них посилається конфігурація, але локальний реєстр Plugin не може їх знайти (суттєвий plugins.entries, налаштовані параметри каналу, постачальника або пошуку, налаштовані середовища виконання агентів). Під час оновлення пакетів doctor не перевстановлює пакети Plugin, доки замінюється основний пакет; якщо налаштований Plugin усе ще потребує відновлення, після оновлення знову виконайте openclaw doctor --fix. За винятком описаного нижче запуску образу контейнера, під час запуску Gateway та перезавантаження конфігурації відновлення пакетів не виконується; інсталяція Plugin залишається явною операцією doctor/install/update.Контейнеризований запуск Gateway має вузький виняток для оновлення: коли openclaw gateway run запускається з новою версією OpenClaw, перед переходом у стан готовності він виконує безпечні міграції стану та наявне узгодження Plugin після оновлення ядра, а потім записує контрольну точку для кожної версії. Цей прохід під час запуску може очистити застарілі записи вбудованих Plugin, відновити локальні посилання Plugin, перевстановити налаштовані пакети Plugin, коли це потрібно для узгодження, і перевірити активні дані Plugin. Якщо під час запуску неможливо виконати безпечне відновлення, один раз запустіть той самий образ із openclaw doctor --fix для того самого змонтованого стану й конфігурації, перш ніж перезапускати контейнер у звичайному режимі.
Doctor виявляє застарілі служби Gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити службу OpenClaw із використанням поточного порту Gateway. Він також може просканувати систему на наявність додаткових служб, подібних до Gateway, і вивести підказки щодо очищення. Служби Gateway OpenClaw із назвами профілів вважаються повноцінними й не позначаються як «додаткові».У Linux, якщо служба Gateway на рівні користувача відсутня, але існує системна служба Gateway OpenClaw, doctor не встановлює автоматично другу службу на рівні користувача. Перевірте за допомогою openclaw gateway status --deep або openclaw doctor --deep, а потім видаліть дублікат або задайте OPENCLAW_SERVICE_REPAIR_POLICY=external, якщо життєвим циклом Gateway керує системний супервізор.
Коли обліковий запис каналу Matrix має очікувану або доступну для виконання міграцію застарілого стану, doctor (у режимі --fix / --repair) створює знімок перед міграцією, а потім виконує міграцію за принципом максимально можливих зусиль: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є критичними; помилки записуються до журналу, а запуск триває. У режимі лише для читання (openclaw doctor без --fix) ця перевірка повністю пропускається.
Doctor перевіряє стан сполучення пристроїв у межах звичайної перевірки справності та повідомляє про:
  • очікувані запити на перше сполучення
  • очікувані підвищення ролі або області дії для вже сполучених пристроїв
  • виправлення невідповідності відкритого ключа, коли ідентифікатор пристрою все ще збігається, але ідентичність пристрою більше не відповідає схваленому запису
  • сполучені записи без активного токена для схваленої ролі
  • сполучені токени, області дії яких відхилилися від схваленої базової конфігурації сполучення
  • локальні кешовані записи токенів пристрою для поточного комп’ютера, які передують ротації токена на боці Gateway або містять застарілі метадані області дії
Doctor не схвалює запити на сполучення автоматично й не виконує автоматичну ротацію токенів пристрою. Він виводить точні наступні кроки:
  • перевірити очікувані запити за допомогою openclaw devices list
  • схвалити конкретний запит за допомогою openclaw devices approve <requestId>
  • створити новий токен шляхом ротації за допомогою openclaw devices rotate --device <deviceId> --role <role>
  • видалити та повторно схвалити застарілий запис за допомогою openclaw devices remove <deviceId>
Це дає змогу відрізняти перше сполучення від очікуваного підвищення ролі чи області дії та від розбіжності застарілого токена або ідентичності пристрою, усуваючи поширену проблему «пристрій уже сполучено, але вимога сполучення все одно з’являється».
Doctor виводить примітку щодо безпеки лише тоді, коли знаходить попередження, наприклад постачальника, відкритого для приватних повідомлень без списку дозволених відправників, або небезпечно налаштовану політику. Використовуйте openclaw security audit для повної інвентаризації безпеки.
Під час роботи як користувацька служба systemd doctor перевіряє, що збереження активності ввімкнено, аби Gateway продовжував працювати після виходу користувача.
Doctor виводить проблеми та дії для типового агента, а не інвентаризацію справного стану:
  • Skills: перелічує дозволені, але непридатні до використання назви навичок; скористайтеся openclaw skills check, щоб переглянути докладні вимоги та повну кількість.
  • Plugin: повідомляє лише ідентифікатори Plugin із помилками; скористайтеся openclaw plugins list, щоб переглянути інвентаризацію завантажених, імпортованих, вимкнених і пакетних Plugin.
  • Попередження про сумісність Plugin: позначає Plugin, що мають проблеми сумісності з поточним середовищем виконання.
  • Діагностика Plugin: показує всі попередження або помилки під час завантаження, виведені реєстром Plugin.
  • Відновлення TaskFlow: показує підозрілі керовані TaskFlows, що потребують ручної перевірки або скасування.
  • Claude CLI: повідомляє лише про проблеми з виконуваним файлом, автентифікацією, профілем, робочим простором або каталогом проєкту; подробиці успішної перевірки не наводяться.
Doctor перевіряє, чи наближаються файли початкового завантаження робочого простору (наприклад, AGENTS.md, CLAUDE.md або інші впроваджені файли контексту) до налаштованого бюджету символів або перевищують його. Він повідомляє для кожного файлу початкову та впроваджену кількість символів, відсоток скорочення, причину скорочення (max/file або max/total) і загальну кількість впроваджених символів як частку загального бюджету. Коли файли скорочено або вони наближаються до обмеження, doctor виводить поради щодо налаштування agents.defaults.bootstrapMaxChars і agents.defaults.bootstrapTotalMaxChars.
Doctor перевіряє, чи встановлено автодоповнення клавішею табуляції для поточної оболонки (zsh, bash, fish або PowerShell):
  • Якщо профіль оболонки використовує повільну схему динамічного автодоповнення (source <(openclaw completion ...)), doctor замінює її швидшим варіантом із кешованим файлом.
  • Якщо автодоповнення налаштовано в профілі, але файл кешу відсутній, doctor автоматично відновлює кеш.
  • Якщо автодоповнення взагалі не налаштовано, doctor пропонує встановити його (лише в інтерактивному режимі; пропускається з --non-interactive).
Виконайте openclaw completion --write-state, щоб відновити кеш вручну.
Коли openclaw doctor --fix видаляє відсутній Plugin каналу, він також видаляє завислу конфігурацію в межах каналу, яка посилалася на цей Plugin: записи channels.<id>, цілі Heartbeat, у яких було вказано канал, і перевизначення agents.*.models["<channel>/*"]. Це запобігає циклічним збоям запуску Gateway, коли середовище виконання каналу відсутнє, але конфігурація й надалі вимагає від Gateway прив’язатися до нього.
Doctor перевіряє готовність автентифікації локального Gateway за допомогою токена.
  • Якщо режим токена потребує токена, але жодного джерела токена не існує, doctor пропонує згенерувати його.
  • Якщо gateway.auth.token керується SecretRef, але недоступний, doctor попереджає про це й не перезаписує його відкритим текстом.
  • openclaw doctor --generate-gateway-token примусово генерує токен лише тоді, коли SecretRef токена не налаштовано.
Деякі процеси відновлення мають перевіряти налаштовані облікові дані, не послаблюючи поведінку середовища виконання з негайним завершенням у разі помилки.
  • openclaw doctor --fix використовує ту саму модель зведення SecretRef лише для читання, що й команди сімейства status, для цільового виправлення конфігурації.
  • Приклад: виправлення Telegram allowFrom / groupAllowFrom @username намагається використати налаштовані облікові дані бота, якщо вони доступні.
  • Якщо токен бота Telegram налаштовано через SecretRef, але він недоступний у поточному шляху виконання команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає автоматичне визначення замість аварійного завершення або хибного повідомлення про відсутність токена.
Doctor виконує перевірку справності й пропонує перезапустити Gateway, якщо він видається несправним.
Doctor перевіряє, чи готовий налаштований постачальник вбудовувань для пошуку в пам’яті для типового агента. Поведінка залежить від налаштованого бекенду та постачальника:
  • Бекенд QMD: перевіряє, чи доступний і чи може запускатися бінарний файл qmd. Якщо ні, виводить настанови щодо виправлення, зокрема npm install -g @tobilu/qmd (або еквівалент для Bun), і варіант ручного зазначення шляху до бінарного файлу.
  • Явно заданий локальний постачальник: перевіряє наявність локального файлу моделі або розпізнаної віддаленої URL-адреси моделі, доступної для завантаження. Якщо їх немає, пропонує перейти на віддаленого постачальника.
  • Явно заданий віддалений постачальник (openai, voyage тощо): перевіряє наявність ключа API в середовищі або сховищі автентифікації. Якщо ключ відсутній, виводить практичні підказки щодо виправлення.
  • Застарілий автоматичний постачальник: розглядає memorySearch.provider: "auto" як OpenAI, перевіряє готовність OpenAI, а doctor --fix замінює його на provider: "openai".
Якщо доступний кешований результат перевірки Gateway (Gateway був справним на момент перевірки), doctor зіставляє його з конфігурацією, видимою через CLI, і зазначає будь-які розбіжності. Doctor не запускає нову перевірку вбудовувань у типовому шляху; щоб виконати перевірку постачальника наживо, скористайтеся командою поглибленого стану пам’яті.Використовуйте openclaw memory status --deep, щоб перевірити готовність вбудовувань під час виконання.
Якщо Gateway справний, doctor виконує перевірку стану каналів і повідомляє попередження з рекомендованими виправленнями.
Doctor перевіряє встановлену конфігурацію супервізора (launchd/systemd/schtasks) на відсутність або застарілість типових параметрів (наприклад, залежностей systemd від network-online і затримки перезапуску). Якщо виявлено невідповідність, він рекомендує оновлення та може перезаписати файл служби або завдання відповідно до поточних типових параметрів.Примітки:
  • openclaw doctor запитує підтвердження перед перезаписом конфігурації супервізора.
  • openclaw doctor --yes приймає типові запити на виправлення.
  • openclaw doctor --fix застосовує рекомендовані виправлення без запитів (--repair є псевдонімом).
  • openclaw doctor --fix --force перезаписує користувацькі конфігурації супервізора.
  • OPENCLAW_SERVICE_REPAIR_POLICY=external зберігає для doctor режим лише для читання щодо життєвого циклу служби Gateway. Він і надалі повідомляє про справність служби та виконує виправлення, не пов’язані зі службою, але пропускає встановлення, запуск, перезапуск і початкове налаштування служби, перезапис конфігурації супервізора й очищення застарілих служб, оскільки цим життєвим циклом керує зовнішній супервізор.
  • У Linux doctor не перезаписує метадані команди або точки входу, поки відповідний модуль Gateway у systemd активний. Під час пошуку дублікатів служб він також ігнорує неактивні додаткові модулі, подібні до Gateway, які не є застарілими, щоб супровідні файли служб не створювали зайвих повідомлень про очищення.
  • Якщо автентифікація за токеном потребує токена, а gateway.auth.token керується через SecretRef, під час встановлення або виправлення служби doctor перевіряє SecretRef, але не зберігає визначені значення токенів у формі відкритого тексту в метаданих середовища служби супервізора.
  • Doctor виявляє керовані значення середовища служби на основі .env/SecretRef, які старіші встановлення LaunchAgent, systemd або Windows Scheduled Task вбудували безпосередньо, і перезаписує метадані служби, щоб ці значення завантажувалися з джерела середовища виконання, а не з визначення супервізора.
  • Doctor виявляє, коли команда служби й далі фіксує старий --port після змін gateway.port, і перезаписує метадані служби, використовуючи поточний порт.
  • Якщо автентифікація за токеном потребує токена, а налаштований SecretRef токена не визначається, doctor блокує шлях встановлення або виправлення та надає практичні настанови.
  • Якщо налаштовано і gateway.auth.token, і gateway.auth.password, а gateway.auth.mode не задано, doctor блокує встановлення або виправлення, доки режим не буде задано явно.
  • Для користувацьких модулів systemd у Linux перевірки розбіжностей токенів у doctor враховують джерела як Environment=, так і EnvironmentFile= під час порівняння метаданих автентифікації служби.
  • Під час виправлення служб doctor відмовляється перезаписувати, зупиняти або перезапускати службу Gateway зі старішого бінарного файлу OpenClaw, якщо конфігурацію востаннє записала новіша версія. Див. Усунення несправностей Gateway.
  • Завжди можна примусово виконати повний перезапис за допомогою openclaw gateway install --force.
Doctor перевіряє середовище виконання служби (PID, стан останнього завершення) і попереджає, коли службу встановлено, але вона фактично не працює. Він також перевіряє конфлікти портів на порту Gateway (типово 18789) і повідомляє ймовірні причини (Gateway уже працює, тунель SSH).
Doctor попереджає, коли служба Gateway працює на Bun або використовує шлях Node, керований менеджером версій (nvm, fnm, volta, asdf тощо). Bun не може відкрити сховище стану OpenClaw node:sqlite, тому виправлення переносять застарілі служби Bun на Node. Шляхи менеджерів версій можуть перестати працювати після оновлень, оскільки служба не завантажує файл ініціалізації оболонки. Doctor пропонує перейти на системне встановлення Node, якщо воно доступне (Homebrew/apt/choco).Щойно встановлені або виправлені LaunchAgent у macOS використовують канонічний системний PATH (/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin) замість копіювання PATH інтерактивної оболонки, тож системні бінарні файли, якими керує Homebrew, залишаються доступними, а каталоги Volta, asdf, fnm, pnpm та інших менеджерів версій не змінюють, який Node визначають дочірні процеси. Служби Linux і надалі зберігають явно задані кореневі каталоги середовища (NVM_DIR, FNM_DIR, VOLTA_HOME, ASDF_DATA_DIR, BUN_INSTALL, PNPM_HOME) і стабільні користувацькі каталоги бінарних файлів, але передбачені резервні каталоги менеджерів версій записуються до PATH служби лише тоді, коли вони існують на диску.
Doctor зберігає всі зміни конфігурації та додає до метаданих майстра позначку про запуск doctor.
Doctor пропонує систему пам’яті робочого простору, якщо її немає, і виводить пораду щодо резервного копіювання, якщо робочий простір ще не перебуває під керуванням git.Повний посібник зі структури робочого простору та резервного копіювання за допомогою git (рекомендовано приватний GitHub або GitLab) див. у розділі /concepts/agent-workspace.

​
Пов’язані матеріали