--- read_when: - Додавання або змінення міграцій doctor - Запровадження несумісних змін конфігурації sidebarTitle: Doctor summary: 'Команда doctor: перевірки справності, міграції конфігурації та кроки відновлення' title: Діагностика x-i18n: generated_at: "2026-05-12T08:45:44Z" model: gpt-5.5 provider: openai source_hash: 53d67fcc5ab4a356747bc4f4af0c5d42cbdae0c89a41616aaded7589e408a017 source_path: gateway/doctor.md workflow: 16 --- `openclaw doctor` — це інструмент виправлення та міграції для OpenClaw. Він виправляє застарілі конфігурацію/стан, перевіряє справність і надає практичні кроки з виправлення. ## Швидкий старт ```bash openclaw doctor ``` ### Режими без інтерфейсу та автоматизації ```bash openclaw doctor --yes ``` Приймати типові значення без запитів (включно з кроками виправлення перезапуску/служби/пісочниці, коли застосовно). ```bash openclaw doctor --repair ``` Застосувати рекомендовані виправлення без запитів (виправлення + перезапуски там, де це безпечно). ```bash openclaw doctor --repair --force ``` Застосувати також агресивні виправлення (перезаписує користувацькі конфігурації супервізора). ```bash openclaw doctor --non-interactive ``` Запустити без запитів і застосовувати лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії перезапуску/служби/пісочниці, які потребують підтвердження людини. Міграції застарілого стану запускаються автоматично, коли їх виявлено. ```bash openclaw doctor --deep ``` Сканувати системні служби на наявність додаткових інсталяцій Gateway (launchd/systemd/schtasks). Якщо хочете переглянути зміни перед записом, спочатку відкрийте файл конфігурації: ```bash cat ~/.openclaw/openclaw.json ``` ## Що він робить (підсумок) - Необов’язкове попереднє оновлення для інсталяцій із git (лише інтерактивно). - Перевірка актуальності протоколу UI (перезбирає Control UI, коли схема протоколу новіша). - Перевірка справності + запит на перезапуск. - Підсумок стану Skills (придатні/відсутні/заблоковані) і стан плагінів. - Нормалізація конфігурації для застарілих значень. - Міграція конфігурації Talk із застарілих пласких полів `talk.*` у `talk.provider` + `talk.providers.`. - Перевірки міграції браузера для застарілих конфігурацій розширення Chrome і готовності Chrome MCP. - Попередження щодо перевизначення провайдера OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). - Попередження щодо затінення OAuth Codex (`models.providers.openai-codex`). - Перевірка передумов OAuth TLS для профілів OpenAI Codex OAuth. - Попередження щодо списку дозволів Plugin/інструментів, коли `plugins.allow` обмежувальний, але політика інструментів усе ще запитує маску або інструменти, що належать плагіну. - Міграція застарілого стану на диску (сеанси/каталог агента/автентифікація WhatsApp). - Міграція ключів контракту застарілого маніфесту плагіна (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). - Міграція застарілого сховища Cron (`jobId`, `schedule.cron`, поля доставки/навантаження верхнього рівня, `provider` у навантаженні, прості резервні завдання Webhook `notify: true`). - Очищення застарілої політики runtime для всього агента; політика runtime провайдера/моделі є активним селектором маршруту. - Очищення застарілої конфігурації плагінів, коли плагіни ввімкнено; коли `plugins.enabled=false`, застарілі посилання на плагіни вважаються інертною конфігурацією containment і зберігаються. - Перевірка файлів блокування сеансів і очищення застарілих блокувань. - Виправлення транскриптів сеансів для дубльованих гілок переписування промпта, створених ураженими збірками 2026.4.24. - Виявлення маркерів завершення для відновлення після перезапуску завислого субагента, з підтримкою `--fix` для очищення застарілих прапорців перерваного відновлення, щоб запуск не продовжував вважати дочірній процес перерваним під час перезапуску. - Перевірки цілісності стану та дозволів (сеанси, транскрипти, каталог стану). - Перевірки дозволів файлу конфігурації (chmod 600) під час локального запуску. - Справність автентифікації моделей: перевіряє завершення терміну OAuth, може оновлювати токени, що скоро спливають, і повідомляє про стани паузи/вимкнення профілю автентифікації. - Виявлення додаткового каталогу робочого простору (`~/openclaw`). - Виправлення образу пісочниці, коли пісочницю ввімкнено. - Міграція застарілої служби та виявлення додаткового Gateway. - Міграція застарілого стану каналу Matrix (у режимі `--fix` / `--repair`). - Перевірки runtime Gateway (службу встановлено, але не запущено; кешована мітка launchd). - Попередження про стан каналів (перевіряються з запущеного Gateway). - Перевірки дозволів для конкретних каналів розміщено в `openclaw channels capabilities`; наприклад, дозволи голосового каналу Discord перевіряються за допомогою `openclaw channels capabilities --channel discord --target channel:`. - Перевірки чутливості WhatsApp для погіршеної справності циклу подій Gateway, коли локальні клієнти TUI все ще запущені; `--fix` зупиняє лише перевірені локальні клієнти TUI. - Виправлення маршруту Codex для застарілих посилань на моделі `openai-codex/*` в основних моделях, резервних варіантах, перевизначеннях Heartbeat/субагента/Compaction, хуках, перевизначеннях моделей каналів і закріпленнях маршрутів сеансів; `--fix` переписує їх на `openai/*`, видаляє застарілі закріплення runtime сеансів/усього агента й залишає канонічні посилання агентів OpenAI на типовій обв’язці Codex. - Аудит конфігурації супервізора (launchd/systemd/schtasks) з необов’язковим виправленням. - Очищення середовища вбудованого проксі для служб Gateway, які захопили значення оболонки `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` під час встановлення або оновлення. - Перевірки найкращих практик runtime Gateway (Node проти Bun, шляхи менеджера версій). - Діагностика конфлікту порту Gateway (типово `18789`). - Попередження безпеки для відкритих політик DM. - Перевірки автентифікації Gateway для режиму локального токена (пропонує генерацію токена, коли джерела токена не існує; не перезаписує конфігурації токена SecretRef). - Виявлення проблем зі спарюванням пристроїв (очікувані перші запити на спарювання, очікувані підвищення ролі/обсягу, дрейф застарілого локального кешу токенів пристрою та дрейф автентифікації запису спарювання). - Перевірка systemd linger на Linux. - Перевірка розміру bootstrap-файлу робочого простору (попередження про обрізання/наближення до ліміту для файлів контексту). - Перевірка готовності Skills для типового агента; повідомляє про дозволені Skills з відсутніми бінарними файлами, env, конфігурацією або вимогами ОС, а `--fix` може вимкнути недоступні Skills у `skills.entries`. - Перевірка стану автодоповнення оболонки та автоматичне встановлення/оновлення. - Перевірка готовності провайдера ембедингів пошуку пам’яті (локальна модель, віддалений ключ API або бінарний файл QMD). - Перевірки інсталяції з джерела (невідповідність робочого простору pnpm, відсутні ресурси UI, відсутній бінарний файл tsx). - Записує оновлену конфігурацію + метадані майстра. ## Зворотне заповнення та скидання в UI Dreams Сцена Dreams в Control UI містить дії **Зворотне заповнення**, **Скидання** та **Очистити обґрунтоване** для робочого процесу обґрунтованого Dreaming. Ці дії використовують RPC-методи в стилі doctor для Gateway, але вони **не** є частиною виправлення/міграції CLI `openclaw doctor`. Що вони роблять: - **Зворотне заповнення** сканує історичні файли `memory/YYYY-MM-DD.md` в активному робочому просторі, запускає обґрунтований прохід REM-щоденника та записує оборотні записи зворотного заповнення в `DREAMS.md`. - **Скидання** видаляє лише ці позначені записи щоденника зворотного заповнення з `DREAMS.md`. - **Очистити обґрунтоване** видаляє лише підготовлені короткострокові записи, призначені тільки для обґрунтованого режиму, які походять з історичного відтворення й ще не накопичили live recall або щоденну підтримку. Чого вони **не** роблять самі по собі: - вони не редагують `MEMORY.md` - вони не запускають повні міграції doctor - вони не додають автоматично обґрунтованих кандидатів до активного короткострокового сховища просування, якщо ви явно не запустите спершу підготовлений шлях CLI Якщо хочете, щоб обґрунтоване історичне відтворення впливало на звичайний шлях глибокого просування, натомість використовуйте потік CLI: ```bash openclaw memory rem-backfill --path ./memory --stage-short-term ``` Це готує обґрунтованих стійких кандидатів у короткостроковому сховищі Dreaming, залишаючи `DREAMS.md` як поверхню перегляду. ## Детальна поведінка та обґрунтування Якщо це checkout git і doctor працює інтерактивно, він пропонує оновити (fetch/rebase/build) перед запуском doctor. Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction` без перевизначення для конкретного каналу), doctor нормалізує їх до поточної схеми. Це включає застарілі пласкі поля Talk. Поточна публічна конфігурація мовлення Talk — це `talk.provider` + `talk.providers.`, а конфігурація голосу в реальному часі — `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: ["*"]` відповідає лише інструментам із плагінів, які фактично завантажуються; він не обходить ексклюзивний список дозволених плагінів. Doctor записує `plugins.bundledDiscovery: "compat"` для мігрованих застарілих конфігурацій списку дозволів, щоб зберегти наявну поведінку вбудованих провайдерів, а потім вказує на суворіше налаштування `"allowlist"`. Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися й просять запустити `openclaw doctor`. 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` - конфіги налаштованих каналів без видимої політики відповідей → `messages.groupChat.visibleReplies: "message_tool"` - `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.` - застарілі верхньорівневі селектори Talk реального часу (`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.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.` - `messages.tts.provider: "edge"` і `messages.tts.providers.edge` → `messages.tts.provider: "microsoft"` і `messages.tts.providers.microsoft` - `channels.discord.voice.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.voice.tts.providers.` - `channels.discord.accounts..voice.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.accounts..voice.tts.providers.` - `plugins.entries.voice-call.config.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `plugins.entries.voice-call.config.tts.providers.` - `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 може зберегти наявну відповідну іменовану/default ціль) - `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..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 нативними Попередження doctor також містять настанови щодо типового облікового запису для каналів з кількома обліковими записами: - Якщо налаштовано два або більше записів `channels..accounts` без `channels..defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний обліковий запис. - Якщо `channels..defaultAccount` встановлено на невідомий ID облікового запису, doctor попереджає і перелічує налаштовані ID облікових записів. Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`, це перевизначає вбудований каталог OpenCode з `@earendil-works/pi-ai`. Це може примусово спрямувати моделі на неправильний 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, перехоплення завантажень і пакетні дії, все ще потребують керованого браузера або raw CDP profile. Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших headless-потоків. Вони й надалі використовують raw CDP. Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє endpoint авторизації OpenAI, щоб переконатися, що локальний стек Node/OpenSSL TLS може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат), doctor виводить інструкції з виправлення для конкретної платформи. На macOS із Homebrew Node виправлення зазвичай таке: `brew postinstall ca-certificates`. З `--deep` перевірка виконується навіть тоді, коли gateway справний. Якщо раніше ви додали застарілі налаштування транспорту OpenAI у `models.providers.openai-codex`, вони можуть затіняти вбудований шлях провайдера Codex OAuth, який новіші випуски використовують автоматично. Doctor попереджає, коли бачить ці старі транспортні налаштування разом із Codex OAuth, щоб ви могли видалити або переписати застаріле перевизначення транспорту й повернути вбудовану поведінку маршрутизації/резервування. Користувацькі proxy та перевизначення лише заголовків і далі підтримуються й не запускають це попередження. Doctor перевіряє наявність застарілих посилань на моделі `openai-codex/*`. Нативна маршрутизація Codex harness використовує канонічні посилання на моделі `openai/*`; ходи агентів OpenAI проходять через Codex app-server harness замість шляху OpenClaw PI OpenAI. У режимі `--fix` / `--repair` doctor переписує зачеплені посилання типового агента й окремих агентів, зокрема основні моделі, резервні варіанти, перевизначення Heartbeat/subagent/Compaction, hooks, перевизначення моделей каналів і застарілий збережений стан маршруту сесії: - `openai-codex/gpt-*` стає `openai/gpt-*`. - Намір Codex переноситься в записи `agentRuntime.id: "codex"` на рівні провайдера/моделі для виправлених посилань на модель агента, щоб профілі авторизації `openai-codex:...` і надалі можна було вибирати після того, як посилання на модель стане `openai/*`. - Застаріла конфігурація runtime всього агента й збережені прив’язки runtime сесії видаляються, оскільки вибір runtime прив’язаний до провайдера/моделі. - Наявна політика runtime провайдера/моделі зберігається, якщо тільки виправлене застаріле посилання на модель не потребує маршрутизації Codex, щоб зберегти старий шлях авторизації. - Наявні списки резервних моделей зберігаються з переписаними застарілими записами; скопійовані налаштування для кожної моделі переміщуються із застарілого ключа до канонічного ключа `openai/*`. - Збережені сесійні `modelProvider`/`providerOverride`, `model`/`modelOverride`, повідомлення про fallback і прив’язки auth-profile виправляються в усіх виявлених сховищах сесій агентів. - `/codex ...` означає «керувати або прив’язати нативну розмову Codex із чату». - `/acp ...` або `runtime: "acp"` означає «використовувати зовнішній адаптер ACP/acpx». Doctor також сканує виявлені сховища сесій агентів на наявність застарілого автоматично створеного стану маршруту після того, як ви переносите налаштовані моделі або runtime з маршруту, яким володіє Plugin, наприклад Codex. `openclaw doctor --fix` може очищати автоматично створений застарілий стан, як-от прив’язки моделей `modelOverrideSource: "auto"`, метадані моделей runtime, закріплені ID harness, прив’язки сесій CLI та автоматичні перевизначення auth-profile, коли маршрут-власник більше не налаштовано. Явні користувацькі або застарілі вибори моделей сесії повідомляються для ручного перегляду й залишаються без змін; перемикайте їх через `/model ...`, `/new` або скидайте сесію, коли цей маршрут більше не планується використовувати. Doctor може мігрувати старіші структури на диску в поточну структуру: - Сховище сесій + транскрипти: - з `~/.openclaw/sessions/` до `~/.openclaw/agents//sessions/` - Каталог агента: - з `~/.openclaw/agent/` до `~/.openclaw/agents//agent/` - Стан авторизації WhatsApp (Baileys): - із застарілих `~/.openclaw/credentials/*.json` (крім `oauth.json`) - до `~/.openclaw/credentials/whatsapp//...` (ID типового облікового запису: `default`) Ці міграції виконуються best-effort і є ідемпотентними; doctor виводитиме попередження, коли залишає будь-які застарілі папки як резервні копії. Gateway/CLI також автоматично мігрує застарілі сесії + каталог агента під час запуску, щоб історія/auth/моделі потрапили в шлях для кожного агента без ручного запуску doctor. Авторизація WhatsApp навмисно мігрується лише через `openclaw doctor`. Нормалізація провайдера/мапи провайдерів Talk тепер порівнює за структурною рівністю, тож відмінності лише в порядку ключів більше не запускають повторні no-op зміни `doctor --fix`. Doctor сканує всі встановлені маніфести Plugin на наявність застарілих верхньорівневих ключів capability (`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` - поля payload верхнього рівня (`message`, `model`, `thinking`, ...) → `payload` - поля delivery верхнього рівня (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` - delivery-аліаси `provider` у payload → явне `delivery.channel` - прості застарілі fallback-завдання Webhook `notify: true` → явне `delivery.mode="webhook"` з `delivery.to=cron.webhook` Doctor автоматично мігрує лише завдання `notify: true`, коли може зробити це без зміни поведінки. Якщо завдання поєднує застарілий fallback notify з наявним режимом доставки не через Webhook, doctor попереджає і залишає це завдання для ручного перегляду. У 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` він автоматично видаляє застарілі файли блокування; інакше друкує примітку й просить повторно запустити з `--fix`. Doctor сканує JSONL-файли сеансів агента на дубльовану форму гілки, створену помилкою переписування транскрипту prompt від 2026.4.24: покинутий користувацький хід із внутрішнім runtime-контекстом OpenClaw плюс активний суміжний елемент із тим самим видимим користувацьким 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 може бути повільнішим і швидше зношувати носій під час запису сеансів та облікових даних. - **Каталоги сеансів відсутні**: `sessions/` і каталог сховища сеансів потрібні для збереження історії та уникнення аварій `ENOENT`. - **Невідповідність транскрипту**: попереджає, коли нещодавні записи сеансів мають відсутні файли транскриптів. - **Головний сеанс "1-line JSONL"**: позначає випадок, коли головний транскрипт має лише один рядок (історія не накопичується). - **Кілька каталогів стану**: попереджає, коли кілька папок `~/.openclaw` існують у різних домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (історія може розділитися між інсталяціями). - **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, doctor нагадує запустити його на віддаленому хості (стан живе там). - **Дозволи файлу конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` доступний для читання групі/всім, і пропонує посилити дозволи до `600`. Doctor перевіряє профілі OAuth у сховищі автентифікації, попереджає, коли токени скоро закінчуються або вже закінчилися, і може оновити їх, коли це безпечно. Якщо профіль OAuth/токена Anthropic застарів, він пропонує API-ключ Anthropic або шлях setup-token Anthropic. Запити на оновлення з’являються лише під час інтерактивного запуску (TTY); `--non-interactive` пропускає спроби оновлення. Коли оновлення OAuth завершується остаточною помилкою (наприклад `refresh_token_reused`, `invalid_grant` або провайдер просить увійти знову), doctor повідомляє, що потрібна повторна автентифікація, і друкує точну команду `openclaw models auth login --provider ...`, яку треба виконати. Doctor також повідомляє про профілі автентифікації, що тимчасово непридатні через: - короткі періоди очікування (обмеження швидкості/таймаути/помилки автентифікації) - довші вимкнення (помилки білінгу/кредитів) Якщо `hooks.gmail.model` задано, doctor перевіряє посилання на модель за каталогом і allowlist та попереджає, коли воно не розв’язується або заборонене. Коли sandboxing увімкнено, doctor перевіряє образи Docker і пропонує зібрати або перемкнутися на застарілі назви, якщо поточний образ відсутній. Doctor видаляє застарілий створений OpenClaw проміжний стан залежностей Plugin у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Це охоплює застарілі згенеровані корені залежностей, старі каталоги етапу встановлення, локальне для пакета сміття з попереднього коду відновлення залежностей bundled-plugin, а також осиротілі або відновлені керовані npm-копії bundled `@openclaw/*` plugins, які можуть затіняти поточний bundled manifest. Doctor також повторно зв’язує хостовий пакет `openclaw` у керовані npm plugins, що оголошують `peerDependencies.openclaw`, щоб локальні runtime-імпорти пакета, як-от `openclaw/plugin-sdk/*`, продовжували розв’язуватися після оновлень або ремонтів npm. Doctor також може перевстановити відсутні завантажувані plugins, коли конфігурація посилається на них, але локальний реєстр plugin не може їх знайти. Приклади включають матеріальні `plugins.entries`, налаштовані параметри каналів/провайдерів/пошуку та налаштовані runtime агентів. Під час оновлень пакета doctor уникає запуску відновлення plugin через менеджер пакетів, доки основний пакет замінюється; запустіть `openclaw doctor --fix` ще раз після оновлення, якщо налаштований plugin досі потребує відновлення. Запуск Gateway і перезавантаження конфігурації не запускають менеджери пакетів; встановлення plugin залишаються явною роботою doctor/install/update. Doctor виявляє застарілі сервіси gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити сервіс OpenClaw з поточним портом gateway. Він також може просканувати додаткові gateway-подібні сервіси й надрукувати підказки з очищення. Іменовані за профілем сервіси OpenClaw gateway вважаються повноцінними й не позначаються як "extra." У Linux, якщо користувацький сервіс gateway відсутній, але існує системний сервіс OpenClaw gateway, doctor не встановлює автоматично другий користувацький сервіс. Перевірте за допомогою `openclaw gateway status --deep` або `openclaw doctor --deep`, потім видаліть дублікат або задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли системний supervisor відповідає за життєвий цикл gateway. Коли обліковий запис каналу Matrix має очікувану або придатну до дії застарілу міграцію стану, doctor (у режимі `--fix` / `--repair`) створює знімок перед міграцією, а потім запускає найкращі можливі кроки міграції: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки записуються в журнал, а запуск продовжується. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається. Doctor тепер перевіряє стан сполучення пристроїв як частину звичайного проходу перевірки здоров’я. Що він повідомляє: - очікувані запити на перше сполучення - очікувані підвищення ролі для вже сполучених пристроїв - очікувані підвищення scope для вже сполучених пристроїв - виправлення невідповідності публічного ключа, коли id пристрою все ще збігається, але ідентичність пристрою більше не відповідає затвердженому запису - сполучені записи без активного токена для затвердженої ролі - сполучені токени, чиї scope відхилилися за межі затвердженої базової лінії сполучення - локальні кешовані записи device-token для поточної машини, що передують ротації токена на боці gateway або містять застарілі метадані scope Doctor не схвалює автоматично запити на сполучення і не ротує автоматично токени пристроїв. Натомість він друкує точні наступні кроки: - перегляньте очікувані запити за допомогою `openclaw devices list` - схваліть точний запит за допомогою `openclaw devices approve ` - згенеруйте свіжий токен ротацією за допомогою `openclaw devices rotate --device --role ` - видаліть і повторно схваліть застарілий запис за допомогою `openclaw devices remove ` Це закриває поширену прогалину "already paired but still getting pairing required": doctor тепер відрізняє перше сполучення від очікуваних підвищень ролі/scope і від застарілого дрейфу токена/ідентичності пристрою. Doctor видає попередження, коли провайдер відкритий для DM без allowlist або коли політику налаштовано небезпечним чином. Якщо запущено як користувацький сервіс systemd, doctor забезпечує ввімкнення lingering, щоб gateway залишався активним після виходу з системи. Doctor друкує підсумок стану робочого простору для типового агента: - **Стан Skills**: підраховує придатні, з відсутніми вимогами та заблоковані allowlist skills. - **Застарілі каталоги робочого простору**: попереджає, коли `~/openclaw` або інші застарілі каталоги робочого простору існують поруч із поточним робочим простором. - **Стан Plugin**: підраховує ввімкнені/вимкнені/з помилками plugins; перелічує ID plugin для будь-яких помилок; повідомляє можливості bundled plugin. - **Попередження сумісності Plugin**: позначає plugins, що мають проблеми сумісності з поточним runtime. - **Діагностика Plugin**: показує всі попередження або помилки часу завантаження, видані реєстром plugin. Doctor перевіряє, чи файли bootstrap робочого простору (наприклад `AGENTS.md`, `CLAUDE.md` або інші впроваджені файли контексту) близькі до налаштованого бюджету символів або перевищують його. Він повідомляє для кожного файлу сирі та впроваджені кількості символів, відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість впроваджених символів як частку від загального бюджету. Коли файли обрізано або вони близькі до ліміту, doctor друкує поради щодо налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`. Коли `openclaw doctor --fix` видаляє відсутній plugin каналу, він також видаляє висячу конфігурацію в області каналу, яка посилалася на цей plugin: записи `channels.`, цілі Heartbeat, що називали канал, і перевизначення `agents.*.models["/*"]`. Це запобігає циклам запуску Gateway, коли runtime каналу зник, але конфігурація все ще просить gateway прив’язатися до нього. Doctor перевіряє, чи встановлено автодоповнення клавішею Tab для поточної оболонки (zsh, bash, fish або PowerShell): - Якщо профіль оболонки використовує повільний шаблон динамічного автодоповнення (`source <(openclaw completion ...)`), doctor оновлює його до швидшого варіанта з кешованим файлом. - Якщо автодоповнення налаштоване в профілі, але файл кешу відсутній, doctor автоматично регенерує кеш. - Якщо автодоповнення взагалі не налаштоване, doctor пропонує встановити його (лише в інтерактивному режимі; пропускається з `--non-interactive`). Запустіть `openclaw completion --write-state`, щоб регенерувати кеш вручну. 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-пакет і варіант ручного шляху до бінарного файлу. - **Явний локальний постачальник**: перевіряє наявність локального файлу моделі або розпізнаної віддаленої/доступної для завантаження URL-адреси моделі. Якщо відсутня, пропонує перейти на віддаленого постачальника. - **Явний віддалений постачальник** (`openai`, `voyage` тощо): перевіряє, що ключ API присутній у середовищі або сховищі автентифікації. Виводить практичні підказки для виправлення, якщо його немає. - **Автоматичний постачальник**: спершу перевіряє доступність локальної моделі, потім пробує кожного віддаленого постачальника в порядку автоматичного вибору. Коли доступний кешований результат зонду Gateway (Gateway був справним на момент перевірки), doctor зіставляє його результат із конфігурацією, видимою для CLI, і зазначає будь-яку розбіжність. Doctor не запускає новий ping ембедингів у типовому шляху; використовуйте команду глибокого статусу пам’яті, коли потрібна поточна перевірка постачальника. Використайте `openclaw memory status --deep`, щоб перевірити готовність ембедингів під час виконання. Якщо Gateway справний, doctor запускає зондування статусу каналу й повідомляє попередження із запропонованими виправленнями. Doctor перевіряє встановлену конфігурацію супервізора (launchd/systemd/schtasks) на відсутні або застарілі типові параметри (наприклад, залежності systemd від network-online і затримку перезапуску). Коли він знаходить невідповідність, то рекомендує оновлення й може переписати файл служби/завдання до поточних типових параметрів. Примітки: - `openclaw doctor` запитує підтвердження перед переписуванням конфігурації супервізора. - `openclaw doctor --yes` приймає типові запити на виправлення. - `openclaw doctor --repair` застосовує рекомендовані виправлення без запитів. - `openclaw doctor --repair --force` перезаписує власні конфігурації супервізора. - `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає doctor у режимі лише для читання для життєвого циклу служби Gateway. Він усе ще повідомляє стан служби й виконує виправлення, не пов’язані зі службою, але пропускає встановлення/запуск/перезапуск/bootstrap служби, переписування конфігурації супервізора й очищення застарілих служб, оскільки цим життєвим циклом керує зовнішній супервізор. - У Linux doctor не переписує метадані команди/точки входу, поки відповідний systemd-модуль Gateway активний. Він також ігнорує неактивні незастарілі додаткові модулі, схожі на Gateway, під час сканування дубльованих служб, щоб супровідні файли служб не створювали шум очищення. - Якщо автентифікація токеном потребує токен і `gateway.auth.token` керується SecretRef, встановлення/виправлення служби doctor перевіряє SecretRef, але не зберігає розв’язані значення токена відкритим текстом у метаданих середовища служби супервізора. - Doctor виявляє значення середовища служби, керовані `.env`/SecretRef, які старіші встановлення LaunchAgent, systemd або Windows Scheduled Task вбудовували inline, і переписує метадані служби так, щоб ці значення завантажувалися з джерела виконання, а не з визначення супервізора. - 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](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard). - Ви завжди можете примусово виконати повне переписування через `openclaw gateway install --force`. Doctor перевіряє виконання служби (PID, останній статус виходу) і попереджає, коли служба встановлена, але фактично не працює. Він також перевіряє конфлікти портів на порту Gateway (типово `18789`) і повідомляє ймовірні причини (Gateway уже запущений, SSH-тунель). Doctor попереджає, коли служба Gateway працює на Bun або шляху Node, керованому менеджером версій (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, а шляхи менеджера версій можуть зламатися після оновлень, оскільки служба не завантажує ініціалізацію вашої оболонки. Doctor пропонує перейти на системне встановлення Node, коли воно доступне (Homebrew/apt/choco). Ново встановлені або відремонтовані macOS LaunchAgents використовують канонічний системний 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. Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace) для повного посібника зі структури робочої області та резервного копіювання в git (рекомендовано приватний GitHub або GitLab). ## Пов’язане - [Runbook Gateway](/uk/gateway) - [Усунення несправностей Gateway](/uk/gateway/troubleshooting)