diff --git a/docs/uk/gateway/doctor.md b/docs/uk/gateway/doctor.md index 738267ac5..26cea1e03 100644 --- a/docs/uk/gateway/doctor.md +++ b/docs/uk/gateway/doctor.md @@ -5,18 +5,18 @@ read_when: summary: 'Команда Doctor: перевірки стану, міграції конфігурації та кроки відновлення' title: Doctor x-i18n: - generated_at: "2026-04-06T15:29:18Z" + generated_at: "2026-04-08T02:10:27Z" model: gpt-5.4 provider: openai - source_hash: a834dc7aec79c20d17bc23d37fb5f5e99e628d964d55bd8cf24525a7ee57130c + source_hash: 3761a222d9db7088f78215575fa84e5896794ad701aa716e8bf9039a4424dca6 source_path: gateway/doctor.md workflow: 15 --- # Doctor -`openclaw doctor` — це інструмент відновлення та міграції для OpenClaw. Він виправляє застарілі -конфігурації/стан, перевіряє працездатність і надає практичні кроки для відновлення. +`openclaw doctor` — це інструмент відновлення та міграції для OpenClaw. Він виправляє застарілий +конфігураційний файл/стан, перевіряє працездатність і надає практичні кроки для відновлення. ## Швидкий старт @@ -24,80 +24,81 @@ x-i18n: openclaw doctor ``` -### Headless / автоматизація +### Безголовий режим / автоматизація ```bash openclaw doctor --yes ``` -Приймає типові значення без запитів (зокрема кроки відновлення restart/service/sandbox, де це застосовно). +Прийняти типові значення без запитів (зокрема кроки відновлення перезапуску/служб/пісочниці, де це застосовно). ```bash openclaw doctor --repair ``` -Застосовує рекомендовані виправлення без запитів (виправлення + restart там, де це безпечно). +Застосувати рекомендовані виправлення без запитів (виправлення + перезапуски, де це безпечно). ```bash openclaw doctor --repair --force ``` -Також застосовує агресивні виправлення (перезаписує користувацькі конфігурації supervisor). +Застосувати також агресивні виправлення (перезаписує користувацькі конфігурації supervisor). ```bash openclaw doctor --non-interactive ``` -Запускається без запитів і застосовує лише безпечні міграції (нормалізація конфігурації + перенесення стану на диску). Пропускає дії restart/service/sandbox, які потребують підтвердження людиною. +Запустити без запитів і застосувати лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії з перезапуском/службами/пісочницею, які потребують підтвердження людини. Міграції застарілого стану запускаються автоматично, якщо їх виявлено. ```bash openclaw doctor --deep ``` -Сканує системні служби на наявність додаткових встановлень gateway (launchd/systemd/schtasks). +Просканувати системні служби на наявність додаткових встановлень gateway (launchd/systemd/schtasks). -Якщо ви хочете переглянути зміни перед записом, спершу відкрийте файл конфігурації: +Якщо ви хочете переглянути зміни перед записом, спочатку відкрийте файл конфігурації: ```bash cat ~/.openclaw/openclaw.json ``` -## Що робить команда (підсумок) +## Що він робить (стисло) - Необов’язкове попереднє оновлення для git-встановлень (лише в інтерактивному режимі). -- Перевірка актуальності UI protocol (перебудовує Control UI, якщо схема protocol новіша). -- Перевірка працездатності + запит на restart. -- Підсумок стану Skills (доступні/відсутні/заблоковані) і стан плагінів. +- Перевірка актуальності протоколу UI (перезбирає Control UI, якщо схема протоколу новіша). +- Перевірка працездатності + запит на перезапуск. +- Зведення стану Skills (доступні/відсутні/заблоковані) і стану plugin. - Нормалізація конфігурації для застарілих значень. -- Міграція конфігурації Talk із застарілих плоских полів `talk.*` у `talk.provider` + `talk.providers.`. -- Перевірки міграції browser для застарілих конфігурацій розширення Chrome і готовності Chrome MCP. +- Міграція конфігурації Talk зі старих плоских полів `talk.*` у `talk.provider` + `talk.providers.`. +- Перевірки міграції браузера для застарілих конфігурацій розширення Chrome і готовності Chrome MCP. - Попередження про перевизначення провайдера OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). -- Перевірка TLS-передумов OAuth для профілів OpenAI Codex OAuth. -- Міграція застарілого стану на диску (sessions/каталог агента/автентифікація WhatsApp). -- Міграція застарілих ключів контрактів у маніфестах плагінів (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). -- Міграція застарілого сховища cron (`jobId`, `schedule.cron`, верхньорівневі поля delivery/payload, `provider` у payload, прості резервні webhook jobs із `notify: true`). +- Попередження про затінення Codex OAuth (`models.providers.openai-codex`). +- Перевірка вимог TLS для профілів OpenAI Codex OAuth. +- Міграція застарілого стану на диску (сесії/каталог агента/автентифікація WhatsApp). +- Міграція застарілих ключів контракту маніфесту plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). +- Міграція застарілого сховища cron (`jobId`, `schedule.cron`, поля delivery/payload верхнього рівня, `provider` у payload, прості резервні webhook jobs з `notify: true`). - Перевірка файлів блокування сесій і очищення застарілих блокувань. - Перевірки цілісності стану та прав доступу (sessions, transcripts, каталог стану). -- Перевірки прав доступу до файлу конфігурації (chmod 600) при локальному запуску. -- Стан автентифікації моделей: перевіряє строк дії OAuth, може оновлювати токени, строк дії яких добігає кінця, і повідомляє про стани cooldown/disabled для auth-profile. +- Перевірки прав доступу до файлу конфігурації (`chmod 600`) під час локального запуску. +- Стан автентифікації моделей: перевіряє строк дії OAuth, може оновлювати токени, що скоро спливають, і повідомляє про стани cooldown/disabled профілів автентифікації. - Виявлення додаткового каталогу workspace (`~/openclaw`). -- Відновлення образу sandbox, якщо sandbox увімкнено. +- Відновлення образу sandbox, якщо sandboxing увімкнено. - Міграція застарілих служб і виявлення додаткових gateway. - Міграція застарілого стану каналу Matrix (у режимі `--fix` / `--repair`). -- Перевірки runtime gateway (службу встановлено, але вона не запущена; кешована мітка launchd). -- Попередження про стан каналів (зондуються із запущеного gateway). +- Перевірки середовища виконання gateway (службу встановлено, але вона не запущена; кешована мітка launchd). +- Попередження про стан каналів (отримані з запущеного gateway). - Аудит конфігурації supervisor (launchd/systemd/schtasks) з необов’язковим відновленням. -- Перевірки рекомендованих практик runtime gateway (Node проти Bun, шляхи менеджерів версій). -- Діагностика конфліктів порту gateway (типово `18789`). +- Перевірки рекомендованих практик середовища виконання gateway (Node проти Bun, шляхи менеджерів версій). +- Діагностика конфліктів портів gateway (типово `18789`). - Попередження безпеки для відкритих політик DM. -- Перевірки автентифікації gateway для локального режиму токена (пропонує згенерувати токен, якщо немає його джерела; не перезаписує конфігурації токенів через SecretRef). +- Перевірки автентифікації gateway для локального режиму токена (пропонує згенерувати токен, коли джерело токена відсутнє; не перезаписує конфігурації токенів SecretRef). - Перевірка systemd linger у Linux. -- Перевірка розміру bootstrap-файлів workspace (попередження про обрізання/наближення до межі для контекстних файлів). +- Перевірка розміру bootstrap-файлів workspace (попередження про обрізання/наближення до ліміту для контекстних файлів). - Перевірка стану shell completion і автоматичне встановлення/оновлення. -- Перевірка готовності провайдера embedding для пошуку в пам’яті (локальна модель, віддалений API key або двійковий файл QMD). -- Перевірки вихідного встановлення (невідповідність pnpm workspace, відсутні UI assets, відсутній двійковий файл tsx). -- Записує оновлену конфігурацію + метадані wizard. +- Перевірка готовності провайдера embedding для пошуку в пам’яті (локальна модель, віддалений API key або бінарний файл QMD). +- Перевірки встановлення з вихідного коду (невідповідність pnpm workspace, відсутні UI assets, відсутній бінарний файл tsx). +- Записує оновлену конфігурацію + метадані майстра. ## Докладна поведінка та обґрунтування @@ -112,25 +113,25 @@ cat ~/.openclaw/openclaw.json без перевизначення для конкретного каналу), doctor нормалізує їх до поточної схеми. -Сюди також входять застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — це -`talk.provider` + `talk.providers.`. Doctor переписує старі форми -`talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / +Сюди також входять застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — +це `talk.provider` + `talk.providers.`. Doctor переписує старі +форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у мапу провайдерів. ### 2) Міграції застарілих ключів конфігурації -Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися -і просять виконати `openclaw doctor`. +Коли конфігурація містить застарілі ключі, інші команди відмовляються виконуватися та просять +запустити `openclaw doctor`. Doctor: -- Пояснює, які саме застарілі ключі знайдено. -- Показує застосовану міграцію. -- Перезаписує `~/.openclaw/openclaw.json` за оновленою схемою. +- Пояснить, які застарілі ключі було знайдено. +- Покажe міграцію, яку він застосував. +- Перезапише `~/.openclaw/openclaw.json` за оновленою схемою. Gateway також автоматично запускає міграції doctor під час старту, коли виявляє -застарілий формат конфігурації, тому старі конфігурації виправляються без ручного втручання. -Міграції сховища cron jobs виконує `openclaw doctor --fix`. +застарілий формат конфігурації, тому старі конфігурації відновлюються без ручного втручання. +Міграції сховища cron jobs обробляються через `openclaw doctor --fix`. Поточні міграції: @@ -154,30 +155,30 @@ Gateway також автоматично запускає міграції doct - `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 може зберегти наявну відповідну іменовану/типову ціль) +- Для каналів з іменованими `accounts`, але зі збереженими однокористувацькими значеннями каналу верхнього рівня, перемістити ці значення, прив’язані до облікового запису, до вибраного підвищеного облікового запису для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну іменовану/типову ціль) - `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` (застаріле налаштування extension relay) +- видалити `browser.relayBindHost` (застаріле налаштування relay для розширення) -Попередження doctor також містять рекомендації щодо типового облікового запису для багатoоблікових каналів: +Попередження doctor також містять рекомендації щодо типового облікового запису для багатокористувацьких каналів: -- Якщо налаштовано два або більше записи `channels..accounts`, але немає `channels..defaultAccount` або `accounts.default`, doctor попереджає, що fallback-маршрутизація може вибрати неочікуваний обліковий запис. -- Якщо `channels..defaultAccount` вказано для невідомого ID облікового запису, doctor попереджає та перелічує налаштовані ID облікових записів. +- Якщо налаштовано два або більше записів `channels..accounts` без `channels..defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний обліковий запис. +- Якщо `channels..defaultAccount` установлено на невідомий ID облікового запису, doctor попереджає та перелічує налаштовані ID облікових записів. ### 2b) Перевизначення провайдера OpenCode Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`, це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`. -Через це моделі можуть використовувати неправильний API або мати нульову вартість. Doctor попереджає про це, щоб ви -могли прибрати перевизначення та відновити маршрутизацію API і вартість для кожної моделі. +Це може спрямувати моделі на неправильний API або обнулити вартість. Doctor попереджає, щоб ви +могли прибрати перевизначення й відновити маршрутизацію API та вартість для кожної моделі. -### 2c) Міграція browser і готовність Chrome MCP +### 2c) Міграція браузера та готовність Chrome MCP -Якщо ваша конфігурація browser все ще вказує на вилучений шлях розширення Chrome, doctor +Якщо ваша конфігурація браузера все ще вказує на видалений шлях розширення Chrome, doctor нормалізує її до поточної моделі підключення host-local Chrome MCP: - `browser.profiles.*.driver: "extension"` стає `"existing-session"` @@ -187,62 +188,72 @@ Doctor також перевіряє шлях host-local Chrome MCP, коли в "user"` або налаштований профіль `existing-session`: - перевіряє, чи встановлено Google Chrome на тому самому хості для типових - профілів з автоматичним підключенням + профілів автопідключення - перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144 -- нагадує увімкнути remote debugging на сторінці inspect у браузері (наприклад - `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, +- нагадує ввімкнути remote debugging на сторінці inspect браузера (наприклад + `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`) -Doctor не може увімкнути це налаштування на стороні Chrome за вас. Host-local Chrome MCP -досі потребує: +Doctor не може ввімкнути це налаштування в Chrome за вас. Host-local Chrome MCP +усе ще потребує: -- браузер на основі Chromium 144+ на хості gateway/node -- локально запущений браузер +- браузер на базі Chromium 144+ на хості gateway/node +- браузер, що працює локально - увімкнений remote debugging у цьому браузері -- підтвердження першого запиту згоди на підключення в браузері +- підтвердження першого запиту на дозвіл attach у браузері -Готовність тут стосується лише передумов локального підключення. Existing-session зберігає +Готовність тут стосується лише локальних передумов attach. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, -перехоплення завантажень і пакетні дії, як і раніше, потребують керованого -browser або сирого профілю CDP. +перехоплення завантажень і пакетні дії, усе ще потребують керованого +браузера або профілю raw CDP. -Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших -headless-потоків. Вони й надалі використовують сирий CDP. +Ця перевірка **не** застосовується до Docker, sandbox, remote-browser чи інших +безголових сценаріїв. Вони, як і раніше, використовують raw CDP. -### 2d) TLS-передумови OAuth +### 2d) Вимоги OAuth TLS -Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє кінцеву точку авторизації OpenAI, -щоб переконатися, що локальний стек Node/OpenSSL TLS може +Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє кінцеву точку +авторизації OpenAI, щоб упевнитися, що локальний стек TLS Node/OpenSSL може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад -`UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або self-signed cert), -doctor виводить інструкції з виправлення для конкретної платформи. На macOS із Node від Homebrew +`UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат), +doctor виводить інструкції з виправлення для конкретної платформи. У macOS з Node від Homebrew виправленням зазвичай є `brew postinstall ca-certificates`. З `--deep` перевірка виконується -навіть якщо gateway працездатний. +навіть якщо gateway справний. + +### 2c) Перевизначення провайдера Codex OAuth + +Якщо ви раніше додали застарілі налаштування транспорту OpenAI у +`models.providers.openai-codex`, вони можуть затіняти вбудований шлях +провайдера Codex OAuth, який новіші випуски використовують автоматично. Doctor попереджає, коли бачить +ці старі налаштування транспорту разом із Codex OAuth, щоб ви могли видалити або переписати +застаріле перевизначення транспорту та повернути вбудовану поведінку маршрутизації/резервування. +Користувацькі проксі та перевизначення лише заголовків, як і раніше, підтримуються й не +викликають цього попередження. ### 3) Міграції застарілого стану (структура на диску) -Doctor може переносити старіші структури на диску до поточної структури: +Doctor може мігрувати старіші структури на диску до поточної: -- Сховище sessions + transcripts: +- Сховище сесій + стенограми: - з `~/.openclaw/sessions/` до `~/.openclaw/agents//sessions/` - Каталог агента: - з `~/.openclaw/agent/` до `~/.openclaw/agents//agent/` - Стан автентифікації WhatsApp (Baileys): - - зі старого `~/.openclaw/credentials/*.json` (крім `oauth.json`) + - зі старих `~/.openclaw/credentials/*.json` (крім `oauth.json`) - до `~/.openclaw/credentials/whatsapp//...` (типовий ID облікового запису: `default`) -Ці міграції виконуються за принципом best-effort та є ідемпотентними; doctor виведе попередження, якщо -залишить будь-які старі каталоги як резервні копії. Gateway/CLI також автоматично мігрує -старі sessions + каталог агента під час старту, щоб history/auth/models потрапляли до -шляху для конкретного агента без ручного запуску doctor. Автентифікація WhatsApp навмисно -мігрується лише через `openclaw doctor`. Нормалізація provider/provider-map для Talk тепер -порівнює структурну рівність, тому відмінності лише в порядку ключів більше не спричиняють +Ці міграції виконуються за можливості та є ідемпотентними; doctor виведе попередження, якщо +залишить будь-які застарілі каталоги як резервні копії. Gateway/CLI також автоматично мігрує +застарілі сесії та каталог агента під час запуску, тож історія/автентифікація/моделі потрапляють у шлях +для конкретного агента без ручного запуску doctor. Автентифікація WhatsApp навмисно +мігрується лише через `openclaw doctor`. Нормалізація Talk provider/provider-map тепер +порівнює за структурною рівністю, тому відмінності лише в порядку ключів більше не викликають повторних порожніх змін `doctor --fix`. -### 3a) Міграції застарілих маніфестів плагінів +### 3a) Міграції застарілих маніфестів plugin -Doctor сканує всі встановлені маніфести плагінів на наявність застарілих верхньорівневих ключів -можливостей (`speechProviders`, `realtimeTranscriptionProviders`, +Doctor сканує всі встановлені маніфести plugin на наявність застарілих ключів +можливостей верхнього рівня (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Якщо їх знайдено, він пропонує перемістити їх до об’єкта `contracts` @@ -253,142 +264,143 @@ Doctor сканує всі встановлені маніфести плагі ### 3b) Міграції застарілого сховища cron Doctor також перевіряє сховище cron jobs (`~/.openclaw/cron/jobs.json` типово, -або `cron.store`, якщо воно перевизначене) на старі форми jobs, які планувальник -досі приймає для сумісності. +або `cron.store`, якщо його перевизначено) на старі форми job, які планувальник усе ще +приймає для сумісності. Поточні очищення cron включають: - `jobId` → `id` - `schedule.cron` → `schedule.expr` -- верхньорівневі поля payload (`message`, `model`, `thinking`, ...) → `payload` -- верхньорівневі поля delivery (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` +- поля payload верхнього рівня (`message`, `model`, `thinking`, ...) → `payload` +- поля delivery верхнього рівня (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` - псевдоніми delivery `provider` у payload → явний `delivery.channel` -- прості застарілі резервні webhook jobs із `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook` +- прості застарілі резервні webhook jobs з `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook` -Doctor автоматично мігрує jobs з `notify: true` лише тоді, коли може зробити це -без зміни поведінки. Якщо job поєднує застарілий резервний notify із наявним -режимом delivery, відмінним від webhook, doctor попереджає і залишає цей job для ручного перегляду. +Doctor автоматично мігрує jobs з `notify: true` лише тоді, коли це можна зробити без +зміни поведінки. Якщо job поєднує застарілий резервний notify з наявним +не-webhook режимом delivery, doctor попереджає й залишає цей job для ручної перевірки. ### 3c) Очищення блокувань сесій -Doctor сканує каталог сесій кожного агента на наявність застарілих файлів write-lock — файлів, -які залишилися після аварійного завершення сесії. Для кожного знайденого файлу блокування він повідомляє: -шлях, PID, чи PID ще активний, вік блокування та чи -вважається воно застарілим (мертвий PID або старше 30 хвилин). У режимі `--fix` / `--repair` +Doctor сканує каталог сесій кожного агента на наявність застарілих файлів блокування запису — файлів, +що залишилися після аварійного завершення сесії. Для кожного знайденого файлу блокування він повідомляє: +шлях, PID, чи PID усе ще активний, вік блокування та чи +вважається воно застарілим (мертвий PID або вік понад 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше виводить примітку та -пропонує повторно запустити команду з `--fix`. +пропонує повторити запуск з `--fix`. ### 4) Перевірки цілісності стану (збереження сесій, маршрутизація та безпека) -Каталог стану — це операційний стовбур системи. Якщо він зникне, ви втратите -sessions, облікові дані, журнали та конфігурацію (якщо тільки у вас немає резервних копій деінде). +Каталог стану — це операційний стовбур мозку системи. Якщо він зникне, ви втратите +сесії, облікові дані, журнали та конфігурацію (якщо у вас немає резервних копій деінде). Doctor перевіряє: - **Відсутній каталог стану**: попереджає про катастрофічну втрату стану, пропонує відтворити - каталог і нагадує, що не може відновити відсутні дані. + каталог і нагадує, що не може відновити втрачені дані. - **Права доступу до каталогу стану**: перевіряє можливість запису; пропонує виправити права (і виводить підказку `chown`, якщо виявлено невідповідність власника/групи). -- **Каталог стану macOS у хмарній синхронізації**: попереджає, якщо стан розташовано в iCloud Drive +- **Каталог стану macOS у хмарній синхронізації**: попереджає, коли стан розгортається в iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або - `~/Library/CloudStorage/...`, оскільки шляхи на основі синхронізації можуть спричиняти повільніше введення-виведення - і гонки блокувань/синхронізації. -- **Каталог стану Linux на SD або eMMC**: попереджає, якщо стан розташовано на джерелі монтування `mmcblk*`, - оскільки випадкове введення-виведення на носіях SD або eMMC може бути повільнішим і швидше зношуватися - при записі сесій та облікових даних. -- **Відсутні каталоги sessions**: `sessions/` і каталог сховища сесій - потрібні для збереження history та уникнення збоїв `ENOENT`. -- **Невідповідність transcript**: попереджає, коли в недавніх записах сесій відсутні - файли transcript. -- **Основна сесія “1-line JSONL”**: виявляє, коли основний transcript містить лише один - рядок (history не накопичується). + `~/Library/CloudStorage/...`, оскільки шляхи із синхронізацією можуть спричиняти повільніший I/O + і конфлікти блокувань/синхронізації. +- **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розгортається на джерелі монтування `mmcblk*`, + оскільки випадковий I/O на SD або eMMC може бути повільнішим і швидше зношувати носій + через записи сесій та облікових даних. +- **Відсутні каталоги сесій**: `sessions/` і каталог сховища сесій + потрібні для збереження історії та уникнення збоїв `ENOENT`. +- **Невідповідність стенограм**: попереджає, коли в недавніх записах сесій відсутні + файли стенограм. +- **Основна сесія “1-line JSONL”**: позначає випадки, коли основна стенограма має лише один + рядок (історія не накопичується). - **Кілька каталогів стану**: попереджає, коли існує кілька папок `~/.openclaw` у різних - домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (history може - розділитися між встановленнями). -- **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, doctor нагадує запустити - його на віддаленому хості (стан зберігається там). -- **Права доступу до файлу конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` - доступний на читання для групи/всіх користувачів, і пропонує обмежити права до `600`. + домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (історія може + розділятися між установками). +- **Нагадування про remote mode**: якщо `gateway.mode=remote`, doctor нагадує запустити + його на віддаленому хості (стан зберігається саме там). +- **Права доступу до файлу конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` є + читабельним для групи/усіх, і пропонує посилити права до `600`. ### 5) Стан автентифікації моделей (строк дії OAuth) -Doctor перевіряє профілі OAuth у сховищі автентифікації, попереджає, коли токени -ось-ось завершаться або вже завершилися, і може оновити їх, коли це безпечно. Якщо профіль Anthropic -OAuth/token застарів, він пропонує ключ Anthropic API або -шлях Anthropic setup-token. +Doctor перевіряє профілі OAuth у сховищі автентифікації, попереджає, коли строк дії токенів +наближається до завершення або вже завершився, і може оновити їх, якщо це безпечно. Якщо профіль +Anthropic OAuth/token застарів, він пропонує Anthropic API key або +шлях налаштування Anthropic setup-token. Запити на оновлення з’являються лише в інтерактивному режимі (TTY); `--non-interactive` пропускає спроби оновлення. -Doctor також повідомляє про auth profiles, які тимчасово непридатні до використання через: +Doctor також повідомляє про профілі автентифікації, які тимчасово непридатні до використання через: - короткі cooldown (обмеження швидкості/тайм-аути/помилки автентифікації) -- довші відключення (помилки тарифікації/кредитів) +- довші вимкнення (помилки білінгу/кредитів) ### 6) Перевірка моделі hooks -Якщо задано `hooks.gmail.model`, doctor перевіряє посилання на модель у -каталозі та allowlist і попереджає, коли воно не може бути розв’язане або не дозволене. +Якщо встановлено `hooks.gmail.model`, doctor перевіряє посилання на модель за +каталогом і allowlist та попереджає, коли його не вдається розв’язати або воно не дозволене. ### 7) Відновлення образу sandbox -Коли sandbox увімкнено, doctor перевіряє образи Docker і пропонує зібрати їх або -перемкнутися на застарілі назви, якщо поточний образ відсутній. +Коли sandboxing увімкнено, doctor перевіряє образи Docker і пропонує зібрати їх або +переключитися на застарілі імена, якщо поточний образ відсутній. -### 7b) Runtime dependencies вбудованих плагінів +### 7b) Runtime-залежності bundled plugin -Doctor перевіряє, чи наявні runtime dependencies вбудованих плагінів (наприклад, -runtime packages плагіна Discord) у кореневому каталозі встановлення OpenClaw. -Якщо чогось бракує, doctor повідомляє про пакети й установлює їх у режимі -`openclaw doctor --fix` / `openclaw doctor --repair`. +Doctor перевіряє, що runtime-залежності bundled plugin (наприклад +runtime-пакети plugin Discord) присутні в корені встановлення OpenClaw. +Якщо якихось не вистачає, doctor повідомляє про ці пакети та встановлює їх у +режимі `openclaw doctor --fix` / `openclaw doctor --repair`. -### 8) Міграції служб gateway і підказки для очищення +### 8) Міграції служб gateway та підказки з очищення Doctor виявляє застарілі служби gateway (launchd/systemd/schtasks) і -пропонує видалити їх та встановити службу OpenClaw з використанням поточного порту gateway. -Він також може сканувати додаткові служби, схожі на gateway, і виводити підказки для очищення. -Служби OpenClaw gateway з назвами профілів вважаються повноцінними й не +пропонує видалити їх та встановити службу OpenClaw з поточним портом gateway. +Він також може сканувати наявність додаткових gateway-подібних служб і виводити підказки з очищення. +Іменовані за профілем служби OpenClaw gateway вважаються повноцінними і не позначаються як "додаткові". -### 8b) Міграція стартового Matrix +### 8b) Стартова міграція Matrix -Коли для облікового запису каналу Matrix є очікувана або застосовна міграція застарілого стану, +Коли обліковий запис каналу Matrix має очікувану або придатну до виконання міграцію застарілого стану, doctor (у режимі `--fix` / `--repair`) створює знімок стану до міграції, а потім -виконує кроки міграції за принципом best-effort: міграцію застарілого стану Matrix і підготовку -застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки журналюються, а -запуск триває. У режимі лише читання (`openclaw doctor` без `--fix`) цю перевірку -повністю пропущено. +виконує найкращим можливим способом кроки міграції: міграцію застарілого стану Matrix і підготовку +застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки записуються в журнал, а +запуск триває. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка +повністю пропускається. ### 9) Попередження безпеки -Doctor видає попередження, коли провайдер відкритий для DM без allowlist -або коли політику налаштовано небезпечним чином. +Doctor виводить попередження, коли провайдер відкритий для DM без allowlist або +коли політику налаштовано небезпечним чином. ### 10) systemd linger (Linux) -Якщо робота відбувається як служба користувача systemd, doctor гарантує, що linger увімкнено, щоб +Якщо система працює як користувацька служба systemd, doctor перевіряє, що lingering увімкнено, щоб gateway залишався активним після виходу з системи. -### 11) Стан workspace (Skills, плагіни та застарілі каталоги) +### 11) Стан workspace (Skills, plugins і застарілі каталоги) -Doctor виводить підсумок стану workspace для типового агента: +Doctor виводить зведення стану workspace для типового агента: -- **Стан Skills**: рахує доступні, з відсутніми вимогами та заблоковані allowlist Skills. +- **Стан Skills**: кількість доступних, тих, що не відповідають вимогам, і заблокованих allowlist Skills. - **Застарілі каталоги workspace**: попереджає, коли `~/openclaw` або інші застарілі каталоги workspace існують поруч із поточним workspace. -- **Стан плагінів**: рахує завантажені/вимкнені/з помилками плагіни; перелічує ID плагінів для - будь-яких помилок; повідомляє про можливості bundle plugins. -- **Попередження сумісності плагінів**: позначає плагіни, які мають проблеми сумісності з +- **Стан plugin**: кількість завантажених/вимкнених/plugin із помилками; перелічує ID plugin для будь-яких + помилок; повідомляє про можливості bundle plugin. +- **Попередження про сумісність plugin**: позначає plugins, які мають проблеми сумісності з поточним runtime. -- **Діагностика плагінів**: показує всі попередження або помилки під час завантаження, які - видані реєстром плагінів. +- **Діагностика plugin**: показує будь-які попередження або помилки під час завантаження, які надіслав + реєстр plugin. -### 11b) Розмір bootstrap-файлів +### 11b) Розмір bootstrap-файлу Doctor перевіряє, чи bootstrap-файли workspace (наприклад `AGENTS.md`, -`CLAUDE.md` або інші ін’єктовані файли контексту) не наблизилися або не перевищили -налаштований ліміт символів. Він повідомляє для кожного файлу сирі та ін’єктовані значення кількості символів, відсоток обрізання, -причину обрізання (`max/file` або `max/total`) і загальну кількість ін’єктованих -символів як частку від загального бюджету. Коли файли обрізано або вони близькі до межі, doctor виводить поради щодо налаштування `agents.defaults.bootstrapMaxChars` +`CLAUDE.md` або інші впроваджені контекстні файли) наближаються до налаштованого +ліміту символів або перевищують його. Він повідомляє для кожного файлу сирий та впроваджений обсяг символів, відсоток обрізання, +причину обрізання (`max/file` або `max/total`) і загальну кількість впроваджених +символів як частку від загального бюджету. Коли файли обрізано або вони наближаються до +ліміту, doctor виводить поради щодо налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`. ### 11c) Shell completion @@ -396,33 +408,33 @@ Doctor перевіряє, чи bootstrap-файли workspace (наприкла Doctor перевіряє, чи встановлено tab completion для поточної оболонки (zsh, bash, fish або PowerShell): -- Якщо профіль оболонки використовує повільну схему динамічного completion - (`source <(openclaw completion ...)`), doctor оновлює її до швидшого - варіанта з кешованим файлом. +- Якщо профіль оболонки використовує повільний шаблон динамічного completion + (`source <(openclaw completion ...)`), doctor оновлює його до швидшого + варіанту з кешованим файлом. - Якщо completion налаштовано в профілі, але файл кешу відсутній, - doctor автоматично повторно генерує кеш. + doctor автоматично відновлює кеш. - Якщо completion взагалі не налаштовано, doctor пропонує встановити його - (лише в інтерактивному режимі; пропускається з `--non-interactive`). + (лише інтерактивний режим; пропускається з `--non-interactive`). -Запустіть `openclaw completion --write-state`, щоб вручну повторно згенерувати кеш. +Запустіть `openclaw completion --write-state`, щоб відновити кеш вручну. ### 12) Перевірки автентифікації gateway (локальний токен) -Doctor перевіряє готовність локальної автентифікації gateway на основі токена. +Doctor перевіряє готовність автентифікації локального токена gateway. -- Якщо режиму токена потрібен токен і джерела токена немає, doctor пропонує згенерувати його. -- Якщо `gateway.auth.token` керується через SecretRef, але недоступний, doctor попереджає і не перезаписує його відкритим текстом. -- `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли не налаштовано SecretRef для токена. +- Якщо режим токена потребує токен, а джерела токена немає, doctor пропонує згенерувати його. +- Якщо `gateway.auth.token` керується через SecretRef, але недоступний, doctor попереджає й не перезаписує його відкритим текстом. +- `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли токен SecretRef не налаштовано. -### 12b) Виправлення в режимі лише читання з урахуванням SecretRef +### 12b) Відновлення в режимі лише читання з урахуванням SecretRef -Деякі потоки виправлення потребують перевірки налаштованих облікових даних без послаблення поведінки runtime з негайним збоєм. +Деяким сценаріям відновлення потрібно перевіряти налаштовані облікові дані без послаблення поведінки швидкої відмови під час виконання. - `openclaw doctor --fix` тепер використовує ту саму модель зведення SecretRef у режимі лише читання, що й команди сімейства status, для цільових виправлень конфігурації. -- Приклад: виправлення Telegram `allowFrom` / `groupAllowFrom` для `@username` намагається використати налаштовані облікові дані бота, якщо вони доступні. -- Якщо токен Telegram-бота налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає автоматичне розв’язання замість аварійного завершення або хибного повідомлення, що токен відсутній. +- Приклад: виправлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використовувати налаштовані облікові дані бота, коли вони доступні. +- Якщо токен Telegram-бота налаштовано через SecretRef, але він недоступний у поточному шляху виконання команди, doctor повідомляє, що облікові дані налаштовано, але вони недоступні, і пропускає автоматичне розв’язання замість аварійного завершення або хибного повідомлення про відсутність токена. -### 13) Перевірка працездатності gateway + restart +### 13) Перевірка працездатності gateway + перезапуск Doctor запускає перевірку працездатності й пропонує перезапустити gateway, якщо той виглядає несправним. @@ -432,63 +444,63 @@ Doctor запускає перевірку працездатності й пр Doctor перевіряє, чи готовий налаштований провайдер embedding для пошуку в пам’яті для типового агента. Поведінка залежить від налаштованого backend і провайдера: -- **Backend QMD**: перевіряє, чи доступний і чи запускається двійковий файл `qmd`. - Якщо ні, виводить інструкції з виправлення, включно з npm-пакетом і параметром ручного шляху до двійкового файлу. -- **Явний локальний провайдер**: перевіряє наявність локального файлу моделі або розпізнаної - віддаленої/завантажуваної URL-адреси моделі. Якщо нічого не знайдено, пропонує перейти на віддаленого провайдера. -- **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, чи є API key - у середовищі або в сховищі автентифікації. Якщо його немає, виводить практичні підказки. -- **Автоматичний провайдер**: спочатку перевіряє доступність локальної моделі, а потім пробує кожного віддаленого - провайдера у порядку автоматичного вибору. +- **QMD backend**: перевіряє, чи доступний і чи запускається бінарний файл `qmd`. + Якщо ні, виводить інструкції з виправлення, зокрема npm package та варіант ручного шляху до бінарного файла. +- **Явно локальний провайдер**: перевіряє наявність локального файлу моделі або розпізнаваного + URL віддаленої/завантажуваної моделі. Якщо його немає, пропонує перейти на віддаленого провайдера. +- **Явно віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, чи присутній API key + у середовищі або сховищі автентифікації. Якщо його немає, виводить практичні підказки для виправлення. +- **Автоматичний провайдер**: спочатку перевіряє доступність локальної моделі, а потім намагається використати кожного віддаленого + провайдера в порядку автоматичного вибору. -Коли доступний результат probe від gateway (на момент -перевірки gateway був працездатним), doctor звіряє його результат із конфігурацією, видимою CLI, і відзначає -будь-які розбіжності. +Коли доступний результат перевірки gateway (gateway був справний на момент +перевірки), doctor зіставляє його з конфігурацією, видимою CLI, і вказує +на будь-які розбіжності. -Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding у runtime. +Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding під час виконання. ### 14) Попередження про стан каналів -Якщо gateway працездатний, doctor запускає probe стану каналів і повідомляє -попередження разом із запропонованими виправленнями. +Якщо gateway справний, doctor запускає перевірку стану каналів і повідомляє +про попередження разом із пропозиціями щодо виправлення. ### 15) Аудит конфігурації supervisor + відновлення -Doctor перевіряє встановлену конфігурацію supervisor (launchd/systemd/schtasks) на -відсутні або застарілі типові значення (наприклад залежності systemd network-online і -затримку restart). Коли виявляється невідповідність, він -рекомендує оновлення і може переписати файл служби/завдання відповідно до поточних типових значень. +Doctor перевіряє встановлену конфігурацію supervisor (launchd/systemd/schtasks) на наявність +відсутніх або застарілих типових значень (наприклад, systemd network-online dependencies та +затримка перезапуску). Коли він знаходить невідповідність, то +рекомендує оновлення й може переписати файл служби/завдання відповідно до поточних типових значень. Примітки: -- `openclaw doctor` запитує підтвердження перед перезаписом конфігурації supervisor. -- `openclaw doctor --yes` приймає типові запити на виправлення. +- `openclaw doctor` запитує підтвердження перед переписуванням конфігурації supervisor. +- `openclaw doctor --yes` приймає типові запити на відновлення. - `openclaw doctor --repair` застосовує рекомендовані виправлення без запитів. - `openclaw doctor --repair --force` перезаписує користувацькі конфігурації supervisor. -- Якщо для токен-автентифікації потрібен токен і `gateway.auth.token` керується через SecretRef, шлях встановлення/відновлення служби в doctor перевіряє SecretRef, але не зберігає відкриті значення токенів, отримані з нього, у метаданих середовища служби supervisor. -- Якщо для токен-автентифікації потрібен токен, а налаштований токен SecretRef не розв’язано, doctor блокує шлях встановлення/відновлення та надає практичні вказівки. -- Якщо одночасно налаштовано `gateway.auth.token` і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує встановлення/відновлення, доки режим не буде явно задано. -- Для користувацьких systemd units у Linux перевірки розбіжностей токенів у doctor тепер враховують і джерела `Environment=`, і `EnvironmentFile=` під час порівняння метаданих автентифікації служби. +- Якщо автентифікація токеном вимагає токен, а `gateway.auth.token` керується через SecretRef, під час встановлення/відновлення служби doctor перевіряє SecretRef, але не зберігає розв’язані відкриті значення токена в метадані середовища служби supervisor. +- Якщо автентифікація токеном вимагає токен, а налаштований токен SecretRef не розв’язується, doctor блокує шлях встановлення/відновлення та надає практичні вказівки. +- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не встановлено, doctor блокує встановлення/відновлення, доки режим не буде явно задано. +- Для користувацьких systemd unit у Linux перевірки розбіжності токенів у doctor тепер включають обидва джерела `Environment=` і `EnvironmentFile=` під час порівняння метаданих автентифікації служби. - Ви завжди можете примусово виконати повний перезапис через `openclaw gateway install --force`. -### 16) Діагностика runtime gateway і порту +### 16) Діагностика runtime gateway + порту Doctor перевіряє runtime служби (PID, останній статус завершення) і попереджає, коли -службу встановлено, але вона фактично не запущена. Він також перевіряє конфлікти -на порту gateway (типово `18789`) і повідомляє про ймовірні причини (gateway уже -запущено, SSH tunnel). +службу встановлено, але вона фактично не запущена. Він також перевіряє конфлікти портів +на порту gateway (типово `18789`) і повідомляє ймовірні причини (gateway уже +працює, SSH tunnel). ### 17) Рекомендовані практики runtime gateway -Doctor попереджає, коли служба gateway працює на Bun або на шляху Node, керованому -менеджером версій (`nvm`, `fnm`, `volta`, `asdf` тощо). Каналам WhatsApp + Telegram потрібен Node, -а шляхи менеджерів версій можуть ламатися після оновлень, тому що служба не -завантажує ініціалізацію вашої оболонки. Doctor пропонує перейти на системне встановлення Node, якщо -воно доступне (Homebrew/apt/choco). +Doctor попереджає, коли служба gateway працює на Bun або через шлях Node, керований менеджером версій +(`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram вимагають Node, +а шляхи менеджерів версій можуть ламатися після оновлень, оскільки служба не +завантажує вашу ініціалізацію оболонки. Doctor пропонує перейти на системне встановлення Node, +якщо воно доступне (Homebrew/apt/choco). -### 18) Запис конфігурації + метадані wizard +### 18) Запис конфігурації + метадані майстра -Doctor зберігає всі зміни конфігурації й проставляє метадані wizard, щоб зафіксувати +Doctor зберігає будь-які зміни конфігурації та проставляє метадані майстра, щоб зафіксувати запуск doctor. ### 19) Поради щодо workspace (резервне копіювання + система пам’яті) @@ -496,5 +508,5 @@ Doctor зберігає всі зміни конфігурації й прост Doctor пропонує систему пам’яті workspace, якщо її немає, і виводить пораду щодо резервного копіювання, якщо workspace ще не перебуває під git. -Повний посібник зі структури -workspace та резервного копіювання через git (рекомендовано приватний GitHub або GitLab) див. у [/concepts/agent-workspace](/uk/concepts/agent-workspace). +Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace), щоб отримати повний посібник зі +структури workspace та резервного копіювання через git (рекомендовано приватний GitHub або GitLab).