diff --git a/docs/uk/channels/slack.md b/docs/uk/channels/slack.md index 696ee3326..74342938f 100644 --- a/docs/uk/channels/slack.md +++ b/docs/uk/channels/slack.md @@ -1,27 +1,27 @@ --- read_when: - - Налаштування Slack або налагодження сокетного/HTTP-режиму Slack + - Налаштування Slack або налагодження режиму сокета/HTTP для Slack summary: Налаштування Slack і поведінка під час виконання (режим Socket + URL-адреси HTTP-запитів) title: Slack x-i18n: - generated_at: "2026-05-04T07:02:44Z" + generated_at: "2026-05-05T01:21:09Z" model: gpt-5.5 provider: openai - source_hash: d4a91fc1ae5f1e03f714308be54e164ef204809e74efabed8dc75c3035c14228 + source_hash: 7334027c606ff6465190433d2159c3f9cfbcf1e8a3a1e826682423f71700a064 source_path: channels/slack.md workflow: 16 --- -Готово до production-використання для DM і каналів через інтеграції застосунку Slack. Режим за замовчуванням — Socket Mode; URL-адреси HTTP-запитів також підтримуються. +Готово до продакшену для DM і каналів через інтеграції Slack app. Режим за замовчуванням — Socket Mode; HTTP Request URLs також підтримуються. - - DM у Slack за замовчуванням використовують режим спарювання. + + DM у Slack за замовчуванням використовують режим сполучення. - + Нативна поведінка команд і каталог команд. - + Міжканальна діагностика та сценарії відновлення. @@ -31,13 +31,148 @@ x-i18n: - - У налаштуваннях застосунку Slack натисніть кнопку **[Create New App](https://api.slack.com/apps/new)**: + + Відкрийте [api.slack.com/apps](https://api.slack.com/apps/new) → **Create New App** → **From a manifest** → виберіть свій робочий простір → вставте один із наведених нижче маніфестів → **Next** → **Create**. - - виберіть **from a manifest** і виберіть workspace для свого застосунку - - вставте [приклад маніфесту](#manifest-and-scope-checklist) нижче й продовжте створення - - згенеруйте **App-Level Token** (`xapp-...`) з `connections:write` - - встановіть застосунок і скопіюйте показаний **Bot Token** (`xoxb-...`) + + +```json Recommended +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "emoji:read", + "files:read", + "files:write", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "mpim:history", + "mpim:read", + "mpim:write", + "pins:read", + "pins:write", + "reactions:read", + "reactions:write", + "usergroups:read", + "users:read" + ] + } + }, + "settings": { + "socket_mode_enabled": true, + "event_subscriptions": { + "bot_events": [ + "app_home_opened", + "app_mention", + "channel_rename", + "member_joined_channel", + "member_left_channel", + "message.channels", + "message.groups", + "message.im", + "message.mpim", + "pin_added", + "pin_removed", + "reaction_added", + "reaction_removed" + ] + } + } +} +``` + +```json Minimal +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "users:read" + ] + } + }, + "settings": { + "socket_mode_enabled": true, + "event_subscriptions": { + "bot_events": [ + "app_home_opened", + "app_mention", + "message.channels", + "message.groups", + "message.im" + ] + } + } +} +``` + + + + + **Recommended** відповідає повному набору можливостей вбудованого Slack plugin: App Home, слеш-команди, файли, реакції, закріплення, групові DM і читання емодзі/груп користувачів. Виберіть **Minimal**, коли політика робочого простору обмежує scopes — він охоплює DM, історію каналів/груп, згадки та слеш-команди, але вилучає файли, реакції, закріплення, групові DM (`mpim:*`), `emoji:read` і `usergroups:read`. Див. [Контрольний список маніфесту та scopes](#manifest-and-scope-checklist), щоб дізнатися обґрунтування для кожного scope і додаткові параметри, як-от додаткові слеш-команди. + + + Після того як Slack створить app: + + - **Basic Information → App-Level Tokens → Generate Token and Scopes**: додайте `connections:write`, збережіть, скопіюйте значення `xapp-...`. + - **Install App → Install to Workspace**: скопіюйте `xoxb-...` Bot User OAuth Token. @@ -84,15 +219,162 @@ openclaw gateway - + - - У налаштуваннях застосунку Slack натисніть кнопку **[Create New App](https://api.slack.com/apps/new)**: + + Відкрийте [api.slack.com/apps](https://api.slack.com/apps/new) → **Create New App** → **From a manifest** → виберіть свій робочий простір → вставте один із наведених нижче маніфестів → замініть `https://gateway-host.example.com/slack/events` на публічну URL-адресу вашого Gateway → **Next** → **Create**. - - виберіть **from a manifest** і виберіть workspace для свого застосунку - - вставте [приклад маніфесту](#manifest-and-scope-checklist) і оновіть URL-адреси перед створенням - - збережіть **Signing Secret** для перевірки запитів - - встановіть застосунок і скопіюйте показаний **Bot Token** (`xoxb-...`) + + +```json Recommended +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false, + "url": "https://gateway-host.example.com/slack/events" + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "emoji:read", + "files:read", + "files:write", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "mpim:history", + "mpim:read", + "mpim:write", + "pins:read", + "pins:write", + "reactions:read", + "reactions:write", + "usergroups:read", + "users:read" + ] + } + }, + "settings": { + "event_subscriptions": { + "request_url": "https://gateway-host.example.com/slack/events", + "bot_events": [ + "app_home_opened", + "app_mention", + "channel_rename", + "member_joined_channel", + "member_left_channel", + "message.channels", + "message.groups", + "message.im", + "message.mpim", + "pin_added", + "pin_removed", + "reaction_added", + "reaction_removed" + ] + }, + "interactivity": { + "is_enabled": true, + "request_url": "https://gateway-host.example.com/slack/events", + "message_menu_options_url": "https://gateway-host.example.com/slack/events" + } + } +} +``` + +```json Minimal +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false, + "url": "https://gateway-host.example.com/slack/events" + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "users:read" + ] + } + }, + "settings": { + "event_subscriptions": { + "request_url": "https://gateway-host.example.com/slack/events", + "bot_events": [ + "app_home_opened", + "app_mention", + "message.channels", + "message.groups", + "message.im" + ] + }, + "interactivity": { + "is_enabled": true, + "request_url": "https://gateway-host.example.com/slack/events", + "message_menu_options_url": "https://gateway-host.example.com/slack/events" + } + } +} +``` + + + + + **Recommended** відповідає повному набору можливостей вбудованого Slack plugin; **Minimal** вилучає файли, реакції, закріплення, групові DM (`mpim:*`), `emoji:read` і `usergroups:read` для робочих просторів із суворими обмеженнями. Див. [Контрольний список маніфесту та scopes](#manifest-and-scope-checklist), щоб дізнатися обґрунтування для кожного scope. + + + Після того як Slack створить app: + + - **Basic Information → App Credentials**: скопіюйте **Signing Secret** для перевірки запитів. + - **Install App → Install to Workspace**: скопіюйте `xoxb-...` Bot User OAuth Token. @@ -121,7 +403,7 @@ openclaw config patch --file ./slack.http.patch.json5 ``` - Використовуйте унікальні шляхи webhook для HTTP із кількома обліковими записами + Використовуйте унікальні шляхи Webhook для HTTP із кількома обліковими записами Надайте кожному обліковому запису окремий `webhookPath` (за замовчуванням `/slack/events`), щоб реєстрації не конфліктували. @@ -142,7 +424,7 @@ openclaw gateway ## Налаштування транспорту Socket Mode -OpenClaw за замовчуванням встановлює для клієнта Slack SDK тайм-аут pong у 15 секунд для Socket Mode. Перевизначайте параметри транспорту лише тоді, коли потрібне налаштування для конкретного workspace або хоста: +OpenClaw за замовчуванням встановлює для клієнта Slack SDK тайм-аут pong у 15 секунд для Socket Mode. Перевизначайте параметри транспорту лише тоді, коли потрібне налаштування під конкретний робочий простір або хост: ```json5 { @@ -159,11 +441,11 @@ OpenClaw за замовчуванням встановлює для клієн } ``` -Використовуйте це лише для workspace у Socket Mode, які реєструють тайм-аути pong/server-ping websocket Slack або працюють на хостах із відомим голодуванням event loop. `clientPingTimeout` — це очікування pong після того, як SDK надсилає клієнтський ping; `serverPingTimeout` — це очікування ping від сервера Slack. Повідомлення та події застосунку залишаються станом застосунку, а не сигналами працездатності транспорту. +Використовуйте це лише для робочих просторів Socket Mode, які журналюють тайм-аути pong/server-ping вебсокета Slack, або працюють на хостах із відомим блокуванням event loop. `clientPingTimeout` — це очікування pong після того, як SDK надсилає client ping; `serverPingTimeout` — це очікування server pings від Slack. Повідомлення й події app залишаються станом застосунку, а не сигналами живучості транспорту. -## Контрольний список маніфесту й scope +## Контрольний список маніфесту та scopes -Базовий маніфест застосунку Slack однаковий для Socket Mode і URL-адрес HTTP-запитів. Відрізняється лише блок `settings` (і `url` slash-команди). +Базовий маніфест Slack app однаковий для Socket Mode і HTTP Request URLs. Відрізняється лише блок `settings` (і `url` слеш-команди). Базовий маніфест (Socket Mode за замовчуванням): @@ -240,7 +522,7 @@ OpenClaw за замовчуванням встановлює для клієн } ``` -Для режиму **URL-адрес HTTP-запитів** замініть `settings` на HTTP-варіант і додайте `url` до кожної slash-команди. Потрібна публічна URL-адреса: +Для **режиму HTTP Request URLs** замініть `settings` варіантом HTTP і додайте `url` до кожної slash-команди. Потрібна публічна URL-адреса: ```json { @@ -284,22 +566,22 @@ OpenClaw за замовчуванням встановлює для клієн ### Додаткові налаштування маніфесту -Увімкніть інші функції, що розширюють наведені вище значення за замовчуванням. +Відкрийте різні функції, які розширюють наведені вище типові значення. -Маніфест за замовчуванням вмикає вкладку Slack App Home **Home** і підписується на `app_home_opened`. Коли учасник workspace відкриває вкладку Home, OpenClaw публікує безпечний стандартний вигляд Home через `views.publish`; payload розмови або приватна конфігурація не включаються. Вкладка **Messages** залишається ввімкненою для DM у Slack. +Типовий маніфест вмикає вкладку **Home** для Slack App Home і підписується на `app_home_opened`. Коли учасник робочого простору відкриває вкладку Home, OpenClaw публікує безпечний типовий вигляд Home за допомогою `views.publish`; корисне навантаження розмови або приватна конфігурація не включаються. Вкладка **Messages** залишається ввімкненою для приватних повідомлень Slack. - Кілька [нативних slash-команд](#commands-and-slash-behavior) можна використовувати замість однієї налаштованої команди з нюансами: + Замість однієї налаштованої команди можна використовувати кілька [нативних slash-команд](#commands-and-slash-behavior) з урахуванням нюансів: - - Використовуйте `/agentstatus` замість `/status`, бо команда `/status` зарезервована. - - Одночасно можна зробити доступними не більше 25 slash-команд. + - Використовуйте `/agentstatus` замість `/status`, оскільки команда `/status` зарезервована. + - Одночасно можна зробити доступними не більше ніж 25 slash-команд. Замініть наявний розділ `features.slash_commands` підмножиною [доступних команд](/uk/tools/slash-commands#command-list): - + ```json { @@ -422,8 +704,8 @@ OpenClaw за замовчуванням встановлює для клієн ``` - - Використовуйте той самий список `slash_commands`, що й для Socket Mode вище, і додайте `"url": "https://gateway-host.example.com/slack/events"` до кожного запису. Приклад: + + Використовуйте той самий список `slash_commands`, що й у Socket Mode вище, і додайте `"url": "https://gateway-host.example.com/slack/events"` до кожного запису. Приклад: ```json { @@ -443,16 +725,16 @@ OpenClaw за замовчуванням встановлює для клієн } ``` - Повторіть це значення `url` для кожної команди у списку. + Повторіть це значення `url` для кожної команди в списку. - Додайте область бота `chat:write.customize`, якщо хочете, щоб вихідні повідомлення використовували ідентичність активного агента (власне ім’я користувача та іконку) замість стандартної ідентичності застосунку Slack. + Додайте область бота `chat:write.customize`, якщо хочете, щоб вихідні повідомлення використовували ідентичність активного агента (власне ім’я користувача та піктограму) замість типової ідентичності застосунку Slack. - Якщо ви використовуєте іконку-емодзі, Slack очікує синтаксис `:emoji_name:`. + Якщо ви використовуєте піктограму emoji, Slack очікує синтаксис `:emoji_name:`. @@ -473,25 +755,25 @@ OpenClaw за замовчуванням встановлює для клієн - `botToken` + `appToken` потрібні для Socket Mode. - Режим HTTP потребує `botToken` + `signingSecret`. -- `botToken`, `appToken`, `signingSecret` і `userToken` приймають відкриті +- `botToken`, `appToken`, `signingSecret` і `userToken` приймають звичайні текстові рядки або об’єкти SecretRef. - Токени конфігурації перевизначають резервні значення env. -- Резервне значення env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` застосовується лише до стандартного облікового запису. -- `userToken` (`xoxp-...`) доступний лише в конфігурації (без резервного значення env) і типово має поведінку лише для читання (`userTokenReadOnly: true`). +- Резервні значення env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` застосовуються лише до типового облікового запису. +- `userToken` (`xoxp-...`) налаштовується лише в конфігурації (без резервного значення env) і типово має поведінку лише для читання (`userTokenReadOnly: true`). Поведінка знімка стану: -- Інспекція облікового запису Slack відстежує поля `*Source` і `*Status` +- Перевірка облікового запису Slack відстежує поля `*Source` і `*Status` для кожних облікових даних (`botToken`, `appToken`, `signingSecret`, `userToken`). -- Стан має значення `available`, `configured_unavailable` або `missing`. +- Стан може бути `available`, `configured_unavailable` або `missing`. - `configured_unavailable` означає, що обліковий запис налаштовано через SecretRef - або інше неінлайнове джерело секрету, але поточна команда чи шлях виконання - не змогли отримати фактичне значення. + або інше неінлайнове джерело секретів, але поточний шлях команди/середовища виконання + не зміг отримати фактичне значення. - У режимі HTTP включено `signingSecretStatus`; у Socket Mode - обов’язкова пара — `botTokenStatus` + `appTokenStatus`. + потрібна пара — `botTokenStatus` + `appTokenStatus`. -Для дій і читання каталогу перевага може надаватися токену користувача, якщо його налаштовано. Для запису пріоритетним залишається токен бота; записи через токен користувача дозволені лише коли `userTokenReadOnly: false` і токен бота недоступний. +Для дій/читання каталогу токен користувача може мати перевагу, коли його налаштовано. Для записів перевага залишається за токеном бота; записи з токеном користувача дозволені лише коли `userTokenReadOnly: false` і токен бота недоступний. ## Дії та шлюзи @@ -508,17 +790,17 @@ OpenClaw за замовчуванням встановлює для клієн | memberInfo | увімкнено | | emojiList | увімкнено | -Поточні дії повідомлень Slack включають `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` і `emoji-list`. `download-file` приймає ID файлів Slack, показані у вхідних заповнювачах файлів, і повертає попередні перегляди зображень для зображень або метадані локального файлу для інших типів файлів. +Поточні дії повідомлень Slack включають `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` і `emoji-list`. `download-file` приймає ідентифікатори файлів Slack, показані у вхідних плейсхолдерах файлів, і повертає попередні перегляди зображень для зображень або метадані локального файлу для інших типів файлів. ## Контроль доступу та маршрутизація - `channels.slack.dmPolicy` керує доступом до DM. `channels.slack.allowFrom` — канонічний allowlist для DM. + `channels.slack.dmPolicy` контролює доступ DM. `channels.slack.allowFrom` — канонічний allowlist для DM. - `pairing` (типово) - `allowlist` - - `open` (вимагає, щоб `channels.slack.allowFrom` містив `"*"`) + - `open` (потребує, щоб `channels.slack.allowFrom` містив `"*"`) - `disabled` Прапорці DM: @@ -529,39 +811,39 @@ OpenClaw за замовчуванням встановлює для клієн - `dm.groupEnabled` (групові DM типово false) - `dm.groupChannels` (необов’язковий allowlist MPIM) - Пріоритетність для кількох облікових записів: + Пріоритет для кількох облікових записів: - `channels.slack.accounts.default.allowFrom` застосовується лише до облікового запису `default`. - Іменовані облікові записи успадковують `channels.slack.allowFrom`, коли їхній власний `allowFrom` не задано. - Іменовані облікові записи не успадковують `channels.slack.accounts.default.allowFrom`. - Застарілі `channels.slack.dm.policy` і `channels.slack.dm.allowFrom` досі читаються для сумісності. `openclaw doctor --fix` переносить їх до `dmPolicy` і `allowFrom`, коли це можна зробити без зміни доступу. + Застарілі `channels.slack.dm.policy` і `channels.slack.dm.allowFrom` досі читаються для сумісності. `openclaw doctor --fix` мігрує їх до `dmPolicy` і `allowFrom`, коли це можна зробити без зміни доступу. - Pairing у DM використовує `openclaw pairing approve slack `. + Сполучення в DM використовує `openclaw pairing approve slack `. - - `channels.slack.groupPolicy` керує обробкою каналів: + + `channels.slack.groupPolicy` контролює обробку каналів: - `open` - `allowlist` - `disabled` - Allowlist каналів розміщується в `channels.slack.channels` і **має використовувати стабільні ID каналів Slack** (наприклад, `C12345678`) як ключі конфігурації. + Allowlist каналів розміщується в `channels.slack.channels` і **має використовувати стабільні ідентифікатори каналів Slack** (наприклад `C12345678`) як ключі конфігурації. - Примітка щодо виконання: якщо `channels.slack` повністю відсутній (налаштування лише через env), під час виконання використовується резервне `groupPolicy="allowlist"` і записується попередження (навіть якщо `channels.defaults.groupPolicy` задано). + Примітка щодо середовища виконання: якщо `channels.slack` повністю відсутній (налаштування лише через env), середовище виконання повертається до `groupPolicy="allowlist"` і записує попередження в журнал (навіть якщо `channels.defaults.groupPolicy` задано). - Розв’язання імені/ID: + Розпізнавання назви/ідентифікатора: - - записи allowlist каналів і записи allowlist DM розв’язуються під час запуску, коли доступ токена це дозволяє - - нерозв’язані записи назв каналів зберігаються як налаштовані, але типово ігноруються для маршрутизації - - вхідна авторизація та маршрутизація каналів типово спершу використовують ID; пряме зіставлення імені користувача/slug вимагає `channels.slack.dangerouslyAllowNameMatching: true` + - записи списку дозволених каналів і записи списку дозволених DM розпізнаються під час запуску, коли доступ до токена це дозволяє + - нерозпізнані записи з назвами каналів зберігаються як налаштовано, але типово ігноруються для маршрутизації + - вхідна авторизація та маршрутизація каналів типово спершу використовують ID; пряме зіставлення за іменем користувача/slug потребує `channels.slack.dangerouslyAllowNameMatching: true` - Ключі на основі імен (`#channel-name` або `channel-name`) **не** збігаються за `groupPolicy: "allowlist"`. Пошук каналу типово спершу використовує ID, тому ключ на основі імені ніколи не маршрутизуватиметься успішно, і всі повідомлення в цьому каналі буде мовчки заблоковано. Це відрізняється від `groupPolicy: "open"`, де ключ каналу не потрібен для маршрутизації, а ключ на основі імені здається робочим. + Ключі на основі назв (`#channel-name` або `channel-name`) **не** збігаються за `groupPolicy: "allowlist"`. Пошук каналу типово спершу використовує ID, тому ключ на основі назви ніколи не маршрутизуватиметься успішно, а всі повідомлення в цьому каналі буде мовчки заблоковано. Це відрізняється від `groupPolicy: "open"`, де ключ каналу не потрібен для маршрутизації, а ключ на основі назви здається робочим. - Завжди використовуйте ID каналу Slack як ключ. Щоб знайти його: клацніть канал у Slack правою кнопкою миші → **Copy link** — ID (`C...`) з’являється в кінці URL. + Завжди використовуйте ID каналу Slack як ключ. Щоб знайти його: клацніть канал у Slack правою кнопкою миші → **Copy link** — ID (`C...`) зʼявиться в кінці URL. Правильно: @@ -578,7 +860,7 @@ OpenClaw за замовчуванням встановлює для клієн } ``` - Неправильно (тихо заблоковано за `groupPolicy: "allowlist"`): + Неправильно (мовчки блокується за `groupPolicy: "allowlist"`): ```json5 { @@ -597,43 +879,43 @@ OpenClaw за замовчуванням встановлює для клієн - Повідомлення каналів за замовчуванням допускаються лише за наявності згадки. + Повідомлення в каналах типово пропускаються лише за наявності згадки. Джерела згадок: - явна згадка застосунку (`<@botId>`) - - згадка групи користувачів Slack (``), коли користувач-бот є учасником цієї групи користувачів; потребує `usergroups:read` + - згадка групи користувачів Slack (``), коли користувач бота є учасником цієї групи користувачів; потребує `usergroups:read` - regex-шаблони згадок (`agents.list[].groupChat.mentionPatterns`, резервний варіант `messages.groupChat.mentionPatterns`) - - неявна поведінка відповіді в треді боту (вимкнено, коли `thread.requireExplicitMention` має значення `true`) + - неявна поведінка гілки з відповіддю боту (вимкнено, коли `thread.requireExplicitMention` має значення `true`) - Керування для окремого каналу (`channels.slack.channels.`; імена лише через розпізнавання під час запуску або `dangerouslyAllowNameMatching`): + Поканальні елементи керування (`channels.slack.channels.`; назви лише через розпізнавання під час запуску або `dangerouslyAllowNameMatching`): - `requireMention` - - `users` (allowlist) + - `users` (список дозволених) - `allowBots` - `skills` - `systemPrompt` - `tools`, `toolsBySender` - формат ключа `toolsBySender`: `id:`, `e164:`, `username:`, `name:` або wildcard `"*"` - (застарілі ключі без префікса й далі зіставляються лише з `id:`) + (застарілі ключі без префікса досі зіставляються лише з `id:`) - `allowBots` є консервативним для каналів і приватних каналів: повідомлення кімнати, створені ботом, приймаються лише тоді, коли бот-відправник явно вказаний в allowlist `users` цієї кімнати, або коли принаймні один явний ідентифікатор власника Slack з `channels.slack.allowFrom` зараз є учасником кімнати. Wildcard і записи власника за відображуваним іменем не задовольняють наявність власника. Наявність власника використовує Slack `conversations.members`; переконайтеся, що застосунок має відповідний scope читання для типу кімнати (`channels:read` для публічних каналів, `groups:read` для приватних каналів). Якщо пошук учасників не вдається, OpenClaw відкидає повідомлення кімнати, створене ботом. + `allowBots` є консервативним для каналів і приватних каналів: повідомлення кімнати, написані ботом, приймаються лише тоді, коли бот-відправник явно вказаний у списку дозволених `users` цієї кімнати, або коли принаймні один явний ID власника Slack із `channels.slack.allowFrom` наразі є учасником кімнати. Wildcard і записи власників за відображуваним іменем не задовольняють умову присутності власника. Присутність власника використовує Slack `conversations.members`; переконайтеся, що застосунок має відповідний read-scope для типу кімнати (`channels:read` для публічних каналів, `groups:read` для приватних каналів). Якщо пошук учасників не вдається, OpenClaw відкидає повідомлення кімнати, написане ботом. -## Треди, сеанси й теги відповіді +## Гілки, сеанси та теги відповіді -- Особисті повідомлення маршрутизуються як `direct`; канали як `channel`; багатокористувацькі особисті повідомлення як `group`. -- Прив'язки маршрутів Slack приймають сирі ідентифікатори співрозмовників, а також форми цілі Slack, як-от `channel:C12345678`, `user:U12345678` і `<@U12345678>`. -- З типовим `session.dmScope=main` особисті повідомлення Slack згортаються до основного сеансу агента. +- DM маршрутизуються як `direct`; канали як `channel`; MPIM як `group`. +- Привʼязки маршрутів Slack приймають необроблені ID учасників, а також цільові форми Slack, як-от `channel:C12345678`, `user:U12345678` і `<@U12345678>`. +- За типового `session.dmScope=main` DM Slack згортаються в головний сеанс агента. - Сеанси каналів: `agent::slack:channel:`. -- Відповіді в тредах можуть створювати суфікси сеансу треду (`:thread:`), коли це застосовно. +- Відповіді в гілках можуть створювати суфікси сеансів гілок (`:thread:`), коли це застосовно. - Типове значення `channels.slack.thread.historyScope` — `thread`; типове значення `thread.inheritParent` — `false`. -- `channels.slack.thread.initialHistoryLimit` керує тим, скільки наявних повідомлень треду отримується під час запуску нового сеансу треду (типово `20`; установіть `0`, щоб вимкнути). -- `channels.slack.thread.requireExplicitMention` (типово `false`): коли `true`, пригнічує неявні згадки в треді, тож бот відповідає лише на явні згадки `@bot` у тредах, навіть якщо бот уже брав участь у треді. Без цього відповіді в треді за участю бота обходять перевірку `requireMention`. +- `channels.slack.thread.initialHistoryLimit` керує тим, скільки наявних повідомлень гілки завантажується під час запуску нового сеансу гілки (типово `20`; задайте `0`, щоб вимкнути). +- `channels.slack.thread.requireExplicitMention` (типово `false`): коли `true`, пригнічує неявні згадки в гілці, щоб бот відповідав лише на явні згадки `@bot` у гілках, навіть якщо бот уже брав участь у гілці. Без цього відповіді в гілці за участі бота обходять фільтр `requireMention`. -Керування тредами відповідей: +Елементи керування гілками відповідей: - `channels.slack.replyToMode`: `off|first|all|batched` (типово `off`) - `channels.slack.replyToModeByChatType`: для кожного `direct|group|channel` @@ -645,14 +927,14 @@ OpenClaw за замовчуванням встановлює для клієн - `[[reply_to:]]` -`replyToMode="off"` вимикає **всі** треди відповідей у Slack, включно з явними тегами `[[reply_to_*]]`. Це відрізняється від Telegram, де явні теги й далі враховуються в режимі `"off"`. Треди Slack приховують повідомлення з каналу, тоді як відповіді Telegram залишаються видимими в рядку. +`replyToMode="off"` вимикає **всі** гілки відповідей у Slack, включно з явними тегами `[[reply_to_*]]`. Це відрізняється від Telegram, де явні теги досі враховуються в режимі `"off"`. Гілки Slack приховують повідомлення з каналу, тоді як відповіді Telegram залишаються видимими в рядку. ## Реакції підтвердження `ackReaction` надсилає emoji підтвердження, поки OpenClaw обробляє вхідне повідомлення. -Порядок розв'язання: +Порядок розпізнавання: - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` @@ -661,21 +943,21 @@ OpenClaw за замовчуванням встановлює для клієн Примітки: -- Slack очікує shortcode (наприклад, `"eyes"`). +- Slack очікує shortcodes (наприклад, `"eyes"`). - Використовуйте `""`, щоб вимкнути реакцію для облікового запису Slack або глобально. ## Потокове передавання тексту -`channels.slack.streaming` керує поведінкою live preview: +`channels.slack.streaming` керує поведінкою живого попереднього перегляду: -- `off`: вимкнути потокове передавання live preview. -- `partial` (типово): замінювати текст preview найновішим частковим виводом. -- `block`: додавати фрагментовані оновлення preview. -- `progress`: показувати текст статусу перебігу під час генерування, а потім надіслати фінальний текст. -- `streaming.preview.toolProgress`: коли draft preview активний, спрямовувати оновлення інструментів/перебігу в те саме редаговане повідомлення preview (типово: `true`). Установіть `false`, щоб зберігати окремі повідомлення інструментів/перебігу. -- `streaming.preview.commandText` / `streaming.progress.commandText`: установіть `status`, щоб зберігати компактні рядки перебігу інструментів, приховуючи сирий текст команд/виконання (типово: `raw`). +- `off`: вимкнути потокове передавання живого попереднього перегляду. +- `partial` (типово): замінювати текст попереднього перегляду найновішим частковим виводом. +- `block`: додавати фрагментовані оновлення попереднього перегляду. +- `progress`: показувати текст стану прогресу під час генерації, потім надсилати фінальний текст. +- `streaming.preview.toolProgress`: коли активний чернетковий попередній перегляд, спрямовувати оновлення інструментів/прогресу в те саме редаговане повідомлення попереднього перегляду (типово: `true`). Задайте `false`, щоб зберігати окремі повідомлення інструментів/прогресу. +- `streaming.preview.commandText` / `streaming.progress.commandText`: задайте `status`, щоб зберігати компактні рядки прогресу інструментів, приховуючи необроблений текст команд/exec (типово: `raw`). -Приховати сирий текст команд/виконання, зберігаючи компактні рядки перебігу: +Приховати необроблений текст команд/exec, зберігаючи компактні рядки прогресу: ```json { @@ -695,14 +977,14 @@ OpenClaw за замовчуванням встановлює для клієн `channels.slack.streaming.nativeTransport` керує нативним потоковим передаванням тексту Slack, коли `channels.slack.streaming.mode` має значення `partial` (типово: `true`). -- Для появи нативного потокового передавання тексту й статусу треду асистента Slack має бути доступний тред відповіді. Вибір треду й далі дотримується `replyToMode`. -- Канали, групові чати й кореневі повідомлення особистих повідомлень верхнього рівня й далі можуть використовувати звичайний draft preview, коли нативне потокове передавання недоступне або тред відповіді не існує. -- Особисті повідомлення Slack верхнього рівня за замовчуванням лишаються поза тредом, тому вони не показують нативний stream/status preview у стилі треду Slack; натомість OpenClaw публікує й редагує draft preview в особистому повідомленні. -- Медіа й нетекстові payload повертаються до звичайної доставки. -- Фінальні медіа/помилки скасовують очікувані редагування preview; придатні фінальні тексти/блоки скидаються лише тоді, коли можуть редагувати preview на місці. -- Якщо потокове передавання зазнає помилки посеред відповіді, OpenClaw повертається до звичайної доставки для решти payload. +- Для появи нативного потокового передавання тексту та стану гілки помічника Slack має бути доступна гілка відповіді. Вибір гілки досі відповідає `replyToMode`. +- Канали, групові чати та кореневі повідомлення DM верхнього рівня досі можуть використовувати звичайний чернетковий попередній перегляд, коли нативне потокове передавання недоступне або гілки відповіді немає. +- DM Slack верхнього рівня типово залишаються поза гілками, тому вони не показують нативний потоковий/статусний попередній перегляд Slack у стилі гілки; натомість OpenClaw публікує й редагує чернетковий попередній перегляд у DM. +- Медіа та нетекстові payloads повертаються до звичайної доставки. +- Фінальні медіа/помилки скасовують очікувані редагування попереднього перегляду; придатні фінальні текстові/блокові повідомлення скидаються лише тоді, коли вони можуть редагувати попередній перегляд на місці. +- Якщо потокове передавання зазнає збою посеред відповіді, OpenClaw повертається до звичайної доставки для решти payloads. -Використовувати draft preview замість нативного потокового передавання тексту Slack: +Використати чернетковий попередній перегляд замість нативного потокового передавання тексту Slack: ```json5 { @@ -719,58 +1001,58 @@ OpenClaw за замовчуванням встановлює для клієн Застарілі ключі: -- `channels.slack.streamMode` (`replace | status_final | append`) автоматично мігрується до `channels.slack.streaming.mode`. -- boolean `channels.slack.streaming` автоматично мігрується до `channels.slack.streaming.mode` і `channels.slack.streaming.nativeTransport`. -- застарілий `channels.slack.nativeStreaming` автоматично мігрується до `channels.slack.streaming.nativeTransport`. +- `channels.slack.streamMode` (`replace | status_final | append`) автоматично мігрує до `channels.slack.streaming.mode`. +- boolean `channels.slack.streaming` автоматично мігрує до `channels.slack.streaming.mode` і `channels.slack.streaming.nativeTransport`. +- застарілий `channels.slack.nativeStreaming` автоматично мігрує до `channels.slack.streaming.nativeTransport`. -## Резервна реакція набору тексту +## Резервна реакція введення -`typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки OpenClaw обробляє відповідь, а потім видаляє її після завершення запуску. Це найкорисніше поза відповідями в тредах, які використовують стандартний індикатор стану "набирає текст...". +`typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки OpenClaw обробляє відповідь, а потім видаляє її, коли виконання завершується. Це найкорисніше поза відповідями в гілках, які використовують типовий індикатор стану "is typing...". -Порядок вирішення: +Порядок розпізнавання: - `channels.slack.accounts..typingReaction` - `channels.slack.typingReaction` Примітки: -- Slack очікує короткі коди (наприклад `"hourglass_flowing_sand"`). -- Реакція виконується за принципом найкращих зусиль, а очищення автоматично виконується після завершення відповіді або шляху помилки. +- Slack очікує shortcodes (наприклад, `"hourglass_flowing_sand"`). +- Реакція виконується за принципом best-effort, а очищення автоматично виконується після завершення відповіді або шляху помилки. -## Медіа, розбиття на фрагменти та доставка +## Медіа, фрагментація та доставка - - Файлові вкладення Slack завантажуються з приватних URL, розміщених у Slack (потік запитів з автентифікацією токеном), і записуються до сховища медіа, коли отримання успішне та обмеження розміру це дозволяють. Заповнювачі файлів містять Slack `fileId`, щоб агенти могли отримати оригінальний файл за допомогою `download-file`. + + Файлові вкладення Slack завантажуються з приватних URL, розміщених Slack (потік запиту з автентифікацією токеном), і записуються до сховища медіа, коли отримання успішне й обмеження розміру це дозволяють. Заповнювачі файлів включають Slack `fileId`, щоб агенти могли отримати оригінальний файл через `download-file`. - Завантаження використовують обмежені тайм-аути простою та загальні тайм-аути. Якщо отримання файлу Slack зависає або завершується помилкою, OpenClaw продовжує обробляти повідомлення й повертається до заповнювача файлу. + Завантаження використовують обмежені тайм-аути простою та загального часу. Якщо отримання файлу Slack зависає або завершується з помилкою, OpenClaw продовжує обробляти повідомлення й повертається до заповнювача файлу. - Стандартне обмеження розміру вхідних даних під час виконання становить `20MB`, якщо його не перевизначено через `channels.slack.mediaMaxMb`. + Типове runtime-обмеження розміру вхідних даних — `20MB`, якщо його не перевизначено через `channels.slack.mediaMaxMb`. - - - текстові фрагменти використовують `channels.slack.textChunkLimit` (стандартно 4000) - - `channels.slack.chunkMode="newline"` вмикає поділ із пріоритетом абзаців - - надсилання файлів використовує API завантаження Slack і може включати відповіді в тредах (`thread_ts`) - - обмеження вихідних медіа дотримується `channels.slack.mediaMaxMb`, коли налаштовано; інакше надсилання в канал використовує стандартні значення MIME-виду з медіаконвеєра + + - текстові фрагменти використовують `channels.slack.textChunkLimit` (типово 4000) + - `channels.slack.chunkMode="newline"` вмикає розбиття зі пріоритетом абзаців + - надсилання файлів використовують API завантаження Slack і можуть включати відповіді в гілках (`thread_ts`) + - обмеження вихідних медіа відповідає `channels.slack.mediaMaxMb`, коли налаштовано; інакше надсилання в канал використовує типові значення за MIME-типом із media pipeline - + Бажані явні цілі: - `user:` для DM - `channel:` для каналів - Текстові або лише блокові DM Slack можуть публікуватися безпосередньо за ID користувачів; завантаження файлів і надсилання в тредах спершу відкривають DM через API розмов Slack, оскільки ці шляхи потребують конкретного ID розмови. + DM Slack лише з текстом/блоками можуть публікуватися безпосередньо в ID користувачів; завантаження файлів і надсилання в гілках спершу відкривають DM через API розмов Slack, оскільки ці шляхи потребують конкретного ID розмови. ## Команди та поведінка slash -Slash-команди відображаються в Slack або як одна налаштована команда, або як кілька нативних команд. Налаштуйте `channels.slack.slashCommand`, щоб змінити стандартні значення команд: +Slash-команди зʼявляються в Slack або як одна налаштована команда, або як кілька нативних команд. Налаштуйте `channels.slack.slashCommand`, щоб змінити типові значення команд: - `enabled: false` - `name: "openclaw"` @@ -781,7 +1063,7 @@ Slash-команди відображаються в Slack або як одна /openclaw /help ``` -Нативні команди потребують [додаткових параметрів маніфесту](#additional-manifest-settings) у вашому застосунку Slack і натомість вмикаються через `channels.slack.commands.native: true` або `commands.native: true` у глобальних конфігураціях. +Нативні команди потребують [додаткових налаштувань маніфесту](#additional-manifest-settings) у вашому застосунку Slack і натомість вмикаються через `channels.slack.commands.native: true` або `commands.native: true` у глобальних конфігураціях. - Автоматичний режим нативних команд **вимкнено** для Slack, тому `commands.native: "auto"` не вмикає нативні команди Slack. @@ -789,24 +1071,24 @@ Slash-команди відображаються в Slack або як одна /help ``` -Меню нативних аргументів використовують адаптивну стратегію рендерингу, яка показує модальне підтвердження перед передаванням вибраного значення опції: +Меню аргументів нативних команд використовують адаптивну стратегію рендерингу, яка показує модальне підтвердження перед dispatch вибраного значення опції: - до 5 опцій: блоки кнопок - 6-100 опцій: статичне меню вибору -- понад 100 опцій: зовнішній вибір з асинхронною фільтрацією опцій, коли доступні обробники параметрів інтерактивності -- перевищено ліміти Slack: закодовані значення опцій повертаються до кнопок +- понад 100 опцій: зовнішній select з асинхронною фільтрацією опцій, коли доступні обробники interactivity options +- перевищені ліміти Slack: закодовані значення опцій повертаються до кнопок ```txt /think ``` -Slash-сесії використовують ізольовані ключі на кшталт `agent::slack:slash:` і все одно спрямовують виконання команд до цільової сесії розмови за допомогою `CommandTargetSessionKey`. +Slash-сеанси використовують ізольовані ключі на кшталт `agent::slack:slash:` і досі маршрутизують виконання команд до цільового сеансу розмови за допомогою `CommandTargetSessionKey`. ## Інтерактивні відповіді -Slack може відображати створені агентом інтерактивні елементи керування відповідями, але ця функція стандартно вимкнена. +Slack може рендерити інтерактивні елементи керування відповідями, створені агентом, але цю функцію типово вимкнено. -Увімкніть її глобально: +Увімкнути її глобально: ```json5 { @@ -820,7 +1102,7 @@ Slack може відображати створені агентом інтер } ``` -Або увімкніть її лише для одного облікового запису Slack: +Або увімкнути її лише для одного облікового запису Slack: ```json5 { @@ -843,39 +1125,39 @@ Slack може відображати створені агентом інтер - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -Ці директиви компілюються в Slack Block Kit і спрямовують кліки або вибори назад через наявний шлях подій взаємодії Slack. +Ці директиви компілюються в Slack Block Kit і маршрутизують кліки або вибори назад через наявний шлях подій взаємодії Slack. Примітки: -- Це UI, специфічний для Slack. Інші канали не перекладають директиви Slack Block Kit у власні системи кнопок. -- Значення інтерактивних callback — це непрозорі токени, згенеровані OpenClaw, а не необроблені значення, створені агентом. -- Якщо згенеровані інтерактивні блоки перевищили б ліміти Slack Block Kit, OpenClaw повертається до початкової текстової відповіді замість надсилання недійсного корисного навантаження блоків. +- Це інтерфейс, специфічний для Slack. Інші канали не перекладають директиви Slack Block Kit у власні системи кнопок. +- Значення інтерактивних callback — це згенеровані OpenClaw непрозорі токени, а не сирі значення, створені агентом. +- Якщо згенеровані інтерактивні блоки перевищуватимуть обмеження Slack Block Kit, OpenClaw повертається до початкової текстової відповіді замість надсилання недійсного payload блоків. ## Схвалення exec у Slack -Slack може працювати як нативний клієнт схвалень з інтерактивними кнопками та взаємодіями, замість повернення до Web UI або термінала. +Slack може працювати як нативний клієнт схвалень з інтерактивними кнопками та взаємодіями замість повернення до вебінтерфейсу або термінала. -- Схвалення exec використовують `channels.slack.execApprovals.*` для нативної маршрутизації DM/каналом. -- Схвалення Plugin усе ще можуть вирішуватися через ту саму нативну поверхню кнопок Slack, коли запит уже потрапляє в Slack, а вид ID схвалення — `plugin:`. -- Авторизація схвалювача все одно застосовується: лише користувачі, визначені як схвалювачі, можуть схвалювати або відхиляти запити через Slack. +- Схвалення exec використовують `channels.slack.execApprovals.*` для нативної маршрутизації DM/каналу. +- Схвалення Plugin все ще можуть оброблятися через ту саму нативну для Slack поверхню кнопок, коли запит уже потрапляє в Slack і тип id схвалення — `plugin:`. +- Авторизація схвалювачів усе ще застосовується: лише користувачі, визначені як схвалювачі, можуть схвалювати або відхиляти запити через Slack. Це використовує ту саму спільну поверхню кнопок схвалення, що й інші канали. Коли `interactivity` увімкнено в налаштуваннях вашого застосунку Slack, запити на схвалення відображаються як кнопки Block Kit безпосередньо в розмові. -Коли ці кнопки присутні, вони є основним UX схвалення; OpenClaw -має включати ручну команду `/approve` лише тоді, коли результат інструмента каже, що чат-схвалення -недоступні або ручне схвалення є єдиним шляхом. +Коли ці кнопки присутні, вони є основним UX для схвалення; OpenClaw +має включати ручну команду `/approve` лише тоді, коли результат інструмента повідомляє, що схвалення +в чаті недоступні або ручне схвалення є єдиним шляхом. Шлях конфігурації: - `channels.slack.execApprovals.enabled` - `channels.slack.execApprovals.approvers` (необов’язково; за можливості повертається до `commands.ownerAllowFrom`) -- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, стандартно: `dm`) +- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, типово: `dm`) - `agentFilter`, `sessionFilter` -Slack автоматично вмикає нативні схвалення exec, коли `enabled` не задано або має значення `"auto"` і принаймні один -схвалювач визначається. Установіть `enabled: false`, щоб явно вимкнути Slack як нативний клієнт схвалень. -Установіть `enabled: true`, щоб примусово ввімкнути нативні схвалення, коли визначаються схвалювачі. +Slack автоматично вмикає нативні схвалення exec, коли `enabled` не задано або має значення `"auto"` і визначено принаймні одного +схвалювача. Установіть `enabled: false`, щоб явно вимкнути Slack як нативний клієнт схвалень. +Установіть `enabled: true`, щоб примусово ввімкнути нативні схвалення, коли визначено схвалювачів. -Стандартна поведінка без явної конфігурації схвалень exec для Slack: +Типова поведінка без явної конфігурації схвалень exec у Slack: ```json5 { @@ -886,7 +1168,7 @@ Slack автоматично вмикає нативні схвалення exec ``` Явна нативна конфігурація Slack потрібна лише тоді, коли ви хочете перевизначити схвалювачів, додати фільтри або -увімкнути доставку в початковий чат: +увімкнути доставку в чат походження: ```json5 { @@ -902,25 +1184,25 @@ Slack автоматично вмикає нативні схвалення exec } ``` -Спільне переспрямування `approvals.exec` є окремим. Використовуйте його лише тоді, коли запити схвалення exec також мають +Спільне переспрямування `approvals.exec` є окремим. Використовуйте його лише тоді, коли запити на схвалення exec також мають маршрутизуватися до інших чатів або явних позасмугових цілей. Спільне переспрямування `approvals.plugin` також -окреме; нативні кнопки Slack все ще можуть вирішувати схвалення Plugin, коли ці запити вже потрапляють +окреме; нативні кнопки Slack усе ще можуть обробляти схвалення Plugin, коли ці запити вже потрапляють у Slack. -`/approve` у тому самому чаті також працює в каналах Slack і DM, які вже підтримують команди. Див. [Схвалення exec](/uk/tools/exec-approvals), щоб ознайомитися з повною моделлю переспрямування схвалень. +Same-chat `/approve` також працює в каналах Slack і DM, які вже підтримують команди. Див. [Схвалення exec](/uk/tools/exec-approvals), щоб переглянути повну модель переспрямування схвалень. ## Події та операційна поведінка - Редагування/видалення повідомлень відображаються в системні події. -- Трансляції тредів (відповіді в треді "Також надіслати в канал") обробляються як звичайні повідомлення користувачів. +- Трансляції тредів (відповіді треду з «Also send to channel») обробляються як звичайні повідомлення користувача. - Події додавання/видалення реакцій відображаються в системні події. - Події приєднання/виходу учасника, створення/перейменування каналу та додавання/видалення закріплення відображаються в системні події. -- `channel_id_changed` може мігрувати ключі конфігурації каналу, коли `configWrites` увімкнено. -- Метадані теми/призначення каналу вважаються недовіреним контекстом і можуть бути інжектовані в контекст маршрутизації. -- Початковий допис треду та початкове заповнення контексту історії треду фільтруються налаштованими списками дозволених відправників, коли це застосовно. -- Дії блоків і модальні взаємодії створюють структуровані системні події `Slack interaction: ...` з насиченими полями корисного навантаження: - - дії блоків: вибрані значення, мітки, значення вибирача та метадані `workflow_*` - - події модальних `view_submission` і `view_closed` з маршрутизованими метаданими каналу та введеннями форми +- `channel_id_changed` може мігрувати ключі конфігурації каналів, коли ввімкнено `configWrites`. +- Метадані теми/призначення каналу вважаються ненадійним контекстом і можуть бути вставлені в контекст маршрутизації. +- Початкове повідомлення треду та засівання початкового контексту історії треду фільтруються налаштованими allowlist відправників, коли це застосовно. +- Дії блоків і взаємодії з модальними вікнами створюють структуровані системні події `Slack interaction: ...` з насиченими полями payload: + - дії блоків: вибрані значення, мітки, значення picker та метадані `workflow_*` + - події modal `view_submission` і `view_closed` з метаданими маршрутизованого каналу та введеннями форми ## Довідник конфігурації @@ -934,7 +1216,7 @@ Slack автоматично вмикає нативні схвалення exec - доступ до каналу: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` - треди/історія: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - доставка: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress` -- операції/функції: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` +- ops/функції: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` @@ -942,12 +1224,12 @@ Slack автоматично вмикає нативні схвалення exec - Перевірте по порядку: + Перевірте в такому порядку: - `groupPolicy` - - список дозволених каналів (`channels.slack.channels`) — **ключі мають бути ID каналів** (`C12345678`), а не назвами (`#channel-name`). Ключі на основі назв непомітно не спрацьовують із `groupPolicy: "allowlist"`, оскільки маршрутизація каналів стандартно спершу використовує ID. Щоб знайти ID: клацніть канал у Slack правою кнопкою → **Копіювати посилання** — значення `C...` наприкінці URL є ID каналу. + - allowlist каналів (`channels.slack.channels`) — **ключі мають бути ID каналів** (`C12345678`), а не назвами (`#channel-name`). Ключі на основі назв тихо не спрацьовують за `groupPolicy: "allowlist"`, тому що маршрутизація каналів типово спершу використовує ID. Щоб знайти ID: клацніть канал у Slack правою кнопкою → **Copy link** — значення `C...` наприкінці URL є ID каналу. - `requireMention` - - поканальний список дозволених `users` + - поканальний allowlist `users` Корисні команди: @@ -964,7 +1246,7 @@ openclaw doctor - `channels.slack.dm.enabled` - `channels.slack.dmPolicy` (або застаріле `channels.slack.dm.policy`) - - схвалення спарювання / записи списку дозволених + - схвалення pairing / записи allowlist - події DM Slack Assistant: докладні журнали зі згадкою `drop message_changed` зазвичай означають, що Slack надіслав відредаговану подію треду Assistant без відновлюваного людського відправника в метаданих повідомлення @@ -976,124 +1258,124 @@ openclaw pairing list slack - Перевірте токени бота й застосунку та ввімкнення Socket Mode у налаштуваннях застосунку Slack. + Перевірте bot + app токени та ввімкнення Socket Mode у налаштуваннях застосунку Slack. Якщо `openclaw channels status --probe --json` показує `botTokenStatus` або `appTokenStatus: "configured_unavailable"`, обліковий запис Slack - налаштований, але поточне середовище виконання не змогло визначити значення, - підкріплене SecretRef. + налаштовано, але поточне середовище виконання не змогло визначити значення, + підтримане SecretRef. Перевірте: - - секрет підпису - - шлях Webhook - - URL запитів Slack (події + інтерактивність + Slash Commands) - - унікальний `webhookPath` для кожного облікового запису HTTP + - signing secret + - webhook path + - Slack Request URLs (Events + Interactivity + Slash Commands) + - унікальний `webhookPath` для кожного HTTP-облікового запису Якщо `signingSecretStatus: "configured_unavailable"` з’являється в знімках - облікових записів, обліковий запис HTTP налаштований, але поточне середовище виконання не змогло - визначити секрет підпису, підкріплений SecretRef. + облікового запису, HTTP-обліковий запис налаштовано, але поточне середовище виконання не змогло + визначити signing secret, підтриманий SecretRef. - Перевірте, що саме ви мали намір використати: + Перевірте, що саме ви мали на увазі: - режим нативних команд (`channels.slack.commands.native: true`) з відповідними slash-командами, зареєстрованими в Slack - або режим однієї slash-команди (`channels.slack.slashCommand.enabled: true`) - Також перевірте `commands.useAccessGroups` і списки дозволених каналів/користувачів. + Також перевірте `commands.useAccessGroups` і allowlist каналів/користувачів. -## Довідник vision для вкладень +## Довідник щодо бачення для вкладень -Slack може приєднувати завантажені медіа до ходу агента, коли завантаження файлів Slack успішні та обмеження розміру це дозволяють. Файли зображень можуть передаватися через шлях розуміння медіа або безпосередньо до моделі відповідей з підтримкою vision; інші файли зберігаються як завантажуваний файловий контекст, а не обробляються як вхідні зображення. +Slack може прикріплювати завантажені медіа до ходу агента, коли завантаження файлів Slack успішні й обмеження розміру це дозволяють. Файли зображень можуть передаватися через шлях розуміння медіа або безпосередньо до моделі відповіді з підтримкою vision; інші файли зберігаються як завантажуваний файловий контекст, а не обробляються як вхідні зображення. ### Підтримувані типи медіа -| Тип медіа | Джерело | Поточна поведінка | Примітки | -| ------------------------------ | -------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -| Зображення JPEG / PNG / GIF / WebP | URL файлу Slack | Завантажуються й долучаються до ходу для обробки з підтримкою зору | Ліміт на файл: `channels.slack.mediaMaxMb` (за замовчуванням 20 MB) | -| Файли PDF | URL файлу Slack | Завантажуються й надаються як файловий контекст для інструментів, як-от `download-file` або `pdf` | Вхідні повідомлення Slack не перетворюють PDF автоматично на вхідні дані для зору за зображеннями | -| Інші файли | URL файлу Slack | Завантажуються, коли це можливо, і надаються як файловий контекст | Двійкові файли не обробляються як вхідні зображення | -| Відповіді в гілці | Файли початкового повідомлення гілки | Файли кореневого повідомлення можуть бути завантажені як контекст, коли відповідь не має власних медіа | Початкові повідомлення лише з файлами використовують placeholder вкладення | -| Повідомлення з кількома зображеннями | Кілька файлів Slack | Кожен файл оцінюється незалежно | Обробка Slack обмежена вісьмома файлами на повідомлення | +| Тип медіа | Джерело | Поточна поведінка | Примітки | +| ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | +| Зображення JPEG / PNG / GIF / WebP | URL файлу Slack | Завантажуються й прикріплюються до ходу для обробки з підтримкою vision | Обмеження на файл: `channels.slack.mediaMaxMb` (типово 20 MB) | +| Файли PDF | URL файлу Slack | Завантажуються й доступні як файловий контекст для інструментів, як-от `download-file` або `pdf` | Вхідні дані Slack не перетворюють PDF автоматично на image-vision input | +| Інші файли | URL файлу Slack | Завантажуються, коли можливо, і доступні як файловий контекст | Бінарні файли не обробляються як вхідні зображення | +| Відповіді треду | Файли початкового повідомлення треду | Файли кореневого повідомлення можуть бути гідратовані як контекст, коли відповідь не має безпосередніх медіа | Стартери лише з файлами використовують placeholder вкладення | +| Повідомлення з кількома зображеннями | Кілька файлів Slack | Кожен файл оцінюється незалежно | Обробка Slack обмежена вісьмома файлами на повідомлення | -### Вхідний конвеєр +### Вхідний pipeline Коли надходить повідомлення Slack із файловими вкладеннями: -1. OpenClaw завантажує файл із приватної URL-адреси Slack за допомогою токена бота (`xoxb-...`). -2. Після успішного завантаження файл записується до сховища медіа. -3. Шляхи завантажених медіа й типи вмісту додаються до вхідного контексту. -4. Шляхи моделей/інструментів із підтримкою зору можуть використовувати вкладення зображень із цього контексту. +1. OpenClaw завантажує файл із приватного URL Slack, використовуючи bot token (`xoxb-...`). +2. У разі успіху файл записується до сховища медіа. +3. Завантажені шляхи медіа та типи вмісту додаються до вхідного контексту. +4. Шляхи моделі/інструментів із підтримкою зображень можуть використовувати вкладення зображень із цього контексту. 5. Файли, що не є зображеннями, залишаються доступними як файлові метадані або посилання на медіа для інструментів, які можуть їх обробляти. -### Успадкування вкладень кореня гілки +### Успадкування вкладень кореня треду -Коли повідомлення надходить у гілці (має батьківський `thread_ts`): +Коли повідомлення надходить у треді (має батьківський `thread_ts`): -- Якщо сама відповідь не має власних медіа, а включене кореневе повідомлення має файли, Slack може завантажити кореневі файли як контекст початкового повідомлення гілки. +- Якщо сама відповідь не має безпосередніх медіа, а включене кореневе повідомлення має файли, Slack може гідратувати кореневі файли як контекст стартера треду. - Безпосередні вкладення відповіді мають пріоритет над вкладеннями кореневого повідомлення. -- Кореневе повідомлення, яке має лише файли й не має тексту, представляється placeholder вкладення, щоб fallback усе ще міг включити його файли. +- Кореневе повідомлення, яке має лише файли й не має тексту, представляється з placeholder вкладенням, щоб fallback усе ще міг включити його файли. ### Обробка кількох вкладень Коли одне повідомлення Slack містить кілька файлових вкладень: -- Кожне вкладення обробляється незалежно через конвеєр медіа. -- Посилання на завантажені медіа агрегуються в контекст повідомлення. +- Кожне вкладення обробляється незалежно через медійний pipeline. +- Завантажені посилання на медіа агрегуються в контекст повідомлення. - Порядок обробки відповідає порядку файлів Slack у payload події. - Помилка завантаження одного вкладення не блокує інші. -### Обмеження розміру, завантаження й моделі +### Обмеження розміру, завантаження та моделей -- **Ліміт розміру**: За замовчуванням 20 MB на файл. Налаштовується через `channels.slack.mediaMaxMb`. -- **Помилки завантаження**: Файли, які Slack не може надати, прострочені URL-адреси, недоступні файли, завеликі файли та HTML-відповіді автентифікації/входу Slack пропускаються замість того, щоб повідомлятися як непідтримувані формати. -- **Модель зору**: Аналіз зображень використовує активну модель відповіді, якщо вона підтримує зір, або модель зображень, налаштовану в `agents.defaults.imageModel`. +- **Обмеження розміру**: типово 20 MB на файл. Налаштовується через `channels.slack.mediaMaxMb`. +- **Помилки завантаження**: файли, які Slack не може віддати, протерміновані URL, недоступні файли, надто великі файли та HTML-відповіді автентифікації/входу Slack пропускаються замість повідомлення як непідтримувані формати. +- **Vision model**: аналіз зображень використовує активну модель відповіді, коли вона підтримує vision, або модель зображень, налаштовану в `agents.defaults.imageModel`. ### Відомі обмеження -| Сценарій | Поточна поведінка | Обхідний шлях | -| ------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -| Прострочена URL-адреса файлу Slack | Файл пропущено; помилка не показується | Повторно завантажте файл у Slack | -| Модель зору не налаштована | Вкладення зображень зберігаються як посилання на медіа, але не аналізуються як зображення | Налаштуйте `agents.defaults.imageModel` або використайте модель відповіді з підтримкою зору | -| Дуже великі зображення (> 20 MB за замовчуванням) | Пропускаються згідно з лімітом розміру | Збільште `channels.slack.mediaMaxMb`, якщо Slack дозволяє | -| Переслані/поширені вкладення | Текст і розміщені в Slack медіа зображень/файлів обробляються за best-effort | Поширте повторно безпосередньо в гілці OpenClaw | -| Вкладення PDF | Зберігаються як файловий/медіаконтекст, але не маршрутизуються автоматично через зір за зображеннями | Використайте `download-file` для файлових метаданих або інструмент `pdf` для аналізу PDF | +| Сценарій | Поточна поведінка | Обхідний шлях | +| ------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | +| Прострочена URL-адреса файлу Slack | Файл пропущено; помилка не відображається | Повторно завантажте файл у Slack | +| Модель зору не налаштовано | Вкладення зображень зберігаються як медіапосилання, але не аналізуються як зображення | Налаштуйте `agents.defaults.imageModel` або використайте модель відповіді з підтримкою зору | +| Дуже великі зображення (> 20 MB за замовчуванням) | Пропущено відповідно до обмеження розміру | Збільште `channels.slack.mediaMaxMb`, якщо Slack дозволяє | +| Переслані/поширені вкладення | Текст і медіа зображень/файлів, розміщені в Slack, обробляються за принципом найкращих зусиль | Повторно поширте безпосередньо в потоці OpenClaw | +| PDF-вкладення | Зберігаються як контекст файлу/медіа, але не спрямовуються автоматично через зоровий аналіз зображень | Використайте `download-file` для метаданих файлу або інструмент `pdf` для аналізу PDF | ### Пов’язана документація - [Конвеєр розуміння медіа](/uk/nodes/media-understanding) - [Інструмент PDF](/uk/tools/pdf) -- Епік: [#51349](https://github.com/openclaw/openclaw/issues/51349) — увімкнення зору для вкладень Slack +- Епік: [#51349](https://github.com/openclaw/openclaw/issues/51349) — увімкнення зорового аналізу вкладень Slack - Регресійні тести: [#51353](https://github.com/openclaw/openclaw/issues/51353) -- Перевірка наживо: [#51354](https://github.com/openclaw/openclaw/issues/51354) +- Жива перевірка: [#51354](https://github.com/openclaw/openclaw/issues/51354) ## Пов’язане - - Прив’яжіть користувача Slack до Gateway. + + Сполучіть користувача Slack із Gateway. - - Поведінка каналів і групових особистих повідомлень. + + Поведінка каналу та групових DM. - + Маршрутизуйте вхідні повідомлення до агентів. - + Модель загроз і посилення захисту. - - Структура конфігурації та пріоритети. + + Структура конфігурації та пріоритетність. - + Каталог команд і поведінка. diff --git a/docs/uk/cli/doctor.md b/docs/uk/cli/doctor.md index e3e8649a1..366e57c8b 100644 --- a/docs/uk/cli/doctor.md +++ b/docs/uk/cli/doctor.md @@ -1,14 +1,14 @@ --- read_when: - - У вас проблеми з підключенням або автентифікацією, і вам потрібні покрокові виправлення - - Ви виконали оновлення й хочете провести базову перевірку -summary: Довідник CLI для `openclaw doctor` (перевірки працездатності + керовані виправлення) + - У вас виникли проблеми з підключенням або автентифікацією, і ви хочете отримати покрокові способи їх усунення + - Ви виконали оновлення й хочете базову перевірку +summary: Довідник CLI для `openclaw doctor` (перевірки стану + керовані виправлення) title: Діагностика x-i18n: - generated_at: "2026-05-03T21:48:54Z" + generated_at: "2026-05-05T01:21:15Z" model: gpt-5.5 provider: openai - source_hash: cd7fb09d373c313e4be45ad9e3b19ceb187a5787ef3e70fcd2b1f1f01b50c905 + source_hash: 079d7674ae2a259a0430e30e7577ac532135ad5461c57c4b3a6514a007bc9ea5 source_path: cli/doctor.md workflow: 16 --- @@ -17,7 +17,7 @@ x-i18n: Перевірки стану + швидкі виправлення для Gateway і каналів. -Пов’язане: +Пов’язано: - Усунення несправностей: [Усунення несправностей](/uk/gateway/troubleshooting) - Аудит безпеки: [Безпека](/uk/gateway/security) @@ -35,44 +35,44 @@ openclaw doctor --generate-gateway-token ## Параметри - `--no-workspace-suggestions`: вимкнути пропозиції пам’яті/пошуку робочої області -- `--yes`: приймати типові значення без запитів -- `--repair`: застосувати рекомендовані виправлення, не пов’язані зі службами, без запитів; установлення та перезапис служб Gateway усе ще потребують інтерактивного підтвердження або явних команд Gateway +- `--yes`: приймати стандартні значення без запитів +- `--repair`: застосувати рекомендовані виправлення, не пов’язані зі службами, без запитів; встановлення та перезапис служб Gateway все одно потребують інтерактивного підтвердження або явних команд Gateway - `--fix`: псевдонім для `--repair` - `--force`: застосувати агресивні виправлення, зокрема перезапис користувацької конфігурації служби за потреби -- `--non-interactive`: запуск без запитів; лише безпечні міграції та виправлення, не пов’язані зі службами +- `--non-interactive`: запускати без запитів; лише безпечні міграції та виправлення, не пов’язані зі службами - `--generate-gateway-token`: згенерувати й налаштувати токен Gateway -- `--deep`: просканувати системні служби на наявність додаткових установлень Gateway +- `--deep`: сканувати системні служби на наявність додаткових встановлень Gateway Примітки: -- Інтерактивні запити (наприклад, виправлення keychain/OAuth) виконуються лише тоді, коли stdin є TTY і **не** задано `--non-interactive`. Запуски без інтерфейсу (cron, Telegram, без термінала) пропускають запити. -- Продуктивність: неінтерактивні запуски `doctor` пропускають завчасне завантаження plugins, щоб перевірки стану без інтерфейсу залишалися швидкими. Інтерактивні сеанси все одно повністю завантажують plugins, коли перевірці потрібен їхній внесок. +- Інтерактивні запити (наприклад, виправлення 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`, якщо ви навмисно хочете замінити засіб запуску. -- Перевірки цілісності стану тепер виявляють осиротілі файли транскриптів у каталозі сеансів. Архівування їх як `.deleted.` потребує інтерактивного підтвердження; `--fix`, `--yes` і запуски без інтерфейсу залишають їх на місці. +- `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`; цей скрипт більше не підтримується і може журналювати хибні збої WhatsApp Gateway, коли cron не має середовища user-bus systemd. -- Doctor очищає застарілий стан підготовки залежностей plugin, створений старішими версіями OpenClaw. Він також відновлює відсутні налаштовані завантажувані plugins, коли реєстр може їх розпізнати, а прохід doctor 2026.5.2 автоматично встановлює завантажувані plugins, які вже використовує старіша конфігурація, перш ніж позначити конфігурацію як змінену для цього випуску. Якщо завантаження не вдається, 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 керує інший supervisor. Doctor усе ще повідомляє про стан Gateway/служби та застосовує виправлення, не пов’язані зі службами, але пропускає встановлення/запуск/перезапуск/bootstrap служби та очищення застарілих служб. -- У Linux doctor ігнорує неактивні додаткові systemd-юніти, схожі на Gateway, і не перезаписує метадані команди/точки входу для запущеної systemd-служби Gateway під час виправлення. Спершу зупиніть службу або використайте `openclaw gateway install --force`, якщо ви навмисно хочете замінити активний засіб запуску. -- Doctor автоматично мігрує застарілу пласку конфігурацію Talk (`talk.voiceId`, `talk.modelId` і пов’язані параметри) у `talk.provider` + `talk.providers.`. +- На 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.`. - Повторні запуски `doctor --fix` більше не повідомляють і не застосовують нормалізацію Talk, коли єдина різниця полягає в порядку ключів об’єкта. -- Doctor містить перевірку готовності пошуку в пам’яті та може рекомендувати `openclaw configure --section model`, коли відсутні облікові дані embeddings. -- Doctor попереджає, коли не налаштовано власника команд. Власник команд — це обліковий запис оператора-людини, якому дозволено запускати команди лише для власника та схвалювати небезпечні дії. Сполучення через DM лише дозволяє комусь говорити з ботом; якщо ви схвалили відправника до появи bootstrap першого власника, явно задайте `commands.ownerAllowFrom`. -- Doctor попереджає, коли налаштовано агентів у режимі Codex і особисті ресурси Codex CLI існують у Codex home оператора. Локальні запуски app-server Codex використовують ізольовані home для кожного агента, тож використайте `openclaw migrate codex --dry-run`, щоб інвентаризувати ресурси, які слід свідомо підвищити. -- Doctor попереджає, коли Skills, дозволені для типового агента, недоступні в поточному середовищі виконання, бо відсутні bins, змінні середовища, конфігурація або вимоги ОС. `doctor --fix` може вимкнути ці недоступні Skills через `skills.entries..enabled=false`; натомість установіть/налаштуйте відсутню вимогу, якщо хочете зберегти skill активним. -- Якщо режим пісочниці ввімкнено, але Docker недоступний, doctor повідомляє чітке попередження з виправленням (`install Docker` або `openclaw config set agents.defaults.sandbox.mode off`). -- Якщо присутні застарілі файли реєстру пісочниці (`~/.openclaw/sandbox/containers.json` або `~/.openclaw/sandbox/browsers.json`), doctor повідомляє про них; `openclaw doctor --fix` мігрує дійсні записи в сегментовані каталоги реєстру та ізолює недійсні застарілі файли. -- Якщо `gateway.auth.token`/`gateway.auth.password` керуються SecretRef і недоступні в поточному шляху команди, doctor повідомляє попередження лише для читання й не записує відкриті резервні облікові дані. -- Якщо інспекція SecretRef каналу зазнає невдачі в шляху виправлення, doctor продовжує роботу й повідомляє попередження замість раннього завершення. -- Після міграцій каталогу стану doctor попереджає, коли ввімкнені типові облікові записи Telegram або Discord залежать від резервного env, а `TELEGRAM_BOT_TOKEN` або `DISCORD_BOT_TOKEN` недоступний процесу doctor. -- Автоматичне розпізнавання імен користувачів Telegram `allowFrom` (`doctor --fix`) потребує доступного для розпізнавання токена Telegram у поточному шляху команди. Якщо інспекція токена недоступна, doctor повідомляє попередження й пропускає автоматичне розпізнавання для цього проходу. +- 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 повідомляє попередження й пропускає автоматичне визначення для цього проходу. ## macOS: перевизначення env `launchctl` -Якщо ви раніше запускали `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (або `...PASSWORD`), це значення перевизначає ваш файл конфігурації та може спричиняти постійні помилки “unauthorized”. +Якщо ви раніше запускали `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (або `...PASSWORD`), це значення перевизначає ваш файл конфігурації й може спричиняти постійні помилки “unauthorized”. ```bash launchctl getenv OPENCLAW_GATEWAY_TOKEN @@ -82,7 +82,7 @@ launchctl unsetenv OPENCLAW_GATEWAY_TOKEN launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD ``` -## Пов’язане +## Пов’язано - [Довідник CLI](/uk/cli) -- [Gateway doctor](/uk/gateway/doctor) +- [Doctor Gateway](/uk/gateway/doctor) diff --git a/docs/uk/cli/plugins.md b/docs/uk/cli/plugins.md index 1c5c366ec..9b3c5dc5b 100644 --- a/docs/uk/cli/plugins.md +++ b/docs/uk/cli/plugins.md @@ -1,36 +1,36 @@ --- read_when: - - Ви хочете встановити або керувати Plugin Gateway чи сумісними пакетами + - Ви хочете встановити або керувати плагінами Gateway чи сумісними бандлами - Ви хочете діагностувати збої завантаження Plugin sidebarTitle: Plugins -summary: Довідник CLI для `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor) +summary: Довідник CLI для `openclaw plugins` (список, встановлення, маркетплейс, видалення, увімкнення/вимкнення, діагностика) title: Plugins x-i18n: - generated_at: "2026-05-04T09:37:09Z" + generated_at: "2026-05-05T01:21:27Z" model: gpt-5.5 provider: openai - source_hash: f561ce098181b07f25db3520b1726162863469ac05fb4a3e786915257d97c9a4 + source_hash: 24d274f33213231eaed48ac848a9266802a2179ba0311ab18462ad783219095a source_path: cli/plugins.md workflow: 16 --- -Керуйте Plugin для Gateway, пакетами хуків і сумісними наборами. +Керуйте Gateway plugins, пакетами hook і сумісними bundles. - Посібник для кінцевих користувачів зі встановлення, увімкнення й усунення проблем із plugins. + Посібник для кінцевих користувачів зі встановлення, увімкнення та усунення несправностей plugins. - Короткі приклади встановлення, виведення списку, оновлення, видалення та публікації. + Короткі приклади для встановлення, перегляду списку, оновлення, видалення та публікації. - - Модель сумісності наборів. + + Модель сумісності bundle. - - Поля маніфесту та схема конфігурації. + + Поля manifest і схема config. - Посилення безпеки для встановлень Plugin. + Посилення безпеки для встановлення plugin. @@ -62,16 +62,16 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -Щоб дослідити повільне встановлення, інспектування, видалення або оновлення реєстру, запустіть -команду з `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. Трасування записує таймінги фаз -у stderr і залишає JSON-вивід придатним для парсингу. Див. [Налагодження](/uk/help/debugging#plugin-lifecycle-trace). +Для дослідження повільного встановлення, інспектування, видалення або оновлення registry запустіть +команду з `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. Trace записує фазові таймінги +до stderr і залишає JSON-вивід придатним для парсингу. Див. [Налагодження](/uk/help/debugging#plugin-lifecycle-trace). -Вбудовані plugins постачаються разом з OpenClaw. Деякі ввімкнені типово (наприклад, вбудовані провайдери моделей, вбудовані провайдери мовлення та вбудований браузерний Plugin); інші потребують `plugins enable`. +Bundled plugins постачаються разом з OpenClaw. Деякі увімкнені за замовчуванням (наприклад, bundled model providers, bundled speech providers і bundled browser plugin); інші потребують `plugins enable`. -Нативні OpenClaw plugins мають постачати `openclaw.plugin.json` з inline JSON Schema (`configSchema`, навіть якщо порожня). Сумісні набори натомість використовують власні маніфести наборів. +Native OpenClaw plugins мають постачати `openclaw.plugin.json` з inline JSON Schema (`configSchema`, навіть якщо вона порожня). Compatible bundles натомість використовують власні manifests bundle. -`plugins list` показує `Format: openclaw` або `Format: bundle`. Деталізований вивід list/info також показує підтип набору (`codex`, `claude` або `cursor`) плюс виявлені можливості набору. +`plugins list` показує `Format: openclaw` або `Format: bundle`. Детальний вивід list/info також показує підтип bundle (`codex`, `claude` або `cursor`) і виявлені можливості bundle. ### Встановлення @@ -93,108 +93,108 @@ openclaw plugins install --marketplace https://github.com// -Під час перехідного запуску голі імена пакетів типово встановлюються з npm. Використовуйте `clawhub:` для ClawHub. Ставтеся до встановлення Plugin як до запуску коду. Надавайте перевагу закріпленим версіям. +Голі назви packages під час launch cutover встановлюються з npm за замовчуванням. Використовуйте `clawhub:` для ClawHub. Ставтеся до встановлення plugin як до запуску коду. Віддавайте перевагу зафіксованим версіям. -`plugins search` надсилає запит до ClawHub щодо встановлюваних пакетів Plugin і друкує -готові до встановлення імена пакетів. Він шукає пакети code-plugin і bundle-plugin, +`plugins search` надсилає запит до ClawHub щодо доступних для встановлення packages plugin і виводить +готові до встановлення назви packages. Він шукає packages code-plugin і bundle-plugin, а не skills. Використовуйте `openclaw skills search` для ClawHub skills. ClawHub є основною поверхнею розповсюдження та пошуку для більшості plugins. Npm -залишається підтримуваним резервним і прямим шляхом встановлення. Пакети Plugin -`@openclaw/*`, що належать OpenClaw, знову публікуються в npm; див. поточний список +залишається підтримуваним fallback і шляхом прямого встановлення. Packages plugin, +що належать OpenClaw, `@openclaw/*` знову публікуються в npm; див. поточний список на [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) або [інвентар Plugin](/uk/plugins/plugin-inventory). Стабільні встановлення використовують `latest`. -Встановлення та оновлення beta-каналу надають перевагу npm `beta` dist-tag, коли такий тег +Встановлення й оновлення beta-channel віддають перевагу npm `beta` dist-tag, коли цей tag доступний, а потім повертаються до `latest`. - - Якщо ваш розділ `plugins` спирається на однофайловий `$include`, `plugins install/update/enable/disable/uninstall` записує зміни в цей включений файл і залишає `openclaw.json` без змін. Кореневі включення, масиви включень і включення з сусідніми перевизначеннями завершуються закрито замість сплющення. Див. [Включення конфігурації](/uk/gateway/configuration) щодо підтримуваних форм. + + Якщо ваш розділ `plugins` підтримується однофайловим `$include`, `plugins install/update/enable/disable/uninstall` записують зміни в цей включений файл і не змінюють `openclaw.json`. Root includes, масиви include та includes із sibling overrides завершуються закрито замість flattening. Див. [Config includes](/uk/gateway/configuration) щодо підтримуваних форм. - Якщо конфігурація некоректна під час встановлення, `plugins install` зазвичай завершується закрито й повідомляє, що спершу потрібно запустити `openclaw doctor --fix`. Під час запуску Gateway і гарячого перезавантаження некоректна конфігурація Plugin завершується закрито, як і будь-яка інша некоректна конфігурація; `openclaw doctor --fix` може помістити некоректний запис Plugin у карантин. Єдиний задокументований виняток під час встановлення — вузький шлях відновлення вбудованого Plugin для plugins, які явно вмикають `openclaw.install.allowInvalidConfigRecovery`. + Якщо config невалідна під час встановлення, `plugins install` зазвичай завершується закрито й просить спочатку запустити `openclaw doctor --fix`. Під час запуску Gateway і hot reload невалідна config plugin завершується закрито, як і будь-яка інша невалідна config; `openclaw doctor --fix` може ізолювати невалідний запис plugin. Єдиний задокументований виняток під час встановлення — вузький шлях відновлення bundled-plugin для plugins, які явно обирають `openclaw.install.allowInvalidConfigRecovery`. - - `--force` повторно використовує наявну ціль встановлення й перезаписує вже встановлений Plugin або пакет хуків на місці. Використовуйте його, коли ви навмисно перевстановлюєте той самий id з нового локального шляху, архіву, пакета ClawHub або артефакта npm. Для звичайних оновлень уже відстежуваного npm Plugin надавайте перевагу `openclaw plugins update `. + + `--force` повторно використовує наявну ціль встановлення й перезаписує вже встановлений plugin або hook pack на місці. Використовуйте це, коли ви навмисно перевстановлюєте той самий id з нового локального шляху, archive, package ClawHub або artifact npm. Для звичайних upgrade вже відстежуваного npm plugin віддавайте перевагу `openclaw plugins update `. - Якщо ви запускаєте `plugins install` для id Plugin, який уже встановлено, OpenClaw зупиняється й спрямовує вас до `plugins update ` для звичайного оновлення або до `plugins install --force`, коли ви справді хочете перезаписати поточне встановлення з іншого джерела. + Якщо ви запускаєте `plugins install` для вже встановленого id plugin, OpenClaw зупиняється й указує на `plugins update ` для звичайного upgrade або на `plugins install --force`, коли ви справді хочете перезаписати поточне встановлення з іншого джерела. - `--pin` застосовується лише до встановлень npm. Він не підтримується з установленнями `git:`; використовуйте явне посилання git, наприклад `git:github.com/acme/plugin@v1.2.3`, коли потрібне закріплене джерело. Він не підтримується з `--marketplace`, оскільки встановлення з маркетплейсу зберігають метадані джерела маркетплейсу замість npm spec. + `--pin` застосовується лише до npm installs. Він не підтримується з `git:` installs; використовуйте явний git ref, наприклад `git:github.com/acme/plugin@v1.2.3`, коли хочете зафіксоване джерело. Він не підтримується з `--marketplace`, оскільки marketplace installs зберігають metadata джерела marketplace замість npm spec. - `--dangerously-force-unsafe-install` — це аварійний параметр для хибних спрацьовувань у вбудованому сканері небезпечного коду. Він дозволяє продовжити встановлення, навіть коли вбудований сканер повідомляє про знахідки `critical`, але **не** обходить блокування політик хука `before_install` Plugin і **не** обходить збої сканування. + `--dangerously-force-unsafe-install` — це аварійний варіант для хибних спрацювань у вбудованому сканері небезпечного коду. Він дозволяє встановленню продовжитися, навіть коли вбудований scanner повідомляє про findings рівня `critical`, але він **не** обходить blocks політики hook `before_install` plugin і **не** обходить failures сканування. - Цей прапорець CLI застосовується до потоків встановлення/оновлення Plugin. Встановлення залежностей skill через Gateway використовують відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком завантаження/встановлення ClawHub skill. + Цей CLI flag застосовується до потоків install/update plugin. Gateway-backed installs залежностей skill використовують відповідний request override `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком завантаження/встановлення skill з ClawHub. - Якщо Plugin, який ви опублікували на ClawHub, заблоковано скануванням реєстру, скористайтеся кроками для видавця в [ClawHub](/uk/tools/clawhub). + Якщо plugin, який ви опублікували на ClawHub, заблокований registry scan, скористайтеся кроками publisher у [ClawHub](/uk/tools/clawhub). - - `plugins install` також є поверхнею встановлення для пакетів хуків, які надають `openclaw.hooks` у `package.json`. Використовуйте `openclaw hooks` для фільтрованої видимості хуків і ввімкнення окремих хуків, а не для встановлення пакетів. + + `plugins install` також є поверхнею встановлення для hook packs, які експонують `openclaw.hooks` у `package.json`. Використовуйте `openclaw hooks` для фільтрованої видимості hooks і ввімкнення окремих hooks, а не для встановлення package. - Npm specs є **лише реєстровими** (ім’я пакета + необов’язкова **точна версія** або **dist-tag**). Git/URL/file specs і діапазони semver відхиляються. Встановлення залежностей виконується локально для проєкту з `--ignore-scripts` заради безпеки, навіть якщо ваша оболонка має глобальні налаштування встановлення npm. + Npm specs є **лише registry-only** (назва package + необов’язкова **точна версія** або **dist-tag**). Git/URL/file specs і semver ranges відхиляються. Dependency installs виконуються project-local з `--ignore-scripts` для безпеки, навіть коли ваша shell має глобальні налаштування npm install. - Використовуйте `npm:`, коли хочете зробити npm-розв’язання явним. Під час перехідного запуску голі package specs також встановлюються напряму з npm. + Використовуйте `npm:`, коли хочете зробити npm resolution явним. Голі package specs також встановлюються безпосередньо з npm під час launch cutover. - Голі specs і `@latest` залишаються на стабільному каналі. Версії виправлень OpenClaw із датою, як-от `2026.5.3-1`, є стабільними релізами для цієї перевірки. Якщо npm розв’язує будь-який із них у prerelease, OpenClaw зупиняється й просить вас явно погодитися за допомогою prerelease-тега, як-от `@beta`/`@rc`, або точної prerelease-версії, як-от `@1.2.3-beta.4`. + Bare specs і `@latest` залишаються на stable track. OpenClaw date-stamped correction versions, як-от `2026.5.3-1`, є stable releases для цієї перевірки. Якщо npm resolve будь-який із них у prerelease, OpenClaw зупиняється й просить вас явно погодитися через prerelease tag, наприклад `@beta`/`@rc`, або точну prerelease version, наприклад `@1.2.3-beta.4`. - Якщо голий spec встановлення збігається з офіційним id Plugin (наприклад `diffs`), OpenClaw встановлює запис каталогу напряму. Щоб установити npm-пакет із тією самою назвою, використовуйте явний scoped spec (наприклад `@scope/diffs`). + Якщо bare install spec збігається з офіційним id plugin (наприклад `diffs`), OpenClaw встановлює catalog entry безпосередньо. Щоб встановити npm package з такою самою назвою, використовуйте явний scoped spec (наприклад `@scope/diffs`). - - Використовуйте `git:` для встановлення напряму з репозиторію git. Підтримувані форми включають `git:github.com/owner/repo`, `git:owner/repo`, повні URL клонування `https://`, `ssh://`, `git://`, `file://` і `git@host:owner/repo.git`. Додайте `@` або `#`, щоб отримати гілку, тег або коміт перед встановленням. + + Використовуйте `git:`, щоб встановлювати безпосередньо з git repository. Підтримувані форми включають `git:github.com/owner/repo`, `git:owner/repo`, повні clone URLs `https://`, `ssh://`, `git://`, `file://` і `git@host:owner/repo.git`. Додайте `@` або `#`, щоб checkout branch, tag або commit перед встановленням. - Установлення Git клонують у тимчасовий каталог, отримують запитаний ref, якщо він присутній, а потім використовують звичайний інсталятор каталогу Plugin. Це означає, що валідація маніфесту, сканування небезпечного коду, робота встановлення менеджера пакетів і записи встановлення поводяться як npm-встановлення. Записані git-встановлення містять URL/ref джерела плюс розв’язаний коміт, щоб `openclaw plugins update` міг пізніше повторно розв’язати джерело. + Git installs клонують у тимчасовий directory, checkout requested ref, коли він є, а потім використовують звичайний installer directory plugin. Це означає, що validation manifest, dangerous-code scanning, package-manager install work і install records поводяться як npm installs. Записані git installs включають source URL/ref плюс resolved commit, щоб `openclaw plugins update` міг пізніше повторно resolve джерело. - Після встановлення з git використовуйте `openclaw plugins inspect --runtime --json`, щоб перевірити runtime-реєстрації, як-от методи gateway і команди CLI. Якщо Plugin зареєстрував CLI-корінь через `api.registerCli`, виконайте цю команду напряму через кореневий CLI OpenClaw, наприклад `openclaw demo-plugin ping`. + Після встановлення з git використовуйте `openclaw plugins inspect --runtime --json`, щоб перевірити runtime registrations, як-от gateway methods і CLI commands. Якщо plugin зареєстрував CLI root через `api.registerCli`, виконайте цю command безпосередньо через root CLI OpenClaw, наприклад `openclaw demo-plugin ping`. - - Підтримувані архіви: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Архіви нативних OpenClaw Plugin мають містити валідний `openclaw.plugin.json` у корені розпакованого Plugin; архіви, що містять лише `package.json`, відхиляються до того, як OpenClaw записує записи встановлення. + + Підтримувані archives: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Archives native OpenClaw plugin мають містити валідний `openclaw.plugin.json` у extracted plugin root; archives, які містять лише `package.json`, відхиляються до того, як OpenClaw запише install records. - Установлення з маркетплейсу Claude також підтримуються. + Claude marketplace installs також підтримуються. -Встановлення ClawHub використовують явний локатор `clawhub:`: +ClawHub installs використовують явний locator `clawhub:`: ```bash openclaw plugins install clawhub:openclaw-codex-app-server openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3 ``` -Голі npm-safe specs Plugin типово встановлюються з npm під час перехідного запуску: +Bare npm-safe plugin specs під час launch cutover встановлюються з npm за замовчуванням: ```bash openclaw plugins install openclaw-codex-app-server ``` -Використовуйте `npm:`, щоб зробити npm-only розв’язання явним: +Використовуйте `npm:`, щоб зробити npm-only resolution явним: ```bash openclaw plugins install npm:openclaw-codex-app-server openclaw plugins install npm:@scope/plugin-name@1.0.1 ``` -OpenClaw перевіряє оголошену сумісність plugin API / мінімального gateway перед встановленням. Коли вибрана версія ClawHub публікує артефакт ClawPack, OpenClaw завантажує версійний npm-pack `.tgz`, перевіряє digest-заголовок ClawHub і digest артефакта, а потім встановлює його через звичайний шлях архіву. Старіші версії ClawHub без метаданих ClawPack усе ще встановлюються через застарілий шлях перевірки архіву пакета. Записані встановлення зберігають свої метадані джерела ClawHub, тип артефакта, npm integrity, npm shasum, ім’я tarball і факти digest ClawPack для подальших оновлень. -Неверсійовані встановлення ClawHub зберігають неверсійований записаний spec, щоб `openclaw plugins update` міг відстежувати новіші релізи ClawHub; явні селектори версії або тега, як-от `clawhub:pkg@1.2.3` і `clawhub:pkg@beta`, залишаються закріпленими за цим селектором. +OpenClaw перевіряє оголошену сумісність plugin API / minimum gateway перед встановленням. Коли вибрана версія ClawHub публікує artifact ClawPack, OpenClaw завантажує versioned npm-pack `.tgz`, перевіряє digest header ClawHub і artifact digest, а потім встановлює його через звичайний archive path. Старіші версії ClawHub без metadata ClawPack все ще встановлюються через legacy package archive verification path. Записані installs зберігають ClawHub source metadata, artifact kind, npm integrity, npm shasum, tarball name і ClawPack digest facts для подальших оновлень. +Unversioned ClawHub installs зберігають unversioned recorded spec, щоб `openclaw plugins update` міг відстежувати новіші releases ClawHub; explicit version або tag selectors, як-от `clawhub:pkg@1.2.3` і `clawhub:pkg@beta`, залишаються pinned до цього selector. -#### Скорочення маркетплейсу +#### Скорочення marketplace -Використовуйте скорочення `plugin@marketplace`, коли назва маркетплейсу існує в локальному кеші реєстру Claude за адресою `~/.claude/plugins/known_marketplaces.json`: +Використовуйте скорочення `plugin@marketplace`, коли назва marketplace існує в local registry cache Claude за адресою `~/.claude/plugins/known_marketplaces.json`: ```bash openclaw plugins marketplace list openclaw plugins install @ ``` -Використовуйте `--marketplace`, коли хочете явно передати джерело маркетплейсу: +Використовуйте `--marketplace`, коли хочете явно передати джерело marketplace: ```bash openclaw plugins install --marketplace @@ -206,26 +206,26 @@ openclaw plugins install --marketplace ./my-marketplace - назва відомого маркетплейсу Claude з `~/.claude/plugins/known_marketplaces.json` - - корінь локального маркетплейсу або шлях `marketplace.json` + - локальний корінь маркетплейсу або шлях до `marketplace.json` - скорочення репозиторію GitHub, як-от `owner/repo` - URL репозиторію GitHub, як-от `https://github.com/owner/repo` - - URL git + - git URL - Для віддалених маркетплейсів, завантажених із GitHub або git, записи плагінів мають залишатися всередині клонованого репозиторію маркетплейсу. OpenClaw приймає джерела відносних шляхів із цього репозиторію та відхиляє HTTP(S), абсолютні шляхи, git, GitHub та інші непутьові джерела плагінів із віддалених маніфестів. + Для віддалених маркетплейсів, завантажених із GitHub або git, записи плагінів мають залишатися всередині клонованого репозиторію маркетплейсу. OpenClaw приймає джерела з відносним шляхом із цього репозиторію та відхиляє HTTP(S), абсолютні шляхи, git, GitHub та інші непутеві джерела плагінів із віддалених маніфестів. -Для локальних шляхів і архівів OpenClaw автоматично визначає: +Для локальних шляхів і архівів OpenClaw автоматично виявляє: - нативні плагіни OpenClaw (`openclaw.plugin.json`) - сумісні з Codex пакети (`.codex-plugin/plugin.json`) -- сумісні з Claude пакети (`.claude-plugin/plugin.json` або типовий макет компонентів Claude) +- сумісні з Claude пакети (`.claude-plugin/plugin.json` або стандартний макет компонентів Claude) - сумісні з Cursor пакети (`.cursor-plugin/plugin.json`) -Сумісні пакети встановлюються у звичайний корінь плагінів і беруть участь у тому самому потоці list/info/enable/disable. Наразі підтримуються Skills пакета, command-Skills Claude, типові значення Claude `settings.json`, типові значення Claude `.lsp.json` / оголошені в маніфесті `lspServers`, command-Skills Cursor і сумісні каталоги хуків Codex; інші виявлені можливості пакетів показуються в діагностиці/info, але ще не підключені до виконання під час роботи. +Сумісні пакети встановлюються у звичайний корінь плагінів і беруть участь у тому самому потоці list/info/enable/disable. Наразі підтримуються Skills пакетів, командні Skills Claude, стандартні значення Claude `settings.json`, стандартні значення Claude `.lsp.json` / оголошених у маніфесті `lspServers`, командні Skills Cursor і сумісні каталоги хуків Codex; інші виявлені можливості пакетів показуються в діагностиці/info, але ще не підключені до виконання під час роботи. ### Список @@ -241,59 +241,59 @@ openclaw plugins search --json ``` - Показувати лише ввімкнені плагіни. + Показати лише ввімкнені плагіни. - Перемкнутися з табличного подання на рядки деталізації для кожного плагіна з метаданими джерела/походження/версії/активації. + Перемкнутися з табличного подання на детальні рядки для кожного плагіна з метаданими джерела/походження/версії/активації. - Машиночитний інвентар, а також діагностика реєстру й стан встановлення залежностей пакетів. + Машиночитаний інвентар, а також діагностика реєстру та стан встановлення залежностей пакета. -`plugins list` спочатку читає збережений локальний реєстр плагінів із резервним варіантом, виведеним лише з маніфестів, коли реєстр відсутній або недійсний. Це корисно для перевірки, чи плагін встановлено, увімкнено та видно для планування холодного запуску, але це не live-перевірка runtime уже запущеного процесу Gateway. Після зміни коду плагіна, увімкнення, політики хуків або `plugins.load.paths` перезапустіть Gateway, який обслуговує канал, перш ніж очікувати запуску нового коду `register(api)` або хуків. Для віддалених/контейнерних розгортань перевірте, що перезапускаєте фактичний дочірній процес `openclaw gateway run`, а не лише процес-обгортку. +`plugins list` спочатку читає збережений локальний реєстр плагінів, із запасним варіантом, виведеним лише з маніфесту, коли реєстр відсутній або недійсний. Це корисно для перевірки, чи плагін встановлено, увімкнено та видно для планування холодного запуску, але це не live-зонд середовища виконання для вже запущеного процесу Gateway. Після зміни коду плагіна, увімкнення, політики хуків або `plugins.load.paths` перезапустіть Gateway, який обслуговує канал, перш ніж очікувати запуску нового коду `register(api)` або хуків. Для віддалених/контейнерних розгортань перевірте, що ви перезапускаєте фактичний дочірній процес `openclaw gateway run`, а не лише процес-обгортку. -`plugins list --json` містить `dependencyStatus` кожного плагіна з `package.json` -`dependencies` і `optionalDependencies`. OpenClaw перевіряє, чи ці назви пакетів -наявні вздовж звичайного шляху пошуку Node `node_modules` для плагіна; він -не імпортує runtime-код плагіна, не запускає менеджер пакетів і не виправляє -відсутні залежності. +`plugins list --json` включає `dependencyStatus` кожного плагіна з `package.json` +`dependencies` і `optionalDependencies`. OpenClaw перевіряє, чи присутні ці назви пакетів +уздовж звичайного шляху пошуку Node `node_modules` для плагіна; він +не імпортує код виконання плагіна, не запускає менеджер пакетів і не відновлює відсутні +залежності. -`plugins search` — це пошук у віддаленому каталозі ClawHub. Він не перевіряє локальний -стан, не змінює конфігурацію, не встановлює пакети й не завантажує runtime-код плагіна. Результати пошуку -містять назву пакета ClawHub, сімейство, канал, версію, короткий опис і +`plugins search` — це віддалений пошук у каталозі ClawHub. Він не перевіряє локальний +стан, не змінює конфігурацію, не встановлює пакети й не завантажує код виконання плагіна. Результати пошуку +містять назву пакета ClawHub, сімейство, канал, версію, підсумок і підказку для встановлення, як-от `openclaw plugins install clawhub:`. -Для роботи з bundled plugin усередині запакованого Docker-образу змонтуйте з прив'язкою -каталог джерел плагіна поверх відповідного запакованого шляху джерел, як-от -`/app/extensions/synology-chat`. OpenClaw виявить це змонтоване накладання джерел -перед `/app/dist/extensions/synology-chat`; звичайно скопійований каталог джерел -залишається неактивним, тож звичайні запаковані встановлення й далі використовують скомпільований dist. +Для роботи з вбудованими плагінами всередині запакованого образу Docker змонтуйте через bind-mount каталог +джерела плагіна поверх відповідного запакованого шляху джерела, наприклад +`/app/extensions/synology-chat`. OpenClaw виявить цей змонтований +оверлей джерела перед `/app/dist/extensions/synology-chat`; звичайний скопійований каталог +джерела залишається неактивним, тож звичайні запаковані встановлення все одно використовують скомпільований dist. -Для налагодження runtime-хуків: +Для налагодження хуків під час роботи: -- `openclaw plugins inspect --runtime --json` показує зареєстровані хуки та діагностику з проходу інспекції із завантаженим модулем. Runtime-інспекція ніколи не встановлює залежності; використовуйте `openclaw doctor --fix`, щоб очистити застарілий стан залежностей або встановити відсутні налаштовані завантажувані плагіни. -- `openclaw gateway status --deep --require-rpc` підтверджує доступний Gateway, підказки сервісу/процесу, шлях конфігурації та справність RPC. -- Невбудовані хуки розмови (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) потребують `plugins.entries..hooks.allowConversationAccess=true`. +- `openclaw plugins inspect --runtime --json` показує зареєстровані хуки та діагностику з проходу інспекції із завантаженням модуля. Інспекція під час роботи ніколи не встановлює залежності; використовуйте `openclaw doctor --fix`, щоб очистити застарілий стан залежностей або відновити відсутні завантажувані плагіни, на які посилається конфігурація. +- `openclaw gateway status --deep --require-rpc` підтверджує доступний Gateway, підказки служби/процесу, шлях конфігурації та справність RPC. +- Невбудовані хуки розмов (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) потребують `plugins.entries..hooks.allowConversationAccess=true`. -Використовуйте `--link`, щоб не копіювати локальний каталог (додає до `plugins.load.paths`): +Використовуйте `--link`, щоб уникнути копіювання локального каталогу (додає до `plugins.load.paths`): ```bash openclaw plugins install -l ./my-plugin ``` -`--force` не підтримується з `--link`, оскільки пов'язані встановлення повторно використовують шлях джерела замість копіювання поверх керованої цілі встановлення. +`--force` не підтримується з `--link`, оскільки пов’язані встановлення повторно використовують шлях джерела замість копіювання поверх керованої цілі встановлення. -Використовуйте `--pin` для npm-встановлень, щоб зберегти розв'язану точну специфікацію (`name@version`) у керованому індексі плагінів, залишаючи типову поведінку без закріплення. +Використовуйте `--pin` для npm-встановлень, щоб зберегти розв’язану точну специфікацію (`name@version`) у керованому індексі плагінів, залишаючи стандартну поведінку незакріпленою. ### Індекс Plugin -Метадані встановлення Plugin — це стан, керований машиною, а не конфігурація користувача. Встановлення й оновлення записують його до `plugins/installs.json` в активному каталозі стану OpenClaw. Його верхньорівнева мапа `installRecords` є сталим джерелом метаданих встановлення, включно із записами для пошкоджених або відсутніх маніфестів плагінів. Масив `plugins` — це холодний кеш реєстру, виведений із маніфестів. Файл містить попередження не редагувати його та використовується `openclaw plugins update`, видаленням, діагностикою й холодним реєстром плагінів. +Метадані встановлення Plugin — це керований машиною стан, а не користувацька конфігурація. Встановлення й оновлення записують його до `plugins/installs.json` в активному каталозі стану OpenClaw. Його мапа верхнього рівня `installRecords` є довговічним джерелом метаданих встановлення, зокрема записів для пошкоджених або відсутніх маніфестів плагінів. Масив `plugins` — це кеш холодного реєстру, виведений із маніфесту. Файл містить попередження не редагувати його та використовується `openclaw plugins update`, видаленням, діагностикою та холодним реєстром плагінів. -Коли OpenClaw бачить поставлені застарілі записи `plugins.installs` у конфігурації, він переміщує їх в індекс плагінів і видаляє ключ конфігурації; якщо будь-який запис не вдається, записи конфігурації зберігаються, щоб метадані встановлення не було втрачено. +Коли OpenClaw бачить доставлені застарілі записи `plugins.installs` у конфігурації, він переміщує їх в індекс плагінів і видаляє ключ конфігурації; якщо будь-який запис не вдається, записи конфігурації зберігаються, щоб метадані встановлення не було втрачено. ### Видалення @@ -303,7 +303,7 @@ openclaw plugins uninstall --dry-run openclaw plugins uninstall --keep-files ``` -`uninstall` видаляє записи плагіна з `plugins.entries`, збереженого індексу плагінів, записів списків дозволу/заборони плагінів і пов'язаних записів `plugins.load.paths`, коли це застосовно. Якщо `--keep-files` не задано, видалення також вилучає відстежуваний керований каталог встановлення, коли він розташований усередині кореня розширень плагінів OpenClaw. Для плагінів Active Memory слот пам'яті скидається до `memory-core`. +`uninstall` видаляє записи плагіна з `plugins.entries`, збереженого індексу плагінів, записів списків дозволу/заборони плагінів і пов’язаних записів `plugins.load.paths`, коли це застосовно. Якщо не встановлено `--keep-files`, видалення також прибирає відстежуваний керований каталог встановлення, коли він розташований усередині кореня розширень плагінів OpenClaw. Для плагінів active memory слот пам’яті скидається до `memory-core`. `--keep-config` підтримується як застарілий псевдонім для `--keep-files`. @@ -322,26 +322,26 @@ openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-ins Оновлення застосовуються до відстежуваних встановлень плагінів у керованому індексі плагінів і відстежуваних встановлень hook-pack у `hooks.internal.installs`. - - Коли ви передаєте ідентифікатор плагіна, OpenClaw повторно використовує записану специфікацію встановлення для цього плагіна. Це означає, що раніше збережені dist-теги, як-от `@beta`, і точні закріплені версії й надалі використовуються під час пізніших запусків `update `. + + Коли ви передаєте id плагіна, OpenClaw повторно використовує записану специфікацію встановлення для цього плагіна. Це означає, що раніше збережені dist-теги, як-от `@beta`, і точні закріплені версії продовжують використовуватися під час подальших запусків `update `. - Для npm-встановлень ви також можете передати явну специфікацію npm-пакета з dist-тегом або точною версією. OpenClaw розв'язує цю назву пакета назад до відстежуваного запису плагіна, оновлює цей встановлений плагін і записує нову npm-специфікацію для майбутніх оновлень на основі ідентифікатора. + Для npm-встановлень ви також можете передати явну специфікацію npm-пакета з dist-тегом або точною версією. OpenClaw розв’язує цю назву пакета назад до відстежуваного запису плагіна, оновлює цей установлений плагін і записує нову npm-специфікацію для майбутніх оновлень на основі id. - Передавання назви npm-пакета без версії або тегу також розв'язується назад до відстежуваного запису плагіна. Використовуйте це, коли плагін було закріплено до точної версії, а ви хочете повернути його до типової лінії випусків реєстру. + Передавання назви npm-пакета без версії або тегу також розв’язується назад до відстежуваного запису плагіна. Використовуйте це, коли плагін було закріплено до точної версії, а ви хочете повернути його до стандартної лінії випусків реєстру. - - `openclaw plugins update` повторно використовує відстежувану специфікацію плагіна, якщо ви не передаєте нову специфікацію. `openclaw update` додатково знає активний канал оновлень OpenClaw: на бета-каналі записи плагінів npm і ClawHub типової лінії спочатку пробують `@beta`, а потім повертаються до записаної типової/останньої специфікації, якщо бета-випуску плагіна не існує. Точні версії та явні теги залишаються закріпленими за цим селектором. + + `openclaw plugins update` повторно використовує відстежувану специфікацію плагіна, якщо ви не передаєте нову специфікацію. `openclaw update` додатково знає активний канал оновлень OpenClaw: на beta-каналі записи плагінів npm і ClawHub зі стандартної лінії спершу пробують `@beta`, а потім повертаються до записаної стандартної/latest-специфікації, якщо beta-випуску плагіна не існує. Точні версії та явні теги залишаються закріпленими до цього селектора. - Перед live-оновленням npm OpenClaw перевіряє встановлену версію пакета щодо метаданих npm-реєстру. Якщо встановлена версія та записана ідентичність артефакта вже збігаються з розв'язаною ціллю, оновлення пропускається без завантаження, повторного встановлення або переписування `openclaw.json`. + Перед live-оновленням npm OpenClaw перевіряє встановлену версію пакета за метаданими реєстру npm. Якщо встановлена версія та записана ідентичність артефакта вже збігаються з розв’язаною ціллю, оновлення пропускається без завантаження, перевстановлення або перезапису `openclaw.json`. - Коли збережений хеш цілісності існує, а хеш отриманого артефакта змінюється, OpenClaw трактує це як дрейф npm-артефакта. Інтерактивна команда `openclaw plugins update` друкує очікуваний і фактичний хеші та запитує підтвердження перед продовженням. Неінтерактивні помічники оновлення завершуються відмовою за замовчуванням, якщо викликач не надає явну політику продовження. + Коли збережений хеш цілісності існує, а хеш отриманого артефакта змінюється, OpenClaw розглядає це як дрейф артефакта npm. Інтерактивна команда `openclaw plugins update` друкує очікуваний і фактичний хеші та запитує підтвердження перед продовженням. Неінтерактивні помічники оновлення завершуються закрито, якщо викликач не надає явну політику продовження. - `--dangerously-force-unsafe-install` також доступний у `plugins update` як екстрене перевизначення для хибних спрацьовувань вбудованого сканування небезпечного коду під час оновлень плагінів. Він усе одно не обходить блокування політики `before_install` плагіна або блокування через помилку сканування, і застосовується лише до оновлень плагінів, а не до оновлень hook-pack. + `--dangerously-force-unsafe-install` також доступний у `plugins update` як аварійний override для хибних спрацювань вбудованого сканування небезпечного коду під час оновлень плагінів. Він усе одно не обходить блокування політики `before_install` плагіна або блокування через невдале сканування, і застосовується лише до оновлень плагінів, а не оновлень hook-pack. @@ -353,34 +353,34 @@ openclaw plugins inspect --runtime openclaw plugins inspect --json ``` -Inspect показує ідентичність, стан завантаження, джерело, можливості маніфесту, прапорці політик, діагностику, метадані встановлення, можливості пакета та будь-яку виявлену підтримку серверів MCP або LSP без імпорту runtime плагіна за замовчуванням. Додайте `--runtime`, щоб завантажити модуль плагіна та включити зареєстровані хуки, інструменти, команди, сервіси, методи Gateway і HTTP-маршрути. Runtime-інспекція повідомляє про відсутні залежності плагіна напряму; встановлення та виправлення залишаються в `openclaw plugins install`, `openclaw plugins update` і `openclaw doctor --fix`. +Inspect показує ідентичність, стан завантаження, джерело, можливості маніфесту, прапорці політики, діагностику, метадані встановлення, можливості пакета та будь-яку виявлену підтримку серверів MCP або LSP без імпорту коду виконання плагіна за замовчуванням. Додайте `--runtime`, щоб завантажити модуль плагіна та включити зареєстровані хуки, інструменти, команди, служби, методи Gateway і HTTP-маршрути. Інспекція під час роботи напряму повідомляє про відсутні залежності плагіна; встановлення та відновлення залишаються в `openclaw plugins install`, `openclaw plugins update` і `openclaw doctor --fix`. -CLI-команди, якими володіє плагін, встановлюються як кореневі групи команд `openclaw`. Після того як `inspect --runtime` покаже команду в `cliCommands`, запускайте її як `openclaw ...`; наприклад, плагін, що реєструє `demo-git`, можна перевірити через `openclaw demo-git ping`. +CLI-команди, що належать плагінам, установлюються як кореневі групи команд `openclaw`. Після того як `inspect --runtime` покаже команду в `cliCommands`, запускайте її як `openclaw ...`; наприклад, плагін, який реєструє `demo-git`, можна перевірити за допомогою `openclaw demo-git ping`. -Кожен плагін класифікується за тим, що він фактично реєструє під час виконання: +Кожен плагін класифікується за тим, що він фактично реєструє під час роботи: -- **plain-capability** — один тип можливостей (наприклад, плагін лише провайдера) +- **plain-capability** — один тип можливості (наприклад, плагін лише для провайдера) - **hybrid-capability** — кілька типів можливостей (наприклад, текст + мовлення + зображення) - **hook-only** — лише хуки, без можливостей або поверхонь -- **non-capability** — інструменти/команди/сервіси, але без можливостей +- **non-capability** — інструменти/команди/служби, але без можливостей Див. [Форми Plugin](/uk/plugins/architecture#plugin-shapes), щоб дізнатися більше про модель можливостей. -Прапорець `--json` виводить машиночитний звіт, придатний для скриптів і аудиту. `inspect --all` відображає таблицю для всього набору зі стовпцями форми, видів можливостей, приміток сумісності, можливостей пакета та підсумку хуків. `info` — псевдонім для `inspect`. +Прапорець `--json` виводить машиночитаний звіт, придатний для скриптів і аудиту. `inspect --all` рендерить таблицю для всього парку з колонками форми, типів можливостей, повідомлень про сумісність, можливостей пакета та підсумку хуків. `info` є псевдонімом для `inspect`. -### Діагностика +### Doctor ```bash openclaw plugins doctor ``` -`doctor` повідомляє про помилки завантаження плагінів, діагностику маніфестів/виявлення та примітки сумісності. Коли все чисто, він друкує `No plugin issues detected.` +`doctor` повідомляє про помилки завантаження плагінів, діагностику маніфесту/виявлення та повідомлення про сумісність. Коли все чисто, він друкує `No plugin issues detected.` -Якщо налаштований плагін наявний на диску, але заблокований перевірками безпеки шляхів завантажувача, валідація конфігурації зберігає запис плагіна й повідомляє про нього як `present but blocked`. Виправте попередню діагностику заблокованого плагіна, як-от власність шляху або дозволи на запис для всіх, замість видалення конфігурації `plugins.entries.` або `plugins.allow`. +Якщо налаштований плагін присутній на диску, але заблокований перевірками безпеки шляхів завантажувача, перевірка конфігурації зберігає запис плагіна та повідомляє про нього як `present but blocked`. Виправте попередню діагностику заблокованого плагіна, наприклад власника шляху або дозволи world-writable, замість видалення конфігурації `plugins.entries.` або `plugins.allow`. -Для збоїв форми модуля, як-от відсутні експорти `register`/`activate`, перезапустіть із `OPENCLAW_PLUGIN_LOAD_DEBUG=1`, щоб включити стислий підсумок форми експортів у діагностичний вивід. +Для помилок форми модуля, як-от відсутніх експортів `register`/`activate`, повторно запустіть з `OPENCLAW_PLUGIN_LOAD_DEBUG=1`, щоб включити компактний підсумок форми експортів у діагностичний вивід. ### Реєстр @@ -390,24 +390,24 @@ openclaw plugins registry --refresh openclaw plugins registry --json ``` -Локальний реєстр плагінів — це збережена холодна модель читання OpenClaw для встановленої ідентичності плагінів, увімкнення, метаданих джерела та власників внесків. Звичайний запуск, пошук власника провайдера, класифікація налаштування каналу та інвентар плагінів можуть читати його без імпорту runtime-модулів плагінів. +Локальний реєстр плагінів — це збережена холодна модель читання OpenClaw для ідентичності встановлених плагінів, увімкнення, метаданих джерела та власності внесків. Звичайний запуск, пошук власника провайдера, класифікація налаштування каналу та інвентар плагінів можуть читати його без імпорту модулів виконання плагінів. -Використовуйте `plugins registry`, щоб перевірити, чи наявний збережений реєстр, чи він актуальний або застарілий. Використовуйте `--refresh`, щоб перебудувати його зі збереженого індексу Plugin, політики конфігурації та метаданих маніфесту/пакета. Це шлях відновлення, а не шлях активації під час виконання. +Використовуйте `plugins registry`, щоб перевірити, чи постійний реєстр наявний, актуальний або застарілий. Використовуйте `--refresh`, щоб перебудувати його з постійного індексу Plugin, політики конфігурації та метаданих маніфесту/пакета. Це шлях відновлення, а не шлях активації під час виконання. -`openclaw doctor --fix` також виправляє кероване розходження npm поруч із реєстром: якщо осиротілий або відновлений пакет `@openclaw/*` у керованому npm-корені Plugin затінює вбудований Plugin, doctor видаляє цей застарілий пакет і перебудовує реєстр, щоб запуск перевірявся за вбудованим маніфестом. +`openclaw doctor --fix` також виправляє пов’язане з реєстром відхилення керованого npm: якщо осиротілий або відновлений пакет `@openclaw/*` під коренем npm керованого Plugin затіняє вбудований Plugin, doctor видаляє цей застарілий пакет і перебудовує реєстр, щоб запуск перевірявся за вбудованим маніфестом. -`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` — це застарілий аварійний перемикач сумісності для збоїв читання реєстру. Надавайте перевагу `plugins registry --refresh` або `openclaw doctor --fix`; резервний варіант через змінну середовища призначений лише для аварійного відновлення запуску, поки міграція розгортається. +`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` — це застарілий аварійний перемикач сумісності для збоїв читання реєстру. Надавайте перевагу `plugins registry --refresh` або `openclaw doctor --fix`; резервний варіант через env призначений лише для екстреного відновлення запуску, поки міграція розгортається. -### Маркетплейс +### Marketplace ```bash openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -Список маркетплейсу приймає локальний шлях до маркетплейсу, шлях до `marketplace.json`, скорочення GitHub на кшталт `owner/repo`, URL репозиторію GitHub або git URL. `--json` виводить мітку розв’язаного джерела, а також розібраний маніфест маркетплейсу та записи Plugin. +Список Marketplace приймає локальний шлях Marketplace, шлях `marketplace.json`, скорочення GitHub на кшталт `owner/repo`, URL репозиторію GitHub або URL git. `--json` виводить визначену мітку джерела, а також розібраний маніфест Marketplace і записи Plugin. ## Пов’язане diff --git a/docs/uk/concepts/qa-e2e-automation.md b/docs/uk/concepts/qa-e2e-automation.md index eca34af74..5d517024e 100644 --- a/docs/uk/concepts/qa-e2e-automation.md +++ b/docs/uk/concepts/qa-e2e-automation.md @@ -1,67 +1,67 @@ --- read_when: - - Розуміння того, як складові QA-стека поєднуються між собою + - Розуміння того, як стек QA працює разом - Розширення qa-lab, qa-channel або транспортного адаптера - - Додавання QA-сценаріїв на основі репозиторію - - Створення реалістичнішої QA-автоматизації навколо панелі керування Gateway -summary: 'Огляд стеку QA: qa-lab, qa-channel, сценарії на основі репозиторію, живі транспортні лінії, транспортні адаптери та звітування.' -title: Огляд забезпечення якості + - Додавання QA-сценаріїв із підтримкою репозиторію + - Побудова QA-автоматизації з вищим рівнем реалістичності для панелі керування Gateway +summary: 'Огляд QA-стека: qa-lab, qa-channel, сценарії, підтримувані репозиторієм, лінії live-транспорту, транспортні адаптери та звітування.' +title: Огляд QA x-i18n: - generated_at: "2026-05-05T00:42:46Z" + generated_at: "2026-05-05T01:21:36Z" model: gpt-5.5 provider: openai - source_hash: 01cc3543a10a8ea3a7ea3a135e95ae0ea0c6e983e6b30c35aab1f74c13d7f4a3 + source_hash: 83adbe934d73265a1b47ee463c98fdd3eddfb1cd063d3a46a83dfc7568df0a96 source_path: concepts/qa-e2e-automation.md workflow: 16 --- -Приватний стек QA призначений для перевірки OpenClaw у більш реалістичний, -каналоподібний спосіб, ніж це може зробити один модульний тест. +Приватний стек QA призначений для перевірки OpenClaw у реалістичніший, +канально-орієнтований спосіб, ніж це може зробити один unit test. -Поточні частини: +Поточні складники: - `extensions/qa-channel`: синтетичний канал повідомлень із поверхнями DM, каналу, треду, - реакції, редагування та видалення. -- `extensions/qa-lab`: UI налагоджувача і QA-шина для спостереження за транскриптом, + реакцій, редагування та видалення. +- `extensions/qa-lab`: UI налагоджувача й шина QA для спостереження за транскриптом, ін’єкції вхідних повідомлень та експорту Markdown-звіту. -- `extensions/qa-matrix`, майбутні плагіни запуску: адаптери живого транспорту, які +- `extensions/qa-matrix`, майбутні runner plugins: адаптери live-transport, які керують реальним каналом усередині дочірнього QA gateway. -- `qa/`: seed-ресурси з репозиторію для стартового завдання та базових QA - сценаріїв. -- [Mantis](/uk/concepts/mantis): перевірка до і після наживо для багів, яким +- `qa/`: seed-ресурси з репозиторію для kickoff-завдання та базових + сценаріїв QA. +- [Mantis](/uk/concepts/mantis): перевірка до й після live-верифікації для багів, яким потрібні реальні транспорти, скриншоти браузера, стан VM і докази для PR. ## Поверхня команд Кожен QA-потік запускається через `pnpm openclaw qa `. Багато з них мають -аліаси сценаріїв `pnpm qa:*`; підтримуються обидві форми. +script aliases `pnpm qa:*`; підтримуються обидві форми. | Команда | Призначення | | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `qa run` | Вбудована самоперевірка QA; записує Markdown-звіт. | -| `qa suite` | Запускає сценарії з репозиторію проти QA gateway lane. Аліаси: `pnpm openclaw qa suite --runner multipass` для одноразової Linux VM. | -| `qa coverage` | Друкує markdown-інвентар покриття сценаріями (`--json` для машинного виводу). | -| `qa parity-report` | Порівнює два файли `qa-suite-summary.json` і записує агентний звіт про паритет. | -| `qa character-eval` | Запускає QA-сценарій персонажа на кількох живих моделях зі звітом оцінювання. Див. [Звітування](#reporting). | -| `qa manual` | Запускає одноразовий prompt проти вибраної provider/model lane. | -| `qa ui` | Запускає UI налагоджувача QA і локальну QA-шину (аліас: `pnpm qa:lab:ui`). | +| `qa suite` | Запускає сценарії з репозиторію проти QA gateway lane. Aliases: `pnpm openclaw qa suite --runner multipass` для одноразової Linux VM. | +| `qa coverage` | Друкує markdown-інвентар покриття сценаріїв (`--json` для машинного виводу). | +| `qa parity-report` | Порівнює два файли `qa-suite-summary.json` і записує агентний parity report. | +| `qa character-eval` | Запускає character QA scenario на кількох live models зі звітом, оціненим суддею. Див. [Звітування](#reporting). | +| `qa manual` | Запускає одноразовий prompt проти вибраного provider/model lane. | +| `qa ui` | Запускає QA debugger UI і локальну QA bus (alias: `pnpm qa:lab:ui`). | | `qa docker-build-image` | Збирає попередньо підготовлений QA Docker image. | | `qa docker-scaffold` | Записує docker-compose scaffold для QA dashboard + gateway lane. | -| `qa up` | Збирає QA site, запускає Docker-backed stack, друкує URL (аліас: `pnpm qa:lab:up`; варіант `:fast` додає `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). | -| `qa aimock` | Запускає лише server provider AIMock. | -| `qa mock-openai` | Запускає лише server provider `mock-openai`, обізнаний зі сценаріями. | +| `qa up` | Збирає QA site, запускає Docker-backed stack, друкує URL (alias: `pnpm qa:lab:up`; варіант `:fast` додає `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). | +| `qa aimock` | Запускає лише AIMock provider server. | +| `qa mock-openai` | Запускає лише scenario-aware `mock-openai` provider server. | | `qa credentials doctor` / `add` / `list` / `remove` | Керує спільним пулом облікових даних Convex. | | `qa matrix` | Live transport lane проти одноразового Tuwunel homeserver. Див. [Matrix QA](/uk/concepts/qa-matrix). | -| `qa telegram` | Live transport lane проти реальної приватної групи Telegram. | -| `qa discord` | Live transport lane проти реального приватного каналу Discord guild. | -| `qa slack` | Live transport lane проти реального приватного каналу Slack. | -| `qa mantis` | Runner перевірки до і після для багів live transport, із доказами status-reactions у Discord, desktop/browser smoke у Crabbox та Slack-in-VNC smoke. Див. [Mantis](/uk/concepts/mantis). | +| `qa telegram` | Live transport lane проти реальної приватної Telegram group. | +| `qa discord` | Live transport lane проти реального приватного Discord guild channel. | +| `qa slack` | Live transport lane проти реального приватного Slack channel. | +| `qa mantis` | Runner перевірки до й після для багів live transport, із доказами Discord status-reactions, Crabbox desktop/browser smoke та Slack-in-VNC smoke. Див. [Mantis](/uk/concepts/mantis). | -## Потік оператора +## Операторський потік -Поточний потік оператора QA — це двопанельний QA site: +Поточний операторський потік QA — це двопанельний QA site: -- Ліворуч: Gateway dashboard (Control UI) з агентом. +- Ліворуч: Gateway dashboard (Control UI) з agent. - Праворуч: QA Lab, що показує Slack-подібний транскрипт і план сценарію. Запустіть його так: @@ -70,13 +70,13 @@ x-i18n: pnpm qa:lab:up ``` -Це збирає QA site, запускає Docker-backed gateway lane і відкриває сторінку -QA Lab, де оператор або цикл автоматизації може дати агенту QA -місію, спостерігати реальну поведінку каналу та записати, що спрацювало, не спрацювало або -залишилося заблокованим. +Це збирає QA site, запускає Docker-backed gateway lane і відкриває +сторінку QA Lab, де оператор або цикл автоматизації може дати agent QA +місію, спостерігати за реальною поведінкою каналу та записувати, що спрацювало, що не вдалося або +що залишилося заблокованим. -Для швидшої ітерації UI QA Lab без повторного збирання Docker image щоразу -запустіть стек із bind-mounted QA Lab bundle: +Для швидшої ітерації QA Lab UI без перебудови Docker image щоразу, +запустіть stack із bind-mounted QA Lab bundle: ```bash pnpm openclaw qa docker-build-image @@ -85,38 +85,38 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` тримає Docker services на попередньо зібраному image і bind-mount-ить -`extensions/qa-lab/web/dist` у container `qa-lab`. `qa:lab:watch` -перезбирає цей bundle під час змін, а браузер автоматично перезавантажується, коли hash ресурсу QA Lab -змінюється. +`qa:lab:up:fast` тримає Docker services на попередньо зібраному image і bind-mounts +`extensions/qa-lab/web/dist` у контейнер `qa-lab`. `qa:lab:watch` +перезбирає цей bundle після змін, а браузер автоматично перезавантажується, коли змінюється +asset hash QA Lab. -Для локального OpenTelemetry trace smoke запустіть: +Для локального OpenTelemetry trace smoke виконайте: ```bash pnpm qa:otel:smoke ``` Цей script запускає локальний OTLP/HTTP trace receiver, виконує -QA-сценарій `otel-trace-smoke` з увімкненим plugin `diagnostics-otel`, потім -декодує експортовані protobuf spans і перевіряє критичну для релізу форму: +QA scenario `otel-trace-smoke` з увімкненим plugin `diagnostics-otel`, потім +декодує експортовані protobuf spans і перевіряє release-critical shape: `openclaw.run`, `openclaw.harness.run`, `openclaw.model.call`, `openclaw.context.assembled` і `openclaw.message.delivery` мають бути присутні; model calls не мають експортувати `StreamAbandoned` на успішних turns; raw diagnostic IDs і атрибути `openclaw.content.*` мають залишатися поза trace. Він записує `otel-smoke-summary.json` поруч з artifacts QA suite. -Observability QA залишається лише для source checkout. npm tarball навмисно не містить +Observability QA залишається доступним лише з source checkout. npm tarball навмисно не містить QA Lab, тому package Docker release lanes не запускають команди `qa`. Використовуйте -`pnpm qa:otel:smoke` із зібраного source checkout під час зміни diagnostics +`pnpm qa:otel:smoke` зі зібраного source checkout, коли змінюєте diagnostics instrumentation. -Для transport-real Matrix smoke lane запустіть: +Для transport-real Matrix smoke lane виконайте: ```bash pnpm openclaw qa matrix --profile fast --fail-fast ``` -Повний довідник CLI, каталог profiles/scenarios, env vars і layout artifacts для цієї lane наведені в [Matrix QA](/uk/concepts/qa-matrix). Коротко: він provision-ить одноразовий Tuwunel homeserver у Docker, реєструє тимчасових користувачів driver/SUT/observer, запускає реальний Matrix plugin усередині дочірнього QA gateway, scoped до цього транспорту (без `qa-channel`), потім записує Markdown-звіт, JSON summary, artifact observed-events і combined output log у `.artifacts/qa-e2e/matrix-/`. +Повний CLI reference, catalog профілів/сценаріїв, env vars і layout artifacts для цього lane описані в [Matrix QA](/uk/concepts/qa-matrix). Коротко: він provision одноразовий Tuwunel homeserver у Docker, реєструє тимчасових користувачів driver/SUT/observer, запускає реальний Matrix plugin усередині дочірнього QA gateway, scoped до цього transport (без `qa-channel`), потім записує Markdown report, JSON summary, observed-events artifact і combined output log у `.artifacts/qa-e2e/matrix-/`. Для transport-real Telegram, Discord і Slack smoke lanes: @@ -126,9 +126,9 @@ pnpm openclaw qa discord pnpm openclaw qa slack ``` -Вони націлені на вже наявний реальний канал із двома ботами (driver + SUT). Обов’язкові env vars, списки сценаріїв, output artifacts і пул облікових даних Convex задокументовані в [довіднику QA для Telegram, Discord і Slack](#telegram-discord-and-slack-qa-reference) нижче. +Вони націлені на вже наявний реальний канал із двома bots (driver + SUT). Required env vars, списки сценаріїв, output artifacts і Convex credential pool задокументовані в [довідці QA для Telegram, Discord і Slack](#telegram-discord-and-slack-qa-reference) нижче. -Для повного запуску Slack desktop VM із VNC rescue запустіть: +Для повного Slack desktop VM run із VNC rescue виконайте: ```bash pnpm openclaw qa mantis slack-desktop-smoke \ @@ -137,25 +137,25 @@ pnpm openclaw qa mantis slack-desktop-smoke \ --keep-lease ``` -Ця команда орендує desktop/browser machine Crabbox, запускає Slack live lane +Ця команда орендує Crabbox desktop/browser machine, запускає Slack live lane усередині VM, відкриває Slack Web у VNC browser, захоплює desktop і -копіює `slack-qa/` разом із `slack-desktop-smoke.png` назад до artifact +копіює `slack-qa/` плюс `slack-desktop-smoke.png` назад до artifact directory Mantis. Повторно використовуйте `--lease-id ` після ручного входу в Slack Web -через VNC. З `--gateway-setup` Mantis залишає persistent OpenClaw Slack -gateway, що працює всередині VM на port `38973`; без нього команда запускає -звичайну bot-to-bot Slack QA lane і завершується після захоплення artifacts. +через VNC. З `--gateway-setup` Mantis залишає постійний OpenClaw Slack +gateway, що працює всередині VM на порту `38973`; без нього команда запускає +звичайний bot-to-bot Slack QA lane і завершується після захоплення artifacts. -Перед використанням pooled live credentials запустіть: +Перед використанням pooled live credentials виконайте: ```bash pnpm openclaw qa credentials doctor ``` -Doctor перевіряє env брокера Convex, валідує endpoint settings і перевіряє admin/list reachability, коли присутній maintainer secret. Для secrets він повідомляє лише статус set/missing. +Doctor перевіряє Convex broker env, валідовує endpoint settings і перевіряє reachability admin/list, коли присутній maintainer secret. Для secrets він повідомляє лише статус set/missing. ## Покриття live transport -Live transport lanes мають один спільний contract замість того, щоб кожна винаходила власну форму списку сценаріїв. `qa-channel` — це широкий synthetic product-behavior suite і не є частиною матриці покриття live transport. +Live transport lanes мають спільний контракт замість того, щоб кожен винаходив власну форму списку сценаріїв. `qa-channel` — це широкий synthetic product-behavior suite і він не є частиною матриці live transport coverage. | Lane | Canary | Mention gating | Bot-to-bot | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Help command | Native command registration | | -------- | ------ | -------------- | ---------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | --------------------------- | @@ -168,60 +168,60 @@ Live transport lanes мають один спільний contract заміст Telegram і майбутні live transports мають один явний transport-contract checklist. -Для одноразової Linux VM lane без залучення Docker у QA path запустіть: +Для одноразового Linux VM lane без залучення Docker у QA path виконайте: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -Це завантажує свіжого guest Multipass, встановлює залежності, збирає OpenClaw -усередині guest, запускає `qa suite`, а потім копіює звичайний QA-звіт і -зведення назад у `.artifacts/qa-e2e/...` на host. -Він повторно використовує ту саму поведінку вибору сценаріїв, що й `qa suite` на host. -Запуски наборів на host і Multipass за замовчуванням виконують кілька вибраних сценаріїв паралельно -з ізольованими працівниками Gateway. `qa-channel` за замовчуванням має concurrency +Це завантажує свіжий гостьовий екземпляр Multipass, установлює залежності, збирає OpenClaw +усередині гостя, запускає `qa suite`, а потім копіює звичайний звіт QA та +підсумок назад у `.artifacts/qa-e2e/...` на хості. +Він повторно використовує ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. +Запуски набору на хості й у Multipass виконують кілька вибраних сценаріїв паралельно +з ізольованими працівниками Gateway за замовчуванням. `qa-channel` за замовчуванням використовує паралельність 4, обмежену кількістю вибраних сценаріїв. Використовуйте `--concurrency `, щоб налаштувати кількість працівників, або `--concurrency 1` для послідовного виконання. -Команда завершується з ненульовим кодом, якщо будь-який сценарій не вдається. Використовуйте `--allow-failures`, коли +Команда завершується з ненульовим кодом, коли будь-який сценарій зазнає невдачі. Використовуйте `--allow-failures`, коли потрібні артефакти без коду завершення з помилкою. -Live-запуски передають підтримувані вхідні дані автентифікації QA, практичні для -guest: ключі провайдерів на основі env, шлях до конфігурації QA live provider і -`CODEX_HOME`, коли він присутній. Тримайте `--output-dir` під коренем репозиторію, щоб guest -міг записувати назад через змонтований workspace. +Живі запуски передають підтримувані вхідні дані автентифікації QA, практичні для +гостя: ключі провайдерів на основі env, шлях до конфігурації живого провайдера QA та +`CODEX_HOME`, коли він наявний. Тримайте `--output-dir` під коренем репозиторію, щоб гість +міг записувати назад через змонтований робочий простір. ## Довідник QA для Telegram, Discord і Slack -Matrix має [окрему сторінку](/uk/concepts/qa-matrix) через кількість сценаріїв і підготовку homeserver на базі Docker. Telegram, Discord і Slack менші — по кілька сценаріїв кожен, без системи профілів, проти вже наявних реальних каналів — тому їхній довідник розміщено тут. +Matrix має [окрему сторінку](/uk/concepts/qa-matrix) через кількість сценаріїв і підготовку homeserver на базі Docker. Telegram, Discord і Slack менші — кілька сценаріїв кожен, без системи профілів, для вже наявних реальних каналів — тому їхній довідник наведено тут. ### Спільні прапорці CLI -Ці lanes реєструються через `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` і приймають однакові прапорці: +Ці лінії реєструються через `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` і приймають ті самі прапорці: -| Прапорець | За замовчуванням | Опис | -| ------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -| `--scenario ` | — | Запустити лише цей сценарій. Можна повторювати. | -| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord,slack}-` | Куди записуються звіти/зведення/спостережені повідомлення та журнал виводу. Відносні шляхи визначаються від `--repo-root`. | -| `--repo-root ` | `process.cwd()` | Корінь репозиторію під час виклику з нейтрального cwd. | -| `--sut-account ` | `sut` | Тимчасовий id облікового запису в конфігурації QA Gateway. | -| `--provider-mode ` | `live-frontier` | `mock-openai` або `live-frontier` (застарілий `live-openai` досі працює). | -| `--model ` / `--alt-model ` | провайдер за замовчуванням | Посилання на основну/альтернативну модель. | -| `--fast` | вимкнено | Швидкий режим провайдера, де підтримується. | -| `--credential-source ` | `env` | Див. [пул облікових даних Convex](#convex-credential-pool). | -| `--credential-role ` | `ci` у CI, інакше `maintainer` | Роль, що використовується, коли `--credential-source convex`. | +| Прапорець | За замовчуванням | Опис | +| ------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| `--scenario ` | — | Запустити лише цей сценарій. Можна повторювати. | +| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord,slack}-` | Куди записуються звіти/підсумок/спостережені повідомлення та журнал виводу. Відносні шляхи визначаються відносно `--repo-root`. | +| `--repo-root ` | `process.cwd()` | Корінь репозиторію під час виклику з нейтрального cwd. | +| `--sut-account ` | `sut` | Тимчасовий id облікового запису в конфігурації Gateway QA. | +| `--provider-mode ` | `live-frontier` | `mock-openai` або `live-frontier` (застарілий `live-openai` усе ще працює). | +| `--model ` / `--alt-model ` | стандарт провайдера | Посилання на основну/альтернативну модель. | +| `--fast` | вимкнено | Швидкий режим провайдера, де підтримується. | +| `--credential-source ` | `env` | Див. [пул облікових даних Convex](#convex-credential-pool). | +| `--credential-role ` | `ci` у CI, інакше `maintainer` | Роль, що використовується, коли `--credential-source convex`. | -Кожна lane завершується з ненульовим кодом за будь-якого невдалого сценарію. `--allow-failures` записує артефакти без встановлення коду завершення з помилкою. +Кожна лінія завершується з ненульовим кодом у разі будь-якого невдалого сценарію. `--allow-failures` записує артефакти без встановлення коду завершення з помилкою. -### Telegram QA +### QA для Telegram ```bash pnpm openclaw qa telegram ``` -Націлено на одну реальну приватну групу Telegram із двома окремими ботами (driver + SUT). SUT bot повинен мати ім’я користувача Telegram; спостереження bot-to-bot працює найкраще, коли в обох ботів увімкнено **Bot-to-Bot Communication Mode** у `@BotFather`. +Націлено на одну реальну приватну групу Telegram із двома окремими ботами (driver + SUT). Бот SUT повинен мати ім’я користувача Telegram; спостереження бот-бот працює найкраще, коли обидва боти мають увімкнений **Bot-to-Bot Communication Mode** у `@BotFather`. Обов’язкові env, коли `--credential-source env`: -- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — числовий chat id (рядок). +- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — числовий id чату (рядок). - `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` - `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` @@ -240,19 +240,19 @@ pnpm openclaw qa telegram - `telegram-whoami-command` - `telegram-context-command` -Вихідні артефакти: +Артефакти виводу: - `telegram-qa-report.md` - `telegram-qa-summary.json` — містить RTT для кожної відповіді (надсилання driver → спостережена відповідь SUT), починаючи з canary. -- `telegram-qa-observed-messages.json` — тіла редагуються, якщо не встановлено `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`. +- `telegram-qa-observed-messages.json` — тіла редагуються, якщо не задано `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`. -### Discord QA +### QA для Discord ```bash pnpm openclaw qa discord ``` -Націлено на один реальний приватний канал guild Discord із двома ботами: driver bot, керований harness, і SUT bot, запущений дочірнім OpenClaw Gateway через вбудований Discord Plugin. Перевіряє обробку згадок каналу, що SUT bot зареєстрував нативну команду `/help` у Discord, а також opt-in сценарії доказів Mantis. +Націлено на один реальний приватний канал гільдії Discord із двома ботами: ботом driver, яким керує harness, і ботом SUT, запущеним дочірнім Gateway OpenClaw через вбудований Discord plugin. Перевіряє обробку згадок у каналі, те, що бот SUT зареєстрував нативну команду `/help` у Discord, і opt-in сценарії доказів Mantis. Обов’язкові env, коли `--credential-source env`: @@ -260,7 +260,7 @@ pnpm openclaw qa discord - `OPENCLAW_QA_DISCORD_CHANNEL_ID` - `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN` - `OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN` -- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — має збігатися з id користувача SUT bot, повернутим Discord (інакше lane швидко завершується з помилкою). +- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — має збігатися з id користувача бота SUT, який повертає Discord (інакше лінія швидко завершується помилкою). Необов’язково: @@ -271,9 +271,9 @@ pnpm openclaw qa discord - `discord-canary` - `discord-mention-gating` - `discord-native-help-command-registration` -- `discord-status-reactions-tool-only` — opt-in сценарій Mantis. Запускається самостійно, бо перемикає SUT на always-on, tool-only відповіді guild з `messages.statusReactions.enabled=true`, а потім захоплює timeline реакцій REST плюс візуальний артефакт HTML/PNG. +- `discord-status-reactions-tool-only` — opt-in сценарій Mantis. Запускається самостійно, бо перемикає SUT на постійно ввімкнені відповіді гільдії лише через інструменти з `messages.statusReactions.enabled=true`, а потім захоплює часову шкалу реакцій REST і візуальний артефакт HTML/PNG. -Запустіть сценарій status-reaction Mantis явно: +Запустіть сценарій реакцій статусу Mantis явно: ```bash pnpm openclaw qa discord \ @@ -284,20 +284,20 @@ pnpm openclaw qa discord \ --fast ``` -Вихідні артефакти: +Артефакти виводу: - `discord-qa-report.md` - `discord-qa-summary.json` -- `discord-qa-observed-messages.json` — тіла редагуються, якщо не встановлено `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1`. -- `discord-qa-reaction-timelines.json` і `discord-status-reactions-tool-only-timeline.png`, коли запускається сценарій status-reaction. +- `discord-qa-observed-messages.json` — тіла редагуються, якщо не задано `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1`. +- `discord-qa-reaction-timelines.json` і `discord-status-reactions-tool-only-timeline.png`, коли запускається сценарій реакцій статусу. -### Slack QA +### QA для Slack ```bash pnpm openclaw qa slack ``` -Націлено на один реальний приватний канал Slack із двома окремими ботами: driver bot, керований harness, і SUT bot, запущений дочірнім OpenClaw Gateway через вбудований Slack Plugin. +Націлено на один реальний приватний канал Slack із двома окремими ботами: ботом driver, яким керує harness, і ботом SUT, запущеним дочірнім Gateway OpenClaw через вбудований Slack plugin. Обов’язкові env, коли `--credential-source env`: @@ -315,26 +315,28 @@ pnpm openclaw qa slack - `slack-canary` - `slack-mention-gating` -Вихідні артефакти: +Артефакти виводу: - `slack-qa-report.md` - `slack-qa-summary.json` -- `slack-qa-observed-messages.json` — тіла редагуються, якщо не встановлено `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1`. +- `slack-qa-observed-messages.json` — тіла редагуються, якщо не задано `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1`. -#### Налаштування workspace Slack +#### Налаштування робочого простору Slack -Lane потребує двох окремих застосунків Slack в одному workspace, а також канал, учасниками якого є обидва боти: +Лінії потрібні дві окремі програми Slack в одному робочому просторі, а також канал, учасниками якого є обидва боти: -- `channelId` — id `Cxxxxxxxxxx` каналу, до якого запрошено обох ботів. Використовуйте виділений канал; lane публікує повідомлення під час кожного запуску. -- `driverBotToken` — token бота (`xoxb-...`) застосунку **Driver**. -- `sutBotToken` — token бота (`xoxb-...`) застосунку **SUT**, який має бути окремим застосунком Slack від driver, щоб його id користувача бота був іншим. -- `sutAppToken` — token рівня застосунку (`xapp-...`) застосунку SUT з `connections:write`, який використовується Socket Mode, щоб застосунок SUT міг отримувати події. +- `channelId` — id `Cxxxxxxxxxx` каналу, до якого запрошено обох ботів. Використовуйте спеціальний канал; лінія публікує повідомлення під час кожного запуску. +- `driverBotToken` — токен бота (`xoxb-...`) програми **Driver**. +- `sutBotToken` — токен бота (`xoxb-...`) програми **SUT**, яка має бути окремою програмою Slack від driver, щоб її id користувача бота був окремим. +- `sutAppToken` — токен рівня програми (`xapp-...`) програми SUT з `connections:write`, який використовується Socket Mode, щоб програма SUT могла отримувати події. -Віддавайте перевагу workspace Slack, виділеному для QA, замість повторного використання production workspace. +Віддавайте перевагу робочому простору Slack, призначеному для QA, замість повторного використання виробничого робочого простору. -**1. Створіть застосунок Driver** +Наведений нижче маніфест SUT віддзеркалює виробниче встановлення вбудованого Slack plugin (`extensions/slack/src/setup-shared.ts:10`). Налаштування виробничого каналу, як його бачать користувачі, див. у [швидкому налаштуванні каналу Slack](/uk/channels/slack#quick-setup); пара QA Driver/SUT навмисно окрема, бо лінії потрібні два окремі id користувачів ботів в одному робочому просторі. -Перейдіть до [api.slack.com/apps](https://api.slack.com/apps) → _Create New App_ → _From a manifest_ → виберіть QA workspace, вставте наведений нижче manifest, а потім _Install to Workspace_: +**1. Створіть програму Driver** + +Перейдіть до [api.slack.com/apps](https://api.slack.com/apps) → _Create New App_ → _From a manifest_ → виберіть робочий простір QA, вставте наведений нижче маніфест, потім _Install to Workspace_: ```json { @@ -359,11 +361,11 @@ Lane потребує двох окремих застосунків Slack в о } ``` -Скопіюйте _Bot User OAuth Token_ (`xoxb-...`) — він стане `driverBotToken`. Driver має лише публікувати повідомлення та ідентифікувати себе; без подій, без Socket Mode. +Скопіюйте _Bot User OAuth Token_ (`xoxb-...`) — він стане `driverBotToken`. Driver потрібен лише для публікації повідомлень і самоідентифікації; без подій, без Socket Mode. -**2. Створіть застосунок SUT** +**2. Створіть програму SUT** -Повторіть _Create New App → From a manifest_ у тому самому workspace. Набір scope віддзеркалює production install вбудованого Slack Plugin (`extensions/slack/src/setup-shared.ts:10`): +Повторіть _Create New App → From a manifest_ у тому самому робочому просторі. Набір scope віддзеркалює виробниче встановлення вбудованого Slack plugin (`extensions/slack/src/setup-shared.ts:10`): ```json { @@ -434,29 +436,29 @@ Lane потребує двох окремих застосунків Slack в о } ``` -Після того як Slack створить застосунок, зробіть дві речі на його сторінці налаштувань: +Після того як Slack створить програму, зробіть дві речі на її сторінці налаштувань: - _Install to Workspace_ → скопіюйте _Bot User OAuth Token_ → він стане `sutBotToken`. - _Basic Information → App-Level Tokens → Generate Token and Scopes_ → додайте scope `connections:write` → збережіть → скопіюйте значення `xapp-...` → воно стане `sutAppToken`. -Перевірте, що два боти мають різні user ids, викликавши `auth.test` для кожного token. Runtime розрізняє driver і SUT за user id; повторне використання одного застосунку для обох одразу провалить mention-gating. +Перевірте, що два боти мають різні ідентифікатори користувачів, викликавши `auth.test` для кожного токена. Runtime розрізняє driver і SUT за ідентифікатором користувача; повторне використання одного застосунку для обох ролей одразу призведе до помилки mention-gating. **3. Створіть канал** -У QA workspace створіть канал (наприклад, `#openclaw-qa`) і запросіть обох ботів зсередини каналу: +У робочому просторі QA створіть канал (наприклад, `#openclaw-qa`) і запросіть обох ботів ізсередини каналу: ``` /invite @OpenClaw QA Driver /invite @OpenClaw QA SUT ``` -Скопіюйте ідентифікатор `Cxxxxxxxxxx` з _інформація про канал → Про канал → ID каналу_ — він стане `channelId`. Публічний канал працює; якщо ви використовуєте приватний канал, обидва застосунки вже мають `groups:history`, тож читання історії в harness все одно успішно виконуватиметься. +Скопіюйте ідентифікатор `Cxxxxxxxxxx` з _channel info → About → Channel ID_ — він стане `channelId`. Публічний канал підійде; якщо ви використовуєте приватний канал, обидва застосунки вже мають `groups:history`, тож читання історії у harness все одно буде успішним. **4. Зареєструйте облікові дані** -Є два варіанти. Використовуйте змінні середовища для налагодження на одній машині (задайте чотири змінні `OPENCLAW_QA_SLACK_*` і передайте `--credential-source env`) або засійте спільний пул Convex, щоб CI та інші maintainers могли їх орендувати. +Є два варіанти. Використовуйте змінні середовища для налагодження на одній машині (задайте чотири змінні `OPENCLAW_QA_SLACK_*` і передайте `--credential-source env`) або заповніть спільний пул Convex, щоб CI та інші maintainers могли брати їх в оренду. -Для пулу Convex запишіть чотири поля у файл JSON: +Для пулу Convex запишіть чотири поля у JSON-файл: ```json { @@ -467,7 +469,7 @@ Lane потребує двох окремих застосунків Slack в о } ``` -Коли `OPENCLAW_QA_CONVEX_SITE_URL` і `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` експортовані у вашій оболонці, зареєструйте та перевірте: +Коли `OPENCLAW_QA_CONVEX_SITE_URL` і `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` експортовано у вашій оболонці, зареєструйте та перевірте: ```bash pnpm openclaw qa credentials add \ @@ -480,7 +482,7 @@ pnpm openclaw qa credentials list --kind slack --status all --json Очікуйте `count: 1`, `status: "active"`, без поля `lease`. -**5. Перевірте повний цикл** +**5. Перевірте end to end** Запустіть lane локально, щоб підтвердити, що обидва боти можуть спілкуватися один з одним через broker: @@ -491,123 +493,123 @@ pnpm openclaw qa slack \ --output-dir .artifacts/qa-e2e/slack-local ``` -Успішний запуск завершується значно швидше ніж за 30 секунд, а `slack-qa-report.md` показує обидва `slack-canary` і `slack-mention-gating` зі статусом `pass`. Якщо lane зависає приблизно на 90 секунд і завершується з `Convex credential pool exhausted for kind "slack"`, пул або порожній, або кожен рядок орендований — `qa credentials list --kind slack --status all --json` покаже, який саме випадок. +Успішний запуск завершується значно менш ніж за 30 секунд, а `slack-qa-report.md` показує і `slack-canary`, і `slack-mention-gating` зі статусом `pass`. Якщо lane зависає приблизно на 90 секунд і завершується з `Convex credential pool exhausted for kind "slack"`, то або пул порожній, або всі рядки взято в оренду — `qa credentials list --kind slack --status all --json` покаже, який саме випадок. ### Пул облікових даних Convex -Lanes Telegram, Discord і Slack можуть орендувати облікові дані зі спільного пулу Convex замість читання наведених вище змінних середовища. Передайте `--credential-source convex` (або задайте `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`); QA Lab отримує ексклюзивну оренду, надсилає Heartbeat протягом усього запуску та звільняє її під час завершення. Типи пулу: `"telegram"`, `"discord"` і `"slack"`. +Lane-и Telegram, Discord і Slack можуть брати облікові дані зі спільного пулу Convex замість читання наведених вище змінних середовища. Передайте `--credential-source convex` (або задайте `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`); QA Lab отримує ексклюзивну оренду, надсилає Heartbeat протягом виконання запуску та звільняє її під час завершення. Види пулів: `"telegram"`, `"discord"` і `"slack"`. Форми payload, які broker перевіряє на `admin/add`: - Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` має бути числовим рядком chat-id. - Discord (`kind: "discord"`): `{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }`. -- Slack (`kind: "slack"`): `{ channelId: string, driverBotToken: string, sutBotToken: string, sutAppToken: string }` — `channelId` має відповідати `^[A-Z][A-Z0-9]+$` (ідентифікатор Slack на кшталт `Cxxxxxxxxxx`). Див. [Налаштування робочого простору Slack](#setting-up-the-slack-workspace) щодо підготовки застосунків і scopes. +- Slack (`kind: "slack"`): `{ channelId: string, driverBotToken: string, sutBotToken: string, sutAppToken: string }` — `channelId` має відповідати `^[A-Z][A-Z0-9]+$` (Slack id на кшталт `Cxxxxxxxxxx`). Див. [Налаштування робочого простору Slack](#setting-up-the-slack-workspace) для підготовки застосунків і scopes. -Операційні змінні середовища та контракт endpoint broker Convex описані в [Тестування → Спільні облікові дані Telegram через Convex](/uk/help/testing#shared-telegram-credentials-via-convex-v1) (назва розділу з’явилася до підтримки Discord; семантика broker однакова для обох типів). +Операційні змінні середовища та контракт endpoint broker Convex описані в [Тестування → Спільні облікові дані Telegram через Convex](/uk/help/testing#shared-telegram-credentials-via-convex-v1) (назва розділу передує підтримці Discord; семантика broker однакова для обох видів). -## Seeds, підкріплені репозиторієм +## Seeds із repo-backed -Seed assets розташовані в `qa/`: +Seed assets розміщені в `qa/`: - `qa/scenarios/index.md` - `qa/scenarios//*.md` -Вони навмисно зберігаються в git, щоб план QA був видимий і людям, і agent. +Їх навмисно збережено в git, щоб план QA був видимий і людям, і агенту. -`qa-lab` має залишатися generic markdown runner. Кожен markdown-файл scenario є джерелом істини для одного тестового запуску й має визначати: +`qa-lab` має залишатися універсальним runner для Markdown. Кожен Markdown-файл сценарію є джерелом істини для одного тестового запуску та має визначати: -- метадані scenario -- необов’язкові метадані категорії, capability, lane і risk -- посилання на документацію та код +- метадані сценарію +- необов’язкові метадані категорії, можливості, lane і ризику +- посилання на docs і code - необов’язкові вимоги до Plugin - необов’язковий patch конфігурації Gateway - виконуваний `qa-flow` -Багаторазова runtime-поверхня, що підтримує `qa-flow`, може залишатися generic і наскрізною. Наприклад, markdown scenarios можуть поєднувати helpers транспортного боку з helpers браузерного боку, які керують вбудованим Control UI через seam Gateway `browser.request` без додавання runner для спеціального випадку. +Повторно використовувана runtime-поверхня, яка підтримує `qa-flow`, може залишатися універсальною та наскрізною. Наприклад, Markdown-сценарії можуть поєднувати helpers транспортного боку з helpers браузерного боку, які керують вбудованим Control UI через Gateway seam `browser.request`, без додавання спеціального runner. -Файли scenario слід групувати за product capability, а не за папкою дерева джерел. Зберігайте ідентифікатори scenario стабільними під час переміщення файлів; використовуйте `docsRefs` і `codeRefs` для простежуваності реалізації. +Файли сценаріїв слід групувати за можливістю продукту, а не за папкою дерева джерел. Зберігайте стабільні ідентифікатори сценаріїв під час переміщення файлів; використовуйте `docsRefs` і `codeRefs` для відстежуваності реалізації. -Базовий список має залишатися достатньо широким, щоб покривати: +Базовий список має залишатися достатньо широким, щоб охоплювати: -- чат у DM і каналі -- поведінку threads -- життєвий цикл message action -- callbacks Cron -- memory recall +- DM і чат у каналі +- поведінку thread +- життєвий цикл дії з повідомленням +- зворотні виклики Cron +- пригадування пам’яті - перемикання моделей -- передавання subagent -- читання репозиторію та документації -- невелике build-завдання, наприклад Lobster Invaders +- передачу subagent +- читання repo і docs +- одне невелике build-завдання, наприклад Lobster Invaders -## Mock lanes провайдера +## Mock lanes провайдерів -`qa suite` має два локальні mock lanes провайдера: +`qa suite` має два локальні mock lanes провайдерів: -- `mock-openai` — це scenario-aware mock OpenClaw. Він залишається стандартним детермінованим mock lane для repo-backed QA і parity gates. -- `aimock` запускає сервер провайдера на базі AIMock для експериментального покриття protocol, fixture, record/replay і chaos. Він є додатковим і не замінює dispatcher scenario `mock-openai`. +- `mock-openai` — scenario-aware mock OpenClaw. Він залишається стандартним детермінованим mock lane для repo-backed QA і parity gates. +- `aimock` запускає provider server на базі AIMock для експериментального protocol, fixture, record/replay і chaos coverage. Він є додатковим і не замінює scenario dispatcher `mock-openai`. -Реалізація provider-lane розташована в `extensions/qa-lab/src/providers/`. Кожен провайдер володіє своїми defaults, запуском локального сервера, конфігурацією моделі Gateway, потребами staging auth-profile і flags live/mock capability. Спільний код suite і gateway має маршрутизуватися через provider registry замість розгалуження за назвами провайдерів. +Реалізація provider-lane міститься в `extensions/qa-lab/src/providers/`. Кожен провайдер володіє своїми defaults, запуском локального сервера, конфігурацією моделі Gateway, потребами staging auth-profile і flags можливостей live/mock. Спільний suite і код Gateway мають маршрутизувати через реєстр провайдерів замість розгалуження за іменами провайдерів. -## Transport adapters +## Транспортні адаптери -`qa-lab` володіє generic transport seam для markdown QA scenarios. `qa-channel` — перший adapter на цьому seam, але ціль дизайну ширша: майбутні реальні або синтетичні канали мають підключатися до того самого suite runner замість додавання transport-specific QA runner. +`qa-lab` володіє універсальним transport seam для Markdown-сценаріїв QA. `qa-channel` — перший адаптер на цьому seam, але ціль дизайну ширша: майбутні реальні або синтетичні канали мають підключатися до того самого suite runner замість додавання транспортно-специфічного runner QA. -На рівні архітектури розподіл такий: +На архітектурному рівні поділ такий: -- `qa-lab` володіє generic виконанням scenario, concurrency workers, записом artifacts і reporting. -- Transport adapter володіє конфігурацією gateway, readiness, inbound і outbound observation, transport actions і normalized transport state. -- Markdown-файли scenario в `qa/scenarios/` визначають тестовий запуск; `qa-lab` надає багаторазову runtime-поверхню, яка їх виконує. +- `qa-lab` володіє універсальним виконанням сценаріїв, concurrency worker-ів, записом artifacts і reporting. +- Транспортний адаптер володіє конфігурацією gateway, готовністю, inbound і outbound observation, transport actions і нормалізованим transport state. +- Markdown-файли сценаріїв у `qa/scenarios/` визначають тестовий запуск; `qa-lab` надає повторно використовувану runtime-поверхню, яка їх виконує. ### Додавання каналу -Додавання каналу до markdown QA system потребує рівно двох речей: +Додавання каналу до Markdown-системи QA вимагає рівно двох речей: -1. Transport adapter для каналу. -2. Scenario pack, який перевіряє контракт каналу. +1. Транспортного адаптера для каналу. +2. Пакета сценаріїв, який перевіряє контракт каналу. -Не додавайте новий top-level корінь команди QA, коли спільний host `qa-lab` може володіти flow. +Не додавайте новий top-level root команди QA, коли спільний host `qa-lab` може володіти flow. `qa-lab` володіє спільною механікою host: -- корінь команди `openclaw qa` -- запуск і teardown suite -- concurrency workers -- запис artifacts -- генерація report -- виконання scenario -- compatibility aliases для старіших scenarios `qa-channel` +- root команди `openclaw qa` +- запуском і teardown suite +- concurrency worker-ів +- записом artifacts +- генерацією report +- виконанням сценаріїв +- compatibility aliases для старіших сценаріїв `qa-channel` -Runner plugins володіють transport contract: +Runner plugins володіють транспортним контрактом: -- як `openclaw qa ` монтується під спільним коренем `qa` -- як gateway конфігурується для цього transport -- як перевіряється readiness -- як вводяться inbound events +- як `openclaw qa ` монтується під спільним root `qa` +- як Gateway налаштовується для цього транспорту +- як перевіряється готовність +- як впроваджуються inbound events - як спостерігаються outbound messages - як надаються transcripts і normalized transport state - як виконуються transport-backed actions -- як обробляється transport-specific reset або cleanup +- як обробляється транспортно-специфічний reset або cleanup -Мінімальна планка adoption для нового каналу: +Мінімальний поріг упровадження для нового каналу: -1. Залиште `qa-lab` власником спільного кореня `qa`. +1. Залиште `qa-lab` власником спільного root `qa`. 2. Реалізуйте transport runner на спільному host seam `qa-lab`. -3. Залиште transport-specific механіку всередині runner plugin або channel harness. -4. Монтуйте runner як `openclaw qa ` замість реєстрації конкуруючої root command. Runner plugins мають оголошувати `qaRunners` в `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. Тримайте `runtime-api.ts` легким; lazy CLI і виконання runner мають залишатися за окремими entrypoints. -5. Створіть або адаптуйте markdown scenarios у тематичних директоріях `qa/scenarios/`. -6. Використовуйте generic scenario helpers для нових scenarios. -7. Зберігайте наявні compatibility aliases робочими, якщо репозиторій не виконує навмисну міграцію. +3. Тримайте транспортно-специфічну механіку всередині runner plugin або channel harness. +4. Монтуйте runner як `openclaw qa ` замість реєстрації конкуруючої root-команди. Runner plugins мають оголошувати `qaRunners` в `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. Тримайте `runtime-api.ts` легким; lazy CLI і виконання runner мають залишатися за окремими entrypoints. +5. Створіть або адаптуйте Markdown-сценарії в тематичних каталогах `qa/scenarios/`. +6. Використовуйте універсальні helpers сценаріїв для нових сценаріїв. +7. Зберігайте наявні compatibility aliases працездатними, якщо repo не виконує навмисну міграцію. -Правило ухвалення рішення суворе: +Правило ухвалення рішень суворе: - Якщо поведінку можна виразити один раз у `qa-lab`, розмістіть її в `qa-lab`. -- Якщо поведінка залежить від одного channel transport, залиште її в цьому runner plugin або plugin harness. -- Якщо scenario потребує нової capability, яку може використовувати більше ніж один канал, додайте generic helper замість channel-specific branch у `suite.ts`. -- Якщо поведінка має сенс лише для одного transport, залиште scenario transport-specific і зробіть це явним у контракті scenario. +- Якщо поведінка залежить від одного channel transport, тримайте її в цьому runner plugin або plugin harness. +- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додайте універсальний helper замість channel-specific branch у `suite.ts`. +- Якщо поведінка має сенс лише для одного транспорту, залиште сценарій транспортно-специфічним і явно вкажіть це в контракті сценарію. -### Назви scenario helpers +### Назви helpers сценаріїв -Бажані generic helpers для нових scenarios: +Бажані універсальні helpers для нових сценаріїв: - `waitForTransportReady` - `waitForChannelReady` @@ -622,22 +624,21 @@ Runner plugins володіють transport contract: - `formatTransportTranscript` - `resetTransport` -Compatibility aliases залишаються доступними для наявних scenarios — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — але під час створення нових scenarios слід використовувати generic names. Aliases існують, щоб уникнути flag-day migration, а не як модель на майбутнє. +Compatibility aliases залишаються доступними для наявних сценаріїв — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — але для створення нових сценаріїв слід використовувати універсальні назви. Aliases існують, щоб уникнути flag-day migration, а не як модель на майбутнє. ## Reporting -`qa-lab` експортує Markdown protocol report зі спостереженої bus timeline. +`qa-lab` експортує Markdown protocol report зі спостереженої timeline bus. Report має відповідати на такі питання: - Що спрацювало -- Що не спрацювало +- Що не вдалося - Що залишилося заблокованим - Які follow-up scenarios варто додати -Для inventory доступних scenarios — корисного під час оцінювання follow-up work або підключення нового transport — запустіть `pnpm openclaw qa coverage` (додайте `--json` для machine-readable output). +Щоб отримати inventory доступних сценаріїв — корисно під час оцінювання follow-up work або підключення нового транспорту — запустіть `pnpm openclaw qa coverage` (додайте `--json` для machine-readable output). -Для перевірок характеру та стилю запустіть той самий scenario на кількох live model -refs і запишіть judged Markdown report: +Для перевірок character і style запустіть той самий сценарій на кількох live model refs і запишіть judged Markdown report: ```bash pnpm openclaw qa character-eval \ @@ -656,42 +657,42 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -Команда запускає дочірні процеси локального QA gateway, а не Docker. Character eval -scenarios мають задавати persona через `SOUL.md`, а потім виконувати звичайні user turns, -такі як чат, допомога з workspace і невеликі file tasks. Candidate model не слід -повідомляти, що її оцінюють. Команда зберігає кожен повний -transcript, записує базову статистику запуску, а потім просить judge models у fast mode з -reasoning `xhigh`, де це підтримується, ранжувати запуски за naturalness, vibe і humor. -Використовуйте `--blind-judge-models` під час порівняння providers: judge prompt усе ще отримує -кожен transcript і run status, але candidate refs замінюються нейтральними -labels, такими як `candidate-01`; report зіставляє rankings назад із реальними refs після -parsing. -Candidate runs за замовчуванням використовують thinking `high`, з `medium` для GPT-5.5 і `xhigh` -для старіших OpenAI eval refs, які це підтримують. Перевизначте конкретного candidate inline за допомогою +Команда запускає дочірні процеси локального QA Gateway, а не Docker. Сценарії оцінювання персонажа +мають задавати персону через `SOUL.md`, а потім виконувати звичайні користувацькі ходи, +як-от чат, допомога з робочим простором і невеликі файлові завдання. Модель-кандидат +не повинна знати, що її оцінюють. Команда зберігає кожен повний +транскрипт, записує базову статистику запуску, а потім просить моделі-судді у швидкому режимі з +режимом міркування `xhigh`, де він підтримується, ранжувати запуски за природністю, загальним враженням і гумором. +Використовуйте `--blind-judge-models` під час порівняння провайдерів: підказка для судді все одно отримує +кожен транскрипт і статус запуску, але посилання на кандидатів замінюються нейтральними +мітками, такими як `candidate-01`; після розбору звіт зіставляє рейтинги з реальними +посиланнями. +Запуски кандидатів типово використовують мислення `high`, з `medium` для GPT-5.5 і `xhigh` +для старіших eval-посилань OpenAI, які це підтримують. Перевизначте конкретного кандидата вбудовано за допомогою `--model provider/model,thinking=`. `--thinking ` усе ще задає -global fallback, а старішу форму `--model-thinking ` збережено -для compatibility. -OpenAI candidate refs за замовчуванням використовують fast mode, щоб priority processing застосовувався там, -де провайдер це підтримує. Додайте `,fast`, `,no-fast` або `,fast=false` inline, коли -окремому candidate або judge потрібне перевизначення. Передавайте `--fast` лише тоді, коли хочете -примусово ввімкнути fast mode для кожної candidate model. Тривалості candidate і judge -записуються в report для benchmark analysis, але judge prompts явно вказують +глобальний резервний варіант, а старіша форма `--model-thinking ` +збережена для сумісності. +Посилання на кандидатів OpenAI типово використовують швидкий режим, щоб пріоритетна обробка застосовувалася там, де +провайдер її підтримує. Додайте `,fast`, `,no-fast` або `,fast=false` вбудовано, коли +окремий кандидат або суддя потребує перевизначення. Передавайте `--fast` лише тоді, коли потрібно +примусово ввімкнути швидкий режим для кожної моделі-кандидата. Тривалості роботи кандидатів і суддів +записуються у звіт для аналізу бенчмарків, але підказки суддям явно вказують не ранжувати за швидкістю. -Запуски candidate і judge model обидва за замовчуванням мають concurrency 16. Зменште -`--concurrency` або `--judge-concurrency`, коли provider limits або навантаження локального gateway +Запуски моделей-кандидатів і моделей-суддів типово мають concurrency 16. Зменште +`--concurrency` або `--judge-concurrency`, коли ліміти провайдера або навантаження на локальний Gateway роблять запуск надто шумним. -Якщо candidate `--model` не передано, character eval за замовчуванням використовує +Коли не передано жодної кандидатської `--model`, оцінювання персонажа типово використовує `openai/gpt-5.5`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, `moonshot/kimi-k2.5` і -`google/gemini-3.1-pro-preview`, коли `--model` не передано. -Якщо `--judge-model` не передано, judges за замовчуванням: +`google/gemini-3.1-pro-preview`, коли не передано жодної `--model`. +Коли не передано жодної `--judge-model`, судді типово використовують `openai/gpt-5.5,thinking=xhigh,fast` і `anthropic/claude-opus-4-6,thinking=high`. ## Пов’язана документація -- [Матриця QA](/uk/concepts/qa-matrix) -- [Канал QA](/uk/channels/qa-channel) +- [Matrix QA](/uk/concepts/qa-matrix) +- [QA Channel](/uk/channels/qa-channel) - [Тестування](/uk/help/testing) - [Панель керування](/uk/web/dashboard) diff --git a/docs/uk/gateway/doctor.md b/docs/uk/gateway/doctor.md index 45bccf1f3..62906a001 100644 --- a/docs/uk/gateway/doctor.md +++ b/docs/uk/gateway/doctor.md @@ -3,18 +3,18 @@ read_when: - Додавання або змінення міграцій doctor - Запровадження несумісних змін конфігурації sidebarTitle: Doctor -summary: 'Команда Doctor: перевірки справності, міграції конфігурації та кроки виправлення' +summary: 'Команда doctor: перевірки стану, міграції конфігурації та кроки відновлення' title: Діагностика x-i18n: - generated_at: "2026-05-05T00:55:58Z" + generated_at: "2026-05-05T01:21:21Z" model: gpt-5.5 provider: openai - source_hash: f8386e5d733ab599c78b96ad04135c8168cacdc55e864676aac26cd095a72685 + source_hash: 3e374f91d00d4b43a3852de6f746b044471e80af936d464a789061a31cadd09d 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, коли застосовно). + Приймає типові значення без запитів (включно з кроками перезапуску/сервісу/відновлення 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, які потребують підтвердження людини. Міграції застарілого стану запускаються автоматично, коли їх виявлено. + Запускається без запитів і застосовує лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії перезапуску/сервісу/sandbox, які потребують підтвердження людини. Міграції застарілого стану виконуються автоматично після виявлення. @@ -62,12 +62,12 @@ openclaw doctor openclaw doctor --deep ``` - Просканувати системні служби на додаткові встановлення gateway (launchd/systemd/schtasks). + Сканує системні сервіси на наявність додаткових інсталяцій Gateway (launchd/systemd/schtasks). -Якщо хочете переглянути зміни перед записом, спершу відкрийте файл конфігурації: +Якщо ви хочете переглянути зміни перед записом, спочатку відкрийте файл конфігурації: ```bash cat ~/.openclaw/openclaw.json @@ -76,121 +76,121 @@ cat ~/.openclaw/openclaw.json ## Що він робить (підсумок) - - - Необов’язкове попереднє оновлення для git-встановлень (лише інтерактивно). + + - Необов’язкове попереднє оновлення для git-інсталяцій (лише інтерактивно). - Перевірка актуальності протоколу UI (перезбирає Control UI, коли схема протоколу новіша). - - Перевірка справності + запит на перезапуск. - - Підсумок стану Skills (придатні/відсутні/заблоковані) і стан plugin. + - Перевірка стану + запит на перезапуск. + - Підсумок стану Skills (доступні/відсутні/заблоковані) і стан Plugin. - Нормалізація конфігурації для застарілих значень. - - Міграція конфігурації Talk із застарілих пласких полів `talk.*` у `talk.provider` + `talk.providers.`. + - Міграція конфігурації Talk із застарілих плоских полів `talk.*` у `talk.provider` + `talk.providers.`. - Перевірки міграції браузера для застарілих конфігурацій розширення Chrome і готовності Chrome MCP. - - Попередження про перевизначення провайдера OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). - - Попередження про затінення Codex OAuth (`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). - - Міграція застарілих ключів контракту маніфесту plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). - - Міграція застарілого сховища cron (`jobId`, `schedule.cron`, поля delivery/payload верхнього рівня, payload `provider`, прості fallback-завдання webhook `notify: true`). - - Міграція застарілої політики runtime агента до `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`. - - Очищення застарілої конфігурації plugin, коли plugins увімкнено; коли `plugins.enabled=false`, застарілі посилання на plugin вважаються інертною конфігурацією стримування та зберігаються. + - Попередження 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 вважаються інертною конфігурацією ізоляції та зберігаються. - - Перевірка lock-файлів session і очищення застарілих lock-файлів. - - Ремонт transcript session для дубльованих гілок prompt-rewrite, створених ураженими збірками 2026.4.24. - - Виявлення tombstone для restart-recovery застряглого subagent, з підтримкою `--fix` для очищення застарілих прапорців перерваного відновлення, щоб startup не продовжував вважати дочірній процес restart-aborted. + - Перевірка lock-файлів сесій і очищення застарілих lock-файлів. + - Відновлення transcript сесій для дубльованих гілок prompt-rewrite, створених ураженими збірками 2026.4.24. + - Виявлення tombstone для restart-recovery завислих subagent із підтримкою `--fix` для очищення застарілих прапорців aborted recovery, щоб запуск не продовжував вважати дочірній процес restart-aborted. - Перевірки цілісності стану та дозволів (sessions, transcripts, state dir). - Перевірки дозволів файлу конфігурації (chmod 600) під час локального запуску. - - Справність автентифікації моделі: перевіряє завершення терміну OAuth, може оновлювати токени, термін яких минає, і повідомляє стани cooldown/disabled auth-profile. + - Стан автентифікації моделей: перевіряє закінчення строку OAuth, може оновлювати токени, що скоро спливають, і повідомляє стани cooldown/disabled auth-profile. - Виявлення додаткового каталогу workspace (`~/openclaw`). - - - Ремонт образу sandbox, коли sandboxing увімкнено. - - Міграція застарілої служби та виявлення додаткового gateway. + + - Відновлення образу sandbox, коли 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, шляхи менеджера версій). - - Діагностика конфліктів порту Gateway (стандартно `18789`). + - Перевірки 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`). - - Попередження безпеки для відкритих політик DM. - - Перевірки автентифікації Gateway для режиму локального токена (пропонує генерацію токена, коли джерела токена немає; не перезаписує конфігурації token SecretRef). - - Виявлення проблем pairing пристрою (очікувані перші запити pair, очікувані оновлення ролі/scope, drift застарілого локального кешу device-token і drift автентифікації paired-record). + - Попередження безпеки для відкритих DM-політик. + - Перевірки автентифікації Gateway для режиму локального токена (пропонує генерацію токена, коли джерела токена немає; не перезаписує конфігурації SecretRef токенів). + - Виявлення проблем pairing пристроїв (очікувані перші запити pairing, очікувані підвищення ролі/області, застаріле розходження кешу локального device-token і розходження автентифікації paired-record). - Перевірка systemd linger у Linux. - - Перевірка розміру bootstrap-файлу workspace (попередження про обрізання/наближення до ліміту для файлів контексту). - - Перевірка готовності Skills для стандартного агента; повідомляє дозволені skills з відсутніми bins, env, config або вимогами ОС, а `--fix` може вимкнути недоступні skills у `skills.entries`. + - Перевірка розміру bootstrap-файлу workspace (попередження про обрізання/наближення до ліміту для контекстних файлів). + - Перевірка готовності Skills для типового агента; повідомляє дозволені skills із відсутніми binaries, env, config або вимогами до ОС, а `--fix` може вимкнути недоступні skills у `skills.entries`. - Перевірка стану shell completion і автоматичне встановлення/оновлення. - - Перевірка готовності провайдера embedding для пошуку пам’яті (локальна модель, remote API key або QMD binary). + - Перевірка готовності провайдера embedding для пошуку в пам’яті (локальна модель, віддалений API-ключ або QMD binary). - Перевірки source install (невідповідність pnpm workspace, відсутні UI assets, відсутній tsx binary). - Записує оновлену конфігурацію + метадані wizard. -## Backfill і reset UI Dreams +## Зворотне заповнення й скидання Dreams UI -Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded** для grounded dreaming workflow. Ці дії використовують RPC-методи в стилі gateway doctor, але вони **не** є частиною ремонту/міграції CLI `openclaw doctor`. +Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded** для workflow grounded dreaming. Ці дії використовують RPC-методи у стилі Gateway doctor, але вони **не** є частиною repair/migration CLI `openclaw doctor`. Що вони роблять: -- **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному workspace, запускає прохід grounded REM diary і записує оборотні backfill-записи в `DREAMS.md`. -- **Reset** видаляє лише ці позначені backfill-записи diary з `DREAMS.md`. -- **Clear Grounded** видаляє лише staged grounded-only short-term entries, що походять з історичного replay і ще не накопичили live recall або daily support. +- **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 ``` -Це додає grounded durable candidates до short-term dreaming store, залишаючи `DREAMS.md` поверхнею перегляду. +Це готує grounded durable candidates у short-term dreaming store, залишаючи `DREAMS.md` поверхнею для перегляду. -## Детальна поведінка й обґрунтування +## Детальна поведінка та обґрунтування - - Якщо це git checkout і doctor працює інтерактивно, він пропонує оновити (fetch/rebase/build) перед запуском doctor. + + Якщо це git checkout і doctor працює інтерактивно, він пропонує оновитися (fetch/rebase/build) перед запуском doctor. - Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction` без перевизначення для конкретного каналу), 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. + Це включає застарілі плоскі поля 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, щоб зберегти наявну поведінку bundled provider, а - потім вказує на суворіший параметр `"allowlist"`. + застарілих allowlist configs, щоб зберегти наявну поведінку bundled provider, а + потім вказує на суворіше налаштування `"allowlist"`. - Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися й просять запустити `openclaw doctor`. + Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися й просять вас запустити `openclaw doctor`. Doctor: - Пояснить, які застарілі ключі знайдено. - - Покаже міграцію, яку він застосував. + - Покаже застосовану міграцію. - Перепише `~/.openclaw/openclaw.json` з оновленою схемою. - Gateway також автоматично запускає міграції doctor під час startup, коли виявляє застарілий формат конфігурації, тому застарілі конфігурації ремонтуються без ручного втручання. Міграції сховища cron job обробляються через `openclaw doctor --fix`. + Gateway також автоматично запускає міграції doctor під час старту, коли виявляє застарілий формат конфігурації, тож застарілі конфігурації відновлюються без ручного втручання. Міграції сховища Cron job обробляються `openclaw doctor --fix`. Поточні міграції: @@ -199,7 +199,7 @@ 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.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default` @@ -217,295 +217,295 @@ 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 може зберегти наявну відповідну іменовану/типову ціль) - `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` (застаріле налаштування ретранслятора розширення) + - видалити `browser.relayBindHost` (застаріле налаштування ретранслятора extension) - застаріле `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, doctor нормалізує її до поточної моделі підключення Chrome MCP на локальному хості: + Якщо ваша конфігурація браузера все ще вказує на видалений шлях Chrome extension, doctor нормалізує її до поточної моделі підключення host-local Chrome MCP: - `browser.profiles.*.driver: "extension"` стає `"existing-session"` - `browser.relayBindHost` видаляється - Doctor також перевіряє шлях Chrome MCP на локальному хості, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`: + Doctor також перевіряє шлях host-local Chrome MCP, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`: - - перевіряє, чи встановлено Google Chrome на тому самому хості для типових профілів автоматичного підключення + - перевіряє, чи Google Chrome встановлено на тому самому хості для типових профілів автоматичного підключення - перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144 - - нагадує ввімкнути віддалене налагодження на сторінці перевірки браузера (наприклад `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`) + - нагадує ввімкнути віддалене налагодження на сторінці перевірки браузера (наприклад, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`) - Doctor не може ввімкнути налаштування з боку Chrome замість вас. Chrome MCP на локальному хості все ще потребує: + Doctor не може ввімкнути налаштування на стороні Chrome за вас. Host-local Chrome MCP усе ще потребує: - - браузера на основі Chromium 144+ на хості Gateway/вузла + - браузера на основі Chromium 144+ на хості gateway/node - локально запущеного браузера - увімкненого віддаленого налагодження в цьому браузері - підтвердження першого запиту згоди на підключення в браузері - Готовність тут стосується лише передумов локального підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, досі потребують керованого браузера або сирого профілю CDP. + Готовність тут стосується лише локальних передумов підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, усе ще потребують керованого браузера або raw CDP-профілю. - Ця перевірка **не** застосовується до Docker, sandbox, remote-browser чи інших headless-потоків. Вони й надалі використовують сирий CDP. + Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших headless-потоків. Вони й надалі використовують raw CDP. - Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє кінцеву точку авторизації 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 справний. - Якщо раніше ви додали застарілі транспортні налаштування в `models.providers.openai-codex`, вони можуть затінити вбудований шлях провайдера Codex OAuth, який новіші випуски використовують автоматично. Doctor попереджає, коли бачить ці старі транспортні налаштування разом із Codex OAuth, щоб ви могли видалити або переписати застаріле транспортне перевизначення й повернути вбудовану маршрутизацію/резервну поведінку. Користувацькі проксі та перевизначення лише заголовків і надалі підтримуються та не викликають це попередження. + Якщо раніше ви додали застарілі налаштування транспорту OpenAI у `models.providers.openai-codex`, вони можуть затіняти вбудований шлях провайдера Codex OAuth, який новіші випуски використовують автоматично. Doctor попереджає, коли бачить ці старі налаштування транспорту разом із Codex OAuth, щоб ви могли видалити або переписати застаріле перевизначення транспорту й повернути вбудовану поведінку маршрутизації/резервування. Користувацькі проксі та перевизначення лише заголовків усе ще підтримуються й не спричиняють цього попередження. - Коли ввімкнено вбудований Plugin Codex, doctor також перевіряє, чи посилання первинної моделі `openai-codex/*` досі розв’язуються через типовий PI runner. Ця комбінація чинна, коли ви хочете використовувати автентифікацію Codex OAuth/передплати через PI, але її легко сплутати з нативним harness сервера застосунку Codex. Doctor попереджає та вказує на явну форму сервера застосунку: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`. + Коли ввімкнено вбудований 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`. - Doctor не виправляє це автоматично, оскільки обидва маршрути чинні: + Doctor не виправляє це автоматично, оскільки обидва маршрути є допустимими: - - `openai-codex/*` + PI означає "використовувати автентифікацію Codex OAuth/передплати через звичайний runner OpenClaw." - - `openai/*` + `agentRuntime.id: "codex"` означає "запустити вбудований хід через нативний сервер застосунку Codex." - - `/codex ...` означає "керувати нативною розмовою Codex або прив’язати її з чату." + - `openai-codex/*` + PI означає "використовувати автентифікацію Codex OAuth/підписки через звичайний runner OpenClaw." + - `openai/*` + `agentRuntime.id: "codex"` означає "виконати вбудований turn через нативний app-server Codex." + - `/codex ...` означає "керувати або прив'язати нативну розмову Codex із чату." - `/acp ...` або `runtime: "acp"` означає "використовувати зовнішній адаптер ACP/acpx." - Якщо з’являється попередження, виберіть потрібний маршрут і вручну змініть конфігурацію. Залиште попередження без змін, коли 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-моделі, закріплені ID harness, прив'язки 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/*.json` (крім `oauth.json`) - до `~/.openclaw/credentials/whatsapp//...` (типовий ID облікового запису: `default`) - Ці міграції виконуються за принципом best-effort та є ідемпотентними; doctor виводитиме попередження, коли залишатиме будь-які застарілі папки як резервні копії. Gateway/CLI також автоматично мігрує застарілі сеанси + каталог агента під час запуску, щоб історія/автентифікація/моделі потрапляли до шляху для окремого агента без ручного запуску doctor. Автентифікація WhatsApp навмисно мігрується лише через `openclaw doctor`. Нормалізація провайдера/мапи провайдерів Talk тепер порівнює за структурною рівністю, тому різниці лише в порядку ключів більше не спричиняють повторних no-op змін `doctor --fix`. + Ці міграції виконуються за принципом найкращої спроби та є ідемпотентними; doctor виводитиме попередження, коли залишатиме будь-які застарілі папки як резервні копії. Gateway/CLI також автоматично мігрує застарілі сесії + каталог агента під час запуску, щоб історія/автентифікація/моделі потрапили в шлях для кожного агента без ручного запуску doctor. Нормалізація talk provider/provider-map тепер порівнює за структурною рівністю, тому відмінності лише в порядку ключів більше не спричиняють повторних no-op змін `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`, коли перевизначено) на старі форми завдань, які планувальник досі приймає для сумісності. + + Doctor також перевіряє сховище завдань cron (`~/.openclaw/cron/jobs.json` за замовчуванням або `cron.store`, коли перевизначено) на старі форми завдань, які scheduler усе ще приймає для сумісності. Поточні очищення cron включають: - `jobId` → `id` - `schedule.cron` → `schedule.expr` - верхньорівневі поля payload (`message`, `model`, `thinking`, ...) → `payload` - - верхньорівневі поля доставки (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` - - псевдоніми доставки `provider` у payload → явний `delivery.channel` - - прості застарілі резервні webhook-завдання `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook` + - верхньорівневі поля delivery (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` + - псевдоніми delivery `provider` у payload → явний `delivery.channel` + - прості застарілі fallback-завдання webhook `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook` - Doctor автоматично мігрує завдання `notify: true` лише тоді, коли може зробити це без зміни поведінки. Якщо завдання поєднує застарілий резервний notify із наявним режимом доставки, що не є webhook, doctor попереджає та залишає це завдання для ручного перегляду. + Doctor автоматично мігрує завдання `notify: true` лише тоді, коли може зробити це без зміни поведінки. Якщо завдання поєднує застарілий fallback notify з наявним режимом delivery, що не є webhook, doctor попереджає і залишає це завдання для ручного перегляду. - У 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` для поточних перевірок стану. + У 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`. - - Doctor сканує кожен каталог сеансів агентів на наявність застарілих файлів блокування запису — файлів, що залишилися після аварійного завершення сеансу. Для кожного знайденого файлу блокування він повідомляє: шлях, PID, чи PID досі активний, вік блокування та чи вважається воно застарілим (мертвий PID або старше ніж 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше виводить примітку й радить повторно запустити з `--fix`. + + Засіб діагностики сканує кожен каталог сеансу агента на наявність застарілих файлів блокування запису — файлів, що залишилися після аварійного завершення сеансу. Для кожного знайденого файлу блокування він повідомляє: шлях, PID, чи PID досі активний, вік блокування та чи вважається воно застарілим (мертвий PID або старше за 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше друкує примітку й указує повторно запустити з `--fix`. - - Doctor сканує JSONL-файли сеансів агентів на дубльовану форму гілки, створену помилкою переписування стенограми промпта 2026.4.24: покинутий хід користувача з внутрішнім runtime-контекстом OpenClaw плюс активний сусідній елемент із тим самим видимим промптом користувача. У режимі `--fix` / `--repair` doctor створює резервну копію кожного ураженого файлу поруч з оригіналом і переписує стенограму на активну гілку, щоб історія gateway і читачі пам’яті більше не бачили дубльованих ходів. + + Засіб діагностики сканує JSONL-файли сеансів агентів на дубльовану форму гілки, створену помилкою переписування транскрипту prompt від 2026.4.24: покинутий хід користувача з внутрішнім runtime-контекстом OpenClaw плюс активний сусідній елемент із тим самим видимим prompt користувача. У режимі `--fix` / `--repair` засіб діагностики створює резервну копію кожного ураженого файлу поруч з оригіналом і переписує транскрипт до активної гілки, щоб історія gateway і читачі пам'яті більше не бачили дубльованих ходів. - Каталог стану — це операційний стовбур системи. Якщо він зникне, ви втратите сеанси, облікові дані, журнали й конфігурацію (якщо не маєте резервних копій деінде). + Каталог стану — це операційний стовбур системи. Якщо він зникне, ви втратите сеанси, облікові дані, журнали та конфігурацію (якщо не маєте резервних копій деінде). - Doctor перевіряє: + Засіб діагностики перевіряє: - - **Каталог стану відсутній**: попереджає про катастрофічну втрату стану, пропонує повторно створити каталог і нагадує, що не може відновити відсутні дані. - - **Права доступу каталогу стану**: перевіряє можливість запису; пропонує виправити права доступу (і виводить підказку `chown`, коли виявлено невідповідність власника/групи). - - **Синхронізований із хмарою каталог стану 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`. + - **Відсутній каталог стану**: попереджає про катастрофічну втрату стану, пропонує повторно створити каталог і нагадує, що не може відновити відсутні дані. + - **Дозволи каталогу стану**: перевіряє можливість запису; пропонує виправити дозволи (і виводить підказку `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`. - - Doctor перевіряє профілі OAuth у сховищі автентифікації, попереджає, коли токени незабаром закінчуються або вже закінчилися, і може оновити їх, коли це безпечно. Якщо профіль Anthropic OAuth/токена застарів, він пропонує API-ключ Anthropic або шлях setup-token Anthropic. Запити на оновлення з’являються лише під час інтерактивного запуску (TTY); `--non-interactive` пропускає спроби оновлення. + + Засіб діагностики перевіряє OAuth-профілі в сховищі автентифікації, попереджає, коли термін дії токенів наближається до завершення або вже минув, і може оновити їх, коли це безпечно. Якщо OAuth/токен-профіль Anthropic застарів, він пропонує API-ключ Anthropic або шлях setup-token Anthropic. Запити на оновлення з'являються лише під час інтерактивного запуску (TTY); `--non-interactive` пропускає спроби оновлення. - Коли оновлення OAuth остаточно не вдається (наприклад, `refresh_token_reused`, `invalid_grant` або провайдер повідомляє, що потрібно знову ввійти), doctor повідомляє, що потрібна повторна автентифікація, і друкує точну команду `openclaw models auth login --provider ...`, яку треба виконати. + Коли оновлення OAuth остаточно не вдається (наприклад, `refresh_token_reused`, `invalid_grant` або provider повідомляє, що потрібно ввійти знову), засіб діагностики повідомляє, що потрібна повторна автентифікація, і друкує точну команду `openclaw models auth login --provider ...`, яку треба виконати. - Doctor також повідомляє про профілі автентифікації, які тимчасово непридатні через: + Засіб діагностики також повідомляє про профілі автентифікації, які тимчасово непридатні через: - - короткі періоди очікування (ліміти швидкості/тайм-аути/збої автентифікації) - - довші вимкнення (збої оплати/кредиту) + - короткі періоди очікування (обмеження швидкості/тайм-аути/помилки автентифікації) + - довші вимкнення (помилки білінгу/кредитів) - - Якщо встановлено `hooks.gmail.model`, doctor перевіряє посилання на модель за каталогом і списком дозволених та попереджає, коли воно не розв’яжеться або заборонене. + + Якщо `hooks.gmail.model` задано, засіб діагностики перевіряє посилання на модель за каталогом і allowlist та попереджає, коли воно не розв'язується або заборонене. - Коли sandboxing увімкнено, doctor перевіряє Docker-образи й пропонує зібрати або перемкнутися на застарілі назви, якщо поточний образ відсутній. + Коли sandboxing увімкнено, засіб діагностики перевіряє Docker-образи й пропонує зібрати або перемкнутися на застарілі назви, якщо поточний образ відсутній. - Doctor видаляє застарілий створений OpenClaw проміжний стан залежностей plugin у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Це охоплює застарілі згенеровані корені залежностей, старі каталоги етапу встановлення, локальні для пакета залишки від попереднього коду відновлення залежностей bundled-plugin, а також осиротілі або відновлені керовані npm-копії bundled `@openclaw/*` plugins, які можуть затіняти поточний bundled-маніфест. + Засіб діагностики видаляє застарілий staging-стан залежностей plugin, згенерований OpenClaw, у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Це охоплює застарілі згенеровані корені залежностей, старі каталоги етапу встановлення, локальне для пакета сміття від попереднього коду відновлення залежностей bundled-plugin, а також осиротілі або відновлені керовані npm-копії bundled `@openclaw/*` plugins, які можуть затіняти поточний bundled manifest. - Doctor також може перевстановити налаштовані завантажувані plugins, коли конфігурація посилається на них, але локальний реєстр plugin не може їх знайти. Для externalization bundled-plugin 2026.5.2 doctor автоматично встановлює завантажувані plugins, які вже використовує наявна конфігурація, а потім покладається на `meta.lastTouchedVersion`, щоб виконати цей релізний прохід лише один раз. Запуск Gateway і перезавантаження конфігурації не запускають менеджери пакетів; встановлення plugin лишаються явною роботою doctor/install/update. + Засіб діагностики також може перевстановити відсутні завантажувані plugins, коли конфігурація посилається на них, але локальний реєстр plugin не може їх знайти. Приклади включають матеріальні `plugins.entries`, налаштовані параметри channel/provider/search і налаштовані середовища виконання агентів. Під час оновлень пакета засіб діагностики уникає запуску package-manager-відновлення plugin, поки core-пакет замінюється; запустіть `openclaw doctor --fix` знову після оновлення, якщо налаштований plugin усе ще потребує відновлення. Запуск Gateway і перезавантаження конфігурації не запускають package managers; встановлення plugin залишаються явною роботою doctor/install/update. - Doctor виявляє застарілі сервіси gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити сервіс OpenClaw з поточним портом gateway. Він також може сканувати додаткові подібні до gateway сервіси й друкувати підказки з очищення. Сервіси OpenClaw gateway з іменами профілів вважаються повноцінними й не позначаються як "зайві." + Засіб діагностики виявляє застарілі сервіси gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити сервіс OpenClaw із поточним портом gateway. Він також може сканувати додаткові gateway-подібні сервіси й друкувати підказки з очищення. Gateway-сервіси OpenClaw з іменами профілів вважаються повноцінними й не позначаються як "додаткові". - У Linux, якщо користувацький сервіс gateway відсутній, але існує системний сервіс OpenClaw gateway, doctor не встановлює автоматично другий користувацький сервіс. Перевірте за допомогою `openclaw gateway status --deep` або `openclaw doctor --deep`, а потім видаліть дублікат або встановіть `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли системний supervisor керує життєвим циклом gateway. + У Linux, якщо user-level gateway-сервіс відсутній, але system-level gateway-сервіс OpenClaw існує, засіб діагностики не встановлює автоматично другий user-level сервіс. Перевірте за допомогою `openclaw gateway status --deep` або `openclaw doctor --deep`, а потім видаліть дублікат або встановіть `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли життєвим циклом gateway керує системний supervisor. - - Коли обліковий запис каналу Matrix має очікувану або придатну до дії міграцію застарілого стану, doctor (у режимі `--fix` / `--repair`) створює знімок перед міграцією, а потім виконує найкращі можливі кроки міграції: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки журналюються, а запуск продовжується. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається. + + Коли обліковий запис channel Matrix має pending або actionable застарілу міграцію стану, засіб діагностики (у режимі `--fix` / `--repair`) створює знімок перед міграцією, а потім виконує best-effort кроки міграції: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки записуються до журналу, а запуск триває. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається. - Doctor тепер перевіряє стан сполучення пристроїв у межах звичайного проходу перевірки стану. + Засіб діагностики тепер перевіряє стан сполучення пристроїв як частину звичайного проходу перевірки стану. Що він повідомляє: - - очікувані запити на перше сполучення - - очікувані підвищення ролі для вже сполучених пристроїв - - очікувані підвищення scope для вже сполучених пристроїв - - відновлення невідповідності публічного ключа, коли id пристрою все ще збігається, але ідентичність пристрою більше не збігається із затвердженим записом + - pending запити першого сполучення + - pending підвищення ролі для вже сполучених пристроїв + - pending підвищення scope для вже сполучених пристроїв + - відновлення невідповідності відкритого ключа, коли ідентифікатор пристрою все ще збігається, але ідентичність пристрою більше не збігається із затвердженим записом - сполучені записи без активного токена для затвердженої ролі - - сполучені токени, чиї scope відхиляються за межі затвердженого базового сполучення + - сполучені токени, чиї scopes відхиляються від затвердженої базової лінії сполучення - локальні кешовані записи device-token для поточної машини, що передують ротації токена на боці gateway або містять застарілі метадані scope - Doctor не затверджує автоматично запити на сполучення й не виконує автоматичну ротацію токенів пристроїв. Натомість він друкує точні наступні кроки: + Засіб діагностики не затверджує запити сполучення автоматично й не обертає токени пристроїв автоматично. Натомість він друкує точні наступні кроки: - - переглянути очікувані запити за допомогою `openclaw devices list` - - затвердити точний запит за допомогою `openclaw devices approve ` - - згенерувати свіжий токен ротацією за допомогою `openclaw devices rotate --device --role ` - - видалити й повторно затвердити застарілий запис за допомогою `openclaw devices remove ` + - перегляньте pending запити за допомогою `openclaw devices list` + - затвердьте точний запит за допомогою `openclaw devices approve ` + - оберніть свіжий токен за допомогою `openclaw devices rotate --device --role ` + - видаліть і повторно затвердьте застарілий запис за допомогою `openclaw devices remove ` - Це закриває поширену прогалину "вже сполучено, але все ще вимагається сполучення": doctor тепер відрізняє перше сполучення від очікуваних підвищень ролі/scope і від застарілого дрейфу токена/ідентичності пристрою. + Це закриває поширену прогалину "already paired but still getting pairing required": засіб діагностики тепер відрізняє перше сполучення від pending підвищень ролі/scope і від дрейфу застарілого токена/ідентичності пристрою. - Doctor виводить попередження, коли провайдер відкритий для DM без списку дозволених або коли політику налаштовано небезпечним способом. + Засіб діагностики видає попередження, коли provider відкритий для DM без allowlist або коли політику налаштовано небезпечним способом. - Якщо запущено як користувацький сервіс systemd, doctor гарантує, що lingering увімкнено, щоб gateway залишався активним після виходу з системи. + Якщо запущено як user service systemd, засіб діагностики забезпечує ввімкнення lingering, щоб gateway залишався активним після виходу з системи. - - Doctor друкує підсумок стану робочого простору для типового агента: + + Засіб діагностики друкує підсумок стану workspace для агента за замовчуванням: - - **Стан Skills**: підраховує придатні skills, skills із відсутніми вимогами та заблоковані списком дозволених skills. - - **Застарілі каталоги робочого простору**: попереджає, коли `~/openclaw` або інші застарілі каталоги робочого простору існують поруч із поточним робочим простором. - - **Стан Plugin**: підраховує увімкнені/вимкнені/помилкові plugins; перелічує ID plugin для будь-яких помилок; повідомляє можливості bundle plugin. + - **Стан Skills**: рахує eligible, missing-requirements і allowlist-blocked skills. + - **Застарілі каталоги workspace**: попереджає, коли `~/openclaw` або інші застарілі каталоги workspace існують поряд із поточним workspace. + - **Стан Plugin**: рахує enabled/disabled/errored plugins; перелічує ідентифікатори plugin для будь-яких помилок; повідомляє можливості bundle plugin. - **Попередження сумісності Plugin**: позначає plugins, які мають проблеми сумісності з поточним runtime. - - **Діагностика Plugin**: показує будь-які попередження або помилки під час завантаження, виведені реєстром plugin. + - **Діагностика Plugin**: показує будь-які попередження або помилки часу завантаження, видані реєстром plugin. - - Doctor перевіряє, чи файли bootstrap робочого простору (наприклад `AGENTS.md`, `CLAUDE.md` або інші вставлені файли контексту) наближаються до налаштованого бюджету символів або перевищують його. Він повідомляє для кожного файлу кількість сирих і вставлених символів, відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість вставлених символів як частку від загального бюджету. Коли файли обрізані або близькі до ліміту, doctor друкує поради з налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`. + + Засіб діагностики перевіряє, чи bootstrap-файли workspace (наприклад, `AGENTS.md`, `CLAUDE.md` або інші інжектовані файли контексту) близькі до налаштованого ліміту символів або перевищують його. Він повідомляє для кожного файлу сирі та інжектовані кількості символів, відсоток усічення, причину усічення (`max/file` або `max/total`) і загальну кількість інжектованих символів як частку загального бюджету. Коли файли усічено або вони близькі до ліміту, засіб діагностики друкує поради з налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`. - - Коли `openclaw doctor --fix` видаляє відсутній channel plugin, він також видаляє висячі channel-scoped налаштування, що посилалися на цей plugin: записи `channels.`, цілі Heartbeat, які називали канал, і перевизначення `agents.*.models["/*"]`. Це запобігає циклам завантаження Gateway, коли runtime каналу зник, але конфігурація все ще просить gateway прив’язатися до нього. + + Коли `openclaw doctor --fix` видаляє відсутній channel plugin, він також видаляє висячі channel-scoped конфігурації, які посилалися на цей plugin: записи `channels.`, цілі Heartbeat, що називали channel, і перевизначення `agents.*.models["/*"]`. Це запобігає циклам завантаження Gateway, коли runtime channel зник, але конфігурація все ще просить gateway прив'язатися до нього. - Doctor перевіряє, чи встановлено автодоповнення клавішею Tab для поточного shell (zsh, bash, fish або PowerShell): + Засіб діагностики перевіряє, чи встановлено автодоповнення tab для поточного shell (zsh, bash, fish або PowerShell): - - Якщо профіль shell використовує повільний динамічний шаблон доповнення (`source <(openclaw completion ...)`), doctor оновлює його до швидшого варіанта кешованого файлу. - - Якщо доповнення налаштоване у профілі, але файл кешу відсутній, doctor автоматично відновлює кеш. - - Якщо доповнення взагалі не налаштоване, doctor пропонує встановити його (лише інтерактивний режим; пропускається з `--non-interactive`). + - Якщо профіль shell використовує повільний динамічний шаблон completion (`source <(openclaw completion ...)`), засіб діагностики оновлює його до швидшого варіанта з кешованим файлом. + - Якщо completion налаштовано в профілі, але файл кешу відсутній, засіб діагностики автоматично регенерує кеш. + - Якщо completion взагалі не налаштовано, засіб діагностики пропонує встановити його (лише інтерактивний режим; пропускається з `--non-interactive`). - Запустіть `openclaw completion --write-state`, щоб вручну відновити кеш. + Запустіть `openclaw completion --write-state`, щоб регенерувати кеш вручну. - Doctor перевіряє готовність локальної автентифікації токена gateway. + Засіб діагностики перевіряє готовність автентифікації локального токена gateway. - - Якщо режим токена потребує токен, а джерела токена немає, doctor пропонує згенерувати його. - - Якщо `gateway.auth.token` керується SecretRef, але недоступний, doctor попереджає й не перезаписує його відкритим текстом. - - `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли не налаштовано жоден SecretRef токена. + - Якщо режим токена потребує токен, а джерела токена не існує, засіб діагностики пропонує згенерувати його. + - Якщо `gateway.auth.token` керується SecretRef, але недоступний, засіб діагностики попереджає й не перезаписує його відкритим текстом. + - `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли не налаштовано token SecretRef. - Деякі процеси відновлення мають перевіряти налаштовані облікові дані, не послаблюючи runtime-поведінку fail-fast. + Деякі потоки відновлення потребують перевірки налаштованих облікових даних без послаблення fail-fast поведінки runtime. - - `openclaw doctor --fix` тепер використовує ту саму модель зведення SecretRef лише для читання, що й команди сімейства status, для цільових виправлень конфігурації. - - Приклад: виправлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використати налаштовані облікові дані бота, коли вони доступні. - - Якщо токен бота Telegram налаштовано через SecretRef, але він недоступний у поточному шляху команди, засіб діагностики повідомляє, що облікові дані налаштовані, але недоступні, і пропускає автоматичне розв’язання замість аварійного завершення або помилкового повідомлення, що токен відсутній. + - `openclaw doctor --fix` тепер використовує ту саму модель read-only зведення SecretRef, що й команди сімейства status, для цільового ремонту конфігурації. + - Приклад: ремонт Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використовувати налаштовані облікові дані бота, коли вони доступні. + - Якщо токен бота Telegram налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає автоматичне розв'язання замість збою або помилкового повідомлення, що токен відсутній. - Засіб діагностики виконує перевірку стану й пропонує перезапустити Gateway, коли він виглядає несправним. + Команда doctor виконує перевірку стану й пропонує перезапустити Gateway, коли він виглядає несправним. - - Засіб діагностики перевіряє, чи налаштований постачальник embedding для пошуку в пам’яті готовий для агента за замовчуванням. Поведінка залежить від налаштованого backend і постачальника: + + Команда doctor перевіряє, чи налаштований постачальник embedding для пошуку в пам'яті готовий для агента за замовчуванням. Поведінка залежить від налаштованого бекенда й постачальника: - - **Backend QMD**: перевіряє, чи доступний і придатний до запуску бінарний файл `qmd`. Якщо ні, виводить поради з виправлення, включно з пакетом npm і варіантом ручного шляху до бінарного файла. - - **Явний локальний постачальник**: перевіряє наявність локального файла моделі або розпізнаної URL-адреси віддаленої/завантажуваної моделі. Якщо її немає, пропонує перейти на віддаленого постачальника. - - **Явний віддалений постачальник** (`openai`, `voyage` тощо): перевіряє, чи є API-ключ у середовищі або сховищі автентифікації. Виводить дієві підказки з виправлення, якщо його немає. - - **Автоматичний постачальник**: спочатку перевіряє наявність локальної моделі, а потім пробує кожного віддаленого постачальника в порядку автоматичного вибору. + - **Бекенд QMD**: перевіряє, чи бінарний файл `qmd` доступний і може запуститися. Якщо ні, виводить рекомендації з виправлення, включно з npm-пакетом і варіантом ручного шляху до бінарного файла. + - **Явний локальний постачальник**: перевіряє наявність локального файла моделі або розпізнаної віддаленої/завантажуваної URL-адреси моделі. Якщо відсутні, пропонує перейти на віддаленого постачальника. + - **Явний віддалений постачальник** (`openai`, `voyage` тощо): перевіряє, чи API-ключ присутній у середовищі або сховищі автентифікації. Виводить дієві підказки для виправлення, якщо його бракує. + - **Автоматичний постачальник**: спочатку перевіряє доступність локальної моделі, а потім пробує кожного віддаленого постачальника в порядку автоматичного вибору. - Коли доступний кешований результат перевірки Gateway (Gateway був справним на момент перевірки), засіб діагностики зіставляє його результат із конфігурацією, видимою для CLI, і позначає будь-яку невідповідність. Засіб діагностики не запускає новий embedding ping у типовому шляху; використовуйте команду глибокого статусу пам’яті, коли потрібна жива перевірка постачальника. + Коли доступний кешований результат перевірки Gateway (Gateway був справним на момент перевірки), doctor зіставляє його результат із конфігурацією, видимою для CLI, і зазначає будь-яку розбіжність. Doctor не запускає новий embedding ping у стандартному шляху; використовуйте команду глибокого статусу пам'яті, коли потрібна жива перевірка постачальника. Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding під час виконання. - Якщо Gateway справний, засіб діагностики запускає перевірку стану каналу й повідомляє попередження із запропонованими виправленнями. + Якщо Gateway справний, doctor виконує перевірку стану каналу й повідомляє попередження із запропонованими виправленнями. - - Засіб діагностики перевіряє встановлену конфігурацію супервізора (launchd/systemd/schtasks) на відсутні або застарілі стандартні значення (наприклад, залежності systemd від network-online і затримку перезапуску). Коли знаходить невідповідність, рекомендує оновлення й може переписати файл служби/завдання до поточних стандартних значень. + + Doctor перевіряє встановлену конфігурацію супервізора (launchd/systemd/schtasks) на відсутні або застарілі стандартні значення (наприклад, залежності systemd від network-online і затримку перезапуску). Коли знаходить невідповідність, рекомендує оновлення й може перезаписати файл служби/завдання до поточних стандартних значень. Примітки: - - `openclaw doctor` запитує підтвердження перед переписуванням конфігурації супервізора. - - `openclaw doctor --yes` приймає типові запити на виправлення. + - `openclaw doctor` запитує підтвердження перед перезаписом конфігурації супервізора. + - `openclaw doctor --yes` приймає стандартні запити на ремонт. - `openclaw doctor --repair` застосовує рекомендовані виправлення без запитів. - `openclaw doctor --repair --force` перезаписує користувацькі конфігурації супервізора. - - `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає засіб діагностики в режимі лише читання для життєвого циклу служби Gateway. Він усе ще повідомляє стан служби й виконує виправлення, не пов’язані зі службою, але пропускає встановлення/запуск/перезапуск/bootstrap служби, переписування конфігурації супервізора й очищення застарілих служб, оскільки цим життєвим циклом керує зовнішній супервізор. - - На Linux засіб діагностики не переписує метадані команди/точки входу, поки відповідний systemd-модуль Gateway активний. Він також ігнорує неактивні незастарілі додаткові модулі, схожі на Gateway, під час сканування дублікатів служб, щоб допоміжні файли служб не створювали зайвого шуму очищення. - - Якщо автентифікація за токеном вимагає токен і `gateway.auth.token` керується SecretRef, встановлення/виправлення служби засобом діагностики перевіряє SecretRef, але не зберігає розв’язані значення токена у відкритому тексті в метаданих середовища служби супервізора. - - Засіб діагностики виявляє керовані значення середовища служби на основі `.env`/SecretRef, які старіші встановлення LaunchAgent, systemd або Windows Scheduled Task вбудовували inline, і переписує метадані служби так, щоб ці значення завантажувалися з джерела виконання, а не з визначення супервізора. - - Засіб діагностики виявляє, коли команда служби все ще закріплює старий `--port` після зміни `gateway.port`, і переписує метадані служби на поточний порт. - - Якщо автентифікація за токеном вимагає токен, а налаштований SecretRef токена не розв’язано, засіб діагностики блокує шлях встановлення/виправлення з дієвими порадами. - - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, засіб діагностики блокує встановлення/виправлення, доки режим не буде задано явно. - - Для користувацьких systemd-модулів Linux засіб діагностики тепер перевіряє дрейф токена, враховуючи джерела як `Environment=`, так і `EnvironmentFile=` під час порівняння метаданих автентифікації служби. - - Виправлення служб засобом діагностики відмовляються переписувати, зупиняти або перезапускати службу Gateway зі старішого бінарного файла OpenClaw, коли конфігурацію востаннє записала новіша версія. Див. [усунення несправностей Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard). - - Ви завжди можете примусово виконати повне переписування через `openclaw gateway install --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-джерела замість визначення супервізора. + - 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). + - Ви завжди можете примусово виконати повний перезапис через `openclaw gateway install --force`. - - Засіб діагностики перевіряє середовище виконання служби (PID, останній статус виходу) і попереджає, коли службу встановлено, але вона фактично не працює. Він також перевіряє конфлікти портів на порту Gateway (типово `18789`) і повідомляє ймовірні причини (Gateway уже запущено, SSH-тунель). + + Doctor перевіряє runtime служби (PID, останній статус виходу) і попереджає, коли службу встановлено, але вона фактично не працює. Він також перевіряє конфлікти портів на порту Gateway (типово `18789`) і повідомляє ймовірні причини (Gateway уже запущено, SSH-тунель). - - Засіб діагностики попереджає, коли служба Gateway працює на Bun або шляху Node, керованому версіями (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram вимагають Node, а шляхи менеджера версій можуть ламатися після оновлень, бо служба не завантажує ініціалізацію вашої оболонки. Засіб діагностики пропонує перейти на системне встановлення Node, коли воно доступне (Homebrew/apt/choco). + + Doctor попереджає, коли служба Gateway працює на Bun або шляху Node, керованому менеджером версій (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram вимагають Node, а шляхи менеджера версій можуть ламатися після оновлень, бо служба не завантажує ініціалізацію вашої оболонки. Doctor пропонує мігрувати на системне встановлення Node, коли воно доступне (Homebrew/apt/choco). - Нововстановлені або виправлені 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`) і стабільні user-bin каталоги, але припущені резервні каталоги менеджерів версій записуються до PATH служби лише тоді, коли ці каталоги існують на диску. + Нововстановлені або відремонтовані 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 служби лише тоді, коли ці каталоги існують на диску. - Засіб діагностики зберігає всі зміни конфігурації й ставить позначку в метаданих майстра, щоб зафіксувати запуск засобу діагностики. + 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) diff --git a/docs/uk/plugins/bundles.md b/docs/uk/plugins/bundles.md index 14fcfae5c..d12014077 100644 --- a/docs/uk/plugins/bundles.md +++ b/docs/uk/plugins/bundles.md @@ -1,26 +1,26 @@ --- read_when: - Ви хочете встановити пакет, сумісний із Codex, Claude або Cursor - - Вам потрібно зрозуміти, як OpenClaw зіставляє вміст пакета з нативними можливостями - - Ви налагоджуєте виявлення бандла або відсутні можливості -summary: Встановлення та використання пакетів Codex, Claude і Cursor як плагінів OpenClaw + - Потрібно зрозуміти, як OpenClaw відображає вміст бандла в нативні функції + - Ви налагоджуєте виявлення бандла або усуваєте проблему відсутніх можливостей +summary: Установлення та використання наборів Codex, Claude і Cursor як плагінів OpenClaw title: Пакети Plugin x-i18n: - generated_at: "2026-05-01T20:39:39Z" + generated_at: "2026-05-05T01:21:29Z" model: gpt-5.5 provider: openai - source_hash: 4b949ad70881714a30ab136261441687b439e39b516638ffa052efeab6b75bd4 + source_hash: 5bc06300e765e2faaf51800462003e242d29d4102ac9feaa47f86d4ad35bf157 source_path: plugins/bundles.md workflow: 16 --- OpenClaw може встановлювати плагіни з трьох зовнішніх екосистем: **Codex**, **Claude** -і **Cursor**. Вони називаються **пакетами** — наборами вмісту та метаданих, які -OpenClaw відображає на нативні функції, як-от Skills, хуки та MCP-інструменти. +і **Cursor**. Вони називаються **пакетами** — наборами вмісту й метаданих, які +OpenClaw відображає на нативні функції, як-от навички, хуки та MCP-інструменти. - Пакети — це **не** те саме, що нативні плагіни OpenClaw. Нативні плагіни працюють - у процесі й можуть реєструвати будь-яку можливість. Пакети — це набори вмісту з + Пакети — це **не** те саме, що нативні плагіни OpenClaw. Нативні плагіни + працюють у процесі та можуть реєструвати будь-які можливості. Пакети — це набори вмісту з вибірковим відображенням функцій і вужчою межею довіри. @@ -29,13 +29,13 @@ OpenClaw відображає на нативні функції, як-от Skil Багато корисних плагінів публікуються у форматі Codex, Claude або Cursor. Замість того щоб вимагати від авторів переписувати їх як нативні плагіни OpenClaw, OpenClaw виявляє ці формати й відображає їхній підтримуваний вміст на нативний набір -функцій. Це означає, що ви можете встановити пакет команд Claude або пакет Skills -Codex і одразу використовувати його. +функцій. Це означає, що ви можете встановити набір команд Claude або пакет навичок Codex +і одразу ним користуватися. -## Встановлення пакета +## Установлення пакета - + ```bash # Local directory openclaw plugins install ./my-bundle @@ -56,7 +56,7 @@ Codex і одразу використовувати його. openclaw plugins inspect ``` - Пакети відображаються як `Format: bundle` із підтипом `codex`, `claude` або `cursor`. + Пакети показуються як `Format: bundle` із підтипом `codex`, `claude` або `cursor`. @@ -65,60 +65,60 @@ Codex і одразу використовувати його. openclaw gateway restart ``` - Відображені функції (Skills, хуки, MCP-інструменти, стандартні налаштування LSP) доступні в наступному сеансі. + Відображені функції (навички, хуки, MCP-інструменти, типові параметри LSP) доступні в наступному сеансі. ## Що OpenClaw відображає з пакетів -Сьогодні не кожна функція пакета запускається в OpenClaw. Ось що працює та що -виявляється, але ще не підключене. +Не кожна функція пакета наразі працює в OpenClaw. Ось що працює, а що +виявляється, але ще не підключено. ### Підтримується зараз -| Функція | Як вона відображається | Застосовується до | -| ------------- | ------------------------------------------------------------------------------------------- | -------------- | -| Вміст Skills | Кореневі каталоги Skills пакета завантажуються як звичайні Skills OpenClaw | Усі формати | -| Команди | `commands/` і `.cursor/commands/` обробляються як кореневі каталоги Skills | Claude, Cursor | -| Пакети хуків | OpenClaw-стиль макетів `HOOK.md` + `handler.ts` | Codex | -| MCP-інструменти | MCP-конфігурація пакета об’єднується з вбудованими налаштуваннями Pi; підтримувані stdio та HTTP-сервери завантажуються | Усі формати | -| LSP-сервери | Claude `.lsp.json` і оголошені в маніфесті `lspServers` об’єднуються зі стандартними налаштуваннями LSP вбудованого Pi | Claude | -| Налаштування | Claude `settings.json` імпортується як стандартні налаштування вбудованого Pi | Claude | +| Функція | Як вона відображається | Застосовується до | +| ------------- | ------------------------------------------------------------------------------------------- | ----------------- | +| Вміст навичок | Корені навичок пакета завантажуються як звичайні навички OpenClaw | Усі формати | +| Команди | `commands/` і `.cursor/commands/` обробляються як корені навичок | Claude, Cursor | +| Набори хуків | Макети у стилі OpenClaw з `HOOK.md` + `handler.ts` | Codex | +| MCP-інструменти | MCP-конфігурація пакета об’єднується з вбудованими налаштуваннями Pi; підтримувані сервери stdio та HTTP завантажуються | Усі формати | +| LSP-сервери | Claude `.lsp.json` і оголошені в маніфесті `lspServers` об’єднуються з типовими параметрами LSP вбудованого Pi | Claude | +| Налаштування | Claude `settings.json` імпортується як типові параметри вбудованого Pi | Claude | -#### Вміст Skills +#### Вміст навичок -- кореневі каталоги Skills пакета завантажуються як звичайні корені Skills OpenClaw -- корені Claude `commands` обробляються як додаткові корені Skills -- корені Cursor `.cursor/commands` обробляються як додаткові корені Skills +- корені навичок пакета завантажуються як звичайні корені навичок OpenClaw +- корені Claude `commands` обробляються як додаткові корені навичок +- корені Cursor `.cursor/commands` обробляються як додаткові корені навичок Це означає, що markdown-файли команд Claude працюють через звичайний завантажувач -Skills OpenClaw. Markdown-команди Cursor працюють через той самий шлях. +навичок OpenClaw. Markdown команд Cursor працює через той самий шлях. -#### Пакети хуків +#### Набори хуків -- корені хуків пакета працюють **лише** тоді, коли вони використовують звичайний - макет пакета хуків OpenClaw. Сьогодні це насамперед сумісний із Codex випадок: +- корені хуків пакета працюють **лише** тоді, коли використовують звичайний для OpenClaw + макет набору хуків. Наразі це переважно випадок, сумісний із Codex: - `HOOK.md` - `handler.ts` або `handler.js` #### MCP для Pi - увімкнені пакети можуть додавати конфігурацію MCP-сервера -- OpenClaw об’єднує MCP-конфігурацію пакета з ефективними вбудованими налаштуваннями Pi як +- OpenClaw об’єднує MCP-конфігурацію пакета з ефективними налаштуваннями вбудованого Pi як `mcpServers` -- OpenClaw надає підтримувані MCP-інструменти пакета під час ходів вбудованого агента Pi, - запускаючи stdio-сервери або підключаючись до HTTP-серверів -- профілі інструментів `coding` і `messaging` за замовчуванням включають MCP-інструменти пакета; - використовуйте `tools.deny: ["bundle-mcp"]`, щоб вимкнути їх для агента або Gateway -- локальні налаштування Pi проєкту все одно застосовуються після стандартних налаштувань пакета, тому налаштування +- OpenClaw надає підтримувані MCP-інструменти пакета під час ходів агента вбудованого Pi, + запускаючи сервери stdio або підключаючись до HTTP-серверів +- профілі інструментів `coding` і `messaging` типово включають MCP-інструменти пакета; + використовуйте `tools.deny: ["bundle-mcp"]`, щоб відмовитися від них для агента або Gateway +- локальні для проєкту налаштування Pi все ще застосовуються після типових параметрів пакета, тому налаштування робочого простору можуть перевизначати записи MCP пакета за потреби -- каталоги MCP-інструментів пакета детерміновано сортуються перед реєстрацією, тому - зміни порядку upstream `listTools()` не порушують блоки інструментів prompt-cache +- каталоги MCP-інструментів пакета сортуються детерміновано перед реєстрацією, тому + зміни порядку `listTools()` вище за стеком не спричиняють нестабільності блоків інструментів у prompt-cache ##### Транспорти -MCP-сервери можуть використовувати stdio або HTTP-транспорт: +MCP-сервери можуть використовувати транспорт stdio або HTTP: **Stdio** запускає дочірній процес: @@ -136,7 +136,7 @@ MCP-сервери можуть використовувати stdio або HTTP } ``` -**HTTP** підключається до запущеного MCP-сервера через `sse` за замовчуванням або через `streamable-http`, коли це запитано: +**HTTP** типово підключається до запущеного MCP-сервера через `sse` або через `streamable-http`, якщо це запитано: ```json { @@ -155,36 +155,36 @@ MCP-сервери можуть використовувати stdio або HTTP } ``` -- `transport` можна встановити як `"streamable-http"` або `"sse"`; якщо його пропущено, OpenClaw використовує `sse` -- `type: "http"` — це downstream-форма, нативна для CLI; використовуйте `transport: "streamable-http"` у конфігурації OpenClaw. `openclaw mcp set` і `openclaw doctor --fix` нормалізують поширений псевдонім. -- дозволені лише URL-схеми `http:` і `https:` +- `transport` можна встановити в `"streamable-http"` або `"sse"`; якщо його пропущено, OpenClaw використовує `sse` +- `type: "http"` — це CLI-нативна форма нижче за стеком; використовуйте `transport: "streamable-http"` у конфігурації OpenClaw. `openclaw mcp set` і `openclaw doctor --fix` нормалізують поширений псевдонім. +- дозволені лише схеми URL `http:` і `https:` - значення `headers` підтримують інтерполяцію `${ENV_VAR}` -- запис сервера з одночасно `command` і `url` відхиляється -- облікові дані URL (userinfo та параметри запиту) редагуються в описах інструментів - і журналах -- `connectionTimeoutMs` перевизначає стандартний 30-секундний тайм-аут підключення для - stdio та HTTP-транспортів +- запис сервера з одночасно заданими `command` і `url` відхиляється +- облікові дані URL (userinfo та параметри запиту) редагуються з описів + інструментів і журналів +- `connectionTimeoutMs` перевизначає типове 30-секундне очікування підключення для + транспортів stdio і HTTP -##### Іменування інструментів +##### Назви інструментів -OpenClaw реєструє MCP-інструменти пакета з безпечними для провайдера іменами у формі +OpenClaw реєструє MCP-інструменти пакета з безпечними для провайдера назвами у формі `serverName__toolName`. Наприклад, сервер із ключем `"vigil-harbor"`, який надає інструмент `memory_search`, реєструється як `vigil-harbor__memory_search`. - символи поза `A-Za-z0-9_-` замінюються на `-` - префікси серверів обмежені 30 символами -- повні імена інструментів обмежені 64 символами -- порожні імена серверів замінюються на `mcp` -- конфліктні санітизовані імена розрізняються числовими суфіксами -- фінальний порядок відкритих інструментів детермінований за безпечним іменем, щоб повторні ходи Pi +- повні назви інструментів обмежені 64 символами +- порожні назви серверів повертаються до `mcp` +- конфліктні санітизовані назви розрізняються числовими суфіксами +- остаточний порядок відкритих інструментів детермінований за безпечною назвою, щоб повторні ходи Pi залишалися стабільними для кешу -- фільтрація профілю розглядає всі інструменти з одного MCP-сервера пакета як такі, що належать плагіну - `bundle-mcp`, тому allowlist і deny list профілю можуть включати або - окремі відкриті імена інструментів, або ключ плагіна `bundle-mcp` +- фільтрація профілю обробляє всі інструменти з одного MCP-сервера пакета як належні плагіну + `bundle-mcp`, тому списки дозволів і заборон профілю можуть включати або + окремі відкриті назви інструментів, або ключ плагіна `bundle-mcp` #### Налаштування вбудованого Pi -- Claude `settings.json` імпортується як стандартні налаштування вбудованого Pi, коли +- Claude `settings.json` імпортується як типові налаштування вбудованого Pi, коли пакет увімкнено - OpenClaw санітизує ключі перевизначення оболонки перед їх застосуванням @@ -197,17 +197,17 @@ OpenClaw реєструє MCP-інструменти пакета з безпе - увімкнені пакети Claude можуть додавати конфігурацію LSP-сервера - OpenClaw завантажує `.lsp.json` плюс будь-які оголошені в маніфесті шляхи `lspServers` -- LSP-конфігурація пакета об’єднується з ефективними стандартними налаштуваннями LSP вбудованого Pi -- сьогодні можна запускати лише підтримувані LSP-сервери на основі stdio; непідтримувані - транспорти все одно відображаються в `openclaw plugins inspect ` +- LSP-конфігурація пакета об’єднується з ефективними типовими параметрами LSP вбудованого Pi +- наразі запускатися можуть лише підтримувані LSP-сервери на базі stdio; непідтримувані + транспорти все одно показуються в `openclaw plugins inspect ` ### Виявляється, але не виконується -Вони розпізнаються та відображаються в діагностиці, але OpenClaw їх не запускає: +Вони розпізнаються й показуються в діагностиці, але OpenClaw їх не запускає: - Claude `agents`, автоматизація `hooks.json`, `outputStyles` - Cursor `.cursor/agents`, `.cursor/hooks.json`, `.cursor/rules` -- Вбудовані метадані Codex/app поза звітуванням про можливості +- вбудовані/прикладні метадані Codex поза звітуванням про можливості ## Формати пакетів @@ -217,8 +217,8 @@ OpenClaw реєструє MCP-інструменти пакета з безпе Необов’язковий вміст: `skills/`, `hooks/`, `.mcp.json`, `.app.json` - Пакети Codex найкраще підходять OpenClaw, коли вони використовують корені Skills і каталоги - пакетів хуків у стилі OpenClaw (`HOOK.md` + `handler.ts`). + Пакети Codex найкраще пасують OpenClaw, коли використовують корені навичок і каталоги + наборів хуків у стилі OpenClaw (`HOOK.md` + `handler.ts`). @@ -226,16 +226,16 @@ OpenClaw реєструє MCP-інструменти пакета з безпе Два режими виявлення: - **На основі маніфесту:** `.claude-plugin/plugin.json` - - **Без маніфесту:** стандартний макет Claude (`skills/`, `commands/`, `agents/`, `hooks/`, `.mcp.json`, `.lsp.json`, `settings.json`) + - **Без маніфесту:** типовий макет Claude (`skills/`, `commands/`, `agents/`, `hooks/`, `.mcp.json`, `.lsp.json`, `settings.json`) Поведінка, специфічна для Claude: - - `commands/` обробляється як вміст Skills + - `commands/` обробляється як вміст навичок - `settings.json` імпортується в налаштування вбудованого Pi (ключі перевизначення оболонки санітизуються) - - `.mcp.json` надає підтримувані stdio-інструменти вбудованому Pi - - `.lsp.json` плюс оголошені в маніфесті шляхи `lspServers` завантажуються у стандартні налаштування LSP вбудованого Pi + - `.mcp.json` відкриває підтримувані stdio-інструменти для вбудованого Pi + - `.lsp.json` плюс оголошені в маніфесті шляхи `lspServers` завантажуються в типові параметри LSP вбудованого Pi - `hooks/hooks.json` виявляється, але не виконується - - користувацькі шляхи компонентів у маніфесті є додатковими (вони розширюють стандартні, а не замінюють їх) + - користувацькі шляхи компонентів у маніфесті є додатковими (вони розширюють типові значення, а не замінюють їх) @@ -244,8 +244,8 @@ OpenClaw реєструє MCP-інструменти пакета з безпе Необов’язковий вміст: `skills/`, `.cursor/commands/`, `.cursor/agents/`, `.cursor/rules/`, `.cursor/hooks.json`, `.mcp.json` - - `.cursor/commands/` обробляється як вміст Skills - - `.cursor/rules/`, `.cursor/agents/` і `.cursor/hooks.json` призначені лише для виявлення + - `.cursor/commands/` обробляється як вміст навичок + - `.cursor/rules/`, `.cursor/agents/` і `.cursor/hooks.json` лише виявляються @@ -255,41 +255,41 @@ OpenClaw реєструє MCP-інструменти пакета з безпе OpenClaw спочатку перевіряє нативний формат плагіна: 1. `openclaw.plugin.json` або дійсний `package.json` з `openclaw.extensions` — обробляється як **нативний плагін** -2. Маркери пакетів (`.codex-plugin/`, `.claude-plugin/` або стандартний макет Claude/Cursor) — обробляються як **пакет** +2. Маркери пакета (`.codex-plugin/`, `.claude-plugin/` або типовий макет Claude/Cursor) — обробляється як **пакет** Якщо каталог містить обидва варіанти, OpenClaw використовує нативний шлях. Це запобігає -частковому встановленню пакетів із двома форматами як пакетів. +частковому встановленню двоформатних пакетів як пакетів. -## Залежності середовища виконання та очищення +## Runtime-залежності та очищення -- Сумісні сторонні пакети не отримують startup-ремонт `npm install`. Їх - слід встановлювати через `openclaw plugins install`, і вони мають постачати все, - що їм потрібно, у встановленому каталозі плагіна. -- Пакети плагінів, що належать OpenClaw, або постачаються легкими в core, або - завантажуються через інсталятор плагінів. Запуск Gateway ніколи не запускає для них - менеджер пакетів. +- Сторонні сумісні пакети не отримують startup-ремонту через `npm install`. Їх + слід встановлювати через `openclaw plugins install` і постачати все потрібне + в установленому каталозі плагіна. +- Пакетні плагіни, що належать OpenClaw, або постачаються легкими в core, або + доступні для завантаження через інсталятор плагінів. Запуск Gateway ніколи не запускає + для них менеджер пакетів. - `openclaw doctor --fix` видаляє застарілі staged-каталоги залежностей і може - встановлювати налаштовані завантажувані плагіни, яких немає в локальному - індексі плагінів. + відновлювати завантажувані плагіни, яких бракує в локальному індексі плагінів, коли + конфігурація посилається на них. ## Безпека Пакети мають вужчу межу довіри, ніж нативні плагіни: -- OpenClaw **не** завантажує довільні модулі середовища виконання пакета в процес -- Шляхи Skills і пакетів хуків мають залишатися всередині кореня плагіна (з перевіркою меж) -- Файли налаштувань читаються з тими самими перевірками меж -- Підтримувані stdio MCP-сервери можуть запускатися як підпроцеси +- OpenClaw **не** завантажує довільні runtime-модулі пакета в процес +- шляхи Skills і наборів хуків мають залишатися всередині кореня плагіна (з перевіркою меж) +- файли налаштувань читаються з такими самими перевірками меж +- підтримувані MCP-сервери stdio можуть запускатися як subprocesses -Це робить пакети безпечнішими за замовчуванням, але все одно слід вважати сторонні -пакети довіреним вмістом для функцій, які вони надають. +Це робить пакети безпечнішими за замовчуванням, але сторонні +пакети все одно слід вважати довіреним вмістом для функцій, які вони відкривають. -## Усунення неполадок +## Усунення несправностей - Виконайте `openclaw plugins inspect `. Якщо можливість зазначена, але позначена як - непідключена, це обмеження продукту, а не пошкоджене встановлення. + Запустіть `openclaw plugins inspect `. Якщо можливість перелічена, але позначена як + не підключена, це обмеження продукту, а не несправне встановлення. @@ -299,17 +299,17 @@ OpenClaw спочатку перевіряє нативний формат пл Підтримуються лише налаштування вбудованого Pi з `settings.json`. OpenClaw не - розглядає налаштування пакета як сирі патчі конфігурації. + обробляє налаштування пакета як сирі патчі конфігурації. - `hooks/hooks.json` призначений лише для виявлення. Якщо вам потрібні виконувані хуки, використовуйте - макет пакета хуків OpenClaw або постачайте нативний плагін. + `hooks/hooks.json` лише виявляється. Якщо вам потрібні виконувані хуки, використовуйте + макет набору хуків OpenClaw або постачайте нативний плагін. ## Пов’язане -- [Встановлення та налаштування плагінів](/uk/tools/plugin) +- [Установлення та налаштування плагінів](/uk/tools/plugin) - [Створення плагінів](/uk/plugins/building-plugins) — створення нативного плагіна -- [Маніфест Plugin](/uk/plugins/manifest) — схема нативного маніфесту +- [Маніфест плагіна](/uk/plugins/manifest) — схема нативного маніфесту diff --git a/docs/uk/plugins/dependency-resolution.md b/docs/uk/plugins/dependency-resolution.md index c11ed9278..c3eba3337 100644 --- a/docs/uk/plugins/dependency-resolution.md +++ b/docs/uk/plugins/dependency-resolution.md @@ -1,51 +1,51 @@ --- read_when: - - Ви налагоджуєте встановлення пакетів plugin - - Ви змінюєте поведінку запуску Plugin, doctor або встановлення через менеджер пакетів - - Ви супроводжуєте пакетовані інсталяції OpenClaw або вбудовані маніфести Plugin + - Ви налагоджуєте встановлення Plugin-пакетів + - Ви змінюєте поведінку запуску Plugin, `doctor` або встановлення через менеджер пакетів + - Ви підтримуєте пакетні встановлення OpenClaw або маніфести вбудованих Plugin sidebarTitle: Dependencies summary: Як OpenClaw встановлює пакети Plugin і розв’язує залежності Plugin title: Розв’язання залежностей Plugin x-i18n: - generated_at: "2026-05-03T20:54:39Z" + generated_at: "2026-05-05T01:21:32Z" model: gpt-5.5 provider: openai - source_hash: 46af62ff866d50cb53bb2761d9928f0fd2a25bdb945040885ec6bfb85be35c6d + source_hash: 1a832f705e51bba8ac77e2a8715a7213fd2caf10bfa42059d53db4a6d5ad8c20 source_path: plugins/dependency-resolution.md workflow: 16 --- -# Розв’язання залежностей Plugin +# Вирішення залежностей Plugin -OpenClaw виконує роботу із залежностями Plugin під час установлення/оновлення. Завантаження під час виконання -не запускає менеджери пакетів, не відновлює дерева залежностей і не змінює -каталог пакета OpenClaw. +OpenClaw виконує роботу із залежностями Plugin під час встановлення/оновлення. Завантаження під час виконання +не запускає менеджери пакетів, не відновлює дерева залежностей і не змінює каталог +пакета OpenClaw. ## Розподіл відповідальності -Пакети Plugin володіють своїм графом залежностей: +Пакети Plugin відповідають за власний граф залежностей: -- залежності часу виконання розміщуються в `dependencies` або +- залежності часу виконання містяться в `dependencies` або `optionalDependencies` пакета Plugin - імпорти SDK/ядра є peer-імпортами або імпортами, наданими OpenClaw -- локальні Plugin для розробки приносять власні вже встановлені залежності -- npm- і git-Plugin установлюються в корені пакетів, що належать OpenClaw +- локальні плагіни для розробки постачаються з уже встановленими власними залежностями +- npm- і git-плагіни встановлюються в корені пакетів, якими керує OpenClaw -OpenClaw володіє лише життєвим циклом Plugin: +OpenClaw відповідає лише за життєвий цикл Plugin: - виявити джерело Plugin -- установити або оновити пакет, коли це явно запитано +- встановити або оновити пакет за явним запитом - записати метадані встановлення - завантажити точку входу Plugin -- завершитися помилкою з дієвою підказкою, коли залежності відсутні +- завершити з дієвою помилкою, коли залежності відсутні ## Корені встановлення OpenClaw використовує стабільні корені для кожного джерела: -- npm-пакети встановлюються в `~/.openclaw/npm` -- git-пакети клонуються в `~/.openclaw/git` -- локальні/шляхові/архівні встановлення копіюються або посилаються без відновлення залежностей +- пакети npm встановлюються в `~/.openclaw/npm` +- пакети git клонуються в `~/.openclaw/git` +- локальні/path/archive-встановлення копіюються або посилаються без відновлення залежностей npm-встановлення виконуються в корені npm за допомогою: @@ -53,10 +53,10 @@ npm-встановлення виконуються в корені npm за д npm install --prefix ~/.openclaw/npm --omit=dev --ignore-scripts --no-audit --no-fund ``` -npm може піднімати транзитивні залежності до `~/.openclaw/npm/node_modules` поруч із -пакетом Plugin. OpenClaw сканує керований корінь npm перед довірою до -встановлення й використовує npm для видалення керованих npm пакетів під час деінсталяції, тож підняті -залежності часу виконання залишаються всередині керованої межі очищення. +npm може підіймати транзитивні залежності в `~/.openclaw/npm/node_modules` поряд +із пакетом Plugin. OpenClaw сканує керований корінь npm перед тим, як довіряти +встановленню, і використовує npm для видалення керованих npm пакетів під час деінсталяції, тож підняті +залежності часу виконання залишаються в межах керованого очищення. git-встановлення клонують або оновлюють репозиторій, а потім виконують: @@ -64,18 +64,18 @@ git-встановлення клонують або оновлюють репо npm install --omit=dev --ignore-scripts --no-audit --no-fund ``` -Установлений Plugin потім завантажується з каталогу цього пакета, тож розв’язання -пакетно-локальних і батьківських `node_modules` працює так само, як для звичайного +Після цього встановлений Plugin завантажується з каталогу цього пакета, тож розв’язання +пакетних локальних і батьківських `node_modules` працює так само, як для звичайного пакета Node. -## Локальні Plugin +## Локальні плагіни -Локальні Plugin розглядаються як каталоги, контрольовані розробником. OpenClaw не -запускає для них `npm install`, `pnpm install` або відновлення залежностей. Якщо локальний +Локальні плагіни розглядаються як каталоги, контрольовані розробником. OpenClaw не +виконує для них `npm install`, `pnpm install` або відновлення залежностей. Якщо локальний Plugin має залежності, установіть їх у цьому Plugin перед його завантаженням. -Сторонні локальні Plugin на TypeScript можуть використовувати аварійний шлях Jiti. Пакетовані -JavaScript Plugin і вбудовані внутрішні Plugin завантажуються через нативний +Сторонні локальні плагіни TypeScript можуть використовувати аварійний шлях Jiti. Пакетовані +плагіни JavaScript і вбудовані внутрішні плагіни завантажуються через нативний import/require замість Jiti. ## Запуск і перезавантаження @@ -84,7 +84,7 @@ import/require замість Jiti. записи встановлення Plugin, обчислюють точку входу й завантажують її. Якщо залежність відсутня під час виконання, Plugin не завантажується, а помилка -має спрямувати оператора до явного виправлення: +має вказати оператору на явне виправлення: ```bash openclaw plugins update @@ -92,44 +92,45 @@ openclaw plugins install openclaw doctor --fix ``` -`doctor --fix` може очищати застарілий стан залежностей, згенерований OpenClaw, і встановлювати -налаштовані завантажувані Plugin, які відсутні в локальних записах встановлення. -Він не відновлює залежності для вже встановленого локального Plugin. +`doctor --fix` може очистити застарілий стан залежностей, згенерований OpenClaw, і відновити +завантажувані плагіни, яких немає в локальних записах встановлення, коли конфігурація +посилається на них. Doctor не відновлює залежності для вже встановленого +локального Plugin. -## Вбудовані Plugin +## Вбудовані плагіни -Легкі та критично важливі для ядра вбудовані Plugin постачаються як частина OpenClaw. +Легкі й критично важливі для ядра вбудовані плагіни постачаються як частина OpenClaw. Вони або не повинні мати важкого дерева залежностей часу виконання, або мають бути винесені в завантажуваний пакет на ClawHub/npm. -Поточний згенерований список Plugin, які постачаються в пакеті ядра, встановлюються -зовнішньо або залишаються лише у вихідному коді, див. в [інвентарі Plugin](/uk/plugins/plugin-inventory). +Поточний згенерований список плагінів, які постачаються в пакеті ядра, встановлюються +зовні або залишаються лише вихідним кодом, див. у [Інвентарі Plugin](/uk/plugins/plugin-inventory). Маніфести вбудованих Plugin не повинні запитувати підготовку залежностей. Велика або необов’язкова функціональність Plugin має пакуватися як звичайний Plugin і встановлюватися через -той самий шлях npm/git/ClawHub, що й сторонні Plugin. +той самий шлях npm/git/ClawHub, що й сторонні плагіни. У checkout вихідного коду OpenClaw розглядає репозиторій як pnpm-монорепозиторій. Після -`pnpm install` вбудовані Plugin завантажуються з `extensions/`, тож пакетно-локальні -залежності робочого простору доступні, а зміни підхоплюються напряму. Розробка в -checkout вихідного коду підтримується лише з pnpm; звичайний `npm install` у корені репозиторію -не є підтримуваним способом підготовки залежностей вбудованих Plugin. +`pnpm install` вбудовані плагіни завантажуються з `extensions/`, тому пакетні локальні +workspace-залежності доступні, а зміни підхоплюються напряму. Розробка в checkout вихідного коду +підтримується лише з pnpm; звичайний `npm install` у корені репозиторію не є +підтримуваним способом підготувати залежності вбудованих Plugin. -| Форма встановлення | Розташування вбудованого Plugin | Власник залежностей | +| Форма встановлення | Розташування вбудованого Plugin | Власник залежностей | | -------------------------------- | ------------------------------------- | -------------------------------------------------------------------- | -| `npm install -g openclaw` | Побудоване дерево часу виконання всередині пакета | Пакет OpenClaw і явні потоки встановлення/оновлення/doctor для Plugin | -| Git checkout плюс `pnpm install` | Пакети робочого простору `extensions/` | Робочий простір pnpm, включно з власними залежностями кожного пакета Plugin | +| `npm install -g openclaw` | Зібране дерево часу виконання всередині пакета | Пакет OpenClaw і явні потоки встановлення/оновлення/doctor для Plugin | +| Git checkout плюс `pnpm install` | Workspace-пакети `extensions/` | pnpm workspace, включно з власними залежностями кожного пакета Plugin | | `openclaw plugins install ...` | Керований корінь Plugin npm/git/ClawHub | Потік встановлення/оновлення Plugin | ## Очищення застарілого стану Старіші версії OpenClaw генерували корені залежностей вбудованих Plugin під час запуску або -під час відновлення через doctor. Поточне очищення doctor видаляє ці застарілі каталоги й -символьні посилання, коли використовується `--fix`, включно зі старими коренями `plugin-runtime-deps`, глобальними -символьними посиланнями пакетів із префіксом Node, які вказують на обрізані цілі `plugin-runtime-deps`, -маніфестами `.openclaw-runtime-deps*`, згенерованими `node_modules` Plugin, каталогами -етапу встановлення та пакетно-локальними сховищами pnpm. Пакетований postinstall також -видаляє ці глобальні символьні посилання перед обрізанням застарілих цільових коренів, щоб оновлення -не залишали висячі імпорти пакетів ESM. +під час відновлення doctor. Поточне очищення doctor видаляє ці застарілі каталоги та +символічні посилання, коли використовується `--fix`, включно зі старими коренями `plugin-runtime-deps`, глобальними +символічними посиланнями пакетів із префіксом Node, які вказують на обрізані цілі `plugin-runtime-deps`, +маніфестами `.openclaw-runtime-deps*`, згенерованими Plugin `node_modules`, каталогами +етапу встановлення та пакетними локальними сховищами pnpm. Пакетований postinstall також +видаляє ці глобальні символічні посилання перед обрізанням застарілих цільових коренів, щоб оновлення +не залишали завислих імпортів пакетів ESM. Ці шляхи є лише застарілими залишками. Нові встановлення не повинні їх створювати. diff --git a/docs/uk/tools/loop-detection.md b/docs/uk/tools/loop-detection.md index 5c215b6e2..b42f4b294 100644 --- a/docs/uk/tools/loop-detection.md +++ b/docs/uk/tools/loop-detection.md @@ -3,26 +3,26 @@ read_when: - Користувач повідомляє, що агенти застрягають, повторюючи виклики інструментів - Потрібно налаштувати захист від повторюваних викликів - Ви редагуєте політики інструментів/середовища виконання агента -summary: Як увімкнути й налаштувати захисні механізми, які виявляють повторювані цикли викликів інструментів +summary: Як увімкнути та налаштувати захисні механізми, які виявляють повторювані цикли викликів інструментів title: Виявлення зациклення інструментів x-i18n: - generated_at: "2026-05-03T17:33:12Z" + generated_at: "2026-05-05T01:21:22Z" model: gpt-5.5 provider: openai - source_hash: 1b3976948d5735cf08b7ce854bab048a77a778a07a9f3f66d17c15aed0d42a97 + source_hash: b9221e1716d3f4c2814a4705b160253839510cd6d11fe4ccd598c67958851afb source_path: tools/loop-detection.md workflow: 16 --- OpenClaw може запобігати застряганню агентів у повторюваних шаблонах викликів інструментів. -Захист **вимкнено за замовчуванням**. +Цей захист **вимкнено за замовчуванням**. -Увімкніть його лише там, де це потрібно, оскільки за суворих налаштувань він може блокувати легітимні повторні виклики. +Умикайте його лише там, де потрібно, оскільки за строгих налаштувань він може блокувати легітимні повторні виклики. ## Навіщо це потрібно - Виявляти повторювані послідовності, які не дають прогресу. -- Виявляти високочастотні цикли без результатів (той самий інструмент, ті самі вхідні дані, повторювані помилки). +- Виявляти високочастотні цикли без результату (той самий інструмент, ті самі вхідні дані, повторювані помилки). - Виявляти конкретні шаблони повторних викликів для відомих інструментів опитування. ## Блок конфігурації @@ -71,44 +71,67 @@ OpenClaw може запобігати застряганню агентів у ### Поведінка полів -- `enabled`: Головний перемикач. `false` означає, що виявлення циклів не виконується. -- `historySize`: кількість нещодавніх викликів інструментів, які зберігаються для аналізу. +- `enabled`: головний перемикач. `false` означає, що виявлення циклів не виконується. +- `historySize`: кількість останніх викликів інструментів, які зберігаються для аналізу. - `warningThreshold`: поріг перед класифікацією шаблону як лише попереджувального. - `criticalThreshold`: поріг для блокування повторюваних циклічних шаблонів. -- `globalCircuitBreakerThreshold`: глобальний поріг переривника для випадків без прогресу. +- `globalCircuitBreakerThreshold`: глобальний поріг переривача для відсутності прогресу. - `detectors.genericRepeat`: виявляє повторювані шаблони з тим самим інструментом і тими самими параметрами. -- `detectors.knownPollNoProgress`: виявляє відомі шаблони, подібні до опитування, без зміни стану. +- `detectors.knownPollNoProgress`: виявляє відомі шаблони, схожі на опитування, без зміни стану. - `detectors.pingPong`: виявляє почергові шаблони ping-pong. -Для `exec` перевірки відсутності прогресу порівнюють стабільні результати команд і ігнорують мінливі метадані виконання, як-от тривалість, PID, ідентифікатор сеансу та робочий каталог. -Коли доступний ідентифікатор запуску, історія нещодавніх викликів інструментів оцінюється лише в межах цього запуску, тож заплановані цикли Heartbeat і нові запуски не успадковують застарілі лічильники циклів із попередніх запусків. +Для `exec` перевірки відсутності прогресу порівнюють стабільні результати команд і ігнорують мінливі метадані виконання, як-от тривалість, PID, ідентифікатор сесії та робочий каталог. +Коли доступний ідентифікатор запуску, історія останніх викликів інструментів оцінюється лише в межах цього запуску, щоб заплановані цикли Heartbeat і нові запуски не успадковували застарілі лічильники циклів із попередніх запусків. ## Рекомендоване налаштування -- Для менших моделей почніть з `enabled: true`, не змінюючи значення за замовчуванням. Флагманські моделі рідко потребують виявлення циклів і можуть залишати його вимкненим. -- Тримайте пороги впорядкованими як `warningThreshold < criticalThreshold < globalCircuitBreakerThreshold`. -- Якщо виникають хибні спрацьовування: +- Для менших моделей починайте з `enabled: true`, не змінюючи значень за замовчуванням. Флагманським моделям виявлення циклів потрібно рідко, і його можна залишити вимкненим. +- Дотримуйтеся порядку порогів `warningThreshold < criticalThreshold < globalCircuitBreakerThreshold`. +- Якщо виникають хибні спрацювання: - підвищте `warningThreshold` та/або `criticalThreshold` - (необов’язково) підвищте `globalCircuitBreakerThreshold` - вимкніть лише той детектор, який спричиняє проблеми - - зменште `historySize` для менш суворого історичного контексту + - зменште `historySize` для менш строгого історичного контексту + +## Захист після Compaction + +Коли runner завершує автоматичну повторну спробу після Compaction (після переповнення контексту), він вмикає коротковіконний захист, який відстежує кілька наступних викликів інструментів. Якщо агент кілька разів у межах цього вікна видає той _самий_ трійник `(toolName, args, result)`, захист робить висновок, що Compaction не розірвала цикл, і перериває запуск із помилкою `compaction_loop_persisted`. + +Це окремий шлях коду від глобальних детекторів `tools.loopDetection`. Він налаштовується незалежно: + +```json5 +{ + tools: { + loopDetection: { + enabled: true, // existing master switch; set false to disable loop guards + postCompactionGuard: { + windowSize: 3, // default: 3 + }, + }, + }, +} +``` + +- `windowSize`: кількість викликів інструментів після Compaction, протягом яких захист залишається активним, _і_ кількість однакових трійників (інструмент, аргументи, результат), яка спричиняє переривання. + +Захист ніколи не перериває запуск, коли результати змінюються, а лише коли результати побайтно ідентичні в межах вікна. Він навмисно вузький: спрацьовує лише безпосередньо після повторної спроби з Compaction. ## Журнали та очікувана поведінка -Коли виявлено цикл, OpenClaw повідомляє про подію циклу та блокує або послаблює наступний цикл інструментів залежно від серйозності. -Це захищає користувачів від неконтрольованих витрат токенів і зависань, зберігаючи нормальний доступ до інструментів. +Коли виявлено цикл, OpenClaw повідомляє про подію циклу та блокує або пом’якшує наступний цикл інструментів залежно від серйозності. +Це захищає користувачів від неконтрольованих витрат токенів і зависань, водночас зберігаючи звичайний доступ до інструментів. -- Спочатку віддавайте перевагу попередженню та тимчасовому приглушенню. -- Підвищуйте серйозність лише тоді, коли накопичуються повторні докази. +- Спершу надавайте перевагу попередженню та тимчасовому приглушенню. +- Ескалуйте лише тоді, коли накопичуються повторні докази. ## Примітки - `tools.loopDetection` об’єднується з перевизначеннями на рівні агента. - Конфігурація для окремого агента повністю перевизначає або розширює глобальні значення. -- Якщо конфігурації немає, захисні механізми залишаються вимкненими. +- Якщо конфігурації немає, захисні обмеження залишаються вимкненими. ## Пов’язане -- [Затвердження Exec](/uk/tools/exec-approvals) +- [Схвалення Exec](/uk/tools/exec-approvals) - [Рівні мислення](/uk/tools/thinking) -- [Субагенти](/uk/tools/subagents) +- [Підагенті](/uk/tools/subagents)