diff --git a/docs/uk/automation/hooks.md b/docs/uk/automation/hooks.md index c81753112..a35857e00 100644 --- a/docs/uk/automation/hooks.md +++ b/docs/uk/automation/hooks.md @@ -1,26 +1,26 @@ --- read_when: - - Вам потрібна подієво-керована автоматизація для /new, /reset, /stop і подій життєвого циклу агента + - Вам потрібна автоматизація, керована подіями, для /new, /reset, /stop і подій життєвого циклу агента - Ви хочете створювати, встановлювати або налагоджувати хуки summary: 'Хуки: подієво-керована автоматизація для команд і подій життєвого циклу' title: Хуки x-i18n: - generated_at: "2026-05-03T13:47:07Z" + generated_at: "2026-05-05T08:03:54Z" model: gpt-5.5 provider: openai - source_hash: 15f0d120ccf7314a991da5d66e65e5c78375222a846ba01d7a04ddfe1f02cb32 + source_hash: 321eb7a583d5e8c90d2c2026f6e1cf46cd207bef52213774b469a8d46b993967 source_path: automation/hooks.md workflow: 16 --- -Hooks — це невеликі скрипти, які запускаються, коли щось відбувається всередині Gateway. Їх можна виявляти з директорій і переглядати за допомогою `openclaw hooks`. Gateway завантажує внутрішні hooks лише після того, як ви ввімкнете hooks або налаштуєте принаймні один запис hook, пакет hook, застарілий обробник чи додаткову директорію hooks. +Хуки — це невеликі скрипти, які запускаються, коли щось відбувається всередині Gateway. Їх можна виявляти в каталогах і переглядати за допомогою `openclaw hooks`. Gateway завантажує внутрішні хуки лише після того, як ви ввімкнете хуки або налаштуєте принаймні один запис хука, пакет хуків, застарілий обробник чи додатковий каталог хуків. -В OpenClaw є два типи hooks: +В OpenClaw є два типи хуків: -- **Внутрішні hooks** (ця сторінка): запускаються всередині Gateway, коли спрацьовують події агента, як-от `/new`, `/reset`, `/stop` або події життєвого циклу. -- **Webhook-и**: зовнішні HTTP endpoint-и, які дають іншим системам змогу запускати роботу в OpenClaw. Див. [Webhook-и](/uk/automation/cron-jobs#webhooks). +- **Внутрішні хуки** (ця сторінка): запускаються всередині Gateway, коли спрацьовують події агента, як-от `/new`, `/reset`, `/stop` або події життєвого циклу. +- **Webhook-и**: зовнішні HTTP-ендпоїнти, які дають змогу іншим системам запускати роботу в OpenClaw. Див. [Webhook-и](/uk/automation/cron-jobs#webhooks). -Hooks також можуть бути включені до plugins. `openclaw hooks list` показує як окремі hooks, так і hooks, керовані plugins. +Хуки також можуть постачатися всередині plugins. `openclaw hooks list` показує як окремі хуки, так і хуки, керовані plugin. ## Швидкий старт @@ -40,29 +40,29 @@ openclaw hooks info session-memory ## Типи подій -| Подія | Коли спрацьовує | -| ------------------------ | --------------------------------------------------------- | -| `command:new` | Видано команду `/new` | -| `command:reset` | Видано команду `/reset` | -| `command:stop` | Видано команду `/stop` | -| `command` | Будь-яка подія команди (загальний слухач) | -| `session:compact:before` | Перед тим, як compaction підсумовує історію | -| `session:compact:after` | Після завершення compaction | -| `session:patch` | Коли змінюються властивості сесії | -| `agent:bootstrap` | Перед вставленням bootstrap-файлів робочого простору | -| `gateway:startup` | Після запуску каналів і завантаження hooks | -| `gateway:shutdown` | Коли починається завершення роботи gateway | -| `gateway:pre-restart` | Перед очікуваним перезапуском gateway | -| `message:received` | Вхідне повідомлення з будь-якого каналу | -| `message:transcribed` | Після завершення транскрипції аудіо | -| `message:preprocessed` | Після завершення або пропуску попередньої обробки медіа й посилань | -| `message:sent` | Вихідне повідомлення доставлено | +| Подія | Коли вона спрацьовує | +| ------------------------ | ---------------------------------------------------------- | +| `command:new` | Видано команду `/new` | +| `command:reset` | Видано команду `/reset` | +| `command:stop` | Видано команду `/stop` | +| `command` | Будь-яка подія команди (загальний слухач) | +| `session:compact:before` | Перед тим, як Compaction підсумовує історію | +| `session:compact:after` | Після завершення Compaction | +| `session:patch` | Коли змінено властивості сесії | +| `agent:bootstrap` | Перед вставленням файлів початкового налаштування робочої області | +| `gateway:startup` | Після запуску каналів і завантаження хуків | +| `gateway:shutdown` | Коли починається завершення роботи gateway | +| `gateway:pre-restart` | Перед очікуваним перезапуском gateway | +| `message:received` | Вхідне повідомлення з будь-якого каналу | +| `message:transcribed` | Після завершення транскрибування аудіо | +| `message:preprocessed` | Після завершення або пропуску попередньої обробки медіа та посилань | +| `message:sent` | Доставлено вихідне повідомлення | -## Написання hooks +## Написання хуків -### Структура hook +### Структура хука -Кожен hook — це директорія, що містить два файли: +Кожен хук — це каталог, що містить два файли: ``` my-hook/ @@ -87,15 +87,15 @@ Detailed documentation goes here. **Поля метаданих** (`metadata.openclaw`): -| Поле | Опис | -| ---------- | ---------------------------------------------------- | -| `emoji` | Емодзі для відображення в CLI | -| `events` | Масив подій, які потрібно слухати | -| `export` | Іменований export для використання (за замовчуванням `"default"`) | +| Поле | Опис | +| ---------- | ----------------------------------------------------- | +| `emoji` | Емодзі для відображення в CLI | +| `events` | Масив подій, які потрібно слухати | +| `export` | Іменований експорт для використання (за замовчуванням `"default"`) | | `os` | Потрібні платформи (наприклад, `["darwin", "linux"]`) | -| `requires` | Потрібні шляхи `bins`, `anyBins`, `env` або `config` | -| `always` | Обійти перевірки придатності (булеве значення) | -| `install` | Методи встановлення | +| `requires` | Потрібні шляхи `bins`, `anyBins`, `env` або `config` | +| `always` | Обійти перевірки придатності (булеве значення) | +| `install` | Методи встановлення | ### Реалізація обробника @@ -115,64 +115,64 @@ const handler = async (event) => { export default handler; ``` -Кожна подія містить: `type`, `action`, `sessionKey`, `timestamp`, `messages` (додайте елемент, щоб надіслати користувачу), і `context` (дані, специфічні для події). Контексти hooks agents і tool plugins також можуть містити `trace`, діагностичний контекст трасування лише для читання, сумісний із W3C, який plugins можуть передавати в структуровані журнали для кореляції OTEL. +Кожна подія містить: `type`, `action`, `sessionKey`, `timestamp`, `messages` (додайте елемент, щоб надіслати користувачу), і `context` (дані, специфічні для події). Контексти хуків агента та інструментального plugin також можуть містити `trace`, контекст діагностичного трасування, сумісний із W3C і доступний лише для читання, який plugins можуть передавати в структуровані журнали для кореляції OTEL. -### Основні моменти контексту подій +### Основні дані контексту подій **Події команд** (`command:new`, `command:reset`): `context.sessionEntry`, `context.previousSessionEntry`, `context.commandSource`, `context.workspaceDir`, `context.cfg`. -**Події повідомлень** (`message:received`): `context.from`, `context.content`, `context.channelId`, `context.metadata` (дані, специфічні для провайдера, зокрема `senderId`, `senderName`, `guildId`). `context.content` надає перевагу непорожньому тілу команди для повідомлень, схожих на команди, а потім повертається до сирого вхідного тіла та загального тіла; він не містить збагачення лише для агента, такого як історія треду чи підсумки посилань. +**Події повідомлень** (`message:received`): `context.from`, `context.content`, `context.channelId`, `context.metadata` (дані, специфічні для провайдера, зокрема `senderId`, `senderName`, `guildId`). `context.content` віддає перевагу непорожньому тілу команди для повідомлень, схожих на команди, а потім повертається до сирого вхідного тіла та загального тіла; воно не містить збагачення, призначеного лише для агента, як-от історія гілки або підсумки посилань. **Події повідомлень** (`message:sent`): `context.to`, `context.content`, `context.success`, `context.channelId`. **Події повідомлень** (`message:transcribed`): `context.transcript`, `context.from`, `context.channelId`, `context.mediaPath`. -**Події повідомлень** (`message:preprocessed`): `context.bodyForAgent` (фінальне збагачене тіло), `context.from`, `context.channelId`. +**Події повідомлень** (`message:preprocessed`): `context.bodyForAgent` (остаточне збагачене тіло), `context.from`, `context.channelId`. -**Bootstrap-події** (`agent:bootstrap`): `context.bootstrapFiles` (змінюваний масив), `context.agentId`. +**Події початкового налаштування** (`agent:bootstrap`): `context.bootstrapFiles` (змінюваний масив), `context.agentId`. -**Події patch сесії** (`session:patch`): `context.sessionEntry`, `context.patch` (лише змінені поля), `context.cfg`. Лише привілейовані клієнти можуть запускати patch-події. +**Події виправлення сесії** (`session:patch`): `context.sessionEntry`, `context.patch` (лише змінені поля), `context.cfg`. Лише привілейовані клієнти можуть запускати події виправлення. -**Події compaction**: `session:compact:before` містить `messageCount`, `tokenCount`. `session:compact:after` додає `compactedCount`, `summaryLength`, `tokensBefore`, `tokensAfter`. +**Події Compaction**: `session:compact:before` містить `messageCount`, `tokenCount`. `session:compact:after` додає `compactedCount`, `summaryLength`, `tokensBefore`, `tokensAfter`. -`command:stop` спостерігає за тим, як користувач видає `/stop`; це життєвий цикл скасування/команди, а не шлюз фіналізації агента. Plugins, яким потрібно переглянути природну фінальну відповідь і попросити агента виконати ще один прохід, мають натомість використовувати типізований plugin hook `before_agent_finalize`. Див. [Plugin hooks](/uk/plugins/hooks). +`command:stop` фіксує, що користувач видає `/stop`; це життєвий цикл скасування/команди, а не шлюз фіналізації агента. Plugins, яким потрібно переглянути природну фінальну відповідь і попросити агента виконати ще один прохід, мають натомість використовувати типізований хук plugin `before_agent_finalize`. Див. [Хуки Plugin](/uk/plugins/hooks). -**Події життєвого циклу Gateway**: `gateway:shutdown` містить `reason` і `restartExpectedMs` та спрацьовує, коли починається завершення роботи gateway. `gateway:pre-restart` містить той самий контекст, але спрацьовує лише тоді, коли завершення роботи є частиною очікуваного перезапуску й надано скінченне значення `restartExpectedMs`. Під час завершення роботи очікування кожного lifecycle hook виконується за принципом best-effort і має обмеження, щоб завершення роботи продовжувалося, якщо обробник зависає. +**Події життєвого циклу Gateway**: `gateway:shutdown` містить `reason` і `restartExpectedMs` та спрацьовує, коли починається завершення роботи gateway. `gateway:pre-restart` містить той самий контекст, але спрацьовує лише тоді, коли завершення роботи є частиною очікуваного перезапуску й надано скінченне значення `restartExpectedMs`. Під час завершення роботи очікування кожного хука життєвого циклу виконується за принципом найкращого зусилля й має обмеження, щоб завершення роботи продовжувалося, якщо обробник зависає. -## Виявлення hooks +## Виявлення хуків -Hooks виявляються з цих директорій, у порядку зростання пріоритету перевизначення: +Хуки виявляються в цих каталогах у порядку зростання пріоритету перевизначення: -1. **Вбудовані hooks**: постачаються з OpenClaw -2. **Plugin hooks**: hooks, включені до встановлених plugins -3. **Керовані hooks**: `~/.openclaw/hooks/` (встановлені користувачем, спільні для робочих просторів). Додаткові директорії з `hooks.internal.load.extraDirs` мають той самий пріоритет. -4. **Hooks робочого простору**: `/hooks/` (для окремого агента, вимкнені за замовчуванням, доки їх явно не ввімкнуть) +1. **Вбудовані хуки**: постачаються з OpenClaw +2. **Хуки Plugin**: хуки, вбудовані у встановлені plugins +3. **Керовані хуки**: `~/.openclaw/hooks/` (встановлені користувачем, спільні для робочих областей). Додаткові каталоги з `hooks.internal.load.extraDirs` мають той самий пріоритет. +4. **Хуки робочої області**: `/hooks/` (для кожного агента, вимкнені за замовчуванням, доки їх явно не ввімкнуть) -Hooks робочого простору можуть додавати нові назви hooks, але не можуть перевизначати вбудовані, керовані або надані plugins hooks із тією самою назвою. +Хуки робочої області можуть додавати нові назви хуків, але не можуть перевизначати вбудовані, керовані або надані plugin хуки з тією самою назвою. -Gateway пропускає виявлення внутрішніх hooks під час запуску, доки внутрішні hooks не налаштовано. Увімкніть вбудований або керований hook за допомогою `openclaw hooks enable `, установіть пакет hook або задайте `hooks.internal.enabled=true`, щоб увімкнути цю можливість. Коли ви вмикаєте один іменований hook, Gateway завантажує лише обробник цього hook; `hooks.internal.enabled=true`, додаткові директорії hooks і застарілі обробники вмикають широке виявлення. +Gateway пропускає виявлення внутрішніх хуків під час запуску, доки внутрішні хуки не налаштовано. Увімкніть вбудований або керований хук за допомогою `openclaw hooks enable `, установіть пакет хуків або задайте `hooks.internal.enabled=true`, щоб явно погодитися. Коли ви вмикаєте один іменований хук, Gateway завантажує лише обробник цього хука; `hooks.internal.enabled=true`, додаткові каталоги хуків і застарілі обробники вмикають широке виявлення. -### Пакети hooks +### Пакети хуків -Пакети hooks — це npm-пакети, які експортують hooks через `openclaw.hooks` у `package.json`. Установіть за допомогою: +Пакети хуків — це npm-пакети, які експортують хуки через `openclaw.hooks` у `package.json`. Установіть за допомогою: ```bash openclaw plugins install ``` -Npm specs обмежені registry-only (назва пакета + необов’язкова точна версія або dist-tag). Git/URL/file specs і діапазони semver відхиляються. +Специфікації npm підтримуються лише з реєстру (назва пакета + необов’язкова точна версія або dist-tag). Специфікації Git/URL/file і діапазони semver відхиляються. -## Вбудовані hooks +## Вбудовані хуки -| Hook | Події | Що робить | -| --------------------- | ------------------------------------------------- | ------------------------------------------------------------- | -| session-memory | `command:new`, `command:reset` | Зберігає контекст сесії в `/memory/` | -| bootstrap-extra-files | `agent:bootstrap` | Вставляє додаткові bootstrap-файли з glob-шаблонів | -| command-logger | `command` | Журналює всі команди в `~/.openclaw/logs/commands.log` | -| compaction-notifier | `session:compact:before`, `session:compact:after` | Надсилає видимі повідомлення в чаті, коли compaction сесії починається/завершується | -| boot-md | `gateway:startup` | Запускає `BOOT.md`, коли gateway стартує | +| Хук | Події | Що він робить | +| --------------------- | ------------------------------------------------- | ------------------------------------------------------------ | +| session-memory | `command:new`, `command:reset` | Зберігає контекст сесії в `/memory/` | +| bootstrap-extra-files | `agent:bootstrap` | Вставляє додаткові bootstrap-файли з glob-шаблонів | +| command-logger | `command` | Записує всі команди в `~/.openclaw/logs/commands.log` | +| compaction-notifier | `session:compact:before`, `session:compact:after` | Надсилає видимі сповіщення в чаті, коли Compaction сесії починається/завершується | +| boot-md | `gateway:startup` | Запускає `BOOT.md`, коли запускається Gateway | -Увімкніть будь-який вбудований hook: +Увімкніть будь-який вбудований хук: ```bash openclaw hooks enable @@ -180,13 +180,13 @@ openclaw hooks enable -### Деталі session-memory +### подробиці session-memory -Витягує останні 15 повідомлень користувача/асистента, генерує описовий slug імені файлу через LLM і зберігає в `/memory/YYYY-MM-DD-slug.md` з використанням локальної дати хоста. Потрібно, щоб `workspace.dir` було налаштовано. +Витягує останні 15 повідомлень користувача/асистента й зберігає їх у `/memory/YYYY-MM-DD-HHMM.md` з використанням локальної дати хоста. Захоплення пам’яті виконується у фоні, тому підтвердження `/new` і `/reset` не затримуються через читання транскрипту або необов’язкове генерування slug. Установіть `hooks.internal.entries.session-memory.llmSlug: true`, щоб генерувати описові slug для імен файлів за допомогою налаштованої моделі. Потрібно, щоб було налаштовано `workspace.dir`. -### Конфігурація bootstrap-extra-files +### конфігурація bootstrap-extra-files ```json { @@ -203,34 +203,34 @@ openclaw hooks enable } ``` -Шляхи вирішуються відносно робочого простору. Завантажуються лише розпізнані базові назви bootstrap-файлів (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `MEMORY.md`). +Шляхи розв’язуються відносно робочого простору. Завантажуються лише розпізнані базові імена bootstrap (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `MEMORY.md`). -### Деталі command-logger +### подробиці command-logger -Журналює кожну slash-команду в `~/.openclaw/logs/commands.log`. +Записує кожну slash-команду в `~/.openclaw/logs/commands.log`. -### Деталі compaction-notifier +### подробиці compaction-notifier -Надсилає короткі статусні повідомлення в поточну розмову, коли OpenClaw починає та завершує compacting транскрипту сесії. Це робить довгі ходи менш заплутаними на чат-поверхнях, бо користувач бачить, що асистент підсумовує контекст і продовжить після compaction. +Надсилає короткі статусні повідомлення в поточну розмову, коли OpenClaw починає й завершує Compaction транскрипту сесії. Це робить довгі кроки менш заплутаними в чат-інтерфейсах, оскільки користувач бачить, що асистент підсумовує контекст і продовжить після Compaction. -### Деталі boot-md +### подробиці boot-md -Запускає `BOOT.md` з активного робочого простору, коли gateway стартує. +Запускає `BOOT.md` з активного робочого простору, коли запускається Gateway. -## Plugin hooks +## Хуки Plugin -Plugins можуть реєструвати типізовані hooks через Plugin SDK для глибшої інтеграції: -перехоплення tool calls, змінення prompts, керування потоком повідомлень тощо. -Використовуйте plugin hooks, коли вам потрібні `before_tool_call`, `before_agent_reply`, -`before_install` або інші lifecycle hooks у процесі. +Plugins можуть реєструвати типізовані хуки через Plugin SDK для глибшої інтеграції: +перехоплення викликів інструментів, змінювання промптів, керування потоком повідомлень тощо. +Використовуйте хуки plugin, коли вам потрібні `before_tool_call`, `before_agent_reply`, +`before_install` або інші хуки життєвого циклу в межах процесу. -Повний довідник plugin hook див. у [Plugin hooks](/uk/plugins/hooks). +Повну довідку з хуків plugin див. у [Хуки Plugin](/uk/plugins/hooks). ## Конфігурація @@ -248,7 +248,7 @@ Plugins можуть реєструвати типізовані hooks чере } ``` -Змінні середовища для окремого hook: +Змінні середовища для окремих хуків: ```json { @@ -265,7 +265,7 @@ Plugins можуть реєструвати типізовані hooks чере } ``` -Додаткові директорії hooks: +Додаткові каталоги хуків: ```json { @@ -280,10 +280,10 @@ Plugins можуть реєструвати типізовані hooks чере ``` -Застарілий формат конфігурації масиву `hooks.internal.handlers` досі підтримується для зворотної сумісності, але нові hooks мають використовувати систему на основі виявлення. +Застарілий формат конфігурації масиву `hooks.internal.handlers` досі підтримується для зворотної сумісності, але нові хуки мають використовувати систему на основі виявлення. -## Довідник CLI +## Довідка CLI ```bash # List all hooks (add --eligible, --verbose, or --json) @@ -302,9 +302,9 @@ openclaw hooks disable ## Найкращі практики -- **Зберігайте обробники швидкими.** Хуки виконуються під час обробки команд. Запускайте важку роботу у фоновому режимі без очікування результату за допомогою `void processInBackground(event)`. +- **Тримайте обробники швидкими.** Хуки виконуються під час обробки команд. Запускайте важку роботу у фоновому режимі без очікування через `void processInBackground(event)`. - **Обробляйте помилки коректно.** Обгортайте ризиковані операції в try/catch; не кидайте винятки, щоб інші обробники могли виконатися. -- **Фільтруйте події якомога раніше.** Негайно повертайтеся, якщо тип/дія події не релевантні. +- **Фільтруйте події на ранньому етапі.** Негайно повертайтеся, якщо тип/дія події не є релевантними. - **Використовуйте конкретні ключі подій.** Надавайте перевагу `"events": ["command:new"]` замість `"events": ["command"]`, щоб зменшити накладні витрати. ## Усунення несправностей @@ -320,23 +320,23 @@ ls -la ~/.openclaw/hooks/my-hook/ openclaw hooks list ``` -### Хук не придатний +### Хук не відповідає умовам ```bash openclaw hooks info my-hook ``` -Перевірте відсутні двійкові файли (PATH), змінні середовища, значення конфігурації або сумісність з ОС. +Перевірте відсутні бінарні файли (PATH), змінні середовища, значення конфігурації або сумісність з ОС. ### Хук не виконується -1. Переконайтеся, що хук увімкнено: `openclaw hooks list` +1. Перевірте, що хук увімкнено: `openclaw hooks list` 2. Перезапустіть процес Gateway, щоб хуки перезавантажилися. -3. Перевірте логи Gateway: `./scripts/clawlog.sh | grep hook` +3. Перевірте журнали Gateway: `./scripts/clawlog.sh | grep hook` ## Пов’язане - [Довідник CLI: хуки](/uk/cli/hooks) -- [Webhook-и](/uk/automation/cron-jobs#webhooks) -- [Хуки Plugin](/uk/plugins/hooks) — внутрішньопроцесні хуки життєвого циклу Plugin +- [Webhook](/uk/automation/cron-jobs#webhooks) +- [Хуки Plugin](/uk/plugins/hooks) — хуки життєвого циклу Plugin у процесі - [Конфігурація](/uk/gateway/configuration-reference#hooks) diff --git a/docs/uk/channels/troubleshooting.md b/docs/uk/channels/troubleshooting.md index 08f89880c..2bba68307 100644 --- a/docs/uk/channels/troubleshooting.md +++ b/docs/uk/channels/troubleshooting.md @@ -1,23 +1,23 @@ --- read_when: - - Транспорт каналу показує стан «підключено», але відповіді не надсилаються - - Перш ніж переходити до докладної документації провайдера, потрібні перевірки, специфічні для каналу -summary: Швидке усунення неполадок на рівні каналу із сигнатурами збоїв і виправленнями для кожного каналу + - Транспорт каналу повідомляє про підключення, але відповіді не вдається надіслати + - Потрібні перевірки, специфічні для каналів, перед детальною документацією провайдерів +summary: Швидке усунення несправностей на рівні каналів із сигнатурами збоїв і виправленнями для кожного каналу title: Усунення несправностей каналів x-i18n: - generated_at: "2026-05-04T00:48:59Z" + generated_at: "2026-05-05T08:03:55Z" model: gpt-5.5 provider: openai - source_hash: a3a0737156ae83897c44d18505e0355a5d8e5700106b984496d94874c270deb2 + source_hash: 360184c41ce6929c696688af597c5104a8a28b54620c354f7ee400a2e5490519 source_path: channels/troubleshooting.md workflow: 16 --- Використовуйте цю сторінку, коли канал підключається, але поведінка неправильна. -## Ієрархія команд +## Послідовність команд -Спочатку виконайте ці команди по порядку: +Спочатку виконайте їх у такому порядку: ```bash openclaw status @@ -31,19 +31,20 @@ openclaw channels status --probe - `Runtime: running` - `Connectivity probe: ok` -- `Capability: read-only`, `write-capable` або `admin-capable` +- `Capability: read-only`, `write-capable`, або `admin-capable` - Перевірка каналу показує, що транспорт підключено, і, де підтримується, `works` або `audit ok` ## WhatsApp ### Ознаки збоїв WhatsApp -| Симптом | Найшвидша перевірка | Виправлення | -| ------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -| Підключено, але немає відповідей у DM | `openclaw pairing list whatsapp` | Схваліть відправника або змініть політику/allowlist для DM. | -| Групові повідомлення ігноруються | Перевірте `requireMention` + шаблони згадок у config | Згадайте бота або послабте політику згадок для цієї групи. | -| Вхід через QR завершується за тайм-аутом із 408 | Перевірте env `HTTPS_PROXY` / `HTTP_PROXY` для gateway | Налаштуйте доступний проксі; використовуйте `NO_PROXY` лише для обходів. | -| Випадкові цикли відключення/повторного входу | `openclaw channels status --probe` + журнали | Нещодавні повторні підключення позначаються навіть коли зараз підключено; стежте за журналами, перезапустіть gateway, потім повторно прив’яжіть, якщо нестабільність триває. | +| Симптом | Найшвидша перевірка | Виправлення | +| -------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | +| Підключено, але немає відповідей у DM | `openclaw pairing list whatsapp` | Схваліть відправника або змініть політику DM/список дозволених. | +| Повідомлення в групі ігноруються | Перевірте `requireMention` + шаблони згадок у config | Згадайте бота або послабте політику згадок для цієї групи. | +| Вхід через QR завершується тайм-аутом із 408 | Перевірте env Gateway `HTTPS_PROXY` / `HTTP_PROXY` | Налаштуйте доступний proxy; використовуйте `NO_PROXY` лише для обходів. | +| Випадкові цикли відключення/повторного входу | `openclaw channels status --probe` + журнали | Нещодавні перепідключення позначаються навіть за поточного підключення; стежте за журналами, перезапустіть Gateway, а потім повторно прив’яжіть, якщо нестабільність триває. | +| Відповіді надходять із затримкою в секунди/хвилини | `openclaw doctor --fix` | Doctor зупиняє перевірені застарілі локальні клієнти TUI, коли вони погіршують цикл подій Gateway. | Повне усунення несправностей: [Усунення несправностей WhatsApp](/uk/channels/whatsapp#troubleshooting) @@ -51,15 +52,15 @@ openclaw channels status --probe ### Ознаки збоїв Telegram -| Симптом | Найшвидша перевірка | Виправлення | -| ------------------------------------ | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | -| `/start`, але немає придатного потоку відповідей | `openclaw pairing list telegram` | Схваліть pairing або змініть політику DM. | -| Бот онлайн, але група мовчить | Перевірте вимогу згадки та режим приватності бота | Вимкніть режим приватності для видимості в групі або згадайте бота. | -| Помилки надсилання через мережеві помилки | Перегляньте журнали на збої викликів Telegram API | Виправте маршрутизацію DNS/IPv6/проксі до `api.telegram.org`. | -| Під час запуску повідомляється `getMe returned 401` | Перевірте налаштоване джерело токена | Скопіюйте повторно або згенеруйте заново токен BotFather і оновіть `botToken`, `tokenFile` або `TELEGRAM_BOT_TOKEN` для default-account. | -| Polling зависає або повільно перепідключається | `openclaw logs --follow` для діагностики polling | Оновіть; якщо перезапуски є хибнопозитивними, налаштуйте `pollingStallThresholdMs`. Постійні зависання все ще вказують на проксі/DNS/IPv6. | -| `setMyCommands` відхилено під час запуску | Перегляньте журнали на `BOT_COMMANDS_TOO_MUCH` | Зменште кількість Plugin/skill/користувацьких команд Telegram або вимкніть нативні меню. | -| Після оновлення allowlist блокує вас | `openclaw security audit` і config allowlists | Запустіть `openclaw doctor --fix` або замініть `@username` на числові ID відправників. | +| Симптом | Найшвидша перевірка | Виправлення | +| -------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | +| `/start`, але немає придатного потоку відповідей | `openclaw pairing list telegram` | Схваліть прив’язування або змініть політику DM. | +| Бот онлайн, але група мовчить | Перевірте вимогу згадки та режим приватності бота | Вимкніть режим приватності для видимості в групі або згадайте бота. | +| Помилки надсилання з мережевими помилками | Перегляньте журнали на збої викликів Telegram API | Виправте маршрутизацію DNS/IPv6/proxy до `api.telegram.org`. | +| Під час запуску повідомляється `getMe returned 401` | Перевірте налаштоване джерело token | Скопіюйте повторно або згенеруйте заново token BotFather і оновіть `botToken`, `tokenFile` або `TELEGRAM_BOT_TOKEN` облікового запису за замовчуванням. | +| Polling зависає або перепідключається повільно | `openclaw logs --follow` для діагностики polling | Оновіть; якщо перезапуски є хибними спрацюваннями, налаштуйте `pollingStallThresholdMs`. Постійні зависання все ще вказують на proxy/DNS/IPv6. | +| `setMyCommands` відхилено під час запуску | Перегляньте журнали на `BOT_COMMANDS_TOO_MUCH` | Зменште кількість команд Telegram із Plugin/skill/користувацьких команд або вимкніть нативні меню. | +| Після оновлення список дозволених блокує вас | `openclaw security audit` і списки дозволених у config | Запустіть `openclaw doctor --fix` або замініть `@username` на числові ID відправників. | Повне усунення несправностей: [Усунення несправностей Telegram](/uk/channels/telegram#troubleshooting) @@ -67,12 +68,12 @@ openclaw channels status --probe ### Ознаки збоїв Discord -| Симптом | Найшвидша перевірка | Виправлення | -| ----------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Бот онлайн, але немає відповідей у guild | `openclaw channels status --probe` | Дозвольте guild/channel і перевірте message content intent. | -| Групові повідомлення ігноруються | Перевірте журнали на відкидання через gating згадок | Згадайте бота або встановіть для guild/channel `requireMention: false`. | -| Є введення/використання токенів, але немає повідомлення Discord | Журнал сесії показує текст assistant з `didSendViaMessagingTool: false` | Модель відповіла приватно замість виклику message tool. Використайте модель із надійними tool-call або встановіть `messages.groupChat.visibleReplies: "automatic"` для автоматичної публікації. | -| Немає відповідей у DM | `openclaw pairing list discord` | Схваліть DM pairing або змініть політику DM. | +| Симптом | Найшвидша перевірка | Виправлення | +| -------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Бот онлайн, але немає відповідей у guild | `openclaw channels status --probe` | Дозвольте guild/channel і перевірте intent вмісту повідомлень. | +| Повідомлення в групі ігноруються | Перевірте журнали на відкидання через шлюз згадок | Згадайте бота або встановіть для guild/channel `requireMention: false`. | +| Є індикація typing/використання token, але немає повідомлення Discord | Журнал сесії показує текст помічника з `didSendViaMessagingTool: false` | Модель відповіла приватно замість виклику message tool. Використайте модель із надійними tool calls або встановіть `messages.groupChat.visibleReplies: "automatic"` для автоматичного допису. | +| Відповіді в DM відсутні | `openclaw pairing list discord` | Схваліть прив’язування DM або змініть політику DM. | Повне усунення несправностей: [Усунення несправностей Discord](/uk/channels/discord#troubleshooting) @@ -80,11 +81,11 @@ openclaw channels status --probe ### Ознаки збоїв Slack -| Симптом | Найшвидша перевірка | Виправлення | -| -------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Socket mode підключено, але немає відповідей | `openclaw channels status --probe` | Перевірте app token + bot token і потрібні scopes; стежте за `botTokenStatus` / `appTokenStatus = configured_unavailable` у налаштуваннях на основі SecretRef. | -| DM заблоковано | `openclaw pairing list slack` | Схваліть pairing або послабте політику DM. | -| Повідомлення каналу ігнорується | Перевірте `groupPolicy` і allowlist каналу | Дозвольте канал або змініть політику на `open`. | +| Симптом | Найшвидша перевірка | Виправлення | +| -------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Socket mode підключено, але відповідей немає | `openclaw channels status --probe` | Перевірте app token + bot token і потрібні scopes; стежте за `botTokenStatus` / `appTokenStatus = configured_unavailable` у налаштуваннях на основі SecretRef. | +| DM заблоковано | `openclaw pairing list slack` | Схваліть прив’язування або послабте політику DM. | +| Повідомлення в каналі ігнорується | Перевірте `groupPolicy` і список дозволених каналів | Дозвольте канал або перемкніть політику на `open`. | Повне усунення несправностей: [Усунення несправностей Slack](/uk/channels/slack#troubleshooting) @@ -92,11 +93,11 @@ openclaw channels status --probe ### Ознаки збоїв iMessage і BlueBubbles -| Симптом | Найшвидша перевірка | Виправлення | -| -------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------- | -| Немає вхідних подій | Перевірте доступність webhook/сервера та дозволи застосунку | Виправте URL webhook або стан сервера BlueBubbles. | +| Симптом | Найшвидша перевірка | Виправлення | +| -------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------- | +| Немає вхідних подій | Перевірте досяжність Webhook/сервера та дозволи застосунку | Виправте URL Webhook або стан сервера BlueBubbles. | | Можна надсилати, але немає отримання на macOS | Перевірте дозволи приватності macOS для автоматизації Messages | Повторно надайте дозволи TCC і перезапустіть процес каналу. | -| Відправника DM заблоковано | `openclaw pairing list imessage` або `openclaw pairing list bluebubbles` | Схваліть pairing або оновіть allowlist. | +| Відправника DM заблоковано | `openclaw pairing list imessage` або `openclaw pairing list bluebubbles` | Схваліть прив’язування або оновіть список дозволених. | Повне усунення несправностей: @@ -107,11 +108,11 @@ openclaw channels status --probe ### Ознаки збоїв Signal -| Симптом | Найшвидша перевірка | Виправлення | -| ------------------------------- | -------------------------------------- | --------------------------------------------------------- | -| Daemon доступний, але бот мовчить | `openclaw channels status --probe` | Перевірте URL/account daemon `signal-cli` і режим отримання. | -| DM заблоковано | `openclaw pairing list signal` | Схваліть відправника або змініть політику DM. | -| Відповіді в групі не запускаються | Перевірте allowlist групи та шаблони згадок | Додайте відправника/групу або послабте gating. | +| Симптом | Найшвидша перевірка | Виправлення | +| ------------------------------------ | ----------------------------------------- | ------------------------------------------------------------- | +| Daemon доступний, але бот мовчить | `openclaw channels status --probe` | Перевірте URL/account daemon `signal-cli` і режим отримання. | +| DM заблоковано | `openclaw pairing list signal` | Схваліть відправника або змініть політику DM. | +| Відповіді в групі не запускаються | Перевірте список дозволених груп і шаблони згадок | Додайте відправника/групу або послабте шлюз. | Повне усунення несправностей: [Усунення несправностей Signal](/uk/channels/signal#troubleshooting) @@ -119,12 +120,12 @@ openclaw channels status --probe ### Ознаки збоїв QQ Bot -| Симптом | Найшвидша перевірка | Виправлення | -| ------------------------------- | ------------------------------------------- | ------------------------------------------------------------------ | -| Бот відповідає "gone to Mars" | Перевірте `appId` і `clientSecret` у config | Налаштуйте облікові дані або перезапустіть gateway. | -| Немає вхідних повідомлень | `openclaw channels status --probe` | Перевірте облікові дані на QQ Open Platform. | -| Голос не транскрибується | Перевірте config постачальника STT | Налаштуйте `channels.qqbot.stt` або `tools.media.audio`. | -| Проактивні повідомлення не надходять | Перевірте вимоги взаємодії платформи QQ | QQ може блокувати ініційовані ботом повідомлення без нещодавньої взаємодії. | +| Симптом | Найшвидша перевірка | Виправлення | +| ---------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------- | +| Бот відповідає "gone to Mars" | Перевірте `appId` і `clientSecret` у config | Налаштуйте облікові дані або перезапустіть Gateway. | +| Немає вхідних повідомлень | `openclaw channels status --probe` | Перевірте облікові дані на QQ Open Platform. | +| Голос не транскрибується | Перевірте config постачальника STT | Налаштуйте `channels.qqbot.stt` або `tools.media.audio`. | +| Проактивні повідомлення не надходять | Перевірте вимоги взаємодії платформи QQ | QQ може блокувати ініційовані ботом повідомлення без нещодавньої взаємодії. | Повне усунення несправностей: [Усунення несправностей QQ Bot](/uk/channels/qqbot#troubleshooting) @@ -132,18 +133,18 @@ openclaw channels status --probe ### Ознаки збоїв Matrix -| Симптом | Найшвидша перевірка | Виправлення | -| ----------------------------------- | -------------------------------------- | ------------------------------------------------------------------------ | -| Увійшов, але ігнорує повідомлення кімнати | `openclaw channels status --probe` | Перевірте `groupPolicy`, allowlist кімнат і gating згадок. | -| DM не обробляються | `openclaw pairing list matrix` | Схваліть відправника або змініть політику DM. | -| Зашифровані кімнати не працюють | `openclaw matrix verify status` | Повторно верифікуйте пристрій, потім перевірте `openclaw matrix verify backup status`. | -| Відновлення backup очікує/зламане | `openclaw matrix verify backup status` | Запустіть `openclaw matrix verify backup restore` або повторіть із recovery key. | -| Cross-signing/bootstrap виглядає неправильно | `openclaw matrix verify bootstrap` | Відновіть secret storage, cross-signing і стан backup за один прохід. | +| Симптом | Найшвидша перевірка | Виправлення | +| -------------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------- | +| Увійшов у систему, але ігнорує повідомлення кімнати | `openclaw channels status --probe` | Перевірте `groupPolicy`, список дозволених кімнат і шлюз згадок. | +| DM не обробляються | `openclaw pairing list matrix` | Схваліть відправника або змініть політику DM. | +| Зашифровані кімнати не працюють | `openclaw matrix verify status` | Повторно перевірте пристрій, потім перевірте `openclaw matrix verify backup status`. | +| Відновлення backup очікує або пошкоджене | `openclaw matrix verify backup status` | Запустіть `openclaw matrix verify backup restore` або повторіть із ключем відновлення. | +| Cross-signing/bootstrap виглядає неправильно | `openclaw matrix verify bootstrap` | Виправте secret storage, cross-signing і стан backup за один прохід. | -Повне налаштування і config: [Matrix](/uk/channels/matrix) +Повне налаштування та config: [Matrix](/uk/channels/matrix) ## Пов’язане -- [Pairing](/uk/channels/pairing) +- [Прив’язування](/uk/channels/pairing) - [Маршрутизація каналів](/uk/channels/channel-routing) - [Усунення несправностей Gateway](/uk/gateway/troubleshooting) diff --git a/docs/uk/cli/doctor.md b/docs/uk/cli/doctor.md index 366e57c8b..74418f5cb 100644 --- a/docs/uk/cli/doctor.md +++ b/docs/uk/cli/doctor.md @@ -1,14 +1,14 @@ --- read_when: - - У вас виникли проблеми з підключенням або автентифікацією, і ви хочете отримати покрокові способи їх усунення - - Ви виконали оновлення й хочете базову перевірку + - У вас виникли проблеми з підключенням або автентифікацією, і ви хочете отримати покрокові інструкції з їх усунення + - Ви оновили й хочете виконати контрольну перевірку summary: Довідник CLI для `openclaw doctor` (перевірки стану + керовані виправлення) title: Діагностика x-i18n: - generated_at: "2026-05-05T01:21:15Z" + generated_at: "2026-05-05T08:03:55Z" model: gpt-5.5 provider: openai - source_hash: 079d7674ae2a259a0430e30e7577ac532135ad5461c57c4b3a6514a007bc9ea5 + source_hash: d6101008d1cb7e08f9902a8a29785710f325966524b003b87b5c628fe906ab78 source_path: cli/doctor.md workflow: 16 --- @@ -34,45 +34,46 @@ openclaw doctor --generate-gateway-token ## Параметри -- `--no-workspace-suggestions`: вимкнути пропозиції пам’яті/пошуку робочої області -- `--yes`: приймати стандартні значення без запитів -- `--repair`: застосувати рекомендовані виправлення, не пов’язані зі службами, без запитів; встановлення та перезапис служб Gateway все одно потребують інтерактивного підтвердження або явних команд Gateway +- `--no-workspace-suggestions`: вимкнути пропозиції пам’яті/пошуку робочого простору +- `--yes`: прийняти типові значення без запиту +- `--repair`: застосувати рекомендовані виправлення, не пов’язані із сервісом, без запиту; встановлення та перезапис сервісу Gateway все одно потребують інтерактивного підтвердження або явних команд Gateway - `--fix`: псевдонім для `--repair` -- `--force`: застосувати агресивні виправлення, зокрема перезапис користувацької конфігурації служби за потреби -- `--non-interactive`: запускати без запитів; лише безпечні міграції та виправлення, не пов’язані зі службами +- `--force`: застосувати агресивні виправлення, зокрема перезапис спеціальної конфігурації сервісу за потреби +- `--non-interactive`: запускати без запитів; лише безпечні міграції та виправлення, не пов’язані із сервісом - `--generate-gateway-token`: згенерувати й налаштувати токен Gateway -- `--deep`: сканувати системні служби на наявність додаткових встановлень Gateway +- `--deep`: сканувати системні сервіси на наявність додаткових встановлень Gateway і повідомляти про нещодавні передавання перезапуску супервізора Gateway Примітки: -- Інтерактивні запити (наприклад, виправлення keychain/OAuth) запускаються лише тоді, коли stdin є TTY і `--non-interactive` **не** встановлено. Запуски без термінала (Cron, Telegram, без термінала) пропускатимуть запити. -- Продуктивність: неінтерактивні запуски `doctor` пропускають завчасне завантаження Plugin, щоб перевірки стану без термінала залишалися швидкими. Інтерактивні сеанси все одно повністю завантажують plugins, коли перевірці потрібен їхній внесок. -- `--fix` (псевдонім для `--repair`) записує резервну копію в `~/.openclaw/openclaw.json.bak` і вилучає невідомі ключі конфігурації, перелічуючи кожне вилучення. -- `doctor --fix --non-interactive` повідомляє про відсутні або застарілі визначення служби Gateway, але не встановлює й не перезаписує їх поза режимом виправлення оновлення. Запустіть `openclaw gateway install` для відсутньої служби або `openclaw gateway install --force`, коли ви свідомо хочете замінити launcher. -- Перевірки цілісності стану тепер виявляють осиротілі файли транскриптів у каталозі сеансів. Їх архівування як `.deleted.` потребує інтерактивного підтвердження; `--fix`, `--yes` і запуски без термінала залишають їх на місці. -- Doctor також сканує `~/.openclaw/cron/jobs.json` (або `cron.store`) на застарілі форми завдань Cron і може перезаписати їх на місці до того, як планувальнику доведеться автоматично нормалізувати їх під час виконання. -- На Linux doctor попереджає, коли crontab користувача все ще запускає застарілий `~/.openclaw/bin/ensure-whatsapp.sh`; цей скрипт більше не підтримується й може хибно реєструвати збої Gateway WhatsApp, коли Cron не має середовища user-bus systemd. -- Doctor очищає застарілий проміжний стан залежностей Plugin, створений старішими версіями OpenClaw. Він також виправляє відсутні завантажувані plugins, на які посилається конфігурація, як-от `plugins.entries`, налаштовані канали, налаштовані параметри провайдера/пошуку або налаштовані середовища виконання агентів. Під час оновлень пакетів doctor пропускає виправлення Plugin через менеджер пакетів, доки заміну пакета не буде завершено; після цього повторно запустіть `openclaw doctor --fix`, якщо налаштований plugin усе ще потребує відновлення. Якщо завантаження не вдається, doctor повідомляє про помилку встановлення й зберігає налаштований запис plugin для наступної спроби виправлення. -- Doctor виправляє застарілу конфігурацію Plugin, вилучаючи відсутні ідентифікатори plugin з `plugins.allow`/`plugins.entries`, а також відповідну нечинну конфігурацію каналу, цілі Heartbeat і перевизначення моделей каналу, коли виявлення plugin працює справно. -- Doctor ізолює недійсну конфігурацію Plugin, вимикаючи відповідний запис `plugins.entries.` і вилучаючи його недійсний payload `config`. Запуск Gateway уже пропускає лише цей проблемний plugin, тож інші plugins і канали можуть продовжувати працювати. -- Встановіть `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли інший supervisor керує життєвим циклом Gateway. Doctor усе одно повідомляє про стан Gateway/служби й застосовує виправлення, не пов’язані зі службами, але пропускає встановлення/запуск/перезапуск/bootstrap служби та очищення застарілих служб. -- На Linux doctor ігнорує неактивні додаткові systemd units, схожі на Gateway, і не перезаписує метадані команди/entrypoint для запущеної служби Gateway systemd під час виправлення. Спочатку зупиніть службу або використайте `openclaw gateway install --force`, коли ви свідомо хочете замінити активний launcher. -- Doctor автоматично мігрує застарілу плоску конфігурацію Talk (`talk.voiceId`, `talk.modelId` та подібні) у `talk.provider` + `talk.providers.`. +- Інтерактивні запити (наприклад, виправлення keychain/OAuth) виконуються лише тоді, коли stdin є TTY і `--non-interactive` **не** встановлено. Запуски без інтерфейсу (cron, Telegram, без термінала) пропускатимуть запити. +- Продуктивність: неінтерактивні запуски `doctor` пропускають раннє завантаження Plugin, щоб перевірки стану без інтерфейсу залишалися швидкими. Інтерактивні сеанси все одно повністю завантажують plugins, коли перевірці потрібен їхній внесок. +- `--fix` (псевдонім для `--repair`) записує резервну копію в `~/.openclaw/openclaw.json.bak` і відкидає невідомі ключі конфігурації, перелічуючи кожне видалення. +- `doctor --fix --non-interactive` повідомляє про відсутні або застарілі визначення сервісу Gateway, але не встановлює й не перезаписує їх поза режимом виправлення оновлення. Запустіть `openclaw gateway install` для відсутнього сервісу або `openclaw gateway install --force`, коли ви свідомо хочете замінити launcher. +- Перевірки цілісності стану тепер виявляють осиротілі файли transcript у каталозі сеансів. Архівування їх як `.deleted.` потребує інтерактивного підтвердження; `--fix`, `--yes` і запуски без інтерфейсу залишають їх на місці. +- Doctor також сканує `~/.openclaw/cron/jobs.json` (або `cron.store`) на застарілі форми завдань cron і може перезаписати їх на місці до того, як планувальнику доведеться автоматично нормалізувати їх під час виконання. +- У Linux doctor попереджає, коли crontab користувача все ще запускає застарілий `~/.openclaw/bin/ensure-whatsapp.sh`; цей скрипт більше не підтримується й може журналювати хибні збої Gateway WhatsApp, коли cron не має середовища systemd user-bus. +- Коли WhatsApp увімкнено, doctor перевіряє деградований цикл подій Gateway із локальними клієнтами `openclaw-tui`, які все ще працюють. `doctor --fix` зупиняє лише перевірені локальні клієнти TUI, щоб відповіді WhatsApp не ставали в чергу за застарілими циклами оновлення TUI. +- Doctor очищає застарілий проміжний стан залежностей Plugin, створений старішими версіями OpenClaw. Він також відновлює відсутні завантажувані plugins, на які посилається конфігурація, як-от `plugins.entries`, налаштовані канали, налаштовані параметри провайдера/пошуку або налаштовані runtime агентів. Під час оновлень пакетів doctor пропускає виправлення Plugin через менеджер пакетів, доки заміна пакета не завершиться; після цього повторно запустіть `openclaw doctor --fix`, якщо налаштований Plugin усе ще потребує відновлення. Якщо завантаження не вдається, doctor повідомляє про помилку встановлення й зберігає налаштований запис Plugin для наступної спроби виправлення. +- Doctor виправляє застарілу конфігурацію Plugin, видаляючи відсутні ідентифікатори Plugin з `plugins.allow`/`plugins.entries`, а також відповідну висячу конфігурацію каналу, цілі Heartbeat і перевизначення моделей каналів, коли виявлення Plugin працює справно. +- Doctor поміщає недійсну конфігурацію Plugin у карантин, вимикаючи відповідний запис `plugins.entries.` і видаляючи його недійсне навантаження `config`. Запуск Gateway уже пропускає лише цей несправний Plugin, тож інші plugins і канали можуть продовжувати працювати. +- Установіть `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли інший супервізор керує життєвим циклом Gateway. Doctor усе ще повідомляє про стан Gateway/сервісу й застосовує виправлення, не пов’язані із сервісом, але пропускає встановлення/запуск/перезапуск/bootstrap сервісу та очищення застарілих сервісів. +- У Linux doctor ігнорує неактивні додаткові systemd units, схожі на Gateway, і не перезаписує метадані команди/entrypoint для запущеного сервісу Gateway systemd під час виправлення. Спочатку зупиніть сервіс або використайте `openclaw gateway install --force`, коли свідомо хочете замінити активний launcher. +- Doctor автоматично мігрує застарілу плоску конфігурацію Talk (`talk.voiceId`, `talk.modelId` та пов’язані ключі) у `talk.provider` + `talk.providers.`. - Повторні запуски `doctor --fix` більше не повідомляють і не застосовують нормалізацію Talk, коли єдина різниця полягає в порядку ключів об’єкта. -- Doctor містить перевірку готовності пошуку в пам’яті й може рекомендувати `openclaw configure --section model`, коли відсутні облікові дані для embeddings. -- Doctor попереджає, коли не налаштовано власника команд. Власник команд — це обліковий запис людини-оператора, якому дозволено запускати команди лише для власника й підтверджувати небезпечні дії. DM pairing лише дозволяє комусь спілкуватися з ботом; якщо ви схвалили відправника до появи bootstrap першого власника, явно встановіть `commands.ownerAllowFrom`. -- Doctor попереджає, коли налаштовано агентів у режимі Codex і в Codex home оператора існують особисті ресурси Codex CLI. Локальні запуски app-server Codex використовують ізольовані home для кожного агента, тому використовуйте `openclaw migrate codex --dry-run`, щоб інвентаризувати ресурси, які слід свідомо просунути. -- Doctor попереджає, коли Skills, дозволені для стандартного агента, недоступні в поточному середовищі виконання, бо відсутні bins, env vars, конфігурація або вимоги ОС. `doctor --fix` може вимкнути ці недоступні Skills за допомогою `skills.entries..enabled=false`; натомість встановіть/налаштуйте відсутню вимогу, якщо хочете залишити skill активним. -- Якщо режим sandbox увімкнено, але Docker недоступний, doctor повідомляє високосигнальне попередження з виправленням (`install Docker` або `openclaw config set agents.defaults.sandbox.mode off`). -- Якщо наявні застарілі файли реєстру sandbox (`~/.openclaw/sandbox/containers.json` або `~/.openclaw/sandbox/browsers.json`), doctor повідомляє про них; `openclaw doctor --fix` мігрує дійсні записи в sharded registry directories і ізолює недійсні застарілі файли. -- Якщо `gateway.auth.token`/`gateway.auth.password` керуються SecretRef і недоступні в поточному шляху команди, doctor повідомляє попередження лише для читання й не записує резервні облікові дані у відкритому тексті. -- Якщо перевірка SecretRef каналу зазнає невдачі в шляху виправлення, doctor продовжує роботу й повідомляє попередження замість раннього завершення. -- Після міграцій каталогу стану doctor попереджає, коли ввімкнені стандартні облікові записи Telegram або Discord залежать від env fallback, а `TELEGRAM_BOT_TOKEN` або `DISCORD_BOT_TOKEN` недоступні для процесу doctor. -- Автоматичне визначення імен користувачів Telegram `allowFrom` (`doctor --fix`) потребує доступного для визначення токена Telegram у поточному шляху команди. Якщо перевірка токена недоступна, doctor повідомляє попередження й пропускає автоматичне визначення для цього проходу. +- Doctor містить перевірку готовності пошуку в пам’яті й може рекомендувати `openclaw configure --section model`, коли облікові дані embedding відсутні. +- Doctor попереджає, коли не налаштовано власника команд. Власник команд — це обліковий запис людини-оператора, якому дозволено запускати команди лише для власника й схвалювати небезпечні дії. Сполучення через DM лише дозволяє комусь говорити з ботом; якщо ви схвалили відправника до появи bootstrap першого власника, явно встановіть `commands.ownerAllowFrom`. +- Doctor попереджає, коли налаштовано агентів у режимі Codex і персональні ресурси Codex CLI існують у домашньому каталозі Codex оператора. Локальні запуски app-server Codex використовують ізольовані домашні каталоги для кожного агента, тому використовуйте `openclaw migrate codex --dry-run`, щоб інвентаризувати ресурси, які слід просувати навмисно. +- Doctor попереджає, коли Skills, дозволені для типового агента, недоступні в поточному runtime-середовищі, бо відсутні bins, env vars, конфігурація або вимоги ОС. `doctor --fix` може вимкнути ці недоступні skills за допомогою `skills.entries..enabled=false`; натомість встановіть/налаштуйте відсутню вимогу, якщо хочете зберегти skill активним. +- Якщо режим sandbox увімкнено, але Docker недоступний, doctor повідомляє високосигнальне попередження з дією для виправлення (`install Docker` або `openclaw config set agents.defaults.sandbox.mode off`). +- Якщо наявні застарілі файли реєстру sandbox (`~/.openclaw/sandbox/containers.json` або `~/.openclaw/sandbox/browsers.json`), doctor повідомляє про них; `openclaw doctor --fix` мігрує дійсні записи в шардовані каталоги реєстру й поміщає недійсні застарілі файли в карантин. +- Якщо `gateway.auth.token`/`gateway.auth.password` керуються SecretRef і недоступні в поточному шляху команди, doctor повідомляє попередження лише для читання й не записує plaintext fallback credentials. +- Якщо перевірка SecretRef каналу не вдається у шляху виправлення, doctor продовжує роботу й повідомляє попередження замість дострокового виходу. +- Після міграцій каталогу стану doctor попереджає, коли ввімкнені типові облікові записи Telegram або Discord залежать від env fallback, а `TELEGRAM_BOT_TOKEN` або `DISCORD_BOT_TOKEN` недоступні процесу doctor. +- Автоматичне розв’язання імен користувачів Telegram `allowFrom` (`doctor --fix`) потребує доступного для розв’язання токена Telegram у поточному шляху команди. Якщо перевірка токена недоступна, doctor повідомляє попередження й пропускає автоматичне розв’язання для цього проходу. ## macOS: перевизначення env `launchctl` -Якщо ви раніше запускали `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (або `...PASSWORD`), це значення перевизначає ваш файл конфігурації й може спричиняти постійні помилки “unauthorized”. +Якщо ви раніше запускали `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (або `...PASSWORD`), це значення перевизначає ваш файл конфігурації та може спричиняти постійні помилки “unauthorized”. ```bash launchctl getenv OPENCLAW_GATEWAY_TOKEN @@ -85,4 +86,4 @@ launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD ## Пов’язано - [Довідник CLI](/uk/cli) -- [Doctor Gateway](/uk/gateway/doctor) +- [Gateway doctor](/uk/gateway/doctor) diff --git a/docs/uk/cli/gateway.md b/docs/uk/cli/gateway.md index 697b0a71a..9a3aa7a1f 100644 --- a/docs/uk/cli/gateway.md +++ b/docs/uk/cli/gateway.md @@ -1,35 +1,35 @@ --- read_when: - - Запуск Gateway із CLI (для розробки або серверів) - - Налагодження автентифікації Gateway, режимів прив’язки та підключення - - Виявлення Gateway через Bonjour (локальний + широкозонний DNS-SD) + - Запуск Gateway з CLI (розробка або сервери) + - Налагодження автентифікації Gateway, режимів прив’язування та підключення + - Виявлення Gateway через Bonjour (локальний + wide-area DNS-SD) sidebarTitle: Gateway -summary: OpenClaw Gateway CLI (`openclaw gateway`) — запускайте, опитуйте та виявляйте екземпляри Gateway +summary: OpenClaw Gateway CLI (`openclaw gateway`) — запускайте, запитуйте й виявляйте Gateway title: Gateway x-i18n: - generated_at: "2026-05-05T00:49:35Z" + generated_at: "2026-05-05T08:04:10Z" model: gpt-5.5 provider: openai - source_hash: 521558189b150b2faa22f95ec32419ac9e02c5f47c72b9095f40d1432840c038 + source_hash: 89f798724971151cdd297fcdbbc1fe79dedc19f57521f2ad2c1fff0f9acf9b24 source_path: cli/gateway.md workflow: 16 --- -Gateway — це WebSocket-сервер OpenClaw (канали, вузли, сесії, хуки). Підкоманди на цій сторінці знаходяться в `openclaw gateway …`. +Gateway — це WebSocket-сервер OpenClaw (канали, вузли, сесії, хуки). Підкоманди на цій сторінці розташовані під `openclaw gateway …`. - Налаштування локального mDNS + широкозонного DNS-SD. + Налаштування локального mDNS + глобального DNS-SD. - Як OpenClaw оголошує та знаходить Gateway. + Як OpenClaw оголошує про шлюзи й знаходить їх. Ключі конфігурації gateway верхнього рівня. -## Запустіть Gateway +## Запуск Gateway Запустіть локальний процес Gateway: @@ -44,13 +44,13 @@ openclaw gateway run ``` - - - За замовчуванням Gateway відмовляється запускатися, якщо `gateway.mode=local` не задано в `~/.openclaw/openclaw.json`. Використовуйте `--allow-unconfigured` для разових/розробницьких запусків. - - Очікується, що `openclaw onboard --mode local` і `openclaw setup` запишуть `gateway.mode=local`. Якщо файл існує, але `gateway.mode` відсутній, розглядайте це як пошкоджену або перезаписану конфігурацію та відновіть її, замість неявно припускати локальний режим. - - Якщо файл існує, а `gateway.mode` відсутній, Gateway вважає це підозрілим пошкодженням конфігурації та відмовляється "вгадувати local" за вас. - - Прив’язування поза межами loopback без автентифікації заблоковано (захисне обмеження). - - `SIGUSR1` запускає перезапуск усередині процесу, коли це авторизовано (`commands.restart` увімкнено за замовчуванням; задайте `commands.restart: false`, щоб заблокувати ручний перезапуск, водночас застосування/оновлення через інструмент і конфігурацію gateway лишаються дозволеними). - - Обробники `SIGINT`/`SIGTERM` зупиняють процес gateway, але не відновлюють жодний спеціальний стан термінала. Якщо ви обгортаєте CLI за допомогою TUI або введення в raw-mode, відновіть термінал перед виходом. + + - За замовчуванням Gateway відмовляється запускатися, якщо `gateway.mode=local` не задано в `~/.openclaw/openclaw.json`. Використовуйте `--allow-unconfigured` для разових/dev-запусків. + - Очікується, що `openclaw onboard --mode local` і `openclaw setup` записують `gateway.mode=local`. Якщо файл існує, але `gateway.mode` відсутній, вважайте це пошкодженою або перезаписаною конфігурацією й виправте її, замість неявного припущення локального режиму. + - Якщо файл існує, але `gateway.mode` відсутній, Gateway розцінює це як підозріле пошкодження конфігурації та відмовляється "вгадувати local" за вас. + - Прив’язка поза loopback без автентифікації блокується (захисне обмеження). + - `SIGUSR1` запускає перезапуск у межах процесу, коли це дозволено (`commands.restart` увімкнено за замовчуванням; задайте `commands.restart: false`, щоб заблокувати ручний перезапуск, водночас застосування/оновлення через інструмент/config gateway залишаються дозволеними). + - Обробники `SIGINT`/`SIGTERM` зупиняють процес gateway, але не відновлюють жоден кастомний стан термінала. Якщо ви обгортаєте CLI за допомогою TUI або введення в raw-mode, відновіть термінал перед виходом. @@ -58,10 +58,10 @@ openclaw gateway run ### Параметри - Порт WebSocket (значення за замовчуванням береться з конфігурації/env; зазвичай `18789`). + Порт WebSocket (значення за замовчуванням береться з config/env; зазвичай `18789`). - Режим прив’язування слухача. + Режим прив’язки слухача. Перевизначення режиму автентифікації. @@ -73,46 +73,46 @@ openclaw gateway run Перевизначення пароля. - Зчитати пароль gateway з файла. + Прочитати пароль gateway з файлу. - Надати доступ до Gateway через Tailscale. + Відкрити доступ до Gateway через Tailscale. Скинути конфігурацію Tailscale serve/funnel під час завершення. - Дозволити запуск gateway без `gateway.mode=local` у конфігурації. Обходить захист запуску лише для разового/розробницького bootstrap; не записує й не відновлює файл конфігурації. + Дозволити запуск gateway без `gateway.mode=local` у конфігурації. Обходить захист запуску лише для разового/dev bootstrap; не записує й не виправляє файл конфігурації. - Створити dev-конфігурацію + робочий простір, якщо їх немає (пропускає BOOTSTRAP.md). + Створити dev config + робочий простір, якщо їх немає (пропускає BOOTSTRAP.md). - Скинути dev-конфігурацію + облікові дані + сесії + робочий простір (потребує `--dev`). + Скинути dev config + облікові дані + сесії + робочий простір (потребує `--dev`). Завершити будь-який наявний слухач на вибраному порту перед запуском. - Докладні логи. + Докладні журнали. - Показувати в консолі лише логи backend CLI (і ввімкнути stdout/stderr). + Показувати в консолі лише журнали backend CLI (і ввімкнути stdout/stderr). - Стиль логів Websocket. + Стиль журналу WebSocket. Псевдонім для `--ws-log compact`. - Логувати сирі події потоку моделі в jsonl. + Записувати сирі події потоку моделі в jsonl. - Шлях jsonl для сирого потоку. + Шлях до jsonl сирого потоку. -## Перезапустіть Gateway +## Перезапуск Gateway ```bash openclaw gateway restart @@ -120,19 +120,19 @@ openclaw gateway restart --safe openclaw gateway restart --force ``` -`openclaw gateway restart --safe` просить запущений Gateway попередньо перевірити активну роботу OpenClaw перед перезапуском. Якщо активні операції в черзі, доставлення відповідей, вбудовані запуски або запуски завдань, Gateway повідомляє про блокувальники, об’єднує дублікати безпечних запитів на перезапуск і перезапускається після завершення активної роботи. Звичайний `restart` зберігає наявну поведінку service-manager для сумісності. Використовуйте `--force` лише тоді, коли явно потрібен шлях негайного перевизначення. +`openclaw gateway restart --safe` просить запущений Gateway виконати попередню перевірку активної роботи OpenClaw перед перезапуском. Якщо активні операції в черзі, доставлення відповідей, вбудовані запуски або запуски завдань, Gateway повідомляє про блокувальники, об’єднує дубльовані запити безпечного перезапуску й перезапускається після завершення активної роботи. Звичайний `restart` зберігає наявну поведінку менеджера сервісів для сумісності. Використовуйте `--force` лише тоді, коли явно хочете негайний шлях примусового перевизначення. -Вбудований `--password` може бути видимим у локальних списках процесів. Надавайте перевагу `--password-file`, env або `gateway.auth.password`, підкріпленому SecretRef. +Вбудований `--password` може бути видимим у локальних списках процесів. Надавайте перевагу `--password-file`, env або `gateway.auth.password` на основі SecretRef. ### Профілювання запуску -- Задайте `OPENCLAW_GATEWAY_STARTUP_TRACE=1`, щоб логувати таймінги фаз під час запуску Gateway, включно із затримкою `eventLoopMax` для кожної фази та таймінгами lookup-table плагінів для installed-index, manifest registry, startup planning і owner-map. -- Задайте `OPENCLAW_DIAGNOSTICS=timeline` з `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=`, щоб записати best-effort JSONL-хронологію діагностики запуску для зовнішніх QA harnesses. Також можна ввімкнути прапорець через `diagnostics.flags: ["timeline"]` у конфігурації; шлях усе одно задається через env. Додайте `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1`, щоб включити зразки event-loop. -- Запустіть `pnpm test:startup:gateway -- --runs 5 --warmup 1`, щоб виконати benchmark запуску Gateway. Benchmark записує перший вивід процесу, `/healthz`, `/readyz`, таймінги startup trace, затримку event-loop і деталі таймінгів lookup-table плагінів. +- Задайте `OPENCLAW_GATEWAY_STARTUP_TRACE=1`, щоб записувати в журнал таймінги фаз під час запуску Gateway, включно із затримкою `eventLoopMax` для кожної фази та таймінгами таблиць пошуку plugin для installed-index, реєстру manifest, планування запуску й роботи owner-map. +- Задайте `OPENCLAW_DIAGNOSTICS=timeline` із `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=`, щоб записати best-effort JSONL timeline діагностики запуску для зовнішніх QA harnesses. Також можна ввімкнути прапорець через `diagnostics.flags: ["timeline"]` у конфігурації; шлях все одно надається через env. Додайте `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1`, щоб включити вибірки event-loop. +- Запустіть `pnpm test:startup:gateway -- --runs 5 --warmup 1`, щоб виміряти швидкодію запуску Gateway. Бенчмарк записує перший вивід процесу, `/healthz`, `/readyz`, таймінги трасування запуску, затримку event-loop і подробиці таймінгів таблиць пошуку plugin. -## Опитайте запущений Gateway +## Запит до запущеного Gateway Усі команди запитів використовують WebSocket RPC. @@ -140,21 +140,21 @@ openclaw gateway restart --force - За замовчуванням: зручно для читання людиною (кольорове в TTY). - `--json`: машинозчитуваний JSON (без стилізації/spinner). - - `--no-color` (або `NO_COLOR=1`): вимкнути ANSI, зберігаючи людський макет. + - `--no-color` (або `NO_COLOR=1`): вимкнути ANSI, зберігаючи людське компонування. - `--url `: WebSocket URL Gateway. - `--token `: токен Gateway. - `--password `: пароль Gateway. - - `--timeout `: timeout/budget (залежить від команди). - - `--expect-final`: чекати на відповідь "final" (виклики агента). + - `--timeout `: тайм-аут/бюджет (залежить від команди). + - `--expect-final`: чекати на "final" відповідь (виклики агента). -Коли ви задаєте `--url`, CLI не повертається до облікових даних із конфігурації чи середовища. Передайте `--token` або `--password` явно. Відсутність явних облікових даних є помилкою. +Коли ви задаєте `--url`, CLI не повертається до облікових даних із конфігурації або середовища. Передайте `--token` або `--password` явно. Відсутність явних облікових даних є помилкою. ### `gateway health` @@ -163,11 +163,11 @@ openclaw gateway restart --force openclaw gateway health --url ws://127.0.0.1:18789 ``` -HTTP endpoint `/healthz` є liveness probe: він повертає відповідь, щойно сервер може відповідати через HTTP. HTTP endpoint `/readyz` суворіший і лишається червоним, доки sidecar-и плагінів запуску, канали або налаштовані хуки ще стабілізуються. Локальні або автентифіковані докладні відповіді readiness містять діагностичний блок `eventLoop` із затримкою event-loop, використанням event-loop, співвідношенням ядер CPU та прапорцем `degraded`. +HTTP endpoint `/healthz` — це liveness probe: він повертає відповідь, щойно сервер може відповідати через HTTP. HTTP endpoint `/readyz` суворіший і залишається червоним, поки startup plugin sidecars, канали або налаштовані хуки ще стабілізуються. Локальні або автентифіковані докладні відповіді готовності містять діагностичний блок `eventLoop` із затримкою event-loop, використанням event-loop, співвідношенням CPU core та прапорцем `degraded`. ### `gateway usage-cost` -Отримайте підсумки usage-cost із логів сесій. +Отримати зведення вартості використання з журналів сесій. ```bash openclaw gateway usage-cost @@ -181,7 +181,7 @@ openclaw gateway usage-cost --json ### `gateway stability` -Отримайте нещодавній diagnostic stability recorder із запущеного Gateway. +Отримати останній diagnostic stability recorder із запущеного Gateway. ```bash openclaw gateway stability @@ -192,7 +192,7 @@ openclaw gateway stability --json ``` - Максимальна кількість нещодавніх подій для включення (макс. `1000`). + Максимальна кількість останніх подій для включення (макс. `1000`). Фільтрувати за типом діагностичної події, наприклад `payload.large` або `diagnostic.memory.pressure`. @@ -201,10 +201,10 @@ openclaw gateway stability --json Включати лише події після номера діагностичної послідовності. - Читати збережений stability bundle замість виклику запущеного Gateway. Використовуйте `--bundle latest` (або просто `--bundle`) для найновішого bundle у каталозі стану або передайте шлях до JSON bundle напряму. + Прочитати збережений stability bundle замість виклику запущеного Gateway. Використовуйте `--bundle latest` (або просто `--bundle`) для найновішого bundle у каталозі стану або передайте шлях до JSON bundle напряму. - Записати придатний для поширення zip із діагностикою підтримки замість друку деталей стабільності. + Записати придатний для поширення zip із діагностикою підтримки замість друку подробиць стабільності. Шлях виводу для `--export`. @@ -212,15 +212,15 @@ openclaw gateway stability --json - - Записи зберігають операційні метадані: назви подій, лічильники, розміри в байтах, показники пам’яті, стан черги/сесії, назви каналів/плагінів і редаговані підсумки сесій. Вони не зберігають текст чату, тіла webhook, виводи інструментів, сирі тіла запитів або відповідей, токени, cookies, секретні значення, hostnames або сирі ідентифікатори сесій. Задайте `diagnostics.enabled: false`, щоб повністю вимкнути recorder. - - Під час фатальних завершень Gateway, timeout під час shutdown і збоїв startup restart OpenClaw записує той самий діагностичний snapshot у `~/.openclaw/logs/stability/openclaw-stability-*.json`, коли recorder має події. Перегляньте найновіший bundle за допомогою `openclaw gateway stability --bundle latest`; `--limit`, `--type` і `--since-seq` також застосовуються до виводу bundle. + - Записи зберігають операційні метадані: назви подій, лічильники, розміри в байтах, показники пам’яті, стан черги/сесії, назви каналів/plugin і заредаговані зведення сесій. Вони не зберігають текст чату, тіла webhook, виводи інструментів, сирі тіла запитів або відповідей, токени, cookie, секретні значення, імена хостів або сирі id сесій. Задайте `diagnostics.enabled: false`, щоб повністю вимкнути recorder. + - Під час фатальних завершень Gateway, тайм-аутів завершення й помилок запуску після перезапуску OpenClaw записує той самий діагностичний snapshot у `~/.openclaw/logs/stability/openclaw-stability-*.json`, коли recorder має події. Перегляньте найновіший bundle за допомогою `openclaw gateway stability --bundle latest`; `--limit`, `--type` і `--since-seq` також застосовуються до виводу bundle. ### `gateway diagnostics export` -Запишіть локальний zip із діагностикою, призначений для додавання до bug reports. Модель конфіденційності та вміст bundle див. у [Експорті діагностики](/uk/gateway/diagnostics). +Записати локальний zip із діагностикою, призначений для додавання до звітів про помилки. Модель конфіденційності та вміст bundle описано в [Експорт діагностики](/uk/gateway/diagnostics). ```bash openclaw gateway diagnostics export @@ -229,25 +229,25 @@ openclaw gateway diagnostics export --json ``` - Шлях zip-виводу. За замовчуванням це експорт підтримки в каталозі стану. + Шлях до zip виводу. За замовчуванням — support export у каталозі стану. - Максимальна кількість очищених рядків логів для включення. + Максимальна кількість очищених рядків журналу для включення. - Максимальна кількість байтів логів для перевірки. + Максимальна кількість байтів журналу для перевірки. - WebSocket URL Gateway для snapshot health. + WebSocket URL Gateway для snapshot стану здоров’я. - Токен Gateway для snapshot health. + Токен Gateway для snapshot стану здоров’я. - Пароль Gateway для snapshot health. + Пароль Gateway для snapshot стану здоров’я. - Timeout для snapshot status/health. + Тайм-аут snapshot статусу/стану здоров’я. Пропустити пошук збереженого stability bundle. @@ -256,13 +256,13 @@ openclaw gateway diagnostics export --json Надрукувати записаний шлях, розмір і manifest як JSON. -Експорт містить manifest, підсумок Markdown, форму конфігурації, очищені деталі конфігурації, очищені підсумки логів, очищені snapshot-и status/health Gateway і найновіший stability bundle, якщо він існує. +Експорт містить manifest, Markdown-зведення, форму конфігурації, очищені подробиці конфігурації, очищені зведення журналів, очищені snapshot статусу/стану здоров’я Gateway і найновіший stability bundle, якщо він існує. -Він призначений для поширення. Він зберігає операційні деталі, що допомагають у налагодженні, як-от безпечні поля логів OpenClaw, назви підсистем, коди статусу, тривалості, налаштовані режими, порти, ідентифікатори плагінів, ідентифікатори providers, несекретні налаштування функцій і редаговані операційні повідомлення логів. Він пропускає або редагує текст чату, тіла webhook, виводи інструментів, облікові дані, cookies, ідентифікатори облікових записів/повідомлень, текст prompts/instructions, hostnames і секретні значення. Коли повідомлення в стилі LogTape схоже на текст payload користувача/чату/інструмента, експорт зберігає лише факт, що повідомлення було пропущено, плюс його кількість байтів. +Він призначений для поширення. Він зберігає операційні подробиці, які допомагають із налагодженням, наприклад безпечні поля журналу OpenClaw, назви підсистем, коди статусу, тривалості, налаштовані режими, порти, id plugin, id провайдерів, несекретні налаштування функцій і заредаговані операційні повідомлення журналу. Він пропускає або редагує текст чату, тіла webhook, виводи інструментів, облікові дані, cookie, ідентифікатори акаунтів/повідомлень, текст prompt/інструкцій, імена хостів і секретні значення. Коли повідомлення у стилі LogTape схоже на текст payload користувача/чату/інструмента, експорт зберігає лише факт, що повідомлення було пропущено, а також його кількість байтів. ### `gateway status` -`gateway status` показує службу Gateway (launchd/systemd/schtasks) плюс необов’язкову перевірку можливості підключення/автентифікації. +`gateway status` показує сервіс Gateway (launchd/systemd/schtasks) плюс необов’язкову перевірку можливості підключення/автентифікації. ```bash openclaw gateway status @@ -271,63 +271,64 @@ openclaw gateway status --require-rpc ``` - Додайте явну ціль зондування. Налаштовані віддалений вузол і localhost все одно зондуються. + Додайте явну ціль перевірки. Налаштований віддалений хост + localhost усе одно перевіряються. - Автентифікація токеном для зондування. + Автентифікація токеном для перевірки. - Автентифікація паролем для зондування. + Автентифікація паролем для перевірки. - Час очікування зондування. + Тайм-аут перевірки. - Пропустити зондування з’єднання (перегляд лише сервісу). + Пропустити перевірку підключення (перегляд лише сервісу). - Також сканувати служби системного рівня. + Також сканувати сервіси системного рівня. - Підвищити стандартне зондування з’єднання до зондування читання й завершити з ненульовим кодом, якщо це зондування читання завершується невдало. Не можна поєднувати з `--no-probe`. + Підвищити стандартну перевірку підключення до перевірки читання та завершуватися з ненульовим кодом, коли ця перевірка читання не вдається. Не можна поєднувати з `--no-probe`. - `gateway status` залишається доступною для діагностики, навіть коли локальна конфігурація CLI відсутня або недійсна. - - Стандартна `gateway status` підтверджує стан сервісу, WebSocket-з’єднання та можливість автентифікації, видиму під час handshake. Вона не підтверджує операції читання/запису/адміністрування. - - Діагностичні зондування не змінюють стан для першої автентифікації пристрою: вони повторно використовують наявний кешований токен пристрою, якщо він існує, але не створюють нову ідентичність пристрою CLI або запис read-only сполучення пристрою лише для перевірки статусу. - - `gateway status` за можливості розв’язує налаштовані SecretRefs автентифікації для автентифікації зондування. - - Якщо потрібний SecretRef автентифікації не розв’язано в цьому шляху команди, `gateway status --json` повідомляє `rpc.authWarning`, коли з’єднання/автентифікація зондування завершується невдало; передайте `--token`/`--password` явно або спершу розв’яжіть джерело секрету. - - Якщо зондування успішне, попередження про нерозв’язані auth-ref приглушуються, щоб уникнути хибних спрацьовувань. - - Використовуйте `--require-rpc` у скриптах і автоматизації, коли сервісу, що прослуховує порт, недостатньо й потрібно, щоб RPC-виклики з областю читання також були працездатними. - - `--deep` додає best-effort сканування додаткових інсталяцій launchd/systemd/schtasks. Коли виявлено кілька gateway-подібних сервісів, текстовий вивід друкує підказки з очищення та попереджає, що більшість налаштувань мають запускати один gateway на машину. - - Текстовий вивід містить розв’язаний шлях до файлового журналу, а також знімок шляхів/чинності конфігурації CLI і сервісу, щоб допомогти діагностувати розбіжність профілю або state-dir. + - Типова команда `gateway status` підтверджує стан сервісу, WebSocket-підключення та можливість автентифікації, видиму під час handshake. Вона не підтверджує операції читання/запису/адміністрування. + - Діагностичні перевірки не вносять змін для автентифікації пристрою вперше: вони повторно використовують наявний кешований токен пристрою, якщо він існує, але не створюють нову ідентичність CLI-пристрою чи запис read-only сполучення пристрою лише для перевірки статусу. + - `gateway status` за можливості розв’язує налаштовані auth SecretRefs для автентифікації перевірки. + - Якщо обов’язковий auth SecretRef не розв’язано в цьому шляху команди, `gateway status --json` повідомляє `rpc.authWarning`, коли підключення/автентифікація перевірки не вдається; передайте `--token`/`--password` явно або спершу розв’яжіть джерело секрету. + - Якщо перевірка успішна, попередження про нерозв’язані auth-ref пригнічуються, щоб уникнути хибних спрацювань. + - Використовуйте `--require-rpc` у скриптах і автоматизації, коли сервіс, що прослуховує порт, недостатній і потрібно, щоб RPC-виклики з областю читання також були справними. + - `--deep` додає best-effort сканування додаткових установок launchd/systemd/schtasks. Коли виявлено кілька gateway-подібних сервісів, вивід для людини друкує підказки з очищення та попереджає, що більшість налаштувань мають запускати один gateway на машину. + - `--deep` також повідомляє про нещодавню передачу перезапуску супервізора Gateway, коли процес сервісу коректно завершився для перезапуску зовнішнім супервізором. + - Вивід для людини містить розв’язаний шлях до файлового журналу, а також знімок шляхів/чинності конфігурації CLI проти сервісу, щоб допомогти діагностувати розбіжність профілю або state-dir. - - - В інсталяціях Linux systemd перевірки auth drift сервісу читають як значення `Environment=`, так і `EnvironmentFile=` з unit (включно з `%h`, шляхами в лапках, кількома файлами та необов’язковими файлами `-`). - - Перевірки drift розв’язують SecretRefs `gateway.auth.token` за допомогою об’єднаного runtime env (спершу env команди сервісу, потім fallback до process env). - - Якщо автентифікація токеном фактично не активна (явний `gateway.auth.mode` зі значенням `password`/`none`/`trusted-proxy` або mode не задано, де пароль може перемогти й жоден кандидат токена не може перемогти), перевірки token-drift пропускають розв’язання токена конфігурації. + + - В установках Linux systemd перевірки розбіжності автентифікації сервісу читають значення `Environment=` і `EnvironmentFile=` з unit (включно з `%h`, шляхами в лапках, кількома файлами та необов’язковими файлами з `-`). + - Перевірки розбіжності розв’язують `gateway.auth.token` SecretRefs за допомогою об’єднаного runtime env (спершу env команди сервісу, потім fallback до process env). + - Якщо автентифікація токеном фактично не активна (явний `gateway.auth.mode` зі значенням `password`/`none`/`trusted-proxy`, або режим не задано, де пароль може перемогти й жоден кандидат токена не може перемогти), перевірки token-drift пропускають розв’язання токена конфігурації. ### `gateway probe` -`gateway probe` — це команда «налагодити все». Вона завжди зондує: +`gateway probe` — це команда «debug everything». Вона завжди перевіряє: - ваш налаштований віддалений gateway (якщо задано), і -- localhost (loopback) **навіть якщо віддалений вузол налаштовано**. +- localhost (loopback) **навіть якщо віддалений gateway налаштовано**. -Якщо передати `--url`, цю явну ціль буде додано перед обома. Текстовий вивід позначає цілі так: +Якщо передати `--url`, ця явна ціль додається перед обома. Вивід для людини позначає цілі так: - `URL (explicit)` - `Remote (configured)` або `Remote (configured, inactive)` - `Local loopback` -Якщо доступні кілька gateway, команда виводить усі. Кілька gateway підтримуються, коли ви використовуєте ізольовані профілі/порти (наприклад, rescue bot), але більшість інсталяцій усе одно запускають один gateway. +Якщо доступні кілька gateway, команда друкує їх усі. Кілька gateway підтримуються, коли ви використовуєте ізольовані профілі/порти (наприклад, rescue bot), але більшість установок усе одно запускає один gateway. ```bash @@ -337,51 +338,51 @@ openclaw gateway probe --json - - `Reachable: yes` означає, що принаймні одна ціль прийняла WebSocket-з’єднання. - - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` повідомляє, що зондування змогло підтвердити щодо автентифікації. Це окремо від досяжності. - - `Read probe: ok` означає, що RPC-виклики деталізації з областю читання (`health`/`status`/`system-presence`/`config.get`) також виконалися успішно. - - `Read probe: limited - missing scope: operator.read` означає, що з’єднання успішне, але RPC з областю читання обмежений. Це повідомляється як **погіршена** досяжність, а не повний збій. - - `Read probe: failed` після `Connect: ok` означає, що Gateway прийняв WebSocket-з’єднання, але подальша діагностика читання перевищила час очікування або завершилася невдало. Це також **погіршена** досяжність, а не недосяжний Gateway. - - Як і `gateway status`, зондування повторно використовує наявну кешовану автентифікацію пристрою, але не створює першу ідентичність пристрою або стан сполучення. - - Код виходу ненульовий лише тоді, коли жодна зондувана ціль недосяжна. + - `Reachable: yes` означає, що принаймні одна ціль прийняла WebSocket-підключення. + - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` повідомляє, що перевірка змогла підтвердити щодо автентифікації. Це окремо від доступності. + - `Read probe: ok` означає, що RPC-виклики деталей з областю читання (`health`/`status`/`system-presence`/`config.get`) також успішні. + - `Read probe: limited - missing scope: operator.read` означає, що підключення успішне, але RPC з областю читання обмежене. Це повідомляється як **погіршена** доступність, а не повна відмова. + - `Read probe: failed` після `Connect: ok` означає, що Gateway прийняв WebSocket-з’єднання, але подальша діагностика читання завершилася тайм-аутом або помилкою. Це також **погіршена** доступність, а не недоступний Gateway. + - Як і `gateway status`, probe повторно використовує наявну кешовану автентифікацію пристрою, але не створює першу ідентичність пристрою чи стан сполучення. + - Код виходу ненульовий лише тоді, коли жодна перевірена ціль недоступна. Верхній рівень: - - `ok`: принаймні одна ціль досяжна. - - `degraded`: принаймні одна ціль прийняла з’єднання, але не завершила повну деталізовану RPC-діагностику. - - `capability`: найкраща можливість, побачена серед досяжних цілей (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` або `unknown`). - - `primaryTargetId`: найкраща ціль, яку слід вважати активним переможцем, у такому порядку: явний URL, SSH tunnel, налаштований віддалений вузол, потім local loopback. + - `ok`: принаймні одна ціль доступна. + - `degraded`: принаймні одна ціль прийняла підключення, але не завершила повну детальну RPC-діагностику. + - `capability`: найкраща можливість, побачена серед доступних цілей (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` або `unknown`). + - `primaryTargetId`: найкраща ціль, яку слід вважати активним переможцем у такому порядку: явний URL, SSH-тунель, налаштований віддалений хост, потім local loopback. - `warnings[]`: best-effort записи попереджень із `code`, `message` та необов’язковими `targetIds`. - `network`: підказки URL для local loopback/tailnet, отримані з поточної конфігурації та мережі хоста. - - `discovery.timeoutMs` і `discovery.count`: фактичний бюджет/кількість результатів discovery, використані для цього проходу зондування. + - `discovery.timeoutMs` і `discovery.count`: фактичний бюджет/кількість результатів виявлення, використані для цього проходу перевірки. Для кожної цілі (`targets[].connect`): - - `ok`: досяжність після класифікації connect + degraded. - - `rpcOk`: успіх повної деталізованої RPC. - - `scopeLimited`: деталізована RPC завершилася невдало через відсутню область operator. + - `ok`: доступність після connect + degraded класифікації. + - `rpcOk`: успішне повне RPC деталей. + - `scopeLimited`: RPC деталей не вдалося через відсутню область оператора. Для кожної цілі (`targets[].auth`): - `role`: роль автентифікації, повідомлена в `hello-ok`, коли доступна. - `scopes`: надані області, повідомлені в `hello-ok`, коли доступні. - - `capability`: відображена класифікація можливості автентифікації для цієї цілі. + - `capability`: показана класифікація можливості автентифікації для цієї цілі. - - `ssh_tunnel_failed`: налаштування SSH tunnel завершилося невдало; команда повернулася до прямих зондувань. - - `multiple_gateways`: досяжною була більш ніж одна ціль; це незвично, якщо ви навмисно не запускаєте ізольовані профілі, наприклад rescue bot. - - `auth_secretref_unresolved`: налаштований SecretRef автентифікації не вдалося розв’язати для цілі, що завершилася невдало. - - `probe_scope_limited`: WebSocket-з’єднання успішне, але зондування читання було обмежене через відсутній `operator.read`. + - `ssh_tunnel_failed`: налаштування SSH-тунелю не вдалося; команда повернулася до прямих перевірок. + - `multiple_gateways`: доступна більше ніж одна ціль; це незвично, якщо ви навмисно не запускаєте ізольовані профілі, наприклад rescue bot. + - `auth_secretref_unresolved`: налаштований auth SecretRef не вдалося розв’язати для цілі з помилкою. + - `probe_scope_limited`: WebSocket-підключення успішне, але перевірка читання обмежена через відсутній `operator.read`. -#### Віддалено через SSH (паритет із Mac app) +#### Віддалений доступ через SSH (паритет із Mac app) -Режим macOS app «Remote over SSH» використовує локальне перенаправлення порту, щоб віддалений gateway (який може бути прив’язаний лише до loopback) став доступним за `ws://127.0.0.1:`. +Режим "Remote over SSH" у macOS app використовує локальне перенаправлення порту, щоб віддалений gateway (який може бути прив’язаний лише до loopback) став доступним за адресою `ws://127.0.0.1:`. Еквівалент CLI: @@ -390,13 +391,13 @@ openclaw gateway probe --ssh user@gateway-host ``` - `user@host` або `user@host:port` (port за замовчуванням `22`). + `user@host` або `user@host:port` (порт за замовчуванням `22`). Файл ідентичності. - Вибрати перший виявлений хост gateway як ціль SSH з розв’язаного endpoint discovery (`local.` плюс налаштований wide-area domain, якщо є). Підказки лише TXT ігноруються. + Вибрати перший виявлений хост gateway як SSH-ціль із розв’язаного endpoint виявлення (`local.` плюс налаштований wide-area domain, якщо є). Підказки лише TXT ігноруються. Конфігурація (необов’язкова, використовується як значення за замовчуванням): @@ -426,10 +427,10 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}' Пароль Gateway. - Бюджет часу очікування. + Бюджет тайм-ауту. - Переважно для RPC у стилі агентів, які передають проміжні події перед фінальним payload. + Переважно для agent-style RPC, які транслюють проміжні події перед фінальним payload. Машинозчитуваний JSON-вивід. @@ -449,9 +450,9 @@ openclaw gateway restart openclaw gateway uninstall ``` -### Інсталяція з wrapper +### Установлення з wrapper -Використовуйте `--wrapper`, коли керований сервіс має запускатися через інший виконуваний файл, наприклад shim менеджера секретів або run-as helper. Wrapper отримує звичайні аргументи Gateway і відповідає за те, щоб зрештою виконати `openclaw` або Node з цими аргументами. +Використовуйте `--wrapper`, коли керований сервіс має запускатися через інший виконуваний файл, наприклад shim менеджера секретів або run-as helper. Wrapper отримує звичайні аргументи Gateway і відповідає за те, щоб зрештою виконати `openclaw` або Node із цими аргументами. ```bash cat > ~/.local/bin/openclaw-doppler <<'EOF' @@ -465,7 +466,7 @@ openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force openclaw gateway restart ``` -Також можна задати wrapper через середовище. `gateway install` перевіряє, що шлях є виконуваним файлом, записує wrapper у `ProgramArguments` сервісу та зберігає `OPENCLAW_WRAPPER` у середовищі сервісу для подальших примусових перевстановлень, оновлень і виправлень doctor. +Ви також можете задати wrapper через середовище. `gateway install` перевіряє, що шлях є виконуваним файлом, записує wrapper у service `ProgramArguments` і зберігає `OPENCLAW_WRAPPER` у середовищі сервісу для подальших примусових перевстановлень, оновлень і виправлень doctor. ```bash OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force @@ -488,39 +489,39 @@ openclaw gateway restart - - Використовуйте `gateway restart`, щоб перезапустити керований сервіс. Не об’єднуйте `gateway stop` і `gateway start` як заміну перезапуску; на macOS `gateway stop` навмисно вимикає LaunchAgent перед його зупинкою. - - `gateway restart --safe` просить запущений Gateway виконати preflight активної роботи OpenClaw і відкласти перезапуск, доки доставлення відповідей, вбудовані запуски та запуски завдань не завершаться. `--safe` не можна поєднувати з `--force` або `--wait`. - - `gateway restart --wait 30s` перевизначає налаштований бюджет drain для перезапуску. Голі числа означають мілісекунди; приймаються одиниці, як-от `s`, `m` і `h`. `--wait 0` чекає безстроково. - - `gateway restart --force` пропускає drain активної роботи й перезапускає негайно. Використовуйте це, коли оператор уже перевірив перелічені блокери завдань і хоче повернути gateway зараз. + - Використовуйте `gateway restart`, щоб перезапустити керований сервіс. Не поєднуйте `gateway stop` і `gateway start` як заміну перезапуску; на macOS `gateway stop` навмисно вимикає LaunchAgent перед його зупинкою. + - `gateway restart --safe` просить запущений Gateway попередньо перевірити активну роботу OpenClaw і відкласти перезапуск, доки доставка відповідей, embedded runs і task runs не завершаться. `--safe` не можна поєднувати з `--force` або `--wait`. + - `gateway restart --wait 30s` перевизначає налаштований бюджет drain для цього перезапуску. Числа без одиниць — мілісекунди; приймаються одиниці на кшталт `s`, `m` і `h`. `--wait 0` очікує безстроково. + - `gateway restart --force` пропускає drain активної роботи та перезапускає негайно. Використовуйте це, коли оператор уже перевірив перелічені блокувальники завдань і хоче повернути gateway зараз. - Команди життєвого циклу приймають `--json` для скриптів. - - - Коли автентифікація за токеном потребує токен і `gateway.auth.token` керується через SecretRef, `gateway install` перевіряє, що SecretRef можна розв'язати, але не зберігає розв'язаний токен у метаданих середовища сервісу. - - Якщо автентифікація за токеном потребує токен, а налаштований SecretRef токена не розв'язано, встановлення завершується закритою відмовою замість збереження резервного відкритого тексту. + + - Коли автентифікація за токеном вимагає токен і `gateway.auth.token` керується через SecretRef, `gateway install` перевіряє, що SecretRef можна розв’язати, але не зберігає розв’язаний токен у метаданих середовища сервісу. + - Якщо автентифікація за токеном вимагає токен, а налаштований SecretRef токена не розв’язано, установлення завершується закритою відмовою замість збереження резервного відкритого тексту. - Для автентифікації паролем у `gateway run` віддавайте перевагу `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` або `gateway.auth.password` на основі SecretRef замість вбудованого `--password`. - - У режимі виведеної автентифікації лише shell-змінна `OPENCLAW_GATEWAY_PASSWORD` не послаблює вимоги до токена під час встановлення; використовуйте сталу конфігурацію (`gateway.auth.password` або config `env`) під час встановлення керованого сервісу. - - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, встановлення блокується, доки режим не буде задано явно. + - У виведеному режимі автентифікації лише оболонковий `OPENCLAW_GATEWAY_PASSWORD` не послаблює вимоги до токена під час установлення; використовуйте тривалу конфігурацію (`gateway.auth.password` або `env` конфігурації) під час установлення керованого сервісу. + - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, установлення блокується, доки режим не буде задано явно. -## Виявлення Gateway (Bonjour) +## Виявлення gateway (Bonjour) -`gateway discover` сканує маячки Gateway (`_openclaw-gw._tcp`). +`gateway discover` сканує beacons Gateway (`_openclaw-gw._tcp`). - Multicast DNS-SD: `local.` - Unicast DNS-SD (Wide-Area Bonjour): виберіть домен (приклад: `openclaw.internal.`) і налаштуйте split DNS + DNS-сервер; див. [Bonjour](/uk/gateway/bonjour). -Лише екземпляри Gateway з увімкненим виявленням Bonjour (типово) оголошують маячок. +Лише gateway, для яких увімкнено виявлення Bonjour (типово), рекламують beacon. -Записи Wide-Area виявлення містять (TXT): +Записи Wide-Area discovery містять (TXT): -- `role` (підказка ролі Gateway) +- `role` (підказка ролі gateway) - `transport` (підказка транспорту, напр. `gateway`) - `gatewayPort` (порт WebSocket, зазвичай `18789`) -- `sshPort` (необов'язково; клієнти типово використовують `22` для SSH-цілей, коли він відсутній) -- `tailnetDns` (ім'я хоста MagicDNS, коли доступне) +- `sshPort` (необов’язково; клієнти типово використовують `22` для SSH-цілей, коли його немає) +- `tailnetDns` (ім’я хоста MagicDNS, коли доступне) - `gatewayTls` / `gatewayTlsSha256` (TLS увімкнено + відбиток сертифіката) - `cliPath` (підказка віддаленого встановлення, записана в wide-area зону) @@ -531,10 +532,10 @@ openclaw gateway discover ``` - Таймаут для команди (browse/resolve). + Тайм-аут для команди (browse/resolve). - Машиночитний вивід (також вимикає стилізацію/індикатор). + Машинозчитуваний вивід (також вимикає стилізацію/індикатор виконання). Приклади: @@ -546,12 +547,12 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl' - CLI сканує `local.` плюс налаштований wide-area домен, коли його ввімкнено. -- `wsUrl` у JSON-виводі походить із розв'язаного endpoint сервісу, а не лише з TXT-підказок, таких як `lanHost` або `tailnetDns`. -- У `local.` mDNS, `sshPort` і `cliPath` транслюються лише тоді, коли `discovery.mdns.mode` дорівнює `full`. Wide-area DNS-SD все одно записує `cliPath`; `sshPort` там також залишається необов'язковим. +- `wsUrl` у JSON-виводі походить від розв’язаного endpoint сервісу, а не від підказок лише з TXT, як-от `lanHost` або `tailnetDns`. +- У `local.` mDNS, `sshPort` і `cliPath` транслюються лише коли `discovery.mdns.mode` дорівнює `full`. Wide-area DNS-SD все одно записує `cliPath`; `sshPort` там також лишається необов’язковим. -## Пов'язане +## Пов’язане - [Довідник CLI](/uk/cli) - [Runbook Gateway](/uk/gateway) diff --git a/docs/uk/cli/hooks.md b/docs/uk/cli/hooks.md index c5689e9c8..853e45b02 100644 --- a/docs/uk/cli/hooks.md +++ b/docs/uk/cli/hooks.md @@ -1,28 +1,28 @@ --- read_when: - - Ви хочете керувати хуками агентів - - Ви хочете перевірити доступність хуків або ввімкнути хуки робочої області -summary: Довідник CLI для `openclaw hooks` (агентські хуки) + - Ви хочете керувати хуками агента + - Ви хочете перевірити доступність хуків або ввімкнути хуки робочого простору +summary: Довідка CLI для `openclaw hooks` (хуки агентів) title: Хуки x-i18n: - generated_at: "2026-05-02T19:10:48Z" + generated_at: "2026-05-05T08:03:54Z" model: gpt-5.5 provider: openai - source_hash: 3b02c176b4a310adba3fa1fde3758f6c8a19d454aeec58e919458b3f1a66c87d + source_hash: 8e860d4a20a09526e804fa1aff8c983a75396fcd1e6e24f742252fdf1812f6b7 source_path: cli/hooks.md workflow: 16 --- # `openclaw hooks` -Керуйте хуками агента (автоматизаціями, керованими подіями, для команд на кшталт `/new`, `/reset` і запуску Gateway). +Керуйте хуками агента (автоматизаціями на основі подій для команд на кшталт `/new`, `/reset` і запуску Gateway). Запуск `openclaw hooks` без підкоманди еквівалентний `openclaw hooks list`. Пов’язане: - Хуки: [Хуки](/uk/automation/hooks) -- Хуки Plugin: [Хуки Plugin](/uk/plugins/hooks) +- Plugin-хуки: [Plugin-хуки](/uk/plugins/hooks) ## Перелічити всі хуки @@ -30,10 +30,10 @@ x-i18n: openclaw hooks list ``` -Перелічує всі виявлені хуки з робочого простору, керованих, додаткових і вбудованих каталогів. -Під час запуску Gateway внутрішні обробники хуків не завантажуються, доки не налаштовано принаймні один внутрішній хук. +Перелічує всі виявлені хуки з каталогів workspace, managed, extra та bundled. +Запуск Gateway не завантажує внутрішні обробники хуків, доки не налаштовано принаймні один внутрішній хук. -**Параметри:** +**Опції:** - `--eligible`: Показати лише придатні хуки (вимоги виконано) - `--json`: Вивести як JSON @@ -51,7 +51,7 @@ Ready: 💾 session-memory ✓ - Save session context to memory when /new or /reset command is issued ``` -**Приклад (докладно):** +**Приклад (докладний):** ```bash openclaw hooks list --verbose @@ -79,7 +79,7 @@ openclaw hooks info - ``: Назва хуку або ключ хуку (наприклад, `session-memory`) -**Параметри:** +**Опції:** - `--json`: Вивести як JSON @@ -113,9 +113,9 @@ Requirements: openclaw hooks check ``` -Показує підсумок статусу придатності хуків (скільки готові, а скільки ні). +Показує підсумок стану придатності хуків (скільки готові, а скільки не готові). -**Параметри:** +**Опції:** - `--json`: Вивести як JSON @@ -135,9 +135,9 @@ Not ready: 0 openclaw hooks enable ``` -Увімкніть конкретний хук, додавши його до своєї конфігурації (типово `~/.openclaw/openclaw.json`). +Увімкніть конкретний хук, додавши його до своєї конфігурації (`~/.openclaw/openclaw.json` за замовчуванням). -**Примітка:** Хуки робочого простору вимкнено за замовчуванням, доки їх не буде ввімкнено тут або в конфігурації. Хуки, керовані Plugin, показують `plugin:` у `openclaw hooks list`, і їх не можна ввімкнути або вимкнути тут. Натомість увімкніть або вимкніть Plugin. +**Примітка:** Workspace-хуки вимкнені за замовчуванням, доки їх не ввімкнути тут або в конфігурації. Хуки, керовані plugins, показують `plugin:` в `openclaw hooks list`, і їх не можна ввімкнути або вимкнути тут. Натомість увімкніть або вимкніть відповідний plugin. **Аргументи:** @@ -157,16 +157,16 @@ openclaw hooks enable session-memory **Що це робить:** -- Перевіряє, чи існує хук і чи він придатний +- Перевіряє, чи хук існує та є придатним - Оновлює `hooks.internal.entries..enabled = true` у вашій конфігурації - Зберігає конфігурацію на диск -Якщо хук походить із `/hooks/`, цей крок явної згоди потрібен до того, як +Якщо хук походить із `/hooks/`, цей крок явної згоди потрібен, перш ніж Gateway завантажить його. **Після ввімкнення:** -- Перезапустіть Gateway, щоб хуки перезавантажилися (перезапуск програми в рядку меню на macOS або перезапуск процесу Gateway у розробці). +- Перезапустіть gateway, щоб хуки перезавантажилися (перезапуск застосунку в рядку меню на macOS або перезапуск процесу gateway у dev). ## Вимкнути хук @@ -194,12 +194,12 @@ openclaw hooks disable command-logger **Після вимкнення:** -- Перезапустіть Gateway, щоб хуки перезавантажилися +- Перезапустіть gateway, щоб хуки перезавантажилися ## Примітки - `openclaw hooks list --json`, `info --json` і `check --json` записують структурований JSON безпосередньо в stdout. -- Хуки, керовані Plugin, не можна ввімкнути або вимкнути тут; натомість увімкніть або вимкніть Plugin, якому вони належать. +- Хуки, керовані Plugin, не можна ввімкнути або вимкнути тут; натомість увімкніть або вимкніть відповідний plugin. ## Установити пакети хуків @@ -213,27 +213,27 @@ openclaw plugins install # local path Установлюйте пакети хуків через уніфікований інсталятор plugins. `openclaw hooks install` досі працює як псевдонім сумісності, але виводить -попередження про застарілість і передає виконання до `openclaw plugins install`. +попередження про застарілість і переспрямовує до `openclaw plugins install`. -Специфікації npm є **лише реєстровими** (назва пакета + необов’язкова **точна версія** або -**dist-tag**). Специфікації Git/URL/файлів і діапазони semver відхиляються. Установлення залежностей -виконується локально для проєкту з `--ignore-scripts` задля безпеки, навіть коли ваша -оболонка має глобальні налаштування npm install. +Специфікації npm є **лише registry** (назва пакета + необов’язкова **точна версія** або +**dist-tag**). Специфікації Git/URL/file і діапазони semver відхиляються. Установлення залежностей +виконується локально для проєкту з `--ignore-scripts` задля безпеки, навіть якщо у вашій +оболонці налаштовано глобальні параметри встановлення npm. -Прості специфікації та `@latest` залишаються на стабільному каналі. Якщо npm розв’язує будь-що з -цього до попереднього випуску, OpenClaw зупиняється й просить вас явно погодитися за допомогою -тегу попереднього випуску, як-от `@beta`/`@rc`, або точної версії попереднього випуску. +Прості специфікації та `@latest` залишаються на стабільному каналі. Якщо npm зіставляє будь-яку з +них із попереднім випуском, OpenClaw зупиняється й просить вас явно погодитися за допомогою +тегу попереднього випуску, наприклад `@beta`/`@rc`, або точної версії попереднього випуску. **Що це робить:** - Копіює пакет хуків у `~/.openclaw/hooks/` -- Увімкнює встановлені хуки в `hooks.internal.entries.*` +- Вмикає встановлені хуки в `hooks.internal.entries.*` - Записує встановлення в `hooks.internal.installs` -**Параметри:** +**Опції:** - `-l, --link`: Зв’язати локальний каталог замість копіювання (додає його до `hooks.internal.load.extraDirs`) -- `--pin`: Записувати встановлення npm як точно розв’язане `name@version` у `hooks.internal.installs` +- `--pin`: Записувати npm-встановлення як точне розв’язане `name@version` у `hooks.internal.installs` **Підтримувані архіви:** `.zip`, `.tgz`, `.tar.gz`, `.tar` @@ -254,7 +254,7 @@ openclaw plugins install -l ./my-hook-pack ``` Зв’язані пакети хуків розглядаються як керовані хуки з каталогу, налаштованого оператором, -а не як хуки робочого простору. +а не як workspace-хуки. ## Оновити пакети хуків @@ -263,17 +263,17 @@ openclaw plugins update openclaw plugins update --all ``` -Оновлюйте відстежувані пакети хуків на основі npm через уніфікований оновлювач plugins. +Оновлюйте відстежувані npm-пакети хуків через уніфікований оновлювач plugins. `openclaw hooks update` досі працює як псевдонім сумісності, але виводить -попередження про застарілість і передає виконання до `openclaw plugins update`. +попередження про застарілість і переспрямовує до `openclaw plugins update`. -**Параметри:** +**Опції:** - `--all`: Оновити всі відстежувані пакети хуків -- `--dry-run`: Показати, що зміниться, без запису +- `--dry-run`: Показати, що змінилося б, без запису -Коли існує збережений хеш цілісності, а хеш отриманого артефакту змінюється, +Коли збережений хеш цілісності існує, а хеш отриманого артефакту змінюється, OpenClaw виводить попередження й просить підтвердження перед продовженням. Використовуйте глобальний `--yes`, щоб обійти запити в CI/неінтерактивних запусках. @@ -281,7 +281,7 @@ OpenClaw виводить попередження й просить підтв ### session-memory -Зберігає контекст сеансу в пам’ять, коли ви видаєте `/new` або `/reset`. +Зберігає контекст сесії в пам’ять, коли ви виконуєте `/new` або `/reset`. **Увімкнути:** @@ -289,13 +289,13 @@ OpenClaw виводить попередження й просить підтв openclaw hooks enable session-memory ``` -**Вивід:** `~/.openclaw/workspace/memory/YYYY-MM-DD-slug.md` +**Вивід:** `~/.openclaw/workspace/memory/YYYY-MM-DD-HHMM.md` за замовчуванням. Установіть `hooks.internal.entries.session-memory.llmSlug: true` для slug-частин імен файлів, згенерованих моделлю. -**Див.:** [документація session-memory](/uk/automation/hooks#session-memory) +**Див.:** [документацію session-memory](/uk/automation/hooks#session-memory) ### bootstrap-extra-files -Вставляє додаткові файли bootstrap (наприклад, локальні для монорепозиторію `AGENTS.md` / `TOOLS.md`) під час `agent:bootstrap`. +Вставляє додаткові bootstrap-файли (наприклад, локальні для монорепозиторію `AGENTS.md` / `TOOLS.md`) під час `agent:bootstrap`. **Увімкнути:** @@ -303,11 +303,11 @@ openclaw hooks enable session-memory openclaw hooks enable bootstrap-extra-files ``` -**Див.:** [документація bootstrap-extra-files](/uk/automation/hooks#bootstrap-extra-files) +**Див.:** [документацію bootstrap-extra-files](/uk/automation/hooks#bootstrap-extra-files) ### command-logger -Записує всі події команд до централізованого файлу аудиту. +Записує всі події команд у централізований файл аудиту. **Увімкнути:** @@ -330,11 +330,11 @@ cat ~/.openclaw/logs/commands.log | jq . grep '"action":"new"' ~/.openclaw/logs/commands.log | jq . ``` -**Див.:** [документація command-logger](/uk/automation/hooks#command-logger) +**Див.:** [документацію command-logger](/uk/automation/hooks#command-logger) ### boot-md -Запускає `BOOT.md`, коли Gateway запускається (після запуску каналів). +Запускає `BOOT.md`, коли gateway запускається (після запуску каналів). **Події**: `gateway:startup` @@ -344,9 +344,9 @@ grep '"action":"new"' ~/.openclaw/logs/commands.log | jq . openclaw hooks enable boot-md ``` -**Див.:** [документація boot-md](/uk/automation/hooks#boot-md) +**Див.:** [документацію boot-md](/uk/automation/hooks#boot-md) ## Пов’язане -- [довідник CLI](/uk/cli) -- [хуки автоматизації](/uk/automation/hooks) +- [Довідник CLI](/uk/cli) +- [Хуки автоматизації](/uk/automation/hooks) diff --git a/docs/uk/gateway/doctor.md b/docs/uk/gateway/doctor.md index 62906a001..9a59affcf 100644 --- a/docs/uk/gateway/doctor.md +++ b/docs/uk/gateway/doctor.md @@ -1,20 +1,20 @@ --- read_when: - - Додавання або змінення міграцій doctor + - Додавання або змінення діагностичних міграцій - Запровадження несумісних змін конфігурації sidebarTitle: Doctor -summary: 'Команда doctor: перевірки стану, міграції конфігурації та кроки відновлення' +summary: 'Команда doctor: перевірки справності, міграції конфігурації та кроки відновлення' title: Діагностика x-i18n: - generated_at: "2026-05-05T01:21:21Z" + generated_at: "2026-05-05T08:04:00Z" model: gpt-5.5 provider: openai - source_hash: 3e374f91d00d4b43a3852de6f746b044471e80af936d464a789061a31cadd09d + source_hash: 360f9f7a349e4633ff61d526f1eb5b668b595b4f35c5e0fd2a314715a0599c4c source_path: gateway/doctor.md workflow: 16 --- -`openclaw doctor` — це інструмент відновлення + міграції для OpenClaw. Він виправляє застарілі конфігурацію/стан, перевіряє працездатність і надає придатні до виконання кроки відновлення. +`openclaw doctor` — це інструмент ремонту й міграції для OpenClaw. Він виправляє застарілі конфігурацію/стан, перевіряє справність і надає практичні кроки ремонту. ## Швидкий старт @@ -22,7 +22,7 @@ x-i18n: openclaw doctor ``` -### Безголовий режим і режими автоматизації +### Режими без інтерфейсу та автоматизації @@ -30,7 +30,7 @@ openclaw doctor openclaw doctor --yes ``` - Приймає типові значення без запитів (включно з кроками перезапуску/сервісу/відновлення sandbox, коли застосовно). + Прийняти стандартні значення без запитів (зокрема кроки перезапуску/сервісу/ремонту пісочниці, коли застосовно). @@ -38,7 +38,7 @@ openclaw doctor openclaw doctor --repair ``` - Застосовує рекомендовані виправлення без запитів (виправлення + перезапуски, де це безпечно). + Застосувати рекомендовані ремонти без запитів (ремонти + перезапуски, де це безпечно). @@ -46,7 +46,7 @@ openclaw doctor openclaw doctor --repair --force ``` - Також застосовує агресивні виправлення (перезаписує користувацькі конфігурації supervisor). + Застосувати також агресивні ремонти (перезаписує користувацькі конфігурації supervisor). @@ -54,7 +54,7 @@ openclaw doctor openclaw doctor --non-interactive ``` - Запускається без запитів і застосовує лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії перезапуску/сервісу/sandbox, які потребують підтвердження людини. Міграції застарілого стану виконуються автоматично після виявлення. + Запустити без запитів і застосувати лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії перезапуску/сервісу/пісочниці, що потребують підтвердження людини. Міграції застарілого стану запускаються автоматично, коли їх виявлено. @@ -62,99 +62,100 @@ openclaw doctor openclaw doctor --deep ``` - Сканує системні сервіси на наявність додаткових інсталяцій Gateway (launchd/systemd/schtasks). + Сканувати системні сервіси на наявність додаткових інсталяцій Gateway (launchd/systemd/schtasks). -Якщо ви хочете переглянути зміни перед записом, спочатку відкрийте файл конфігурації: +Якщо ви хочете переглянути зміни перед записом, спершу відкрийте файл конфігурації: ```bash cat ~/.openclaw/openclaw.json ``` -## Що він робить (підсумок) +## Що він робить (зведення) - - - Необов’язкове попереднє оновлення для git-інсталяцій (лише інтерактивно). + + - Необовʼязкове попереднє оновлення для git-інсталяцій (лише інтерактивно). - Перевірка актуальності протоколу UI (перезбирає Control UI, коли схема протоколу новіша). - - Перевірка стану + запит на перезапуск. - - Підсумок стану Skills (доступні/відсутні/заблоковані) і стан Plugin. + - Перевірка справності + запит на перезапуск. + - Зведення стану Skills (придатні/відсутні/заблоковані) і стан Plugin. - Нормалізація конфігурації для застарілих значень. - Міграція конфігурації Talk із застарілих плоских полів `talk.*` у `talk.provider` + `talk.providers.`. - Перевірки міграції браузера для застарілих конфігурацій розширення Chrome і готовності Chrome MCP. - - Попередження щодо перевизначень провайдера OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). - - Попередження щодо затінення OAuth Codex (`models.providers.openai-codex`). + - Попередження про перевизначення провайдера OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). + - Попередження про затінення OAuth Codex (`models.providers.openai-codex`). - Перевірка передумов OAuth TLS для профілів OpenAI Codex OAuth. - Попередження allowlist Plugin/інструментів, коли `plugins.allow` є обмежувальним, але політика інструментів усе ще запитує wildcard або інструменти, що належать Plugin. - Міграція застарілого стану на диску (sessions/agent dir/WhatsApp auth). - Міграція застарілих ключів контракту маніфесту Plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). - - Міграція застарілого сховища Cron (`jobId`, `schedule.cron`, поля доставки/payload верхнього рівня, payload `provider`, прості резервні завдання Webhook `notify: true`). - - Міграція застарілої runtime-політики агентів до `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`. - - Очищення застарілої конфігурації Plugin, коли plugins увімкнено; коли `plugins.enabled=false`, застарілі посилання на Plugin вважаються інертною конфігурацією ізоляції та зберігаються. + - Міграція застарілого сховища cron (`jobId`, `schedule.cron`, поля delivery/payload верхнього рівня, payload `provider`, прості резервні webhook-завдання `notify: true`). + - Міграція застарілої політики runtime agent до `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`. + - Очищення застарілої конфігурації Plugin, коли plugins увімкнено; коли `plugins.enabled=false`, застарілі посилання на Plugin вважаються інертною конфігурацією containment і зберігаються. - - Перевірка lock-файлів сесій і очищення застарілих lock-файлів. - - Відновлення transcript сесій для дубльованих гілок prompt-rewrite, створених ураженими збірками 2026.4.24. - - Виявлення tombstone для restart-recovery завислих subagent із підтримкою `--fix` для очищення застарілих прапорців aborted recovery, щоб запуск не продовжував вважати дочірній процес restart-aborted. + - Перевірка lock-файлів сеансів і очищення застарілих lock-файлів. + - Ремонт transcript сеансів для дубльованих гілок prompt-rewrite, створених ураженими збірками 2026.4.24. + - Виявлення tombstone для restart-recovery заблокованих subagent, з підтримкою `--fix` для очищення застарілих прапорців aborted recovery, щоб startup не продовжував трактувати child як restart-aborted. - Перевірки цілісності стану та дозволів (sessions, transcripts, state dir). - Перевірки дозволів файлу конфігурації (chmod 600) під час локального запуску. - - Стан автентифікації моделей: перевіряє закінчення строку OAuth, може оновлювати токени, що скоро спливають, і повідомляє стани cooldown/disabled auth-profile. - - Виявлення додаткового каталогу workspace (`~/openclaw`). + - Справність автентифікації моделей: перевіряє строк дії OAuth, може оновлювати токени, строк дії яких спливає, і повідомляє про стани cooldown/disabled auth-profile. + - Виявлення додаткового workspace dir (`~/openclaw`). - - - Відновлення образу sandbox, коли sandboxing увімкнено. + + - Ремонт образу пісочниці, коли sandboxing увімкнено. - Міграція застарілого сервісу та виявлення додаткових Gateway. - Міграція застарілого стану каналу Matrix (у режимі `--fix` / `--repair`). - - Перевірки runtime Gateway (сервіс встановлено, але він не працює; кешована мітка launchd). - - Попередження стану каналу (перевіряються з запущеного Gateway). - - Аудит конфігурації supervisor (launchd/systemd/schtasks) з необов’язковим відновленням. - - Очищення середовища вбудованого proxy для сервісів Gateway, які захопили shell-значення `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` під час встановлення або оновлення. - - Перевірки найкращих практик runtime Gateway (Node проти Bun, шляхи version-manager). - - Діагностика конфлікту порту Gateway (типовий `18789`). + - Перевірки runtime Gateway (сервіс встановлено, але не запущено; кешована мітка launchd). + - Попередження про стан каналів (перевіряються з запущеного Gateway). + - Перевірки чутливості WhatsApp для погіршеного стану event-loop Gateway, коли локальні TUI-клієнти все ще працюють; `--fix` зупиняє лише перевірені локальні TUI-клієнти. + - Аудит конфігурації supervisor (launchd/systemd/schtasks) з необовʼязковим ремонтом. + - Очищення середовища вбудованого proxy для сервісів Gateway, які захопили значення shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` під час встановлення або оновлення. + - Перевірки найкращих практик runtime Gateway (Node vs Bun, шляхи version-manager). + - Діагностика конфліктів портів Gateway (типово `18789`). - - Попередження безпеки для відкритих DM-політик. - - Перевірки автентифікації Gateway для режиму локального токена (пропонує генерацію токена, коли джерела токена немає; не перезаписує конфігурації SecretRef токенів). - - Виявлення проблем pairing пристроїв (очікувані перші запити pairing, очікувані підвищення ролі/області, застаріле розходження кешу локального device-token і розходження автентифікації paired-record). + - Попередження безпеки для відкритих політик DM. + - Перевірки автентифікації Gateway для режиму локального токена (пропонує генерацію токена, коли джерела токена не існує; не перезаписує конфігурації token SecretRef). + - Виявлення проблем pairing пристрою (очікувані перші запити pair, очікувані оновлення role/scope, застаріле розходження локального кешу device-token і розходження автентифікації paired-record). - Перевірка systemd linger у Linux. - - Перевірка розміру bootstrap-файлу workspace (попередження про обрізання/наближення до ліміту для контекстних файлів). - - Перевірка готовності Skills для типового агента; повідомляє дозволені skills із відсутніми binaries, env, config або вимогами до ОС, а `--fix` може вимкнути недоступні skills у `skills.entries`. + - Перевірка розміру bootstrap-файлу workspace (попередження про truncation/near-limit для context-файлів). + - Перевірка готовності Skills для типового agent; повідомляє про дозволені skills із відсутніми bins, env, config або вимогами OS, а `--fix` може вимкнути недоступні skills у `skills.entries`. - Перевірка стану shell completion і автоматичне встановлення/оновлення. - - Перевірка готовності провайдера embedding для пошуку в пам’яті (локальна модель, віддалений API-ключ або QMD binary). - - Перевірки source install (невідповідність pnpm workspace, відсутні UI assets, відсутній tsx binary). - - Записує оновлену конфігурацію + метадані wizard. + - Перевірка готовності провайдера embedding для пошуку memory (локальна модель, віддалений API key або binary QMD). + - Перевірки source install (невідповідність pnpm workspace, відсутні UI assets, відсутній binary tsx). + - Записує оновлену конфігурацію + metadata wizard. -## Зворотне заповнення й скидання Dreams UI +## Backfill і reset у Dreams UI -Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded** для workflow grounded dreaming. Ці дії використовують RPC-методи у стилі Gateway doctor, але вони **не** є частиною repair/migration CLI `openclaw doctor`. +Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded** для grounded dreaming workflow. Ці дії використовують RPC-методи у стилі gateway doctor, але вони **не** є частиною CLI ремонту/міграції `openclaw doctor`. Що вони роблять: -- **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному workspace, запускає grounded REM diary pass і записує зворотні записи backfill у `DREAMS.md`. -- **Reset** видаляє з `DREAMS.md` лише позначені backfill diary entries. +- **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному workspace, запускає grounded REM diary pass і записує оборотні backfill-записи в `DREAMS.md`. +- **Reset** видаляє з `DREAMS.md` лише ці позначені backfill diary entries. - **Clear Grounded** видаляє лише підготовлені grounded-only short-term entries, що походять з історичного replay і ще не накопичили live recall або daily support. -Чого вони самі по собі **не** роблять: +Чого вони **не** роблять самі по собі: - вони не редагують `MEMORY.md` - вони не запускають повні міграції doctor -- вони не готують автоматично grounded candidates у live short-term promotion store, якщо ви явно спочатку не запустите staged CLI path +- вони не готують grounded candidates автоматично в live short-term promotion store, якщо ви явно спершу не запустите staged CLI path -Якщо ви хочете, щоб grounded historical replay впливав на звичайну deep promotion lane, натомість використовуйте CLI flow: +Якщо ви хочете, щоб grounded historical replay впливав на звичайний deep promotion lane, натомість використовуйте CLI flow: ```bash openclaw memory rem-backfill --path ./memory --stage-short-term @@ -162,22 +163,22 @@ openclaw memory rem-backfill --path ./memory --stage-short-term Це готує grounded durable candidates у short-term dreaming store, залишаючи `DREAMS.md` поверхнею для перегляду. -## Детальна поведінка та обґрунтування +## Докладна поведінка й обґрунтування - + Якщо це git checkout і doctor працює інтерактивно, він пропонує оновитися (fetch/rebase/build) перед запуском doctor. - Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction` без channel-specific override), doctor нормалізує їх до поточної схеми. + Якщо конфігурація містить застарілі форми значень (наприклад `messages.ackReaction` без channel-specific override), doctor нормалізує їх у поточну схему. Це включає застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — `talk.provider` + `talk.providers.`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у provider map. - Doctor також попереджає, коли `plugins.allow` не порожній і політика інструментів використовує - wildcard або записи інструментів, що належать Plugin. `tools.allow: ["*"]` збігається лише з інструментами - з plugins, які фактично завантажуються; він не обходить ексклюзивний allowlist Plugin. + Doctor також попереджає, коли `plugins.allow` не порожній, а політика інструментів використовує + wildcard або записи інструментів, що належать Plugin. `tools.allow: ["*"]` відповідає лише інструментам + з plugins, які справді завантажуються; це не обходить ексклюзивний allowlist Plugin. Doctor записує `plugins.bundledDiscovery: "compat"` для мігрованих - застарілих allowlist configs, щоб зберегти наявну поведінку bundled provider, а + застарілих конфігурацій allowlist, щоб зберегти наявну поведінку bundled provider, а потім вказує на суворіше налаштування `"allowlist"`. @@ -190,7 +191,7 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - Покаже застосовану міграцію. - Перепише `~/.openclaw/openclaw.json` з оновленою схемою. - Gateway також автоматично запускає міграції doctor під час старту, коли виявляє застарілий формат конфігурації, тож застарілі конфігурації відновлюються без ручного втручання. Міграції сховища Cron job обробляються `openclaw doctor --fix`. + Gateway також автоматично запускає міграції doctor під час startup, коли виявляє застарілий формат конфігурації, тому застарілі конфігурації ремонтуються без ручного втручання. Міграції сховища Cron job обробляються через `openclaw doctor --fix`. Поточні міграції: @@ -199,9 +200,9 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit` - `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns` - `channels.telegram.requireMention` → `channels.telegram.groups."*".requireMention` - - конфігурації налаштованих каналів без видимої політики відповіді → `messages.groupChat.visibleReplies: "message_tool"` + - конфігурації налаштованих каналів без видимої політики відповідей → `messages.groupChat.visibleReplies: "message_tool"` - `routing.queue` → `messages.queue` - - `routing.bindings` → верхньорівневий `bindings` + - `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.` - `routing.agentToAgent` → `tools.agentToAgent` @@ -217,93 +218,93 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - `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 може зберегти наявну відповідну іменовану/типову ціль) + - Для каналів з іменованими `accounts`, але із залишковими верхньорівневими значеннями каналу для одного облікового запису, перемістіть ці значення в межах облікового запису до підвищеного облікового запису, вибраного для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну іменовану/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` - - видалити `agents.defaults.llm`; використовуйте `models.providers..timeoutSeconds` для таймаутів повільних провайдерів/моделей + - вилучіть `agents.defaults.llm`; використовуйте `models.providers..timeoutSeconds` для тайм-аутів повільних провайдерів/моделей - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` - - видалити `browser.relayBindHost` (застаріле налаштування ретранслятора extension) - - застаріле `models.providers.*.api: "openai"` → `"openai-completions"` (запуск Gateway також пропускає провайдерів, у яких `api` встановлено на майбутнє або невідоме значення enum, замість завершення з помилкою) + - вилучіть `browser.relayBindHost` (застаріле налаштування ретранслятора розширення) + - застаріле `models.providers.*.api: "openai"` → `"openai-completions"` (запуск Gateway також пропускає провайдерів, чий `api` встановлено на майбутнє або невідоме значення enum, замість закритої відмови) - Попередження doctor також містять поради щодо типового облікового запису для каналів із кількома обліковими записами: + Попередження doctor також містять поради щодо стандартного облікового запису для багатооблікових каналів: - - Якщо налаштовано два або більше записи `channels..accounts` без `channels..defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний обліковий запис. - - Якщо `channels..defaultAccount` встановлено на невідомий ID облікового запису, doctor попереджає і перелічує налаштовані ID облікових записів. + - Якщо налаштовано два або більше записів `channels..accounts` без `channels..defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний обліковий запис. + - Якщо `channels..defaultAccount` встановлено на невідомий ID облікового запису, doctor попереджає та перелічує налаштовані ID облікових записів. - Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`, це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`. Це може примусово спрямувати моделі до неправильного API або обнулити витрати. Doctor попереджає, щоб ви могли видалити перевизначення й відновити маршрутизацію API та витрати для кожної моделі. + Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`, це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`. Це може примусово спрямувати моделі до неправильного API або обнулити витрати. Doctor попереджає, щоб ви могли вилучити перевизначення та відновити маршрутизацію API й витрати для кожної моделі. - Якщо ваша конфігурація браузера все ще вказує на видалений шлях Chrome extension, doctor нормалізує її до поточної моделі підключення host-local Chrome MCP: + Якщо ваша конфігурація браузера все ще вказує на вилучений шлях розширення Chrome, doctor нормалізує її до поточної моделі підключення Chrome MCP на локальному хості: - `browser.profiles.*.driver: "extension"` стає `"existing-session"` - - `browser.relayBindHost` видаляється + - `browser.relayBindHost` вилучається - Doctor також перевіряє шлях host-local Chrome MCP, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`: + Doctor також перевіряє шлях Chrome MCP на локальному хості, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`: - - перевіряє, чи Google Chrome встановлено на тому самому хості для типових профілів автоматичного підключення - - перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144 - - нагадує ввімкнути віддалене налагодження на сторінці перевірки браузера (наприклад, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`) + - перевіряє, чи встановлено Google Chrome на тому самому хості для стандартних профілів автоматичного підключення + - перевіряє виявлену версію Chrome і попереджає, коли вона нижча за Chrome 144 + - нагадує ввімкнути віддалене налагодження на сторінці перевірки браузера (наприклад `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`) - Doctor не може ввімкнути налаштування на стороні Chrome за вас. Host-local Chrome MCP усе ще потребує: + Doctor не може ввімкнути налаштування на боці Chrome за вас. Chrome MCP на локальному хості все ще потребує: - - браузера на основі Chromium 144+ на хості gateway/node - - локально запущеного браузера - - увімкненого віддаленого налагодження в цьому браузері - - підтвердження першого запиту згоди на підключення в браузері + - браузер на основі Chromium 144+ на хості gateway/node + - браузер, запущений локально + - віддалене налагодження, увімкнене в цьому браузері + - схвалення першого запиту згоди на підключення в браузері - Готовність тут стосується лише локальних передумов підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, усе ще потребують керованого браузера або raw CDP-профілю. + Готовність тут стосується лише передумов локального підключення. Existing-session зберігає поточні обмеження маршруту Chrome MCP; розширені маршрути на кшталт `responsebody`, експорту PDF, перехоплення завантажень і пакетних дій усе ще потребують керованого браузера або raw CDP profile. - Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших headless-потоків. Вони й надалі використовують raw CDP. + Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших headless потоків. Вони й надалі використовують raw CDP. - Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє endpoint авторизації OpenAI, щоб переконатися, що локальний стек Node/OpenSSL TLS може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат), doctor виводить поради з виправлення для конкретної платформи. На macOS з Homebrew Node виправленням зазвичай є `brew postinstall ca-certificates`. З `--deep` перевірка виконується, навіть якщо gateway справний. + Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє endpoint авторизації OpenAI, щоб переконатися, що локальний стек Node/OpenSSL TLS може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат), doctor виводить поради з виправлення для конкретної платформи. На macOS із Homebrew Node виправлення зазвичай таке: `brew postinstall ca-certificates`. З `--deep` перевірка виконується навіть тоді, коли gateway справний. - Якщо раніше ви додали застарілі налаштування транспорту OpenAI у `models.providers.openai-codex`, вони можуть затіняти вбудований шлях провайдера Codex OAuth, який новіші випуски використовують автоматично. Doctor попереджає, коли бачить ці старі налаштування транспорту разом із Codex OAuth, щоб ви могли видалити або переписати застаріле перевизначення транспорту й повернути вбудовану поведінку маршрутизації/резервування. Користувацькі проксі та перевизначення лише заголовків усе ще підтримуються й не спричиняють цього попередження. + Якщо раніше ви додали застарілі налаштування транспорту OpenAI у `models.providers.openai-codex`, вони можуть затіняти вбудований шлях провайдера Codex OAuth, який новіші випуски використовують автоматично. Doctor попереджає, коли бачить ці старі налаштування транспорту разом із Codex OAuth, щоб ви могли вилучити або переписати застаріле перевизначення транспорту та повернути вбудовану поведінку маршрутизації/резервування. Користувацькі проксі та перевизначення лише заголовків усе ще підтримуються й не викликають цього попередження. - - Коли ввімкнено вбудований Plugin Codex, doctor також перевіряє, чи посилання на основну модель `openai-codex/*` усе ще розв'язуються через типовий runner PI. Така комбінація коректна, коли ви хочете використовувати автентифікацію Codex OAuth/підписки через PI, але її легко сплутати з нативним app-server harness Codex. Doctor попереджає і вказує на явну форму app-server: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`. + + Коли ввімкнено вбудований Codex plugin, doctor також перевіряє, чи primary model refs `openai-codex/*` усе ще розв’язуються через стандартний PI runner. Ця комбінація коректна, коли вам потрібна автентифікація Codex OAuth/підписки через PI, але її легко сплутати з нативним app-server harness Codex. Doctor попереджає та вказує на явну форму app-server: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`. - Doctor не виправляє це автоматично, оскільки обидва маршрути є допустимими: + Doctor не виправляє це автоматично, тому що обидва маршрути коректні: - `openai-codex/*` + PI означає "використовувати автентифікацію Codex OAuth/підписки через звичайний runner OpenClaw." - - `openai/*` + `agentRuntime.id: "codex"` означає "виконати вбудований turn через нативний app-server Codex." - - `/codex ...` означає "керувати або прив'язати нативну розмову Codex із чату." - - `/acp ...` або `runtime: "acp"` означає "використовувати зовнішній адаптер ACP/acpx." + - `openai/*` + `agentRuntime.id: "codex"` означає "виконати вбудований turn через нативний Codex app-server." + - `/codex ...` означає "керувати або прив’язати нативну розмову Codex із чату." + - `/acp ...` або `runtime: "acp"` означає "використовувати зовнішній ACP/acpx adapter." - Якщо з'являється попередження, виберіть потрібний маршрут і вручну відредагуйте конфігурацію. Залиште попередження без змін, якщо PI Codex OAuth є навмисним. + Якщо з’являється попередження, виберіть маршрут, який ви мали на увазі, і відредагуйте конфігурацію вручну. Залиште попередження без змін, коли PI Codex OAuth є навмисним. - - Doctor також сканує сховище активних сесій на наявність застарілого автоматично створеного стану маршруту після того, як ви перемістили налаштовану типову/резервну модель або runtime з маршруту, що належить plugin, наприклад Codex. + + Doctor також сканує сховище активних сеансів на застарілий автоматично створений стан маршрутів після того, як ви перемістили налаштовану стандартну/резервну модель або runtime з маршруту, що належить plugin, як-от Codex. - `openclaw doctor --fix` може очистити автоматично створений застарілий стан, як-от закріплення моделей `modelOverrideSource: "auto"`, метадані runtime-моделі, закріплені ID harness, прив'язки CLI-сесій і автоматичні перевизначення auth-profile, коли їхній власний маршрут більше не налаштований. Явні користувацькі або застарілі вибори моделі сесії повідомляються для ручного перегляду й залишаються без змін; перемкніть їх за допомогою `/model ...`, `/new` або скиньте сесію, коли цей маршрут більше не потрібен. + `openclaw doctor --fix` може очистити автоматично створений застарілий стан, як-от закріплення моделей `modelOverrideSource: "auto"`, runtime metadata моделей, закріплені harness ids, прив’язки CLI-сеансів і автоматичні перевизначення auth-profile, коли їхній маршрут-власник більше не налаштовано. Явні користувацькі або застарілі вибори моделей сеансу повідомляються для ручної перевірки й залишаються без змін; перемкніть їх за допомогою `/model ...`, `/new` або скиньте сеанс, коли цей маршрут більше не призначений. - - Doctor може мігрувати старіші розмітки на диску до поточної структури: + + Doctor може мігрувати старіші дискові структури в поточну структуру: - - Сховище сесій + transcripts: + - Сховище сеансів + транскрипти: - з `~/.openclaw/sessions/` до `~/.openclaw/agents//sessions/` - Каталог агента: - з `~/.openclaw/agent/` до `~/.openclaw/agents//agent/` - Стан автентифікації WhatsApp (Baileys): - - із застарілого `~/.openclaw/credentials/*.json` (крім `oauth.json`) - - до `~/.openclaw/credentials/whatsapp//...` (типовий ID облікового запису: `default`) + - із застарілих `~/.openclaw/credentials/*.json` (крім `oauth.json`) + - до `~/.openclaw/credentials/whatsapp//...` (ID стандартного облікового запису: `default`) - Ці міграції виконуються за принципом найкращої спроби та є ідемпотентними; doctor виводитиме попередження, коли залишатиме будь-які застарілі папки як резервні копії. Gateway/CLI також автоматично мігрує застарілі сесії + каталог агента під час запуску, щоб історія/автентифікація/моделі потрапили в шлях для кожного агента без ручного запуску doctor. Нормалізація talk provider/provider-map тепер порівнює за структурною рівністю, тому відмінності лише в порядку ключів більше не спричиняють повторних no-op змін `doctor --fix`. + Ці міграції виконуються за принципом найкращої спроби й є ідемпотентними; doctor видаватиме попередження, коли залишає будь-які застарілі папки як резервні копії. Gateway/CLI також автоматично мігрує застарілі сеанси + каталог агента під час запуску, щоб історія/автентифікація/моделі потрапляли в шлях для кожного агента без ручного запуску doctor. Нормалізація провайдера talk/карти провайдерів тепер порівнює за структурною рівністю, тому відмінності лише в порядку ключів більше не спричиняють повторні noop-зміни `doctor --fix`. - Doctor сканує всі встановлені маніфести plugin на наявність застарілих верхньорівневих ключів можливостей (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Якщо їх знайдено, він пропонує перемістити їх в об'єкт `contracts` і переписати файл маніфесту на місці. Ця міграція ідемпотентна; якщо ключ `contracts` уже має ті самі значення, застарілий ключ видаляється без дублювання даних. + Doctor сканує всі встановлені маніфести plugin на застарілі верхньорівневі ключі можливостей (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Коли їх знайдено, він пропонує перемістити їх до об’єкта `contracts` і переписати файл маніфесту на місці. Ця міграція ідемпотентна; якщо ключ `contracts` уже має ті самі значення, застарілий ключ вилучається без дублювання даних. - Doctor також перевіряє сховище завдань cron (`~/.openclaw/cron/jobs.json` за замовчуванням або `cron.store`, коли перевизначено) на старі форми завдань, які scheduler усе ще приймає для сумісності. + Doctor також перевіряє сховище cron-завдань (`~/.openclaw/cron/jobs.json` за замовчуванням або `cron.store`, якщо перевизначено) на старі форми завдань, які scheduler усе ще приймає для сумісності. Поточні очищення cron включають: @@ -311,201 +312,201 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - `schedule.cron` → `schedule.expr` - верхньорівневі поля payload (`message`, `model`, `thinking`, ...) → `payload` - верхньорівневі поля delivery (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` - - псевдоніми delivery `provider` у payload → явний `delivery.channel` - - прості застарілі fallback-завдання webhook `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook` + - delivery aliases `provider` у payload → явне `delivery.channel` + - прості застарілі fallback-завдання webhook `notify: true` → явне `delivery.mode="webhook"` з `delivery.to=cron.webhook` - Doctor автоматично мігрує завдання `notify: true` лише тоді, коли може зробити це без зміни поведінки. Якщо завдання поєднує застарілий fallback notify з наявним режимом delivery, що не є webhook, doctor попереджає і залишає це завдання для ручного перегляду. + Doctor автоматично мігрує завдання `notify: true` лише тоді, коли може зробити це без зміни поведінки. Якщо завдання поєднує застарілий notify fallback з наявним режимом delivery, що не є webhook, doctor попереджає та залишає це завдання для ручної перевірки. - У Linux засіб діагностики також попереджає, коли crontab користувача все ще викликає застарілий `~/.openclaw/bin/ensure-whatsapp.sh`. Цей локальний для хоста скрипт не підтримується поточним OpenClaw і може записувати хибні повідомлення `Gateway inactive` до `~/.openclaw/logs/whatsapp-health.log`, коли cron не може дістатися до користувацької шини systemd. Видаліть застарілий запис crontab за допомогою `crontab -e`; для поточних перевірок стану використовуйте `openclaw channels status --probe`, `openclaw doctor` і `openclaw gateway status`. + У Linux doctor також попереджає, коли crontab користувача все ще викликає застарілий `~/.openclaw/bin/ensure-whatsapp.sh`. Цей локальний для хоста скрипт не підтримується поточною версією OpenClaw і може записувати хибні повідомлення `Gateway inactive` у `~/.openclaw/logs/whatsapp-health.log`, коли cron не може підключитися до користувацької шини systemd. Видаліть застарілий запис crontab за допомогою `crontab -e`; для поточних перевірок стану використовуйте `openclaw channels status --probe`, `openclaw doctor` і `openclaw gateway status`. - - Засіб діагностики сканує кожен каталог сеансу агента на наявність застарілих файлів блокування запису — файлів, що залишилися після аварійного завершення сеансу. Для кожного знайденого файлу блокування він повідомляє: шлях, PID, чи PID досі активний, вік блокування та чи вважається воно застарілим (мертвий PID або старше за 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше друкує примітку й указує повторно запустити з `--fix`. + + Doctor сканує кожен каталог сеансів агента на наявність застарілих файлів блокування запису — файлів, що залишилися після аварійного завершення сеансу. Для кожного знайденого файлу блокування він повідомляє: шлях, PID, чи PID досі активний, вік блокування та чи вважається воно застарілим (мертвий PID або старіше за 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше друкує примітку й вказує повторно запустити з `--fix`. - - Засіб діагностики сканує JSONL-файли сеансів агентів на дубльовану форму гілки, створену помилкою переписування транскрипту prompt від 2026.4.24: покинутий хід користувача з внутрішнім runtime-контекстом OpenClaw плюс активний сусідній елемент із тим самим видимим prompt користувача. У режимі `--fix` / `--repair` засіб діагностики створює резервну копію кожного ураженого файлу поруч з оригіналом і переписує транскрипт до активної гілки, щоб історія gateway і читачі пам'яті більше не бачили дубльованих ходів. + + Doctor сканує JSONL-файли сеансів агента на дубльовану форму гілки, створену помилкою переписування стенограми prompt від 2026.4.24: покинутий хід користувача з внутрішнім runtime-контекстом OpenClaw плюс активний споріднений елемент із тим самим видимим prompt користувача. У режимі `--fix` / `--repair` doctor створює резервну копію кожного зачепленого файлу поряд з оригіналом і переписує стенограму на активну гілку, щоб історія gateway і читачі пам’яті більше не бачили дубльованих ходів. - Каталог стану — це операційний стовбур системи. Якщо він зникне, ви втратите сеанси, облікові дані, журнали та конфігурацію (якщо не маєте резервних копій деінде). + Каталог стану — це операційний стовбур системи. Якщо він зникне, ви втратите сеанси, облікові дані, журнали й конфігурацію (якщо у вас немає резервних копій в іншому місці). - Засіб діагностики перевіряє: + Doctor перевіряє: - **Відсутній каталог стану**: попереджає про катастрофічну втрату стану, пропонує повторно створити каталог і нагадує, що не може відновити відсутні дані. - **Дозволи каталогу стану**: перевіряє можливість запису; пропонує виправити дозволи (і виводить підказку `chown`, коли виявлено невідповідність власника/групи). - - **Синхронізований із хмарою каталог стану macOS**: попереджає, коли стан розташовано під iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або `~/Library/CloudStorage/...`, оскільки шляхи з синхронізацією можуть спричиняти повільніше введення-виведення та конфлікти блокування/синхронізації. - - **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розташовано на джерелі монтування `mmcblk*`, оскільки випадкове введення-виведення на SD або eMMC може бути повільнішим і швидше зношувати носій під час записів сеансів і облікових даних. - - **Відсутні каталоги сеансів**: `sessions/` і каталог сховища сеансів потрібні для збереження історії та уникнення збоїв `ENOENT`. - - **Невідповідність транскрипту**: попереджає, коли в останніх записах сеансів відсутні файли транскриптів. - - **Основний сеанс "1-line JSONL"**: позначає, коли основний транскрипт має лише один рядок (історія не накопичується). - - **Кілька каталогів стану**: попереджає, коли кілька папок `~/.openclaw` існують у різних домашніх каталогах або коли `OPENCLAW_STATE_DIR` указує в інше місце (історія може розділитися між інсталяціями). - - **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, засіб діагностики нагадує запускати його на віддаленому хості (стан зберігається там). - - **Дозволи файлу конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` доступний для читання групі/усім, і пропонує посилити дозволи до `600`. + - **Синхронізований із хмарою каталог стану macOS**: попереджає, коли стан розташовано під iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або `~/Library/CloudStorage/...`, оскільки шляхи з синхронізацією можуть спричиняти повільніший I/O та перегони блокування/синхронізації. + - **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розташовано на джерелі монтування `mmcblk*`, оскільки випадковий I/O на SD або eMMC може бути повільнішим і швидше зношувати носій під час записів сеансів і облікових даних. + - **Відсутні каталоги сеансів**: `sessions/` і каталог сховища сеансів потрібні для збереження історії та уникнення аварій `ENOENT`. + - **Невідповідність стенограми**: попереджає, коли в нещодавніх записах сеансів відсутні файли стенограм. + - **Головний сеанс "1-line JSONL"**: позначає випадки, коли головна стенограма має лише один рядок (історія не накопичується). + - **Кілька каталогів стану**: попереджає, коли кілька папок `~/.openclaw` існують у різних домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (історія може розділятися між встановленнями). + - **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, doctor нагадує запустити його на віддаленому хості (стан живе там). + - **Дозволи файлу конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` доступний для читання групі/усім, і пропонує посилити до `600`. - - Засіб діагностики перевіряє OAuth-профілі в сховищі автентифікації, попереджає, коли термін дії токенів наближається до завершення або вже минув, і може оновити їх, коли це безпечно. Якщо OAuth/токен-профіль Anthropic застарів, він пропонує API-ключ Anthropic або шлях setup-token Anthropic. Запити на оновлення з'являються лише під час інтерактивного запуску (TTY); `--non-interactive` пропускає спроби оновлення. + + Doctor перевіряє профілі OAuth у сховищі авторизації, попереджає, коли строк дії токенів наближається до завершення або вже завершився, і може оновити їх, коли це безпечно. Якщо профіль OAuth/токена Anthropic застарів, він пропонує API-ключ Anthropic або шлях setup-token Anthropic. Запити на оновлення з’являються лише під час інтерактивного запуску (TTY); `--non-interactive` пропускає спроби оновлення. - Коли оновлення OAuth остаточно не вдається (наприклад, `refresh_token_reused`, `invalid_grant` або provider повідомляє, що потрібно ввійти знову), засіб діагностики повідомляє, що потрібна повторна автентифікація, і друкує точну команду `openclaw models auth login --provider ...`, яку треба виконати. + Коли оновлення OAuth остаточно не вдається (наприклад, `refresh_token_reused`, `invalid_grant` або провайдер просить увійти знову), doctor повідомляє, що потрібна повторна авторизація, і друкує точну команду `openclaw models auth login --provider ...`, яку слід виконати. - Засіб діагностики також повідомляє про профілі автентифікації, які тимчасово непридатні через: + Doctor також повідомляє про профілі авторизації, які тимчасово непридатні через: - - короткі періоди очікування (обмеження швидкості/тайм-аути/помилки автентифікації) + - короткі періоди охолодження (обмеження частоти/тайм-аути/помилки авторизації) - довші вимкнення (помилки білінгу/кредитів) - - Якщо `hooks.gmail.model` задано, засіб діагностики перевіряє посилання на модель за каталогом і allowlist та попереджає, коли воно не розв'язується або заборонене. + + Якщо задано `hooks.gmail.model`, doctor перевіряє посилання на модель за каталогом і списком дозволених та попереджає, коли його неможливо розв’язати або воно заборонене. - Коли sandboxing увімкнено, засіб діагностики перевіряє Docker-образи й пропонує зібрати або перемкнутися на застарілі назви, якщо поточний образ відсутній. + Коли sandboxing увімкнено, doctor перевіряє образи Docker і пропонує зібрати або перейти на застарілі назви, якщо поточний образ відсутній. - Засіб діагностики видаляє застарілий staging-стан залежностей plugin, згенерований OpenClaw, у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Це охоплює застарілі згенеровані корені залежностей, старі каталоги етапу встановлення, локальне для пакета сміття від попереднього коду відновлення залежностей bundled-plugin, а також осиротілі або відновлені керовані npm-копії bundled `@openclaw/*` plugins, які можуть затіняти поточний bundled manifest. + Doctor видаляє застарілий, згенерований OpenClaw staging-стан залежностей plugin у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Це охоплює застарілі згенеровані корені залежностей, старі каталоги етапу встановлення, локальні для пакета залишки від попереднього коду відновлення залежностей вбудованого plugin, а також осиротілі або відновлені керовані npm-копії вбудованих plugins `@openclaw/*`, які можуть затіняти поточний вбудований маніфест. - Засіб діагностики також може перевстановити відсутні завантажувані plugins, коли конфігурація посилається на них, але локальний реєстр plugin не може їх знайти. Приклади включають матеріальні `plugins.entries`, налаштовані параметри channel/provider/search і налаштовані середовища виконання агентів. Під час оновлень пакета засіб діагностики уникає запуску package-manager-відновлення plugin, поки core-пакет замінюється; запустіть `openclaw doctor --fix` знову після оновлення, якщо налаштований plugin усе ще потребує відновлення. Запуск Gateway і перезавантаження конфігурації не запускають package managers; встановлення plugin залишаються явною роботою doctor/install/update. + Doctor також може перевстановити відсутні завантажувані plugins, коли конфігурація посилається на них, але локальний реєстр plugin не може їх знайти. Приклади включають матеріальні `plugins.entries`, налаштовані параметри каналів/провайдерів/пошуку та налаштовані runtime агента. Під час оновлень пакета doctor уникає запуску відновлення plugin через менеджер пакетів, доки основний пакет замінюється; запустіть `openclaw doctor --fix` ще раз після оновлення, якщо налаштований plugin усе ще потребує відновлення. Запуск Gateway і перезавантаження конфігурації не запускають менеджери пакетів; встановлення plugins лишаються явною роботою doctor/install/update. - Засіб діагностики виявляє застарілі сервіси gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити сервіс OpenClaw із поточним портом gateway. Він також може сканувати додаткові gateway-подібні сервіси й друкувати підказки з очищення. Gateway-сервіси OpenClaw з іменами профілів вважаються повноцінними й не позначаються як "додаткові". + Doctor виявляє застарілі сервіси gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити сервіс OpenClaw, використовуючи поточний порт gateway. Він також може просканувати додаткові gateway-подібні сервіси й надрукувати підказки з очищення. Сервіси gateway OpenClaw з іменами профілів вважаються повноцінними й не позначаються як "додаткові." - У Linux, якщо user-level gateway-сервіс відсутній, але system-level gateway-сервіс OpenClaw існує, засіб діагностики не встановлює автоматично другий user-level сервіс. Перевірте за допомогою `openclaw gateway status --deep` або `openclaw doctor --deep`, а потім видаліть дублікат або встановіть `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли життєвим циклом gateway керує системний supervisor. + У Linux, якщо сервіс gateway рівня користувача відсутній, але існує системний сервіс gateway OpenClaw, doctor не встановлює автоматично другий сервіс рівня користувача. Перевірте за допомогою `openclaw gateway status --deep` або `openclaw doctor --deep`, потім видаліть дублікат або задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли системний супервізор керує життєвим циклом gateway. - Коли обліковий запис channel Matrix має pending або actionable застарілу міграцію стану, засіб діагностики (у режимі `--fix` / `--repair`) створює знімок перед міграцією, а потім виконує best-effort кроки міграції: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки записуються до журналу, а запуск триває. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається. + Коли обліковий запис каналу Matrix має очікувану або придатну до дії міграцію застарілого стану, doctor (у режимі `--fix` / `--repair`) створює знімок перед міграцією, а потім виконує кроки міграції в режимі best-effort: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки журналюються, а запуск продовжується. У режимі лише для читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається. - - Засіб діагностики тепер перевіряє стан сполучення пристроїв як частину звичайного проходу перевірки стану. + + Doctor тепер перевіряє стан сполучення пристроїв як частину звичайного проходу перевірки стану. Що він повідомляє: - - pending запити першого сполучення - - pending підвищення ролі для вже сполучених пристроїв - - pending підвищення scope для вже сполучених пристроїв - - відновлення невідповідності відкритого ключа, коли ідентифікатор пристрою все ще збігається, але ідентичність пристрою більше не збігається із затвердженим записом - - сполучені записи без активного токена для затвердженої ролі - - сполучені токени, чиї scopes відхиляються від затвердженої базової лінії сполучення - - локальні кешовані записи device-token для поточної машини, що передують ротації токена на боці gateway або містять застарілі метадані scope + - очікувані запити першого сполучення + - очікувані підвищення ролі для вже сполучених пристроїв + - очікувані підвищення scope для вже сполучених пристроїв + - відновлення невідповідності відкритого ключа, коли id пристрою все ще збігається, але ідентичність пристрою більше не відповідає затвердженому запису + - сполучені записи, у яких відсутній активний токен для затвердженої ролі + - сполучені токени, чиї scopes відхилилися за межі затвердженого базового рівня сполучення + - локальні кешовані записи токена пристрою для поточної машини, які передують ротації токена на боці gateway або містять застарілі метадані scope - Засіб діагностики не затверджує запити сполучення автоматично й не обертає токени пристроїв автоматично. Натомість він друкує точні наступні кроки: + Doctor не затверджує автоматично запити сполучення й не ротатує автоматично токени пристроїв. Натомість він друкує точні наступні кроки: - - перегляньте pending запити за допомогою `openclaw devices list` - - затвердьте точний запит за допомогою `openclaw devices approve ` - - оберніть свіжий токен за допомогою `openclaw devices rotate --device --role ` - - видаліть і повторно затвердьте застарілий запис за допомогою `openclaw devices remove ` + - переглянути очікувані запити за допомогою `openclaw devices list` + - затвердити точний запит за допомогою `openclaw devices approve ` + - ротувати свіжий токен за допомогою `openclaw devices rotate --device --role ` + - видалити й повторно затвердити застарілий запис за допомогою `openclaw devices remove ` - Це закриває поширену прогалину "already paired but still getting pairing required": засіб діагностики тепер відрізняє перше сполучення від pending підвищень ролі/scope і від дрейфу застарілого токена/ідентичності пристрою. + Це закриває типову прогалину "already paired but still getting pairing required": doctor тепер відрізняє перше сполучення від очікуваних підвищень ролі/scope і від дрейфу застарілого токена/ідентичності пристрою. - Засіб діагностики видає попередження, коли provider відкритий для DM без allowlist або коли політику налаштовано небезпечним способом. + Doctor видає попередження, коли провайдер відкритий для DM без списку дозволених або коли політика налаштована небезпечним способом. - Якщо запущено як user service systemd, засіб діагностики забезпечує ввімкнення lingering, щоб gateway залишався активним після виходу з системи. + Якщо запущено як користувацький сервіс systemd, doctor гарантує, що lingering увімкнено, щоб gateway залишався активним після виходу з системи. - - Засіб діагностики друкує підсумок стану workspace для агента за замовчуванням: + + Doctor друкує підсумок стану робочого простору для стандартного агента: - - **Стан Skills**: рахує eligible, missing-requirements і allowlist-blocked skills. - - **Застарілі каталоги workspace**: попереджає, коли `~/openclaw` або інші застарілі каталоги workspace існують поряд із поточним workspace. - - **Стан Plugin**: рахує enabled/disabled/errored plugins; перелічує ідентифікатори plugin для будь-яких помилок; повідомляє можливості bundle plugin. + - **Стан Skills**: рахує придатні, з відсутніми вимогами та заблоковані списком дозволених skills. + - **Застарілі каталоги робочого простору**: попереджає, коли `~/openclaw` або інші застарілі каталоги робочого простору існують поряд із поточним робочим простором. + - **Стан Plugin**: рахує увімкнені/вимкнені/з помилками plugins; перелічує ID plugin для будь-яких помилок; повідомляє можливості plugin bundle. - **Попередження сумісності Plugin**: позначає plugins, які мають проблеми сумісності з поточним runtime. - **Діагностика Plugin**: показує будь-які попередження або помилки часу завантаження, видані реєстром plugin. - Засіб діагностики перевіряє, чи bootstrap-файли workspace (наприклад, `AGENTS.md`, `CLAUDE.md` або інші інжектовані файли контексту) близькі до налаштованого ліміту символів або перевищують його. Він повідомляє для кожного файлу сирі та інжектовані кількості символів, відсоток усічення, причину усічення (`max/file` або `max/total`) і загальну кількість інжектованих символів як частку загального бюджету. Коли файли усічено або вони близькі до ліміту, засіб діагностики друкує поради з налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`. + Doctor перевіряє, чи bootstrap-файли робочого простору (наприклад `AGENTS.md`, `CLAUDE.md` або інші інжектовані файли контексту) наближаються до налаштованого бюджету символів або перевищують його. Він повідомляє для кожного файлу необроблену кількість символів проти інжектованої, відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість інжектованих символів як частку від загального бюджету. Коли файли обрізано або вони близькі до ліміту, doctor друкує поради з налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`. - Коли `openclaw doctor --fix` видаляє відсутній channel plugin, він також видаляє висячі channel-scoped конфігурації, які посилалися на цей plugin: записи `channels.`, цілі Heartbeat, що називали channel, і перевизначення `agents.*.models["/*"]`. Це запобігає циклам завантаження Gateway, коли runtime channel зник, але конфігурація все ще просить gateway прив'язатися до нього. + Коли `openclaw doctor --fix` видаляє відсутній channel plugin, він також видаляє завислу конфігурацію в області каналу, яка посилалася на цей plugin: записи `channels.`, цілі heartbeat, що називали канал, і перевизначення `agents.*.models["/*"]`. Це запобігає циклам завантаження Gateway, коли runtime каналу зник, але конфігурація все ще просить gateway прив’язатися до нього. - Засіб діагностики перевіряє, чи встановлено автодоповнення tab для поточного shell (zsh, bash, fish або PowerShell): + Doctor перевіряє, чи встановлено автодоповнення табуляцією для поточного shell (zsh, bash, fish або PowerShell): - - Якщо профіль shell використовує повільний динамічний шаблон completion (`source <(openclaw completion ...)`), засіб діагностики оновлює його до швидшого варіанта з кешованим файлом. - - Якщо completion налаштовано в профілі, але файл кешу відсутній, засіб діагностики автоматично регенерує кеш. - - Якщо completion взагалі не налаштовано, засіб діагностики пропонує встановити його (лише інтерактивний режим; пропускається з `--non-interactive`). + - Якщо профіль shell використовує повільний динамічний шаблон доповнення (`source <(openclaw completion ...)`), doctor оновлює його до швидшого варіанта з кешованим файлом. + - Якщо доповнення налаштоване в профілі, але файл кешу відсутній, doctor автоматично регенерує кеш. + - Якщо доповнення взагалі не налаштоване, doctor пропонує встановити його (лише інтерактивний режим; пропускається з `--non-interactive`). Запустіть `openclaw completion --write-state`, щоб регенерувати кеш вручну. - - Засіб діагностики перевіряє готовність автентифікації локального токена gateway. + + Doctor перевіряє готовність авторизації токена локального gateway. - - Якщо режим токена потребує токен, а джерела токена не існує, засіб діагностики пропонує згенерувати його. - - Якщо `gateway.auth.token` керується SecretRef, але недоступний, засіб діагностики попереджає й не перезаписує його відкритим текстом. - - `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли не налаштовано token SecretRef. + - Якщо режим токена потребує токен і не існує жодного джерела токена, doctor пропонує згенерувати його. + - Якщо `gateway.auth.token` керується SecretRef, але недоступний, doctor попереджає й не перезаписує його відкритим текстом. + - `openclaw doctor --generate-gateway-token` примусово генерує токен лише коли не налаштовано SecretRef токена. - - Деякі потоки відновлення потребують перевірки налаштованих облікових даних без послаблення fail-fast поведінки runtime. + + Деякі потоки відновлення мають перевіряти налаштовані облікові дані, не послаблюючи runtime-поведінку fail-fast. - - `openclaw doctor --fix` тепер використовує ту саму модель read-only зведення SecretRef, що й команди сімейства status, для цільового ремонту конфігурації. - - Приклад: ремонт Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використовувати налаштовані облікові дані бота, коли вони доступні. - - Якщо токен бота Telegram налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає автоматичне розв'язання замість збою або помилкового повідомлення, що токен відсутній. + - `openclaw doctor --fix` тепер використовує ту саму модель підсумку SecretRef лише для читання, що й команди родини status, для цільових виправлень конфігурації. + - Приклад: виправлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використати налаштовані облікові дані бота, коли вони доступні. + - Якщо токен бота Telegram налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає автоматичне розв’язання замість аварійного завершення або помилкового повідомлення, що токен відсутній. - Команда doctor виконує перевірку стану й пропонує перезапустити Gateway, коли він виглядає несправним. + Doctor запускає перевірку стану й пропонує перезапустити Gateway, коли він виглядає несправним. - - Команда doctor перевіряє, чи налаштований постачальник embedding для пошуку в пам'яті готовий для агента за замовчуванням. Поведінка залежить від налаштованого бекенда й постачальника: + + Doctor перевіряє, чи налаштований провайдер embedding для пошуку пам’яті готовий для агента за замовчуванням. Поведінка залежить від налаштованого бекенда й провайдера: - - **Бекенд QMD**: перевіряє, чи бінарний файл `qmd` доступний і може запуститися. Якщо ні, виводить рекомендації з виправлення, включно з npm-пакетом і варіантом ручного шляху до бінарного файла. - - **Явний локальний постачальник**: перевіряє наявність локального файла моделі або розпізнаної віддаленої/завантажуваної URL-адреси моделі. Якщо відсутні, пропонує перейти на віддаленого постачальника. - - **Явний віддалений постачальник** (`openai`, `voyage` тощо): перевіряє, чи API-ключ присутній у середовищі або сховищі автентифікації. Виводить дієві підказки для виправлення, якщо його бракує. - - **Автоматичний постачальник**: спочатку перевіряє доступність локальної моделі, а потім пробує кожного віддаленого постачальника в порядку автоматичного вибору. + - **Бекенд QMD**: перевіряє, чи бінарний файл `qmd` доступний і може запуститися. Якщо ні, виводить підказки з виправлення, включно з npm-пакетом і варіантом ручного шляху до бінарного файла. + - **Явний локальний провайдер**: перевіряє наявність локального файла моделі або розпізнаної віддаленої URL-адреси моделі, яку можна завантажити. Якщо відсутня, пропонує перейти на віддаленого провайдера. + - **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, чи API-ключ присутній у середовищі або сховищі автентифікації. Виводить дієві підказки з виправлення, якщо ключ відсутній. + - **Автоматичний провайдер**: спершу перевіряє доступність локальної моделі, потім пробує кожного віддаленого провайдера в порядку автоматичного вибору. - Коли доступний кешований результат перевірки Gateway (Gateway був справним на момент перевірки), doctor зіставляє його результат із конфігурацією, видимою для CLI, і зазначає будь-яку розбіжність. Doctor не запускає новий embedding ping у стандартному шляху; використовуйте команду глибокого статусу пам'яті, коли потрібна жива перевірка постачальника. + Коли доступний кешований результат перевірки Gateway (Gateway був справним на момент перевірки), doctor зіставляє його результат із конфігурацією, видимою для CLI, і зазначає будь-яку розбіжність. Doctor не запускає новий ping embedding у стандартному шляху; використовуйте глибоку команду стану пам’яті, коли потрібна жива перевірка провайдера. Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding під час виконання. - - Якщо Gateway справний, doctor виконує перевірку стану каналу й повідомляє попередження із запропонованими виправленнями. + + Якщо Gateway справний, doctor запускає перевірку стану каналу й повідомляє попередження із запропонованими виправленнями. - - Doctor перевіряє встановлену конфігурацію супервізора (launchd/systemd/schtasks) на відсутні або застарілі стандартні значення (наприклад, залежності systemd від network-online і затримку перезапуску). Коли знаходить невідповідність, рекомендує оновлення й може перезаписати файл служби/завдання до поточних стандартних значень. + + Doctor перевіряє встановлену конфігурацію supervisor (launchd/systemd/schtasks) на відсутні або застарілі стандартні значення (наприклад, залежності systemd від network-online і затримку перезапуску). Коли він знаходить невідповідність, рекомендує оновлення й може перезаписати файл служби/завдання до поточних стандартних значень. Примітки: - - `openclaw doctor` запитує підтвердження перед перезаписом конфігурації супервізора. - - `openclaw doctor --yes` приймає стандартні запити на ремонт. + - `openclaw doctor` запитує підтвердження перед перезаписом конфігурації supervisor. + - `openclaw doctor --yes` приймає стандартні запити на виправлення. - `openclaw doctor --repair` застосовує рекомендовані виправлення без запитів. - - `openclaw doctor --repair --force` перезаписує користувацькі конфігурації супервізора. - - `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає doctor у режимі read-only для життєвого циклу служби Gateway. Він усе одно повідомляє стан служби й виконує ремонти, не пов'язані зі службою, але пропускає встановлення/запуск/перезапуск/bootstrap служби, перезапис конфігурації супервізора та очищення застарілих служб, бо цим життєвим циклом керує зовнішній супервізор. - - У Linux doctor не перезаписує метадані команди/entrypoint, поки відповідний systemd-модуль Gateway активний. Він також ігнорує неактивні додаткові gateway-подібні модулі, що не є застарілими, під час сканування дублікатів служб, щоб супутні файли служб не створювали зайвого шуму очищення. - - Якщо автентифікація токеном вимагає токен і `gateway.auth.token` керується SecretRef, встановлення/ремонт служби doctor перевіряє SecretRef, але не зберігає розв'язані plaintext-значення токена в метадані середовища служби супервізора. - - Doctor виявляє керовані `.env`/SecretRef-backed значення середовища служби, які старіші встановлення LaunchAgent, systemd або Windows Scheduled Task вбудували inline, і перезаписує метадані служби так, щоб ці значення завантажувалися з runtime-джерела замість визначення супервізора. + - `openclaw doctor --repair --force` перезаписує власні конфігурації supervisor. + - `OPENCLAW_SERVICE_REPAIR_POLICY=external` лишає doctor у режимі лише для читання для життєвого циклу служби Gateway. Він усе ще повідомляє стан служби й запускає виправлення, не пов’язані зі службою, але пропускає встановлення/запуск/перезапуск/bootstrap служби, перезаписи конфігурації supervisor і очищення застарілих служб, оскільки цим життєвим циклом керує зовнішній supervisor. + - У Linux doctor не перезаписує метадані команди/точки входу, доки відповідний systemd-юніт Gateway активний. Він також ігнорує неактивні додаткові юніти, схожі на Gateway, які не є застарілими, під час сканування дубльованих служб, щоб супутні файли служб не створювали зайвий шум очищення. + - Якщо автентифікація токеном потребує токена, а `gateway.auth.token` керується SecretRef, встановлення/виправлення служби doctor перевіряє SecretRef, але не зберігає розв’язані значення токена у відкритому тексті в метадані середовища служби supervisor. + - Doctor виявляє керовані значення середовища служби на базі `.env`/SecretRef, які старіші встановлення LaunchAgent, systemd або Windows Scheduled Task вбудували inline, і перезаписує метадані служби так, щоб ці значення завантажувалися з джерела runtime замість визначення supervisor. - Doctor виявляє, коли команда служби все ще фіксує старий `--port` після зміни `gateway.port`, і перезаписує метадані служби на поточний порт. - - Якщо автентифікація токеном вимагає токен, а налаштований SecretRef токена не розв'язано, doctor блокує шлях встановлення/ремонту з дієвими рекомендаціями. - - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує встановлення/ремонт, доки режим не буде задано явно. - - Для користувацьких systemd-модулів Linux перевірки drift токена doctor тепер включають джерела `Environment=` і `EnvironmentFile=` під час порівняння метаданих автентифікації служби. - - Ремонти служби doctor відмовляються перезаписувати, зупиняти або перезапускати службу Gateway зі старішого бінарного файла OpenClaw, коли конфігурацію востаннє було записано новішою версією. Див. [Усунення несправностей Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard). + - Якщо автентифікація токеном потребує токена, а налаштований SecretRef токена не розв’язано, doctor блокує шлях встановлення/виправлення з дієвими вказівками. + - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує встановлення/виправлення, доки режим не буде задано явно. + - Для Linux user-systemd юнітів перевірки розбіжності токенів doctor тепер включають джерела і `Environment=`, і `EnvironmentFile=` під час порівняння метаданих автентифікації служби. + - Виправлення служби doctor відмовляються перезаписувати, зупиняти або перезапускати службу Gateway зі старішого бінарного файла OpenClaw, коли конфігурацію востаннє записала новіша версія. Див. [Усунення несправностей Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard). - Ви завжди можете примусово виконати повний перезапис через `openclaw gateway install --force`. - - Doctor перевіряє runtime служби (PID, останній статус виходу) і попереджає, коли службу встановлено, але вона фактично не працює. Він також перевіряє конфлікти портів на порту Gateway (типово `18789`) і повідомляє ймовірні причини (Gateway уже запущено, SSH-тунель). + + Doctor перевіряє runtime служби (PID, останній статус виходу) і попереджає, коли службу встановлено, але вона фактично не працює. Він також перевіряє конфлікти портів на порту Gateway (стандартно `18789`) і повідомляє ймовірні причини (Gateway вже працює, SSH-тунель). - 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). - Нововстановлені або відремонтовані LaunchAgents macOS використовують канонічний системний PATH (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) замість копіювання PATH інтерактивної оболонки, тож Volta, asdf, fnm, pnpm та інші каталоги менеджерів версій не змінюють, який Node розв'язують дочірні процеси. Служби Linux усе ще зберігають явні корені середовища (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) і стабільні каталоги user-bin, але вгадані fallback-каталоги менеджерів версій записуються до PATH служби лише тоді, коли ці каталоги існують на диску. + Нововстановлені або виправлені macOS LaunchAgents використовують канонічний системний PATH (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) замість копіювання PATH інтерактивної оболонки, тому Volta, asdf, fnm, pnpm та інші каталоги менеджерів версій не змінюють, який Node розв’язують дочірні процеси. Служби Linux усе ще зберігають явні корені середовища (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) і стабільні користувацькі bin-каталоги, але вгадані резервні каталоги менеджерів версій записуються до PATH служби лише тоді, коли ці каталоги існують на диску. - Doctor зберігає будь-які зміни конфігурації й ставить мітку метаданих майстра для запису запуску doctor. + Doctor зберігає будь-які зміни конфігурації й ставить штамп метаданих майстра, щоб записати запуск doctor. - - Doctor пропонує систему пам'яті робочої області, коли її бракує, і виводить пораду щодо резервного копіювання, якщо робоча область ще не перебуває під git. + + Doctor пропонує систему пам’яті робочого простору, коли її немає, і виводить пораду щодо резервного копіювання, якщо робочий простір ще не перебуває під git. - Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace), щоб отримати повний посібник зі структури робочої області та резервного копіювання git (рекомендовано приватний GitHub або GitLab). + Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace), щоб отримати повний посібник зі структури робочого простору й резервного копіювання git (рекомендовано приватний GitHub або GitLab). -## Пов'язане +## Пов’язане - [Runbook Gateway](/uk/gateway) - [Усунення несправностей Gateway](/uk/gateway/troubleshooting)