Диагностика

• Необязательное предварительное обновление для установок из git (только в интерактивном режиме).
• Проверка актуальности протокола интерфейса (пересобирает Control UI, если схема протокола новее).
• Проверка работоспособности и запрос на перезапуск.
• Сводка состояния Skills (доступны/отсутствуют/заблокированы) и состояния плагинов.

• Нормализация устаревших форматов значений конфигурации.
• Миграция конфигурации 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).
• Запись обновлённой конфигурации и метаданных мастера настройки.

Если это рабочая копия git и диагностика выполняется интерактивно, перед её запуском предлагается выполнить обновление (fetch/rebase/build).

Диагностика преобразует устаревшие формы значений в текущую схему. Текущая конфигурация речи Talk — talk.provider + talk.providers.<provider>, а конфигурация голоса в реальном времени находится в talk.realtime.*. Диагностика преобразует старые формы talk.voiceId / talk.voiceAliases / talk.modelId / talk.outputFormat / talk.apiKey в карту провайдеров, а устаревшие селекторы реального времени верхнего уровня (talk.mode, talk.transport, talk.brain, talk.model, talk.voice) — в talk.realtime.

Диагностика также предупреждает, если plugins.allow не пуст и политика инструментов использует подстановочный знак или записи инструментов, принадлежащие плагинам. tools.allow: ["*"] сопоставляется только с инструментами фактически загруженных плагинов; он не позволяет обойти эксклюзивный список разрешённых плагинов.

Если конфигурация содержит устаревший ключ с активной миграцией, другие команды отказываются запускаться и предлагают выполнить openclaw doctor. Диагностика объясняет, какие устаревшие ключи были обнаружены, показывает применённую миграцию и перезаписывает ~/.openclaw/openclaw.json с обновлённой схемой. Gateway отказывается запускаться с устаревшими форматами конфигурации и предлагает выполнить openclaw doctor --fix; при запуске он не перезаписывает openclaw.json. Миграции хранилища заданий Cron также выполняются командой openclaw doctor --fix.

Активные миграции:

Рекомендации по учётной записи по умолчанию для каналов с несколькими учётными записями:

• Если настроены две или более записи channels.<channel>.accounts без channels.<channel>.defaultAccount или accounts.default, диагностика предупреждает, что резервная маршрутизация может выбрать неожиданную учётную запись.
• Если в channels.<channel>.defaultAccount указан неизвестный идентификатор учётной записи, диагностика выводит предупреждение и перечисляет идентификаторы настроенных учётных записей.

Если вы вручную добавили 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/узла, с включённой удалённой отладкой и подтверждённым в браузере первым запросом согласия на подключение.

Проверка готовности здесь охватывает только предварительные требования для локального подключения. Режим 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. При нормализации провайдера Talk и карты провайдеров используется структурное сравнение, поэтому различия только в порядке ключей больше не приводят к повторным изменениям 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 он автоматически удаляет блокировки, владельцы которых завершены, потеряны, повторно используют PID, имеют старые некорректные метаданные или не относятся к 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» основного сеанса: сообщает, когда основной транскрипт содержит только одну строку (история не накапливается).
• Несколько каталогов состояния: предупреждает, когда в домашних каталогах существует несколько папок ~/.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, в режиме openclaw doctor --fix / openclaw doctor --repair: устаревшие созданные корни зависимостей, старые каталоги этапов установки, локальные остатки пакетов от прежнего кода восстановления зависимостей встроенных плагинов, а также потерянные или восстановленные управляемые 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 выводит предупреждения, когда провайдер открыт для личных сообщений без списка разрешённых отправителей или когда политика настроена опасным образом.

При работе в качестве пользовательской службы systemd doctor обеспечивает включение сохранения пользовательского сеанса, чтобы Gateway продолжал работать после выхода пользователя.

Doctor выводит сводку состояния рабочей области для агента по умолчанию:

• Состояние Skills: подсчитывает подходящие Skills, Skills с невыполненными требованиями и Skills, заблокированные списком разрешений.
• Состояние плагинов: подсчитывает включённые, отключённые плагины и плагины с ошибками; перечисляет идентификаторы плагинов для всех ошибок; сообщает о возможностях плагинов комплекта.
• Предупреждения о совместимости плагинов: отмечает плагины с проблемами совместимости с текущей средой выполнения.
• Диагностика плагинов: показывает все предупреждения и ошибки времени загрузки, выданные реестром плагинов.
• Восстановление TaskFlow: показывает подозрительные управляемые TaskFlow, которые требуют ручной проверки или отмены.

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 удаляет отсутствующий плагин канала, он также удаляет оставшуюся конфигурацию области канала, которая ссылалась на этот плагин: записи 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 модели или 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. Doctor по-прежнему сообщает о работоспособности службы и выполняет исправления, не связанные со службой, но пропускает установку, запуск, перезапуск и начальную настройку службы, перезапись конфигурации супервизора и очистку устаревших служб, поскольку этим жизненным циклом управляет внешний супервизор.
• В 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.