Конфигурация и операции

Doctor

openclaw doctor — это инструмент для ремонта и миграции OpenClaw. Он исправляет устаревшие конфигурации/состояния, проверяет работоспособность и предоставляет конкретные шаги для исправления.

Быстрый старт

openclaw doctor

Автоматический режим / автоматизация

openclaw doctor --yes

Принять значения по умолчанию без запросов (включая шаги по перезапуску/сервису/ремонту песочницы, где применимо).

openclaw doctor --repair

Применить рекомендуемые исправления без запросов (исправления + перезапуски, где это безопасно).

openclaw doctor --repair --force

Применить также агрессивные исправления (перезаписывает пользовательские конфигурации супервизора).

openclaw doctor --non-interactive

Запустить без запросов и применять только безопасные миграции (нормализация конфигурации + перемещения состояний на диске). Пропускает действия по перезапуску/сервису/песочнице, требующие подтверждения пользователя. Миграции устаревших состояний запускаются автоматически при обнаружении.

openclaw doctor --deep

Просканировать системные сервисы на наличие дополнительных установок шлюза (launchd/systemd/schtasks). Если вы хотите просмотреть изменения перед записью, сначала откройте файл конфигурации:

cat ~/.openclaw/openclaw.json

Что он делает (кратко)

  • Опциональная предварительная проверка обновлений для git-установок (только в интерактивном режиме).
  • Проверка актуальности протокола UI (пересобирает Control UI, когда схема протокола новее).
  • Проверка работоспособности + запрос на перезапуск.
  • Сводка статуса навыков (доступны/отсутствуют/заблокированы).
  • Нормализация конфигурации для устаревших значений.
  • Предупреждения о переопределениях провайдера OpenCode Zen (models.providers.opencode).
  • Миграция устаревших состояний на диске (сессии/директория агента/аутентификация WhatsApp).
  • Проверки целостности состояния и прав доступа (сессии, транскрипты, директория состояния).
  • Проверки прав доступа к файлу конфигурации (chmod 600) при локальном запуске.
  • Состояние аутентификации моделей: проверяет истечение срока действия OAuth, может обновить истекающие токены и сообщает о состояниях охлаждения/отключения профилей аутентификации.
  • Обнаружение дополнительных рабочих директорий (~/openclaw).
  • Ремонт образа песочницы, когда песочница включена.
  • Миграция устаревших сервисов и обнаружение дополнительных шлюзов.
  • Проверки времени выполнения шлюза (сервис установлен, но не запущен; закэшированный метка launchd).
  • Предупреждения о статусе каналов (проверяются из запущенного шлюза).
  • Аудит конфигурации супервизора (launchd/systemd/schtasks) с опциональным ремонтом.
  • Проверки лучших практик времени выполнения шлюза (Node vs Bun, пути менеджеров версий).
  • Диагностика конфликтов портов шлюза (по умолчанию 18789).
  • Предупреждения безопасности об открытых политиках личных сообщений.
  • Проверки аутентификации шлюза для локального режима токена (предлагает сгенерировать токен, когда источник токена отсутствует; не перезаписывает конфигурации SecretRef токена).
  • Проверка systemd linger на Linux.
  • Проверки установки из исходников (несоответствие pnpm workspace, отсутствующие UI-ресурсы, отсутствующий бинарный файл tsx).
  • Записывает обновленную конфигурацию + метаданные мастера настройки.

Подробное поведение и обоснование

0) Опциональное обновление (git-установки)

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

1) Нормализация конфигурации

Если конфигурация содержит устаревшие структуры значений (например, messages.ackReaction без специфичного для канала переопределения), doctor нормализует их в соответствии с текущей схемой.

2) Миграции устаревших ключей конфигурации

Когда конфигурация содержит устаревшие ключи, другие команды отказываются работать и просят запустить openclaw doctor. Doctor сделает следующее:

  • Объяснит, какие устаревшие ключи были найдены.
  • Покажет примененную миграцию.
  • Перезапишет ~/.openclaw/openclaw.json обновленной схемой.

Шлюз также автоматически запускает миграции doctor при старте, когда обнаруживает устаревший формат конфигурации, поэтому устаревшие конфигурации исправляются без ручного вмешательства. Текущие миграции:

  • 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
  • routing.queue → messages.queue
  • routing.bindings → верхнеуровневые bindings
  • routing.agents/routing.defaultAgentId → agents.list + agents.list[].default
  • routing.agentToAgent → tools.agentToAgent
  • routing.transcribeAudio → tools.media.audio.models
  • bindings[].match.accountID → bindings[].match.accountId
  • Для каналов с именованными accounts, но без accounts.default, переместить верхнеуровневые значения канала для одного аккаунта в channels.<channel>.accounts.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
  • browser.ssrfPolicy.allowPrivateNetwork → browser.ssrfPolicy.dangerouslyAllowPrivateNetwork

Предупреждения doctor также включают рекомендации по умолчанию для аккаунтов в многопользовательских каналах:

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

2b) Переопределения провайдера OpenCode Zen

Если вы вручную добавили models.providers.opencode (или opencode-zen), это переопределяет встроенный каталог OpenCode Zen из @mariozechner/pi-ai. Это может заставить каждую модель использовать единый API или обнулить стоимость. Doctor предупреждает, чтобы вы могли удалить переопределение и восстановить маршрутизацию API и стоимость для каждой модели.

3) Миграции устаревших состояний (структура диска)

Doctor может перенести старые структуры на диске в текущую:

  • Хранилище сессий + транскрипты:
    • из ~/.openclaw/sessions/ в ~/.openclaw/agents/<agentId>/sessions/
  • Директория агента:
    • из ~/.openclaw/agent/ в ~/.openclaw/agents/<agentId>/agent/
  • Состояние аутентификации WhatsApp (Baileys):
    • из устаревших ~/.openclaw/credentials/*.json (кроме oauth.json)
    • в ~/.openclaw/credentials/whatsapp/<accountId>/... (ID аккаунта по умолчанию: default)

Эти миграции выполняются по возможности и идемпотентны; doctor выдаст предупреждения, когда оставит какие-либо устаревшие папки в качестве резервных копий. Шлюз/CLI также автоматически переносит устаревшие сессии и директорию агента при запуске, так что история/аутентификация/модели попадают в путь для конкретного агента без ручного запуска doctor. Аутентификация WhatsApp намеренно мигрируется только через openclaw doctor.

4) Проверки целостности состояния (сохранение сессий, маршрутизация и безопасность)

Директория состояния — это операционный ствол мозга. Если она исчезнет, вы потеряете сессии, учетные данные, логи и конфигурацию (если у вас нет резервных копий в другом месте). Doctor проверяет:

  • Отсутствует директория состояния: предупреждает о катастрофической потере состояния, предлагает воссоздать директорию и напоминает, что не может восстановить отсутствующие данные.
  • Права доступа к директории состояния: проверяет возможность записи; предлагает исправить права доступа (и выдает подсказку chown, когда обнаружено несоответствие владельца/группы).
  • Директория состояния, синхронизируемая с облаком macOS: предупреждает, когда состояние находится в iCloud Drive (~/Library/Mobile Documents/com~apple~CloudDocs/...) или ~/Library/CloudStorage/..., потому что пути с синхронизацией могут вызывать более медленный ввод-вывод и гонки блокировок/синхронизации.
  • Директория состояния на SD или eMMC в Linux: предупреждает, когда состояние находится на источнике монтирования mmcblk*, потому что случайный ввод-вывод на SD или eMMC может быть медленнее и быстрее изнашиваться при записи сессий и учетных данных.
  • Отсутствуют директории сессий: sessions/ и директория хранилища сессий необходимы для сохранения истории и избежания сбоев ENOENT.
  • Несоответствие транскриптов: предупреждает, когда у недавних записей сессий отсутствуют файлы транскриптов.
  • Главная сессия «1-строчный JSONL»: помечает, когда главный транскрипт имеет только одну строку (история не накапливается).
  • Несколько директорий состояния: предупреждает, когда несколько папок ~/.openclaw существуют в разных домашних директориях или когда OPENCLAW_STATE_DIR указывает в другое место (история может разделиться между установками).
  • Напоминание о удаленном режиме: если gateway.mode=remote, doctor напоминает запустить его на удаленном хосте (состояние находится там).
  • Права доступа к файлу конфигурации: предупреждает, если ~/.openclaw/openclaw.json доступен для чтения группе/всем, и предлагает ужесточить до 600.

5) Состояние аутентификации моделей (истечение OAuth)

Doctor проверяет OAuth-профили в хранилище аутентификации, предупреждает об истекающих/истекших токенах и может обновить их, когда это безопасно. Если профиль Anthropic Claude Code устарел, он предлагает запустить claude setup-token (или вставить setup-token). Запросы на обновление появляются только при интерактивном запуске (TTY); --non-interactive пропускает попытки обновления. Doctor также сообщает о профилях аутентификации, которые временно непригодны для использования из-за:

  • коротких периодов охлаждения (ограничения скорости/таймауты/ошибки аутентификации)
  • более длительных отключений (проблемы с биллингом/кредитами)

6) Валидация модели хуков

Если установлен hooks.gmail.model, doctor проверяет ссылку на модель по каталогу и списку разрешенных и предупреждает, когда она не разрешится или запрещена.

7) Ремонт образа песочницы

Когда песочница включена, doctor проверяет образы Docker и предлагает собрать или переключиться на устаревшие имена, если текущий образ отсутствует.

8) Миграции сервиса шлюза и подсказки по очистке

Doctor обнаруживает устаревшие сервисы шлюза (launchd/systemd/schtasks) и предлагает удалить их и установить сервис OpenClaw, используя текущий порт шлюза. Он также может сканировать на наличие дополнительных сервисов, похожих на шлюз, и выводить подсказки по очистке. Сервисы шлюза OpenClaw с именованными профилями считаются основными и не помечаются как «дополнительные».

9) Предупреждения безопасности

Doctor выдает предупреждения, когда провайдер открыт для личных сообщений без списка разрешений или когда политика настроена опасным образом.

10) systemd linger (Linux)

Если запущен как пользовательский сервис systemd, doctor обеспечивает включение lingering, чтобы шлюз оставался активным после выхода из системы.

11) Статус навыков

Doctor выводит краткую сводку о доступных/отсутствующих/заблокированных навыках для текущей рабочей области.

12) Проверки аутентификации шлюза (локальный токен)

Doctor проверяет готовность локальной аутентификации шлюза по токену.

  • Если для режима токена нужен токен, а источник токена отсутствует, doctor предлагает сгенерировать его.
  • Если gateway.auth.token управляется через SecretRef, но недоступен, doctor предупреждает и не перезаписывает его обычным текстом.
  • openclaw doctor --generate-gateway-token принудительно генерирует токен только тогда, когда не настроен SecretRef токена.

12b) Ремонт с учетом SecretRef только для чтения

Некоторые процессы ремонта должны проверять настроенные учетные данные, не ослабляя поведение быстрого отказа во время выполнения.

  • openclaw doctor --fix теперь использует ту же модель сводки SecretRef только для чтения, что и команды семейства status, для целевого ремонта конфигурации.
  • Пример: ремонт allowFrom / groupAllowFrom @username для Telegram пытается использовать настроенные учетные данные бота, когда они доступны.
  • Если токен бота Telegram настроен через SecretRef, но недоступен в текущем пути команды, doctor сообщает, что учетные данные настроены, но недоступны, и пропускает автоматическое разрешение вместо сбоя или ошибочного сообщения об отсутствии токена.

13) Проверка работоспособности шлюза + перезапуск

Doctor выполняет проверку работоспособности и предлагает перезапустить шлюз, когда он выглядит нездоровым.

14) Предупреждения о статусе каналов

Если шлюз работает нормально, doctor запускает проверку статуса каналов и сообщает о предупреждениях с предлагаемыми исправлениями.

15) Аудит + ремонт конфигурации супервизора

Doctor проверяет установленную конфигурацию супервизора (launchd/systemd/schtasks) на отсутствующие или устаревшие значения по умолчанию (например, зависимости systemd network-online и задержку перезапуска). Когда обнаруживается несоответствие, он рекомендует обновление и может переписать файл сервиса/задачу на текущие значения по умолчанию. Примечания:

  • openclaw doctor запрашивает подтверждение перед перезаписью конфигурации супервизора.
  • openclaw doctor --yes принимает запросы на ремонт по умолчанию.
  • openclaw doctor --repair применяет рекомендуемые исправления без запросов.
  • openclaw doctor --repair --force перезаписывает пользовательские конфигурации супервизора.
  • Если для аутентификации по токену требуется токен и gateway.auth.token управляется через SecretRef, установка/ремонт сервиса doctor проверяет SecretRef, но не сохраняет разрешенные значения токена в виде обычного текста в метаданных среды сервиса супервизора.
  • Если для аутентификации по токену требуется токен и настроенный SecretRef токена не разрешен, doctor блокирует путь установки/ремонта с конкретными указаниями.
  • Если настроены и gateway.auth.token, и gateway.auth.password, а gateway.auth.mode не установлен, doctor блокирует установку/ремонт до явного указания режима.
  • Вы всегда можете принудительно выполнить полную перезапись через openclaw gateway install --force.

16) Диагностика времени выполнения шлюза + портов

Doctor проверяет время выполнения сервиса (PID, последний статус выхода) и предупреждает, когда сервис установлен, но фактически не запущен. Он также проверяет конфликты портов на порту шлюза (по умолчанию 18789) и сообщает о вероятных причинах (шлюз уже запущен, SSH-туннель).

17) Лучшие практики времени выполнения шлюза

Doctor предупреждает, когда сервис шлюза работает на Bun или пути Node под управлением менеджера версий (nvm, fnm, volta, asdf и т.д.). Каналы WhatsApp + Telegram требуют Node, а пути менеджеров версий могут сломаться после обновлений, потому что сервис не загружает вашу инициализацию оболочки. Doctor предлагает перейти на системную установку Node, когда она доступна (Homebrew/apt/choco).

18) Запись конфигурации + метаданные мастера настройки

Doctor сохраняет любые изменения конфигурации и ставит метку метаданных мастера настройки, чтобы записать запуск doctor.

19) Советы по рабочей области (резервное копирование + система памяти)

Doctor предлагает систему памяти для рабочей области, когда она отсутствует, и выводит совет по резервному копированию, если рабочая область еще не находится под управлением git. См. /concepts/agent-workspace для полного руководства по структуре рабочей области и резервному копированию через git (рекомендуется приватный GitHub или GitLab).

HeartbeatLogging