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 (только в интерактивном режиме).
  • Проверка актуальности протокола интерфейса (пересобирает интерфейс управления, если схема протокола новее).
  • Проверка работоспособности и запрос на перезапуск.
  • Только замечания о проблемах со Skills и плагинами; сведения об исправном инвентаре остаются в openclaw skills check и openclaw plugins list.
  • Нормализация конфигурации для устаревших форматов значений.
  • Миграция конфигурации Talk из устаревших плоских полей 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 UI

Сцена Dreams в интерфейсе управления включает действия Backfill, Reset и Clear Grounded для рабочего процесса обоснованного Dreaming. Они используют RPC-методы Gateway в стиле doctor, но не являются частью восстановления или миграции CLI openclaw doctor. Ни одно из этих действий не изменяет MEMORY.md, не запускает полные миграции doctor и само по себе не помещает обоснованные кандидаты в оперативное хранилище продвижения краткосрочных записей. Чтобы передать обоснованное историческое воспроизведение в обычный канал глубокого продвижения, используйте вместо этого поток CLI:
Он помещает обоснованные долговременные кандидаты в краткосрочное хранилище 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 также сканирует обнаруженные хранилища сеансов агентов на наличие устаревшего автоматически созданного состояния маршрута после переноса настроенных моделей или среды выполнения с маршрута, принадлежащего плагину, например 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. Нормализация провайдера речи и карты провайдеров использует структурное сравнение, поэтому различия только в порядке ключей больше не вызывают повторные холостые изменения doctor --fix.
Doctor сканирует все манифесты установленных плагинов на наличие устаревших ключей возможностей верхнего уровня (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.
  • Несоответствие транскриптов: предупреждает, когда у недавних записей сеансов отсутствуют файлы транскриптов.
  • Основной сеанс «JSONL из 1 строки»: сообщает, когда основной транскрипт содержит только одну строку (история не накапливается).
  • Несколько каталогов состояния: предупреждает, когда в домашних каталогах существует несколько папок ~/.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 и предлагает собрать образ или перейти на устаревшие имена, если текущий образ отсутствует.
В режиме openclaw doctor --fix / openclaw doctor --repair doctor удаляет устаревшее промежуточное состояние зависимостей плагинов, созданное OpenClaw: устаревшие сгенерированные корни зависимостей, старые каталоги этапов установки, локальные остатки пакетов от прежнего кода восстановления зависимостей встроенных плагинов, а также потерянные или восстановленные управляемые npm-копии встроенных плагинов @openclaw/*, которые могут перекрывать текущий встроенный манифест. Doctor также повторно связывает пакет хоста openclaw с управляемыми npm-плагинами, объявляющими peerDependencies.openclaw, чтобы локальные для пакета импорты среды выполнения, такие как openclaw/plugin-sdk/*, продолжали разрешаться после обновлений или восстановления npm.Doctor также может повторно установить отсутствующие загружаемые плагины, если на них ссылается конфигурация, но локальный реестр плагинов не может их найти (существенное plugins.entries, настроенные параметры канала, провайдера или поиска, настроенные среды выполнения агентов). Во время обновления пакетов doctor не переустанавливает пакеты плагинов, пока заменяется основной пакет; если настроенный плагин всё ещё требует восстановления, снова выполните openclaw doctor --fix после обновления. За исключением описанного ниже случая запуска образа контейнера, запуск Gateway и перезагрузка конфигурации не выполняют восстановление пакетов; установка плагинов остаётся явной операцией doctor/install/update.Для запуска контейнеризованного Gateway предусмотрено узкое исключение при обновлении: когда openclaw gateway run запускается с новой версией OpenClaw, до перехода в состояние готовности он выполняет безопасные миграции состояния и существующее согласование плагинов после обновления ядра, а затем записывает контрольную точку для каждой версии. Этот проход при запуске может очищать устаревшие записи встроенных плагинов, восстанавливать локальные ссылки плагинов, повторно устанавливать настроенные пакеты плагинов, когда этого требует процесс согласования, и проверять активные данные плагинов. Если запуск не может безопасно выполнить восстановление, один раз запустите тот же образ с 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, чтобы просмотреть требования и полные количественные данные.
  • Плагины: сообщает только идентификаторы плагинов с ошибками; используйте openclaw plugins list, чтобы просмотреть загруженные, импортированные и отключённые плагины, а также перечень встроенных плагинов.
  • Предупреждения о совместимости плагинов: отмечает плагины, имеющие проблемы совместимости с текущей средой выполнения.
  • Диагностика плагинов: показывает все предупреждения и ошибки, выданные реестром плагинов во время загрузки.
  • Восстановление TaskFlow: показывает подозрительные управляемые TaskFlow, требующие ручной проверки или отмены.
  • CLI Claude: сообщает только о проблемах с исполняемым файлом, аутентификацией, профилем, рабочей областью или каталогом проекта; сведения об успешной проверке не выводятся.
Doctor проверяет, приближаются ли файлы начальной загрузки рабочей области (например, AGENTS.md, CLAUDE.md или другие внедряемые контекстные файлы) к настроенному лимиту символов или превышают его. Для каждого файла он сообщает исходное и внедрённое количество символов, процент усечения, причину усечения (max/file или max/total), а также общее количество внедрённых символов в виде доли от общего лимита. Когда файлы усечены или приближаются к лимиту, doctor выводит рекомендации по настройке agents.defaults.bootstrapMaxChars и agents.defaults.bootstrapTotalMaxChars.
Doctor проверяет, установлено ли автодополнение по Tab для текущей оболочки (zsh, bash, fish или PowerShell):
  • Если профиль оболочки использует медленную схему динамического автодополнения (source <(openclaw completion ...)), doctor заменяет её более быстрым вариантом с кэшированным файлом.
  • Если автодополнение настроено в профиле, но файл кэша отсутствует, doctor автоматически создаёт кэш заново.
  • Если автодополнение вообще не настроено, doctor предлагает установить его (только в интерактивном режиме; пропускается при --non-interactive).
Выполните openclaw completion --write-state, чтобы создать кэш заново вручную.
Когда openclaw doctor --fix удаляет отсутствующий плагин канала, он также удаляет зависшую конфигурацию канала, которая ссылалась на этот плагин: записи 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 обнаруживает, когда команда службы после изменения gateway.port по-прежнему закрепляет старое значение --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.

​
Связанные материалы