---
read_when:
    - Додавання або зміна міграцій doctor
    - Запровадження несумісних змін конфігурації
summary: 'Команда doctor: перевірки стану, міграції конфігурації та кроки відновлення'
title: Doctor
x-i18n:
    generated_at: "2026-04-20T06:08:07Z"
    model: gpt-5.4
    provider: openai
    source_hash: 61a5e01a306058c49be6095f7c8082d779a55d63cf3b5f4c4096173943faf51b
    source_path: gateway/doctor.md
    workflow: 15
---

# Doctor

`openclaw doctor` — це інструмент відновлення та міграції для OpenClaw. Він виправляє застарілі конфігурації/стан, перевіряє стан системи та надає практичні кроки для відновлення.

## Швидкий старт

```bash
openclaw doctor
```

### Headless / автоматизація

```bash
openclaw doctor --yes
```

Прийняти типові значення без запитів (зокрема кроки відновлення перезапуску/служб/sandbox, якщо застосовно).

```bash
openclaw doctor --repair
```

Застосувати рекомендовані виправлення без запитів (виправлення + перезапуски, де це безпечно).

```bash
openclaw doctor --repair --force
```

Застосувати також агресивні виправлення (перезаписує користувацькі конфігурації supervisor).

```bash
openclaw doctor --non-interactive
```

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

```bash
openclaw doctor --deep
```

Сканувати системні служби на наявність додаткових інсталяцій gateway (`launchd/systemd/schtasks`).

Якщо ви хочете переглянути зміни перед записом, спочатку відкрийте файл конфігурації:

```bash
cat ~/.openclaw/openclaw.json
```

## Що він робить (коротко)

- Необов’язкове попереднє оновлення для git-інсталяцій (лише в інтерактивному режимі).
- Перевірка актуальності протоколу UI (перебудовує Control UI, якщо схема протоколу новіша).
- Перевірка стану + запит на перезапуск.
- Підсумок стану Skills (доступні/відсутні/заблоковані) і стану plugin.
- Нормалізація конфігурації для застарілих значень.
- Міграція конфігурації Talk із застарілих плоских полів `talk.*` у `talk.provider` + `talk.providers.<provider>`.
- Перевірки міграції browser для застарілих конфігурацій розширення Chrome і готовності Chrome MCP.
- Попередження про перевизначення провайдера OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
- Попередження про затінення OAuth Codex (`models.providers.openai-codex`).
- Перевірка TLS-передумов OAuth для профілів OpenAI Codex OAuth.
- Міграція застарілого стану на диску (sessions/каталог agent/автентифікація WhatsApp).
- Міграція застарілого ключа контракту маніфесту plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Міграція застарілого сховища Cron (`jobId`, `schedule.cron`, поля delivery/payload верхнього рівня, `provider` у payload, прості резервні Webhook-задачі `notify: true`).
- Перевірка файлів блокування сесій і очищення застарілих блокувань.
- Перевірки цілісності стану та прав доступу (sessions, transcripts, каталог state).
- Перевірка прав доступу до файлу конфігурації (`chmod 600`) під час локального запуску.
- Стан автентифікації моделей: перевіряє строк дії OAuth, може оновлювати токени, строк дії яких спливає, і повідомляє про стани cooldown/disabled профілю автентифікації.
- Виявлення додаткового робочого каталогу (`~/openclaw`).
- Відновлення образу sandbox, коли sandboxing увімкнено.
- Міграція застарілих служб і виявлення додаткових gateway.
- Міграція застарілого стану каналу Matrix (у режимі `--fix` / `--repair`).
- Перевірки середовища виконання gateway (службу встановлено, але не запущено; кешований label `launchd`).
- Попередження про стан каналів (зондуються із запущеного gateway).
- Аудит конфігурації supervisor (`launchd/systemd/schtasks`) з необов’язковим відновленням.
- Перевірки рекомендованих практик для середовища виконання gateway (Node vs Bun, шляхи менеджера версій).
- Діагностика конфліктів порту gateway (типово `18789`).
- Попередження безпеки для відкритих політик DM.
- Перевірки автентифікації gateway для режиму локального токена (пропонує згенерувати токен, якщо джерело токена відсутнє; не перезаписує конфігурації токенів SecretRef).
- Виявлення проблем із pairing пристроїв (очікувані перші запити на pairing, очікувані підвищення ролі/області дії, застарілий дрейф локального кешу токенів пристрою та дрейф автентифікації записів paired).
- Перевірка `systemd linger` на Linux.
- Перевірка розміру файлів bootstrap робочого простору (попередження про обрізання/наближення до ліміту для контекстних файлів).
- Перевірка стану shell completion та автоматичне встановлення/оновлення.
- Перевірка готовності провайдера embedding для пошуку в пам’яті (локальна модель, віддалений ключ API або бінарний файл QMD).
- Перевірки інсталяції з вихідного коду (невідповідність робочого простору pnpm, відсутні ресурси UI, відсутній бінарний файл tsx).
- Записує оновлену конфігурацію та метадані wizard.

## Заповнення Dreams UI і скидання

Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded**
для процесу grounded dreaming. Ці дії використовують RPC-методи в стилі doctor для gateway, але вони **не** є частиною CLI-відновлення/міграції `openclaw doctor`.

Що вони роблять:

- **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному робочому просторі, виконує grounded REM-прохід щоденника та записує оборотні записи backfill у `DREAMS.md`.
- **Reset** видаляє з `DREAMS.md` лише ті записи щоденника backfill, що мають відповідну позначку.
- **Clear Grounded** видаляє лише staged grounded-only короткострокові записи, що походять з історичного відтворення і ще не накопичили live recall або щоденну підтримку.

Чого вони самі по собі **не** роблять:

- вони не редагують `MEMORY.md`
- вони не запускають повні міграції doctor
- вони не переводять автоматично grounded candidates до живого сховища підвищення short-term, якщо ви явно не запустили staged CLI-шлях раніше

Якщо ви хочете, щоб grounded historical replay впливав на звичайний шлях deep promotion, використовуйте натомість CLI-процес:

```bash
openclaw memory rem-backfill --path ./memory --stage-short-term
```

Це переводить grounded durable candidates до сховища short-term dreaming, зберігаючи `DREAMS.md` як поверхню перегляду.

## Докладна поведінка та обґрунтування

### 0) Необов’язкове оновлення (git-інсталяції)

Якщо це git checkout і doctor запущено в інтерактивному режимі, він запропонує
оновитися (fetch/rebase/build) перед запуском doctor.

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

Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction`
без channel-specific перевизначення), doctor нормалізує їх до поточної
схеми.

Це також включає застарілі плоскі поля Talk. Поточна публічна конфігурація Talk —
це `talk.provider` + `talk.providers.<provider>`. Doctor переписує старі
форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` /
`talk.apiKey` у мапу провайдерів.

### 2) Міграції застарілих ключів конфігурації

Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися і просять
вас виконати `openclaw doctor`.

Doctor виконає таке:

- Пояснить, які застарілі ключі було знайдено.
- Покажe міграцію, яку він застосував.
- Перезапише `~/.openclaw/openclaw.json` з оновленою схемою.

Gateway також автоматично запускає міграції doctor під час старту, коли виявляє
застарілий формат конфігурації, тож застарілі конфігурації виправляються без ручного втручання.
Міграції сховища Cron обробляються командою `openclaw doctor --fix`.

Поточні міграції:

- `routing.allowFrom` → `channels.whatsapp.allowFrom`
- `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention`
- `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
- `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
- `routing.queue` → `messages.queue`
- `routing.bindings` → `bindings` верхнього рівня
- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
- застарілі `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.<provider>`
- `routing.agentToAgent` → `tools.agentToAgent`
- `routing.transcribeAudio` → `tools.media.audio.models`
- `messages.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.<provider>`
- `channels.discord.voice.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.voice.tts.providers.<provider>`
- `channels.discord.accounts.<id>.voice.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.accounts.<id>.voice.tts.providers.<provider>`
- `plugins.entries.voice-call.config.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `plugins.entries.voice-call.config.tts.providers.<provider>`
- `plugins.entries.voice-call.config.provider: "log"` → `"mock"`
- `plugins.entries.voice-call.config.twilio.from` → `plugins.entries.voice-call.config.fromNumber`
- `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider`
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold`
  → `plugins.entries.voice-call.config.streaming.providers.openai.*`
- `bindings[].match.accountID` → `bindings[].match.accountId`
- Для каналів з іменованими `accounts`, але із залишковими однокористувацькими значеннями каналу верхнього рівня, перемістити ці значення рівня облікового запису до вибраного підвищеного облікового запису для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну ціль named/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`
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
- видалити `browser.relayBindHost` (застарілий параметр relay для extension)

Попередження doctor також містять рекомендації щодо default account для багатокористувацьких каналів:

- Якщо налаштовано два або більше записи `channels.<channel>.accounts` без `channels.<channel>.defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний обліковий запис.
- Якщо `channels.<channel>.defaultAccount` встановлено на невідомий ідентифікатор облікового запису, doctor попереджає та перелічує налаштовані ідентифікатори облікових записів.

### 2b) Перевизначення провайдера OpenCode

Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`,
це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`.
Це може змусити моделі використовувати неправильний API або обнулити вартість. Doctor попереджає про це, щоб ви
могли видалити перевизначення і відновити маршрутизацію API та вартість для кожної моделі.

### 2c) Міграція browser і готовність Chrome MCP

Якщо ваша конфігурація browser усе ще вказує на видалений шлях розширення Chrome, doctor
нормалізує її до поточної моделі підключення host-local Chrome MCP:

- `browser.profiles.*.driver: "extension"` стає `"existing-session"`
- `browser.relayBindHost` видаляється

Doctor також перевіряє шлях host-local Chrome MCP, коли ви використовуєте `defaultProfile:
"user"` або налаштований профіль `existing-session`:

- перевіряє, чи встановлено Google Chrome на тому самому хості для типових
  профілів з автоматичним підключенням
- перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144
- нагадує увімкнути remote debugging на сторінці inspect браузера (наприклад
  `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`,
  або `edge://inspect/#remote-debugging`)

Doctor не може увімкнути цей параметр на стороні Chrome за вас. Host-local Chrome MCP
досі потребує:

- браузер на основі Chromium 144+ на хості gateway/node
- локально запущений браузер
- увімкнений remote debugging у цьому браузері
- підтвердження першого запиту на attach consent у браузері

Готовність тут стосується лише передумов локального attach. Existing-session зберігає
поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF,
перехоплення завантажень та пакетні дії, як і раніше, потребують керованого
browser або сирого профілю CDP.

Ця перевірка **не** застосовується до Docker, sandbox, remote-browser чи інших
headless-сценаріїв. Вони й надалі використовують сирий CDP.

### 2d) TLS-передумови OAuth

Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє endpoint авторизації OpenAI, щоб переконатися, що локальний стек TLS Node/OpenSSL може
перевірити ланцюжок сертифікатів. Якщо перевірка не проходить через помилку сертифіката (наприклад,
`UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат),
doctor виводить специфічні для платформи рекомендації щодо виправлення. На macOS з Node від Homebrew
виправленням зазвичай є `brew postinstall ca-certificates`. З `--deep` перевірка виконується
навіть якщо gateway у справному стані.

### 2c) Перевизначення провайдера Codex OAuth

Якщо ви раніше додали застарілі параметри транспорту OpenAI у
`models.providers.openai-codex`, вони можуть затіняти вбудований шлях
провайдера Codex OAuth, який новіші релізи використовують автоматично. Doctor попереджає, коли бачить
ці старі параметри транспорту разом із Codex OAuth, щоб ви могли видалити або переписати
застаріле перевизначення транспорту й повернути вбудовану поведінку
маршрутизації/резервного перемикання. Користувацькі проксі та перевизначення лише заголовків, як і раніше, підтримуються й не
викликають цього попередження.

### 3) Міграції застарілого стану (структура на диску)

Doctor може мігрувати старіші структури на диску до поточної структури:

- Сховище sessions + transcripts:
  - з `~/.openclaw/sessions/` до `~/.openclaw/agents/<agentId>/sessions/`
- Каталог agent:
  - з `~/.openclaw/agent/` до `~/.openclaw/agents/<agentId>/agent/`
- Стан автентифікації WhatsApp (Baileys):
  - із застарілих `~/.openclaw/credentials/*.json` (крім `oauth.json`)
  - до `~/.openclaw/credentials/whatsapp/<accountId>/...` (типовий id облікового запису: `default`)

Ці міграції виконуються за принципом best-effort та є ідемпотентними; doctor виводить попередження, коли
залишає будь-які застарілі каталоги як резервні копії. Gateway/CLI також автоматично мігрує
застарілі sessions + каталог agent під час запуску, тож історія/автентифікація/моделі потрапляють у шлях
для конкретного agent без ручного запуску doctor. Автентифікація WhatsApp навмисно
мігрується лише через `openclaw doctor`. Нормалізація Talk provider/provider-map тепер
порівнює за структурною рівністю, тож відмінності лише в порядку ключів більше не викликають
повторних порожніх змін у `doctor --fix`.

### 3a) Міграції застарілих маніфестів plugin

Doctor сканує всі встановлені маніфести plugin на наявність застарілих capability-ключів
верхнього рівня (`speechProviders`, `realtimeTranscriptionProviders`,
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
`imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`,
`webSearchProviders`). Якщо їх знайдено, він пропонує перемістити їх в об’єкт `contracts`
і переписати файл маніфесту на місці. Ця міграція є ідемпотентною;
якщо ключ `contracts` уже містить ті самі значення, застарілий ключ видаляється
без дублювання даних.

### 3b) Міграції застарілого сховища Cron

Doctor також перевіряє сховище завдань Cron (`~/.openclaw/cron/jobs.json` типово,
або `cron.store`, якщо його перевизначено) на наявність старих форм завдань, які планувальник
досі приймає для сумісності.

Поточні очищення Cron включають:

- `jobId` → `id`
- `schedule.cron` → `schedule.expr`
- поля payload верхнього рівня (`message`, `model`, `thinking`, ...) → `payload`
- поля delivery верхнього рівня (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
- псевдоніми доставки payload `provider` → явний `delivery.channel`
- прості застарілі резервні Webhook-завдання `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook`

Doctor автоматично мігрує завдання `notify: true`, лише коли може зробити це
без зміни поведінки. Якщо завдання поєднує застарілий резервний notify із вже наявним
режимом доставки не через webhook, doctor попереджає і залишає це завдання для ручної перевірки.

### 3c) Очищення блокувань сесій

Doctor сканує каталог сесій кожного agent на наявність застарілих файлів блокування запису —
файлів, що залишилися після аварійного завершення сесії. Для кожного знайденого файлу блокування він повідомляє:
шлях, PID, чи активний цей PID, вік блокування та чи
вважається воно застарілим (мертвий PID або старше 30 хвилин). У режимі `--fix` / `--repair`
він автоматично видаляє застарілі файли блокування; інакше лише виводить примітку та
пропонує перезапустити з `--fix`.

### 4) Перевірки цілісності стану (збереження сесії, маршрутизація та безпека)

Каталог стану — це операційний стовбур системи. Якщо він зникне, ви втратите
sessions, credentials, logs і config (якщо тільки в вас немає резервних копій в іншому місці).

Doctor перевіряє:

- **Відсутній каталог стану**: попереджає про катастрофічну втрату стану, пропонує повторно створити
  каталог і нагадує, що не може відновити відсутні дані.
- **Права доступу до каталогу стану**: перевіряє можливість запису; пропонує відновити права доступу
  (і виводить підказку `chown`, якщо виявлено невідповідність власника/групи).
- **Каталог стану macOS, синхронізований із хмарою**: попереджає, коли стан розміщено в iCloud Drive
  (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або
  `~/Library/CloudStorage/...`, оскільки шляхи із синхронізацією можуть спричиняти повільніший I/O
  і перегони блокування/синхронізації.
- **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розміщено на джерелі монтування `mmcblk*`,
  оскільки випадковий I/O на SD або eMMC може бути повільнішим і швидше зношувати носій
  під час запису sessions і credentials.
- **Відсутні каталоги sessions**: `sessions/` і каталог сховища сесій
  потрібні для збереження історії та уникнення аварій `ENOENT`.
- **Невідповідність transcript**: попереджає, коли в недавніх записах сесії відсутні
  файли transcript.
- **Основна сесія “1-line JSONL”**: позначає випадки, коли основний transcript містить лише один
  рядок (історія не накопичується).
- **Кілька каталогів стану**: попереджає, коли існує кілька каталогів `~/.openclaw` у різних
  домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (історія може
  розділятися між інсталяціями).
- **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, doctor нагадує виконати
  його на віддаленому хості (там розміщується стан).
- **Права доступу до файлу конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json`
  доступний для читання групі/усім, і пропонує обмежити права до `600`.

### 5) Стан автентифікації моделей (строк дії OAuth)

Doctor перевіряє профілі OAuth у сховищі автентифікації, попереджає, коли токени
спливають/уже спливли, і може оновлювати їх, коли це безпечно. Якщо профіль
OAuth/token Anthropic застарів, він пропонує ключ Anthropic API або
шлях Anthropic setup-token.
Запити на оновлення з’являються лише в інтерактивному режимі (TTY); `--non-interactive`
пропускає спроби оновлення.

Коли оновлення OAuth остаточно не вдається (наприклад, `refresh_token_reused`,
`invalid_grant` або коли провайдер каже увійти знову), doctor повідомляє,
що потрібна повторна автентифікація, і виводить точну команду `openclaw models auth login --provider ...`,
яку потрібно виконати.

Doctor також повідомляє про профілі автентифікації, які тимчасово непридатні до використання через:

- короткі періоди cooldown (обмеження швидкості/тайм-аути/помилки автентифікації)
- довші вимкнення (помилки білінгу/кредитів)

### 6) Перевірка моделі hooks

Якщо встановлено `hooks.gmail.model`, doctor перевіряє посилання на модель щодо
каталогу та allowlist і попереджає, якщо воно не буде дозволене або не може бути знайдене.

### 7) Відновлення образу sandbox

Коли sandboxing увімкнено, doctor перевіряє образи Docker і пропонує зібрати їх або
перейти на застарілі назви, якщо поточний образ відсутній.

### 7b) Runtime-залежності bundled plugin

Doctor перевіряє, що runtime-залежності bundled plugin (наприклад,
runtime-пакети plugin Discord) присутні в корені інсталяції OpenClaw.
Якщо чогось бракує, doctor повідомляє про пакети й установлює їх у режимі
`openclaw doctor --fix` / `openclaw doctor --repair`.

### 8) Міграції служб gateway і підказки з очищення

Doctor виявляє застарілі служби gateway (`launchd/systemd/schtasks`) і
пропонує видалити їх та встановити службу OpenClaw з використанням поточного
порту gateway. Він також може сканувати наявність додаткових служб, схожих на gateway, і виводити підказки з очищення.
Іменовані за профілем служби OpenClaw gateway вважаються повноцінними й не
позначаються як "зайві".

### 8b) Стартова міграція Matrix

Коли обліковий запис каналу Matrix має очікувану або придатну до виконання міграцію застарілого стану,
doctor (у режимі `--fix` / `--repair`) створює знімок до міграції, а потім
виконує кроки міграції за принципом best-effort: міграцію застарілого стану Matrix
та підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки журналюються, а
запуск триває. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка
повністю пропускається.

### 8c) Pairing пристроїв і дрейф автентифікації

Doctor тепер перевіряє стан pairing пристроїв як частину звичайної перевірки стану.

Що він повідомляє:

- очікувані запити на pairing уперше
- очікувані підвищення ролей для вже paired пристроїв
- очікувані підвищення scope для вже paired пристроїв
- відновлення невідповідностей публічного ключа, коли id пристрою все ще збігається, але
  ідентичність пристрою більше не збігається зі схваленим записом
- paired-записи без активного токена для схваленої ролі
- paired-токени, чиї scope відхиляються від затвердженої базової лінії pairing
- локальні кешовані записи токенів пристрою для поточної машини, які передують
  ротації токена на боці gateway або містять застарілі метадані scope

Doctor не схвалює запити на pairing автоматично й не виконує автоматичну ротацію токенів пристрою. Натомість
він виводить точні наступні кроки:

- перегляньте очікувані запити за допомогою `openclaw devices list`
- схваліть точний запит за допомогою `openclaw devices approve <requestId>`
- виконайте ротацію нового токена за допомогою `openclaw devices rotate --device <deviceId> --role <role>`
- видаліть застарілий запис і повторно схваліть його за допомогою `openclaw devices remove <deviceId>`

Це закриває типову прогалину "вже paired, але все ще отримує pairing required":
doctor тепер розрізняє pairing уперше, очікувані підвищення ролі/scope
та дрейф застарілого токена/ідентичності пристрою.

### 9) Попередження безпеки

Doctor виводить попередження, коли провайдер відкритий для DM без allowlist, або
коли політику налаштовано небезпечним чином.

### 10) `systemd linger` (Linux)

Якщо запуск відбувається як користувацька служба systemd, doctor перевіряє, що linger увімкнено, щоб
gateway залишався активним після виходу з системи.

### 11) Стан робочого простору (skills, plugins і застарілі каталоги)

Doctor виводить підсумок стану робочого простору для типового agent:

- **Стан Skills**: кількість доступних skills, skills із відсутніми вимогами та skills, заблокованих allowlist.
- **Застарілі каталоги робочого простору**: попереджає, коли `~/openclaw` або інші застарілі каталоги робочого простору
  існують поруч із поточним робочим простором.
- **Стан plugin**: кількість завантажених/вимкнених/plugin з помилками; перелічує ID plugin для всіх
  помилок; повідомляє про можливості bundled plugin.
- **Попередження сумісності plugin**: позначає plugins, які мають проблеми сумісності з
  поточним runtime.
- **Діагностика plugin**: показує всі попередження або помилки під час завантаження, які видав
  реєстр plugin.

### 11b) Розмір bootstrap-файлів

Doctor перевіряє, чи bootstrap-файли робочого простору (наприклад `AGENTS.md`,
`CLAUDE.md` або інші ін’єктовані контекстні файли) наближаються до налаштованого
ліміту символів або перевищують його. Він повідомляє для кожного файлу кількість сирих та ін’єктованих символів, відсоток обрізання,
причину обрізання (`max/file` або `max/total`) і загальну кількість ін’єктованих
символів як частку від загального бюджету. Коли файли обрізаються або наближаються до
ліміту, doctor виводить поради з налаштування `agents.defaults.bootstrapMaxChars`
і `agents.defaults.bootstrapTotalMaxChars`.

### 11c) Shell completion

Doctor перевіряє, чи встановлено tab completion для поточної оболонки
(zsh, bash, fish або PowerShell):

- Якщо профіль оболонки використовує повільний динамічний шаблон completion
  (`source <(openclaw completion ...)`), doctor оновлює його до швидшого
  варіанту з кешованим файлом.
- Якщо completion налаштовано в профілі, але файл кешу відсутній,
  doctor автоматично перебудовує кеш.
- Якщо completion взагалі не налаштовано, doctor пропонує встановити його
  (лише в інтерактивному режимі; пропускається з `--non-interactive`).

Виконайте `openclaw completion --write-state`, щоб вручну перебудувати кеш.

### 12) Перевірки автентифікації gateway (локальний токен)

Doctor перевіряє готовність автентифікації локального токена gateway.

- Якщо режим токена потребує токен, а джерело токена відсутнє, doctor пропонує згенерувати його.
- Якщо `gateway.auth.token` керується через SecretRef, але недоступний, doctor попереджає і не перезаписує його відкритим текстом.
- `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли не налаштовано токен SecretRef.

### 12b) Відновлення в режимі лише читання з урахуванням SecretRef

Деякі сценарії відновлення потребують перевірки налаштованих credentials без послаблення поведінки runtime fail-fast.

- `openclaw doctor --fix` тепер використовує ту саму модель підсумку SecretRef лише для читання, що й команди сімейства status, для цільового відновлення конфігурації.
- Приклад: відновлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використати налаштовані credentials бота, якщо вони доступні.
- Якщо токен Telegram-бота налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що credential налаштовано, але недоступний, і пропускає автоматичне визначення замість аварійного завершення або помилкового повідомлення, що токен відсутній.

### 13) Перевірка стану gateway + перезапуск

Doctor виконує перевірку стану і пропонує перезапустити gateway, якщо він виглядає
несправним.

### 13b) Готовність пошуку в пам’яті

Doctor перевіряє, чи готовий налаштований провайдер embedding для пошуку в пам’яті
для типового agent. Поведінка залежить від налаштованого бекенда та провайдера:

- **Бекенд QMD**: перевіряє, чи бінарний файл `qmd` доступний і може запускатися.
  Якщо ні, виводить підказки щодо виправлення, зокрема npm-пакет і варіант ручного шляху до бінарного файла.
- **Явно заданий локальний провайдер**: перевіряє наявність локального файла моделі або розпізнаного
  URL віддаленої/завантажуваної моделі. Якщо відсутній, пропонує перейти на віддаленого провайдера.
- **Явно заданий віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, чи присутній API-ключ
  у середовищі або сховищі автентифікації. Якщо ключ відсутній, виводить практичні підказки щодо виправлення.
- **Автоматичний провайдер**: спочатку перевіряє доступність локальної моделі, а потім пробує кожного віддаленого
  провайдера в порядку автоматичного вибору.

Коли результат probe gateway доступний (gateway був справний на момент
перевірки), doctor звіряє цей результат із конфігурацією, видимою CLI, і зазначає
будь-які розбіжності.

Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding під час виконання.

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

Якщо gateway справний, doctor запускає probe стану каналів і повідомляє
попередження разом із запропонованими виправленнями.

### 15) Аудит конфігурації supervisor + відновлення

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

Примітки:

- `openclaw doctor` запитує підтвердження перед переписуванням конфігурації supervisor.
- `openclaw doctor --yes` приймає типові запити на відновлення.
- `openclaw doctor --repair` застосовує рекомендовані виправлення без запитів.
- `openclaw doctor --repair --force` перезаписує користувацькі конфігурації supervisor.
- Якщо автентифікація токеном потребує токен, а `gateway.auth.token` керується через SecretRef, встановлення/відновлення служби doctor перевіряє SecretRef, але не зберігає розв’язані plaintext-значення токена в метаданих середовища служби supervisor.
- Якщо автентифікація токеном потребує токен, а налаштований токен SecretRef не розв’язано, doctor блокує шлях встановлення/відновлення і надає практичні вказівки.
- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує встановлення/відновлення, доки режим не буде явно встановлено.
- Для користувацьких модулів user-systemd у Linux перевірки дрейфу токена в doctor тепер охоплюють і джерела `Environment=`, і `EnvironmentFile=` під час порівняння метаданих автентифікації служби.
- Ви завжди можете примусово виконати повний перезапис через `openclaw gateway install --force`.

### 16) Діагностика середовища виконання gateway + порту

Doctor перевіряє середовище виконання служби (PID, останній статус виходу) і попереджає, якщо
службу встановлено, але вона фактично не запущена. Він також перевіряє конфлікти портів
на порту gateway (типово `18789`) і повідомляє ймовірні причини (gateway уже запущено,
SSH-тунель).

### 17) Рекомендовані практики для середовища виконання gateway

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

### 18) Запис конфігурації + метадані wizard

Doctor зберігає будь-які зміни конфігурації та проставляє метадані wizard, щоб зафіксувати
запуск doctor.

### 19) Поради щодо робочого простору (резервне копіювання + система пам’яті)

Doctor пропонує систему пам’яті робочого простору, якщо вона відсутня, і виводить пораду щодо резервного копіювання,
якщо робочий простір ще не перебуває під git.

Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace), щоб ознайомитися з повним посібником щодо
структури робочого простору та резервного копіювання через git (рекомендовано приватний GitHub або GitLab).
