Перейти к основному содержимому

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

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..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..accounts без channels..defaultAccount или accounts.default, doctor предупреждает, что резервная маршрутизация может выбрать неожиданный аккаунт.
  • Если channels..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//sessions/
  • Директория агента:
    • из ~/.openclaw/agent/ в ~/.openclaw/agents//agent/
  • Состояние аутентификации WhatsApp (Baileys):
    • из устаревших ~/.openclaw/credentials/*.json (кроме oauth.json)
    • в ~/.openclaw/credentials/whatsapp//... (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