From a837eca18e5ac9bf1f58cef111e859a5378cd3f6 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Thu, 23 Apr 2026 18:35:06 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/channels/discord.md | 582 ++++---- docs/uk/ci.md | 120 +- docs/uk/gateway/security/index.md | 1055 +++++++-------- docs/uk/help/faq.md | 2092 +++++++++++++++-------------- docs/uk/help/testing.md | 1065 ++++++++------- docs/uk/help/troubleshooting.md | 303 ++--- docs/uk/tools/exec-approvals.md | 538 ++++---- 7 files changed, 2870 insertions(+), 2885 deletions(-) diff --git a/docs/uk/channels/discord.md b/docs/uk/channels/discord.md index 19ecb5f61..40a59c436 100644 --- a/docs/uk/channels/discord.md +++ b/docs/uk/channels/discord.md @@ -1,69 +1,67 @@ --- read_when: - Робота над функціями каналу Discord -summary: Статус підтримки бота Discord, можливості та налаштування +summary: Статус підтримки, можливості та конфігурація бота Discord title: Discord x-i18n: - generated_at: "2026-04-23T08:25:11Z" + generated_at: "2026-04-23T18:24:15Z" model: gpt-5.4 provider: openai - source_hash: 1160a0b221bc3251722a81c00c65ee7c2001efce345248727f1f3c8580a0e953 + source_hash: 574f23a3a6388b02f92dba42a8b4fa97ca45dd52ac57e2be24c4dc5c1abf0790 source_path: channels/discord.md workflow: 15 --- -# Discord (Bot API) - -Статус: готово для приватних повідомлень і каналів гільдій через офіційний gateway Discord. +Готово до приватних повідомлень і каналів сервера через офіційний Discord gateway. - - За замовчуванням приватні повідомлення Discord працюють у режимі підключення. + + Приватні повідомлення Discord за замовчуванням працюють у режимі сполучення. - + Нативна поведінка команд і каталог команд. - Міжканальна діагностика та процес відновлення. + Діагностика між каналами та процес відновлення. ## Швидке налаштування -Вам потрібно створити новий застосунок із ботом, додати бота на свій сервер і підключити його до OpenClaw. Ми рекомендуємо додавати бота на власний приватний сервер. Якщо у вас його ще немає, [спочатку створіть його](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (оберіть **Create My Own > For me and my friends**). +Вам потрібно створити новий застосунок із ботом, додати бота на свій сервер і виконати сполучення з OpenClaw. Рекомендуємо додати бота на власний приватний сервер. Якщо у вас його ще немає, [спочатку створіть його](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (виберіть **Create My Own > For me and my friends**). - + Перейдіть до [Discord Developer Portal](https://discord.com/developers/applications) і натисніть **New Application**. Назвіть його, наприклад, "OpenClaw". - Натисніть **Bot** на бічній панелі. Установіть **Username** на назву, якою ви називаєте свого агента OpenClaw. + Натисніть **Bot** на бічній панелі. Установіть **Username** на ту назву, якою ви називаєте свого агента OpenClaw. - - Все ще на сторінці **Bot**, прокрутіть вниз до **Privileged Gateway Intents** і увімкніть: + + Усе ще на сторінці **Bot**, прокрутіть вниз до **Privileged Gateway Intents** і ввімкніть: - **Message Content Intent** (обов’язково) - - **Server Members Intent** (рекомендовано; обов’язково для списків дозволених ролей і зіставлення імен з ID) - - **Presence Intent** (необов’язково; потрібне лише для оновлень статусу присутності) + - **Server Members Intent** (рекомендовано; обов’язково для allowlist ролей і зіставлення імен з ID) + - **Presence Intent** (необов’язково; потрібен лише для оновлень статусу) - Поверніться вгору на сторінці **Bot** і натисніть **Reset Token**. + Прокрутіть угору на сторінці **Bot** і натисніть **Reset Token**. Попри назву, це генерує ваш перший токен — нічого не «скидається». - Скопіюйте токен і збережіть його десь. Це ваш **Bot Token**, і він вам скоро знадобиться. + Скопіюйте токен і збережіть його десь. Це ваш **Bot Token**, і він незабаром знадобиться. - - Натисніть **OAuth2** на бічній панелі. Ви згенеруєте URL запрошення з потрібними дозволами, щоб додати бота на свій сервер. + + Натисніть **OAuth2** на бічній панелі. Ви згенеруєте URL-запрошення з потрібними дозволами, щоб додати бота на свій сервер. - Прокрутіть вниз до **OAuth2 URL Generator** і увімкніть: + Прокрутіть вниз до **OAuth2 URL Generator** і ввімкніть: - `bot` - `applications.commands` @@ -79,31 +77,31 @@ x-i18n: - Attach Files - Add Reactions (необов’язково) - Це базовий набір для звичайних текстових каналів. Якщо ви плануєте публікувати в обговореннях Discord, зокрема у сценаріях форумних або медіаканалів, що створюють або продовжують обговорення, також увімкніть **Send Messages in Threads**. - Скопіюйте згенерований URL внизу, вставте його у браузер, виберіть свій сервер і натисніть **Continue**, щоб підключити. Тепер ви маєте побачити свого бота на Discord-сервері. + Це базовий набір для звичайних текстових каналів. Якщо ви плануєте публікувати в потоках Discord, зокрема у сценаріях форумів або медіаканалів, які створюють або продовжують потік, також увімкніть **Send Messages in Threads**. + Скопіюйте згенерований URL унизу, вставте його у браузер, виберіть свій сервер і натисніть **Continue**, щоб підключити бота. Тепер ви маєте бачити свого бота на сервері Discord. - Повернувшись у застосунок Discord, вам потрібно увімкнути Developer Mode, щоб можна було копіювати внутрішні ID. + Повернувшись у застосунок Discord, вам потрібно ввімкнути Developer Mode, щоб копіювати внутрішні ID. 1. Натисніть **User Settings** (значок шестерні поруч із вашим аватаром) → **Advanced** → увімкніть **Developer Mode** - 2. Клацніть правою кнопкою миші на **значку сервера** на бічній панелі → **Copy Server ID** - 3. Клацніть правою кнопкою миші на **власному аватарі** → **Copy User ID** + 2. Клацніть правою кнопкою миші по **значку сервера** на бічній панелі → **Copy Server ID** + 3. Клацніть правою кнопкою миші по **своєму аватару** → **Copy User ID** - Збережіть свій **Server ID** і **User ID** разом із Bot Token — на наступному кроці ви передасте всі три значення в OpenClaw. + Збережіть **Server ID** і **User ID** разом із Bot Token — надішлете всі три значення до OpenClaw на наступному кроці. - Щоб підключення працювало, Discord має дозволяти вашому боту надсилати вам приватні повідомлення. Клацніть правою кнопкою миші на **значку сервера** → **Privacy Settings** → увімкніть **Direct Messages**. + Щоб сполучення працювало, Discord має дозволяти вашому боту надсилати вам приватні повідомлення. Клацніть правою кнопкою миші по **значку сервера** → **Privacy Settings** → увімкніть **Direct Messages**. - Це дозволяє учасникам сервера (включно з ботами) надсилати вам приватні повідомлення. Залиште це увімкненим, якщо хочете використовувати приватні повідомлення Discord з OpenClaw. Якщо ви плануєте використовувати лише канали гільдії, після підключення можна вимкнути приватні повідомлення. + Це дозволяє учасникам сервера (зокрема ботам) надсилати вам приватні повідомлення. Залиште це ввімкненим, якщо хочете використовувати приватні повідомлення Discord з OpenClaw. Якщо ви плануєте використовувати лише канали сервера, після сполучення можна вимкнути приватні повідомлення. - Токен вашого Discord-бота — це секрет (як пароль). Задайте його на машині, де працює OpenClaw, перш ніж писати своєму агенту. + Токен вашого Discord-бота — це секрет (як пароль). Задайте його на машині, де запущено OpenClaw, перш ніж писати своєму агенту. ```bash export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" @@ -113,15 +111,15 @@ openclaw config set channels.discord.enabled true --strict-json openclaw gateway ``` - Якщо OpenClaw уже працює як фонова служба, перезапустіть його через застосунок OpenClaw для Mac або зупинивши й знову запустивши процес `openclaw gateway run`. + Якщо OpenClaw уже працює як фоновий сервіс, перезапустіть його через застосунок OpenClaw для Mac або зупинивши й знову запустивши процес `openclaw gateway run`. - + - - Напишіть своєму агенту OpenClaw у будь-якому наявному каналі (наприклад, Telegram) і скажіть йому це. Якщо Discord — ваш перший канал, замість цього використайте вкладку CLI / config. + + Напишіть своєму агенту OpenClaw у будь-якому наявному каналі (наприклад, Telegram) і повідомте йому це. Якщо Discord — ваш перший канал, скористайтеся вкладкою CLI / config. > "Я вже задав токен свого Discord-бота в конфігурації. Будь ласка, заверши налаштування Discord з User ID `` і Server ID ``." @@ -149,21 +147,21 @@ openclaw gateway DISCORD_BOT_TOKEN=... ``` - Підтримуються відкриті значення `token`. Також підтримуються значення SecretRef для `channels.discord.token` у провайдерах env/file/exec. Див. [Керування секретами](/uk/gateway/secrets). + Підтримуються відкриті значення `token`. Значення SecretRef також підтримуються для `channels.discord.token` у провайдерах env/file/exec. Див. [Керування секретами](/uk/gateway/secrets). - - Дочекайтеся, поки gateway запуститься, а потім надішліть приватне повідомлення своєму боту в Discord. Він відповість кодом підключення. + + Дочекайтеся, поки gateway запуститься, а потім напишіть боту в приватні повідомлення Discord. Він відповість кодом сполучення. - - Надішліть код підключення своєму агенту в наявному каналі: + + Надішліть код сполучення своєму агенту в наявному каналі: - > "Підтвердь цей код підключення Discord: ``" + > "Підтвердь цей код сполучення Discord: ``" @@ -175,7 +173,7 @@ openclaw pairing approve discord - Термін дії кодів підключення спливає через 1 годину. + Термін дії кодів сполучення спливає через 1 годину. Тепер ви маєте змогу спілкуватися зі своїм агентом у Discord через приватні повідомлення. @@ -183,23 +181,23 @@ openclaw pairing approve discord -Визначення токена враховує обліковий запис. Значення токена в конфігурації мають пріоритет над резервною змінною середовища. `DISCORD_BOT_TOKEN` використовується лише для облікового запису за замовчуванням. -Для розширених вихідних викликів (інструмент повідомлень/дії каналу) явний `token` використовується для цього виклику. Це застосовується до дій надсилання й читання/перевірки (наприклад, read/search/fetch/thread/pins/permissions). Політика облікового запису/налаштування повторних спроб усе ще беруться з вибраного облікового запису в активному знімку runtime. +Визначення токена враховує обліковий запис. Значення токена в конфігурації мають пріоритет над резервним значенням із середовища. `DISCORD_BOT_TOKEN` використовується лише для облікового запису за замовчуванням. +Для розширених вихідних викликів (дії інструмента повідомлень/каналу) явний `token` для виклику використовується саме для цього виклику. Це стосується дій надсилання та читання/перевірки (наприклад read/search/fetch/thread/pins/permissions). Політика облікового запису/налаштування повторних спроб усе ще беруться з вибраного облікового запису в активному знімку runtime. -## Рекомендовано: налаштуйте робочий простір гільдії +## Рекомендовано: налаштуйте робочий простір сервера -Щойно приватні повідомлення запрацюють, ви зможете налаштувати свій Discord-сервер як повноцінний робочий простір, де кожен канал отримує власну сесію агента з власним контекстом. Це рекомендовано для приватних серверів, де є лише ви та ваш бот. +Щойно приватні повідомлення запрацюють, ви можете налаштувати свій сервер Discord як повноцінний робочий простір, де кожен канал матиме власну сесію агента з власним контекстом. Це рекомендовано для приватних серверів, де єте лише ви та ваш бот. - + Це дозволяє вашому агенту відповідати в будь-якому каналі на вашому сервері, а не лише в приватних повідомленнях. - - > "Додай мій Discord Server ID `` до списку дозволених гільдій" + + > "Додай мій Discord Server ID `` до allowlist серверів" - + ```json5 { @@ -223,14 +221,14 @@ openclaw pairing approve discord - За замовчуванням ваш агент відповідає в каналах гільдії лише тоді, коли його згадано через @mention. Для приватного сервера, ймовірно, ви захочете, щоб він відповідав на кожне повідомлення. + За замовчуванням ваш агент відповідає в каналах сервера лише тоді, коли його згадано через @mention. Для приватного сервера ви, ймовірно, захочете, щоб він відповідав на кожне повідомлення. - - > "Дозволь моєму агенту відповідати на цьому сервері без @mention" + + > "Дозволь моєму агенту відповідати на цьому сервері без обов’язкового @mention" - - Задайте `requireMention: false` у конфігурації гільдії: + + Задайте `requireMention: false` у конфігурації сервера: ```json5 { @@ -251,58 +249,58 @@ openclaw pairing approve discord - - За замовчуванням довготривала пам’ять (`MEMORY.md`) завантажується лише в сесіях приватних повідомлень. У каналах гільдії `MEMORY.md` автоматично не завантажується. + + За замовчуванням довготривала пам’ять (`MEMORY.md`) завантажується лише в сесіях приватних повідомлень. У каналах сервера `MEMORY.md` не завантажується автоматично. - + > "Коли я ставлю запитання в каналах Discord, використовуй memory_search або memory_get, якщо тобі потрібен довготривалий контекст із MEMORY.md." - Якщо вам потрібен спільний контекст у кожному каналі, розмістіть стабільні інструкції в `AGENTS.md` або `USER.md` (вони впроваджуються для кожної сесії). Довготривалі нотатки зберігайте в `MEMORY.md` і звертайтеся до них за потреби через інструменти пам’яті. + Якщо вам потрібен спільний контекст у кожному каналі, помістіть сталі інструкції в `AGENTS.md` або `USER.md` (вони інʼєктуються в кожну сесію). Довготривалі нотатки зберігайте в `MEMORY.md` і звертайтеся до них за потреби за допомогою інструментів пам’яті. -Тепер створіть кілька каналів на своєму Discord-сервері й почніть спілкування. Ваш агент може бачити назву каналу, і кожен канал отримує власну ізольовану сесію — тож ви можете налаштувати `#coding`, `#home`, `#research` або будь-що, що відповідає вашому робочому процесу. +Тепер створіть кілька каналів на своєму сервері Discord і починайте спілкування. Ваш агент може бачити назву каналу, а кожен канал отримує власну ізольовану сесію — тож ви можете налаштувати `#coding`, `#home`, `#research` або будь-що інше, що відповідає вашому робочому процесу. ## Модель runtime -- Gateway керує з’єднанням Discord. -- Маршрутизація відповідей детермінована: вхідні повідомлення Discord повертаються в Discord. -- За замовчуванням (`session.dmScope=main`) прямі чати використовують спільну основну сесію агента (`agent:main:main`). -- Канали гільдії мають ізольовані ключі сесій (`agent::discord:channel:`). +- Gateway керує підключенням до Discord. +- Маршрутизація відповідей детермінована: вхідні повідомлення з Discord отримують відповіді назад у Discord. +- За замовчуванням (`session.dmScope=main`) прямі чати використовують основну сесію агента (`agent:main:main`). +- Канали сервера мають ізольовані ключі сесій (`agent::discord:channel:`). - Групові приватні повідомлення за замовчуванням ігноруються (`channels.discord.dm.groupEnabled=false`). -- Нативні slash-команди виконуються в ізольованих командних сесіях (`agent::discord:slash:`), водночас зберігаючи `CommandTargetSessionKey` для маршрутизованої сесії розмови. +- Нативні слеш-команди працюють в ізольованих сесіях команд (`agent::discord:slash:`), водночас передаючи `CommandTargetSessionKey` до маршрутизованої сесії розмови. -## Форумні канали +## Канали-форуми -Форумні та медіаканали Discord приймають лише публікації в обговореннях. OpenClaw підтримує два способи їх створення: +Форуми та медіаканали Discord приймають лише публікації в потоках. OpenClaw підтримує два способи їх створення: -- Надішліть повідомлення батьківському форуму (`channel:`), щоб автоматично створити обговорення. Заголовок обговорення використовує перший непорожній рядок вашого повідомлення. -- Використайте `openclaw message thread create`, щоб створити обговорення напряму. Не передавайте `--message-id` для форумних каналів. +- Надішліть повідомлення до батьківського форуму (`channel:`), щоб автоматично створити потік. Заголовок потоку використовує перший непорожній рядок вашого повідомлення. +- Використайте `openclaw message thread create`, щоб створити потік безпосередньо. Не передавайте `--message-id` для каналів-форумів. -Приклад: надсилання в батьківський форум для створення обговорення +Приклад: надсилання до батьківського форуму для створення потоку ```bash openclaw message send --channel discord --target channel: \ --message "Topic title\nBody of the post" ``` -Приклад: явне створення форумного обговорення +Приклад: явне створення потоку форуму ```bash openclaw message thread create --channel discord --target channel: \ --thread-name "Topic title" --message "Body of the post" ``` -Батьківські форуми не приймають компоненти Discord. Якщо вам потрібні компоненти, надсилайте в саме обговорення (`channel:`). +Батьківські форуми не приймають компоненти Discord. Якщо вам потрібні компоненти, надсилайте повідомлення до самого потоку (`channel:`). ## Інтерактивні компоненти -OpenClaw підтримує контейнери компонентів Discord v2 для повідомлень агента. Використовуйте інструмент повідомлень із корисним навантаженням `components`. Результати взаємодії маршрутизуються назад до агента як звичайні вхідні повідомлення й дотримуються наявних налаштувань Discord `replyToMode`. +OpenClaw підтримує контейнери компонентів Discord v2 для повідомлень агента. Використовуйте інструмент повідомлень із payload `components`. Результати взаємодії маршрутизуються назад до агента як звичайні вхідні повідомлення й дотримуються наявних налаштувань Discord `replyToMode`. Підтримувані блоки: @@ -310,21 +308,21 @@ OpenClaw підтримує контейнери компонентів Discord - Рядки дій дозволяють до 5 кнопок або одне меню вибору - Типи вибору: `string`, `user`, `role`, `mentionable`, `channel` -За замовчуванням компоненти одноразові. Установіть `components.reusable=true`, щоб дозволити багаторазове використання кнопок, списків вибору та форм, доки не спливе їхній термін дії. +За замовчуванням компоненти одноразові. Установіть `components.reusable=true`, щоб дозволити багаторазове використання кнопок, списків вибору й форм, доки не сплине їхній термін дії. -Щоб обмежити, хто може натискати кнопку, установіть `allowedUsers` для цієї кнопки (ID користувачів Discord, теги або `*`). Якщо налаштовано, користувачі, які не збігаються, отримають ефемерну відмову. +Щоб обмежити, хто може натискати кнопку, задайте `allowedUsers` для цієї кнопки (ID користувачів Discord, теги або `*`). Якщо налаштовано, користувачі, які не відповідають умовам, отримають ефемерну відмову. -Slash-команди `/model` і `/models` відкривають інтерактивний вибір моделі з випадними списками провайдера й моделі та кроком Submit. Якщо не задано `commands.modelsWrite=false`, `/models add` також підтримує додавання нового запису провайдера/моделі з чату, а нові додані моделі з’являються без перезапуску gateway. Відповідь вибору є ефемерною, і використовувати її може лише користувач, який викликав команду. +Слеш-команди `/model` і `/models` відкривають інтерактивний вибір моделі зі списками провайдерів і моделей та кроком Submit. Якщо не задано `commands.modelsWrite=false`, `/models add` також підтримує додавання нового запису провайдера/моделі з чату, а новододані моделі з’являються без перезапуску gateway. Відповідь засобу вибору є ефемерною, і лише користувач, який викликав команду, може нею користуватися. Вкладення файлів: -- Блоки `file` мають вказувати на посилання вкладення (`attachment://`) +- блоки `file` мають вказувати на посилання вкладення (`attachment://`) - Надайте вкладення через `media`/`path`/`filePath` (один файл); використовуйте `media-gallery` для кількох файлів - Використовуйте `filename`, щоб перевизначити ім’я завантаження, коли воно має збігатися з посиланням вкладення Модальні форми: -- Додайте `components.modal` із до 5 полями +- Додайте `components.modal` із максимум 5 полями - Типи полів: `text`, `checkbox`, `radio`, `select`, `role-select`, `user-select` - OpenClaw автоматично додає кнопку запуску @@ -385,48 +383,48 @@ Slash-команди `/model` і `/models` відкривають інтерак ## Керування доступом і маршрутизація - - `channels.discord.dmPolicy` керує доступом до приватних повідомлень (застаріле: `channels.discord.dm.policy`): + + `channels.discord.dmPolicy` керує доступом до DM (застаріле: `channels.discord.dm.policy`): - `pairing` (за замовчуванням) - `allowlist` - `open` (потрібно, щоб `channels.discord.allowFrom` містив `"*"`; застаріле: `channels.discord.dm.allowFrom`) - `disabled` - Якщо політика приватних повідомлень не відкрита, невідомі користувачі блокуються (або отримують запит на підключення в режимі `pairing`). + Якщо політика DM не є open, невідомі користувачі блокуються (або отримують запит на сполучення в режимі `pairing`). - Пріоритет для кількох облікових записів: + Пріоритетність для кількох облікових записів: - `channels.discord.accounts.default.allowFrom` застосовується лише до облікового запису `default`. - Іменовані облікові записи успадковують `channels.discord.allowFrom`, якщо їхній власний `allowFrom` не задано. - Іменовані облікові записи не успадковують `channels.discord.accounts.default.allowFrom`. - Формат цілі приватного повідомлення для доставки: + Формат цілі DM для доставки: - `user:` - згадка `<@id>` - Числові ID без префікса є неоднозначними та відхиляються, якщо явно не вказано тип цілі користувача/каналу. + Числові ID без уточнення неоднозначні та відхиляються, якщо явно не вказано тип цілі user/channel. - - Обробка гільдій керується через `channels.discord.groupPolicy`: + + Обробка серверів керується через `channels.discord.groupPolicy`: - `open` - `allowlist` - `disabled` - Безпечна базова поведінка, коли існує `channels.discord`, — `allowlist`. + Безпечне базове значення, коли існує `channels.discord`, — `allowlist`. Поведінка `allowlist`: - - гільдія має збігатися з `channels.discord.guilds` (переважно `id`, також приймається slug) - - необов’язкові списки дозволених відправників: `users` (рекомендовано стабільні ID) і `roles` (лише ID ролей); якщо налаштовано будь-який із них, відправники дозволяються, коли вони збігаються з `users` АБО `roles` - - пряме зіставлення за іменем/тегом за замовчуванням вимкнене; увімкніть `channels.discord.dangerouslyAllowNameMatching: true` лише як аварійний режим сумісності + - сервер має збігатися з `channels.discord.guilds` (перевага за `id`, також приймається slug) + - необов’язкові allowlist відправників: `users` (рекомендовано стабільні ID) і `roles` (лише ID ролей); якщо налаштовано будь-яке з них, відправники дозволяються, коли збігаються з `users` АБО `roles` + - пряме зіставлення за ім’ям/тегом за замовчуванням вимкнене; вмикайте `channels.discord.dangerouslyAllowNameMatching: true` лише як аварійний режим сумісності - імена/теги підтримуються для `users`, але ID безпечніші; `openclaw security audit` попереджає, коли використовуються записи з іменами/тегами - - якщо для гільдії налаштовано `channels`, канали, яких немає в списку, забороняються - - якщо для гільдії немає блоку `channels`, дозволяються всі канали в цій гільдії зі списку дозволених + - якщо для сервера налаштовано `channels`, канали поза списком відхиляються + - якщо в сервера немає блоку `channels`, дозволяються всі канали в цьому сервері з allowlist Приклад: @@ -452,33 +450,33 @@ Slash-команди `/model` і `/models` відкривають інтерак } ``` - Якщо ви лише задали `DISCORD_BOT_TOKEN` і не створили блок `channels.discord`, резервна поведінка runtime — `groupPolicy="allowlist"` (із попередженням у логах), навіть якщо `channels.defaults.groupPolicy` має значення `open`. + Якщо ви лише задасте `DISCORD_BOT_TOKEN` і не створите блок `channels.discord`, резервна поведінка runtime буде `groupPolicy="allowlist"` (із попередженням у логах), навіть якщо `channels.defaults.groupPolicy` має значення `open`. - - Повідомлення в гільдіях за замовчуванням вимагають згадки. + + Повідомлення на серверах за замовчуванням вимагають згадки. - Виявлення згадки включає: + Визначення згадок включає: - явну згадку бота - налаштовані шаблони згадок (`agents.list[].groupChat.mentionPatterns`, резервно `messages.groupChat.mentionPatterns`) - - неявну поведінку відповіді боту в підтримуваних випадках + - неявну поведінку reply-to-bot у підтримуваних випадках - `requireMention` налаштовується для кожної гільдії/каналу окремо (`channels.discord.guilds...`). - `ignoreOtherMentions` за бажанням відкидає повідомлення, які згадують іншого користувача/роль, але не бота (за винятком @everyone/@here). + `requireMention` налаштовується для кожного сервера/каналу (`channels.discord.guilds...`). + `ignoreOtherMentions` за потреби відкидає повідомлення, які згадують іншого користувача/роль, але не бота (за винятком @everyone/@here). - Групові приватні повідомлення: + Групові DM: - за замовчуванням: ігноруються (`dm.groupEnabled=false`) - - необов’язковий список дозволених через `dm.groupChannels` (ID каналів або slug) + - необов’язковий allowlist через `dm.groupChannels` (ID каналів або slug) -### Маршрутизація агентів на основі ролей +### Маршрутизація агентів за ролями -Використовуйте `bindings[].match.roles`, щоб маршрутизувати учасників гільдії Discord до різних агентів за ID ролі. Прив’язки на основі ролей приймають лише ID ролей і обчислюються після прив’язок peer або parent-peer та перед прив’язками лише на рівні гільдії. Якщо прив’язка також задає інші поля зіставлення (наприклад, `peer` + `guildId` + `roles`), усі налаштовані поля мають збігатися. +Використовуйте `bindings[].match.roles`, щоб маршрутизувати учасників серверів Discord до різних агентів за ID ролі. Прив’язки на основі ролей приймають лише ID ролей і обчислюються після прив’язок peer або parent-peer та перед прив’язками лише за сервером. Якщо прив’язка також задає інші поля match (наприклад, `peer` + `guildId` + `roles`), мають збігатися всі налаштовані поля. ```json5 { @@ -502,105 +500,51 @@ Slash-команди `/model` і `/models` відкривають інтерак } ``` -## Налаштування Developer Portal - - - - - 1. Discord Developer Portal -> **Applications** -> **New Application** - 2. **Bot** -> **Add Bot** - 3. Скопіюйте токен бота - - - - - У **Bot -> Privileged Gateway Intents** увімкніть: - - - Message Content Intent - - Server Members Intent (рекомендовано) - - Presence intent є необов’язковим і потрібен лише якщо ви хочете отримувати оновлення присутності. Налаштування присутності бота (`setPresence`) не потребує ввімкнення оновлень присутності для учасників. - - - - - Генератор OAuth URL: - - - scopes: `bot`, `applications.commands` - - Типові базові дозволи: - - **General Permissions** - - View Channels - **Text Permissions** - - Send Messages - - Read Message History - - Embed Links - - Attach Files - - Add Reactions (необов’язково) - - Це базовий набір для звичайних текстових каналів. Якщо ви плануєте публікувати в обговореннях Discord, зокрема у сценаріях форумних або медіаканалів, що створюють або продовжують обговорення, також увімкніть **Send Messages in Threads**. - Уникайте `Administrator`, якщо він не потрібен явно. - - - - - Увімкніть Discord Developer Mode, а потім скопіюйте: - - - ID сервера - - ID каналу - - ID користувача - - Для надійних аудитів і перевірок віддавайте перевагу числовим ID у конфігурації OpenClaw. - - - - ## Нативні команди та авторизація команд -- `commands.native` за замовчуванням має значення `"auto"` і ввімкнено для Discord. -- Перевизначення для окремого каналу: `channels.discord.commands.native`. +- `commands.native` за замовчуванням має значення `"auto"` і ввімкнене для Discord. +- Перевизначення для каналу: `channels.discord.commands.native`. - `commands.native=false` явно очищає раніше зареєстровані нативні команди Discord. -- Авторизація нативних команд використовує ті самі списки дозволених і політики Discord, що й звичайна обробка повідомлень. -- Команди все одно можуть бути видимими в інтерфейсі Discord для користувачів без авторизації; виконання все одно застосовує авторизацію OpenClaw і повертає "not authorized". +- Авторизація нативних команд використовує ті самі allowlist/політики Discord, що й звичайна обробка повідомлень. +- Команди все ще можуть бути видимі в інтерфейсі Discord для неавторизованих користувачів; під час виконання все одно застосовується авторизація OpenClaw і повертається "not authorized". -Див. [Slash-команди](/uk/tools/slash-commands) для каталогу команд і поведінки. +Див. [Слеш-команди](/uk/tools/slash-commands) для каталогу команд і поведінки. -Налаштування slash-команд за замовчуванням: +Налаштування слеш-команд за замовчуванням: - `ephemeral: true` -## Деталі можливостей +## Деталі функцій - - Discord підтримує теги відповідей у виводі агента: + + Discord підтримує теги відповіді у виводі агента: - `[[reply_to_current]]` - `[[reply_to:]]` - Це керується через `channels.discord.replyToMode`: + Керується через `channels.discord.replyToMode`: - `off` (за замовчуванням) - `first` - `all` - `batched` - Примітка: `off` вимикає неявне вкладення відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються. - `first` завжди додає неявне посилання нативної відповіді до першого вихідного повідомлення Discord за цей хід. + Примітка: `off` вимикає неявне об’єднання відповідей у тред. Явні теги `[[reply_to_*]]` все одно враховуються. + `first` завжди додає неявне посилання нативної відповіді до першого вихідного повідомлення Discord у цьому ході. `batched` додає неявне посилання нативної відповіді Discord лише тоді, коли - вхідний хід був відкладеним пакетом із кількох повідомлень. Це корисно, - коли вам потрібні нативні відповіді переважно для неоднозначних чатів із - серією повідомлень, а не для кожного окремого повідомлення. + вхідний хід був дебаунсованим пакетом із кількох повідомлень. Це корисно, + коли ви хочете нативні відповіді переважно для неоднозначних серій швидких чатів, а не для кожного + окремого ходу з одним повідомленням. - ID повідомлень відображаються в контексті/історії, щоб агенти могли націлюватися на конкретні повідомлення. + ID повідомлень передаються в контексті/історії, щоб агенти могли націлюватися на конкретні повідомлення. - - OpenClaw може передавати чернетки відповідей потоком, надсилаючи тимчасове повідомлення та редагуючи його в міру надходження тексту. `channels.discord.streaming` приймає `off` (за замовчуванням) | `partial` | `block` | `progress`. `progress` у Discord відповідає `partial`; `streamMode` є застарілим псевдонімом і автоматично мігрується. + + OpenClaw може потоково передавати чернетки відповідей, надсилаючи тимчасове повідомлення та редагуючи його в міру надходження тексту. `channels.discord.streaming` приймає `off` (за замовчуванням) | `partial` | `block` | `progress`. `progress` у Discord зіставляється з `partial`; `streamMode` — це застарілий псевдонім, який автоматично мігрується. - Значенням за замовчуванням лишається `off`, оскільки редагування попереднього перегляду в Discord швидко впирається в обмеження частоти, коли кілька ботів або gateway спільно використовують один обліковий запис. + Значення за замовчуванням залишається `off`, оскільки редагування попереднього перегляду в Discord швидко впирається в обмеження частоти, коли кілька ботів або gateway спільно використовують один обліковий запис. ```json5 { @@ -618,47 +562,47 @@ Slash-команди `/model` і `/models` відкривають інтерак ``` - `partial` редагує одне повідомлення попереднього перегляду в міру надходження токенів. - - `block` виводить фрагменти розміру чернетки (використовуйте `draftChunk` для налаштування розміру й точок розриву, обмежених `textChunkLimit`). - - Фінальні повідомлення з медіа, помилками та явними відповідями скасовують незавершені редагування попереднього перегляду. - - `streaming.preview.toolProgress` (за замовчуванням `true`) керує тим, чи повторно використовують оновлення інструментів/прогресу повідомлення попереднього перегляду. + - `block` виводить фрагменти розміру чернетки (використовуйте `draftChunk`, щоб налаштувати розмір і точки розриву, обмежені до `textChunkLimit`). + - Фінальні повідомлення з медіа, помилками та явними відповідями скасовують відкладені редагування попереднього перегляду. + - `streaming.preview.toolProgress` (за замовчуванням `true`) керує тим, чи перевикористовують оновлення інструментів/прогресу повідомлення попереднього перегляду. - Потоковий попередній перегляд підтримує лише текст; відповіді з медіа повертаються до звичайної доставки. Коли `block` streaming явно ввімкнено, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового виводу. + Потоковий попередній перегляд підтримує лише текст; відповіді з медіа повертаються до звичайної доставки. Коли потоковий режим `block` явно ввімкнений, OpenClaw пропускає попередній потік, щоб уникнути подвійного стримінгу. - - Контекст історії гільдії: + + Контекст історії сервера: - `channels.discord.historyLimit` за замовчуванням `20` - - резервно: `messages.groupChat.historyLimit` + - резервне значення: `messages.groupChat.historyLimit` - `0` вимикає - Керування історією приватних повідомлень: + Керування історією DM: - `channels.discord.dmHistoryLimit` - `channels.discord.dms[""].historyLimit` - Поведінка обговорень: + Поведінка тредів: - - Обговорення Discord маршрутизуються як сесії каналів і успадковують конфігурацію батьківського каналу, якщо не перевизначено. - - `channels.discord.thread.inheritParent` (за замовчуванням `false`) вмикає для нових автообговорень початкове заповнення з батьківського транскрипту. Перевизначення для окремих облікових записів розміщуються в `channels.discord.accounts..thread.inheritParent`. - - Реакції інструмента повідомлень можуть визначати цілі приватних повідомлень `user:`. - - `guilds..channels..requireMention: false` зберігається під час резервної активації на етапі відповіді. + - Треди Discord маршрутизуються як сесії каналів і успадковують конфігурацію батьківського каналу, якщо не перевизначено інше. + - `channels.discord.thread.inheritParent` (за замовчуванням `false`) вмикає для нових автоматичних тредів початкове заповнення з батьківського транскрипту. Перевизначення для облікового запису розміщуються в `channels.discord.accounts..thread.inheritParent`. + - Реакції інструмента повідомлень можуть визначати цілі DM виду `user:`. + - `guilds..channels..requireMention: false` зберігається під час резервного ввімкнення на етапі відповіді. - Теми каналів упроваджуються як **ненадійний** контекст. Списки дозволених обмежують, хто може запускати агента, але не є повною межею редагування додаткового контексту. + Теми каналів інʼєктуються як **недовірений** контекст. Allowlist визначають, хто може запускати агента, але це не повна межа редагування додаткового контексту. - - Discord може прив’язати обговорення до цілі сесії, щоб подальші повідомлення в цьому обговоренні продовжували маршрутизуватися до тієї самої сесії (включно із сесіями субагентів). + + Discord може прив’язати тред до цілі сесії, щоб подальші повідомлення в цьому треді й надалі маршрутизувалися до тієї самої сесії (зокрема сесій субагентів). Команди: - - `/focus ` прив’язати поточне/нове обговорення до цілі субагента/сесії - - `/unfocus` видалити поточну прив’язку обговорення - - `/agents` показати активні запуски й стан прив’язки - - `/session idle ` переглянути/оновити автоматичне скасування фокуса через неактивність для сфокусованих прив’язок - - `/session max-age ` переглянути/оновити жорсткий максимальний вік для сфокусованих прив’язок + - `/focus ` — прив’язати поточний/новий тред до цілі субагента/сесії + - `/unfocus` — прибрати поточну прив’язку треду + - `/agents` — показати активні запуски та стан прив’язки + - `/session idle ` — переглянути/оновити авто-unfocus через неактивність для прив’язаних тредів + - `/session max-age ` — переглянути/оновити жорсткий максимальний вік для прив’язаних тредів Конфігурація: @@ -677,7 +621,7 @@ Slash-команди `/model` і `/models` відкривають інтерак enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // opt-in + spawnSubagentSessions: false, // увімкнення за потреби }, }, }, @@ -688,16 +632,16 @@ Slash-команди `/model` і `/models` відкривають інтерак - `session.threadBindings.*` задає глобальні значення за замовчуванням. - `channels.discord.threadBindings.*` перевизначає поведінку Discord. - - `spawnSubagentSessions` має бути `true`, щоб автоматично створювати/прив’язувати обговорення для `sessions_spawn({ thread: true })`. - - `spawnAcpSessions` має бути `true`, щоб автоматично створювати/прив’язувати обговорення для ACP (`/acp spawn ... --thread ...` або `sessions_spawn({ runtime: "acp", thread: true })`). - - Якщо прив’язки обговорень вимкнено для облікового запису, `/focus` та пов’язані операції прив’язки обговорень недоступні. + - `spawnSubagentSessions` має бути true, щоб автоматично створювати/прив’язувати треди для `sessions_spawn({ thread: true })`. + - `spawnAcpSessions` має бути true, щоб автоматично створювати/прив’язувати треди для ACP (`/acp spawn ... --thread ...` або `sessions_spawn({ runtime: "acp", thread: true })`). + - Якщо прив’язки тредів вимкнені для облікового запису, `/focus` і пов’язані операції з прив’язкою тредів недоступні. Див. [Субагенти](/uk/tools/subagents), [ACP Agents](/uk/tools/acp-agents) і [Довідник із конфігурації](/uk/gateway/configuration-reference). - - Для стабільних «завжди активних» робочих просторів ACP налаштуйте типізовані ACP-прив’язки верхнього рівня, націлені на розмови Discord. + + Для стабільних ACP-робочих просторів "always-on" налаштуйте типізовані ACP-прив’язки верхнього рівня, націлені на розмови Discord. Шлях конфігурації: @@ -753,35 +697,35 @@ Slash-команди `/model` і `/models` відкривають інтерак Примітки: - - `/acp spawn codex --bind here` прив’язує поточний канал або обговорення на місці й зберігає майбутні повідомлення в тій самій сесії ACP. Повідомлення в обговореннях успадковують прив’язку батьківського каналу. - - У прив’язаному каналі або обговоренні `/new` і `/reset` скидають ту саму сесію ACP на місці. Тимчасові прив’язки обговорень можуть перевизначати визначення цілі, поки вони активні. - - `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити/прив’язати дочірнє обговорення через `--thread auto|here`. + - `/acp spawn codex --bind here` прив’язує поточний канал або тред на місці й зберігає майбутні повідомлення в тій самій ACP-сесії. Повідомлення в тредах успадковують прив’язку батьківського каналу. + - У прив’язаному каналі або треді `/new` і `/reset` скидають ту саму ACP-сесію на місці. Тимчасові прив’язки тредів можуть перевизначати визначення цілі, доки вони активні. + - `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити/прив’язати дочірній тред через `--thread auto|here`. Див. [ACP Agents](/uk/tools/acp-agents) для подробиць про поведінку прив’язок. - Режим сповіщень про реакції для кожної гільдії: + Режим сповіщень про реакції для кожного сервера: - `off` - `own` (за замовчуванням) - `all` - `allowlist` (використовує `guilds..users`) - Події реакцій перетворюються на системні події та прикріплюються до маршрутизованої сесії Discord. + Події реакцій перетворюються на системні події та додаються до маршрутизованої сесії Discord. - `ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення. + `ackReaction` надсилає емодзі-підтвердження, поки OpenClaw обробляє вхідне повідомлення. Порядок визначення: - `channels.discord.accounts..ackReaction` - `channels.discord.ackReaction` - `messages.ackReaction` - - резервне емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") + - резервний варіант емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") Примітки: @@ -791,9 +735,9 @@ Slash-команди `/model` і `/models` відкривають інтерак - Записи конфігурації, ініційовані каналом, за замовчуванням увімкнені. + Записи конфігурації, ініційовані з каналу, увімкнені за замовчуванням. - Це впливає на сценарії `/config set|unset` (коли ввімкнено функції команд). + Це впливає на потоки `/config set|unset` (коли функції команд увімкнені). Вимкнення: @@ -809,8 +753,8 @@ Slash-команди `/model` і `/models` відкривають інтерак - - Маршрутизуйте трафік WebSocket gateway Discord і початкові REST-запити (ID застосунку + визначення списку дозволених) через HTTP(S)-проксі за допомогою `channels.discord.proxy`. + + Маршрутизуйте WebSocket-трафік Discord gateway і стартові REST-запити (ID застосунку + визначення allowlist) через HTTP(S)-проксі за допомогою `channels.discord.proxy`. ```json5 { @@ -849,7 +793,7 @@ Slash-команди `/model` і `/models` відкривають інтерак discord: { pluralkit: { enabled: true, - token: "pk_live_...", // optional; needed for private systems + token: "pk_live_...", // необов’язково; потрібен для приватних систем }, }, }, @@ -858,15 +802,15 @@ Slash-команди `/model` і `/models` відкривають інтерак Примітки: - - списки дозволених можуть використовувати `pk:` - - відображувані імена учасників зіставляються за назвою/slug лише коли `channels.discord.dangerouslyAllowNameMatching: true` - - пошук використовує оригінальний ID повідомлення й обмежується часовим вікном + - allowlist можуть використовувати `pk:` + - відображувані імена учасників зіставляються за іменем/slug лише коли `channels.discord.dangerouslyAllowNameMatching: true` + - пошук використовує ID початкового повідомлення й обмежується часовим вікном - якщо пошук не вдається, проксійовані повідомлення вважаються повідомленнями бота й відкидаються, якщо не задано `allowBots=true` - - Оновлення статусу присутності застосовуються, коли ви задаєте поле статусу або активності, або коли вмикаєте автоматичний статус присутності. + + Оновлення статусу застосовуються, коли ви задаєте поле статусу або активності, або коли вмикаєте автоматичний статус. Приклад лише зі статусом: @@ -893,7 +837,7 @@ Slash-команди `/model` і `/models` відкривають інтерак } ``` - Приклад трансляції: + Приклад стримінгу: ```json5 { @@ -916,7 +860,7 @@ Slash-команди `/model` і `/models` відкривають інтерак - 4: Custom (використовує текст активності як стан статусу; емодзі необов’язкове) - 5: Competing - Приклад автоматичного статусу присутності (сигнал стану runtime): + Приклад автоматичного статусу (сигнал стану runtime): ```json5 { @@ -933,7 +877,7 @@ Slash-команди `/model` і `/models` відкривають інтерак } ``` - Автоматичний статус присутності зіставляє доступність runtime зі статусом Discord: healthy => online, degraded або unknown => idle, exhausted або unavailable => dnd. Необов’язкові перевизначення тексту: + Автоматичний статус зіставляє доступність runtime зі статусом Discord: healthy => online, degraded або unknown => idle, exhausted або unavailable => dnd. Необов’язкові перевизначення тексту: - `autoPresence.healthyText` - `autoPresence.degradedText` @@ -941,26 +885,26 @@ Slash-команди `/model` і `/models` відкривають інтерак - - Discord підтримує обробку погоджень за допомогою кнопок у приватних повідомленнях і може за потреби публікувати запити на погодження в каналі, де вони виникли. + + Discord підтримує обробку підтверджень через кнопки в DM і за потреби може публікувати запити на підтвердження у вихідному каналі. Шлях конфігурації: - `channels.discord.execApprovals.enabled` - - `channels.discord.execApprovals.approvers` (необов’язково; за можливості використовується резервно `commands.ownerAllowFrom`) + - `channels.discord.execApprovals.approvers` (необов’язково; де можливо, використовується резервне значення з `commands.ownerAllowFrom`) - `channels.discord.execApprovals.target` (`dm` | `channel` | `both`, за замовчуванням: `dm`) - `agentFilter`, `sessionFilter`, `cleanupAfterResolve` - Discord автоматично вмикає нативні exec-погодження, коли `enabled` не задано або має значення `"auto"` і можна визначити принаймні одного погоджувача — або з `execApprovals.approvers`, або з `commands.ownerAllowFrom`. Discord не визначає exec-погоджувачів із `allowFrom` каналу, застарілого `dm.allowFrom` або `defaultTo` для прямих повідомлень. Задайте `enabled: false`, щоб явно вимкнути Discord як нативний клієнт погодження. + Discord автоматично вмикає нативні підтвердження exec, коли `enabled` не задано або має значення `"auto"` і можна визначити принаймні одного затверджувача — або з `execApprovals.approvers`, або з `commands.ownerAllowFrom`. Discord не визначає затверджувачів exec із `allowFrom` каналу, застарілого `dm.allowFrom` чи `defaultTo` для прямих повідомлень. Установіть `enabled: false`, щоб явно вимкнути Discord як нативний клієнт підтверджень. - Коли `target` має значення `channel` або `both`, запит на погодження видимий у каналі. Лише визначені погоджувачі можуть використовувати кнопки; інші користувачі отримують ефемерну відмову. Запити на погодження містять текст команди, тому вмикайте доставку в канал лише в довірених каналах. Якщо ID каналу неможливо визначити з ключа сесії, OpenClaw повертається до доставки через приватні повідомлення. + Коли `target` має значення `channel` або `both`, запит на підтвердження видно в каналі. Лише визначені затверджувачі можуть користуватися кнопками; інші користувачі отримують ефемерну відмову. Запити на підтвердження містять текст команди, тож увімкнення доставки в канал слід використовувати лише в довірених каналах. Якщо ID каналу неможливо вивести з ключа сесії, OpenClaw повертається до доставки через DM. - Discord також відображає спільні кнопки погодження, які використовуються іншими чат-каналами. Нативний адаптер Discord головним чином додає маршрутизацію приватних повідомлень погоджувачам і розсилання в канал. - Коли ці кнопки присутні, вони є основним UX погодження; OpenClaw - має включати ручну команду `/approve` лише тоді, коли результат інструмента вказує, - що погодження через чат недоступні або ручне погодження — єдиний шлях. + Discord також відображає спільні кнопки підтвердження, які використовуються іншими чат-каналами. Нативний адаптер Discord переважно додає маршрутизацію DM для затверджувачів і fanout до каналу. + Коли ці кнопки присутні, вони є основним UX для підтвердження; OpenClaw + має включати ручну команду `/approve` лише тоді, коли результат інструмента каже, + що підтвердження через чат недоступні або ручне підтвердження — єдиний шлях. - Авторизація gateway і визначення погоджень дотримуються спільного клієнтського контракту Gateway (`plugin:` ID визначаються через `plugin.approval.resolve`; інші ID — через `exec.approval.resolve`). Термін дії погоджень за замовчуванням спливає через 30 хвилин. + Авторизація gateway і визначення підтвердження дотримуються спільного контракту клієнта Gateway (`plugin:` ID визначаються через `plugin.approval.resolve`; інші ID — через `exec.approval.resolve`). За замовчуванням термін дії підтверджень спливає через 30 хвилин. Див. [Exec approvals](/uk/tools/exec-approvals). @@ -969,31 +913,31 @@ Slash-команди `/model` і `/models` відкривають інтерак ## Інструменти та обмеження дій -Дії повідомлень Discord включають обмін повідомленнями, адміністрування каналів, модерацію, статус присутності та дії з метаданими. +Дії повідомлень Discord включають обмін повідомленнями, адміністрування каналів, модерацію, статус і дії з метаданими. Основні приклади: -- повідомлення: `sendMessage`, `readMessages`, `editMessage`, `deleteMessage`, `threadReply` +- обмін повідомленнями: `sendMessage`, `readMessages`, `editMessage`, `deleteMessage`, `threadReply` - реакції: `react`, `reactions`, `emojiList` - модерація: `timeout`, `kick`, `ban` -- статус присутності: `setPresence` +- статус: `setPresence` -Дія `event-create` приймає необов’язковий параметр `image` (URL або локальний шлях до файлу), щоб задати зображення обкладинки запланованої події. +Дія `event-create` приймає необов’язковий параметр `image` (URL або шлях до локального файла), щоб задати зображення обкладинки запланованої події. -Обмеження дій розміщені в `channels.discord.actions.*`. +Обмеження дій розміщуються в `channels.discord.actions.*`. Поведінка обмежень за замовчуванням: -| Група дій | За замовчуванням | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | -| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | увімкнено | -| roles | вимкнено | -| moderation | вимкнено | -| presence | вимкнено | +| Група дій | Типово | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | +| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | увімкнено | +| roles | вимкнено | +| moderation | вимкнено | +| presence | вимкнено | -## UI components v2 +## UI компонентів v2 -OpenClaw використовує Discord components v2 для exec-погоджень і міжконтекстних маркерів. Дії повідомлень Discord також можуть приймати `components` для користувацького UI (розширений сценарій; потребує побудови корисного навантаження компонентів через інструмент discord), тоді як застарілі `embeds` усе ще доступні, але не рекомендовані. +OpenClaw використовує Discord components v2 для exec-підтверджень і маркерів між контекстами. Дії повідомлень Discord також можуть приймати `components` для користувацького UI (розширено; потребує побудови payload компонента через інструмент discord), тоді як застарілі `embeds` залишаються доступними, але не рекомендовані. - `channels.discord.ui.components.accentColor` задає акцентний колір, який використовується контейнерами компонентів Discord (hex). - Задається для окремого облікового запису через `channels.discord.accounts..ui.components.accentColor`. @@ -1017,17 +961,17 @@ OpenClaw використовує Discord components v2 для exec-погодж ## Голос -У Discord є дві окремі голосові поверхні: realtime **voice channels** (безперервні розмови) і **voice message attachments** (формат попереднього перегляду хвильової форми). gateway підтримує обидві. +Discord має дві окремі голосові поверхні: **голосові канали** реального часу (безперервні розмови) і **вкладення голосових повідомлень** (формат попереднього перегляду хвильової форми). Gateway підтримує обидві. -### Voice channels +### Голосові канали Вимоги: - Увімкніть нативні команди (`commands.native` або `channels.discord.commands.native`). - Налаштуйте `channels.discord.voice`. -- Бот має мати дозволи Connect + Speak у цільовому голосовому каналі. +- Бот повинен мати дозволи Connect + Speak у цільовому голосовому каналі. -Використовуйте `/vc join|leave|status` для керування сесіями. Команда використовує агента за замовчуванням для облікового запису й дотримується тих самих правил списку дозволених і групової політики, що й інші команди Discord. +Використовуйте `/vc join|leave|status` для керування сесіями. Команда використовує агента облікового запису за замовчуванням і дотримується тих самих правил allowlist і group policy, що й інші команди Discord. Приклад автоматичного приєднання: @@ -1058,19 +1002,19 @@ OpenClaw використовує Discord components v2 для exec-погодж Примітки: - `voice.tts` перевизначає `messages.tts` лише для голосового відтворення. -- Ходи голосових транскриптів визначають статус власника з `allowFrom` Discord (або `dm.allowFrom`); мовці, які не є власниками, не можуть отримувати доступ до інструментів лише для власника (наприклад, `gateway` і `cron`). -- Голос увімкнено за замовчуванням; задайте `channels.discord.voice.enabled=false`, щоб вимкнути його. -- `voice.daveEncryption` і `voice.decryptionFailureTolerance` передаються в параметри приєднання `@discordjs/voice`. -- Якщо не задано, значення за замовчуванням для `@discordjs/voice` — `daveEncryption=true` і `decryptionFailureTolerance=24`. -- OpenClaw також відстежує збої розшифрування при отриманні й автоматично відновлюється, виходячи та повторно приєднуючись до голосового каналу після повторних збоїв за короткий проміжок часу. -- Якщо в логах отримання постійно з’являється `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`, це може бути помилка отримання у `@discordjs/voice`, що відстежується в [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419). +- Ходи голосового транскрипту визначають статус власника з `allowFrom` Discord (або `dm.allowFrom`); мовці, які не є власниками, не можуть використовувати інструменти лише для власника (наприклад, `gateway` і `cron`). +- Голос увімкнений за замовчуванням; установіть `channels.discord.voice.enabled=false`, щоб вимкнути його. +- `voice.daveEncryption` і `voice.decryptionFailureTolerance` напряму передаються в параметри приєднання `@discordjs/voice`. +- Значення за замовчуванням для `@discordjs/voice` — `daveEncryption=true` і `decryptionFailureTolerance=24`, якщо їх не задано. +- OpenClaw також відстежує збої розшифрування під час приймання й автоматично відновлюється, виходячи та знову приєднуючись до голосового каналу після повторних збоїв у короткому часовому вікні. +- Якщо в логах приймання постійно з’являється `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`, це може бути висхідною помилкою приймання `@discordjs/voice`, відстежуваною в [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419). ### Голосові повідомлення -Голосові повідомлення Discord показують попередній перегляд хвильової форми й потребують аудіо OGG/Opus. OpenClaw автоматично генерує хвильову форму, але на хості gateway потрібні `ffmpeg` і `ffprobe` для перевірки та конвертації. +Голосові повідомлення Discord показують попередній перегляд хвильової форми та потребують аудіо OGG/Opus. OpenClaw генерує хвильову форму автоматично, але для перевірки та конвертації на хості gateway потрібні `ffmpeg` і `ffprobe`. -- Укажіть **локальний шлях до файлу** (URL відхиляються). -- Не додавайте текстовий вміст (Discord відхиляє текст + голосове повідомлення в одному корисному навантаженні). +- Надайте **шлях до локального файла** (URL відхиляються). +- Не додавайте текстовий вміст (Discord відхиляє текст + голосове повідомлення в одному payload). - Підтримується будь-який аудіоформат; OpenClaw за потреби конвертує його в OGG/Opus. ```bash @@ -1080,19 +1024,19 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a ## Усунення проблем - + - увімкніть Message Content Intent - - увімкніть Server Members Intent, якщо ви залежите від визначення користувачів/учасників - - перезапустіть gateway після зміни intents + - увімкніть Server Members Intent, якщо ви залежите від визначення користувача/учасника + - перезапустіть gateway після зміни інтентів - + - перевірте `groupPolicy` - - перевірте список дозволених гільдій у `channels.discord.guilds` - - якщо існує мапа `channels` гільдії, дозволені лише канали зі списку + - перевірте allowlist сервера в `channels.discord.guilds` + - якщо існує мапа `channels` сервера, дозволяються лише канали зі списку - перевірте поведінку `requireMention` і шаблони згадок Корисні перевірки: @@ -1105,16 +1049,16 @@ openclaw logs --follow - + Поширені причини: - - `groupPolicy="allowlist"` без відповідного списку дозволених гільдій/каналів - - `requireMention` налаштовано не в тому місці (має бути в `channels.discord.guilds` або в записі каналу) - - відправник заблокований списком дозволених `users` для гільдії/каналу + - `groupPolicy="allowlist"` без відповідного allowlist сервера/каналу + - `requireMention` налаштовано в неправильному місці (має бути в `channels.discord.guilds` або в записі каналу) + - відправника заблоковано allowlist `users` сервера/каналу - + Типові логи: @@ -1124,16 +1068,16 @@ openclaw logs --follow Параметр бюджету listener: - - один обліковий запис: `channels.discord.eventQueue.listenerTimeout` - - кілька облікових записів: `channels.discord.accounts..eventQueue.listenerTimeout` + - для одного облікового запису: `channels.discord.eventQueue.listenerTimeout` + - для кількох облікових записів: `channels.discord.accounts..eventQueue.listenerTimeout` Параметр тайм-ауту виконання worker: - - один обліковий запис: `channels.discord.inboundWorker.runTimeoutMs` - - кілька облікових записів: `channels.discord.accounts..inboundWorker.runTimeoutMs` - - за замовчуванням: `1800000` (30 хвилин); задайте `0`, щоб вимкнути + - для одного облікового запису: `channels.discord.inboundWorker.runTimeoutMs` + - для кількох облікових записів: `channels.discord.accounts..inboundWorker.runTimeoutMs` + - за замовчуванням: `1800000` (30 хвилин); установіть `0`, щоб вимкнути - Рекомендована базова конфігурація: + Рекомендоване базове налаштування: ```json5 { @@ -1159,35 +1103,35 @@ openclaw logs --follow - - Перевірки дозволів `channels status --probe` працюють лише для числових ID каналів. + + Перевірки дозволів у `channels status --probe` працюють лише для числових ID каналів. - Якщо ви використовуєте ключі slug, зіставлення в runtime все одно може працювати, але probe не зможе повністю перевірити дозволи. + Якщо ви використовуєте ключі slug, зіставлення в runtime все одно може працювати, але probe не може повністю перевірити дозволи. - + - - приватні повідомлення вимкнено: `channels.discord.dm.enabled=false` - - політику приватних повідомлень вимкнено: `channels.discord.dmPolicy="disabled"` (застаріле: `channels.discord.dm.policy`) - - очікується підтвердження підключення в режимі `pairing` + - DM вимкнено: `channels.discord.dm.enabled=false` + - політику DM вимкнено: `channels.discord.dmPolicy="disabled"` (застаріле: `channels.discord.dm.policy`) + - очікується підтвердження сполучення в режимі `pairing` - За замовчуванням повідомлення, створені ботом, ігноруються. + За замовчуванням повідомлення, створені ботами, ігноруються. - Якщо ви задали `channels.discord.allowBots=true`, використовуйте суворі правила згадок і списків дозволених, щоб уникнути циклічної поведінки. - Віддавайте перевагу `channels.discord.allowBots="mentions"`, щоб приймати лише повідомлення ботів, які згадують бота. + Якщо ви задаєте `channels.discord.allowBots=true`, використовуйте суворі правила згадок і allowlist, щоб уникнути циклічної поведінки. + Краще використовувати `channels.discord.allowBots="mentions"`, щоб приймати лише повідомлення ботів, які згадують бота. - + - - підтримуйте актуальність OpenClaw (`openclaw update`), щоб була наявна логіка відновлення прийому голосу Discord - - підтвердьте `channels.discord.voice.daveEncryption=true` (за замовчуванням) - - починайте з `channels.discord.voice.decryptionFailureTolerance=24` (значення upstream за замовчуванням) і налаштовуйте лише за потреби - - відстежуйте логи на наявність: + - підтримуйте актуальність OpenClaw (`openclaw update`), щоб була присутня логіка відновлення приймання голосу Discord + - підтвердьте, що `channels.discord.voice.daveEncryption=true` (за замовчуванням) + - починайте з `channels.discord.voice.decryptionFailureTolerance=24` (висхідне значення за замовчуванням) і змінюйте лише за потреби + - стежте за логами: - `discord voice: DAVE decrypt failures detected` - `discord voice: repeated decrypt failures; attempting rejoin` - якщо збої тривають після автоматичного повторного приєднання, зберіть логи й порівняйте з [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) @@ -1195,41 +1139,53 @@ openclaw logs --follow -## Вказівники на довідник із конфігурації +## Довідник із конфігурації -Основний довідник: +Основний довідник: [Configuration reference - Discord](/uk/gateway/configuration-reference#discord). -- [Довідник із конфігурації - Discord](/uk/gateway/configuration-reference#discord) - -Ключові поля Discord: + - запуск/авторизація: `enabled`, `token`, `accounts.*`, `allowBots` - політика: `groupPolicy`, `dm.*`, `guilds.*`, `guilds.*.channels.*` -- команда: `commands.native`, `commands.useAccessGroups`, `configWrites`, `slashCommand.*` +- команди: `commands.native`, `commands.useAccessGroups`, `configWrites`, `slashCommand.*` - черга подій: `eventQueue.listenerTimeout` (бюджет listener), `eventQueue.maxQueueSize`, `eventQueue.maxConcurrency` -- inbound worker: `inboundWorker.runTimeoutMs` +- вхідний worker: `inboundWorker.runTimeoutMs` - відповідь/історія: `replyToMode`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - доставка: `textChunkLimit`, `chunkMode`, `maxLinesPerMessage` -- streaming: `streaming` (застарілий псевдонім: `streamMode`), `streaming.preview.toolProgress`, `draftChunk`, `blockStreaming`, `blockStreamingCoalesce` -- медіа/повторні спроби: `mediaMaxMb`, `retry` - - `mediaMaxMb` обмежує вихідні завантаження в Discord (за замовчуванням: `100MB`) +- стримінг: `streaming` (застарілий псевдонім: `streamMode`), `streaming.preview.toolProgress`, `draftChunk`, `blockStreaming`, `blockStreamingCoalesce` +- медіа/повторні спроби: `mediaMaxMb` (обмежує вихідні завантаження в Discord, за замовчуванням `100MB`), `retry` - дії: `actions.*` -- статус присутності: `activity`, `status`, `activityType`, `activityUrl` +- статус: `activity`, `status`, `activityType`, `activityUrl` - UI: `ui.components.accentColor` -- можливості: `threadBindings`, верхньорівневий `bindings[]` (`type: "acp"`), `pluralkit`, `execApprovals`, `intents`, `agentComponents`, `heartbeat`, `responsePrefix` +- функції: `threadBindings`, верхньорівневий `bindings[]` (`type: "acp"`), `pluralkit`, `execApprovals`, `intents`, `agentComponents`, `heartbeat`, `responsePrefix` -## Безпека та операції + -- Ставтеся до токенів ботів як до секретів (`DISCORD_BOT_TOKEN` є бажаним варіантом у керованих середовищах). +## Безпека та експлуатація + +- Сприймайте токени бота як секрети (у контрольованих середовищах краще використовувати `DISCORD_BOT_TOKEN`). - Надавайте Discord лише мінімально необхідні дозволи. -- Якщо стан розгортання/стан команд застарів, перезапустіть gateway і повторно перевірте через `openclaw channels status --probe`. +- Якщо стан розгортання/стану команд застарів, перезапустіть gateway і знову перевірте через `openclaw channels status --probe`. ## Пов’язане -- [Підключення](/uk/channels/pairing) -- [Групи](/uk/channels/groups) -- [Маршрутизація каналів](/uk/channels/channel-routing) -- [Безпека](/uk/gateway/security) -- [Маршрутизація кількох агентів](/uk/concepts/multi-agent) -- [Усунення проблем](/uk/channels/troubleshooting) -- [Slash-команди](/uk/tools/slash-commands) + + + Зв’яжіть користувача Discord із gateway. + + + Поведінка групового чату та allowlist. + + + Маршрутизуйте вхідні повідомлення до агентів. + + + Модель загроз і посилення захисту. + + + Зіставляйте сервери й канали з агентами. + + + Поведінка нативних команд. + + diff --git a/docs/uk/ci.md b/docs/uk/ci.md index a36b973ad..4b400c553 100644 --- a/docs/uk/ci.md +++ b/docs/uk/ci.md @@ -2,24 +2,24 @@ read_when: - Вам потрібно зрозуміти, чому завдання CI запустилося або не запустилося - Ви налагоджуєте збої перевірок GitHub Actions -summary: Граф завдань CI, гейти за областю змін і локальні еквіваленти команд +summary: Граф завдань CI, обмеження області, і локальні еквіваленти команд title: Конвеєр CI x-i18n: - generated_at: "2026-04-23T17:53:34Z" + generated_at: "2026-04-23T18:24:14Z" model: gpt-5.4 provider: openai - source_hash: 1de796d57e79eda0328f20172f9029af485a57a3996bc8615e3a7bce281b7d85 + source_hash: 089e7b4dc59bf11ad643ced552537b761da62314717a15b7971e2abc7053a38b source_path: ci.md workflow: 15 --- # Конвеєр CI -CI запускається під час кожного push у `main` і для кожного pull request. Він використовує розумне визначення області змін, щоб пропускати дорогі завдання, коли змінено лише непов’язані ділянки. +CI запускається при кожному push у `main` і для кожного pull request. Він використовує розумне обмеження області, щоб пропускати дорогі завдання, коли змінено лише непов’язані частини. -QA Lab має окремі гілки CI поза основним workflow з розумним визначенням області змін. Workflow `Parity gate` запускається для відповідних змін у PR і через ручний запуск; він збирає приватний runtime QA і порівнює агентні пакети mock GPT-5.4 та Opus 4.6. Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і через ручний запуск; він розгалужує mock parity gate, live lane Matrix і live lane Telegram як паралельні завдання. Live-завдання використовують середовище `qa-live-shared`, а lane Telegram використовує оренди Convex. `OpenClaw Release Checks` також запускає ті самі lane QA Lab перед погодженням релізу. +QA Lab має окремі смуги CI поза основним workflow з розумним обмеженням області. Workflow `Parity gate` запускається для відповідних змін у PR і через manual dispatch; він збирає приватне середовище виконання QA і порівнює агентні набори mock GPT-5.4 та Opus 4.6. Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і через manual dispatch; він розгалужує mock parity gate, live Matrix lane і live Telegram lane як паралельні завдання. Live-завдання використовують середовище `qa-live-shared`, а Telegram lane використовує Convex leases. `OpenClaw Release Checks` також запускає ті самі смуги QA Lab перед схваленням релізу. -Workflow `Duplicate PRs After Merge` — це ручний workflow для мейнтейнерів для очищення дублікатів після злиття. За замовчуванням він працює в режимі dry-run і закриває лише явно вказані PR, коли `apply=true`. Перед внесенням змін у GitHub він перевіряє, що злитий PR справді об’єднано і що кожен дублікат має або спільну згадану issue, або перекривні змінені hunks. +Workflow `Duplicate PRs After Merge` — це ручний workflow для супровідників для очищення дублікатів після приземлення змін. За замовчуванням він працює в режимі dry-run і закриває лише явно перелічені PR, коли `apply=true`. Перш ніж змінювати GitHub, він перевіряє, що приземлений PR злитий, і що кожен дублікат має або спільний згаданий issue, або перетин змінених hunks. ```bash gh workflow run duplicate-after-merge.yml \ @@ -30,81 +30,81 @@ gh workflow run duplicate-after-merge.yml \ ## Огляд завдань -| Завдання | Призначення | Коли запускається | -| -------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------- | -| `preflight` | Визначає зміни лише в документації, області змін, змінені extensions і будує CI-маніфест | Завжди для push і PR не в draft | -| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для push і PR не в draft | -| `security-dependency-audit` | Аудит production lockfile без залежностей щодо advisory npm | Завжди для push і PR не в draft | -| `security-fast` | Обов’язковий агрегатор для швидких завдань безпеки | Завжди для push і PR не в draft | -| `build-artifacts` | Збирає `dist/`, Control UI, перевірки built-artifact і перевикористовувані downstream-артефакти | Зміни, релевантні для Node | -| `checks-fast-core` | Швидкі Linux lane коректності, як-от bundled/plugin-contract/protocol перевірки | Зміни, релевантні для Node | -| `checks-fast-contracts-channels` | Шардовані перевірки контрактів каналів зі стабільним агрегованим результатом | Зміни, релевантні для Node | -| `checks-node-extensions` | Повні шарди тестів bundled plugin у всьому наборі extensions | Зміни, релевантні для Node | -| `checks-node-core-test` | Шарди core Node тестів, окрім lane каналів, bundled, контрактів і extensions | Зміни, релевантні для Node | -| `extension-fast` | Сфокусовані тести лише для змінених bundled plugin | Pull request зі змінами в extensions | -| `check` | Шардований еквівалент основного локального gate: prod types, lint, guards, test types і strict smoke | Зміни, релевантні для Node | -| `check-additional` | Архітектурні, boundary, guards поверхні extensions, package-boundary і shard gateway-watch | Зміни, релевантні для Node | -| `build-smoke` | Smoke-тести зібраного CLI і smoke перевірка пам’яті під час старту | Зміни, релевантні для Node | -| `checks` | Верифікатор для built-artifact тестів каналів плюс lane сумісності Node 22 лише для push | Зміни, релевантні для Node | -| `check-docs` | Форматування документації, lint і перевірки зламаних посилань | Змінено docs | -| `skills-python` | Ruff + pytest для Skills на основі Python | Зміни, релевантні для Python Skills | -| `checks-windows` | Специфічні для Windows lane тестів | Зміни, релевантні для Windows | -| `macos-node` | Lane TypeScript тестів на macOS з використанням спільних built artifacts | Зміни, релевантні для macOS | -| `macos-swift` | Swift lint, build і тести для застосунку macOS | Зміни, релевантні для macOS | -| `android` | Android unit-тести для обох flavor плюс одна debug APK збірка | Зміни, релевантні для Android | +| Завдання | Призначення | Коли запускається | +| -------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------ | +| `preflight` | Визначає зміни лише в docs, змінені області, змінені extensions і будує маніфест CI | Завжди для non-draft push і PR | +| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для non-draft push і PR | +| `security-dependency-audit` | Аудит production lockfile без залежностей щодо advisory npm | Завжди для non-draft push і PR | +| `security-fast` | Обов’язковий агрегатор для швидких завдань безпеки | Завжди для non-draft push і PR | +| `build-artifacts` | Збірка `dist/`, Control UI, перевірки built artifacts і багаторазово використовувані downstream artifacts | Зміни, релевантні для Node | +| `checks-fast-core` | Швидкі correctness-смуги Linux, такі як bundled/plugin-contract/protocol checks | Зміни, релевантні для Node | +| `checks-fast-contracts-channels` | Шардовані перевірки контрактів channel зі стабільним агрегованим результатом перевірки | Зміни, релевантні для Node | +| `checks-node-extensions` | Повні шарди тестів bundled plugin у всьому наборі extension | Зміни, релевантні для Node | +| `checks-node-core-test` | Шарди тестів core Node, за винятком смуг channel, bundled, contract та extension | Зміни, релевантні для Node | +| `extension-fast` | Сфокусовані тести лише для змінених bundled plugin | Pull request із змінами extension | +| `check` | Шардований еквівалент основного локального gate: prod types, lint, guards, test types і strict smoke | Зміни, релевантні для Node | +| `check-additional` | Architecture, boundary, guards поверхні extension, package-boundary та шарди gateway-watch | Зміни, релевантні для Node | +| `build-smoke` | Smoke-тести зібраного CLI і smoke перевірка startup-memory | Зміни, релевантні для Node | +| `checks` | Верифікатор для built-artifact тестів channel плюс compat-напрям Node 22 лише для push | Зміни, релевантні для Node | +| `check-docs` | Форматування docs, lint і перевірки зламаних посилань | Змінено docs | +| `skills-python` | Ruff + pytest для Skills на базі Python | Зміни, релевантні для Python Skills | +| `checks-windows` | Специфічні для Windows тестові смуги | Зміни, релевантні для Windows | +| `macos-node` | Смуга тестів TypeScript на macOS з використанням спільних built artifacts | Зміни, релевантні для macOS | +| `macos-swift` | Lint, build і тести Swift для застосунку macOS | Зміни, релевантні для macOS | +| `android` | Юніт-тести Android для обох flavor плюс одна збірка debug APK | Зміни, релевантні для Android | -## Порядок fail-fast +## Порядок Fail-Fast -Завдання впорядковано так, щоб дешеві перевірки падали раніше, ніж запустяться дорогі: +Завдання впорядковані так, щоб дешеві перевірки завершувалися з помилкою раніше, ніж запускаються дорогі: -1. `preflight` вирішує, які lane взагалі існують. Логіка `docs-scope` і `changed-scope` — це кроки всередині цього завдання, а не окремі завдання. -2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` падають швидко, не чекаючи важчих artifact- і platform-matrix-завдань. -3. `build-artifacts` виконується паралельно зі швидкими Linux lane, щоб downstream-споживачі могли почати роботу, щойно спільна збірка буде готова. -4. Після цього розгалужуються важчі platform і runtime lane: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, лише для PR `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. +1. `preflight` вирішує, які смуги взагалі існують. Логіка `docs-scope` і `changed-scope` — це кроки всередині цього завдання, а не окремі завдання. +2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` завершуються швидко без очікування важчих завдань артефактів і платформених матриць. +3. `build-artifacts` виконується паралельно зі швидкими Linux-смугами, щоб downstream-споживачі могли стартувати, щойно спільна збірка готова. +4. Після цього розгалужуються важчі платформені та runtime-смуги: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast` лише для PR, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. -Логіка області змін живе в `scripts/ci-changed-scope.mjs` і покрита unit-тестами в `src/scripts/ci-changed-scope.test.ts`. -Редагування CI workflow перевіряє Node CI graph разом із lint перевіркою workflow, але саме по собі не примушує запускати нативні збірки Windows, Android або macOS; ці platform lane залишаються прив’язаними до змін у platform source. -Перевірки Windows Node прив’язані до специфічних для Windows обгорток process/path, helper-ів npm/pnpm/UI runner, конфігурації package manager і поверхонь CI workflow, які запускають цей lane; непов’язані зміни в source, plugin, install-smoke і лише тестові зміни залишаються в Linux Node lane, щоб не резервувати Windows worker із 16 vCPU для покриття, яке вже забезпечують звичайні шарди тестів. -Окремий workflow `install-smoke` повторно використовує той самий скрипт області змін через власне завдання `preflight`. Він обчислює `run_install_smoke` з вужчого сигналу changed-smoke, тому Docker/install smoke запускається для змін, пов’язаних з install, packaging, контейнерами, production changes у bundled extension, а також для поверхонь core plugin/channel/gateway/Plugin SDK, які перевіряють Docker smoke jobs. Лише тестові та лише docs-редагування не резервують Docker workers. Його QR package smoke примушує шар Docker `pnpm install` виконатися повторно, зберігаючи cache сховища BuildKit pnpm, тому інсталяція все одно перевіряється без повторного завантаження залежностей під час кожного запуску. Його gateway-network e2e повторно використовує runtime image, зібраний раніше в межах цього завдання, тож додає реальне покриття WebSocket між контейнерами без додавання ще однієї Docker-збірки. Локально `test:docker:all` попередньо збирає один спільний live-test image і один спільний built-app image з `scripts/e2e/Dockerfile`, а потім запускає live/E2E smoke lane паралельно з `OPENCLAW_SKIP_DOCKER_BUILD=1`; стандартний рівень паралелізму 4 можна налаштувати через `OPENCLAW_DOCKER_ALL_PARALLELISM`. Локальний агрегатор за замовчуванням припиняє планувати нові pooled lane після першої помилки, а кожен lane має таймаут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Lane, чутливі до startup або provider, запускаються ексклюзивно після паралельного пулу. Повторно використовуваний workflow live/E2E віддзеркалює шаблон shared-image: він збирає і пушить один Docker E2E image у GHCR з тегом SHA перед Docker matrix, а потім запускає matrix з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Запланований workflow live/E2E щодня запускає повний релізний Docker suite. Docker-тести QR та installer зберігають власні install-орієнтовані Dockerfile. Окреме завдання `docker-e2e-fast` запускає обмежений Docker profile для bundled plugin з таймаутом команди 120 секунд: repair залежностей setup-entry плюс синтетична ізоляція збоїв bundled-loader. Повна matrix оновлення bundled і каналів залишається manual/full-suite, тому що вона виконує повторні реальні проходи npm update і doctor repair. +Логіка області знаходиться в `scripts/ci-changed-scope.mjs` і покрита unit-тестами в `src/scripts/ci-changed-scope.test.ts`. +Зміни workflow CI перевіряють граф Node CI плюс lint workflow, але самі по собі не примушують запускати нативні збірки Windows, Android або macOS; ці платформені смуги залишаються обмеженими змінами у вихідному коді відповідних платформ. +Перевірки Windows Node обмежені специфічними для Windows обгортками process/path, допоміжними засобами для npm/pnpm/UI runner, конфігурацією package manager і поверхнями workflow CI, що виконують цю смугу; непов’язані зміни вихідного коду, plugin, install-smoke і лише тестів залишаються в Linux Node smугам, щоб не резервувати Windows worker на 16 vCPU для покриття, яке вже виконується звичайними test shards. +Окремий workflow `install-smoke` повторно використовує той самий скрипт області через власне завдання `preflight`. Він обчислює `run_install_smoke` із вужчого сигналу changed-smoke, тож Docker/install smoke запускається для змін, пов’язаних з install, packaging, контейнерами, production-змін bundled extension, а також для поверхонь core plugin/channel/gateway/Plugin SDK, які перевіряють Docker smoke jobs. Зміни лише тестів і лише docs не резервують Docker workers. Його smoke QR package змушує шар Docker `pnpm install` виконатися повторно, зберігаючи кеш BuildKit pnpm store, тож він усе одно перевіряє встановлення без повторного завантаження залежностей при кожному запуску. Його gateway-network e2e повторно використовує runtime image, зібраний раніше в цьому завданні, тож додає реальне покриття WebSocket контейнер-до-контейнера без додавання ще однієї Docker build. Локальний `test:docker:all` попередньо збирає один спільний live-test image і один спільний built-app image `scripts/e2e/Dockerfile`, а потім запускає live/E2E smoke-смуги паралельно з `OPENCLAW_SKIP_DOCKER_BUILD=1`; налаштовуйте стандартний паралелізм 4 через `OPENCLAW_DOCKER_ALL_PARALLELISM`. Локальний агрегатор за замовчуванням припиняє планувати нові pooled-smуги після першої помилки, а кожна смуга має тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Смуги, чутливі до startup або provider, виконуються ексклюзивно після паралельного пулу. Багаторазово використовуваний live/E2E workflow повторює шаблон спільного image, збираючи й публікуючи один GHCR Docker E2E image з тегом SHA перед Docker matrix, а потім запускає matrix з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Запланований live/E2E workflow щодня запускає повний Docker suite шляху релізу. Docker-тести QR та installer зберігають власні install-орієнтовані Dockerfile. Окреме завдання `docker-e2e-fast` запускає обмежений профіль Docker для bundled plugin з тайм-аутом команди 120 секунд: відновлення залежностей setup-entry плюс ізоляція синтетичного збою bundled-loader. Повна матриця bundled update/channel залишається ручною/повним набором, оскільки виконує повторні реальні проходи npm update і doctor repair. -Локальна логіка changed-lane живе в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний gate суворіший щодо архітектурних boundary, ніж широка CI-область платформ: зміни в core production запускають core prod typecheck плюс core тести, лише зміни в core tests запускають лише core test typecheck/tests, зміни в extension production запускають extension prod typecheck плюс extension тести, а лише зміни в extension tests запускають лише extension test typecheck/tests. Зміни в публічному Plugin SDK або plugin-contract розширюють перевірку на extensions, тому що extensions залежать від цих core-контрактів. Зміни лише в release metadata для version bump запускають точкові перевірки version/config/root-dependency. Невідомі зміни в root/config безпечно призводять до запуску всіх lane. +Локальна логіка changed-lane знаходиться в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний gate суворіший щодо архітектурних меж, ніж широка платформена область CI: production-зміни core запускають перевірку типів core prod плюс тести core, зміни лише тестів core запускають лише перевірку типів/тести core test, production-зміни extension запускають перевірку типів extension prod плюс тести extension, а зміни лише тестів extension запускають лише перевірку типів/тести extension test. Зміни публічного Plugin SDK або plugin-contract розширюють перевірку на extension, тому що extension залежать від цих контрактів core. Підвищення версії лише в метаданих релізу запускають цільові перевірки version/config/root-dependency. Невідомі зміни root/config безпечно переводять до всіх смуг. -Для push matrix `checks` додає lane `compat-node22`, який запускається лише для push. Для pull request цей lane пропускається, а matrix залишається зосередженою на звичайних test/channel lane. +Для push матриця `checks` додає смугу `compat-node22`, яка запускається лише для push. Для pull request ця смуга пропускається, і матриця залишається зосередженою на звичайних test/channel смугах. -Найповільніші сімейства Node тестів розділено або збалансовано так, щоб кожне завдання залишалося невеликим без надмірного резервування runner-ів: контракти каналів запускаються у трьох зважених shard, тести bundled plugin збалансовані між шістьма workers для extensions, невеликі core unit lane об’єднано попарно, auto-reply запускається в трьох збалансованих workers замість шести дрібних, а agentic gateway/plugin configs розподілено між наявними source-only agentic Node jobs замість очікування built artifacts. Широкі browser, QA, media і miscellaneous plugin тести використовують свої окремі конфігурації Vitest замість спільного універсального plugin-набору. Широкий lane agents використовує спільний file-parallel scheduler Vitest, тому що в ньому домінують імпорт і планування, а не один повільний тестовий файл. `runtime-config` запускається разом із shard infra core-runtime, щоб спільний runtime shard не залишався найдовшим. `check-additional` тримає разом роботу package-boundary compile/canary і відокремлює архітектуру runtime topology від покриття gateway watch; shard boundary guard запускає свої невеликі незалежні guards паралельно всередині одного завдання. Gateway watch, тести каналів і shard core support-boundary виконуються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрано, зберігаючи їхні попередні назви перевірок як легкі завдання-верифікатори, водночас уникаючи двох додаткових Blacksmith worker-ів і другої черги споживачів артефактів. -Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Flavor third-party не має окремого source set або manifest; його lane unit-тестів усе одно компілює цей flavor з прапорами SMS/call-log у BuildConfig, водночас уникаючи дубльованого завдання пакування debug APK під час кожного Android-релевантного push. -`extension-fast` запускається лише для PR, тому що push-запуски вже виконують повні шарди bundled plugin. Це зберігає швидкий зворотний зв’язок щодо змінених plugin для review, не резервуючи додатковий Blacksmith worker на `main` для покриття, яке вже є в `checks-node-extensions`. +Найповільніші сімейства тестів Node розділені або збалансовані так, щоб кожне завдання залишалося невеликим без надмірного резервування runner-ів: контракти channel запускаються в трьох зважених shards, тести bundled plugin балансуються між шістьма worker-ами extension, малі core unit-смуги поєднані в пари, auto-reply запускається на трьох збалансованих worker-ах замість шести дрібних worker-ів, а конфігурації agentic gateway/plugin розподілені по наявних source-only agentic Node jobs замість очікування built artifacts. Широкі browser-, QA-, media- і miscellaneous plugin-тести використовують власні конфігурації Vitest замість спільного plugin catch-all. Завдання shard extension можуть запускати дві групи конфігурацій plugin одночасно, але обмежують кожну конфігурацію Vitest одним worker-ом, щоб важкі за імпортом пакети plugin не перевантажували малі CI runner-и. Широка agents-смуга використовує спільний Vitest file-parallel scheduler, тому що в ній домінують імпорт і планування, а не один повільний тестовий файл. `runtime-config` запускається разом із shard infra core-runtime, щоб спільний runtime shard не залишався хвостом. `check-additional` тримає package-boundary compile/canary-роботи разом і відокремлює архітектуру topology runtime від покриття gateway watch; shard boundary guard запускає свої невеликі незалежні guards паралельно в межах одного завдання. Gateway watch, channel tests і core support-boundary shard виконуються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрані, зберігаючи їхні старі назви перевірок як легкі verifier jobs, водночас уникаючи двох додаткових Blacksmith worker-ів і другої черги споживачів артефактів. +Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Flavor third-party не має окремого source set або manifest; його смуга unit-тестів усе одно компілює цей flavor із прапорцями SMS/call-log у BuildConfig, водночас уникаючи дубльованого завдання пакування debug APK для кожного релевантного Android push. +`extension-fast` доступне лише для PR, тому що push-запуски вже виконують повні шарди bundled plugin. Це дає швидкий зворотний зв’язок щодо змінених plugin під час review без резервування додаткового Blacksmith worker-а на `main` для покриття, яке вже присутнє в `checks-node-extensions`. -GitHub може позначати замінені новішими запусками завдання як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Вважайте це шумом CI, якщо тільки найновіший запуск для того самого ref теж не падає. Агреговані shard checks використовують `!cancelled() && always()`, тож вони все одно повідомляють про звичайні помилки shard, але не стають у чергу після того, як увесь workflow уже було замінено новішим. -Ключ concurrency у CI має версію (`CI-v7-*`), щоб zombie-процес на боці GitHub у старій групі черги не міг безкінечно блокувати новіші запуски main. +GitHub може позначати заміщені завдання як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Вважайте це шумом CI, якщо лише найновіший запуск для того самого ref також не завершується з помилкою. Агреговані перевірки shards використовують `!cancelled() && always()`, тому вони все одно повідомляють про звичайні збої shards, але не стають у чергу після того, як увесь workflow уже було заміщено. +Ключ concurrency для CI має версію (`CI-v7-*`), щоб zombie на боці GitHub у старій групі черги не міг безстроково блокувати новіші запуски `main`. ## Виконавці -| Виконавець | Завдання | -| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки та агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки protocol/contract/bundled, шардовані перевірки контрактів каналів, shard `check`, окрім lint, shard `check-additional` і агрегати, aggregate verifier-и Node тестів, перевірки docs, Python Skills, workflow-sanity, labeler, auto-response; `preflight` для install-smoke також використовує GitHub-hosted Ubuntu, щоб matrix Blacksmith могла стати в чергу раніше | -| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shard Node тестів на Linux, shard тестів bundled plugin, `android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, який залишається достатньо чутливим до CPU, тож 8 vCPU коштували дорожче, ніж заощаджували; Docker-збірки install-smoke, де час очікування в черзі для 32 vCPU коштував дорожче, ніж заощаджував | -| `blacksmith-16vcpu-windows-2025` | `checks-windows` | -| `blacksmith-6vcpu-macos-latest` | `macos-node` у `openclaw/openclaw`; для fork використовується резервний `macos-latest` | -| `blacksmith-12vcpu-macos-latest` | `macos-swift` у `openclaw/openclaw`; для fork використовується резервний `macos-latest` | +| Виконавець | Завдання | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки й агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки protocol/contract/bundled, шардовані перевірки контрактів channel, шарди `check`, окрім lint, шарди й агрегати `check-additional`, агреговані верифікатори тестів Node, перевірки docs, Python Skills, workflow-sanity, labeler, auto-response; preflight для install-smoke також використовує Ubuntu, розміщений на GitHub, щоб матриця Blacksmith могла ставати в чергу раніше | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, шарди тестів Linux Node, шарди тестів bundled plugin, `android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, який усе ще достатньо чутливий до CPU, тож 8 vCPU коштували більше, ніж заощаджували; Docker-збірки install-smoke, де час очікування в черзі на 32 vCPU коштував більше, ніж заощаджував | +| `blacksmith-16vcpu-windows-2025` | `checks-windows` | +| `blacksmith-6vcpu-macos-latest` | `macos-node` у `openclaw/openclaw`; для fork використовується `macos-latest` | +| `blacksmith-12vcpu-macos-latest` | `macos-swift` у `openclaw/openclaw`; для fork використовується `macos-latest` | ## Локальні еквіваленти ```bash -pnpm changed:lanes # переглянути локальний класифікатор changed-lane для origin/main...HEAD -pnpm check:changed # розумний локальний gate: typecheck/lint/tests для змін за boundary lane +pnpm changed:lanes # перевірити локальний класифікатор changed-lane для origin/main...HEAD +pnpm check:changed # розумний локальний gate: changed typecheck/lint/tests за boundary lane pnpm check # швидкий локальний gate: production tsgo + шардований lint + паралельні швидкі guards pnpm check:test-types -pnpm check:timed # той самий gate з таймінгами для кожного етапу +pnpm check:timed # той самий gate із таймінгами для кожного етапу pnpm build:strict-smoke pnpm check:architecture pnpm test:gateway:watch-regression pnpm test # тести vitest pnpm test:channels pnpm test:contracts:channels -pnpm check:docs # форматування docs + lint + биті посилання -pnpm build # зібрати dist, коли важливі CI lane artifact/build-smoke -node scripts/ci-run-timings.mjs # підсумувати загальний час, час очікування в черзі та найповільніші завдання -node scripts/ci-run-timings.mjs --recent 10 # порівняти останні успішні запуски main CI +pnpm check:docs # форматування docs + lint + зламані посилання +pnpm build # зібрати dist, коли важливі смуги CI artifact/build-smoke +node scripts/ci-run-timings.mjs # підсумувати загальний час, час у черзі й найповільніші завдання +node scripts/ci-run-timings.mjs --recent 10 # порівняти нещодавні успішні запуски CI для main ``` diff --git a/docs/uk/gateway/security/index.md b/docs/uk/gateway/security/index.md index a503d91e8..40d0a35a6 100644 --- a/docs/uk/gateway/security/index.md +++ b/docs/uk/gateway/security/index.md @@ -1,37 +1,35 @@ --- read_when: - Додавання функцій, які розширюють доступ або автоматизацію -summary: Міркування щодо безпеки та модель загроз для запуску AI Gateway із доступом до оболонки +summary: Міркування безпеки та модель загроз для запуску AI Gateway із доступом до оболонки title: Безпека x-i18n: - generated_at: "2026-04-23T08:02:52Z" + generated_at: "2026-04-23T18:24:13Z" model: gpt-5.4 provider: openai - source_hash: ccdc8d9a0eef88294d9f831ec4f24eb90b00631b9266d69df888a62468cb1dea + source_hash: 9d0e79f3fd76d75e545f8e58883bd06ffbf48f909b4987e90d6bae72ad9808b3 source_path: gateway/security/index.md workflow: 15 --- -# Безпека - -**Модель довіри персонального помічника:** ці рекомендації виходять із припущення про одну межу довіри оператора на Gateway (модель одного користувача/персонального помічника). -OpenClaw **не є** безпечною межею для ворожого багатокористувацького середовища, де кілька зловмисно налаштованих користувачів ділять один agent/Gateway. -Якщо вам потрібна робота зі змішаною довірою або ворожими користувачами, розділяйте межі довіри (окремий Gateway + облікові дані, а в ідеалі — окремі користувачі ОС/хости). + **Модель довіри для персонального асистента.** Ці рекомендації виходять із припущення про одну межу довіри оператора на Gateway (модель одного користувача, персонального асистента). + OpenClaw **не** є ворожою багатокористувацькою межею безпеки для кількох + недовірених користувачів, які спільно використовують одного агента або Gateway. Якщо вам потрібна робота зі змішаною довірою або за участю + ворожих користувачів, розділіть межі довіри (окремий Gateway + + облікові дані, в ідеалі також окремі користувачі ОС або хости). -**На цій сторінці:** [Модель довіри](#scope-first-personal-assistant-security-model) | [Швидкий аудит](#quick-check-openclaw-security-audit) | [Посилена базова конфігурація](#hardened-baseline-in-60-seconds) | [Модель доступу DM](#dm-access-model-pairing-allowlist-open-disabled) | [Посилення конфігурації](#configuration-hardening-examples) | [Реагування на інциденти](#incident-response) +## Спершу про межі: модель безпеки персонального асистента -## Спочатку про межі: модель безпеки персонального помічника +Рекомендації з безпеки OpenClaw передбачають розгортання **персонального асистента**: одна межа довіри оператора, потенційно багато агентів. -Рекомендації з безпеки OpenClaw виходять із розгортання **персонального помічника**: одна межа довіри оператора, потенційно багато agent. +- Підтримувана позиція безпеки: один користувач/межа довіри на Gateway (бажано один користувач ОС/хост/VPS на одну межу). +- Непідтримувана межа безпеки: один спільний Gateway/агент, яким користуються взаємно недовірені або ворожі користувачі. +- Якщо потрібна ізоляція від ворожих користувачів, розділяйте за межами довіри (окремий Gateway + облікові дані, а в ідеалі ще й окремі користувачі ОС/хости). +- Якщо кілька недовірених користувачів можуть надсилати повідомлення одному агенту з увімкненими інструментами, вважайте, що вони спільно користуються однаковими делегованими повноваженнями цього агента на використання інструментів. -- Підтримувана модель безпеки: один користувач/межа довіри на Gateway (бажано один користувач ОС/хост/VPS на одну межу). -- Непідтримувана межа безпеки: один спільний Gateway/agent, яким користуються взаємно недовірені або ворожо налаштовані користувачі. -- Якщо потрібна ізоляція ворожих користувачів, розділяйте за межами довіри (окремий Gateway + облікові дані, а в ідеалі — окремі користувачі ОС/хости). -- Якщо кілька недовірених користувачів можуть надсилати повідомлення одному agent із увімкненими інструментами, вважайте, що всі вони спільно користуються однаковими делегованими повноваженнями цього agent щодо інструментів. - -Ця сторінка пояснює посилення захисту **в межах цієї моделі**. Вона не стверджує наявність ізоляції для ворожого багатокористувацького середовища на одному спільному Gateway. +Ця сторінка пояснює посилення захисту **в межах цієї моделі**. Вона не стверджує наявність ворожої багатокористувацької ізоляції в одному спільному Gateway. ## Швидка перевірка: `openclaw security audit` @@ -46,61 +44,64 @@ openclaw security audit --fix openclaw security audit --json ``` -`security audit --fix` навмисно має вузький обсяг: він перемикає типові відкриті групові політики на allowlist, відновлює `logging.redactSensitive: "tools"`, посилює дозволи для state/config/include-файлів і використовує скидання Windows ACL замість POSIX `chmod` під час роботи у Windows. +`security audit --fix` навмисно має вузьку сферу дії: він перемикає поширені відкриті групові +політики на allowlist, відновлює `logging.redactSensitive: "tools"`, посилює +права доступу до стану/конфігурації/включених файлів і використовує скидання ACL Windows замість +POSIX `chmod` під час роботи у Windows. -Він виявляє типові небезпечні конфігурації (відкрита автентифікація Gateway, відкрите керування браузером, розширені allowlist, дозволи файлової системи, надто поблажливі схвалення exec та відкритий доступ до інструментів у каналах). +Він виявляє поширені небезпечні конфігурації (експонування автентифікації Gateway, експонування керування браузером, розширені allowlist, права доступу до файлової системи, надто поблажливі дозволи на exec і відкритий доступ до інструментів через канали). -OpenClaw — це і продукт, і експеримент: ви підключаєте поведінку frontier-model до реальних поверхонь обміну повідомленнями та реальних інструментів. **Ідеально безпечного** налаштування не існує. Мета — свідомо визначити: +OpenClaw — це і продукт, і експеримент: ви підключаєте поведінку frontier-моделей до реальних поверхонь обміну повідомленнями та реальних інструментів. **«Ідеально безпечного» налаштування не існує.** Мета — свідомо визначити: -- хто може спілкуватися з вашим ботом; -- де боту дозволено діяти; -- до чого бот може отримати доступ. +- хто може звертатися до вашого бота +- де боту дозволено діяти +- до чого бот може мати доступ -Починайте з найменшого доступу, який усе ще дає змогу працювати, і розширюйте його лише зі зростанням упевненості. +Починайте з найменшого доступу, який усе ще достатній для роботи, а потім розширюйте його в міру зростання впевненості. ### Розгортання та довіра до хоста -OpenClaw припускає, що хост і межа конфігурації є довіреними: +OpenClaw виходить із того, що хост і межа конфігурації є довіреними: -- Якщо хтось може змінювати стан/конфігурацію хоста Gateway (`~/.openclaw`, включно з `openclaw.json`), вважайте його довіреним оператором. +- Якщо хтось може змінювати стан/конфігурацію хоста Gateway (`~/.openclaw`, включно з `openclaw.json`), вважайте цю особу довіреним оператором. - Запуск одного Gateway для кількох взаємно недовірених/ворожих операторів **не є рекомендованим налаштуванням**. -- Для команд зі змішаною довірою розділяйте межі довіри окремими Gateway (або щонайменше окремими користувачами ОС/хостами). -- Рекомендований варіант за замовчуванням: один користувач на машину/хост (або VPS), один gateway для цього користувача та один або більше agent у цьому gateway. -- Усередині одного екземпляра Gateway автентифікований доступ оператора — це довірена роль площини керування, а не роль окремого користувача-орендаря. -- Ідентифікатори сеансів (`sessionKey`, session IDs, labels) — це селектори маршрутизації, а не токени авторизації. -- Якщо кілька людей можуть надсилати повідомлення одному agent із доступом до інструментів, кожен із них може керувати тим самим набором дозволів. Ізоляція сеансів/пам’яті на рівні користувача допомагає конфіденційності, але не перетворює спільний agent на механізм авторизації хоста для окремих користувачів. +- Для команд зі змішаним рівнем довіри розділяйте межі довіри через окремі Gateway (або принаймні окремих користувачів ОС/хости). +- Рекомендований варіант за замовчуванням: один користувач на машину/хост (або VPS), один gateway для цього користувача та один або більше агентів у цьому gateway. +- Усередині одного екземпляра Gateway автентифікований доступ оператора — це довірена роль площини керування, а не роль окремого орендаря на користувача. +- Ідентифікатори сесії (`sessionKey`, ID сесій, мітки) — це селектори маршрутизації, а не токени авторизації. +- Якщо кілька людей можуть надсилати повідомлення одному агенту з увімкненими інструментами, кожен із них може керувати тим самим набором дозволів. Ізоляція сесій/пам’яті на рівні користувача допомагає приватності, але не перетворює спільного агента на авторизацію хоста на користувача. ### Спільний робочий простір Slack: реальний ризик -Якщо «усі в Slack можуть писати боту», основний ризик — це делеговані повноваження на використання інструментів: +Якщо «кожен у Slack може писати боту», основний ризик — це делеговані повноваження на використання інструментів: -- будь-який дозволений відправник може ініціювати виклики інструментів (`exec`, браузер, мережеві/файлові інструменти) в межах політики agent; -- ін’єкція prompt/контенту від одного відправника може спричинити дії, що впливають на спільний стан, пристрої або результати; -- якщо один спільний agent має чутливі облікові дані/файли, будь-який дозволений відправник потенційно може спровокувати їх ексфільтрацію через використання інструментів. +- будь-який дозволений відправник може ініціювати виклики інструментів (`exec`, браузер, мережеві/файлові інструменти) в межах політики агента; +- ін’єкція підказок/контенту від одного відправника може спричинити дії, що впливають на спільний стан, пристрої або результати; +- якщо один спільний агент має чутливі облікові дані/файли, будь-який дозволений відправник потенційно може ініціювати їх ексфільтрацію через використання інструментів. -Для командних сценаріїв використовуйте окремі agent/Gateway з мінімальним набором інструментів; agent із персональними даними тримайте приватними. +Використовуйте окремі агенти/Gateway з мінімальним набором інструментів для командних робочих процесів; агентів із персональними даними тримайте приватними. -### Спільний агент для компанії: допустимий шаблон +### Спільний агент компанії: прийнятний шаблон -Це допустимо, коли всі користувачі такого agent перебувають в одній межі довіри (наприклад, одна корпоративна команда), а сам agent суворо обмежений бізнес-контекстом. +Це прийнятно, коли всі, хто використовує цього агента, перебувають у тій самій межі довіри (наприклад, одна команда в компанії), а сам агент суворо обмежений бізнес-завданнями. -- запускайте його на окремій машині/VM/container; -- використовуйте окремого користувача ОС + окремий браузер/профіль/облікові записи для цього runtime; -- не входьте в цьому runtime до особистих облікових записів Apple/Google або особистих профілів браузера/менеджера паролів. +- запускайте його на виділеній машині/VM/контейнері; +- використовуйте виділеного користувача ОС + окремий браузер/профіль/облікові записи для цього середовища виконання; +- не входьте в цьому середовищі виконання до особистих облікових записів Apple/Google або особистих профілів менеджера паролів/браузера. -Якщо ви змішуєте особисті та корпоративні ідентичності в одному runtime, ви руйнуєте розділення та підвищуєте ризик витоку персональних даних. +Якщо ви змішуєте особисті та корпоративні ідентичності в одному середовищі виконання, ви руйнуєте розділення та підвищуєте ризик витоку персональних даних. ## Концепція довіри до Gateway і node -Розглядайте Gateway і node як один домен довіри оператора з різними ролями: +Розглядайте Gateway і node як одну доменну межу довіри оператора з різними ролями: - **Gateway** — це площина керування та поверхня політик (`gateway.auth`, політика інструментів, маршрутизація). -- **Node** — це поверхня віддаленого виконання, спарена з цим Gateway (команди, дії на пристрої, локальні можливості хоста). -- Виклик, автентифікований у Gateway, є довіреним у межах Gateway. Після спарювання дії node вважаються діями довіреного оператора на цьому node. -- `sessionKey` — це вибір маршрутизації/контексту, а не автентифікація окремого користувача. -- Схвалення exec (allowlist + ask) — це запобіжники для наміру оператора, а не ізоляція від ворожого багатокористувацького середовища. -- Продуктовий стандарт OpenClaw для довірених сценаріїв із одним оператором — дозволяти host exec на `gateway`/`node` без запитів на схвалення (`security="full"`, `ask="off"`, якщо ви не посилите це). Це стандарт UX за задумом, а не вразливість сама по собі. -- Схвалення exec прив’язуються до точного контексту запиту та, наскільки можливо, до прямих локальних файлових операндів; вони не моделюють семантично кожен шлях завантажувача runtime/інтерпретатора. Для сильних меж використовуйте sandboxing та ізоляцію хоста. +- **Node** — це поверхня віддаленого виконання, пов’язана з цим Gateway (команди, дії на пристроях, локальні можливості хоста). +- Викликаючий клієнт, автентифікований у Gateway, є довіреним у межах Gateway. Після pairing дії node вважаються діями довіреного оператора на цій node. +- `sessionKey` — це вибір маршрутизації/контексту, а не автентифікація на користувача. +- Підтвердження exec (allowlist + ask) — це запобіжники для наміру оператора, а не ворожа багатокористувацька ізоляція. +- Типове налаштування продукту OpenClaw для довірених сценаріїв з одним оператором полягає в тому, що exec хоста на `gateway`/`node` дозволений без запитів на підтвердження (`security="full"`, `ask="off"`, якщо ви це не посилюєте). Це типовий UX-рішення, а не вразливість саме по собі. +- Підтвердження exec прив’язуються до точного контексту запиту та до прямих локальних файлових операндів за найкращої можливості; вони не моделюють семантично кожен шлях завантаження середовища виконання/інтерпретатора. Для сильних меж використовуйте sandboxing та ізоляцію хоста. Якщо вам потрібна ізоляція від ворожих користувачів, розділяйте межі довіри за користувачами ОС/хостами та запускайте окремі Gateway. @@ -108,30 +109,36 @@ OpenClaw припускає, що хост і межа конфігурації Використовуйте це як швидку модель під час оцінки ризиків: -| Межа або контроль | Що це означає | Типове хибне тлумачення | -| ------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------- | -| `gateway.auth` (token/password/trusted-proxy/device auth) | Автентифікує виклики до Gateway API | «Щоб було безпечно, потрібні підписи для кожного повідомлення в кожному кадрі» | -| `sessionKey` | Ключ маршрутизації для вибору контексту/сеансу | «Ключ сеансу — це межа автентифікації користувача» | -| Запобіжники prompt/контенту | Зменшують ризик зловживання моделлю | «Сама по собі prompt injection уже доводить обхід auth» | -| `canvas.eval` / browser evaluate | Навмисна можливість оператора, коли її ввімкнено | «Будь-який примітив JS eval автоматично є вразливістю в цій моделі довіри» | -| Локальна TUI `!` shell | Явно ініційоване оператором локальне виконання | «Зручна локальна shell-команда — це віддалена ін’єкція» | -| Спарювання node та команди node | Віддалене виконання на рівні оператора на спарених пристроях | «Керування віддаленим пристроєм слід за замовчуванням вважати доступом недовірених користувачів» | +| Межа або контроль | Що це означає | Типове хибне тлумачення | +| --------------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------- | +| `gateway.auth` (token/password/trusted-proxy/device auth) | Автентифікує викликачів для API gateway | «Щоб бути безпечним, потрібні підписи кожного повідомлення в кожному кадрі» | +| `sessionKey` | Ключ маршрутизації для вибору контексту/сесії | «Ключ сесії є межею автентифікації користувача» | +| Запобіжники підказок/контенту | Зменшують ризик зловживання моделлю | «Лише prompt injection уже доводить обхід автентифікації» | +| `canvas.eval` / browser evaluate | Навмисна можливість оператора, коли її ввімкнено | «Будь-який примітив JS eval автоматично є вразливістю в цій моделі довіри» | +| Локальна TUI-оболонка `!` | Явно ініційоване оператором локальне виконання | «Зручна локальна команда оболонки є віддаленою ін’єкцією» | +| Pairing node і команди node | Віддалене виконання на рівні оператора на пов’язаних пристроях | «Керування віддаленим пристроєм слід за замовчуванням вважати недовіреним доступом користувача» | ## Не є вразливостями за задумом -Про такі шаблони часто повідомляють, але зазвичай їх закривають без дій, якщо не показано реального обходу меж: + + Про такі шаблони часто повідомляють, і їх зазвичай закривають без дій, якщо + не продемонстровано реальний обхід межі: -- Ланцюжки, що ґрунтуються лише на prompt injection, без обходу політик/auth/sandbox. -- Твердження, які виходять із припущення про ворожу багатокористувацьку роботу на одному спільному хості/конфігурації. -- Твердження, які класифікують звичайний операторський доступ на читання (наприклад, `sessions.list`/`sessions.preview`/`chat.history`) як IDOR у сценарії зі спільним Gateway. -- Знахідки, що стосуються розгортання лише на localhost (наприклад, HSTS на Gateway, доступному лише через loopback). -- Знахідки щодо підписів вхідних Webhook Discord для вхідних шляхів, яких у цьому репозиторії не існує. -- Звіти, які трактують метадані спарювання node як прихований другий рівень схвалення для кожної команди `system.run`, хоча фактично межею виконання залишається глобальна політика команд node у gateway плюс власні схвалення exec на node. -- Знахідки про «відсутність авторизації на рівні користувача», які трактують `sessionKey` як токен auth. +- Ланцюжки лише з prompt injection без обходу політики, автентифікації чи sandbox. +- Твердження, які виходять із припущення про ворожу багатокористувацьку роботу на одному спільному хості або з однією спільною конфігурацією. +- Твердження, які класифікують звичайний доступ оператора по шляху читання (наприклад, + `sessions.list` / `sessions.preview` / `chat.history`) як IDOR у + сценарії спільного gateway. +- Знахідки для розгортань лише на localhost (наприклад, HSTS на gateway, доступному лише через loopback). +- Знахідки щодо підписів вхідних Discord Webhook для вхідних шляхів, яких не існує в цьому репозиторії. +- Звіти, які трактують метадані pairing node як прихований другий рівень підтвердження кожної команди для `system.run`, хоча реальною межею виконання все одно є глобальна політика gateway для команд node плюс власні підтвердження exec на node. +- Знахідки про «відсутність авторизації на користувача», які трактують `sessionKey` як + токен автентифікації. + -## Посилена базова конфігурація за 60 секунд +## Посилений базовий варіант за 60 секунд -Спочатку використайте цю базову конфігурацію, а потім вибірково знову вмикайте інструменти для кожного довіреного agent: +Спершу використайте цей базовий варіант, а потім вибірково знову вмикайте інструменти для довірених агентів: ```json5 { @@ -156,89 +163,89 @@ OpenClaw припускає, що хост і межа конфігурації } ``` -Це залишає Gateway доступним лише локально, ізолює DM і вимикає інструменти площини керування/runtime за замовчуванням. +Це залишає Gateway доступним лише локально, ізолює DM і за замовчуванням вимикає інструменти площини керування/середовища виконання. ## Швидке правило для спільної скриньки -Якщо більше ніж одна людина може писати вашому боту в DM: +Якщо більше ніж одна людина може надсилати DM вашому боту: -- Установіть `session.dmScope: "per-channel-peer"` (або `"per-account-channel-peer"` для багатoакаунтних каналів). -- Залишайте `dmPolicy: "pairing"` або суворі allowlist. +- Установіть `session.dmScope: "per-channel-peer"` (або `"per-account-channel-peer"` для каналів із кількома обліковими записами). +- Використовуйте `dmPolicy: "pairing"` або суворі allowlist. - Ніколи не поєднуйте спільні DM із широким доступом до інструментів. -- Це посилює захист для кооперативних/спільних вхідних скриньок, але не призначене для ізоляції ворожих співорендарів, якщо користувачі мають спільний доступ на запис до хоста/конфігурації. +- Це посилює захист для кооперативних/спільних скриньок, але не призначене для ворожої коорендної ізоляції, коли користувачі мають спільний доступ на запис до хоста/конфігурації. ## Модель видимості контексту OpenClaw розділяє два поняття: -- **Авторизація тригера**: хто може активувати agent (`dmPolicy`, `groupPolicy`, allowlist, вимоги до згадки). -- **Видимість контексту**: який додатковий контекст вставляється у вхід моделі (тіло відповіді, цитований текст, історія треду, метадані пересилання). +- **Авторизація тригера**: хто може запускати агента (`dmPolicy`, `groupPolicy`, allowlist, вимоги до згадок). +- **Видимість контексту**: який додатковий контекст ін’єктується у вхід моделі (тіло відповіді, цитований текст, історія треду, метадані пересилання). -Allowlist керують тригерами й авторизацією команд. Параметр `contextVisibility` визначає, як фільтрується додатковий контекст (цитовані відповіді, корені тредів, отримана історія): +Allowlist контролюють тригери та авторизацію команд. Параметр `contextVisibility` визначає, як фільтрується додатковий контекст (цитовані відповіді, корені тредів, отримана історія): -- `contextVisibility: "all"` (за замовчуванням) зберігає додатковий контекст у тому вигляді, в якому його отримано. +- `contextVisibility: "all"` (типово) зберігає додатковий контекст у тому вигляді, у якому його отримано. - `contextVisibility: "allowlist"` фільтрує додатковий контекст до відправників, дозволених активними перевірками allowlist. -- `contextVisibility: "allowlist_quote"` працює як `allowlist`, але все ж зберігає одну явно процитовану відповідь. +- `contextVisibility: "allowlist_quote"` працює як `allowlist`, але все одно зберігає одну явно процитовану відповідь. -Установлюйте `contextVisibility` для кожного каналу або кімнати/розмови. Докладніше див. у [Групові чати](/uk/channels/groups#context-visibility-and-allowlists). +Установлюйте `contextVisibility` для кожного каналу або для кожної кімнати/розмови. Докладніше про налаштування див. у [Групові чати](/uk/channels/groups#context-visibility-and-allowlists). Рекомендації для аналізу advisory: -- Твердження, які лише показують, що «модель може бачити цитований або історичний текст від відправників поза allowlist», є знахідками щодо посилення захисту, які усуваються через `contextVisibility`, але самі по собі не є обходом меж auth чи sandbox. -- Щоб мати вплив на безпеку, звіти все одно мають демонструвати обхід межі довіри (auth, політики, sandbox, схвалення або іншої задокументованої межі). +- Твердження, які лише показують, що «модель може бачити цитований або історичний текст від відправників, яких немає в allowlist», є знахідками щодо посилення захисту, які усуваються через `contextVisibility`, а не самі по собі є обходом меж автентифікації чи sandbox. +- Щоб мати вплив на безпеку, звіти все одно мають демонструвати обхід межі довіри (автентифікація, політика, sandbox, підтвердження або інша задокументована межа). -## Що перевіряє аудит (загалом) +## Що перевіряє аудит (на високому рівні) -- **Вхідний доступ** (політики DM, групові політики, allowlist): чи можуть сторонні користувачі активувати бота? -- **Радіус ураження інструментів** (розширені інструменти + відкриті кімнати): чи може prompt injection перетворитися на дії shell/файлової системи/мережі? -- **Зсув схвалення exec** (`security=full`, `autoAllowSkills`, allowlist інтерпретаторів без `strictInlineEval`): чи запобіжники host-exec досі працюють так, як ви очікуєте? - - `security="full"` — це попередження про широку модель безпеки, а не доказ помилки. Це обране значення за замовчуванням для довірених персональних помічників; посилюйте його лише тоді, коли ваша модель загроз потребує схвалень або запобіжників на основі allowlist. -- **Мережевий доступ** (bind/auth Gateway, Tailscale Serve/Funnel, слабкі/короткі токени auth). -- **Доступ до керування браузером** (віддалені node, relay-порти, віддалені кінцеві точки CDP). -- **Гігієна локального диска** (дозволи, symlink, include конфігурації, шляхи «синхронізованих папок»). +- **Вхідний доступ** (політики DM, групові політики, allowlist): чи можуть сторонні користувачі запускати бота? +- **Радіус ураження інструментів** (привілейовані інструменти + відкриті кімнати): чи може prompt injection перетворитися на дії оболонки/файлової системи/мережі? +- **Відхилення в підтвердженнях exec** (`security=full`, `autoAllowSkills`, allowlist інтерпретаторів без `strictInlineEval`): чи запобіжники host-exec усе ще працюють так, як ви очікуєте? + - `security="full"` — це широке попередження про позицію безпеки, а не доказ помилки. Це свідомо вибране типове значення для довірених конфігурацій персонального асистента; посилюйте його лише тоді, коли ваша модель загроз потребує підтверджень або запобіжників через allowlist. +- **Експонування в мережі** (bind/auth Gateway, Tailscale Serve/Funnel, слабкі/короткі токени автентифікації). +- **Експонування керування браузером** (віддалені node, relay-порти, віддалені кінцеві точки CDP). +- **Гігієна локального диска** (права доступу, symlink, включення конфігурації, шляхи «синхронізованих папок»). - **Plugins** (plugins завантажуються без явного allowlist). -- **Зсув політик/помилки конфігурації** (параметри sandbox docker налаштовані, але режим sandbox вимкнено; неефективні шаблони `gateway.nodes.denyCommands`, оскільки зіставлення виконується лише за точною назвою команди, наприклад `system.run`, і не аналізує текст shell; небезпечні записи `gateway.nodes.allowCommands`; глобальний `tools.profile="minimal"` перевизначено профілями окремих agent; інструменти, що належать plugin, доступні за надто поблажливої політики інструментів). -- **Зсув очікувань від runtime** (наприклад, припущення, що неявний exec усе ще означає `sandbox`, хоча тепер `tools.exec.host` за замовчуванням має значення `auto`, або явне встановлення `tools.exec.host="sandbox"` за вимкненого режиму sandbox). -- **Гігієна моделей** (попередження, якщо налаштовані моделі схожі на застарілі; це не жорстке блокування). +- **Відхилення політик/помилкова конфігурація** (налаштування sandbox docker задано, але режим sandbox вимкнено; неефективні шаблони `gateway.nodes.denyCommands`, бо зіставлення виконується лише за точною назвою команди (наприклад, `system.run`) і не аналізує текст оболонки; небезпечні записи `gateway.nodes.allowCommands`; глобальний `tools.profile="minimal"` перевизначається профілями на рівні агентів; інструменти, якими володіє Plugin, доступні через надто поблажливу політику інструментів). +- **Відхилення очікувань середовища виконання** (наприклад, припущення, що неявний exec все ще означає `sandbox`, коли `tools.exec.host` тепер за замовчуванням має значення `auto`, або явне встановлення `tools.exec.host="sandbox"` за вимкненого режиму sandbox). +- **Гігієна моделей** (попереджає, якщо налаштовані моделі виглядають застарілими; це не жорстке блокування). -Якщо ви запускаєте `--deep`, OpenClaw також намагається виконати best-effort живу перевірку Gateway. +Якщо ви запускаєте `--deep`, OpenClaw також намагається виконати probe живого Gateway у режимі best-effort. ## Карта зберігання облікових даних -Використовуйте це під час аудиту доступу або коли вирішуєте, що резервувати: +Використовуйте це під час аудиту доступу або коли вирішуєте, що саме резервувати: - **WhatsApp**: `~/.openclaw/credentials/whatsapp//creds.json` - **Telegram bot token**: config/env або `channels.telegram.tokenFile` (лише звичайний файл; symlink відхиляються) -- **Discord bot token**: config/env або SecretRef (провайдери env/file/exec) +- **Discord bot token**: config/env або SecretRef (постачальники env/file/exec) - **Slack tokens**: config/env (`channels.slack.*`) -- **Pairing allowlist**: +- **Allowlist pairing**: - `~/.openclaw/credentials/-allowFrom.json` (обліковий запис за замовчуванням) - `~/.openclaw/credentials/--allowFrom.json` (неосновні облікові записи) -- **Профілі auth моделі**: `~/.openclaw/agents//agent/auth-profiles.json` -- **File-backed payload секретів (необов’язково)**: `~/.openclaw/secrets.json` -- **Застарілий імпорт OAuth**: `~/.openclaw/credentials/oauth.json` +- **Профілі автентифікації моделей**: `~/.openclaw/agents//agent/auth-profiles.json` +- **Файловий payload секретів (необов’язково)**: `~/.openclaw/secrets.json` +- **Імпорт застарілого OAuth**: `~/.openclaw/credentials/oauth.json` ## Контрольний список аудиту безпеки -Коли аудит виводить знахідки, сприймайте це в такому порядку пріоритету: +Коли аудит виводить знахідки, розглядайте їх у такому порядку пріоритету: -1. **Усе, що є “open”, + увімкнені інструменти**: спочатку обмежте DM/групи (pairing/allowlist), потім посильте політику інструментів/sandboxing. -2. **Публічний мережевий доступ** (LAN bind, Funnel, відсутній auth): виправляйте негайно. -3. **Віддалений доступ до керування браузером**: розглядайте це як операторський доступ (лише tailnet, навмисно спаровувати node, уникати публічного доступу). -4. **Дозволи**: переконайтеся, що state/config/credentials/auth не доступні для читання групою або всіма. +1. **Усе «відкрите» + увімкнені інструменти**: спершу обмежте DM/групи (pairing/allowlist), потім посильте політику інструментів/sandboxing. +2. **Публічне мережеве експонування** (bind на LAN, Funnel, відсутня автентифікація): виправляйте негайно. +3. **Віддалене експонування керування браузером**: ставтеся до нього як до операторського доступу (лише tailnet, навмисне виконуйте pairing node, уникайте публічного експонування). +4. **Права доступу**: переконайтеся, що стан/конфігурація/облікові дані/автентифікація не доступні для читання групі або всім. 5. **Plugins**: завантажуйте лише те, чому явно довіряєте. -6. **Вибір моделі**: надавайте перевагу сучасним, стійким до інструкцій моделям для будь-якого бота з інструментами. +6. **Вибір моделі**: для будь-якого бота з інструментами надавайте перевагу сучасним моделям, посиленим проти інструкційних атак. ## Глосарій аудиту безпеки -Кожна знахідка аудиту має структурований `checkId` (наприклад, +Кожна знахідка аудиту позначається структурованим `checkId` (наприклад, `gateway.bind_no_auth` або `tools.exec.security_full_configured`). Поширені класи критичної серйозності: -- `fs.*` — дозволи файлової системи для state, config, credentials, профілів auth. -- `gateway.*` — режим bind, auth, Tailscale, Control UI, налаштування trusted-proxy. -- `hooks.*`, `browser.*`, `sandbox.*`, `tools.exec.*` — посилення захисту для конкретних поверхонь. -- `plugins.*`, `skills.*` — знахідки щодо ланцюга постачання plugin/Skills і сканування. +- `fs.*` — права доступу до файлової системи для стану, конфігурації, облікових даних, профілів автентифікації. +- `gateway.*` — режим bind, автентифікація, Tailscale, Control UI, налаштування trusted-proxy. +- `hooks.*`, `browser.*`, `sandbox.*`, `tools.exec.*` — посилення захисту для окремих поверхонь. +- `plugins.*`, `skills.*` — знахідки щодо ланцюга постачання та сканування Plugin/Skills. - `security.exposure.*` — наскрізні перевірки, де політика доступу перетинається з радіусом ураження інструментів. Повний каталог із рівнями серйозності, ключами виправлень і підтримкою @@ -250,29 +257,29 @@ Allowlist керують тригерами й авторизацією кома Для генерації ідентичності пристрою Control UI потрібен **безпечний контекст** (HTTPS або localhost). `gateway.controlUi.allowInsecureAuth` — це локальний перемикач сумісності: -- На localhost він дозволяє auth у Control UI без ідентичності пристрою, коли сторінка +- На localhost він дозволяє автентифікацію Control UI без ідентичності пристрою, якщо сторінка завантажена через незахищений HTTP. - Він не обходить перевірки pairing. -- Він не послаблює вимоги до ідентичності пристрою для віддалених (не localhost) сценаріїв. +- Він не послаблює вимоги до ідентичності пристрою для віддалених розгортань (не на localhost). Надавайте перевагу HTTPS (Tailscale Serve) або відкривайте UI на `127.0.0.1`. Лише для аварійних сценаріїв `gateway.controlUi.dangerouslyDisableDeviceAuth` повністю вимикає перевірки ідентичності пристрою. Це серйозне зниження рівня безпеки; -тримайте цю опцію вимкненою, якщо ви не займаєтеся активним налагодженням і не можете швидко повернути зміни. +тримайте його вимкненим, якщо тільки ви активно не налагоджуєте проблему і не можете швидко відкотити зміни. -Окремо від цих небезпечних прапорців, успішний режим `gateway.auth.mode: "trusted-proxy"` -може допускати **операторські** сеанси Control UI без ідентичності пристрою. Це -навмисна поведінка режиму auth, а не обхід через `allowInsecureAuth`, і вона все одно -не поширюється на сеанси Control UI з роллю node. +Окремо від цих небезпечних прапорців, успішний `gateway.auth.mode: "trusted-proxy"` +може допустити **операторські** сесії Control UI без ідентичності пристрою. Це +навмисна поведінка режиму автентифікації, а не обхід через `allowInsecureAuth`, і вона все одно +не поширюється на сесії Control UI з роллю node. -`openclaw security audit` попереджає, коли це налаштування увімкнено. +`openclaw security audit` попереджає, коли цей параметр увімкнено. ## Підсумок небезпечних і незахищених прапорців `openclaw security audit` піднімає `config.insecure_or_dangerous_flags`, коли -увімкнено відомі небезпечні/незахищені перемикачі налагодження. Не використовуйте їх у -production. +відомі незахищені/небезпечні відлагоджувальні перемикачі ввімкнені. У +production вони мають бути не задані. @@ -292,24 +299,24 @@ production. - `gateway.controlUi.dangerouslyDisableDeviceAuth` - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - Зіставлення назв каналів (вбудовані канали та канали plugin; також доступно для - `accounts.`, де це застосовно): + Зіставлення назв каналів (вбудовані канали та канали Plugin; також доступно для + `accounts.`, де застосовно): - `channels.discord.dangerouslyAllowNameMatching` - `channels.slack.dangerouslyAllowNameMatching` - `channels.googlechat.dangerouslyAllowNameMatching` - `channels.msteams.dangerouslyAllowNameMatching` - - `channels.synology-chat.dangerouslyAllowNameMatching` (канал plugin) - - `channels.synology-chat.dangerouslyAllowInheritedWebhookPath` (канал plugin) - - `channels.zalouser.dangerouslyAllowNameMatching` (канал plugin) - - `channels.irc.dangerouslyAllowNameMatching` (канал plugin) - - `channels.mattermost.dangerouslyAllowNameMatching` (канал plugin) + - `channels.synology-chat.dangerouslyAllowNameMatching` (канал Plugin) + - `channels.synology-chat.dangerouslyAllowInheritedWebhookPath` (канал Plugin) + - `channels.zalouser.dangerouslyAllowNameMatching` (канал Plugin) + - `channels.irc.dangerouslyAllowNameMatching` (канал Plugin) + - `channels.mattermost.dangerouslyAllowNameMatching` (канал Plugin) - Мережевий доступ: + Мережеве експонування: - `channels.telegram.network.dangerouslyAllowPrivateNetwork` (також для кожного облікового запису) - Sandbox Docker (типові значення + для окремих agent): + Sandbox Docker (типові значення + на рівні агентів): - `agents.defaults.sandbox.docker.dangerouslyAllowReservedContainerTargets` - `agents.defaults.sandbox.docker.dangerouslyAllowExternalBindSources` @@ -318,25 +325,25 @@ production. -## Конфігурація зворотного проксі +## Конфігурація reverse proxy -Якщо ви запускаєте Gateway за зворотним проксі (nginx, Caddy, Traefik тощо), налаштуйте -`gateway.trustedProxies` для коректної обробки IP-адрес клієнтів через forwarding-заголовки. +Якщо ви запускаєте Gateway за reverse proxy (nginx, Caddy, Traefik тощо), налаштуйте +`gateway.trustedProxies` для коректної обробки пересланої IP-адреси клієнта. -Коли Gateway виявляє proxy-заголовки від адреси, якої **немає** у `trustedProxies`, він **не** вважає такі з’єднання локальними клієнтами. Якщо auth gateway вимкнено, такі з’єднання відхиляються. Це запобігає обходу автентифікації, коли проксійовані з’єднання інакше могли б виглядати як такі, що надходять із localhost, і отримувати автоматичну довіру. +Коли Gateway виявляє proxy-заголовки від адреси, якої **немає** у `trustedProxies`, він **не** розглядає з’єднання як локальних клієнтів. Якщо автентифікацію gateway вимкнено, такі з’єднання відхиляються. Це запобігає обходу автентифікації, коли проксійовані з’єднання інакше виглядали б як такі, що надходять із localhost, і автоматично отримували б довіру. -`gateway.trustedProxies` також використовується режимом `gateway.auth.mode: "trusted-proxy"`, але цей режим auth суворіший: +`gateway.trustedProxies` також використовується для `gateway.auth.mode: "trusted-proxy"`, але цей режим автентифікації суворіший: -- auth trusted-proxy **завершується безпечною відмовою для проксі з джерелом loopback** -- зворотні проксі loopback на тому самому хості все ще можуть використовувати `gateway.trustedProxies` для виявлення локальних клієнтів і обробки forwarding IP -- для loopback-зворотних проксі на тому самому хості використовуйте auth за token/password замість `gateway.auth.mode: "trusted-proxy"` +- автентифікація trusted-proxy **завжди закривається при proxy із loopback-джерела** +- reverse proxy на тому самому хості через loopback все ще можуть використовувати `gateway.trustedProxies` для виявлення локального клієнта та обробки пересланого IP +- для reverse proxy на тому самому хості через loopback використовуйте автентифікацію через token/password замість `gateway.auth.mode: "trusted-proxy"` ```yaml gateway: trustedProxies: - - "10.0.0.1" # IP-адреса зворотного проксі + - "10.0.0.1" # IP reverse proxy # Необов’язково. Типове значення false. - # Увімкніть лише якщо ваш проксі не може надавати X-Forwarded-For. + # Увімкніть лише якщо ваш proxy не може надавати X-Forwarded-For. allowRealIpFallback: false auth: mode: password @@ -345,117 +352,117 @@ gateway: Коли налаштовано `trustedProxies`, Gateway використовує `X-Forwarded-For` для визначення IP-адреси клієнта. `X-Real-IP` за замовчуванням ігнорується, якщо явно не встановлено `gateway.allowRealIpFallback: true`. -Правильна поведінка зворотного проксі (перезапис вхідних forwarding-заголовків): +Коректна поведінка reverse proxy (перезапис вхідних заголовків пересилання): ```nginx proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Real-IP $remote_addr; ``` -Неправильна поведінка зворотного проксі (додавання/збереження недовірених forwarding-заголовків): +Некоректна поведінка reverse proxy (додавання/збереження недовірених заголовків пересилання): ```nginx proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; ``` -## Примітки щодо HSTS і origin +## Примітки щодо HSTS та origin -- Gateway OpenClaw орієнтований насамперед на local/loopback. Якщо ви завершуєте TLS на зворотному проксі, налаштуйте HSTS на HTTPS-домені з боку проксі. -- Якщо HTTPS завершується самим gateway, ви можете встановити `gateway.http.securityHeaders.strictTransportSecurity`, щоб OpenClaw додавав заголовок HSTS у свої відповіді. -- Детальні рекомендації щодо розгортання наведено в [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts). -- Для розгортань Control UI поза loopback за замовчуванням потрібен `gateway.controlUi.allowedOrigins`. -- `gateway.controlUi.allowedOrigins: ["*"]` — це явна політика браузерних origin «дозволити все», а не посилене типове значення. Уникайте її поза межами жорстко контрольованого локального тестування. -- Збої browser-origin auth на loopback усе ще мають обмеження за частотою, навіть коли - загальний виняток для loopback увімкнено, але ключ блокування прив’язано до - нормалізованого значення `Origin`, а не до одного спільного localhost-блоку. -- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає режим fallback origin за Host-заголовком; розглядайте його як небезпечну політику, навмисно обрану оператором. -- Розглядайте DNS rebinding і поведінку proxy Host-заголовків як питання посилення безпеки розгортання; тримайте `trustedProxies` вузьким і не відкривайте gateway безпосередньо в публічний інтернет. +- Gateway OpenClaw насамперед призначений для local/loopback. Якщо ви завершуєте TLS на reverse proxy, налаштуйте HSTS на HTTPS-домені, що обслуговується proxy. +- Якщо сам gateway завершує HTTPS, ви можете встановити `gateway.http.securityHeaders.strictTransportSecurity`, щоб OpenClaw додавав заголовок HSTS у відповіді. +- Докладні рекомендації щодо розгортання див. у [Автентифікація Trusted Proxy](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts). +- Для розгортань Control UI не на loopback `gateway.controlUi.allowedOrigins` за замовчуванням є обов’язковим. +- `gateway.controlUi.allowedOrigins: ["*"]` — це явна політика дозволу всіх browser-origin, а не посилене типовe налаштування. Уникайте її поза межами жорстко контрольованого локального тестування. +- Збої автентифікації browser-origin на loopback все одно обмежуються за частотою, навіть коли + загальний виняток для loopback увімкнено, але ключ блокування має область дії за + нормалізованим значенням `Origin`, а не один спільний localhost-bucket. +- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає режим fallback origin за заголовком Host; розглядайте це як небезпечну політику, свідомо вибрану оператором. +- Розглядайте DNS rebinding і поведінку proxy-host header як питання посилення захисту розгортання; тримайте `trustedProxies` вузьким і не відкривайте gateway безпосередньо в публічний інтернет. -## Локальні журнали сеансів зберігаються на диску +## Локальні логи сесій зберігаються на диску -OpenClaw зберігає транскрипти сеансів на диску в `~/.openclaw/agents//sessions/*.jsonl`. -Це потрібно для безперервності сеансів і (необов’язково) індексації пам’яті сеансів, але це також означає, що -**будь-який процес/користувач із доступом до файлової системи може читати ці журнали**. Вважайте доступ до диска -межею довіри та обмежуйте дозволи на `~/.openclaw` (див. розділ аудиту нижче). Якщо вам потрібна -сильніша ізоляція між agent, запускайте їх під окремими користувачами ОС або на окремих хостах. +OpenClaw зберігає стенограми сесій на диску в `~/.openclaw/agents//sessions/*.jsonl`. +Це потрібно для безперервності сесій і (необов’язково) індексації пам’яті сесій, але це також означає, що +**будь-який процес/користувач із доступом до файлової системи може читати ці логи**. Розглядайте доступ до диска як межу +довіри та обмежуйте права на `~/.openclaw` (див. розділ аудиту нижче). Якщо вам потрібна +сильніша ізоляція між агентами, запускайте їх під окремими користувачами ОС або на окремих хостах. ## Виконання на node (`system.run`) -Якщо спарено macOS node, Gateway може викликати `system.run` на цьому node. Це **віддалене виконання коду** на Mac: +Якщо виконано pairing із macOS node, Gateway може викликати `system.run` на цій node. Це **віддалене виконання коду** на Mac: -- Потрібне спарювання node (схвалення + токен). -- Спарювання node через Gateway не є поверхнею схвалення для кожної окремої команди. Воно встановлює ідентичність/довіру до node та видачу токенів. +- Потрібен pairing node (підтвердження + токен). +- Pairing node через Gateway не є поверхнею підтвердження для кожної окремої команди. Він установлює ідентичність/довіру до node та видачу токена. - Gateway застосовує грубу глобальну політику команд node через `gateway.nodes.allowCommands` / `denyCommands`. -- Керування на Mac здійснюється через **Settings → Exec approvals** (security + ask + allowlist). -- Політика `system.run` для кожного node — це власний файл схвалень exec цього node (`exec.approvals.node.*`), який може бути суворішим або м’якшим за глобальну політику ідентифікаторів команд у gateway. -- Node, що працює з `security="full"` і `ask="off"`, дотримується типової моделі довіреного оператора. Вважайте це очікуваною поведінкою, якщо тільки ваше розгортання явно не вимагає суворішої моделі схвалення або allowlist. -- Режим схвалення прив’язує точний контекст запиту та, коли це можливо, один конкретний локальний операнд script/file. Якщо OpenClaw не може визначити рівно один прямий локальний файл для команди інтерпретатора/runtime, виконання на основі схвалення забороняється замість того, щоб обіцяти повне семантичне покриття. -- Для `host=node` виконання на основі схвалення також зберігає канонічний підготовлений - `systemRunPlan`; подальші схвалені forwarding-виклики повторно використовують цей збережений план, а gateway - відхиляє зміни від викликача до command/cwd/session context після створення запиту на схвалення. -- Якщо вам не потрібне віддалене виконання, встановіть security у значення **deny** і скасуйте спарювання node для цього Mac. +- На Mac це контролюється через **Налаштування → Підтвердження exec** (security + ask + allowlist). +- Політика `system.run` для кожної node — це власний файл підтверджень exec цієї node (`exec.approvals.node.*`), який може бути суворішим або м’якшим за глобальну політику Gateway на рівні ID команд. +- Node, що працює з `security="full"` і `ask="off"`, дотримується типової моделі довіреного оператора. Вважайте це очікуваною поведінкою, якщо тільки ваше розгортання явно не потребує суворішого режиму підтверджень або allowlist. +- Режим підтвердження прив’язує точний контекст запиту й, коли це можливо, один конкретний локальний операнд script/file. Якщо OpenClaw не може точно визначити один прямий локальний файл для команди інтерпретатора/середовища виконання, виконання з підтвердженням забороняється замість обіцянки повного семантичного покриття. +- Для `host=node` запуски з підтвердженням також зберігають канонічний підготовлений + `systemRunPlan`; пізніші дозволені переспрямування повторно використовують цей збережений план, а gateway + відхиляє зміни викликачем команди/cwd/контексту сесії після створення запиту на підтвердження. +- Якщо ви не хочете віддаленого виконання, установіть security у **deny** і видаліть pairing node для цього Mac. -Ця відмінність важлива для аналізу: +Це розрізнення важливе для аналізу: -- Повторно підключений спарений node, який оголошує інший список команд, сам по собі не є вразливістю, якщо глобальна політика Gateway та локальні схвалення exec на node і надалі забезпечують реальну межу виконання. -- Звіти, які трактують метадані спарювання node як другий прихований рівень схвалення для кожної команди, зазвичай є плутаниною політики/UX, а не обходом межі безпеки. +- Повторно підключена paired node, яка оголошує інший список команд, сама по собі не є вразливістю, якщо глобальна політика Gateway і локальні підтвердження exec на node все ще забезпечують фактичну межу виконання. +- Звіти, які трактують метадані pairing node як другий прихований рівень підтвердження кожної команди, зазвичай є плутаниною політики/UX, а не обходом межі безпеки. ## Динамічні Skills (watcher / віддалені node) -OpenClaw може оновлювати список Skills посеред сеансу: +OpenClaw може оновлювати список Skills посеред сесії: -- **Watcher Skills**: зміни в `SKILL.md` можуть оновити знімок Skills на наступному ході agent. +- **Skills watcher**: зміни в `SKILL.md` можуть оновити знімок Skills на наступному ході агента. - **Віддалені node**: підключення macOS node може зробити доступними Skills лише для macOS (на основі перевірки bin). -Сприймайте папки Skills як **довірений код** і обмежуйте коло тих, хто може їх змінювати. +Розглядайте папки skill як **довірений код** і обмежуйте коло тих, хто може їх змінювати. ## Модель загроз -Ваш AI-помічник може: +Ваш AI-асистент може: -- Виконувати довільні shell-команди +- Виконувати довільні команди оболонки - Читати/записувати файли - Отримувати доступ до мережевих сервісів -- Надсилати повідомлення будь-кому (якщо ви дали йому доступ до WhatsApp) +- Надсилати повідомлення будь-кому (якщо ви надали йому доступ до WhatsApp) Люди, які пишуть вам, можуть: -- Намагатися змусити AI зробити щось шкідливе -- Використовувати соціальну інженерію для доступу до ваших даних -- Досліджувати деталі інфраструктури +- Спробувати обманом змусити ваш AI зробити щось шкідливе +- Соціальною інженерією намагатися отримати доступ до ваших даних +- Шукати деталі про вашу інфраструктуру -## Основна ідея: контроль доступу перед інтелектом +## Основна концепція: контроль доступу перед інтелектом Більшість збоїв тут — не витончені експлойти, а ситуації на кшталт «хтось написав боту, і бот зробив те, що його попросили». Позиція OpenClaw: -- **Спочатку ідентичність:** визначте, хто може спілкуватися з ботом (спарювання DM / allowlist / явне “open”). -- **Потім межі:** визначте, де боту дозволено діяти (group allowlist + вимога згадки, інструменти, sandboxing, дозволи пристрою). -- **І насамкінець модель:** виходьте з того, що моделлю можна маніпулювати; проєктуйте систему так, щоб наслідки таких маніпуляцій були обмеженими. +- **Спочатку ідентичність:** визначте, хто може звертатися до бота (DM pairing / allowlist / явне “open”). +- **Потім межі:** визначте, де боту дозволено діяти (group allowlist + вимоги до згадок, інструменти, sandboxing, дозволи пристрою). +- **Модель — насамкінець:** припускайте, що моделлю можна маніпулювати; проєктуйте систему так, щоб маніпуляції мали обмежений радіус ураження. ## Модель авторизації команд -Slash-команди та директиви обробляються лише для **авторизованих відправників**. Авторизація визначається -через channel allowlist/спарювання разом із `commands.useAccessGroups` (див. [Конфігурація](/uk/gateway/configuration) -і [Slash-команди](/uk/tools/slash-commands)). Якщо channel allowlist порожній або містить `"*"`, -команди фактично є відкритими для цього каналу. +Slash commands і директиви виконуються лише для **авторизованих відправників**. Авторизація визначається з +allowlist/pairing каналу плюс `commands.useAccessGroups` (див. [Конфігурація](/uk/gateway/configuration) +і [Slash commands](/uk/tools/slash-commands)). Якщо allowlist каналу порожній або містить `"*"`, +команди фактично відкриті для цього каналу. -`/exec` — це зручна функція лише для сеансу для авторизованих операторів. Вона **не** записує конфігурацію і -не змінює інші сеанси. +`/exec` — це зручна функція лише для сесії для авторизованих операторів. Вона **не** записує конфігурацію і +не змінює інші сесії. -## Ризики інструментів площини керування +## Ризик інструментів control plane -Два вбудовані інструменти можуть вносити постійні зміни до площини керування: +Два вбудовані інструменти можуть вносити постійні зміни до control plane: -- `gateway` може перевіряти конфігурацію через `config.schema.lookup` / `config.get`, а також робити постійні зміни через `config.apply`, `config.patch` і `update.run`. -- `cron` може створювати заплановані завдання, які продовжують працювати після завершення початкового чату/задачі. +- `gateway` може переглядати конфігурацію через `config.schema.lookup` / `config.get`, а також вносити постійні зміни через `config.apply`, `config.patch` і `update.run`. +- `cron` може створювати заплановані завдання, які продовжують працювати після завершення початкового чату/завдання. -Інструмент runtime `gateway`, доступний лише власнику, як і раніше, відмовляється переписувати +Інструмент середовища виконання `gateway`, доступний лише власнику, все одно відмовляється переписувати `tools.exec.ask` або `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec перед записом. -Для будь-якого agent/поверхні, що обробляє недовірений контент, забороняйте їх за замовчуванням: +Для будь-якого агента/поверхні, що обробляє недовірений контент, за замовчуванням забороняйте таке: ```json5 { @@ -465,35 +472,33 @@ Slash-команди та директиви обробляються лише } ``` -`commands.restart=false` блокує лише дії перезапуску. Він не вимикає дії `gateway` для конфігурації/оновлення. +`commands.restart=false` блокує лише дії перезапуску. Це не вимикає дії конфігурації/оновлення `gateway`. ## Plugins -Plugins працюють **у тому самому процесі**, що й Gateway. Сприймайте їх як довірений код: +Plugins працюють **у тому самому процесі** що й Gateway. Розглядайте їх як довірений код: -- Встановлюйте plugins лише з джерел, яким ви довіряєте. -- Віддавайте перевагу явним allowlist `plugins.allow`. +- Установлюйте plugins лише з джерел, яким довіряєте. +- Надавайте перевагу явним allowlist `plugins.allow`. - Перевіряйте конфігурацію plugin перед увімкненням. - Перезапускайте Gateway після змін plugin. -- Якщо ви встановлюєте або оновлюєте plugins (`openclaw plugins install `, `openclaw plugins update `), сприймайте це як запуск недовіреного коду: - - Шлях установлення — це каталог конкретного plugin у межах активного кореня встановлення plugin. - - Перед установленням/оновленням OpenClaw запускає вбудоване сканування небезпечного коду. Знахідки рівня `critical` блокуються за замовчуванням. - - OpenClaw використовує `npm pack`, а потім запускає `npm install --omit=dev` у цьому каталозі (npm lifecycle scripts можуть виконувати код під час встановлення). - - Віддавайте перевагу зафіксованим точним версіям (`@scope/pkg@1.2.3`) і перевіряйте розпакований код на диску перед увімкненням. - - `--dangerously-force-unsafe-install` — лише аварійний варіант для хибнопозитивних спрацювань вбудованого сканування під час потоків встановлення/оновлення plugin. Він не обходить блокування політик hook `before_install` plugin і не обходить збої сканування. - - Установлення залежностей Skills через Gateway дотримується того самого розділення на dangerous/suspicious: вбудовані знахідки `critical` блокуються, якщо викликач явно не встановить `dangerouslyForceUnsafeInstall`, тоді як suspicious-знахідки все ще лише попереджають. `openclaw skills install` залишається окремим потоком завантаження/встановлення Skills через ClawHub. +- Якщо ви встановлюєте або оновлюєте plugins (`openclaw plugins install `, `openclaw plugins update `), ставтеся до цього як до запуску недовіреного коду: + - Шлях встановлення — це каталог конкретного plugin у межах активного кореня встановлення plugin. + - OpenClaw запускає вбудоване сканування небезпечного коду перед встановленням/оновленням. Знахідки рівня `critical` за замовчуванням блокують операцію. + - OpenClaw використовує `npm pack`, а потім запускає `npm install --omit=dev` у цьому каталозі (`npm` lifecycle scripts можуть виконувати код під час встановлення). + - Надавайте перевагу зафіксованим точним версіям (`@scope/pkg@1.2.3`) і перевіряйте розпакований код на диску перед увімкненням. + - `--dangerously-force-unsafe-install` — лише для аварійних сценаріїв у разі хибнопозитивних результатів вбудованого сканування в потоках встановлення/оновлення plugin. Він не обходить блокування політик hook `before_install` plugin і не обходить збої сканування. + - Установлення залежностей skill через Gateway дотримується того самого розділення на dangerous/suspicious: вбудовані знахідки `critical` блокують операцію, якщо викликач явно не встановить `dangerouslyForceUnsafeInstall`, тоді як suspicious-знахідки лише попереджають. `openclaw skills install` залишається окремим потоком завантаження/встановлення Skills із ClawHub. Докладніше: [Plugins](/uk/tools/plugin) - +## Модель доступу до DM: pairing, allowlist, open, disabled -## Модель доступу DM (pairing / allowlist / open / disabled) +Усі поточні канали з підтримкою DM мають політику DM (`dmPolicy` або `*.dm.policy`), яка контролює вхідні DM **до** обробки повідомлення: -Усі поточні канали з підтримкою DM мають політику DM (`dmPolicy` або `*.dm.policy`), яка обмежує вхідні DM **до** обробки повідомлення: - -- `pairing` (за замовчуванням): невідомі відправники отримують короткий код спарювання, а бот ігнорує їхнє повідомлення до схвалення. Коди спливають через 1 годину; повторні DM не надсилають код повторно, доки не буде створено новий запит. Кількість запитів, що очікують, за замовчуванням обмежена **3 на канал**. -- `allowlist`: невідомі відправники блокуються (без процедури спарювання). -- `open`: дозволити будь-кому писати в DM (публічно). **Потребує**, щоб channel allowlist містив `"*"` (явне підтвердження). +- `pairing` (типово): невідомі відправники отримують короткий код pairing, а бот ігнорує їхнє повідомлення до схвалення. Коди діють 1 годину; повторні DM не надсилають код повторно, доки не буде створено новий запит. Кількість очікувальних запитів за замовчуванням обмежена **3 на канал**. +- `allowlist`: невідомі відправники блокуються (без handshake pairing). +- `open`: дозволити будь-кому надсилати DM (публічно). **Потребує**, щоб allowlist каналу містив `"*"` (явна згода). - `disabled`: повністю ігнорувати вхідні DM. Схвалення через CLI: @@ -505,9 +510,9 @@ openclaw pairing approve Докладніше + файли на диску: [Pairing](/uk/channels/pairing) -## Ізоляція сеансів DM (багатокористувацький режим) +## Ізоляція DM-сесій (багатокористувацький режим) -За замовчуванням OpenClaw спрямовує **усі DM до основного сеансу**, щоб ваш помічник зберігав безперервність між пристроями та каналами. Якщо **кілька людей** можуть писати боту в DM (відкриті DM або allowlist із кількох осіб), подумайте про ізоляцію сеансів DM: +За замовчуванням OpenClaw спрямовує **усі DM в основну сесію**, щоб ваш асистент зберігав безперервність між пристроями та каналами. Якщо **кілька людей** можуть надсилати DM боту (відкриті DM або allowlist з кількох людей), варто ізолювати DM-сесії: ```json5 { @@ -517,70 +522,70 @@ openclaw pairing approve Це запобігає витоку контексту між користувачами, зберігаючи ізоляцію групових чатів. -Це межа контексту обміну повідомленнями, а не межа адміністрування хоста. Якщо користувачі взаємно ворожі й мають спільний хост/конфігурацію Gateway, запускайте окремі Gateway для кожної межі довіри. +Це межа контексту повідомлень, а не межа адміністрування хоста. Якщо користувачі взаємно ворожі та спільно використовують один і той самий хост/конфігурацію Gateway, запускайте окремі gateway для кожної межі довіри. ### Безпечний режим DM (рекомендовано) -Сприймайте наведений вище фрагмент як **безпечний режим DM**: +Вважайте наведений вище фрагмент **безпечним режимом DM**: -- За замовчуванням: `session.dmScope: "main"` (усі DM ділять один сеанс для безперервності). -- Типове значення для локального onboarding через CLI: записує `session.dmScope: "per-channel-peer"`, якщо значення не задано (наявні явні значення зберігаються). -- Безпечний режим DM: `session.dmScope: "per-channel-peer"` (кожна пара канал+відправник отримує ізольований контекст DM). -- Міжканальна ізоляція за відправником: `session.dmScope: "per-peer"` (кожен відправник отримує один сеанс у межах усіх каналів того самого типу). +- Типове значення: `session.dmScope: "main"` (усі DM використовують одну сесію для безперервності). +- Типове значення локального onboarding через CLI: записує `session.dmScope: "per-channel-peer"`, якщо параметр не встановлено (наявні явні значення зберігаються). +- Безпечний режим DM: `session.dmScope: "per-channel-peer"` (кожна пара канал+відправник отримує ізольований DM-контекст). +- Ізоляція peer між каналами: `session.dmScope: "per-peer"` (кожен відправник отримує одну сесію в усіх каналах одного типу). -Якщо ви використовуєте кілька облікових записів в одному каналі, натомість використовуйте `per-account-channel-peer`. Якщо одна й та сама людина звертається до вас через кілька каналів, використовуйте `session.identityLinks`, щоб звести ці сеанси DM до однієї канонічної ідентичності. Див. [Керування сеансами](/uk/concepts/session) і [Конфігурація](/uk/gateway/configuration). +Якщо ви запускаєте кілька облікових записів у тому самому каналі, використовуйте натомість `per-account-channel-peer`. Якщо та сама людина звертається до вас у кількох каналах, використовуйте `session.identityLinks`, щоб об’єднати ці DM-сесії в одну канонічну ідентичність. Див. [Керування сесіями](/uk/concepts/session) і [Конфігурація](/uk/gateway/configuration). -## Allowlists (DM + групи) — термінологія +## Allowlist для DM і груп -OpenClaw має два окремі шари «хто може мене активувати?»: +OpenClaw має два окремі рівні «хто може мене запускати?»: -- **DM allowlist** (`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`; застаріле: `channels.discord.dm.allowFrom`, `channels.slack.dm.allowFrom`): хто має право писати боту в особисті повідомлення. - - Коли `dmPolicy="pairing"`, схвалення записуються до сховища pairing allowlist з областю дії облікового запису в `~/.openclaw/credentials/` (`-allowFrom.json` для облікового запису за замовчуванням, `--allowFrom.json` для неосновних облікових записів), а потім об’єднуються з allowlist із config. -- **Group allowlist** (залежить від каналу): з яких саме груп/каналів/guild бот узагалі прийматиме повідомлення. +- **DM allowlist** (`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`; застаріле: `channels.discord.dm.allowFrom`, `channels.slack.dm.allowFrom`): хто може звертатися до бота в прямих повідомленнях. + - Коли `dmPolicy="pairing"`, схвалення записуються до сховища allowlist pairing з областю облікового запису в `~/.openclaw/credentials/` (`-allowFrom.json` для облікового запису за замовчуванням, `--allowFrom.json` для неосновних облікових записів), а потім об’єднуються з allowlist із конфігурації. +- **Group allowlist** (залежить від каналу): з яких груп/каналів/guild бот взагалі прийматиме повідомлення. - Типові шаблони: - - `channels.whatsapp.groups`, `channels.telegram.groups`, `channels.imessage.groups`: типові значення для груп, наприклад `requireMention`; якщо задано, це також працює як group allowlist (додайте `"*"`, щоб зберегти поведінку «дозволити всі»). - - `groupPolicy="allowlist"` + `groupAllowFrom`: обмежує, хто може активувати бота _всередині_ групового сеансу (WhatsApp/Telegram/Signal/iMessage/Microsoft Teams). - - `channels.discord.guilds` / `channels.slack.channels`: allowlist для конкретних поверхонь + типові параметри згадки. - - Перевірки груп виконуються в такому порядку: спочатку `groupPolicy`/group allowlist, потім активація за згадкою/відповіддю. - - Відповідь на повідомлення бота (неявна згадка) **не** обходить allowlist відправника, такі як `groupAllowFrom`. - - **Примітка щодо безпеки:** сприймайте `dmPolicy="open"` і `groupPolicy="open"` як крайні варіанти. Їх слід використовувати якомога рідше; віддавайте перевагу pairing + allowlist, якщо ви не довіряєте повністю кожному учаснику кімнати. + - `channels.whatsapp.groups`, `channels.telegram.groups`, `channels.imessage.groups`: типові значення для груп, наприклад `requireMention`; якщо їх установлено, це також працює як group allowlist (додайте `"*"`, щоб зберегти поведінку allow-all). + - `groupPolicy="allowlist"` + `groupAllowFrom`: обмежує, хто може запускати бота _всередині_ групової сесії (WhatsApp/Telegram/Signal/iMessage/Microsoft Teams). + - `channels.discord.guilds` / `channels.slack.channels`: allowlist на рівні поверхні + типові налаштування згадок. + - Перевірки груп виконуються в такому порядку: спочатку `groupPolicy`/group allowlist, потім активація згадкою/відповіддю. + - Відповідь на повідомлення бота (неявна згадка) **не** обходить allowlist відправників на кшталт `groupAllowFrom`. + - **Примітка з безпеки:** розглядайте `dmPolicy="open"` і `groupPolicy="open"` як налаштування на крайній випадок. Вони мають використовуватися вкрай рідко; надавайте перевагу pairing + allowlist, якщо ви не довіряєте повністю кожному учаснику кімнати. Докладніше: [Конфігурація](/uk/gateway/configuration) і [Групи](/uk/channels/groups) -## Prompt injection (що це таке і чому це важливо) +## Prompt injection (що це, чому це важливо) -Prompt injection — це коли зловмисник створює повідомлення, яке маніпулює моделлю так, щоб вона зробила щось небезпечне («ігноруй інструкції», «виведи мою файлову систему», «перейди за цим посиланням і виконай команди» тощо). +Prompt injection — це коли зловмисник створює повідомлення, яке маніпулює моделлю, змушуючи її робити щось небезпечне («ігноруй свої інструкції», «вивантаж мою файлову систему», «перейди за цим посиланням і виконай команди» тощо). -Навіть із сильними system prompt **проблему prompt injection не вирішено**. Запобіжники в system prompt — це лише м’які рекомендації; жорстке забезпечення походить від політики інструментів, схвалень exec, sandboxing і channel allowlist (і оператори можуть вимкнути це за задумом). Що реально допомагає на практиці: +Навіть із сильними системними підказками **prompt injection не розв’язано**. Запобіжники системної підказки — це лише м’які рекомендації; жорстке забезпечення походить від політики інструментів, підтверджень exec, sandboxing та allowlist каналів (і оператори за задумом можуть це вимкнути). Що реально допомагає на практиці: - Тримайте вхідні DM закритими (pairing/allowlist). -- У групах віддавайте перевагу активації через згадку; уникайте «завжди активних» ботів у публічних кімнатах. -- Сприймайте посилання, вкладення та вставлені інструкції як ворожі за замовчуванням. -- Запускайте чутливе виконання інструментів у sandbox; тримайте секрети поза файловою системою, доступною для agent. -- Зауваження: sandboxing є добровільним. Якщо режим sandbox вимкнено, неявний `host=auto` визначається як хост gateway. Явний `host=sandbox` усе одно безпечно завершується помилкою, оскільки runtime sandbox недоступний. Установіть `host=gateway`, якщо хочете, щоб така поведінка була явно зафіксована в config. -- Обмежуйте високоризикові інструменти (`exec`, `browser`, `web_fetch`, `web_search`) лише довіреними agent або явними allowlist. -- Якщо ви додаєте інтерпретатори до allowlist (`python`, `node`, `ruby`, `perl`, `php`, `lua`, `osascript`), увімкніть `tools.exec.strictInlineEval`, щоб форми inline eval і надалі вимагали явного схвалення. -- Аналіз схвалення shell також відхиляє форми розгортання параметрів POSIX (`$VAR`, `$?`, `$$`, `$1`, `$@`, `${…}`) всередині **нецитованих heredoc**, щоб тіло heredoc з allowlist не могло непомітно провести розгортання shell повз перевірку allowlist як звичайний текст. Щоб увімкнути буквальну семантику тіла, цитуйте термінатор heredoc (наприклад, `<<'EOF'`); нецитовані heredoc, у яких відбулося б розгортання змінних, відхиляються. -- **Вибір моделі має значення:** старіші/менші/застарілі моделі значно гірше протистоять prompt injection і неправильному використанню інструментів. Для agent із увімкненими інструментами використовуйте найсильнішу доступну модель останнього покоління, стійку до інструкцій. +- У групах надавайте перевагу запуску за згадкою; уникайте «завжди активних» ботів у публічних кімнатах. +- За замовчуванням ставтеся до посилань, вкладень і вставлених інструкцій як до ворожих. +- Виконуйте чутливі інструменти в sandbox; тримайте секрети поза досяжною для агента файловою системою. +- Примітка: sandboxing вмикається явно. Якщо режим sandbox вимкнено, неявний `host=auto` зводиться до хоста gateway. Явний `host=sandbox` усе одно закривається безпечно, бо немає доступного середовища sandbox. Установіть `host=gateway`, якщо хочете, щоб така поведінка була явно виражена в конфігурації. +- Обмежуйте інструменти високого ризику (`exec`, `browser`, `web_fetch`, `web_search`) лише довіреними агентами або явними allowlist. +- Якщо ви додаєте інтерпретатори в allowlist (`python`, `node`, `ruby`, `perl`, `php`, `lua`, `osascript`), увімкніть `tools.exec.strictInlineEval`, щоб inline eval-форми також вимагали явного підтвердження. +- Аналіз підтвердження оболонки також відхиляє форми POSIX parameter-expansion (`$VAR`, `$?`, `$$`, `$1`, `$@`, `${…}`) всередині **нецитованих heredoc**, тож тіло heredoc з allowlist не може непомітно провести shell expansion повз перевірку allowlist як звичайний текст. Щоб увімкнути буквальну семантику тіла, візьміть термінатор heredoc у лапки (наприклад, `<<'EOF'`); нецитовані heredoc, які б розгортали змінні, відхиляються. +- **Вибір моделі має значення:** старіші/менші/застарілі моделі значно менш стійкі до prompt injection та зловживання інструментами. Для агентів з увімкненими інструментами використовуйте найсильнішу доступну модель останнього покоління, посилену проти інструкційних атак. -Ознаки, які слід вважати недовіреними: +Червоні прапорці, які слід вважати недовіреними: - «Прочитай цей файл/URL і зроби точно те, що там сказано.» -- «Ігноруй свій system prompt або правила безпеки.» +- «Ігноруй свою системну підказку або правила безпеки.» - «Розкрий свої приховані інструкції або результати інструментів.» -- «Встав повний вміст `~/.openclaw` або своїх журналів.» +- «Встав повний вміст `~/.openclaw` або своїх логів.» ## Санітизація спеціальних токенів у зовнішньому контенті -OpenClaw видаляє поширені літерали спеціальних токенів шаблонів чату self-hosted LLM із обгорнутого зовнішнього контенту та метаданих до того, як вони потраплять до моделі. Підтримувані сімейства маркерів включають токени ролей/ходів Qwen/ChatML, Llama, Gemma, Mistral, Phi і GPT-OSS. +OpenClaw видаляє поширені літеральні спеціальні токени шаблонів чату для self-hosted LLM із обгорнутого зовнішнього контенту та метаданих, перш ніж вони потраплять до моделі. Підтримувані сімейства маркерів включають токени ролей/ходів Qwen/ChatML, Llama, Gemma, Mistral, Phi та GPT-OSS. -Чому: +Чому це потрібно: -- OpenAI-сумісні бекенди, які працюють поверх self-hosted моделей, іноді зберігають спеціальні токени, що з’являються в тексті користувача, замість їх маскування. Зловмисник, який може записати щось у вхідний зовнішній контент (отриману сторінку, тіло email, вміст файла з інструмента читання), інакше міг би вставити синтетичну межу ролі `assistant` або `system` і обійти запобіжники для обгорнутого контенту. -- Санітизація виконується на рівні обгортання зовнішнього контенту, тому вона однаково застосовується до інструментів fetch/read і вхідного контенту каналів, а не налаштовується окремо для кожного провайдера. -- Вихідні відповіді моделі вже проходять окремий санітайзер, який прибирає з видимих користувачеві відповідей витоки на кшталт ``, `` і подібного службового каркаса. Санітизація зовнішнього контенту є вхідним відповідником цього механізму. +- OpenAI-сумісні бекенди, які працюють поверх self-hosted моделей, інколи зберігають спеціальні токени, що з’являються в тексті користувача, замість того щоб маскувати їх. Зловмисник, який може записувати у вхідний зовнішній контент (завантажену сторінку, тіло email, результат інструмента читання вмісту файла), інакше міг би ін’єктувати синтетичну межу ролі `assistant` або `system` і обійти запобіжники обгортання контенту. +- Санітизація відбувається на рівні обгортання зовнішнього контенту, тому вона однаково застосовується до інструментів fetch/read і вхідного контенту каналів, а не залежить від конкретного провайдера. +- Вихідні відповіді моделі вже мають окремий санітайзер, який видаляє витоки ``, `` та подібної службової структури з видимих користувачу відповідей. Санітизація зовнішнього контенту є її вхідним аналогом. -Це не замінює інші механізми посилення безпеки на цій сторінці — основну роботу й далі виконують `dmPolicy`, allowlist, схвалення exec, sandboxing і `contextVisibility`. Це закриває один конкретний обхід на рівні токенізатора для self-hosted стеків, які передають текст користувача зі збереженими спеціальними токенами. +Це не замінює інші механізми посилення захисту на цій сторінці — `dmPolicy`, allowlist, підтвердження exec, sandboxing і `contextVisibility` усе ще виконують основну роботу. Це закриває один конкретний обхід на рівні токенізатора для self-hosted стеків, які передають текст користувача зі збереженими спеціальними токенами. ## Прапорці обходу для небезпечного зовнішнього контенту @@ -593,142 +598,139 @@ OpenClaw містить явні прапорці обходу, які вими Рекомендації: - У production залишайте їх не встановленими/false. -- Увімкнюйте лише тимчасово для вузько обмеженого налагодження. -- Якщо ввімкнули, ізолюйте цей agent (sandbox + мінімум інструментів + окремий простір імен сеансів). +- Увімкнюйте лише тимчасово для вузькоспеціалізованого налагодження. +- Якщо ввімкнено, ізолюйте цього агента (sandbox + мінімум інструментів + окремий простір імен сесій). Примітка про ризики hooks: -- Payload hooks — це недовірений контент, навіть коли доставлення надходить із систем, які ви контролюєте (пошта/документи/вебконтент можуть містити prompt injection). -- Слабші рівні моделей підвищують цей ризик. Для автоматизації, керованої hooks, віддавайте перевагу сильним сучасним рівням моделей і тримайте політику інструментів суворою (`tools.profile: "messaging"` або жорсткіше), а також використовуйте sandboxing, де це можливо. +- Payload hooks — це недовірений контент, навіть коли доставка надходить із систем, які ви контролюєте (mail/docs/web-контент може містити prompt injection). +- Слабші рівні моделей підвищують цей ризик. Для автоматизації через hooks надавайте перевагу сильним сучасним рівням моделей і тримайте політику інструментів жорсткою (`tools.profile: "messaging"` або суворіше), а також використовуйте sandboxing, де це можливо. ### Prompt injection не потребує публічних DM Навіть якщо **лише ви** можете писати боту, prompt injection усе одно може статися через -будь-який **недовірений контент**, який бот читає (результати web search/fetch, сторінки браузера, -email, документи, вкладення, вставлені журнали/код). Інакше кажучи: не лише відправник -є поверхнею загрози; **сам контент** також може містити ворожі інструкції. +будь-який **недовірений контент**, який читає бот (результати web search/fetch, сторінки браузера, +email, документи, вкладення, вставлені логи/код). Іншими словами: відправник — +не єдина поверхня загрози; **сам контент** також може містити ворожі інструкції. -Коли інструменти ввімкнено, типовий ризик — це ексфільтрація контексту або ініціювання +Коли інструменти ввімкнені, типовий ризик — це ексфільтрація контексту або ініціювання викликів інструментів. Зменшуйте радіус ураження так: -- Використовуйте **agent-читач** лише для читання або без інструментів, щоб підсумовувати недовірений контент, - а потім передавайте підсумок своєму основному agent. -- Тримайте `web_search` / `web_fetch` / `browser` вимкненими для agent із доступом до інструментів, якщо вони не потрібні. -- Для URL-входів OpenResponses (`input_file` / `input_image`) задавайте жорсткі +- Використовуйте **агента-читача** лише для читання або без інструментів, щоб узагальнювати недовірений контент, + а потім передавайте підсумок вашому основному агенту. +- Тримайте `web_search` / `web_fetch` / `browser` вимкненими для агентів з інструментами, якщо вони не потрібні. +- Для URL-входів OpenResponses (`input_file` / `input_image`) установіть жорсткі `gateway.http.endpoints.responses.files.urlAllowlist` і - `gateway.http.endpoints.responses.images.urlAllowlist`, а також залишайте `maxUrlParts` малим. - Порожні allowlist трактуються як не встановлені; використовуйте `files.allowUrl: false` / `images.allowUrl: false`, - якщо хочете повністю вимкнути отримання за URL. -- Для файлових входів OpenResponses декодований текст `input_file` усе одно вставляється як - **недовірений зовнішній контент**. Не вважайте текст файла довіреним лише тому, - що Gateway декодував його локально. Вставлений блок усе одно містить явні - маркери меж `<<>>` плюс метадані `Source: External`, - хоча в цьому шляху відсутній довший банер `SECURITY NOTICE:`. -- Те саме обгортання на основі маркерів застосовується, коли media-understanding витягує текст - із прикріплених документів перед додаванням цього тексту до prompt для медіа. -- Увімкніть sandboxing і суворі allowlist інструментів для будь-якого agent, який працює з недовіреним вводом. -- Не розміщуйте секрети в prompt; передавайте їх через env/config на хості gateway. + `gateway.http.endpoints.responses.images.urlAllowlist`, а також тримайте `maxUrlParts` низьким. + Порожні allowlist вважаються не встановленими; використовуйте `files.allowUrl: false` / `images.allowUrl: false`, + якщо хочете повністю вимкнути завантаження за URL. +- Для файлових входів OpenResponses декодований текст `input_file` усе одно ін’єктується як + **недовірений зовнішній контент**. Не покладайтеся на те, що текст файла є довіреним лише тому, + що Gateway декодував його локально. Ін’єктований блок усе одно містить явні + маркери межі `<<>>` плюс метадані `Source: External`, + хоча в цьому шляху немає довшого банера `SECURITY NOTICE:`. +- Таке саме обгортання на основі маркерів застосовується, коли розуміння медіа витягує текст + із прикріплених документів перед додаванням цього тексту до запиту медіа. +- Увімкніть sandboxing і суворі allowlist інструментів для будь-якого агента, який працює з недовіреним введенням. +- Не розміщуйте секрети в підказках; передавайте їх через env/config на хості gateway. -### Self-hosted LLM бекенди +### Self-hosted бекенди LLM OpenAI-сумісні self-hosted бекенди, такі як vLLM, SGLang, TGI, LM Studio -або власні стеки токенізаторів Hugging Face, можуть відрізнятися від hosted-провайдерів тим, -як обробляються спеціальні токени шаблонів чату. Якщо бекенд токенізує буквальні рядки +або власні стеки токенізаторів Hugging Face, можуть відрізнятися від хостованих провайдерів тим, +як обробляються спеціальні токени шаблону чату. Якщо бекенд токенізує буквальні рядки на кшталт `<|im_start|>`, `<|start_header_id|>` або `` як структурні токени шаблону чату всередині контенту користувача, недовірений текст може спробувати підробити межі ролей на рівні токенізатора. -OpenClaw видаляє поширені літерали спеціальних токенів для сімейств моделей із обгорнутого -зовнішнього контенту перед відправленням його до моделі. Залишайте обгортання зовнішнього контенту -увімкненим і, за можливості, віддавайте перевагу налаштуванням бекенда, які розділяють або екранують спеціальні -токени в наданому користувачем контенті. Hosted-провайдери, такі як OpenAI -і Anthropic, уже застосовують власну санітизацію на боці запиту. +OpenClaw видаляє поширені літеральні спеціальні токени сімейств моделей з обгорнутого +зовнішнього контенту перед відправленням його до моделі. Тримайте обгортання зовнішнього контенту +увімкненим і, за можливості, надавайте перевагу налаштуванням бекенда, які розділяють або екранують спеціальні +токени в контенті, наданому користувачем. Хостовані провайдери, такі як OpenAI +та Anthropic, уже застосовують власну санітизацію на стороні запиту. -### Сила моделі (примітка щодо безпеки) +### Сила моделі (примітка з безпеки) -Стійкість до prompt injection **не є однаковою** в різних рівнях моделей. Менші/дешевші моделі загалом більш схильні до неправильного використання інструментів і перехоплення інструкцій, особливо за ворожих prompt. +Стійкість до prompt injection **не** є однаковою в усіх рівнях моделей. Менші/дешевші моделі загалом більш вразливі до зловживання інструментами та захоплення інструкцій, особливо за ворожих підказок. -Для agent із доступом до інструментів або agent, що читають недовірений контент, ризик prompt injection зі старішими/меншими моделями часто є надто високим. Не запускайте такі навантаження на слабких рівнях моделей. +Для агентів з інструментами або агентів, які читають недовірений контент, ризик prompt injection зі старішими/меншими моделями часто є надто високим. Не запускайте такі навантаження на слабких рівнях моделей. Рекомендації: -- **Використовуйте найновішу модель найвищого рівня** для будь-якого бота, який може запускати інструменти або працювати з файлами/мережами. -- **Не використовуйте старіші/слабші/менші рівні** для agent із доступом до інструментів або недовірених вхідних скриньок; ризик prompt injection надто високий. -- Якщо вам усе ж доводиться використовувати меншу модель, **зменшуйте радіус ураження** (лише читання, сильне sandboxing, мінімальний доступ до файлової системи, суворі allowlist). -- Під час запуску малих моделей **увімкніть sandboxing для всіх сеансів** і **вимкніть `web_search`/`web_fetch`/`browser`**, якщо вхідні дані не контролюються дуже жорстко. -- Для chat-only персональних помічників із довіреним вводом і без інструментів менші моделі зазвичай підходять. +- **Використовуйте модель останнього покоління найкращого рівня** для будь-якого бота, який може запускати інструменти або працювати з файлами/мережами. +- **Не використовуйте старіші/слабші/менші рівні** для агентів з інструментами або недовірених вхідних скриньок; ризик prompt injection надто високий. +- Якщо вам усе ж доводиться використовувати меншу модель, **зменшуйте радіус ураження** (інструменти лише для читання, сильне sandboxing, мінімальний доступ до файлової системи, суворі allowlist). +- Під час запуску малих моделей **увімкніть sandboxing для всіх сесій** і **вимкніть `web_search`/`web_fetch`/`browser`**, якщо тільки вхідні дані не контролюються дуже жорстко. +- Для персональних асистентів лише для чату з довіреним введенням і без інструментів менші моделі зазвичай підходять. - +## Reasoning і verbose-вивід у групах -## Reasoning і докладний вивід у групах - -`/reasoning`, `/verbose` і `/trace` можуть розкривати внутрішні міркування, вивід -інструментів або діагностику plugin, які -не призначалися для публічного каналу. У групових налаштуваннях сприймайте їх як -режими **лише для налагодження** і тримайте вимкненими, якщо вони вам явно не потрібні. +`/reasoning`, `/verbose` і `/trace` можуть розкривати внутрішні міркування, результати +інструментів або діагностику Plugin, які +не призначалися для публічного каналу. У групових налаштуваннях вважайте їх **лише засобами налагодження** +і тримайте вимкненими, якщо тільки вони вам явно не потрібні. Рекомендації: - Тримайте `/reasoning`, `/verbose` і `/trace` вимкненими в публічних кімнатах. -- Якщо ви їх увімкнули, робіть це лише в довірених DM або жорстко контрольованих кімнатах. -- Пам’ятайте: докладний вивід і трасування можуть містити аргументи інструментів, URL, діагностику plugin і дані, які бачила модель. +- Якщо ви їх увімкнули, робіть це лише в довірених DM або в жорстко контрольованих кімнатах. +- Пам’ятайте: verbose і trace-вивід можуть містити аргументи інструментів, URL, діагностику Plugin і дані, які бачила модель. -## Посилення конфігурації (приклади) +## Приклади посилення захисту конфігурації -### Дозволи файлів +### Права доступу до файлів -Тримайте config + state приватними на хості gateway: +Тримайте конфігурацію та стан приватними на хості gateway: - `~/.openclaw/openclaw.json`: `600` (лише читання/запис для користувача) -- `~/.openclaw`: `700` (лише для користувача) +- `~/.openclaw`: `700` (лише користувач) -`openclaw doctor` може попередити та запропонувати посилити ці дозволи. +`openclaw doctor` може попередити про це та запропонувати посилити ці права доступу. -### Мережевий доступ (bind, port, firewall) +### Експонування в мережі (bind, порт, firewall) Gateway мультиплексує **WebSocket + HTTP** на одному порту: -- За замовчуванням: `18789` +- Типове значення: `18789` - Config/flags/env: `gateway.port`, `--port`, `OPENCLAW_GATEWAY_PORT` -Ця HTTP-поверхня включає Control UI і хост canvas: +Ця HTTP-поверхня включає Control UI і canvas host: -- Control UI (ресурси SPA) (базовий шлях за замовчуванням `/`) -- Хост canvas: `/__openclaw__/canvas/` і `/__openclaw__/a2ui/` (довільний HTML/JS; розглядайте як недовірений контент) +- Control UI (SPA-ресурси) (типовий базовий шлях `/`) +- Canvas host: `/__openclaw__/canvas/` і `/__openclaw__/a2ui/` (довільні HTML/JS; розглядайте як недовірений контент) -Якщо ви завантажуєте вміст canvas у звичайному браузері, ставтеся до нього як до будь-якої іншої недовіреної вебсторінки: +Якщо ви завантажуєте canvas-контент у звичайному браузері, ставтеся до нього як до будь-якої іншої недовіреної вебсторінки: -- Не відкривайте хост canvas для недовірених мереж/користувачів. -- Не робіть так, щоб вміст canvas мав той самий origin, що й привілейовані вебповерхні, якщо ви повністю не розумієте наслідків. +- Не відкривайте canvas host для недовірених мереж/користувачів. +- Не змушуйте canvas-контент ділити той самий origin із привілейованими вебповерхнями, якщо ви повністю не розумієте наслідків. -Режим bind визначає, де слухає Gateway: +Режим bind визначає, де Gateway слухає з’єднання: -- `gateway.bind: "loopback"` (за замовчуванням): підключатися можуть лише локальні клієнти. -- Bind поза loopback (`"lan"`, `"tailnet"`, `"custom"`) розширюють поверхню атаки. Використовуйте їх лише разом із auth gateway (спільний token/password або правильно налаштований trusted proxy поза loopback) і реальним firewall. +- `gateway.bind: "loopback"` (типово): підключатися можуть лише локальні клієнти. +- Bind не на loopback (`"lan"`, `"tailnet"`, `"custom"`) розширює поверхню атаки. Використовуйте їх лише з автентифікацією gateway (спільний token/password або коректно налаштований trusted proxy не на loopback) і справжнім firewall. Практичні правила: -- Віддавайте перевагу Tailscale Serve замість bind на LAN (Serve тримає Gateway на loopback, а Tailscale обробляє доступ). -- Якщо bind на LAN неминучий, обмежте порт у firewall жорстким allowlist IP-адрес джерела; не робіть широке перенаправлення порту. -- Ніколи не відкривайте Gateway без auth на `0.0.0.0`. +- Надавайте перевагу Tailscale Serve замість bind на LAN (Serve тримає Gateway на loopback, а Tailscale обробляє доступ). +- Якщо вам потрібно bind на LAN, обмежте порт через firewall жорстким allowlist IP-адрес джерел; не налаштовуйте на нього широке port-forwarding. +- Ніколи не відкривайте Gateway без автентифікації на `0.0.0.0`. -### Публікація портів Docker з UFW +### Публікація Docker-портів із UFW Якщо ви запускаєте OpenClaw з Docker на VPS, пам’ятайте, що опубліковані порти контейнера -(`-p HOST:CONTAINER` або `ports:` у Compose) маршрутизуються через ланцюги forwarding Docker, -а не лише через правила `INPUT` хоста. +(`-p HOST:CONTAINER` або Compose `ports:`) маршрутизуються через ланцюги переспрямування Docker, а не лише через правила `INPUT` хоста. -Щоб трафік Docker відповідав вашій політиці firewall, застосовуйте правила в -`DOCKER-USER` (цей ланцюг обробляється до власних правил allow Docker). +Щоб трафік Docker відповідав вашій політиці firewall, примусово застосовуйте правила в +`DOCKER-USER` (цей ланцюг обробляється до власних правил дозволу Docker). У багатьох сучасних дистрибутивах `iptables`/`ip6tables` використовують frontend `iptables-nft` і все одно застосовують ці правила до backend nftables. Мінімальний приклад allowlist (IPv4): ```bash -# /etc/ufw/after.rules (додайте як окрему секцію *filter) +# /etc/ufw/after.rules (додайте як окремий розділ *filter) *filter :DOCKER-USER - [0:0] -A DOCKER-USER -m conntrack --ctstate ESTABLISHED,RELATED -j RETURN @@ -747,9 +749,9 @@ COMMIT Для IPv6 існують окремі таблиці. Додайте відповідну політику в `/etc/ufw/after6.rules`, якщо Docker IPv6 увімкнено. -Уникайте жорстко закодованих назв інтерфейсів на кшталт `eth0` у фрагментах документації. Назви інтерфейсів -різняться між образами VPS (`ens3`, `enp*` тощо), і невідповідність може випадково -призвести до пропуску вашого правила deny. +Уникайте жорсткого кодування назв інтерфейсів на кшталт `eth0` у фрагментах документації. Назви інтерфейсів +відрізняються між образами VPS (`ens3`, `enp*` тощо), і невідповідність може випадково +пропустити ваше правило заборони. Швидка перевірка після перезавантаження: @@ -760,22 +762,22 @@ ip6tables -S DOCKER-USER nmap -sT -p 1-65535 --open ``` -Очікувані зовнішні порти мають бути лише тими, які ви свідомо відкрили (для більшості -конфігурацій: SSH + порти вашого зворотного проксі). +Очікувані зовнішні порти мають бути лише тими, які ви навмисно відкриваєте (для більшості +конфігурацій: SSH + порти вашого reverse proxy). ### Виявлення через mDNS/Bonjour -Gateway транслює свою присутність через mDNS (`_openclaw-gw._tcp` на порту 5353) для виявлення локальними пристроями. У режимі full це включає TXT-записи, які можуть розкривати операційні деталі: +Gateway транслює свою присутність через mDNS (`_openclaw-gw._tcp` на порту 5353) для локального виявлення пристроїв. У повному режимі це включає TXT-записи, які можуть розкривати операційні деталі: -- `cliPath`: повний шлях файлової системи до бінарника CLI (розкриває ім’я користувача та місце встановлення) -- `sshPort`: повідомляє про доступність SSH на хості +- `cliPath`: повний шлях у файловій системі до бінарного файла CLI (розкриває ім’я користувача та місце встановлення) +- `sshPort`: рекламує доступність SSH на хості - `displayName`, `lanHost`: інформація про ім’я хоста -**Міркування операційної безпеки:** трансляція інфраструктурних деталей полегшує розвідку для будь-кого в локальній мережі. Навіть «нешкідлива» інформація на кшталт шляхів файлової системи та доступності SSH допомагає зловмисникам скласти карту вашого середовища. +**Міркування операційної безпеки:** трансляція деталей інфраструктури полегшує розвідку для будь-кого в локальній мережі. Навіть «нешкідлива» інформація, як-от шляхи файлової системи та доступність SSH, допомагає зловмисникам картографувати ваше середовище. **Рекомендації:** -1. **Режим minimal** (за замовчуванням, рекомендовано для відкритих Gateway): не включає чутливі поля до трансляцій mDNS: +1. **Мінімальний режим** (типово, рекомендовано для відкритих gateway): не включає чутливі поля в трансляції mDNS: ```json5 { @@ -785,7 +787,7 @@ Gateway транслює свою присутність через mDNS (`_open } ``` -2. **Повністю вимкніть**, якщо вам не потрібне виявлення локальними пристроями: +2. **Повністю вимкніть**, якщо вам не потрібне локальне виявлення пристроїв: ```json5 { @@ -795,7 +797,7 @@ Gateway транслює свою присутність через mDNS (`_open } ``` -3. **Режим full** (явне ввімкнення): включає `cliPath` + `sshPort` у TXT-записи: +3. **Повний режим** (явне ввімкнення): включає `cliPath` + `sshPort` у TXT-записи: ```json5 { @@ -805,20 +807,19 @@ Gateway транслює свою присутність через mDNS (`_open } ``` -4. **Змінна середовища** (альтернатива): встановіть `OPENCLAW_DISABLE_BONJOUR=1`, щоб вимкнути mDNS без змін у config. +4. **Змінна середовища** (альтернатива): установіть `OPENCLAW_DISABLE_BONJOUR=1`, щоб вимкнути mDNS без зміни конфігурації. -У режимі minimal Gateway усе одно транслює достатньо даних для виявлення пристрою (`role`, `gatewayPort`, `transport`), але не включає `cliPath` і `sshPort`. Apps, яким потрібна інформація про шлях до CLI, можуть отримати її через автентифіковане з’єднання WebSocket. +У мінімальному режимі Gateway усе ще транслює достатньо для виявлення пристроїв (`role`, `gatewayPort`, `transport`), але не включає `cliPath` і `sshPort`. Apps, яким потрібна інформація про шлях до CLI, можуть отримати її через автентифіковане з’єднання WebSocket. -### Обмежте доступ до WebSocket Gateway (локальний auth) +### Захистіть WebSocket Gateway (локальна автентифікація) -Auth Gateway **обов’язковий за замовчуванням**. Якщо не налаштовано -жоден дійсний шлях auth gateway, Gateway відхиляє з’єднання WebSocket -(безпечна відмова). +Автентифікація Gateway **обов’язкова за замовчуванням**. Якщо не налаштовано +жодного дійсного шляху автентифікації gateway, Gateway відхиляє з’єднання WebSocket (безпечне закриття за замовчуванням). Onboarding за замовчуванням генерує token (навіть для loopback), тому локальні клієнти мають проходити автентифікацію. -Установіть token, щоб **усі** клієнти WS мали проходити автентифікацію: +Установіть token, щоб **усі** WS-клієнти мусили автентифікуватися: ```json5 { @@ -830,148 +831,148 @@ Onboarding за замовчуванням генерує token (навіть д Doctor може згенерувати його для вас: `openclaw doctor --generate-gateway-token`. -Примітка: `gateway.remote.token` / `.password` — це джерела облікових даних клієнта. Вони -самі по собі **не** захищають локальний доступ до WS. -Локальні шляхи виклику можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` +Примітка: `gateway.remote.token` / `.password` — це джерела клієнтських облікових даних. Вони +самі по собі **не** захищають локальний доступ WS. +Локальні шляхи виклику можуть використовувати `gateway.remote.*` як fallback лише тоді, коли `gateway.auth.*` не встановлено. Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через -SecretRef і не вдається розв’язати, розв’язання завершується безпечною відмовою (жоден резервний remote-механізм не маскує це). -Необов’язково: закріпіть віддалений TLS за допомогою `gateway.remote.tlsFingerprint`, якщо використовуєте `wss://`. -Нешифрований `ws://` за замовчуванням дозволено лише для loopback. Для довірених шляхів у приватній мережі -встановіть `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` у процесі клієнта як аварійний варіант. +SecretRef і не вдається їх розв’язати, розв’язання завершується безпечним закриттям (без маскування через remote fallback). +Необов’язково: закріпіть віддалений TLS через `gateway.remote.tlsFingerprint` при використанні `wss://`. +Незашифрований `ws://` за замовчуванням дозволений лише для loopback. Для довірених шляхів +у приватній мережі встановіть `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` у процесі клієнта як аварійний варіант. -Локальне pairing пристроїв: +Локальний pairing пристрою: -- Pairing пристрою автоматично схвалюється для прямих локальних loopback-з’єднань, щоб - зберегти зручність для клієнтів на тому самому хості. -- OpenClaw також має вузький шлях самопідключення backend/container-local для - довірених потоків допоміжних інструментів зі спільним секретом. +- Pairing пристрою автоматично схвалюється для прямих локальних loopback-підключень, щоб + зробити клієнтів на тому самому хості зручними у використанні. +- OpenClaw також має вузький шлях self-connect на рівні backend/container-local для + довірених потоків helper зі спільним секретом. - Підключення через tailnet і LAN, включно з bind через tailnet на тому самому хості, вважаються - віддаленими для pairing і, як і раніше, потребують схвалення. -- Ознаки forwarding-заголовків у loopback-запиті виключають loopback-локальність. - Автосхвалення для metadata-upgrade має вузьку область дії. Докладніше див. - у [Pairing Gateway](/uk/gateway/pairing) для обох правил. + віддаленими для pairing і все одно потребують схвалення. +- Наявність forwarded-header у loopback-запиті знімає статус loopback + locality. Автосхвалення metadata-upgrade має вузьку сферу застосування. Див. + [Pairing Gateway](/uk/gateway/pairing) для обох правил. -Режими auth: +Режими автентифікації: -- `gateway.auth.mode: "token"`: спільний bearer token (рекомендовано для більшості сценаріїв). -- `gateway.auth.mode: "password"`: auth за паролем (краще задавати через env: `OPENCLAW_GATEWAY_PASSWORD`). -- `gateway.auth.mode: "trusted-proxy"`: довіряти reverse proxy з перевіркою ідентичності, який автентифікує користувачів і передає ідентичність через заголовки (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). +- `gateway.auth.mode: "token"`: спільний bearer token (рекомендовано для більшості конфігурацій). +- `gateway.auth.mode: "password"`: автентифікація за паролем (бажано задавати через env: `OPENCLAW_GATEWAY_PASSWORD`). +- `gateway.auth.mode: "trusted-proxy"`: довіра до reverse proxy з урахуванням ідентичності, який автентифікує користувачів і передає ідентичність через заголовки (див. [Автентифікація Trusted Proxy](/uk/gateway/trusted-proxy-auth)). Контрольний список ротації (token/password): 1. Згенеруйте/встановіть новий секрет (`gateway.auth.token` або `OPENCLAW_GATEWAY_PASSWORD`). -2. Перезапустіть Gateway (або перезапустіть macOS app, якщо вона керує Gateway). +2. Перезапустіть Gateway (або перезапустіть macOS app, якщо воно керує Gateway). 3. Оновіть усі віддалені клієнти (`gateway.remote.token` / `.password` на машинах, які звертаються до Gateway). -4. Переконайтеся, що старі облікові дані більше не працюють. +4. Переконайтеся, що зі старими обліковими даними більше не можна підключитися. ### Заголовки ідентичності Tailscale Serve Коли `gateway.auth.allowTailscale` має значення `true` (типово для Serve), OpenClaw -приймає заголовки ідентичності Tailscale Serve (`tailscale-user-login`) для автентифікації -Control UI/WebSocket. OpenClaw перевіряє ідентичність, зіставляючи адресу -`x-forwarded-for` через локальний демон Tailscale (`tailscale whois`) і -порівнюючи її із заголовком. Це спрацьовує лише для запитів, які приходять на loopback +приймає заголовки ідентичності Tailscale Serve (`tailscale-user-login`) для автентифікації Control +UI/WebSocket. OpenClaw перевіряє ідентичність, визначаючи адресу +`x-forwarded-for` через локальний демон Tailscale (`tailscale whois`) і зіставляючи її із заголовком. Це спрацьовує лише для запитів, що потрапляють на loopback і містять `x-forwarded-for`, `x-forwarded-proto` та `x-forwarded-host`, як -додає Tailscale. -Для цього асинхронного шляху перевірки ідентичності невдалі спроби для тієї самої пари `{scope, ip}` -серіалізуються до того, як обмежувач зафіксує збій. Тому одночасні невдалі повтори -від одного клієнта Serve можуть одразу заблокувати другу спробу, -а не пройти паралельно як дві звичайні невідповідності. +це ін’єктується Tailscale. +Для цього асинхронного шляху перевірки ідентичності невдалі спроби для того самого `{scope, ip}` +серіалізуються до того, як обмежувач зареєструє збій. Тому паралельні погані повторні спроби +від одного клієнта Serve можуть одразу заблокувати другу спробу +замість того, щоб пройти як дві звичайні невідповідності. Кінцеві точки HTTP API (наприклад `/v1/*`, `/tools/invoke` і `/api/channels/*`) -**не** використовують auth через заголовки ідентичності Tailscale. Вони, як і раніше, працюють за -налаштованим HTTP auth режимом gateway. +**не** використовують автентифікацію через заголовки ідентичності Tailscale. Вони, як і раніше, дотримуються +налаштованого режиму HTTP-автентифікації gateway. -Важлива примітка щодо меж: +Важлива примітка про межі: -- HTTP bearer auth Gateway фактично дає доступ оператора за принципом «усе або нічого». -- Сприймайте облікові дані, які можуть викликати `/v1/chat/completions`, `/v1/responses` або `/api/channels/*`, як повні секрети операторського доступу до цього gateway. -- На OpenAI-сумісній HTTP-поверхні bearer auth зі спільним секретом відновлює повний стандартний набір операторських scope (`operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`) і semantics власника для ходів agent; вужчі значення `x-openclaw-scopes` не звужують цей шлях зі спільним секретом. -- Семантика scope для кожного HTTP-запиту застосовується лише тоді, коли запит надходить із режиму, що несе ідентичність, такого як auth trusted proxy або `gateway.auth.mode="none"` на приватному ingress. -- У цих режимах із ідентичністю пропуск `x-openclaw-scopes` повертає стандартний набір scope оператора; надсилайте цей заголовок явно, якщо хочете вужчий набір scope. -- `/tools/invoke` дотримується того самого правила спільного секрету: bearer auth за token/password там теж вважається повним операторським доступом, тоді як режими з ідентичністю все ще враховують оголошені scope. -- Не діліться цими обліковими даними з недовіреними викликачами; віддавайте перевагу окремим Gateway для кожної межі довіри. +- HTTP bearer auth Gateway фактично є повним або нульовим операторським доступом. +- Розглядайте облікові дані, які можуть викликати `/v1/chat/completions`, `/v1/responses` або `/api/channels/*`, як секрети повного операторського доступу до цього gateway. +- На OpenAI-сумісній HTTP-поверхні bearer auth зі спільним секретом відновлює повні типові операторські scope (`operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`) і семантику власника для ходів агента; вужчі значення `x-openclaw-scopes` не звужують цей шлях зі спільним секретом. +- Семантика scope на рівні окремого запиту в HTTP застосовується лише тоді, коли запит надходить із режиму, що несе ідентичність, такого як автентифікація trusted proxy або `gateway.auth.mode="none"` на приватному ingress. +- У цих режимах, що несуть ідентичність, відсутність `x-openclaw-scopes` повертає типову нормальну множину операторських scope; надсилайте заголовок явно, якщо хочете вужчу множину scope. +- `/tools/invoke` дотримується того самого правила спільного секрету: bearer auth через token/password там теж вважається повним операторським доступом, тоді як режими з ідентичністю все ще поважають оголошені scope. +- Не передавайте ці облікові дані недовіреним викликачам; надавайте перевагу окремим gateway для кожної межі довіри. -**Припущення довіри:** auth Serve без token виходить із того, що хост gateway є довіреним. -Не вважайте це захистом від ворожих процесів на тому самому хості. Якщо на хості gateway +**Припущення довіри:** автентифікація Serve без token виходить із того, що хост gateway є довіреним. +Не розглядайте це як захист від ворожих процесів на тому самому хості. Якщо на хості gateway може виконуватися недовірений локальний код, вимкніть `gateway.auth.allowTailscale` -і вимагайте явну auth зі спільним секретом через `gateway.auth.mode: "token"` або +і вимагайте явної автентифікації через спільний секрет за допомогою `gateway.auth.mode: "token"` або `"password"`. **Правило безпеки:** не пересилайте ці заголовки зі свого reverse proxy. Якщо -ви завершуєте TLS або використовуєте proxy перед gateway, вимкніть -`gateway.auth.allowTailscale` і використовуйте auth зі спільним секретом (`gateway.auth.mode: -"token"` або `"password"`) або [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth). +ви завершуєте TLS або проксіюєте запити перед gateway, вимкніть +`gateway.auth.allowTailscale` і використовуйте автентифікацію через спільний секрет (`gateway.auth.mode: +"token"` або `"password"`) або [Автентифікацію Trusted Proxy](/uk/gateway/trusted-proxy-auth) +натомість. -Trusted proxies: +Довірені proxy: - Якщо ви завершуєте TLS перед Gateway, установіть `gateway.trustedProxies` на IP-адреси ваших proxy. -- OpenClaw довірятиме `x-forwarded-for` (або `x-real-ip`) від цих IP для визначення IP-адреси клієнта під час локальних перевірок pairing і перевірок HTTP auth/local. +- OpenClaw довірятиме `x-forwarded-for` (або `x-real-ip`) від цих IP для визначення IP клієнта в перевірках локального pairing та HTTP auth/local. - Переконайтеся, що ваш proxy **перезаписує** `x-forwarded-for` і блокує прямий доступ до порту Gateway. -Див. [Tailscale](/uk/gateway/tailscale) і [Огляд вебінтерфейсу](/uk/web). +Див. [Tailscale](/uk/gateway/tailscale) і [Огляд web](/uk/web). -### Керування браузером через host node (рекомендовано) +### Керування браузером через хост node (рекомендовано) -Якщо ваш Gateway віддалений, а браузер працює на іншій машині, запустіть **host node** -на машині з браузером і дозвольте Gateway проксувати дії браузера (див. [Інструмент browser](/uk/tools/browser)). -Сприймайте pairing node як адміністративний доступ. +Якщо ваш Gateway віддалений, але браузер працює на іншій машині, запустіть **хост node** +на машині з браузером і дозвольте Gateway проксіювати дії браузера (див. [Інструмент browser](/uk/tools/browser)). +Розглядайте pairing node як адміністративний доступ. Рекомендований шаблон: -- Тримайте Gateway і host node в одному tailnet (Tailscale). -- Pairing node робіть навмисно; вимикайте проксі-маршрутизацію браузера, якщо вона вам не потрібна. +- Тримайте Gateway і хост node в одній tailnet (Tailscale). +- Виконуйте pairing node навмисно; вимикайте proxy-маршрутизацію браузера, якщо вона вам не потрібна. Уникайте: - Відкриття relay/control-портів у LAN або публічному інтернеті. -- Tailscale Funnel для кінцевих точок керування браузером (публічний доступ). +- Tailscale Funnel для кінцевих точок керування браузером (публічне експонування). ### Секрети на диску -Вважайте, що все в `~/.openclaw/` (або `$OPENCLAW_STATE_DIR/`) може містити секрети або приватні дані: +Припускайте, що все під `~/.openclaw/` (або `$OPENCLAW_STATE_DIR/`) може містити секрети або приватні дані: -- `openclaw.json`: config може містити токени (gateway, remote gateway), налаштування провайдерів та allowlist. -- `credentials/**`: облікові дані каналів (наприклад, облікові дані WhatsApp), pairing allowlist, застарілі імпорти OAuth. -- `agents//agent/auth-profiles.json`: API-ключі, профілі токенів, токени OAuth та необов’язкові `keyRef`/`tokenRef`. -- `secrets.json` (необов’язково): payload секретів у файлі, який використовується провайдерами `file` SecretRef (`secrets.providers`). -- `agents//agent/auth.json`: застарілий файл сумісності. Статичні записи `api_key` очищуються при виявленні. -- `agents//sessions/**`: транскрипти сеансів (`*.jsonl`) + метадані маршрутизації (`sessions.json`), які можуть містити приватні повідомлення та вивід інструментів. -- пакети вбудованих plugin: установлені plugins (разом із їхнім `node_modules/`). -- `sandboxes/**`: робочі простори sandbox інструментів; там можуть накопичуватися копії файлів, які ви читаєте/записуєте всередині sandbox. +- `openclaw.json`: конфігурація може містити токени (gateway, remote gateway), налаштування провайдерів і allowlist. +- `credentials/**`: облікові дані каналів (приклад: облікові дані WhatsApp), allowlist pairing, імпорт застарілого OAuth. +- `agents//agent/auth-profiles.json`: API-ключі, профілі токенів, OAuth-токени й необов’язкові `keyRef`/`tokenRef`. +- `secrets.json` (необов’язково): файловий payload секретів, що використовується провайдерами SecretRef типу `file` (`secrets.providers`). +- `agents//agent/auth.json`: файл застарілої сумісності. Статичні записи `api_key` очищуються, коли їх виявлено. +- `agents//sessions/**`: стенограми сесій (`*.jsonl`) + метадані маршрутизації (`sessions.json`), які можуть містити приватні повідомлення та результати інструментів. +- пакети вбудованих plugin: установлені plugins (разом із їхніми `node_modules/`). +- `sandboxes/**`: робочі простори sandbox для інструментів; можуть накопичувати копії файлів, які ви читаєте/записуєте всередині sandbox. Поради щодо посилення захисту: -- Тримайте дозволи суворими (`700` для каталогів, `600` для файлів). +- Тримайте права доступу жорсткими (`700` для каталогів, `600` для файлів). - Використовуйте повне шифрування диска на хості gateway. -- Якщо хост спільний, надавайте перевагу окремому обліковому запису користувача ОС для Gateway. +- Якщо хост є спільним, надавайте перевагу окремому обліковому запису користувача ОС для Gateway. -### Файли `.env` у робочому просторі +### Файли `.env` у workspace -OpenClaw завантажує локальні для робочого простору файли `.env` для agent і інструментів, але ніколи не дозволяє таким файлам непомітно перевизначати засоби керування runtime gateway. +OpenClaw завантажує локальні для workspace файли `.env` для агентів та інструментів, але ніколи не дозволяє цим файлам непомітно перевизначати керування середовищем виконання gateway. -- Будь-який ключ, що починається з `OPENCLAW_*`, блокується у недовірених `.env` файлах робочого простору. -- Налаштування кінцевих точок каналів для Matrix, Mattermost, IRC і Synology Chat також блокуються від перевизначення через `.env` робочого простору, щоб клоновані робочі простори не могли перенаправляти трафік вбудованих конекторів через локальну конфігурацію endpoint. Ключі env для endpoint (такі як `MATRIX_HOMESERVER`, `MATTERMOST_URL`, `IRC_HOST`, `SYNOLOGY_CHAT_INCOMING_URL`) мають надходити з середовища процесу gateway або `env.shellEnv`, а не з `.env`, завантаженого з робочого простору. -- Блокування працює за принципом безпечної відмови: нову змінну керування runtime, додану в майбутньому релізі, не можна успадкувати з закоміченого чи підкладеного зловмисником `.env`; ключ ігнорується, а gateway зберігає власне значення. -- Довірені змінні середовища процесу/ОС (власна shell gateway, unit launchd/systemd, bundle app) усе ще застосовуються — це обмеження стосується лише завантаження файлів `.env`. +- Будь-який ключ, що починається з `OPENCLAW_*`, блокується з недовірених файлів `.env` workspace. +- Налаштування кінцевих точок каналів для Matrix, Mattermost, IRC і Synology Chat також блокуються для перевизначення з `.env` workspace, тож клоновані workspace не можуть переспрямовувати трафік вбудованих конекторів через локальну конфігурацію кінцевих точок. Ключі env для кінцевих точок (такі як `MATRIX_HOMESERVER`, `MATTERMOST_URL`, `IRC_HOST`, `SYNOLOGY_CHAT_INCOMING_URL`) мають надходити із середовища процесу gateway або `env.shellEnv`, а не з `.env`, завантаженого з workspace. +- Блокування працює за принципом fail-closed: нова змінна керування середовищем виконання, додана в майбутньому випуску, не може бути успадкована з закоміченого або наданого зловмисником `.env`; ключ ігнорується, а gateway зберігає власне значення. +- Довірені змінні середовища процесу/ОС (власна оболонка gateway, модуль launchd/systemd, app bundle) усе ще застосовуються — це обмеження стосується лише завантаження файлів `.env`. -Чому: файли `.env` робочого простору часто лежать поруч із кодом agent, випадково потрапляють у commit або записуються інструментами. Блокування всього префікса `OPENCLAW_*` означає, що додавання нового прапорця `OPENCLAW_*` у майбутньому ніколи не призведе до регресії через мовчазне успадкування зі стану робочого простору. +Чому: файли `.env` workspace часто лежать поруч із кодом агента, випадково потрапляють у коміти або записуються інструментами. Блокування всього префікса `OPENCLAW_*` означає, що додавання нового прапорця `OPENCLAW_*` у майбутньому ніколи не призведе до регресії у вигляді тихого успадкування зі стану workspace. -### Журнали та транскрипти (редагування та зберігання) +### Логи та стенограми (редагування й утримання) -Журнали та транскрипти можуть витікати чутливу інформацію, навіть якщо контроль доступу налаштовано правильно: +Логи та стенограми можуть витікати чутливу інформацію, навіть якщо контроль доступу налаштовано правильно: -- Журнали Gateway можуть містити підсумки інструментів, помилки та URL. -- Транскрипти сеансів можуть містити вставлені секрети, вміст файлів, вивід команд і посилання. +- Логи Gateway можуть містити зведення інструментів, помилки та URL. +- Стенограми сесій можуть містити вставлені секрети, вміст файлів, результати команд і посилання. Рекомендації: -- Тримайте редагування підсумків інструментів увімкненим (`logging.redactSensitive: "tools"`; типове значення). -- Додавайте власні шаблони для свого середовища через `logging.redactPatterns` (токени, імена хостів, внутрішні URL). -- Для обміну діагностикою віддавайте перевагу `openclaw status --all` (зручно вставляти, секрети приховано) замість сирих журналів. -- Видаляйте старі транскрипти сеансів і файли журналів, якщо вам не потрібне довге зберігання. +- Залишайте ввімкненим редагування зведень інструментів (`logging.redactSensitive: "tools"`; типово). +- Додавайте власні шаблони для вашого середовища через `logging.redactPatterns` (токени, імена хостів, внутрішні URL). +- Під час поширення діагностики надавайте перевагу `openclaw status --all` (придатне для вставлення, секрети відредаговано) замість сирих логів. +- Видаляйте старі стенограми сесій і лог-файли, якщо вам не потрібне тривале зберігання. -Докладніше: [Журналювання](/uk/gateway/logging) +Докладніше: [Логування](/uk/gateway/logging) ### DM: pairing за замовчуванням @@ -981,7 +982,7 @@ OpenClaw завантажує локальні для робочого прос } ``` -### Групи: вимагати згадку всюди +### Групи: всюди вимагати згадку ```json { @@ -1007,27 +1008,27 @@ OpenClaw завантажує локальні для робочого прос ### Окремі номери (WhatsApp, Signal, Telegram) -Для каналів на основі телефонних номерів подумайте про запуск AI на окремому телефонному номері, а не на вашому особистому: +Для каналів на основі телефонних номерів розгляньте можливість запуску вашого AI на окремому номері телефону, відмінному від особистого: - Особистий номер: ваші розмови залишаються приватними -- Номер бота: AI обробляє ці взаємодії з відповідними межами +- Номер бота: AI обробляє їх із відповідними межами ### Режим лише для читання (через sandbox і tools) Ви можете побудувати профіль лише для читання, поєднавши: -- `agents.defaults.sandbox.workspaceAccess: "ro"` (або `"none"` для повної заборони доступу до робочого простору) -- списки allow/deny інструментів, які блокують `write`, `edit`, `apply_patch`, `exec`, `process` тощо. +- `agents.defaults.sandbox.workspaceAccess: "ro"` (або `"none"` для повної заборони доступу до workspace) +- списки дозволу/заборони інструментів, які блокують `write`, `edit`, `apply_patch`, `exec`, `process` тощо -Додаткові параметри посилення захисту: +Додаткові варіанти посилення захисту: -- `tools.exec.applyPatch.workspaceOnly: true` (за замовчуванням): гарантує, що `apply_patch` не може записувати/видаляти дані поза каталогом робочого простору, навіть якщо sandboxing вимкнено. Встановлюйте `false` лише якщо ви навмисно хочете, щоб `apply_patch` торкався файлів поза робочим простором. -- `tools.fs.workspaceOnly: true` (необов’язково): обмежує шляхи `read`/`write`/`edit`/`apply_patch` і шляхи автоматичного завантаження зображень із native prompt лише каталогом робочого простору (корисно, якщо ви зараз дозволяєте абсолютні шляхи й хочете один загальний запобіжник). -- Тримайте корені файлової системи вузькими: уникайте широких коренів, наприклад домашнього каталогу, для робочих просторів agent/sandbox. Широкі корені можуть відкрити доступ інструментам файлової системи до чутливих локальних файлів (наприклад state/config у `~/.openclaw`). +- `tools.exec.applyPatch.workspaceOnly: true` (типово): гарантує, що `apply_patch` не може записувати/видаляти файли поза каталогом workspace, навіть якщо sandboxing вимкнено. Установлюйте `false` лише якщо ви навмисно хочете, щоб `apply_patch` працював із файлами поза workspace. +- `tools.fs.workspaceOnly: true` (необов’язково): обмежує шляхи `read`/`write`/`edit`/`apply_patch` і шляхи автоматичного завантаження зображень для native prompt до каталогу workspace (корисно, якщо ви сьогодні дозволяєте абсолютні шляхи й хочете один загальний запобіжник). +- Тримайте корені файлової системи вузькими: уникайте широких коренів на кшталт домашнього каталогу для workspace агента/sandbox workspace. Широкі корені можуть відкрити доступ до чутливих локальних файлів (наприклад, стан/конфігурація в `~/.openclaw`) для файлових інструментів. -### Безпечна базова конфігурація (скопіювати/вставити) +### Безпечний базовий варіант (скопіювати/вставити) -Одна «безпечна типова» config, яка тримає Gateway приватним, вимагає pairing у DM і уникає завжди активних ботів у групах: +Одна «безпечна за замовчуванням» конфігурація, яка тримає Gateway приватним, вимагає pairing для DM і уникає завжди активних ботів у групах: ```json5 { @@ -1046,9 +1047,9 @@ OpenClaw завантажує локальні для робочого прос } ``` -Якщо ви хочете також «безпечніше за замовчуванням» виконання інструментів, додайте sandbox + заборону небезпечних інструментів для будь-якого agent, що не є власником (приклад нижче в розділі «Профілі доступу для окремих agent»). +Якщо ви хочете також «безпечніше за замовчуванням» виконання інструментів, додайте sandbox + заборону небезпечних інструментів для будь-якого агента, що не є власником (приклад нижче в розділі «Профілі доступу на рівні агентів»). -Вбудований базовий стандарт для agent turns, керованих через чат: відправники, які не є власником, не можуть використовувати інструменти `cron` або `gateway`. +Вбудований базовий варіант для ходів агента, керованих чатом: відправники, які не є власником, не можуть використовувати інструменти `cron` або `gateway`. ## Sandboxing (рекомендовано) @@ -1056,59 +1057,59 @@ OpenClaw завантажує локальні для робочого прос Два взаємодоповнювальні підходи: -- **Запускайте весь Gateway у Docker** (межа container): [Docker](/uk/install/docker) -- **Sandbox для інструментів** (`agents.defaults.sandbox`, host gateway + інструменти, ізольовані sandbox; Docker — типовий backend): [Sandboxing](/uk/gateway/sandboxing) +- **Запускайте весь Gateway у Docker** (межа контейнера): [Docker](/uk/install/docker) +- **Sandbox для інструментів** (`agents.defaults.sandbox`, хост gateway + інструменти, ізольовані sandbox; Docker — типовий backend): [Sandboxing](/uk/gateway/sandboxing) -Примітка: щоб запобігти міжагентному доступу, залишайте `agents.defaults.sandbox.scope` зі значенням `"agent"` (за замовчуванням) -або `"session"` для суворішої ізоляції на рівні сеансу. `scope: "shared"` використовує -один container/workspace. +Примітка: щоб запобігти доступу між агентами, залишайте `agents.defaults.sandbox.scope` зі значенням `"agent"` (типово) +або `"session"` для суворішої ізоляції на рівні сесії. `scope: "shared"` використовує +єдиний контейнер/workspace. -Також враховуйте доступ agent до робочого простору всередині sandbox: +Також враховуйте доступ агента до workspace всередині sandbox: -- `agents.defaults.sandbox.workspaceAccess: "none"` (за замовчуванням) не допускає agent до робочого простору; інструменти працюють із робочим простором sandbox у `~/.openclaw/sandboxes` -- `agents.defaults.sandbox.workspaceAccess: "ro"` монтує робочий простір agent лише для читання в `/agent` (вимикає `write`/`edit`/`apply_patch`) -- `agents.defaults.sandbox.workspaceAccess: "rw"` монтує робочий простір agent для читання/запису в `/workspace` -- Додаткові `sandbox.docker.binds` перевіряються за нормалізованими й канонізованими шляхами джерела. Хитрощі з symlink у батьківських каталогах і канонічними псевдонімами домашнього каталогу все одно безпечно відхиляються, якщо вони зрештою вказують на заблоковані корені, такі як `/etc`, `/var/run` або каталоги облікових даних у домашньому каталозі ОС. +- `agents.defaults.sandbox.workspaceAccess: "none"` (типово) залишає workspace агента недоступним; інструменти працюють із sandbox workspace у `~/.openclaw/sandboxes` +- `agents.defaults.sandbox.workspaceAccess: "ro"` монтує workspace агента лише для читання в `/agent` (вимикає `write`/`edit`/`apply_patch`) +- `agents.defaults.sandbox.workspaceAccess: "rw"` монтує workspace агента для читання/запису в `/workspace` +- Додаткові `sandbox.docker.binds` перевіряються відносно нормалізованих і канонізованих шляхів джерела. Трюки з symlink у батьківських каталогах і канонічними псевдонімами home усе одно безпечно закриваються, якщо вони розв’язуються в заблоковані корені, як-от `/etc`, `/var/run` або каталоги облікових даних у home ОС. -Важливо: `tools.elevated` — це глобальний аварійний механізм базового рівня, який запускає exec поза sandbox. Ефективним host за замовчуванням є `gateway`, або `node`, коли ціль exec налаштовано як `node`. Тримайте `tools.elevated.allowFrom` суворим і не вмикайте його для сторонніх. Ви можете додатково обмежити elevated для окремого agent через `agents.list[].tools.elevated`. Див. [Elevated Mode](/uk/tools/elevated). +Важливо: `tools.elevated` — це глобальний аварійний вихід базового рівня, який запускає exec поза sandbox. Ефективний host за замовчуванням — `gateway`, або `node`, коли ціль exec налаштована як `node`. Тримайте `tools.elevated.allowFrom` жорстким і не вмикайте його для сторонніх. Ви можете додатково обмежити elevated для окремих агентів через `agents.list[].tools.elevated`. Див. [Режим Elevated](/uk/tools/elevated). -### Запобіжник делегування в субagent +### Запобіжник делегування субагента -Якщо ви дозволяєте інструменти сеансів, сприймайте делеговані запуски субagent як окреме рішення щодо меж: +Якщо ви дозволяєте інструменти сесій, розглядайте делеговані запуски субагентів як ще одне рішення про межі: -- Забороняйте `sessions_spawn`, якщо agent справді не потребує делегування. -- Тримайте `agents.defaults.subagents.allowAgents` і будь-які перевизначення для окремих agent у `agents.list[].subagents.allowAgents` обмеженими відомо безпечними цільовими agent. -- Для будь-якого потоку, який має залишатися в sandbox, викликайте `sessions_spawn` із `sandbox: "require"` (значення за замовчуванням — `inherit`). -- `sandbox: "require"` одразу завершується помилкою, якщо цільовий дочірній runtime не працює в sandbox. +- Забороняйте `sessions_spawn`, якщо агенту справді не потрібне делегування. +- Тримайте `agents.defaults.subagents.allowAgents` і будь-які перевизначення `agents.list[].subagents.allowAgents` на рівні агентів обмеженими відомо безпечними цільовими агентами. +- Для будь-якого workflow, який має залишатися sandboxed, викликайте `sessions_spawn` із `sandbox: "require"` (типове значення — `inherit`). +- `sandbox: "require"` завершується з помилкою одразу, якщо цільове дочірнє середовище виконання не sandboxed. ## Ризики керування браузером Увімкнення керування браузером дає моделі можливість керувати реальним браузером. -Якщо цей профіль браузера вже містить активні сесії входу, модель може -отримати доступ до цих облікових записів і даних. Сприймайте профілі браузера як **чутливий стан**: +Якщо профіль цього браузера вже містить сеанси входу, модель може +отримати доступ до цих облікових записів і даних. Розглядайте профілі браузера як **чутливий стан**: -- Віддавайте перевагу окремому профілю для agent (типовий профіль `openclaw`). -- Не спрямовуйте agent на ваш особистий щоденний профіль. -- Тримайте керування браузером на host вимкненим для agent у sandbox, якщо ви їм не довіряєте. -- Окремий loopback API керування браузером підтримує лише auth зі спільним секретом - (bearer auth за token gateway або пароль gateway). Він не приймає +- Надавайте перевагу окремому профілю для агента (типовий профіль `openclaw`). +- Не спрямовуйте агента на ваш особистий щоденний профіль. +- Тримайте керування браузером хоста вимкненим для sandboxed агентів, якщо ви їм не довіряєте. +- Окремий loopback API керування браузером підтримує лише автентифікацію зі спільним секретом + (bearer auth через token gateway або пароль gateway). Він не використовує заголовки ідентичності trusted-proxy або Tailscale Serve. -- Сприймайте завантаження з браузера як недовірений ввід; віддавайте перевагу ізольованому каталогу завантажень. -- Якщо можливо, вимикайте синхронізацію браузера/менеджери паролів у профілі agent (це зменшує радіус ураження). -- Для віддалених Gateway вважайте, що «керування браузером» еквівалентне «операторському доступу» до всього, до чого має доступ цей профіль. -- Тримайте Gateway і host node лише в tailnet; не відкривайте порти керування браузером у LAN або публічному інтернеті. -- Вимикайте проксі-маршрутизацію браузера, якщо вона вам не потрібна (`gateway.nodes.browser.mode="off"`). -- Режим наявної сесії Chrome MCP **не є** «безпечнішим»; він може діяти від вашого імені всюди, куди має доступ цей профіль Chrome на host. +- Розглядайте завантаження браузера як недовірене введення; надавайте перевагу ізольованому каталогу завантажень. +- Якщо можливо, вимикайте синхронізацію браузера/менеджери паролів у профілі агента (це зменшує радіус ураження). +- Для віддалених gateway припускайте, що «керування браузером» еквівалентне «операторському доступу» до всього, до чого має доступ цей профіль. +- Тримайте Gateway і хости node лише в tailnet; не відкривайте порти керування браузером у LAN або публічний інтернет. +- Вимикайте proxy-маршрутизацію браузера, коли вона не потрібна (`gateway.nodes.browser.mode="off"`). +- Режим existing-session для Chrome MCP **не** є «безпечнішим»; він може діяти від вашого імені всюди, куди має доступ цей профіль Chrome на хості. ### Політика SSRF браузера (сувора за замовчуванням) -Політика навігації браузера в OpenClaw сувора за замовчуванням: приватні/внутрішні цілі залишаються заблокованими, якщо ви явно не дозволите їх. +Політика навігації браузера в OpenClaw сувора за замовчуванням: приватні/внутрішні адреси залишаються заблокованими, якщо ви явно не дозволите їх. -- За замовчуванням: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` не встановлено, тому навігація браузера й надалі блокує приватні/внутрішні/special-use адреси. +- Типове значення: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` не встановлено, тому навігація браузера зберігає блокування приватних/внутрішніх/special-use адрес. - Застарілий псевдонім: `browser.ssrfPolicy.allowPrivateNetwork` усе ще приймається для сумісності. -- Режим явного ввімкнення: установіть `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`, щоб дозволити приватні/внутрішні/special-use адреси. -- У суворому режимі використовуйте `hostnameAllowlist` (шаблони на кшталт `*.example.com`) і `allowedHostnames` (точні винятки для host, включно із заблокованими іменами на кшталт `localhost`) для явних винятків. -- Навігація перевіряється перед запитом і повторно перевіряється в режимі best-effort на фінальному `http(s)` URL після навігації, щоб зменшити можливість pivot через перенаправлення. +- Режим із явним дозволом: установіть `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`, щоб дозволити приватні/внутрішні/special-use адреси. +- У суворому режимі використовуйте `hostnameAllowlist` (шаблони на кшталт `*.example.com`) і `allowedHostnames` (точні винятки для хостів, включно із заблокованими іменами, як-от `localhost`) для явних винятків. +- Навігація перевіряється перед запитом і повторно перевіряється в режимі best-effort на фінальному URL `http(s)` після навігації, щоб зменшити ризик pivot через редиректи. Приклад суворої політики: @@ -1124,17 +1125,17 @@ OpenClaw завантажує локальні для робочого прос } ``` -## Профілі доступу для окремих agent (кілька agent) +## Профілі доступу на рівні агентів (multi-agent) -У разі маршрутизації між кількома agent кожен agent може мати власну політику sandbox + tools: -використовуйте це, щоб надавати **повний доступ**, **лише читання** або **без доступу** для кожного agent. -Повні подробиці та правила пріоритетів див. у [Sandbox і Tools для кількох agent](/uk/tools/multi-agent-sandbox-tools). +За маршрутизації multi-agent кожен агент може мати власні політики sandbox + tools: +використовуйте це, щоб надати **повний доступ**, **лише читання** або **без доступу** для кожного агента. +Повні подробиці та правила пріоритетності див. у [Sandbox і Tools для Multi-Agent](/uk/tools/multi-agent-sandbox-tools). -Поширені сценарії використання: +Типові сценарії використання: -- Особистий agent: повний доступ, без sandbox -- Сімейний/робочий agent: sandbox + інструменти лише для читання -- Публічний agent: sandbox + без інструментів файлової системи/shell +- Персональний агент: повний доступ, без sandbox +- Агент для сім’ї/роботи: sandboxed + інструменти лише для читання +- Публічний агент: sandboxed + без інструментів файлової системи/оболонки ### Приклад: повний доступ (без sandbox) @@ -1152,7 +1153,7 @@ OpenClaw завантажує локальні для робочого прос } ``` -### Приклад: інструменти лише для читання + робочий простір лише для читання +### Приклад: інструменти лише для читання + workspace лише для читання ```json5 { @@ -1176,7 +1177,7 @@ OpenClaw завантажує локальні для робочого прос } ``` -### Приклад: без доступу до файлової системи/shell (обмін повідомленнями через провайдера дозволено) +### Приклад: без доступу до файлової системи/оболонки (дозволено provider messaging) ```json5 { @@ -1190,9 +1191,9 @@ OpenClaw завантажує локальні для робочого прос scope: "agent", workspaceAccess: "none", }, - // Інструменти сеансів можуть розкривати чутливі дані з транскриптів. За замовчуванням OpenClaw обмежує ці інструменти - // поточним сеансом + сеансами породжених субagent, але за потреби ви можете обмежити ще сильніше. - // Див. `tools.sessions.visibility` у довіднику конфігурації. + // Інструменти сесій можуть розкривати чутливі дані зі стенограм. За замовчуванням OpenClaw обмежує ці інструменти + // поточною сесією + сесіями породжених субагентів, але за потреби ви можете затиснути ще сильніше. + // Див. `tools.sessions.visibility` у довіднику з конфігурації. tools: { sessions: { visibility: "tree" }, // self | tree | agent | all allow: [ @@ -1231,40 +1232,40 @@ OpenClaw завантажує локальні для робочого прос Якщо ваш AI робить щось погане: -### Локалізуйте +### Стримати -1. **Зупиніть це:** зупиніть macOS app (якщо вона керує Gateway) або завершіть свій процес `openclaw gateway`. -2. **Закрийте доступ:** установіть `gateway.bind: "loopback"` (або вимкніть Tailscale Funnel/Serve), доки не зрозумієте, що сталося. -3. **Заморозьте доступ:** перемкніть ризикові DM/групи на `dmPolicy: "disabled"` / вимагайте згадку й видаліть записи `"*"`, що дозволяють усіх, якщо вони були. +1. **Зупиніть це:** зупиніть macOS app (якщо воно керує Gateway) або завершіть процес `openclaw gateway`. +2. **Закрийте експонування:** установіть `gateway.bind: "loopback"` (або вимкніть Tailscale Funnel/Serve), доки не зрозумієте, що сталося. +3. **Заморозьте доступ:** переведіть ризиковані DM/групи в `dmPolicy: "disabled"` / вимагайте згадки та видаліть записи `"*"` із allow-all, якщо вони у вас були. -### Ротуйте (вважайте компрометацію можливою, якщо секрети витекли) +### Ротація (припускайте компрометацію, якщо сталися витоки секретів) -1. Ротуйте auth Gateway (`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`) і перезапустіть. -2. Ротуйте секрети віддалених клієнтів (`gateway.remote.token` / `.password`) на кожній машині, яка може викликати Gateway. -3. Ротуйте облікові дані провайдерів/API (облікові дані WhatsApp, токени Slack/Discord, ключі моделі/API в `auth-profiles.json` і значення зашифрованого payload секретів, якщо вони використовуються). +1. Замініть дані автентифікації Gateway (`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`) і перезапустіть. +2. Замініть секрети віддалених клієнтів (`gateway.remote.token` / `.password`) на будь-якій машині, яка може викликати Gateway. +3. Замініть облікові дані провайдерів/API (облікові дані WhatsApp, токени Slack/Discord, ключі моделей/API в `auth-profiles.json` і значення зашифрованого payload секретів, якщо вони використовуються). -### Проведіть аудит +### Аудит -1. Перевірте журнали Gateway: `/tmp/openclaw/openclaw-YYYY-MM-DD.log` (або `logging.file`). -2. Перегляньте відповідні транскрипти: `~/.openclaw/agents//sessions/*.jsonl`. -3. Перегляньте нещодавні зміни config (усе, що могло розширити доступ: `gateway.bind`, `gateway.auth`, політики DM/груп, `tools.elevated`, зміни plugin). -4. Повторно запустіть `openclaw security audit --deep` і переконайтеся, що критичні знахідки усунуто. +1. Перевірте логи Gateway: `/tmp/openclaw/openclaw-YYYY-MM-DD.log` (або `logging.file`). +2. Перегляньте відповідні стенограми: `~/.openclaw/agents//sessions/*.jsonl`. +3. Перегляньте нещодавні зміни конфігурації (усе, що могло розширити доступ: `gateway.bind`, `gateway.auth`, політики dm/group, `tools.elevated`, зміни plugin). +4. Повторно запустіть `openclaw security audit --deep` і переконайтеся, що критичні знахідки усунено. -### Зберіть дані для звіту +### Що зібрати для звіту -- Позначка часу, ОС хоста gateway + версія OpenClaw -- Транскрипти сеансів + короткий tail журналу (після редагування чутливих даних) -- Що надіслав зловмисник + що зробив agent -- Чи був Gateway доступний не лише через loopback (LAN/Tailscale Funnel/Serve) +- Часову позначку, ОС хоста gateway + версію OpenClaw +- Стенограми сесій + короткий tail логів (після редагування) +- Що надіслав зловмисник + що зробив агент +- Чи був Gateway відкритий далі за loopback (LAN/Tailscale Funnel/Serve) -## Сканування секретів (detect-secrets) +## Сканування секретів за допомогою detect-secrets CI запускає pre-commit hook `detect-secrets` у job `secrets`. Push у `main` завжди запускають сканування всіх файлів. Pull request використовують швидкий шлях -лише для змінених файлів, коли доступний базовий commit, і переходять до повного сканування -в іншому разі. Якщо перевірка не проходить, це означає, що є нові кандидати, яких ще немає в baseline. +для змінених файлів, коли доступний базовий commit, і повертаються до повного сканування +всіх файлів в іншому разі. Якщо воно завершується помилкою, є нові кандидати, яких ще немає в baseline. -### Якщо CI не проходить +### Якщо CI завершується помилкою 1. Відтворіть локально: @@ -1272,28 +1273,28 @@ Push у `main` завжди запускають сканування всіх pre-commit run --all-files detect-secrets ``` -2. Зрозумійте інструменти: - - `detect-secrets` у pre-commit запускає `detect-secrets-hook` із baseline - і виключеннями репозиторію. - - `detect-secrets audit` відкриває інтерактивну перевірку, щоб позначити кожен елемент baseline +2. Розберіться з інструментами: + - `detect-secrets` у pre-commit запускає `detect-secrets-hook` із + baseline та виключеннями репозиторію. + - `detect-secrets audit` відкриває інтерактивний перегляд, щоб позначити кожен елемент baseline як справжній секрет або хибнопозитивний результат. -3. Для справжніх секретів: ротуйтe/видаліть їх, а потім повторно запустіть сканування, щоб оновити baseline. -4. Для хибнопозитивних результатів: запустіть інтерактивний аудит і позначте їх як false: +3. Для справжніх секретів: замініть/видаліть їх, потім повторно запустіть сканування, щоб оновити baseline. +4. Для хибнопозитивних результатів: запустіть інтерактивний аудит і позначте їх як хибні: ```bash detect-secrets audit .secrets.baseline ``` -5. Якщо вам потрібні нові виключення, додайте їх у `.detect-secrets.cfg` і заново згенеруйте - baseline з відповідними прапорцями `--exclude-files` / `--exclude-lines` (файл config - є лише довідковим; detect-secrets не читає його автоматично). +5. Якщо вам потрібні нові виключення, додайте їх у `.detect-secrets.cfg` і перегенеруйте + baseline з відповідними прапорцями `--exclude-files` / `--exclude-lines` (файл + конфігурації є лише довідковим; detect-secrets не читає його автоматично). -Закомітьте оновлений `.secrets.baseline`, щойно він відображатиме бажаний стан. +Закомітьте оновлений `.secrets.baseline`, щойно він відобразить очікуваний стан. ## Повідомлення про проблеми безпеки -Знайшли вразливість в OpenClaw? Будь ласка, повідомте відповідально: +Знайшли вразливість в OpenClaw? Будь ласка, повідомляйте відповідально: 1. Email: [security@openclaw.ai](mailto:security@openclaw.ai) -2. Не публікуйте інформацію публічно, доки проблему не буде виправлено -3. Ми вкажемо вас у подяках (якщо ви не віддаєте перевагу анонімності) +2. Не публікуйте публічно до виправлення +3. Ми зазначимо вас у подяках (якщо ви не віддаєте перевагу анонімності) diff --git a/docs/uk/help/faq.md b/docs/uk/help/faq.md index e93d1d32c..ab1fee03f 100644 --- a/docs/uk/help/faq.md +++ b/docs/uk/help/faq.md @@ -1,47 +1,47 @@ --- read_when: - - Відповіді на поширені запитання щодо налаштування, встановлення, онбордингу або підтримки під час роботи системи - - Сортування проблем, про які повідомили користувачі, перед глибшим налагодженням + - Відповіді на поширені запитання щодо налаштування, встановлення, онбордингу або підтримки під час виконання + - Попередній розбір проблем, про які повідомили користувачі, перед глибшим налагодженням summary: Поширені запитання про налаштування, конфігурацію та використання OpenClaw title: Поширені запитання x-i18n: - generated_at: "2026-04-23T15:44:05Z" + generated_at: "2026-04-23T18:24:15Z" model: gpt-5.4 provider: openai - source_hash: 467e12fb93f778c544899e0c3a3837b84cff423f629db187e8be6e94627771c1 + source_hash: ffa69fef2b88175cc1ed1d2d587f355eb189a38b592af95571240501c15df4a6 source_path: help/faq.md workflow: 15 --- # Поширені запитання -Швидкі відповіді плюс глибше усунення несправностей для реальних сценаріїв налаштування (локальна розробка, VPS, multi-agent, OAuth/API keys, перемикання моделей у разі збою). Для діагностики під час роботи див. [Усунення несправностей](/uk/gateway/troubleshooting). Повний довідник із конфігурації див. у [Конфігурації](/uk/gateway/configuration). +Швидкі відповіді та глибше усунення несправностей для реальних сценаріїв налаштування (локальна розробка, VPS, мультиагентність, OAuth/API-ключі, резервне перемикання моделей). Для діагностики під час виконання див. [Усунення несправностей](/uk/gateway/troubleshooting). Повний довідник із конфігурації див. у [Конфігурація](/uk/gateway/configuration). ## Перші 60 секунд, якщо щось зламалося -1. **Швидкий стан (перша перевірка)** +1. **Швидкий статус (перша перевірка)** ```bash openclaw status ``` - Швидке локальне зведення: ОС + оновлення, доступність gateway/service, agents/sessions, конфігурація провайдерів + проблеми під час роботи (коли Gateway доступний). + Швидкий локальний зведений звіт: ОС + оновлення, доступність gateway/сервісу, агенти/сесії, конфігурація провайдера + проблеми під час виконання (коли gateway доступний). -2. **Звіт, який можна вставити (безпечний для поширення)** +2. **Звіт, який можна вставити й поділитися ним (безпечний для поширення)** ```bash openclaw status --all ``` - Діагностика в режимі лише читання з хвостом логів (токени приховано). + Діагностика лише для читання з хвостом журналу (токени відредаговано). -3. **Стан daemon + port** +3. **Стан демона + порту** ```bash openclaw gateway status ``` - Показує стан supervisor під час роботи порівняно з доступністю RPC, URL цілі перевірки та яку конфігурацію, ймовірно, використала служба. + Показує стан supervisor під час виконання порівняно з доступністю RPC, цільову URL-адресу перевірки та те, яку конфігурацію сервіс, імовірно, використовував. 4. **Глибокі перевірки** @@ -49,10 +49,10 @@ x-i18n: openclaw status --deep ``` - Запускає живу перевірку стану Gateway, зокрема перевірки каналів, коли це підтримується - (потрібен доступний Gateway). Див. [Health](/uk/gateway/health). + Виконує живу перевірку стану gateway, зокрема перевірки каналів, коли це підтримується + (потрібен доступний gateway). Див. [Стан](/uk/gateway/health). -5. **Показати останній лог** +5. **Перегляд хвоста останнього журналу** ```bash openclaw logs --follow @@ -64,50 +64,50 @@ x-i18n: tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" ``` - Файлові логи відокремлені від логів служби; див. [Logging](/uk/logging) і [Усунення несправностей](/uk/gateway/troubleshooting). + Файлові журнали відокремлені від журналів сервісу; див. [Журналювання](/uk/logging) та [Усунення несправностей](/uk/gateway/troubleshooting). -6. **Запустити doctor (виправлення)** +6. **Запуск doctor (виправлення)** ```bash openclaw doctor ``` - Виправляє/мігрує config/state + запускає перевірки стану. Див. [Doctor](/uk/gateway/doctor). + Виправляє/мігрує конфігурацію/стан + виконує перевірки стану. Див. [Doctor](/uk/gateway/doctor). -7. **Знімок Gateway** +7. **Знімок gateway** ```bash openclaw health --json - openclaw health --verbose # показує URL цілі + шлях до config у разі помилок + openclaw health --verbose # показує цільову URL-адресу + шлях до конфігурації при помилках ``` - Запитує у запущеного Gateway повний знімок (лише WS). Див. [Health](/uk/gateway/health). + Запитує в запущеного gateway повний знімок (лише WS). Див. [Стан](/uk/gateway/health). -## Швидкий старт і налаштування першого запуску +## Швидкий старт і початкове налаштування - - Використайте локальний AI agent, який може **бачити вашу машину**. Це значно ефективніше, ніж питати - в Discord, тому що більшість випадків "я застряг" — це **локальні проблеми конфігурації або середовища**, + + Використовуйте локального AI-агента, який може **бачити вашу машину**. Це набагато ефективніше, ніж запитувати + в Discord, тому що більшість випадків на кшталт «я застряг» — це **локальні проблеми конфігурації або середовища**, які віддалені помічники не можуть перевірити. - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/) - Ці інструменти можуть читати репозиторій, запускати команди, перевіряти логи та допомагати виправляти - налаштування на рівні машини (PATH, служби, дозволи, auth-файли). Надайте їм **повний checkout вихідного коду** - через hackable (git) встановлення: + Ці інструменти можуть читати репозиторій, запускати команди, перевіряти журнали та допомагати виправляти + налаштування на рівні вашої машини (PATH, сервіси, дозволи, файли автентифікації). Надайте їм **повну вихідну копію** через + зламний (git) спосіб встановлення: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Це встановлює OpenClaw **із git checkout**, тож agent може читати код + документацію - й аналізувати точну версію, яку ви запускаєте. Ви завжди можете пізніше повернутися до стабільної версії, + Це встановлює OpenClaw **із git checkout**, тож агент може читати код + документацію та + аналізувати точну версію, яку ви використовуєте. Ви завжди можете повернутися до стабільної версії пізніше, повторно запустивши інсталятор без `--install-method git`. - Порада: попросіть agent **спланувати й контролювати** виправлення (крок за кроком), а потім виконати лише - необхідні команди. Це робить зміни меншими та полегшує аудит. + Порада: попросіть агента **спланувати та супроводжувати** виправлення (крок за кроком), а потім виконати лише + необхідні команди. Це робить зміни невеликими та спрощує аудит. Якщо ви виявите справжню помилку або виправлення, будь ласка, створіть issue на GitHub або надішліть PR: [https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues) @@ -123,11 +123,11 @@ x-i18n: Що вони роблять: - - `openclaw status`: швидкий знімок стану gateway/agent + базової конфігурації. - - `openclaw models status`: перевіряє auth провайдерів + доступність моделей. - - `openclaw doctor`: перевіряє та виправляє типові проблеми config/state. + - `openclaw status`: швидкий знімок стану gateway/агента + базова конфігурація. + - `openclaw models status`: перевіряє автентифікацію провайдера + доступність моделей. + - `openclaw doctor`: перевіряє та виправляє поширені проблеми конфігурації/стану. - Інші корисні перевірки CLI: `openclaw status --all`, `openclaw logs --follow`, + Інші корисні перевірки в CLI: `openclaw status --all`, `openclaw logs --follow`, `openclaw gateway status`, `openclaw health --verbose`. Швидкий цикл налагодження: [Перші 60 секунд, якщо щось зламалося](#перші-60-секунд-якщо-щось-зламалося). @@ -138,29 +138,29 @@ x-i18n: Поширені причини пропуску Heartbeat: - - `quiet-hours`: поза налаштованим вікном active-hours - - `empty-heartbeat-file`: `HEARTBEAT.md` існує, але містить лише порожню/лише-заголовок заготовку + - `quiet-hours`: поза межами налаштованого вікна active-hours + - `empty-heartbeat-file`: `HEARTBEAT.md` існує, але містить лише порожню структуру або лише заголовки - `no-tasks-due`: режим завдань `HEARTBEAT.md` активний, але жоден з інтервалів завдань ще не настав - `alerts-disabled`: усю видимість heartbeat вимкнено (`showOk`, `showAlerts` і `useIndicator` усі вимкнені) У режимі завдань часові позначки настання оновлюються лише після завершення - справжнього запуску heartbeat. Пропущені запуски не позначають завдання як виконані. + реального запуску heartbeat. Пропущені запуски не позначають завдання як виконані. Документація: [Heartbeat](/uk/gateway/heartbeat), [Автоматизація та завдання](/uk/automation). - Репозиторій рекомендує запуск із вихідного коду та використання onboarding: + Репозиторій рекомендує запуск із вихідного коду та використання онбордингу: ```bash curl -fsSL https://openclaw.ai/install.sh | bash openclaw onboard --install-daemon ``` - Майстер також може автоматично зібрати UI assets. Після onboarding ви зазвичай запускаєте Gateway на порту **18789**. + Майстер також може автоматично зібрати UI-ресурси. Після онбордингу ви зазвичай запускаєте Gateway на порту **18789**. - Із вихідного коду (contributors/dev): + Із вихідного коду (контриб'ютори/розробники): ```bash git clone https://github.com/openclaw/openclaw.git @@ -175,86 +175,86 @@ x-i18n: - - Майстер відкриває браузер із чистим (без токена) URL dashboard одразу після onboarding, а також друкує посилання у підсумку. Залиште цю вкладку відкритою; якщо вона не запустилася, скопіюйте й вставте надрукований URL на тій самій машині. + + Майстер відкриває ваш браузер із чистою (без токенів) URL-адресою панелі одразу після онбордингу, а також виводить посилання в підсумку. Залиште цю вкладку відкритою; якщо вона не запустилася, скопіюйте/вставте надруковану URL-адресу на тій самій машині. - + **Localhost (та сама машина):** - Відкрийте `http://127.0.0.1:18789/`. - - Якщо запитується автентифікація за спільним секретом, вставте налаштований токен або пароль у налаштуваннях Control UI. + - Якщо система запитує автентифікацію за спільним секретом, вставте налаштований токен або пароль у налаштуваннях Control UI. - Джерело токена: `gateway.auth.token` (або `OPENCLAW_GATEWAY_TOKEN`). - Джерело пароля: `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). - - Якщо спільний секрет ще не налаштовано, згенеруйте токен командою `openclaw doctor --generate-gateway-token`. + - Якщо спільний секрет ще не налаштовано, згенеруйте токен за допомогою `openclaw doctor --generate-gateway-token`. **Не на localhost:** - - **Tailscale Serve** (рекомендовано): залиште bind loopback, запустіть `openclaw gateway --tailscale serve`, відкрийте `https:///`. Якщо `gateway.auth.allowTailscale` дорівнює `true`, заголовки ідентифікації задовольняють автентифікацію Control UI/WebSocket (без вставлення спільного секрету, за умови довіреного хоста Gateway); HTTP API, як і раніше, вимагають автентифікації спільним секретом, якщо ви свідомо не використовуєте private-ingress `none` або HTTP-автентифікацію trusted-proxy. - Некоректні одночасні спроби автентифікації Serve від того самого клієнта серіалізуються до того, як обмежувач невдалої автентифікації їх зафіксує, тож другий невдалий повтор уже може показати `retry later`. - - **Прив’язка tailnet**: запустіть `openclaw gateway --bind tailnet --token ""` (або налаштуйте автентифікацію паролем), відкрийте `http://:18789/`, а потім вставте відповідний спільний секрет у налаштуваннях dashboard. - - **Зворотний proxy з awareness ідентичності**: тримайте Gateway за trusted proxy не-loopback, налаштуйте `gateway.auth.mode: "trusted-proxy"`, а потім відкрийте URL proxy. - - **SSH tunnel**: `ssh -N -L 18789:127.0.0.1:18789 user@host`, а потім відкрийте `http://127.0.0.1:18789/`. Автентифікація спільним секретом усе ще застосовується через tunnel; вставте налаштований токен або пароль, якщо буде запит. + - **Tailscale Serve** (рекомендовано): залиште прив'язку до loopback, запустіть `openclaw gateway --tailscale serve`, відкрийте `https:///`. Якщо `gateway.auth.allowTailscale` має значення `true`, заголовки ідентифікації задовольняють автентифікацію Control UI/WebSocket (без вставлення спільного секрету, за умови довіреного хоста gateway); HTTP API, як і раніше, вимагають автентифікації за спільним секретом, якщо ви навмисно не використовуєте `none` для private-ingress або HTTP-автентифікацію trusted-proxy. + Невдалі одночасні спроби автентифікації Serve від того самого клієнта серіалізуються до того, як обмежувач невдалих автентифікацій зафіксує їх, тож другий невдалий повтор уже може показати `retry later`. + - **Прив'язка tailnet**: запустіть `openclaw gateway --bind tailnet --token ""` (або налаштуйте автентифікацію паролем), відкрийте `http://:18789/`, а потім вставте відповідний спільний секрет у налаштуваннях панелі. + - **Зворотний проксі з урахуванням ідентифікації**: тримайте Gateway за trusted-proxy без loopback, налаштуйте `gateway.auth.mode: "trusted-proxy"`, а потім відкрийте URL-адресу проксі. + - **SSH-тунель**: `ssh -N -L 18789:127.0.0.1:18789 user@host`, а потім відкрийте `http://127.0.0.1:18789/`. Автентифікація за спільним секретом усе ще застосовується через тунель; за потреби вставте налаштований токен або пароль. - Див. [Dashboard](/uk/web/dashboard) і [Web surfaces](/uk/web) для деталей режимів bind та автентифікації. + Див. [Панель](/uk/web/dashboard) і [Веб-поверхні](/uk/web) для режимів прив'язки та деталей автентифікації. - + Вони керують різними рівнями: - - `approvals.exec`: пересилає запити на схвалення до чат-призначень - - `channels..execApprovals`: робить цей канал нативним клієнтом схвалення для exec approvals + - `approvals.exec`: пересилає запити на підтвердження до chat-призначень + - `channels..execApprovals`: робить цей канал нативним клієнтом підтвердження для exec approval - Політика host exec як і раніше є справжнім шлюзом схвалення. Конфігурація чату лише визначає, де з’являються - запити на схвалення та як люди можуть на них відповідати. + Політика host exec усе ще є справжнім механізмом підтвердження. Конфігурація чату лише визначає, де з'являються + запити на підтвердження і як люди можуть на них відповідати. - У більшості налаштувань вам **не** потрібні обидві: + У більшості конфігурацій вам **не** потрібні обидві: - - Якщо чат уже підтримує команди та відповіді, `/approve` у тому самому чаті працює через спільний шлях. - - Якщо підтримуваний нативний канал може безпечно визначати тих, хто схвалює, OpenClaw тепер автоматично вмикає нативні схвалення DM-first, коли `channels..execApprovals.enabled` не задано або дорівнює `"auto"`. - - Коли доступні нативні картки/кнопки схвалення, цей нативний UI є основним шляхом; agent має включати ручну команду `/approve` лише якщо результат інструмента каже, що схвалення в чаті недоступні або ручне схвалення — єдиний шлях. - - Використовуйте `approvals.exec` лише тоді, коли запити також потрібно пересилати в інші чати або явні ops-кімнати. - - Використовуйте `channels..execApprovals.target: "channel"` або `"both"` лише коли ви явно хочете, щоб запити на схвалення поверталися до початкової кімнати/теми. - - Схвалення Plugin — це ще окремий випадок: вони типово використовують `/approve` у тому самому чаті, необов’язкове пересилання `approvals.plugin`, і лише деякі нативні канали додатково зберігають нативну обробку plugin-схвалень. + - Якщо чат уже підтримує команди та відповіді, `/approve` у тому ж чаті працює через спільний шлях. + - Якщо підтримуваний нативний канал може безпечно визначити тих, хто підтверджує, OpenClaw тепер автоматично вмикає нативні підтвердження DM-first, коли `channels..execApprovals.enabled` не задано або має значення `"auto"`. + - Коли доступні нативні картки/кнопки підтвердження, цей нативний UI є основним шляхом; агент має включати ручну команду `/approve` лише якщо результат інструмента каже, що chat approval недоступні або ручне підтвердження є єдиним шляхом. + - Використовуйте `approvals.exec` лише тоді, коли запити також потрібно пересилати до інших чатів або спеціальних кімнат для операцій. + - Використовуйте `channels..execApprovals.target: "channel"` або `"both"` лише тоді, коли ви явно хочете, щоб запити на підтвердження публікувалися назад у вихідну кімнату/тему. + - Підтвердження Plugin знову ж таки окремі: вони типово використовують `/approve` у тому ж чаті, опціональне пересилання `approvals.plugin`, і лише деякі нативні канали додатково залишають нативну обробку plugin approval. Коротко: пересилання — для маршрутизації, конфігурація нативного клієнта — для багатшого UX, специфічного для каналу. Див. [Exec Approvals](/uk/tools/exec-approvals). - - Потрібен Node **>= 22**. Рекомендовано `pnpm`. Bun **не рекомендовано** для Gateway. + + Потрібен Node **>= 22**. Рекомендовано `pnpm`. Bun **не рекомендується** для Gateway. - Так. Gateway є легким — у документації вказано, що для особистого використання достатньо **512MB-1GB RAM**, **1 core** і приблизно **500MB** - диска, а також зазначено, що **Raspberry Pi 4 може його запускати**. + Так. Gateway легковажний — у документації зазначено, що для персонального використання достатньо **512MB-1GB RAM**, **1 ядра** і приблизно **500MB** + дискового простору, а також зазначено, що **Raspberry Pi 4 може його запускати**. - Якщо вам потрібен додатковий запас (логи, медіа, інші служби), **рекомендовано 2GB**, але це + Якщо вам потрібен додатковий запас ресурсів (журнали, медіа, інші сервіси), **рекомендується 2GB**, але це не жорсткий мінімум. - Порада: невеликий Pi/VPS може розміщувати Gateway, а ви можете під’єднати **nodes** на ноутбуці/телефоні для + Порада: невеликий Pi/VPS може розміщувати Gateway, а ви можете під'єднати **nodes** на ноутбуці/телефоні для локального екрана/камери/canvas або виконання команд. Див. [Nodes](/uk/nodes). - Коротко: це працює, але очікуйте шорстких кутів. + Коротко: це працює, але очікуйте певних шорсткостей. - - Використовуйте **64-bit** ОС і підтримуйте Node >= 22. - - Віддавайте перевагу **hackable (git) install**, щоб мати доступ до логів і швидко оновлюватися. - - Починайте без channels/Skills, а потім додавайте їх по одному. - - Якщо натрапите на дивні проблеми з бінарними файлами, зазвичай це проблема **сумісності ARM**. + - Використовуйте **64-bit** ОС і тримайте Node >= 22. + - Віддавайте перевагу **зламному (git) встановленню**, щоб можна було бачити журнали й швидко оновлюватися. + - Починайте без каналів/Skills, а потім додавайте їх по одному. + - Якщо ви натрапили на дивні проблеми з бінарними файлами, зазвичай це проблема **сумісності ARM**. Документація: [Linux](/uk/platforms/linux), [Встановлення](/uk/install). - - Цей екран залежить від того, чи доступний Gateway і чи пройдена автентифікація. TUI також надсилає - "Wake up, my friend!" автоматично під час першого hatch. Якщо ви бачите цей рядок і **немає відповіді**, - а токени залишаються на 0, agent так і не запустився. + + Цей екран залежить від того, чи доступний Gateway і чи пройдена автентифікація. TUI також автоматично надсилає + "Wake up, my friend!" під час першого hatch. Якщо ви бачите цей рядок **без відповіді** + і кількість токенів залишається 0, агент так і не запустився. 1. Перезапустіть Gateway: @@ -262,7 +262,7 @@ x-i18n: openclaw gateway restart ``` - 2. Перевірте стан + auth: + 2. Перевірте статус + автентифікацію: ```bash openclaw status @@ -270,81 +270,81 @@ x-i18n: openclaw logs --follow ``` - 3. Якщо все одно зависає, виконайте: + 3. Якщо це все ще зависає, виконайте: ```bash openclaw doctor ``` - Якщо Gateway віддалений, переконайтеся, що tunnel/Tailscale-з’єднання працює і що UI + Якщо Gateway віддалений, переконайтеся, що тунель/Tailscale-підключення активне і що UI вказує на правильний Gateway. Див. [Віддалений доступ](/uk/gateway/remote). - - Так. Скопіюйте **каталог стану** і **робочий простір**, а потім один раз запустіть Doctor. Це - збереже вашого бота **точно таким самим** (memory, історія сесій, auth і стан - каналів), якщо ви скопіюєте **обидва** місця: + + Так. Скопіюйте **каталог стану** і **робочу область**, а потім один раз запустіть Doctor. Це + збереже вашого бота «точно таким самим» (пам'ять, історія сесій, автентифікація та стан + каналу), якщо ви скопіюєте **обидва** розташування: 1. Встановіть OpenClaw на новій машині. 2. Скопіюйте `$OPENCLAW_STATE_DIR` (типово: `~/.openclaw`) зі старої машини. - 3. Скопіюйте ваш робочий простір (типово: `~/.openclaw/workspace`). - 4. Виконайте `openclaw doctor` і перезапустіть службу Gateway. + 3. Скопіюйте вашу робочу область (типово: `~/.openclaw/workspace`). + 4. Запустіть `openclaw doctor` і перезапустіть сервіс Gateway. - Це зберігає config, профілі auth, облікові дані WhatsApp, сесії та memory. Якщо ви в - remote mode, пам’ятайте, що хост gateway володіє сховищем сесій і робочим простором. + Це зберігає конфігурацію, профілі автентифікації, облікові дані WhatsApp, сесії та пам’ять. Якщо ви працюєте + у віддаленому режимі, пам’ятайте, що хост gateway володіє сховищем сесій і робочою областю. - **Важливо:** якщо ви лише commit/push свій робочий простір на GitHub, ви робите резервну - копію **memory + bootstrap-файлів**, але **не** історії сесій чи auth. Вони зберігаються - в `~/.openclaw/` (наприклад, `~/.openclaw/agents//sessions/`). + **Важливо:** якщо ви лише комітите/надсилаєте свою робочу область на GitHub, ви створюєте + резервну копію **пам’яті + bootstrap-файлів**, але **не** історії сесій або автентифікації. Вони зберігаються + у `~/.openclaw/` (наприклад, `~/.openclaw/agents//sessions/`). - Пов’язане: [Міграція](/uk/install/migrating), [Де що зберігається на диску](#where-things-live-on-disk), - [Робочий простір agent](/uk/concepts/agent-workspace), [Doctor](/uk/gateway/doctor), - [Remote mode](/uk/gateway/remote). + Пов’язане: [Міграція](/uk/install/migrating), [Де що зберігається на диску](#де-що-зберігається-на-диску), + [Робоча область агента](/uk/concepts/agent-workspace), [Doctor](/uk/gateway/doctor), + [Віддалений режим](/uk/gateway/remote). - Перегляньте changelog на GitHub: + Перевірте changelog на GitHub: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Найновіші записи розміщені вгорі. Якщо верхній розділ позначено як **Unreleased**, наступний датований + Найновіші записи — вгорі. Якщо верхній розділ позначено як **Unreleased**, наступний датований розділ — це остання випущена версія. Записи згруповано за **Highlights**, **Changes** і - **Fixes** (а також розділами документації/іншими розділами за потреби). + **Fixes** (а також за розділами документації/іншими розділами, коли потрібно). Деякі з’єднання Comcast/Xfinity помилково блокують `docs.openclaw.ai` через Xfinity - Advanced Security. Вимкніть її або додайте `docs.openclaw.ai` до allowlist, а потім повторіть спробу. + Advanced Security. Вимкніть її або додайте `docs.openclaw.ai` до allowlist, а потім спробуйте ще раз. Будь ласка, допоможіть нам розблокувати сайт, повідомивши тут: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). - Якщо ви все ще не можете відкрити сайт, документація дзеркально доступна на GitHub: + Якщо ви все ще не можете відкрити сайт, документація дзеркалюється на GitHub: [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs) - **Stable** і **beta** — це **dist-tag npm**, а не окремі гілки коду: + **Stable** і **beta** — це **npm dist-tags**, а не окремі гілки коду: - `latest` = stable - `beta` = рання збірка для тестування - Зазвичай стабільний реліз спочатку потрапляє в **beta**, а потім явний - крок просування переносить цю саму версію в `latest`. За потреби супровідники також можуть - публікувати одразу в `latest`. Саме тому beta і stable можуть + Зазвичай stable-реліз спочатку потрапляє в **beta**, а потім окремий + крок просування переміщує ту саму версію в `latest`. Супровідники також можуть + за потреби публікувати одразу в `latest`. Саме тому beta і stable можуть вказувати на **одну й ту саму версію** після просування. Подивіться, що змінилося: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Однорядкові команди для встановлення та різницю між beta і dev див. в акордеоні нижче. + Однорядкові команди для встановлення та різницю між beta і dev див. в accordion нижче. - **Beta** — це dist-tag npm `beta` (може збігатися з `latest` після просування). - **Dev** — це рухома вершина `main` (git); під час публікації вона використовує dist-tag npm `dev`. + **Beta** — це npm dist-tag `beta` (може збігатися з `latest` після просування). + **Dev** — це рухома вершина `main` (git); під час публікації вона використовує npm dist-tag `dev`. Однорядкові команди (macOS/Linux): @@ -363,7 +363,7 @@ x-i18n: - + Є два варіанти: 1. **Dev channel (git checkout):** @@ -372,9 +372,9 @@ x-i18n: openclaw update --channel dev ``` - Це перемикає на гілку `main` і оновлює з вихідного коду. + Це перемикає вас на гілку `main` і оновлює з вихідного коду. - 2. **Hackable install (із сайту інсталятора):** + 2. **Зламне встановлення (з сайту інсталятора):** ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git @@ -382,7 +382,7 @@ x-i18n: Це дає вам локальний репозиторій, який можна редагувати, а потім оновлювати через git. - Якщо вам більше подобається вручну зробити чистий clone, використайте: + Якщо ви віддаєте перевагу чистому ручному клонуванню, використовуйте: ```bash git clone https://github.com/openclaw/openclaw.git @@ -396,14 +396,14 @@ x-i18n: - + Приблизний орієнтир: - - **Встановлення:** 2-5 хвилин - - **Onboarding:** 5-15 хвилин залежно від того, скільки каналів/моделей ви налаштовуєте + - **Встановлення:** 2–5 хвилин + - **Онбординг:** 5–15 хвилин залежно від того, скільки каналів/моделей ви налаштовуєте - Якщо процес зависає, скористайтеся [Інсталятор завис?](#quick-start-and-first-run-setup) - і швидким циклом налагодження в [Я застряг](#quick-start-and-first-run-setup). + Якщо процес зависає, скористайтеся [Інсталятор завис?](#швидкий-старт-і-початкове-налаштування) + і швидким циклом налагодження в [Я застряг](#швидкий-старт-і-початкове-налаштування). @@ -420,7 +420,7 @@ x-i18n: curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose ``` - Для hackable (git) install: + Для зламного (git) встановлення: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose @@ -429,7 +429,7 @@ x-i18n: Еквівалент для Windows (PowerShell): ```powershell - # install.ps1 поки що не має окремого прапорця -Verbose. + # install.ps1 ще не має окремого прапорця -Verbose. Set-PSDebug -Trace 1 & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard Set-PSDebug -Trace 0 @@ -439,15 +439,15 @@ x-i18n: - - Дві поширені проблеми у Windows: + + Дві поширені проблеми в Windows: - **1) npm error spawn git / git not found** + **1) npm-помилка spawn git / git not found** - Встановіть **Git for Windows** і переконайтеся, що `git` є у вашому PATH. - Закрийте й знову відкрийте PowerShell, а потім повторно запустіть інсталятор. - **2) openclaw is not recognized after install** + **2) openclaw is not recognized після встановлення** - Ваша глобальна папка bin npm відсутня в PATH. - Перевірте шлях: @@ -456,10 +456,10 @@ x-i18n: npm config get prefix ``` - - Додайте цей каталог до PATH користувача (суфікс `\bin` у Windows не потрібен; у більшості систем це `%AppData%\npm`). + - Додайте цей каталог до користувацького PATH (суфікс `\bin` у Windows не потрібен; у більшості систем це `%AppData%\npm`). - Закрийте й знову відкрийте PowerShell після оновлення PATH. - Якщо вам потрібне максимально гладке налаштування Windows, використовуйте **WSL2** замість нативної Windows. + Якщо вам потрібне максимально гладке налаштування у Windows, використовуйте **WSL2** замість нативної Windows. Документація: [Windows](/uk/platforms/windows). @@ -469,7 +469,7 @@ x-i18n: Симптоми: - - вивід `system.run`/`exec` показує китайський текст як mojibake + - вивід `system.run`/`exec` показує китайський текст у вигляді «кракозябр» - та сама команда виглядає нормально в іншому профілі термінала Швидке обхідне рішення в PowerShell: @@ -487,15 +487,15 @@ x-i18n: openclaw gateway restart ``` - Якщо ви все ще відтворюєте це в останній версії OpenClaw, відстежуйте/повідомте про це тут: + Якщо ви все ще відтворюєте це на останній версії OpenClaw, відстежуйте/повідомляйте про це тут: - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640) - Використайте **hackable (git) install**, щоб мати локально повний вихідний код і документацію, а потім запитайте - свого бота (або Claude/Codex) _з цієї папки_, щоб він міг читати репозиторій і відповідати точно. + Використовуйте **зламне (git) встановлення**, щоб локально мати повний вихідний код і документацію, а потім запитайте + свого бота (або Claude/Codex) _з цієї папки_, щоб він міг прочитати репозиторій і дати точну відповідь. ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git @@ -506,9 +506,9 @@ x-i18n: - Коротка відповідь: дотримуйтеся інструкції для Linux, а потім запустіть onboarding. + Коротка відповідь: дотримуйтесь посібника для Linux, а потім запустіть онбординг. - - Швидкий шлях для Linux + встановлення служби: [Linux](/uk/platforms/linux). + - Швидкий шлях для Linux + встановлення сервісу: [Linux](/uk/platforms/linux). - Повний покроковий посібник: [Початок роботи](/uk/start/getting-started). - Інсталятор + оновлення: [Встановлення та оновлення](/uk/install/updating). @@ -522,20 +522,20 @@ x-i18n: - - У нас є **хаб хостингу** з поширеними провайдерами. Виберіть один і дотримуйтеся інструкції: + + Ми підтримуємо **хаб хостингу** з поширеними провайдерами. Виберіть одного й дотримуйтеся посібника: - - [VPS hosting](/uk/vps) (усі провайдери в одному місці) + - [VPS-хостинг](/uk/vps) (усі провайдери в одному місці) - [Fly.io](/uk/install/fly) - [Hetzner](/uk/install/hetzner) - [exe.dev](/uk/install/exe-dev) Як це працює в хмарі: **Gateway працює на сервері**, а ви отримуєте до нього доступ - з ноутбука/телефона через Control UI (або Tailscale/SSH). Ваші state + workspace - зберігаються на сервері, тож ставтеся до хоста як до джерела істини та створюйте його резервні копії. + з ноутбука/телефона через Control UI (або Tailscale/SSH). Ваш стан + робоча область + зберігаються на сервері, тому вважайте хост джерелом істини й створюйте його резервні копії. Ви можете під’єднати **nodes** (Mac/iOS/Android/headless) до цього хмарного Gateway, щоб отримати доступ - до локального екрана/камери/canvas або запускати команди на ноутбуці, залишаючи + до локального екрана/камери/canvas або запускати команди на своєму ноутбуці, залишаючи Gateway у хмарі. Хаб: [Платформи](/uk/platforms). Віддалений доступ: [Віддалений Gateway](/uk/gateway/remote). @@ -544,9 +544,9 @@ x-i18n: - Коротка відповідь: **можливо, але не рекомендовано**. Під час оновлення може перезапускатися - Gateway (що розриває активну сесію), може знадобитися чистий git checkout, а також - може з’явитися запит на підтвердження. Безпечніше запускати оновлення з оболонки як оператор. + Коротка відповідь: **можливо, але не рекомендовано**. Процес оновлення може перезапустити + Gateway (що перерве активну сесію), може вимагати чистого git checkout і + може запросити підтвердження. Безпечніше: запускати оновлення з оболонки як оператор. Використовуйте CLI: @@ -558,7 +558,7 @@ x-i18n: openclaw update --no-restart ``` - Якщо вам усе ж потрібно автоматизувати це через agent: + Якщо вам обов’язково потрібно автоматизувати це через агента: ```bash openclaw update --yes --no-restart @@ -569,99 +569,103 @@ x-i18n: - - `openclaw onboard` — це рекомендований шлях налаштування. У **local mode** він проводить вас через: + + `openclaw onboard` — це рекомендований шлях налаштування. У **локальному режимі** він проводить вас через: - - **Налаштування моделі/auth** (OAuth провайдера, API keys, Anthropic setup-token, а також варіанти локальних моделей, як-от LM Studio) - - розташування **робочого простору** + bootstrap-файли + - **Налаштування моделі/автентифікації** (OAuth провайдера, API-ключі, setup-token Anthropic, а також варіанти локальних моделей, такі як LM Studio) + - Розташування **робочої області** + bootstrap-файли - **Налаштування Gateway** (bind/port/auth/tailscale) - **Канали** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, а також вбудовані channel plugins, як-от QQ Bot) - - **Встановлення daemon** (LaunchAgent на macOS; systemd user unit на Linux/WSL2) - - **Перевірки стану** та вибір **Skills** + - **Встановлення демона** (LaunchAgent на macOS; користувацький модуль systemd на Linux/WSL2) + - **Перевірки стану** і вибір **Skills** - Він також попереджає, якщо налаштована модель невідома або для неї бракує auth. + Він також попереджає, якщо ваша налаштована модель невідома або для неї відсутня автентифікація. - - Ні. Ви можете запускати OpenClaw з **API keys** (Anthropic/OpenAI/інші) або з + + Ні. Ви можете запускати OpenClaw з **API-ключами** (Anthropic/OpenAI/інші) або з **лише локальними моделями**, щоб ваші дані залишалися на вашому пристрої. Підписки (Claude - Pro/Max або OpenAI Codex) — це необов’язкові способи автентифікації в цих провайдерах. + Pro/Max або OpenAI Codex) — це лише необов’язкові способи автентифікації в цих провайдерів. Для Anthropic в OpenClaw практичний поділ такий: - - **Anthropic API key**: звичайна оплата Anthropic API - - **Claude CLI / auth через підписку Claude в OpenClaw**: співробітники Anthropic + - **API-ключ Anthropic**: звичайна тарифікація Anthropic API + - **Автентифікація Claude CLI / підпискою Claude в OpenClaw**: співробітники Anthropic повідомили нам, що таке використання знову дозволене, і OpenClaw розглядає використання `claude -p` як санкціоноване для цієї інтеграції, якщо Anthropic не опублікує нову політику - Для довготривалих хостів gateway ключі Anthropic API усе ще залишаються більш + Для довготривалих хостів gateway API-ключі Anthropic усе ще є більш передбачуваним варіантом налаштування. OAuth OpenAI Codex явно підтримується для зовнішніх - інструментів, таких як OpenClaw. + інструментів на кшталт OpenClaw. - OpenClaw також підтримує інші розміщені варіанти в стилі підписки, зокрема + OpenClaw також підтримує інші варіанти з підпискою на розміщені сервіси, зокрема **Qwen Cloud Coding Plan**, **MiniMax Coding Plan** і **Z.AI / GLM Coding Plan**. Документація: [Anthropic](/uk/providers/anthropic), [OpenAI](/uk/providers/openai), [Qwen Cloud](/uk/providers/qwen), - [MiniMax](/uk/providers/minimax), [GLM Models](/uk/providers/glm), + [MiniMax](/uk/providers/minimax), [Моделі GLM](/uk/providers/glm), [Локальні моделі](/uk/gateway/local-models), [Моделі](/uk/concepts/models). - + Так. Співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тож - OpenClaw вважає auth через підписку Claude та використання `claude -p` санкціонованими + OpenClaw вважає автентифікацію через підписку Claude та використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. Якщо вам потрібне - найпередбачуваніше серверне налаштування, замість цього використовуйте ключ Anthropic API. + найбільш передбачуване серверне налаштування, натомість використовуйте API-ключ Anthropic. - + Так. - Співробітники Anthropic повідомили нам, що таке використання знову дозволене, тому OpenClaw вважає + Співробітники Anthropic повідомили нам, що таке використання знову дозволене, тож OpenClaw вважає повторне використання Claude CLI та використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. - Anthropic setup-token як і раніше доступний як підтримуваний шлях токена в OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI та `claude -p`, коли це доступно. - Для production або multi-user навантажень auth через ключ Anthropic API все ще є - безпечнішим і передбачуванішим вибором. Якщо вам потрібні інші розміщені - варіанти в стилі підписки в OpenClaw, див. [OpenAI](/uk/providers/openai), [Qwen / Model - Cloud](/uk/providers/qwen), [MiniMax](/uk/providers/minimax) і [GLM - Models](/uk/providers/glm). + setup-token Anthropic як і раніше доступний як підтримуваний шлях токена OpenClaw, але тепер OpenClaw віддає перевагу повторному використанню Claude CLI та `claude -p`, коли це можливо. + Для продакшену або багатокористувацьких навантажень автентифікація через API-ключ Anthropic усе ще є + безпечнішим і передбачуванішим вибором. Якщо вам потрібні інші розміщені варіанти + з підпискою в OpenClaw, див. [OpenAI](/uk/providers/openai), [Qwen / Model + Cloud](/uk/providers/qwen), [MiniMax](/uk/providers/minimax) і [Моделі + GLM](/uk/providers/glm). + + - -Це означає, що ваша **квота/ліміт запитів Anthropic** вичерпана для поточного вікна. Якщо ви -використовуєте **Claude CLI**, зачекайте, доки вікно не скинеться, або оновіть свій план. Якщо ви -використовуєте **ключ Anthropic API**, перевірте Anthropic Console -щодо використання/білінгу та за потреби підвищте ліміти. - Якщо повідомлення має такий вигляд: - `Extra usage is required for long context requests`, запит намагається використати - бета-функцію Anthropic з контекстом 1M (`context1m: true`). Це працює лише тоді, коли ваші - облікові дані підходять для білінгу довгого контексту (білінг API key або - шлях входу Claude в OpenClaw з увімкненим Extra Usage). + + + Це означає, що вашу **квоту/ліміт запитів Anthropic** вичерпано для поточного вікна. Якщо ви + використовуєте **Claude CLI**, зачекайте, поки вікно скинеться, або перейдіть на вищий тариф. Якщо ви + використовуєте **API-ключ Anthropic**, перевірте Anthropic Console + щодо використання/білінгу та за потреби підвищте ліміти. - Порада: встановіть **резервну модель**, щоб OpenClaw міг продовжувати відповідати, коли провайдер упирається в rate limit. - Див. [Models](/uk/cli/models), [OAuth](/uk/concepts/oauth) і + Якщо повідомлення конкретно таке: + `Extra usage is required for long context requests`, це означає, що запит намагається використати + бета-версію контексту Anthropic 1M (`context1m: true`). Це працює лише тоді, коли ваші + облікові дані мають право на білінг довгого контексту (білінг API-ключа або + шлях входу Claude OpenClaw з увімкненим Extra Usage). + + Порада: налаштуйте **резервну модель**, щоб OpenClaw міг і далі відповідати, поки провайдер обмежений за лімітом запитів. + Див. [Моделі](/uk/cli/models), [OAuth](/uk/concepts/oauth) і [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/uk/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context). - Так. OpenClaw має вбудований провайдер **Amazon Bedrock (Converse)**. За наявності маркерів env AWS OpenClaw може автоматично виявляти каталог Bedrock для streaming/text і об’єднувати його як неявного провайдера `amazon-bedrock`; інакше ви можете явно ввімкнути `plugins.entries.amazon-bedrock.config.discovery.enabled` або додати запис провайдера вручну. Див. [Amazon Bedrock](/uk/providers/bedrock) і [Провайдери моделей](/uk/providers/models). Якщо ви віддаєте перевагу керованому потоку ключів, OpenAI-сумісний proxy перед Bedrock також залишається коректним варіантом. + Так. OpenClaw має вбудований провайдер **Amazon Bedrock (Converse)**. Якщо присутні маркери середовища AWS, OpenClaw може автоматично виявити каталог Bedrock для потокового/текстового режимів і об'єднати його як неявний провайдер `amazon-bedrock`; інакше ви можете явно ввімкнути `plugins.entries.amazon-bedrock.config.discovery.enabled` або додати запис провайдера вручну. Див. [Amazon Bedrock](/uk/providers/bedrock) і [Провайдери моделей](/uk/providers/models). Якщо ви віддаєте перевагу керованому потоку ключів, OpenAI-сумісний проксі перед Bedrock також залишається коректним варіантом. - - OpenClaw підтримує **OpenAI Code (Codex)** через OAuth (вхід через ChatGPT). Onboarding може запустити OAuth-потік і за потреби встановить модель за замовчуванням `openai-codex/gpt-5.4`. Див. [Провайдери моделей](/uk/concepts/model-providers) і [Onboarding (CLI)](/uk/start/wizard). + + OpenClaw підтримує **OpenAI Code (Codex)** через OAuth (вхід через ChatGPT). Онбординг може запустити потік OAuth і встановить модель за замовчуванням `openai-codex/gpt-5.4`, коли це доречно. Див. [Провайдери моделей](/uk/concepts/model-providers) і [Онбординг (CLI)](/uk/start/wizard). @@ -671,35 +675,35 @@ x-i18n: - `openai/gpt-5.4` = прямий API OpenAI Platform В OpenClaw вхід ChatGPT/Codex прив’язаний до маршруту `openai-codex/*`, - а не до прямого маршруту `openai/*`. Якщо вам потрібен прямий шлях API в + а не до прямого маршруту `openai/*`. Якщо ви хочете прямий шлях API в OpenClaw, задайте `OPENAI_API_KEY` (або еквівалентну конфігурацію провайдера OpenAI). - Якщо вам потрібен вхід ChatGPT/Codex в OpenClaw, використовуйте `openai-codex/*`. + Якщо ви хочете вхід ChatGPT/Codex в OpenClaw, використовуйте `openai-codex/*`. `openai-codex/*` використовує маршрут OAuth Codex, а його доступні вікна квот - керуються OpenAI та залежать від плану. На практиці ці ліміти можуть відрізнятися від - досвіду використання на сайті/в застосунку ChatGPT, навіть коли обидва прив’язані до одного облікового запису. + керуються OpenAI і залежать від тарифу. На практиці ці ліміти можуть відрізнятися від + роботи на сайті/у застосунку ChatGPT, навіть якщо обидва прив’язані до одного облікового запису. - OpenClaw може показати поточні видимі вікна використання/квоти провайдера в - `openclaw models status`, але не вигадує і не нормалізує права ChatGPT-web - у прямий доступ до API. Якщо вам потрібен прямий шлях білінгу/лімітів OpenAI Platform, - використовуйте `openai/*` з API key. + OpenClaw може показувати поточні видимі вікна використання/квоти провайдера в + `openclaw models status`, але він не вигадує й не нормалізує права доступу ChatGPT web + до прямого доступу API. Якщо вам потрібен прямий шлях білінгу/лімітів OpenAI Platform, + використовуйте `openai/*` з API-ключем. - + Так. OpenClaw повністю підтримує **OAuth підписки OpenAI Code (Codex)**. OpenAI явно дозволяє використання OAuth підписки в зовнішніх інструментах/робочих процесах - на кшталт OpenClaw. Onboarding може запустити OAuth-потік за вас. + на кшталт OpenClaw. Онбординг може запустити потік OAuth за вас. - Див. [OAuth](/uk/concepts/oauth), [Провайдери моделей](/uk/concepts/model-providers) і [Onboarding (CLI)](/uk/start/wizard). + Див. [OAuth](/uk/concepts/oauth), [Провайдери моделей](/uk/concepts/model-providers) і [Онбординг (CLI)](/uk/start/wizard). - Gemini CLI використовує **потік auth Plugin**, а не client id чи secret у `openclaw.json`. + Gemini CLI використовує **потік автентифікації Plugin**, а не client id чи secret у `openclaw.json`. Кроки: @@ -709,95 +713,95 @@ x-i18n: 2. Увімкніть Plugin: `openclaw plugins enable google` 3. Увійдіть: `openclaw models auth login --provider google-gemini-cli --set-default` 4. Модель за замовчуванням після входу: `google-gemini-cli/gemini-3-flash-preview` - 5. Якщо запити не вдаються, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway + 5. Якщо запити завершуються помилкою, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway - Це зберігає токени OAuth у профілях auth на хості gateway. Подробиці: [Провайдери моделей](/uk/concepts/model-providers). + Це зберігає токени OAuth у профілях автентифікації на хості gateway. Подробиці: [Провайдери моделей](/uk/concepts/model-providers). - - Зазвичай ні. OpenClaw потребує великого контексту + надійної безпеки; малі карти обрізають і витікають. Якщо вже треба, запускайте **найбільшу** збірку моделі, яку можете локально (LM Studio), і див. [/gateway/local-models](/uk/gateway/local-models). Менші/квантизовані моделі підвищують ризик prompt injection — див. [Безпека](/uk/gateway/security). + + Зазвичай ні. OpenClaw потребує великого контексту + сильної безпеки; малі картки обрізають контекст і пропускають небажаний вміст. Якщо іншого варіанту немає, запускайте **найбільшу** збірку моделі, яку можете локально (LM Studio), і див. [/gateway/local-models](/uk/gateway/local-models). Менші/квантизовані моделі підвищують ризик prompt injection — див. [Безпека](/uk/gateway/security). - - Вибирайте endpoints, прив’язані до регіону. OpenRouter надає варіанти з хостингом у США для MiniMax, Kimi і GLM; виберіть варіант із хостингом у США, щоб дані залишалися в межах регіону. Ви все одно можете перераховувати Anthropic/OpenAI поряд із ними, використовуючи `models.mode: "merge"`, щоб резервні варіанти залишалися доступними, водночас дотримуючись вибраного регіонального провайдера. + + Вибирайте endpoint-и, прив’язані до регіону. OpenRouter надає варіанти, розміщені у США, для MiniMax, Kimi і GLM; виберіть варіант, розміщений у США, щоб дані залишалися в межах регіону. Ви все одно можете вказати поруч Anthropic/OpenAI, використовуючи `models.mode: "merge"`, щоб резервні варіанти лишалися доступними, водночас дотримуючись вибраного вами регіонального провайдера. - Ні. OpenClaw працює на macOS або Linux (Windows через WSL2). Mac mini — необов’язковий варіант: - деякі люди купують його як хост, що завжди ввімкнений, але також підійде невеликий VPS, домашній сервер або пристрій класу Raspberry Pi. + Ні. OpenClaw працює на macOS або Linux (Windows через WSL2). Mac mini — необов’язковий: деякі люди + купують його як постійно увімкнений хост, але також підійде невеликий VPS, домашній сервер або пристрій класу Raspberry Pi. - Mac вам потрібен лише **для інструментів тільки для macOS**. Для iMessage використовуйте [BlueBubbles](/uk/channels/bluebubbles) (рекомендовано) — сервер BlueBubbles працює на будь-якому Mac, а Gateway може працювати на Linux або деінде. Якщо вам потрібні інші інструменти тільки для macOS, запускайте Gateway на Mac або під’єднайте macOS Node. + Mac потрібен лише **для інструментів лише для macOS**. Для iMessage використовуйте [BlueBubbles](/uk/channels/bluebubbles) (рекомендовано) — сервер BlueBubbles працює на будь-якому Mac, а Gateway може працювати на Linux або будь-де ще. Якщо вам потрібні інші інструменти лише для macOS, запустіть Gateway на Mac або під’єднайте macOS Node. Документація: [BlueBubbles](/uk/channels/bluebubbles), [Nodes](/uk/nodes), [Віддалений режим Mac](/uk/platforms/mac/remote). - Вам потрібен **якийсь пристрій macOS**, у якому виконано вхід у Messages. Це **не** обов’язково має бути Mac mini — - підійде будь-який Mac. Для iMessage **використовуйте [BlueBubbles](/uk/channels/bluebubbles)** (рекомендовано) — сервер BlueBubbles працює на macOS, а Gateway може працювати на Linux або деінде. + Вам потрібен **якийсь пристрій macOS**, на якому виконано вхід у Messages. Це **не обов’язково** має бути Mac mini — + підійде будь-який Mac. Для iMessage **використовуйте [BlueBubbles](/uk/channels/bluebubbles)** (рекомендовано) — сервер BlueBubbles працює на macOS, тоді як Gateway може працювати на Linux або будь-де ще. Поширені варіанти налаштування: - - Запускайте Gateway на Linux/VPS, а сервер BlueBubbles — на будь-якому Mac, у якому виконано вхід у Messages. - - Запускайте все на Mac, якщо хочете найпростішу конфігурацію з однією машиною. + - Запустіть Gateway на Linux/VPS, а сервер BlueBubbles — на будь-якому Mac із входом у Messages. + - Запустіть усе на Mac, якщо вам потрібне найпростіше налаштування на одній машині. Документація: [BlueBubbles](/uk/channels/bluebubbles), [Nodes](/uk/nodes), [Віддалений режим Mac](/uk/platforms/mac/remote). - + Так. **Mac mini може запускати Gateway**, а ваш MacBook Pro може під’єднатися як **Node** (додатковий пристрій). Nodes не запускають Gateway — вони надають додаткові - можливості, як-от екран/камера/canvas і `system.run` на цьому пристрої. + можливості, такі як screen/camera/canvas і `system.run` на цьому пристрої. - Поширений шаблон: + Поширений сценарій: - - Gateway на Mac mini (завжди ввімкнений). + - Gateway на Mac mini (завжди увімкнений). - MacBook Pro запускає застосунок macOS або хост Node і під’єднується до Gateway. - - Щоб побачити його, використовуйте `openclaw nodes status` / `openclaw nodes list`. + - Використовуйте `openclaw nodes status` / `openclaw nodes list`, щоб побачити його. Документація: [Nodes](/uk/nodes), [CLI Nodes](/uk/cli/nodes). - Bun **не рекомендовано**. Ми бачимо помилки під час роботи, особливо з WhatsApp і Telegram. - Для стабільних Gateway використовуйте **Node**. + Bun **не рекомендується**. Ми спостерігаємо помилки під час виконання, особливо з WhatsApp і Telegram. + Для стабільних gateway використовуйте **Node**. - Якщо ви все ж хочете поекспериментувати з Bun, робіть це на не-production Gateway + Якщо ви все ж хочете поекспериментувати з Bun, робіть це на gateway не для продакшену без WhatsApp/Telegram. - + `channels.telegram.allowFrom` — це **Telegram user ID людини-відправника** (числовий). Це не ім’я користувача бота. Під час налаштування запитуються лише числові user ID. Якщо у вашій конфігурації вже є застарілі записи `@username`, `openclaw doctor --fix` може спробувати їх розв’язати. - Безпечніше (без стороннього бота): + Безпечніший варіант (без стороннього бота): - - Напишіть своєму боту в DM, потім виконайте `openclaw logs --follow` і прочитайте `from.id`. + - Напишіть вашому боту в особисті повідомлення, потім виконайте `openclaw logs --follow` і прочитайте `from.id`. Офіційний Bot API: - - Напишіть своєму боту в DM, потім викличте `https://api.telegram.org/bot/getUpdates` і прочитайте `message.from.id`. + - Напишіть вашому боту в особисті повідомлення, а потім викличте `https://api.telegram.org/bot/getUpdates` і прочитайте `message.from.id`. Сторонній варіант (менш приватний): - - Напишіть у DM `@userinfobot` або `@getidsbot`. + - Напишіть у приват `@userinfobot` або `@getidsbot`. Див. [/channels/telegram](/uk/channels/telegram#access-control-and-activation). - Так, через **маршрутизацію multi-agent**. Прив’яжіть WhatsApp **DM** кожного відправника (peer `kind: "direct"`, E.164 відправника на кшталт `+15551234567`) до різного `agentId`, щоб кожна людина мала власний робочий простір і сховище сесій. Відповіді все одно надходитимуть з **того самого облікового запису WhatsApp**, а контроль доступу DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) є глобальним для кожного облікового запису WhatsApp. Див. [Маршрутизація Multi-Agent](/uk/concepts/multi-agent) і [WhatsApp](/uk/channels/whatsapp). + Так, через **маршрутизацію мультиагентності**. Прив’яжіть **DM** WhatsApp кожного відправника (peer `kind: "direct"`, E.164 відправника на кшталт `+15551234567`) до різного `agentId`, щоб кожна людина мала власну робочу область і сховище сесій. Відповіді все одно надходитимуть з **того самого облікового запису WhatsApp**, а керування доступом DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) є глобальним для кожного облікового запису WhatsApp. Див. [Маршрутизація мультиагентності](/uk/concepts/multi-agent) і [WhatsApp](/uk/channels/whatsapp). - - Так. Використовуйте маршрутизацію multi-agent: призначте кожному agent власну модель за замовчуванням, а потім прив’яжіть вхідні маршрути (обліковий запис провайдера або конкретні peers) до кожного agent. Приклад конфігурації наведено в [Маршрутизації Multi-Agent](/uk/concepts/multi-agent). Див. також [Моделі](/uk/concepts/models) і [Конфігурація](/uk/gateway/configuration). + + Так. Використовуйте маршрутизацію мультиагентності: задайте кожному агенту власну модель за замовчуванням, а потім прив’яжіть вхідні маршрути (обліковий запис провайдера або конкретні peers) до кожного агента. Приклад конфігурації наведено в [Маршрутизація мультиагентності](/uk/concepts/multi-agent). Див. також [Моделі](/uk/concepts/models) і [Конфігурація](/uk/gateway/configuration). @@ -810,27 +814,27 @@ x-i18n: brew install ``` - Якщо ви запускаєте OpenClaw через systemd, переконайтеся, що PATH служби містить `/home/linuxbrew/.linuxbrew/bin` (або ваш префікс brew), щоб інструменти, встановлені через `brew`, визначалися в non-login оболонках. - Останні збірки також додають попереду поширені користувацькі каталоги bin у службах Linux systemd (наприклад `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) і враховують `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` і `FNM_DIR`, якщо вони задані. + Якщо ви запускаєте OpenClaw через systemd, переконайтеся, що PATH сервісу містить `/home/linuxbrew/.linuxbrew/bin` (або ваш префікс brew), щоб інструменти, встановлені через `brew`, коректно знаходилися в non-login оболонках. + Останні збірки також додають на початок типові користувацькі каталоги bin у сервісах Linux systemd (наприклад `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) і враховують `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` і `FNM_DIR`, якщо вони задані. - - - **Hackable (git) install:** повний checkout вихідного коду, можна редагувати, найкраще для contributors. - Ви локально запускаєте збірки та можете вносити зміни в код/документацію. + + - **Зламне (git) встановлення:** повний checkout вихідного коду, можна редагувати, найкраще для контриб’юторів. + Ви локально запускаєте збірки й можете вносити зміни в код/документацію. - **npm install:** глобальне встановлення CLI, без репозиторію, найкраще для сценарію «просто запустити». - Оновлення надходять із dist-tag npm. + Оновлення надходять із npm dist-tags. Документація: [Початок роботи](/uk/start/getting-started), [Оновлення](/uk/install/updating). - - Так. Встановіть інший варіант, а потім запустіть Doctor, щоб служба gateway вказувала на нову точку входу. - Це **не видаляє ваші дані** — змінюється лише встановлення коду OpenClaw. Ваші state - (`~/.openclaw`) і workspace (`~/.openclaw/workspace`) залишаються недоторканими. + + Так. Встановіть інший варіант, а потім запустіть Doctor, щоб сервіс gateway вказував на нову точку входу. + Це **не видаляє ваші дані** — змінюється лише встановлення коду OpenClaw. Ваш стан + (`~/.openclaw`) і робоча область (`~/.openclaw/workspace`) залишаються недоторканими. - Із npm до git: + Із npm на git: ```bash git clone https://github.com/openclaw/openclaw.git @@ -841,7 +845,7 @@ x-i18n: openclaw gateway restart ``` - Із git до npm: + Із git на npm: ```bash npm install -g openclaw@latest @@ -849,67 +853,67 @@ x-i18n: openclaw gateway restart ``` - Doctor виявляє невідповідність точки входу служби gateway і пропонує переписати конфігурацію служби відповідно до поточного встановлення (використовуйте `--repair` в автоматизації). + Doctor виявляє невідповідність точки входу сервісу gateway і пропонує переписати конфігурацію сервісу відповідно до поточного встановлення (використовуйте `--repair` в автоматизації). - Поради щодо резервного копіювання: див. [Стратегія резервного копіювання](#where-things-live-on-disk). + Поради щодо резервного копіювання: див. [Стратегія резервного копіювання](#де-що-зберігається-на-диску). Коротка відповідь: **якщо вам потрібна надійність 24/7, використовуйте VPS**. Якщо ви хочете - мінімального тертя й вас влаштовують сон/перезапуски, запускайте локально. + мінімального тертя і вас влаштовують sleep/перезапуски, запускайте локально. **Ноутбук (локальний Gateway)** - **Плюси:** немає витрат на сервер, прямий доступ до локальних файлів, видиме вікно браузера в реальному часі. - - **Мінуси:** сон/збої мережі = відключення, оновлення ОС/перезавантаження переривають роботу, пристрій має залишатися активним. + - **Мінуси:** sleep/обриви мережі = відключення, оновлення ОС/перезавантаження переривають роботу, машина має залишатися активною. **VPS / хмара** - - **Плюси:** завжди ввімкнений, стабільна мережа, немає проблем через сон ноутбука, простіше підтримувати в роботі. - - **Мінуси:** часто працює без дисплея (використовуйте знімки екрана), лише віддалений доступ до файлів, для оновлень потрібно підключатися через SSH. + - **Плюси:** завжди увімкнено, стабільна мережа, немає проблем зі sleep ноутбука, легше підтримувати безперервну роботу. + - **Мінуси:** часто працює в headless-режимі (використовуйте скриншоти), лише віддалений доступ до файлів, для оновлень потрібен SSH. - **Примітка щодо OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord усі добре працюють з VPS. Єдиний справжній компроміс — **headless browser** проти видимого вікна. Див. [Browser](/uk/tools/browser). + **Примітка щодо OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord — усе це чудово працює з VPS. Єдиний справжній компроміс — **headless browser** проти видимого вікна. Див. [Браузер](/uk/tools/browser). - **Рекомендований варіант за замовчуванням:** VPS, якщо у вас раніше були відключення gateway. Локальний запуск чудово підходить, коли ви активно користуєтеся Mac і хочете локальний доступ до файлів або автоматизацію UI у видимому браузері. + **Рекомендований варіант за замовчуванням:** VPS, якщо раніше у вас вже були відключення gateway. Локальний варіант чудово підходить, коли ви активно користуєтеся Mac і хочете мати доступ до локальних файлів або автоматизації UI з видимим браузером. - - Не обов’язково, але **рекомендовано для надійності та ізоляції**. + + Не обов’язково, але **рекомендується для надійності та ізоляції**. - - **Виділений хост (VPS/Mac mini/Pi):** завжди ввімкнений, менше переривань через сон/перезавантаження, чистіші дозволи, простіше підтримувати в роботі. - - **Спільний ноутбук/настільний комп’ютер:** цілком нормально для тестування та активного використання, але очікуйте пауз, коли машина переходить у сон або оновлюється. + - **Виділений хост (VPS/Mac mini/Pi):** завжди увімкнений, менше переривань через sleep/перезавантаження, чистіші дозволи, простіше підтримувати роботу. + - **Спільний ноутбук/настільний комп’ютер:** цілком підходить для тестування й активного використання, але очікуйте пауз, коли машина переходить у sleep або оновлюється. - Якщо ви хочете поєднати переваги обох варіантів, тримайте Gateway на виділеному хості, а ноутбук під’єднайте як **Node** для локальних інструментів екрана/камери/exec. Див. [Nodes](/uk/nodes). - Для рекомендацій з безпеки прочитайте [Безпека](/uk/gateway/security). + Якщо ви хочете найкраще з обох світів, тримайте Gateway на виділеному хості, а ноутбук під’єднайте як **Node** для локальних інструментів screen/camera/exec. Див. [Nodes](/uk/nodes). + Рекомендації з безпеки див. у [Безпека](/uk/gateway/security). - - OpenClaw є легким. Для базового Gateway + одного чат-каналу: + + OpenClaw легковажний. Для базового Gateway + одного чату-каналу: - **Абсолютний мінімум:** 1 vCPU, 1GB RAM, ~500MB диска. - - **Рекомендовано:** 1-2 vCPU, 2GB RAM або більше із запасом (логи, медіа, кілька каналів). Інструменти Node і автоматизація браузера можуть бути ресурсомісткими. + - **Рекомендовано:** 1–2 vCPU, 2GB RAM або більше із запасом (журнали, медіа, кілька каналів). Інструменти Node і автоматизація браузера можуть споживати багато ресурсів. - ОС: використовуйте **Ubuntu LTS** (або будь-який сучасний Debian/Ubuntu). Шлях встановлення для Linux найкраще протестовано саме там. + ОС: використовуйте **Ubuntu LTS** (або будь-яку сучасну Debian/Ubuntu). Шлях встановлення для Linux там протестовано найкраще. - Документація: [Linux](/uk/platforms/linux), [VPS hosting](/uk/vps). + Документація: [Linux](/uk/platforms/linux), [VPS-хостинг](/uk/vps). - Так. Ставтеся до VM так само, як до VPS: вона має бути завжди ввімкненою, доступною та мати достатньо - RAM для Gateway і всіх каналів, які ви ввімкнете. + Так. Ставтеся до VM так само, як до VPS: вона має бути завжди увімкненою, доступною й мати достатньо + RAM для Gateway та будь-яких каналів, які ви вмикаєте. Базові рекомендації: - **Абсолютний мінімум:** 1 vCPU, 1GB RAM. - **Рекомендовано:** 2GB RAM або більше, якщо ви запускаєте кілька каналів, автоматизацію браузера або медіаінструменти. - - **ОС:** Ubuntu LTS або інший сучасний Debian/Ubuntu. + - **ОС:** Ubuntu LTS або інша сучасна Debian/Ubuntu. - Якщо ви використовуєте Windows, **WSL2 — найпростіше налаштування у стилі VM** і воно має найкращу - сумісність з інструментами. Див. [Windows](/uk/platforms/windows), [VPS hosting](/uk/vps). + Якщо ви на Windows, **WSL2 — це найпростіший варіант налаштування у стилі VM** і він має найкращу + сумісність інструментів. Див. [Windows](/uk/platforms/windows), [VPS-хостинг](/uk/vps). Якщо ви запускаєте macOS у VM, див. [macOS VM](/uk/install/macos-vm). @@ -918,82 +922,82 @@ x-i18n: ## Що таке OpenClaw? - - OpenClaw — це персональний AI assistant, який ви запускаєте на власних пристроях. Він відповідає на тих поверхнях обміну повідомленнями, якими ви вже користуєтеся (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat і вбудовані channel plugins, такі як QQ Bot) і також може працювати з голосом + live Canvas на підтримуваних платформах. **Gateway** — це контрольна площина, що завжди ввімкнена; assistant — це сам продукт. + + OpenClaw — це персональний AI-помічник, який ви запускаєте на власних пристроях. Він відповідає на поверхнях обміну повідомленнями, якими ви вже користуєтеся (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat і вбудовані channel plugins, як-от QQ Bot) і також може працювати з голосом + live Canvas на підтримуваних платформах. **Gateway** — це завжди увімкнена control plane; помічник — це сам продукт. - OpenClaw — це не «просто обгортка навколо Claude». Це **control plane із пріоритетом локального запуску**, яка дає змогу запускати - потужного assistant на **вашому власному обладнанні**, доступного з чат-застосунків, якими ви вже користуєтеся, із - session history, memory та інструментами — без передавання контролю над вашими робочими процесами + OpenClaw — це не «просто обгортка над Claude». Це **local-first control plane**, яка дає змогу запускати + потужного помічника на **вашому власному обладнанні**, доступного з чат-застосунків, якими ви вже користуєтеся, зі + станом сесій, пам’яттю та інструментами — без передавання контролю над вашими робочими процесами розміщеному SaaS. Основні переваги: - **Ваші пристрої, ваші дані:** запускайте Gateway де завгодно (Mac, Linux, VPS) і зберігайте - workspace + session history локально. - - **Реальні канали, а не вебпісочниця:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage тощо, - плюс мобільний голос і Canvas на підтримуваних платформах. - - **Незалежність від моделі:** використовуйте Anthropic, OpenAI, MiniMax, OpenRouter тощо з маршрутизацією - та перемиканням у разі збою для кожного agent окремо. + робочу область + історію сесій локально. + - **Реальні канали, а не веб-пісочниця:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage тощо, + а також мобільний голос і Canvas на підтримуваних платформах. + - **Незалежність від моделі:** використовуйте Anthropic, OpenAI, MiniMax, OpenRouter тощо, з маршрутизацією + та резервним перемиканням на рівні агента. - **Лише локальний варіант:** запускайте локальні моделі, щоб **усі дані могли залишатися на вашому пристрої**, якщо ви цього хочете. - - **Маршрутизація multi-agent:** окремі agents для кожного каналу, облікового запису чи завдання, кожен зі своїм - workspace і значеннями за замовчуванням. - - **Відкритий код і можливість змінювати:** перевіряйте, розширюйте та розміщуйте самостійно без прив’язки до постачальника. + - **Маршрутизація мультиагентності:** окремі агенти для каналу, облікового запису або завдання, кожен із власною + робочою областю та параметрами за замовчуванням. + - **Відкритий код і можливість змін:** перевіряйте, розширюйте й самостійно розгортайте без прив’язки до вендора. - Документація: [Gateway](/uk/gateway), [Канали](/uk/channels), [Multi-agent](/uk/concepts/multi-agent), - [Memory](/uk/concepts/memory). + Документація: [Gateway](/uk/gateway), [Канали](/uk/channels), [Мультиагентність](/uk/concepts/multi-agent), + [Пам’ять](/uk/concepts/memory). - - Хороші перші проєкти: + + Гарні перші проєкти: - Створити вебсайт (WordPress, Shopify або простий статичний сайт). - - Створити прототип мобільного застосунку (структура, екрани, план API). - - Упорядкувати файли та папки (очищення, іменування, теги). - - Під’єднати Gmail і автоматизувати підсумки або follow ups. + - Прототипувати мобільний застосунок (структура, екрани, план API). + - Упорядкувати файли й папки (очищення, найменування, тегування). + - Під’єднати Gmail і автоматизувати зведення або подальші дії. - Він може працювати з великими завданнями, але найкраще працює, коли ви ділите їх на фази й - використовуєте sub agents для паралельної роботи. + Він може впоратися з великими завданнями, але працює найкраще, коли ви розбиваєте їх на етапи + і використовуєте субагентів для паралельної роботи. Повсякденна користь зазвичай виглядає так: - - **Персональні зведення:** підсумки inbox, календаря та важливих для вас новин. - - **Дослідження та чернетки:** швидкі дослідження, підсумки та перші чернетки для листів або документів. - - **Нагадування та follow ups:** підказки й чеклісти на основі Cron або Heartbeat. - - **Автоматизація браузера:** заповнення форм, збирання даних і повторення вебзавдань. + - **Персональні зведення:** підсумки пошти, календаря та важливих для вас новин. + - **Дослідження й чернетки:** швидкі дослідження, підсумки та перші чернетки для листів або документів. + - **Нагадування й подальші дії:** підказки та чеклісти на основі Cron або Heartbeat. + - **Автоматизація браузера:** заповнення форм, збір даних і повторювані вебзавдання. - **Координація між пристроями:** надішліть завдання з телефона, дозвольте Gateway виконати його на сервері й отримайте результат назад у чаті. - - Так, для **дослідження, кваліфікації та підготовки чернеток**. Він може сканувати сайти, створювати списки, - підсумовувати інформацію про потенційних клієнтів і писати чернетки outreach або рекламних текстів. + + Так — для **досліджень, кваліфікації та підготовки чернеток**. Він може сканувати сайти, створювати shortlists, + підсумовувати потенційних клієнтів і писати чернетки аутрічу або рекламних текстів. - Для **outreach або запуску реклами** залишайте людину в циклі. Уникайте спаму, дотримуйтесь місцевих законів і - політик платформ, і переглядайте все перед надсиланням. Найбезпечніший шаблон — дозволити - OpenClaw підготувати чернетку, а ви її схвалюєте. + Для **аутрічу або запуску реклами** залишайте людину в циклі. Уникайте спаму, дотримуйтеся місцевих законів і + правил платформи та перевіряйте все перед відправленням. Найбезпечніший шаблон — дозволити + OpenClaw підготувати чернетку, а вам — затвердити її. Документація: [Безпека](/uk/gateway/security). - OpenClaw — це **персональний assistant** і рівень координації, а не заміна IDE. Використовуйте - Claude Code або Codex для найшвидшого прямого циклу кодування всередині репозиторію. Використовуйте OpenClaw, коли вам - потрібні довготривала memory, кроспристроєвий доступ і оркестрація інструментів. + OpenClaw — це **персональний помічник** і рівень координації, а не заміна IDE. Використовуйте + Claude Code або Codex для найшвидшого прямого циклу кодування в репозиторії. Використовуйте OpenClaw, коли вам + потрібні довготривала пам’ять, міжпристроєвий доступ і оркестрація інструментів. Переваги: - - **Постійна memory + workspace** між сесіями - - **Доступ із багатьох платформ** (WhatsApp, Telegram, TUI, WebChat) - - **Оркестрація інструментів** (browser, files, планування, hooks) - - **Gateway, що завжди ввімкнений** (запуск на VPS, взаємодія звідусіль) - - **Nodes** для локального browser/screen/camera/exec + - **Постійна пам’ять + робоча область** між сесіями + - **Мультиплатформений доступ** (WhatsApp, Telegram, TUI, WebChat) + - **Оркестрація інструментів** (браузер, файли, планування, hooks) + - **Завжди увімкнений Gateway** (запуск на VPS, взаємодія звідусіль) + - **Nodes** для локальних browser/screen/camera/exec Вітрина: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) @@ -1004,68 +1008,68 @@ x-i18n: - Використовуйте керовані перевизначення замість редагування копії в репозиторії. Розміщуйте свої зміни в `~/.openclaw/skills//SKILL.md` (або додайте папку через `skills.load.extraDirs` у `~/.openclaw/openclaw.json`). Пріоритет такий: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → вбудовані → `skills.load.extraDirs`, тож керовані перевизначення все одно мають вищий пріоритет за вбудовані skills без зміни git. Якщо потрібно, щоб skill був встановлений глобально, але видимий лише деяким agents, тримайте спільну копію в `~/.openclaw/skills` і керуйте видимістю через `agents.defaults.skills` і `agents.list[].skills`. Лише зміни, які варті внесення вгору за течією, мають жити в репозиторії та надсилатися як PR. + Використовуйте керовані перевизначення замість редагування копії в репозиторії. Помістіть свої зміни в `~/.openclaw/skills//SKILL.md` (або додайте папку через `skills.load.extraDirs` у `~/.openclaw/openclaw.json`). Пріоритет такий: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → вбудовані → `skills.load.extraDirs`, тож керовані перевизначення все одно мають вищий пріоритет за вбудовані Skills, не торкаючись git. Якщо вам потрібно, щоб skill було встановлено глобально, але видно лише певним агентам, тримайте спільну копію в `~/.openclaw/skills` і керуйте видимістю через `agents.defaults.skills` та `agents.list[].skills`. Лише зміни, гідні внесення в апстрим, мають жити в репозиторії й надсилатися як PR. - - Так. Додавайте додаткові каталоги через `skills.load.extraDirs` у `~/.openclaw/openclaw.json` (найнижчий пріоритет). Типовий пріоритет: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → вбудовані → `skills.load.extraDirs`. `clawhub` типово встановлює в `./skills`, що OpenClaw розглядає як `/skills` у наступній сесії. Якщо skill має бути видимий лише певним agents, поєднуйте це з `agents.defaults.skills` або `agents.list[].skills`. + + Так. Додайте додаткові каталоги через `skills.load.extraDirs` у `~/.openclaw/openclaw.json` (найнижчий пріоритет). Типовий пріоритет: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → вбудовані → `skills.load.extraDirs`. `clawhub` типово встановлює в `./skills`, що OpenClaw розглядає як `/skills` під час наступної сесії. Якщо skill має бути видимий лише певним агентам, поєднайте це з `agents.defaults.skills` або `agents.list[].skills`. - - Сьогодні підтримуються такі шаблони: + + Наразі підтримуються такі шаблони: - **Cron jobs**: ізольовані завдання можуть задавати перевизначення `model` для кожного завдання. - - **Sub-agents**: маршрутизуйте завдання до окремих agents з різними моделями за замовчуванням. - - **Перемикання на вимогу**: використовуйте `/model`, щоб у будь-який момент перемкнути модель поточної сесії. + - **Субагенти**: маршрутизуйте завдання до окремих агентів із різними моделями за замовчуванням. + - **Перемикання на вимогу**: використовуйте `/model`, щоб у будь-який момент змінити модель поточної сесії. - Див. [Cron jobs](/uk/automation/cron-jobs), [Маршрутизація Multi-Agent](/uk/concepts/multi-agent) і [Слеш-команди](/uk/tools/slash-commands). + Див. [Cron jobs](/uk/automation/cron-jobs), [Маршрутизація мультиагентності](/uk/concepts/multi-agent) і [Slash commands](/uk/tools/slash-commands). - - Використовуйте **sub-agents** для довгих або паралельних завдань. Sub-agents працюють у власній сесії, - повертають підсумок і зберігають чутливість основного чату. + + Використовуйте **субагентів** для довгих або паралельних завдань. Субагенти працюють у власній сесії, + повертають підсумок і зберігають чутливість вашого основного чату. - Попросіть свого бота «spawn a sub-agent for this task» або використайте `/subagents`. + Попросіть бота «створити субагента для цього завдання» або використовуйте `/subagents`. Використовуйте `/status` у чаті, щоб бачити, що Gateway робить просто зараз (і чи він зайнятий). - Порада щодо токенів: і довгі завдання, і sub-agents споживають токени. Якщо вартість має значення, задайте - дешевшу модель для sub-agents через `agents.defaults.subagents.model`. + Порада щодо токенів: довгі завдання й субагенти обидва витрачають токени. Якщо вас хвилює вартість, задайте + дешевшу модель для субагентів через `agents.defaults.subagents.model`. - Документація: [Sub-agents](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks). + Документація: [Субагенти](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks). - - Використовуйте прив’язки thread. Ви можете прив’язати Discord thread до subagent або цілі session, щоб наступні повідомлення в цій thread залишалися на цій прив’язаній сесії. + + Використовуйте прив’язки потоків. Ви можете прив’язати потік Discord до субагента або цілі сесії, щоб подальші повідомлення в цьому потоці залишалися в межах цієї прив’язаної сесії. Базовий процес: - - Створіть через `sessions_spawn` з `thread: true` (і, за потреби, `mode: "session"` для постійних наступних повідомлень). - - Або прив’яжіть вручну через `/focus `. + - Створіть через `sessions_spawn` з `thread: true` (і за бажанням `mode: "session"` для постійних подальших повідомлень). + - Або вручну прив’яжіть через `/focus `. - Використовуйте `/agents`, щоб перевірити стан прив’язки. - - Використовуйте `/session idle ` і `/session max-age `, щоб керувати автоматичним зняттям фокусу. - - Використовуйте `/unfocus`, щоб від’єднати thread. + - Використовуйте `/session idle ` і `/session max-age `, щоб керувати автоматичним зняттям фокуса. + - Використовуйте `/unfocus`, щоб від’єднати потік. Потрібна конфігурація: - - Глобальні значення за замовчуванням: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. + - Глобальні параметри за замовчуванням: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. - Перевизначення Discord: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. - Автоприв’язка під час створення: задайте `channels.discord.threadBindings.spawnSubagentSessions: true`. - Документація: [Sub-agents](/uk/tools/subagents), [Discord](/uk/channels/discord), [Довідник із конфігурації](/uk/gateway/configuration-reference), [Слеш-команди](/uk/tools/slash-commands). + Документація: [Субагенти](/uk/tools/subagents), [Discord](/uk/channels/discord), [Довідник із конфігурації](/uk/gateway/configuration-reference), [Slash commands](/uk/tools/slash-commands). - + Спочатку перевірте розв’язаний маршрут запитувача: - - Доставка subagent у режимі завершення надає перевагу будь-якому прив’язаному thread або маршруту conversation, якщо такий існує. - - Якщо джерело завершення містить лише канал, OpenClaw використовує запасний варіант — збережений маршрут сесії запитувача (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все ще могла спрацювати. - - Якщо немає ні прив’язаного маршруту, ні придатного збереженого маршруту, пряма доставка може завершитися невдачею, і результат замість негайної публікації в чаті перейде в доставку через чергу сесії. - - Недійсні або застарілі цілі все одно можуть примусово перевести доставку до черги або спричинити остаточну помилку доставки. - - Якщо остання видима відповідь assistant у дочірній сесії — це точний silent token `NO_REPLY` / `no_reply` або рівно `ANNOUNCE_SKIP`, OpenClaw навмисно пригнічує announce замість публікації застарілого попереднього прогресу. - - Якщо дочірня сесія завершилася за timeout після лише викликів інструментів, announce може згорнути це до короткого підсумку часткового прогресу замість відтворення сирого виводу інструментів. + - Доставка субагента в режимі completion віддає перевагу будь-якому прив’язаному потоку або маршруту розмови, якщо такий існує. + - Якщо джерело completion містить лише канал, OpenClaw повертається до збереженого маршруту сесії запитувача (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все ще могла спрацювати. + - Якщо немає ані прив’язаного маршруту, ані придатного збереженого маршруту, пряма доставка може завершитися невдачею, і тоді результат повернеться до доставки через чергу сесії замість негайної публікації в чаті. + - Недійсні або застарілі цілі все одно можуть змусити систему перейти до запасного варіанта з чергою або спричинити остаточний збій доставки. + - Якщо остання видима відповідь помічника дитини — це точний тихий токен `NO_REPLY` / `no_reply` або рівно `ANNOUNCE_SKIP`, OpenClaw навмисно пригнічує оголошення замість публікації застарілого попереднього прогресу. + - Якщо дочірній процес завершився за тайм-аутом лише після викликів інструментів, оголошення може згорнути це в короткий підсумок часткового прогресу замість відтворення сирого виводу інструментів. Налагодження: @@ -1073,18 +1077,18 @@ x-i18n: openclaw tasks show ``` - Документація: [Sub-agents](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks), [Інструмент Session](/uk/concepts/session-tool). + Документація: [Субагенти](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks), [Інструмент сесій](/uk/concepts/session-tool). Cron виконується всередині процесу Gateway. Якщо Gateway не працює безперервно, - заплановані завдання не виконуватимуться. + заплановані завдання не запускатимуться. - Чекліст: + Контрольний список: - Підтвердьте, що cron увімкнено (`cron.enabled`) і `OPENCLAW_SKIP_CRON` не задано. - - Переконайтеся, що Gateway працює 24/7 (без сну/перезапусків). + - Переконайтеся, що Gateway працює 24/7 (без sleep/перезапусків). - Перевірте налаштування часового поясу для завдання (`--tz` проти часового поясу хоста). Налагодження: @@ -1101,14 +1105,14 @@ x-i18n: Спочатку перевірте режим доставки: - - `--no-deliver` / `delivery.mode: "none"` означає, що резервне надсилання runner не очікується. - - Відсутня або недійсна ціль announce (`channel` / `to`) означає, що runner пропустив вихідну доставку. - - Помилки auth каналу (`unauthorized`, `Forbidden`) означають, що runner намагався доставити повідомлення, але облікові дані це заблокували. - - Тихий ізольований результат (`NO_REPLY` / `no_reply` only) вважається навмисно недоставним, тому runner також пригнічує резервну доставку через чергу. + - `--no-deliver` / `delivery.mode: "none"` означає, що запасне надсилання runner не очікується. + - Відсутня або недійсна ціль оголошення (`channel` / `to`) означає, що runner пропустив вихідну доставку. + - Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що runner спробував виконати доставку, але облікові дані її заблокували. + - Тихий ізольований результат (`NO_REPLY` / `no_reply` і більше нічого) вважається навмисно недоставним, тому runner також пригнічує запасну доставку через чергу. - Для ізольованих Cron jobs agent усе одно може надсилати безпосередньо за допомогою інструмента `message`, - коли маршрут чату доступний. `--announce` керує лише резервним шляхом runner - для фінального тексту, який agent ще не надіслав самостійно. + Для ізольованих cron jobs агент усе ще може надсилати напряму за допомогою інструмента `message`, + коли доступний маршрут чату. `--announce` керує лише запасним шляхом runner + для фінального тексту, який агент ще не надіслав самостійно. Налагодження: @@ -1121,23 +1125,23 @@ x-i18n: - - Зазвичай це шлях живого перемикання моделі, а не дублювання планування. + + Зазвичай це шлях живого перемикання моделі, а не дублювання розкладу. - Ізольований cron може зберегти передавання моделі під час роботи й повторити спробу, коли активний - запуск викидає `LiveSessionModelSwitchError`. Під час повторної спроби зберігаються переключені - provider/model, а якщо перемикання містило нове перевизначення профілю auth, cron - також зберігає його перед повторною спробою. + Ізольований cron може зберегти передачу моделі під час виконання та повторити спробу, коли активний + запуск викидає `LiveSessionModelSwitchError`. Повторна спроба зберігає перемкненого + провайдера/модель, а якщо перемикання також містило нове перевизначення профілю автентифікації, cron + зберігає і його перед повтором. Пов’язані правила вибору: - - Спочатку, якщо застосовно, перемагає перевизначення моделі Gmail hook. - - Потім — `model` для конкретного завдання. - - Потім — будь-яке збережене перевизначення моделі cron-session. - - Потім — звичайний вибір моделі agent/за замовчуванням. + - Перевизначення моделі Gmail hook має найвищий пріоритет, коли застосовне. + - Далі йде `model` для конкретного завдання. + - Потім будь-яке збережене перевизначення моделі cron-session. + - Потім звичайний вибір моделі агента/за замовчуванням. - Цикл повторних спроб обмежений. Після початкової спроби плюс 2 повторів через перемикання - cron завершує роботу замість нескінченного циклу. + Цикл повторів обмежений. Після початкової спроби плюс 2 повторів через перемикання + cron припиняє роботу замість нескінченного циклу. Налагодження: @@ -1151,7 +1155,7 @@ x-i18n: - Використовуйте нативні команди `openclaw skills` або просто розміщуйте skills у своєму workspace. UI Skills для macOS недоступний на Linux. + Використовуйте нативні команди `openclaw skills` або просто помістіть Skills у свою робочу область. UI Skills для macOS недоступний на Linux. Переглянути Skills можна на [https://clawhub.ai](https://clawhub.ai). ```bash @@ -1165,10 +1169,11 @@ x-i18n: openclaw skills check ``` - Нативний `openclaw skills install` записує у каталог `skills/` активного workspace. Окремий CLI `clawhub` встановлюйте лише якщо хочете публікувати або - синхронізувати власні skills. Для спільних встановлень між agents розміщуйте skill у + Нативний `openclaw skills install` записує у каталог `skills/` + активної робочої області. Окремий CLI `clawhub` встановлюйте лише якщо хочете публікувати або + синхронізувати власні Skills. Для спільних встановлень між агентами розміщуйте skill у `~/.openclaw/skills` і використовуйте `agents.defaults.skills` або - `agents.list[].skills`, якщо хочете звузити коло agents, які можуть його бачити. + `agents.list[].skills`, якщо хочете звузити коло агентів, які можуть його бачити. @@ -1177,26 +1182,26 @@ x-i18n: - **Cron jobs** для запланованих або повторюваних завдань (зберігаються після перезапусків). - **Heartbeat** для періодичних перевірок «основної сесії». - - **Ізольовані завдання** для автономних agents, які публікують підсумки або доставляють їх у чати. + - **Ізольовані завдання** для автономних агентів, які публікують підсумки або доставляють їх у чати. Документація: [Cron jobs](/uk/automation/cron-jobs), [Автоматизація та завдання](/uk/automation), [Heartbeat](/uk/gateway/heartbeat). - - Не напряму. macOS skills обмежуються через `metadata.openclaw.os` і потрібні бінарні файли, а skills з’являються в system prompt лише тоді, коли вони придатні на **хості Gateway**. У Linux skills лише для `darwin` (як-от `apple-notes`, `apple-reminders`, `things-mac`) не завантажуються, якщо ви не перевизначите це обмеження. + + Не напряму. Skills для macOS обмежуються через `metadata.openclaw.os` плюс потрібні бінарні файли, і Skills з’являються в системному prompt лише тоді, коли вони придатні на **хості Gateway**. На Linux Skills лише для `darwin` (як-от `apple-notes`, `apple-reminders`, `things-mac`) не завантажаться, якщо ви не перевизначите це обмеження. - Є три підтримувані варіанти: + У вас є три підтримувані шаблони: - **Варіант A — запускати Gateway на Mac (найпростіше).** - Запускайте Gateway там, де існують бінарні файли macOS, а потім підключайтеся з Linux у [remote mode](#gateway-ports-already-running-and-remote-mode) або через Tailscale. Skills завантажуються нормально, тому що хост Gateway — це macOS. + **Варіант A — запустити Gateway на Mac (найпростіше).** + Запустіть Gateway там, де існують бінарні файли macOS, а потім підключайтеся з Linux у [віддаленому режимі](#gateway-ports-already-running-and-remote-mode) або через Tailscale. Skills завантажаться нормально, тому що хост Gateway — це macOS. **Варіант B — використовувати macOS Node (без SSH).** - Запускайте Gateway на Linux, під’єднайте macOS Node (застосунок у рядку меню) і встановіть **Node Run Commands** у значення "Always Ask" або "Always Allow" на Mac. OpenClaw може вважати skills лише для macOS придатними, коли потрібні бінарні файли існують на Node. Agent запускає ці skills через інструмент `nodes`. Якщо ви виберете "Always Ask", підтвердження "Always Allow" у запиті додасть цю команду до allowlist. + Запустіть Gateway на Linux, під’єднайте macOS Node (застосунок у рядку меню) і задайте **Node Run Commands** як «Always Ask» або «Always Allow» на Mac. OpenClaw може вважати Skills лише для macOS придатними, коли потрібні бінарні файли є на Node. Агент запускає ці Skills через інструмент `nodes`. Якщо ви виберете «Always Ask», затвердження «Always Allow» у запиті додає цю команду до allowlist. - **Варіант C — проксувати бінарні файли macOS через SSH (просунутий варіант).** - Тримайте Gateway на Linux, але забезпечте, щоб потрібні CLI-бінарні файли резолвилися до SSH-обгорток, які виконуються на Mac. Потім перевизначте skill, щоб дозволити Linux, і він залишався придатним. + **Варіант C — проксіювання бінарних файлів macOS через SSH (просунуто).** + Залиште Gateway на Linux, але зробіть так, щоб потрібні CLI-бінарні файли розв’язувалися в SSH-обгортки, які запускаються на Mac. Потім перевизначте skill, щоб дозволити Linux і зберегти його придатним. 1. Створіть SSH-обгортку для бінарного файла (приклад: `memo` для Apple Notes): @@ -1206,169 +1211,168 @@ x-i18n: exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@" ``` - 2. Розмістіть обгортку в `PATH` на хості Linux (наприклад `~/bin/memo`). - 3. Перевизначте метадані skill (workspace або `~/.openclaw/skills`), щоб дозволити Linux: + 2. Помістіть обгортку в `PATH` на хості Linux (наприклад, `~/bin/memo`). + 3. Перевизначте метадані skill (робоча область або `~/.openclaw/skills`), щоб дозволити Linux: ```markdown --- name: apple-notes - description: Керування Apple Notes через CLI memo у macOS. + description: Manage Apple Notes via the memo CLI on macOS. metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } } --- ``` - 4. Почніть нову сесію, щоб оновився знімок skills. + 4. Почніть нову сесію, щоб знімок Skills оновився. - - Сьогодні вбудованої немає. + + Наразі вбудованої немає. Варіанти: - - **Власний skill / Plugin:** найкраще для надійного доступу до API (і Notion, і HeyGen мають API). - - **Автоматизація браузера:** працює без коду, але повільніше й крихкіше. + - **Власний skill / Plugin:** найкращий варіант для надійного доступу через API (і в Notion, і в HeyGen є API). + - **Автоматизація браузера:** працює без коду, але повільніше й більш крихко. - Якщо ви хочете зберігати контекст для кожного клієнта окремо (робочі процеси агентства), простий шаблон такий: + Якщо ви хочете зберігати контекст окремо для кожного клієнта (агентські робочі процеси), простий шаблон такий: - Одна сторінка Notion на клієнта (контекст + налаштування + активна робота). - - Просіть agent отримувати цю сторінку на початку сесії. + - Попросіть агента отримувати цю сторінку на початку сесії. - Якщо вам потрібна нативна інтеграція, створіть feature request або побудуйте skill, - орієнтований на ці API. + Якщо вам потрібна нативна інтеграція, відкрийте запит на нову можливість або створіть skill + для цих API. - Встановлення skills: + Встановлення Skills: ```bash openclaw skills install openclaw skills update --all ``` - Нативні встановлення потрапляють у каталог `skills/` активного workspace. Для спільних skills між agents розміщуйте їх у `~/.openclaw/skills//SKILL.md`. Якщо спільне встановлення мають бачити лише деякі agents, налаштуйте `agents.defaults.skills` або `agents.list[].skills`. Деякі skills очікують бінарні файли, встановлені через Homebrew; у Linux це означає Linuxbrew (див. запис FAQ про Homebrew на Linux вище). Див. [Skills](/uk/tools/skills), [Конфігурація Skills](/uk/tools/skills-config) і [ClawHub](/uk/tools/clawhub). + Нативні встановлення потрапляють у каталог `skills/` активної робочої області. Для спільних Skills між агентами розміщуйте їх у `~/.openclaw/skills//SKILL.md`. Якщо спільне встановлення мають бачити лише деякі агенти, налаштуйте `agents.defaults.skills` або `agents.list[].skills`. Деякі Skills очікують наявності бінарних файлів, встановлених через Homebrew; на Linux це означає Linuxbrew (див. запис FAQ про Homebrew на Linux вище). Див. [Skills](/uk/tools/skills), [Конфігурація Skills](/uk/tools/skills-config) і [ClawHub](/uk/tools/clawhub). - - Використовуйте вбудований профіль браузера `user`, який підключається через Chrome DevTools MCP: + + Використовуйте вбудований профіль браузера `user`, який під’єднується через Chrome DevTools MCP: ```bash openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot ``` - Якщо вам потрібна власна назва, створіть явний профіль MCP: + Якщо вам потрібна власна назва, створіть явний MCP-профіль: ```bash openclaw browser create-profile --name chrome-live --driver existing-session openclaw browser --browser-profile chrome-live tabs ``` - Цей шлях може використовувати локальний браузер хоста або підключений browser node. Якщо Gateway працює деінде, або запускайте хост Node на машині з браузером, або використовуйте віддалений CDP. + Цей шлях може використовувати локальний браузер хоста або під’єднаний browser Node. Якщо Gateway працює деінде, або запустіть хост Node на машині з браузером, або використовуйте віддалений CDP. Поточні обмеження `existing-session` / `user`: - - дії ґрунтуються на ref, а не на CSS-selector - - завантаження файлів потребують `ref` / `inputRef` і наразі підтримують лише один файл за раз - - `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії все ще потребують керованого браузера або сирого профілю CDP + - дії прив’язані до `ref`, а не до CSS-селекторів + - вивантаження файлів потребує `ref` / `inputRef` і наразі підтримує лише один файл за раз + - `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії все ще потребують керованого браузера або сирого CDP-профілю -## Ізоляція та memory +## Sandboxing і пам’ять - - Так. Див. [Ізоляція](/uk/gateway/sandboxing). Для налаштування, специфічного для Docker (повний Gateway у Docker або образи ізоляції), див. [Docker](/uk/install/docker). + + Так. Див. [Sandboxing](/uk/gateway/sandboxing). Для налаштування, специфічного для Docker (повний gateway у Docker або sandbox-образи), див. [Docker](/uk/install/docker). - Типовий образ орієнтований насамперед на безпеку і працює від користувача `node`, тому він не + Образ за замовчуванням має пріоритет безпеки й запускається від користувача `node`, тому не містить системних пакетів, Homebrew або вбудованих браузерів. Для повнішого налаштування: - - Зберігайте `/home/node` через `OPENCLAW_HOME_VOLUME`, щоб кеші зберігалися між запусками. - - Додавайте системні залежності в образ через `OPENCLAW_DOCKER_APT_PACKAGES`. + - Зберігайте `/home/node` через `OPENCLAW_HOME_VOLUME`, щоб кеші не втрачалися. + - Вбудовуйте системні залежності в образ через `OPENCLAW_DOCKER_APT_PACKAGES`. - Встановлюйте браузери Playwright через вбудований CLI: `node /app/node_modules/playwright-core/cli.js install chromium` - Задайте `PLAYWRIGHT_BROWSERS_PATH` і переконайтеся, що цей шлях зберігається. - Документація: [Docker](/uk/install/docker), [Browser](/uk/tools/browser). + Документація: [Docker](/uk/install/docker), [Браузер](/uk/tools/browser). - - Так — якщо ваш приватний трафік це **DM**, а публічний трафік — це **групи**. + + Так — якщо ваш приватний трафік це **DM**, а публічний трафік це **групи**. - Використовуйте `agents.defaults.sandbox.mode: "non-main"`, щоб групові/канальні сесії (ключі не-main) працювали у налаштованому бекенді ізоляції, тоді як основна сесія DM залишалася на хості. Docker — типовий бекенд, якщо ви не виберете інший. Потім обмежте, які інструменти доступні в ізольованих сесіях, через `tools.sandbox.tools`. + Використовуйте `agents.defaults.sandbox.mode: "non-main"`, щоб групові/канальні сесії (ключі не-main) працювали у налаштованому sandbox-бекенді, тоді як головна DM-сесія залишалася на хості. Docker є бекендом за замовчуванням, якщо ви не виберете інший. Потім обмежте інструменти, доступні в ізольованих сесіях, через `tools.sandbox.tools`. Покрокове налаштування + приклад конфігурації: [Групи: приватні DM + публічні групи](/uk/channels/groups#pattern-personal-dms-public-groups-single-agent) - Ключовий довідник із конфігурації: [Конфігурація Gateway](/uk/gateway/configuration-reference#agentsdefaultssandbox) + Довідка з ключової конфігурації: [Конфігурація Gateway](/uk/gateway/configuration-reference#agentsdefaultssandbox) - - Задайте `agents.defaults.sandbox.docker.binds` у вигляді `["host:path:mode"]` (наприклад, `"/home/user/src:/src:ro"`). Глобальні прив’язки та прив’язки для окремих agents об’єднуються; прив’язки для окремих agents ігноруються, коли `scope: "shared"`. Використовуйте `:ro` для всього чутливого й пам’ятайте, що прив’язки обходять файлові межі ізольованого середовища. + + Задайте `agents.defaults.sandbox.docker.binds` як `["host:path:mode"]` (наприклад, `"/home/user/src:/src:ro"`). Глобальні прив’язки й прив’язки на рівні агента об’єднуються; прив’язки на рівні агента ігноруються, коли `scope: "shared"`. Використовуйте `:ro` для всього чутливого й пам’ятайте, що прив’язки обходять файлові стіни sandbox. - OpenClaw перевіряє джерела bind і за нормалізованим шляхом, і за канонічним шляхом, розв’язаним через найглибший наявний батьківський елемент. Це означає, що виходи за межі через symlink-parent усе одно надійно блокуються, навіть коли останній сегмент шляху ще не існує, а перевірки allowed-root усе одно застосовуються після розв’язання symlink. + OpenClaw перевіряє джерела bind і за нормалізованим шляхом, і за канонічним шляхом, розв’язаним через найглибшого наявного предка. Це означає, що виходи через батьківський symlink усе одно блокуються за принципом fail closed, навіть коли останній сегмент шляху ще не існує, а перевірки allowed-root усе одно застосовуються після розв’язання symlink. - Приклади та зауваження з безпеки див. у [Ізоляція](/uk/gateway/sandboxing#custom-bind-mounts) і [Ізоляція vs політика інструментів vs elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check). + Приклади та примітки щодо безпеки див. в [Sandboxing](/uk/gateway/sandboxing#custom-bind-mounts) і [Sandbox vs Tool Policy vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check). - - Memory OpenClaw — це просто Markdown-файли в workspace agent: + + Пам’ять OpenClaw — це просто Markdown-файли в робочій області агента: - Щоденні нотатки в `memory/YYYY-MM-DD.md` - - Кураторські довгострокові нотатки в `MEMORY.md` (лише для main/private sessions) + - Кураторські довгострокові нотатки в `MEMORY.md` (лише для main/private-сесій) - OpenClaw також виконує **тихий flush memory перед compaction**, щоб нагадати моделі - записати довговічні нотатки перед auto-compaction. Це працює лише тоді, коли workspace - доступний для запису (ізольовані середовища лише для читання це пропускають). Див. [Memory](/uk/concepts/memory). + OpenClaw також виконує **тихий попередній скид пам’яті перед Compaction**, щоб нагадати моделі + записати стійкі нотатки перед автоматичним стисненням. Це виконується лише тоді, коли робоча область + доступна для запису (sandbox-и лише для читання це пропускають). Див. [Пам’ять](/uk/concepts/memory). - - Попросіть бота **записати факт у memory**. Довгострокові нотатки мають бути в `MEMORY.md`, + + Попросіть бота **записати факт у пам’ять**. Довгострокові нотатки мають зберігатися в `MEMORY.md`, короткостроковий контекст — у `memory/YYYY-MM-DD.md`. - Це все ще сфера, яку ми вдосконалюємо. Допомагає нагадувати моделі зберігати спогади; - вона знатиме, що робити. Якщо вона й далі забуває, перевірте, що Gateway використовує той самий - workspace під час кожного запуску. + Це все ще напрям, який ми покращуємо. Корисно нагадувати моделі зберігати спогади; + вона знатиме, що робити. Якщо вона все одно забуває, перевірте, чи Gateway використовує ту саму + робочу область під час кожного запуску. - Документація: [Memory](/uk/concepts/memory), [Робочий простір agent](/uk/concepts/agent-workspace). + Документація: [Пам’ять](/uk/concepts/memory), [Робоча область агента](/uk/concepts/agent-workspace). - - Файли memory живуть на диску й зберігаються, доки ви їх не видалите. Обмеженням є ваше - сховище, а не модель. **Контекст сесії** усе ще обмежений вікном контексту - моделі, тому довгі розмови можуть compact або truncate. Саме тому існує - пошук по memory — він повертає в контекст лише релевантні частини. + + Файли пам’яті зберігаються на диску й залишаються там, доки ви їх не видалите. Обмеженням є ваше + сховище, а не модель. **Контекст сесії** все одно обмежений вікном контексту + моделі, тому довгі розмови можуть стискатися або обрізатися. Саме тому + існує пошук у пам’яті — він повертає в контекст лише релевантні частини. - Документація: [Memory](/uk/concepts/memory), [Контекст](/uk/concepts/context). + Документація: [Пам’ять](/uk/concepts/memory), [Контекст](/uk/concepts/context). - - Лише якщо ви використовуєте **embeddings OpenAI**. OAuth Codex покриває chat/completions і - **не** надає доступу до embeddings, тож **вхід через Codex (OAuth або - вхід через CLI Codex)** не допомагає для семантичного пошуку по memory. Embeddings OpenAI - як і раніше потребують справжнього API key (`OPENAI_API_KEY` або `models.providers.openai.apiKey`). + + Лише якщо ви використовуєте **ембедінги OpenAI**. OAuth Codex покриває chat/completions і + **не** надає доступу до ембедінгів, тому **вхід через Codex (OAuth або + вхід через Codex CLI)** не допомагає для семантичного пошуку в пам’яті. Ембедінги OpenAI + усе ще потребують справжнього API-ключа (`OPENAI_API_KEY` або `models.providers.openai.apiKey`). - Якщо ви явно не задаєте provider, OpenClaw автоматично вибирає provider, коли він - може знайти API key (профілі auth, `models.providers.*.apiKey` або env vars). - Він надає перевагу OpenAI, якщо доступний ключ OpenAI, інакше Gemini, якщо доступний ключ Gemini, - потім Voyage, потім Mistral. Якщо жоден віддалений ключ недоступний, пошук по memory - залишається вимкненим, доки ви його не налаштуєте. Якщо у вас налаштовано й доступний шлях - до локальної моделі, OpenClaw - надає перевагу `local`. Ollama підтримується, коли ви явно задаєте + Якщо ви явно не задаєте провайдера, OpenClaw автоматично вибирає провайдера, коли + може знайти API-ключ (профілі автентифікації, `models.providers.*.apiKey` або змінні середовища). + Він надає перевагу OpenAI, якщо знаходиться ключ OpenAI, інакше Gemini, якщо знаходиться ключ Gemini, + потім Voyage, потім Mistral. Якщо віддалений ключ недоступний, пошук у пам’яті + залишається вимкненим, доки ви його не налаштуєте. Якщо у вас налаштовано й доступний шлях до локальної моделі, OpenClaw + надає перевагу `local`. Ollama підтримується, якщо ви явно задасте `memorySearch.provider = "ollama"`. - Якщо ви хочете залишатися локальними, задайте `memorySearch.provider = "local"` (і за бажанням - `memorySearch.fallback = "none"`). Якщо вам потрібні embeddings Gemini, задайте + Якщо ви віддаєте перевагу локальному варіанту, задайте `memorySearch.provider = "local"` (і за бажанням + `memorySearch.fallback = "none"`). Якщо вам потрібні ембедінги Gemini, задайте `memorySearch.provider = "gemini"` і надайте `GEMINI_API_KEY` (або - `memorySearch.remote.apiKey`). Ми підтримуємо embedding-моделі **OpenAI, Gemini, Voyage, Mistral, Ollama або local** — - подробиці налаштування див. у [Memory](/uk/concepts/memory). + `memorySearch.remote.apiKey`). Ми підтримуємо моделі ембедінгів **OpenAI, Gemini, Voyage, Mistral, Ollama або local** — + подробиці налаштування див. в [Пам’ять](/uk/concepts/memory). @@ -1376,18 +1380,18 @@ x-i18n: ## Де що зберігається на диску - - Ні — **стан OpenClaw є локальним**, але **зовнішні сервіси все одно бачать те, що ви їм надсилаєте**. + + Ні — **стан OpenClaw локальний**, але **зовнішні сервіси все одно бачать те, що ви їм надсилаєте**. - - **Локально за замовчуванням:** sessions, файли memory, config і workspace живуть на хості Gateway - (`~/.openclaw` + каталог вашого workspace). - - **Віддалено за необхідністю:** повідомлення, які ви надсилаєте providers моделей (Anthropic/OpenAI тощо), ідуть до - їхніх API, а чат-платформи (WhatsApp/Telegram/Slack тощо) зберігають дані повідомлень на своїх - серверах. - - **Ви контролюєте слід:** використання локальних моделей зберігає prompts на вашій машині, але трафік - каналів усе одно проходить через сервери каналу. + - **Локально за замовчуванням:** сесії, файли пам’яті, конфігурація та робоча область зберігаються на хості Gateway + (`~/.openclaw` + каталог вашої робочої області). + - **Віддалено за потребою:** повідомлення, які ви надсилаєте провайдерам моделей (Anthropic/OpenAI тощо), потрапляють до + їхніх API, а чат-платформи (WhatsApp/Telegram/Slack тощо) зберігають дані повідомлень на + своїх серверах. + - **Ви контролюєте слід:** використання локальних моделей залишає prompt-и на вашій машині, але трафік + каналів усе одно проходить через сервери відповідного каналу. - Пов’язане: [Робочий простір agent](/uk/concepts/agent-workspace), [Memory](/uk/concepts/memory). + Пов’язане: [Робоча область агента](/uk/concepts/agent-workspace), [Пам’ять](/uk/concepts/memory). @@ -1396,33 +1400,33 @@ x-i18n: | Path | Призначення | | --------------------------------------------------------------- | ------------------------------------------------------------------ | - | `$OPENCLAW_STATE_DIR/openclaw.json` | Основний config (JSON5) | - | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Застарілий імпорт OAuth (копіюється в профілі auth під час першого використання) | - | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Профілі auth (OAuth, API keys і необов’язкові `keyRef`/`tokenRef`) | - | `$OPENCLAW_STATE_DIR/secrets.json` | Необов’язкове файлове секретне корисне навантаження для providers SecretRef типу `file` | - | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Файл сумісності зі застарілими версіями (статичні записи `api_key` очищуються) | - | `$OPENCLAW_STATE_DIR/credentials/` | Стан provider (наприклад `whatsapp//creds.json`) | - | `$OPENCLAW_STATE_DIR/agents/` | Стан для кожного agent окремо (agentDir + sessions) | - | `$OPENCLAW_STATE_DIR/agents//sessions/` | Історія розмов і стан (для кожного agent окремо) | - | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Метадані sessions (для кожного agent окремо) | + | `$OPENCLAW_STATE_DIR/openclaw.json` | Основна конфігурація (JSON5) | + | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Застарілий імпорт OAuth (копіюється в профілі автентифікації під час першого використання) | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Профілі автентифікації (OAuth, API-ключі та опціональні `keyRef`/`tokenRef`) | + | `$OPENCLAW_STATE_DIR/secrets.json` | Необов’язкове файлове сховище секретів для провайдерів `file` SecretRef | + | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Файл застарілої сумісності (статичні записи `api_key` очищаються) | + | `$OPENCLAW_STATE_DIR/credentials/` | Стан провайдерів (наприклад, `whatsapp//creds.json`) | + | `$OPENCLAW_STATE_DIR/agents/` | Стан на рівні агента (agentDir + сесії) | + | `$OPENCLAW_STATE_DIR/agents//sessions/` | Історія розмов і стан (для кожного агента) | + | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Метадані сесій (для кожного агента) | - Застарілий шлях для одного agent: `~/.openclaw/agent/*` (мігрується через `openclaw doctor`). + Застарілий шлях для одного агента: `~/.openclaw/agent/*` (мігрується через `openclaw doctor`). - Ваш **workspace** (`AGENTS.md`, файли memory, skills тощо) зберігається окремо й налаштовується через `agents.defaults.workspace` (типово: `~/.openclaw/workspace`). + Ваша **робоча область** (`AGENTS.md`, файли пам’яті, Skills тощо) зберігається окремо й налаштовується через `agents.defaults.workspace` (типово: `~/.openclaw/workspace`). - Ці файли зберігаються в **workspace agent**, а не в `~/.openclaw`. + Ці файли зберігаються в **робочій області агента**, а не в `~/.openclaw`. - - **Workspace (для кожного agent):** `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, - `MEMORY.md`, `memory/YYYY-MM-DD.md`, необов’язковий `HEARTBEAT.md`. - `memory.md` у нижньому регістрі в корені — це лише вхід для виправлення застарілих версій; `openclaw doctor --fix` + - **Робоча область (для кожного агента):** `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, + `MEMORY.md`, `memory/YYYY-MM-DD.md`, опціонально `HEARTBEAT.md`. + `memory.md` у нижньому регістрі в корені — це лише вхід для виправлення застарілих даних; `openclaw doctor --fix` може об’єднати його в `MEMORY.md`, коли існують обидва файли. - - **Каталог стану (`~/.openclaw`)**: config, стан channel/provider, профілі auth, sessions, logs, - і спільні skills (`~/.openclaw/skills`). + - **Каталог стану (`~/.openclaw`)**: конфігурація, стан каналів/провайдерів, профілі автентифікації, сесії, журнали + та спільні Skills (`~/.openclaw/skills`). - Типовий workspace: `~/.openclaw/workspace`, налаштовується через: + Робоча область за замовчуванням — `~/.openclaw/workspace`, її можна налаштувати через: ```json5 { @@ -1430,27 +1434,27 @@ x-i18n: } ``` - Якщо бот «забуває» після перезапуску, переконайтеся, що Gateway використовує той самий - workspace під час кожного запуску (і пам’ятайте: remote mode використовує workspace **хоста gateway**, + Якщо бот «забуває» після перезапуску, переконайтеся, що Gateway використовує ту саму + робочу область під час кожного запуску (і пам’ятайте: у віддаленому режимі використовується **робоча область хоста gateway**, а не вашого локального ноутбука). - Порада: якщо ви хочете закріпити поведінку або вподобання надовго, попросіть бота **записати це в - AGENTS.md або MEMORY.md**, а не покладатися на історію чату. + Порада: якщо вам потрібна стійка поведінка або вподобання, попросіть бота **записати це в + AGENTS.md або MEMORY.md**, а не покладайтеся на історію чату. - Див. [Робочий простір agent](/uk/concepts/agent-workspace) і [Memory](/uk/concepts/memory). + Див. [Робоча область агента](/uk/concepts/agent-workspace) і [Пам’ять](/uk/concepts/memory). - Помістіть свій **workspace agent** у **приватний** git-репозиторій і зберігайте його резервну копію десь - приватно (наприклад у приватному GitHub). Це збереже memory + файли AGENTS/SOUL/USER - і дасть змогу пізніше відновити «розум» assistant. + Помістіть свою **робочу область агента** у **приватний** git-репозиторій і створюйте її резервні копії десь + у приватному місці (наприклад, у приватному GitHub). Це зберігає пам’ять + файли AGENTS/SOUL/USER + і дає змогу пізніше відновити «свідомість» помічника. - **Не** робіть commit нічого з `~/.openclaw` (credentials, sessions, tokens або зашифровані секретні корисні навантаження). - Якщо вам потрібне повне відновлення, створюйте резервні копії і workspace, і каталогу стану - окремо (див. запитання про міграцію вище). + **Не** комітьте нічого з `~/.openclaw` (облікові дані, сесії, токени або зашифровані payload-и секретів). + Якщо вам потрібне повне відновлення, окремо створюйте резервні копії і робочої області, і каталогу стану + (див. запитання про міграцію вище). - Документація: [Робочий простір agent](/uk/concepts/agent-workspace). + Документація: [Робоча область агента](/uk/concepts/agent-workspace). @@ -1458,16 +1462,16 @@ x-i18n: Див. окремий посібник: [Видалення](/uk/install/uninstall). - - Так. Workspace — це **типовий cwd** і прив’язка memory, а не жорстка ізоляція. - Відносні шляхи розв’язуються всередині workspace, але абсолютні шляхи можуть звертатися до інших - розташувань хоста, якщо ізоляцію не ввімкнено. Якщо вам потрібна ізоляція, використовуйте - [`agents.defaults.sandbox`](/uk/gateway/sandboxing) або налаштування ізоляції для окремих agents. Якщо ви - хочете, щоб репозиторій був типовим робочим каталогом, вкажіть - `workspace` цього agent на корінь репозиторію. Репозиторій OpenClaw — це лише вихідний код; тримайте - workspace окремо, якщо тільки ви свідомо не хочете, щоб agent працював усередині нього. + + Так. Робоча область — це **cwd за замовчуванням** і якір пам’яті, а не жорсткий sandbox. + Відносні шляхи розв’язуються всередині робочої області, але абсолютні шляхи можуть отримувати доступ до інших + розташувань хоста, якщо sandboxing не ввімкнено. Якщо вам потрібна ізоляція, використовуйте + [`agents.defaults.sandbox`](/uk/gateway/sandboxing) або налаштування sandbox на рівні агента. Якщо ви + хочете, щоб репозиторій був робочим каталогом за замовчуванням, вкажіть для цього агента + `workspace` на корінь репозиторію. Репозиторій OpenClaw — це лише вихідний код; тримайте + робочу область окремо, якщо тільки ви свідомо не хочете, щоб агент працював усередині нього. - Приклад (репозиторій як типовий cwd): + Приклад (репозиторій як cwd за замовчуванням): ```json5 { @@ -1481,30 +1485,30 @@ x-i18n: - - Стан sessions належить **хосту gateway**. Якщо ви в remote mode, потрібне вам сховище sessions перебуває на віддаленій машині, а не на вашому локальному ноутбуці. Див. [Керування sessions](/uk/concepts/session). + + Станом сесій володіє **хост gateway**. Якщо ви працюєте у віддаленому режимі, потрібне вам сховище сесій знаходиться на віддаленій машині, а не на вашому локальному ноутбуці. Див. [Керування сесіями](/uk/concepts/session). -## Основи config +## Основи конфігурації - - OpenClaw читає необов’язковий config **JSON5** з `$OPENCLAW_CONFIG_PATH` (типово: `~/.openclaw/openclaw.json`): + + OpenClaw читає необов’язкову конфігурацію **JSON5** з `$OPENCLAW_CONFIG_PATH` (типово: `~/.openclaw/openclaw.json`): ``` $OPENCLAW_CONFIG_PATH ``` - Якщо файл відсутній, використовуються доволі безпечні значення за замовчуванням (зокрема типовий workspace `~/.openclaw/workspace`). + Якщо файл відсутній, використовуються відносно безпечні значення за замовчуванням (зокрема робоча область за замовчуванням `~/.openclaw/workspace`). - - Bind не-loopback **потребують коректного шляху auth gateway**. На практиці це означає: + + Прив’язки не-loopback **потребують дійсного шляху автентифікації gateway**. На практиці це означає: - - auth зі спільним секретом: токен або пароль - - `gateway.auth.mode: "trusted-proxy"` за правильно налаштованим не-loopback reverse proxy з awareness ідентичності + - автентифікація за спільним секретом: токен або пароль + - `gateway.auth.mode: "trusted-proxy"` за правильно налаштованим identity-aware reverse proxy без loopback ```json5 { @@ -1520,32 +1524,32 @@ x-i18n: Примітки: - - `gateway.remote.token` / `.password` **самі по собі** не вмикають auth локального gateway. - - Локальні шляхи виклику можуть використовувати `gateway.remote.*` як запасний варіант лише тоді, коли `gateway.auth.*` не задано. - - Для auth паролем задайте `gateway.auth.mode: "password"` плюс `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). - - Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і їх не вдається розв’язати, розв’язання надійно завершується помилкою (без маскувального запасного варіанта через remote). - - Налаштування Control UI зі спільним секретом автентифікуються через `connect.params.auth.token` або `connect.params.auth.password` (зберігаються в налаштуваннях app/UI). Режими з передаванням ідентичності, як-от Tailscale Serve або `trusted-proxy`, натомість використовують заголовки запиту. Не розміщуйте спільні секрети в URL. - - За `gateway.auth.mode: "trusted-proxy"` reverse proxy loopback на тому самому хості все одно **не** задовольняють auth trusted-proxy. Trusted proxy має бути налаштованим джерелом не-loopback. + - `gateway.remote.token` / `.password` самі по собі **не** вмикають локальну автентифікацію gateway. + - Локальні шляхи виклику можуть використовувати `gateway.remote.*` як запасний варіант лише коли `gateway.auth.*` не задано. + - Для автентифікації за паролем задайте натомість `gateway.auth.mode: "password"` плюс `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). + - Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef, але не розв’язано, розв’язання завершується за принципом fail closed (без маскування запасним варіантом remote). + - Конфігурації Control UI зі спільним секретом проходять автентифікацію через `connect.params.auth.token` або `connect.params.auth.password` (зберігаються в налаштуваннях застосунку/UI). Режими з ідентифікацією, такі як Tailscale Serve або `trusted-proxy`, натомість використовують заголовки запиту. Уникайте розміщення спільних секретів у URL. + - З `gateway.auth.mode: "trusted-proxy"` reverse proxy з loopback на тому самому хості все одно **не** задовольняють trusted-proxy auth. Trusted proxy має бути налаштованим джерелом без loopback. - OpenClaw типово примусово вимагає auth gateway, зокрема й на loopback. У звичайному типовому сценарії це означає auth токеном: якщо жоден явний шлях auth не налаштовано, під час запуску gateway вибирається режим токена і він автоматично генерується, зберігаючись у `gateway.auth.token`, тож **локальні WS clients мають проходити автентифікацію**. Це блокує іншим локальним процесам виклик Gateway. + OpenClaw типово примусово вимагає автентифікацію gateway, включно з loopback. У звичайному типового сценарії це означає автентифікацію токеном: якщо явний шлях автентифікації не налаштовано, запуск gateway переходить у режим токена й автоматично генерує його, зберігаючи в `gateway.auth.token`, тож **локальні WS-клієнти мають проходити автентифікацію**. Це блокує іншим локальним процесам виклики Gateway. - Якщо ви віддаєте перевагу іншому шляху auth, ви можете явно вибрати режим пароля (або, для не-loopback reverse proxy з awareness ідентичності, `trusted-proxy`). Якщо ви **справді** хочете відкритий loopback, явно задайте `gateway.auth.mode: "none"` у своєму config. Doctor може будь-коли згенерувати для вас токен: `openclaw doctor --generate-gateway-token`. + Якщо ви віддаєте перевагу іншому шляху автентифікації, можете явно вибрати режим пароля (або, для identity-aware reverse proxy без loopback, `trusted-proxy`). Якщо ви **справді** хочете відкритий loopback, явно задайте `gateway.auth.mode: "none"` у своїй конфігурації. Doctor може згенерувати токен для вас у будь-який момент: `openclaw doctor --generate-gateway-token`. - - Gateway стежить за config і підтримує hot-reload: + + Gateway відстежує конфігурацію та підтримує гаряче перезавантаження: - - `gateway.reload.mode: "hybrid"` (типово): безпечно застосовує зміни гаряче, для критичних — перезапускає + - `gateway.reload.mode: "hybrid"` (типово): безпечно застосовує зміни на льоту, перезапускається для критичних змін - також підтримуються `hot`, `restart`, `off` - - Задайте `cli.banner.taglineMode` у config: + + Задайте `cli.banner.taglineMode` у конфігурації: ```json5 { @@ -1557,24 +1561,24 @@ x-i18n: } ``` - - `off`: приховує текст tagline, але залишає рядок заголовка/версії banner. + - `off`: приховує текст підзаголовка, але зберігає рядок назви/версії банера. - `default`: щоразу використовує `All your chats, one OpenClaw.`. - - `random`: ротація кумедних/сезонних tagline (типова поведінка). - - Якщо ви хочете взагалі прибрати banner, задайте env `OPENCLAW_HIDE_BANNER=1`. + - `random`: обертові кумедні/сезонні підзаголовки (поведінка за замовчуванням). + - Якщо ви не хочете банера взагалі, задайте змінну середовища `OPENCLAW_HIDE_BANNER=1`. - - `web_fetch` працює без API key. `web_search` залежить від вибраного - provider: + + `web_fetch` працює без API-ключа. `web_search` залежить від вибраного + провайдера: - - Providers на основі API, як-от Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity і Tavily, потребують звичайного налаштування API key. - - Ollama Web Search не потребує ключа, але використовує налаштований хост Ollama і вимагає `ollama signin`. + - Провайдери на основі API, такі як Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity і Tavily, потребують звичайного налаштування API-ключа. + - Ollama Web Search не потребує ключа, але використовує налаштований хост Ollama й вимагає `ollama signin`. - DuckDuckGo не потребує ключа, але це неофіційна інтеграція на основі HTML. - - SearXNG не потребує ключа / є self-hosted; налаштуйте `SEARXNG_BASE_URL` або `plugins.entries.searxng.config.webSearch.baseUrl`. + - SearXNG не потребує ключа/є самостійно розгорнутим; налаштуйте `SEARXNG_BASE_URL` або `plugins.entries.searxng.config.webSearch.baseUrl`. - **Рекомендовано:** виконайте `openclaw configure --section web` і виберіть provider. - Альтернативи через середовище: + **Рекомендовано:** запустіть `openclaw configure --section web` і виберіть провайдера. + Альтернативи через змінні середовища: - Brave: `BRAVE_API_KEY` - Exa: `EXA_API_KEY` @@ -1609,76 +1613,76 @@ x-i18n: }, fetch: { enabled: true, - provider: "firecrawl", // необов’язково; пропустіть для auto-detect + provider: "firecrawl", // optional; omit for auto-detect }, }, }, } ``` - Конфігурація web-search, специфічна для provider, тепер розміщується в `plugins.entries..config.webSearch.*`. - Застарілі шляхи provider `tools.web.search.*` усе ще тимчасово завантажуються для сумісності, але їх не слід використовувати для нових config. - Резервна конфігурація Firecrawl web-fetch розміщується в `plugins.entries.firecrawl.config.webFetch.*`. + Конфігурація вебпошуку для конкретного провайдера тепер зберігається в `plugins.entries..config.webSearch.*`. + Застарілі шляхи провайдерів `tools.web.search.*` усе ще тимчасово завантажуються для сумісності, але їх не слід використовувати для нових конфігурацій. + Конфігурація запасного варіанта web-fetch Firecrawl зберігається в `plugins.entries.firecrawl.config.webFetch.*`. Примітки: - Якщо ви використовуєте allowlist, додайте `web_search`/`web_fetch`/`x_search` або `group:web`. - - `web_fetch` типово увімкнено (якщо його явно не вимкнути). - - Якщо `tools.web.fetch.provider` пропущено, OpenClaw автоматично визначає першого готового fallback-provider для fetch на основі доступних облікових даних. Наразі вбудований provider — це Firecrawl. - - Daemon читають env vars з `~/.openclaw/.env` (або з середовища служби). + - `web_fetch` увімкнено за замовчуванням (якщо його явно не вимкнено). + - Якщо `tools.web.fetch.provider` пропущено, OpenClaw автоматично визначає першого готового провайдера запасного варіанта fetch на основі доступних облікових даних. Наразі вбудованим провайдером є Firecrawl. + - Демони читають змінні середовища з `~/.openclaw/.env` (або із середовища сервісу). - Документація: [Web tools](/uk/tools/web). + Документація: [Вебінструменти](/uk/tools/web). - - `config.apply` замінює **весь config**. Якщо ви надсилаєте частковий об’єкт, усе - інше видаляється. + + `config.apply` замінює **всю конфігурацію цілком**. Якщо ви надсилаєте частковий об’єкт, усе + інше буде видалено. Поточний OpenClaw захищає від багатьох випадкових перезаписів: - - Записи config, що належать OpenClaw, перевіряють повний config після зміни перед записом. - - Недійсні або руйнівні записи, що належать OpenClaw, відхиляються і зберігаються як `openclaw.json.rejected.*`. - - Якщо пряме редагування ламає startup або hot reload, Gateway відновлює останній відомий справний config і зберігає відхилений файл як `openclaw.json.clobbered.*`. - - Після відновлення основний agent отримує попередження під час завантаження, щоб не записати поганий config знову навмання. + - Записи конфігурації, керовані OpenClaw, перевіряють повну конфігурацію після змін перед записом. + - Недійсні або руйнівні записи, керовані OpenClaw, відхиляються й зберігаються як `openclaw.json.rejected.*`. + - Якщо пряме редагування ламає запуск або гаряче перезавантаження, Gateway відновлює останню відому справну конфігурацію й зберігає відхилений файл як `openclaw.json.clobbered.*`. + - Після відновлення основний агент отримує попередження під час запуску, щоб він не перезаписав погану конфігурацію знову навмання. Відновлення: - Перевірте `openclaw logs --follow` на наявність `Config auto-restored from last-known-good`, `Config write rejected:` або `config reload restored last-known-good config`. - - Перегляньте найновіший `openclaw.json.clobbered.*` або `openclaw.json.rejected.*` поруч з активним config. - - Залиште активний відновлений config, якщо він працює, а потім поверніть лише потрібні ключі через `openclaw config set` або `config.patch`. - - Виконайте `openclaw config validate` і `openclaw doctor`. - - Якщо у вас немає last-known-good або відхиленого payload, відновіть з резервної копії або повторно виконайте `openclaw doctor` і заново налаштуйте channels/models. - - Якщо це було неочікувано, створіть bug report і додайте свій останній відомий config або будь-яку резервну копію. - - Локальний coding agent часто може відновити робочий config з логів або історії. + - Перегляньте найновіший `openclaw.json.clobbered.*` або `openclaw.json.rejected.*` поруч з активною конфігурацією. + - Якщо відновлена активна конфігурація працює, залиште її, а потім поверніть лише потрібні ключі через `openclaw config set` або `config.patch`. + - Запустіть `openclaw config validate` і `openclaw doctor`. + - Якщо у вас немає останньої відомої справної конфігурації або відхиленого payload, відновіть із резервної копії або повторно запустіть `openclaw doctor` і заново налаштуйте канали/моделі. + - Якщо це було неочікувано, створіть bug report і додайте свою останню відому конфігурацію або будь-яку резервну копію. + - Локальний агент для кодування часто може відновити робочу конфігурацію з журналів або історії. Як уникнути цього: - Використовуйте `openclaw config set` для невеликих змін. - Використовуйте `openclaw configure` для інтерактивного редагування. - - Спершу використовуйте `config.schema.lookup`, якщо не впевнені в точному шляху або формі поля; він повертає вузол поверхневої схеми та підсумки безпосередніх дочірніх елементів для подальшого заглиблення. - - Використовуйте `config.patch` для часткових RPC-редагувань; залиште `config.apply` лише для повної заміни config. - - Якщо ви використовуєте tool `gateway` тільки для власника з запуску agent, він усе одно відхилятиме записи в `tools.exec.ask` / `tools.exec.security` (включно із застарілими псевдонімами `tools.bash.*`, які нормалізуються до тих самих захищених шляхів exec). + - Спочатку використовуйте `config.schema.lookup`, якщо не впевнені щодо точного шляху або форми поля; він повертає вузол поверхневої схеми та зведення безпосередніх дочірніх елементів для подальшого заглиблення. + - Використовуйте `config.patch` для часткових RPC-редагувань; залишайте `config.apply` лише для повної заміни конфігурації. + - Якщо ви використовуєте owner-only інструмент `gateway` з запуску агента, він усе одно відхилятиме записи в `tools.exec.ask` / `tools.exec.security` (включно із застарілими псевдонімами `tools.bash.*`, які нормалізуються до тих самих захищених шляхів exec). - Документація: [Config](/uk/cli/config), [Configure](/uk/cli/configure), [Усунення несправностей Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config), [Doctor](/uk/gateway/doctor). + Документація: [Конфігурація](/uk/cli/config), [Налаштування](/uk/cli/configure), [Усунення несправностей Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config), [Doctor](/uk/gateway/doctor). - - Поширений шаблон — **один Gateway** (наприклад, Raspberry Pi) плюс **nodes** і **agents**: + + Поширений шаблон — це **один Gateway** (наприклад, Raspberry Pi) плюс **nodes** і **agents**: - - **Gateway (центральний):** володіє channels (Signal/WhatsApp), маршрутизацією та sessions. - - **Nodes (пристрої):** Mac/iOS/Android підключаються як периферія і надають локальні tools (`system.run`, `canvas`, `camera`). - - **Agents (workers):** окремі brain/workspace для спеціальних ролей (наприклад, «Hetzner ops», «Personal data»). - - **Sub-agents:** запускають фонову роботу з основного agent, коли вам потрібен паралелізм. - - **TUI:** підключається до Gateway і перемикає agents/sessions. + - **Gateway (центральний):** володіє каналами (Signal/WhatsApp), маршрутизацією та сесіями. + - **Nodes (пристрої):** Mac/iOS/Android під’єднуються як периферія й надають локальні інструменти (`system.run`, `canvas`, `camera`). + - **Agents (worker-и):** окремі brain/workspace для спеціалізованих ролей (наприклад, «Hetzner ops», «Personal data»). + - **Субагенти:** запускають фонову роботу з основного агента, коли потрібен паралелізм. + - **TUI:** під’єднується до Gateway і перемикає агентів/сесії. - Документація: [Nodes](/uk/nodes), [Віддалений доступ](/uk/gateway/remote), [Маршрутизація Multi-Agent](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [TUI](/uk/web/tui). + Документація: [Nodes](/uk/nodes), [Віддалений доступ](/uk/gateway/remote), [Маршрутизація мультиагентності](/uk/concepts/multi-agent), [Субагенти](/uk/tools/subagents), [TUI](/uk/web/tui). - - Так. Це параметр config: + + Так. Це параметр конфігурації: ```json5 { @@ -1691,47 +1695,47 @@ x-i18n: } ``` - Типове значення — `false` (headful). Режим headless із більшою ймовірністю запускає anti-bot перевірки на деяких сайтах. Див. [Browser](/uk/tools/browser). + Значення за замовчуванням — `false` (headful). Headless-режим частіше викликає anti-bot перевірки на деяких сайтах. Див. [Браузер](/uk/tools/browser). Headless використовує **той самий рушій Chromium** і працює для більшості сценаріїв автоматизації (форми, кліки, скрейпінг, входи). Основні відмінності: - - Немає видимого вікна браузера (якщо потрібна візуалізація, використовуйте знімки екрана). - - Деякі сайти суворіше ставляться до автоматизації в режимі headless (CAPTCHA, anti-bot). - Наприклад, X/Twitter часто блокує сесії headless. + - Немає видимого вікна браузера (використовуйте скриншоти, якщо вам потрібне візуальне підтвердження). + - Деякі сайти суворіше ставляться до автоматизації в headless-режимі (CAPTCHA, anti-bot). + Наприклад, X/Twitter часто блокує headless-сесії. - - Задайте `browser.executablePath` на ваш бінарний файл Brave (або будь-який browser на базі Chromium) і перезапустіть Gateway. - Повні приклади config див. у [Browser](/uk/tools/browser#use-brave-or-another-chromium-based-browser). + + Задайте `browser.executablePath` на ваш бінарний файл Brave (або будь-який браузер на базі Chromium) і перезапустіть Gateway. + Повні приклади конфігурації див. в [Браузер](/uk/tools/browser#use-brave-or-another-chromium-based-browser). ## Віддалені gateway і nodes - - Повідомлення Telegram обробляються **gateway**. Gateway запускає agent і - лише потім викликає nodes через **Gateway WebSocket**, коли потрібен node tool: + + Повідомлення Telegram обробляються **gateway**. Gateway запускає агента і + лише потім викликає nodes через **Gateway WebSocket**, коли потрібен інструмент node: Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram - Nodes не бачать вхідний трафік provider; вони отримують лише виклики node RPC. + Nodes не бачать вхідний трафік провайдерів; вони отримують лише виклики node RPC. - + Коротка відповідь: **під’єднайте свій комп’ютер як node**. Gateway працює деінде, але він може - викликати tools `node.*` (екран, камера, система) на вашій локальній машині через Gateway WebSocket. + викликати інструменти `node.*` (screen, camera, system) на вашій локальній машині через Gateway WebSocket. Типове налаштування: - 1. Запустіть Gateway на хості, який завжди ввімкнений (VPS/домашній сервер). - 2. Додайте хост Gateway і свій комп’ютер до однієї tailnet. - 3. Переконайтеся, що Gateway WS доступний (bind tailnet або SSH tunnel). - 4. Відкрийте локально застосунок macOS і підключіться в режимі **Remote over SSH** (або напряму через tailnet), + 1. Запустіть Gateway на хості, який завжди увімкнений (VPS/домашній сервер). + 2. Підключіть хост Gateway і ваш комп’ютер до однієї tailnet. + 3. Переконайтеся, що Gateway WS доступний (tailnet bind або SSH-тунель). + 4. Локально відкрийте застосунок macOS і підключіться в режимі **Remote over SSH** (або напряму через tailnet), щоб він міг зареєструватися як node. - 5. Схваліть node на Gateway: + 5. Підтвердьте node на Gateway: ```bash openclaw devices list @@ -1740,7 +1744,7 @@ x-i18n: Окремий TCP-міст не потрібен; nodes підключаються через Gateway WebSocket. - Нагадування щодо безпеки: під’єднання macOS Node дозволяє `system.run` на цій машині. Під’єднуйте + Нагадування щодо безпеки: прив’язка macOS node дозволяє `system.run` на цій машині. Під’єднуйте лише пристрої, яким довіряєте, і перегляньте [Безпека](/uk/gateway/security). Документація: [Nodes](/uk/nodes), [Протокол Gateway](/uk/gateway/protocol), [Віддалений режим macOS](/uk/platforms/mac/remote), [Безпека](/uk/gateway/security). @@ -1752,93 +1756,92 @@ x-i18n: - Gateway працює: `openclaw gateway status` - Стан Gateway: `openclaw status` - - Стан channel: `openclaw channels status` + - Стан каналів: `openclaw channels status` - Потім перевірте auth і маршрутизацію: + Потім перевірте автентифікацію та маршрутизацію: - - Якщо ви використовуєте Tailscale Serve, переконайтеся, що `gateway.auth.allowTailscale` налаштовано правильно. - - Якщо ви підключаєтеся через SSH tunnel, підтвердьте, що локальний tunnel активний і вказує на правильний порт. - - Переконайтеся, що ваші allowlist (DM або group) містять ваш обліковий запис. + - Якщо ви використовуєте Tailscale Serve, переконайтеся, що `gateway.auth.allowTailscale` задано правильно. + - Якщо ви підключаєтеся через SSH-тунель, переконайтеся, що локальний тунель активний і вказує на правильний порт. + - Переконайтеся, що ваші allowlist-и (DM або група) містять ваш обліковий запис. - Документація: [Tailscale](/uk/gateway/tailscale), [Віддалений доступ](/uk/gateway/remote), [Channels](/uk/channels). + Документація: [Tailscale](/uk/gateway/tailscale), [Віддалений доступ](/uk/gateway/remote), [Канали](/uk/channels). - - Так. Вбудованого мосту «bot-to-bot» немає, але це можна під’єднати кількома + + Так. Вбудованого мосту «bot-to-bot» немає, але це можна налаштувати кількома надійними способами: - **Найпростіше:** використовуйте звичайний chat channel, до якого мають доступ обидва боти (Telegram/Slack/WhatsApp). - Нехай Bot A надішле повідомлення Bot B, а тоді Bot B відповість як зазвичай. + **Найпростіше:** використовуйте звичайний чат-канал, до якого мають доступ обидва боти (Telegram/Slack/WhatsApp). + Нехай Bot A надішле повідомлення Bot B, а потім Bot B відповість як зазвичай. - **CLI-міст (загальний):** запустіть скрипт, який викликає інший Gateway через - `openclaw agent --message ... --deliver`, націлюючи його на чат, де слухає інший бот. - Якщо один бот працює на віддаленому VPS, націльте свій CLI на цей віддалений Gateway + **Міст через CLI (загальний варіант):** запустіть скрипт, який викликає інший Gateway через + `openclaw agent --message ... --deliver`, націлюючись на чат, який слухає інший бот. + Якщо один бот працює на віддаленому VPS, налаштуйте ваш CLI на цей віддалений Gateway через SSH/Tailscale (див. [Віддалений доступ](/uk/gateway/remote)). - Приклад шаблону (запускайте з машини, яка може досягти цільового Gateway): + Приклад шаблону (виконується на машині, яка може досягти цільового Gateway): ```bash openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` - Порада: додайте запобіжник, щоб два боти не зациклювалися без кінця (лише згадки, channel - allowlist або правило «не відповідати на повідомлення ботів»). + Порада: додайте запобіжник, щоб два боти не зациклилися в нескінченному обміні відповідями (лише згадки, allowlist-и каналів або правило «не відповідати на повідомлення ботів»). - Документація: [Віддалений доступ](/uk/gateway/remote), [CLI Agent](/uk/cli/agent), [Надсилання Agent](/uk/tools/agent-send). + Документація: [Віддалений доступ](/uk/gateway/remote), [CLI агента](/uk/cli/agent), [Надсилання агентом](/uk/tools/agent-send). - - Ні. Один Gateway може розміщувати кількох agents, кожен зі своїм workspace, типовими моделями - та маршрутизацією. Це нормальний варіант налаштування, і він значно дешевший і простіший, ніж запускати - один VPS на кожного agent. + + Ні. Один Gateway може розміщувати кількох агентів, кожен із власною робочою областю, моделями за замовчуванням + та маршрутизацією. Це нормальне налаштування, і воно набагато дешевше та простіше, ніж запускати + один VPS на агента. Використовуйте окремі VPS лише тоді, коли вам потрібна жорстка ізоляція (межі безпеки) або дуже - різні config, якими ви не хочете ділитися. В іншому разі тримайте один Gateway і - використовуйте кількох agents або sub-agents. + різні конфігурації, які ви не хочете спільно використовувати. В інших випадках тримайте один Gateway і + використовуйте кількох агентів або субагентів. Так — nodes є основним способом доступу до вашого ноутбука з віддаленого Gateway, і вони - відкривають більше, ніж просто доступ до оболонки. Gateway працює на macOS/Linux (Windows через WSL2) і є - легким (достатньо невеликого VPS або пристрою класу Raspberry Pi; 4 GB RAM більш ніж вистачає), тому типовий - варіант — це хост, що завжди ввімкнений, плюс ваш ноутбук як node. + дають більше, ніж просто доступ до оболонки. Gateway працює на macOS/Linux (Windows через WSL2) і є + легковажним (невеликий VPS або пристрій класу Raspberry Pi цілком підходить; 4 GB RAM більш ніж достатньо), тож поширене + налаштування — це завжди увімкнений хост плюс ваш ноутбук як node. - **Не потрібен вхідний SSH.** Nodes самі підключаються до Gateway WebSocket і використовують pairing пристроїв. - - **Безпечніший контроль виконання.** `system.run` обмежується allowlist/схваленнями node на цьому ноутбуці. + - **Безпечніший контроль виконання.** `system.run` контролюється allowlist-ами/підтвердженнями node на цьому ноутбуці. - **Більше інструментів пристрою.** Nodes надають `canvas`, `camera` і `screen` на додачу до `system.run`. - - **Локальна автоматизація browser.** Тримайте Gateway на VPS, але запускайте Chrome локально через node host на ноутбуці або під’єднуйтеся до локального Chrome на хості через Chrome MCP. + - **Локальна автоматизація браузера.** Тримайте Gateway на VPS, але запускайте Chrome локально через хост node на ноутбуці або підключайтеся до локального Chrome на хості через Chrome MCP. - SSH підходить для разового доступу до оболонки, але nodes простіші для постійних робочих процесів agent і - автоматизації пристроїв. + SSH підходить для разового доступу до оболонки, але nodes простіші для постійних робочих процесів агента й + автоматизації пристрою. - Документація: [Nodes](/uk/nodes), [CLI Nodes](/uk/cli/nodes), [Browser](/uk/tools/browser). + Документація: [Nodes](/uk/nodes), [CLI Nodes](/uk/cli/nodes), [Браузер](/uk/tools/browser). - - Ні. На хості має працювати лише **один gateway**, якщо тільки ви свідомо не запускаєте ізольовані профілі (див. [Кілька gateway](/uk/gateway/multiple-gateways)). Nodes — це периферійні елементи, які підключаються - до gateway (nodes iOS/Android або macOS у «режимі node» в застосунку рядка меню). Для headless node - hosts і керування через CLI див. [CLI Node host](/uk/cli/node). + + Ні. На одному хості має працювати лише **один gateway**, якщо тільки ви свідомо не запускаєте ізольовані профілі (див. [Кілька gateway](/uk/gateway/multiple-gateways)). Nodes — це периферійні компоненти, які підключаються + до gateway (nodes iOS/Android або macOS «режим node» у застосунку рядка меню). Для headless-хостів node + і керування через CLI див. [CLI хоста Node](/uk/cli/node). - Повний перезапуск потрібен для змін `gateway`, `discovery` і `canvasHost`. + Для змін `gateway`, `discovery` і `canvasHost` потрібен повний перезапуск. - + Так. - - `config.schema.lookup`: перевіряє одне піддерево config із його вузлом поверхневої схеми, відповідною UI-підказкою та підсумками безпосередніх дочірніх елементів перед записом - - `config.get`: отримує поточний snapshot + hash - - `config.patch`: безпечне часткове оновлення (рекомендовано для більшості редагувань RPC); виконує hot-reload, коли можливо, і перезапуск, коли потрібно - - `config.apply`: перевіряє й замінює весь config; виконує hot-reload, коли можливо, і перезапуск, коли потрібно - - Інструмент виконання `gateway` лише для власника, як і раніше, відмовляється переписувати `tools.exec.ask` / `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec + - `config.schema.lookup`: перевіряє одне піддерево конфігурації з його вузлом поверхневої схеми, відповідною UI-підказкою та зведеннями безпосередніх дочірніх елементів перед записом + - `config.get`: отримує поточний знімок + hash + - `config.patch`: безпечне часткове оновлення (рекомендовано для більшості RPC-редагувань); гаряче перезавантажує, коли це можливо, і перезапускає, коли потрібно + - `config.apply`: перевіряє й замінює всю конфігурацію; гаряче перезавантажує, коли це можливо, і перезапускає, коли потрібно + - owner-only runtime-інструмент `gateway` усе ще відмовляється переписувати `tools.exec.ask` / `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec - + ```json5 { agents: { defaults: { workspace: "~/.openclaw/workspace" } }, @@ -1846,25 +1849,25 @@ x-i18n: } ``` - Це задає ваш workspace і обмежує, хто може активувати бота. + Це задає вашу робочу область і обмежує, хто може запускати бота. Мінімальні кроки: - 1. **Встановіть і виконайте вхід на VPS** + 1. **Встановіть + увійдіть на VPS** ```bash curl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up ``` - 2. **Встановіть і виконайте вхід на Mac** - - Використайте застосунок Tailscale і увійдіть до тієї самої tailnet. + 2. **Встановіть + увійдіть на своєму Mac** + - Використайте застосунок Tailscale і увійдіть у ту саму tailnet. 3. **Увімкніть MagicDNS (рекомендовано)** - У консолі адміністратора Tailscale увімкніть MagicDNS, щоб VPS мав стабільне ім’я. - 4. **Використовуйте ім’я хоста tailnet** + 4. **Використовуйте hostname tailnet** - SSH: `ssh user@your-vps.tailnet-xxxx.ts.net` - Gateway WS: `ws://your-vps.tailnet-xxxx.ts.net:18789` @@ -1874,19 +1877,19 @@ x-i18n: openclaw gateway --tailscale serve ``` - Це залишає gateway прив’язаним до loopback і відкриває HTTPS через Tailscale. Див. [Tailscale](/uk/gateway/tailscale). + Це залишає gateway прив’язаним до loopback і надає HTTPS через Tailscale. Див. [Tailscale](/uk/gateway/tailscale). - + Serve відкриває **Gateway Control UI + WS**. Nodes підключаються через ту саму кінцеву точку Gateway WS. Рекомендоване налаштування: - 1. **Переконайтеся, що VPS і Mac перебувають в одній tailnet**. - 2. **Використовуйте застосунок macOS у режимі Remote** (ціллю SSH може бути ім’я хоста tailnet). - Застосунок протунелює порт Gateway і підключиться як node. - 3. **Схваліть node** на gateway: + 1. **Переконайтеся, що VPS + Mac знаходяться в одній tailnet**. + 2. **Використовуйте застосунок macOS у віддаленому режимі** (ціллю SSH може бути hostname tailnet). + Застосунок тунелюватиме порт Gateway і підключиться як node. + 3. **Підтвердьте node** на gateway: ```bash openclaw devices list @@ -1899,8 +1902,8 @@ x-i18n: Якщо вам потрібні лише **локальні інструменти** (screen/camera/exec) на другому ноутбуці, додайте його як - **node**. Це зберігає один Gateway і дозволяє уникнути дублювання config. Локальні інструменти node - наразі доступні лише для macOS, але ми плануємо розширити їх на інші ОС. + **node**. Це дозволяє зберегти один Gateway і уникнути дублювання конфігурації. Локальні інструменти node + зараз доступні лише на macOS, але ми плануємо поширити їх і на інші ОС. Встановлюйте другий Gateway лише тоді, коли вам потрібна **жорстка ізоляція** або два повністю окремі боти. @@ -1912,15 +1915,15 @@ x-i18n: ## Env vars і завантаження .env - - OpenClaw читає env vars із батьківського процесу (оболонка, launchd/systemd, CI тощо) і додатково завантажує: + + OpenClaw читає env vars з батьківського процесу (оболонка, launchd/systemd, CI тощо) і додатково завантажує: - `.env` з поточного робочого каталогу - - глобальний резервний `.env` з `~/.openclaw/.env` (тобто `$OPENCLAW_STATE_DIR/.env`) + - глобальний запасний `.env` з `~/.openclaw/.env` (тобто `$OPENCLAW_STATE_DIR/.env`) - Жоден із файлів `.env` не перевизначає наявні env vars. + Жоден `.env`-файл не перевизначає вже наявні env vars. - Ви також можете визначити inline env vars у config (застосовуються лише якщо їх немає в env процесу): + Ви також можете визначити inline env vars у конфігурації (застосовуються лише якщо їх немає в env процесу): ```json5 { @@ -1931,15 +1934,15 @@ x-i18n: } ``` - Повний порядок пріоритетів і джерела див. у [/environment](/uk/help/environment). + Повний порядок пріоритету та джерела див. в [/environment](/uk/help/environment). - - Є два поширені способи виправити це: + + Є два поширені виправлення: - 1. Розмістіть відсутні ключі в `~/.openclaw/.env`, щоб вони підхоплювалися, навіть коли служба не успадковує env вашої оболонки. - 2. Увімкніть імпорт оболонки (додаткова зручність): + 1. Помістіть відсутні ключі в `~/.openclaw/.env`, щоб вони підхоплювалися, навіть коли сервіс не успадковує env вашої оболонки. + 2. Увімкніть імпорт оболонки (зручність за opt-in): ```json5 { @@ -1952,27 +1955,27 @@ x-i18n: } ``` - Це запускає вашу login shell і імпортує лише відсутні очікувані ключі (ніколи не перевизначає наявні). Еквіваленти env vars: + Це запускає вашу login shell і імпортує лише відсутні очікувані ключі (ніколи не перевизначає). Еквіваленти через env var: `OPENCLAW_LOAD_SHELL_ENV=1`, `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`. - `openclaw models status` показує, чи увімкнено **імпорт env оболонки**. "Shell env: off" + `openclaw models status` повідомляє, чи ввімкнено **імпорт shell env**. "Shell env: off" **не** означає, що ваших env vars немає — це лише означає, що OpenClaw не завантажуватиме вашу login shell автоматично. - Якщо Gateway працює як служба (launchd/systemd), він не успадковує env + Якщо Gateway працює як сервіс (launchd/systemd), він не успадковує середовище вашої оболонки. Виправити це можна одним із таких способів: - 1. Розмістіть токен у `~/.openclaw/.env`: + 1. Помістіть токен у `~/.openclaw/.env`: ``` COPILOT_GITHUB_TOKEN=... ``` - 2. Або увімкніть імпорт оболонки (`env.shellEnv.enabled: true`). - 3. Або додайте його в блок `env` свого config (застосовується лише якщо значення відсутнє). + 2. Або ввімкніть імпорт оболонки (`env.shellEnv.enabled: true`). + 3. Або додайте його в блок `env` вашої конфігурації (застосовується лише якщо відсутній). Потім перезапустіть gateway і перевірте ще раз: @@ -1980,24 +1983,24 @@ x-i18n: openclaw models status ``` - Токени Copilot зчитуються з `COPILOT_GITHUB_TOKEN` (також `GH_TOKEN` / `GITHUB_TOKEN`). + Токени Copilot читаються з `COPILOT_GITHUB_TOKEN` (також `GH_TOKEN` / `GITHUB_TOKEN`). Див. [/concepts/model-providers](/uk/concepts/model-providers) і [/environment](/uk/help/environment). -## Sessions і кілька чатів +## Сесії та кілька чатів - Надішліть `/new` або `/reset` як окреме повідомлення. Див. [Керування sessions](/uk/concepts/session). + Надішліть `/new` або `/reset` як окреме повідомлення. Див. [Керування сесіями](/uk/concepts/session). - - Sessions можуть завершуватися після `session.idleMinutes`, але це **типово вимкнено** (типове значення **0**). - Задайте додатне значення, щоб увімкнути завершення через неактивність. Коли це ввімкнено, **наступне** - повідомлення після періоду неактивності починає новий ідентифікатор session для цього ключа чату. - Це не видаляє транскрипти — лише починає нову session. + + Сесії можуть завершуватися після `session.idleMinutes`, але за замовчуванням це **вимкнено** (типове значення **0**). + Задайте додатне значення, щоб увімкнути завершення за простоєм. Коли це ввімкнено, **наступне** + повідомлення після періоду простою починає новий session id для цього ключа чату. + Це не видаляє транскрипти — лише починає нову сесію. ```json5 { @@ -2009,47 +2012,47 @@ x-i18n: - - Так, через **маршрутизацію multi-agent** і **sub-agents**. Ви можете створити одного agent-координатора - і кількох agent-воркерів із власними workspace та моделями. + + Так, через **маршрутизацію мультиагентності** та **субагентів**. Ви можете створити одного координуючого + агента і кількох робочих агентів із власними робочими областями та моделями. - Водночас це краще розглядати як **цікавий експеримент**. Це витратно за токенами й часто - менш ефективно, ніж використання одного бота з окремими sessions. Типова модель, яку ми - уявляємо, — це один бот, з яким ви спілкуєтеся, із різними sessions для паралельної роботи. Цей - бот також може породжувати sub-agents за потреби. + Втім, це краще розглядати як **цікавий експеримент**. Це сильно витрачає токени й часто + менш ефективно, ніж використання одного бота з окремими сесіями. Типова модель, яку ми + уявляємо, — це один бот, з яким ви спілкуєтеся, але з різними сесіями для паралельної роботи. Цей + бот також може за потреби запускати субагентів. - Документація: [Маршрутизація multi-agent](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [CLI Agents](/uk/cli/agents). + Документація: [Маршрутизація мультиагентності](/uk/concepts/multi-agent), [Субагенти](/uk/tools/subagents), [CLI агентів](/uk/cli/agents). - - Контекст session обмежений вікном моделі. Довгі чати, великий вивід інструментів або багато - файлів можуть запускати compaction або truncation. + + Контекст сесії обмежений вікном моделі. Довгі чати, великі виводи інструментів або багато + файлів можуть викликати стиснення або обрізання. Що допомагає: - Попросіть бота підсумувати поточний стан і записати його у файл. - - Використовуйте `/compact` перед довгими завданнями та `/new` при зміні теми. - - Тримайте важливий контекст у workspace і просіть бота перечитати його. - - Використовуйте sub-agents для довгої або паралельної роботи, щоб основний чат залишався меншим. - - Виберіть модель із більшим вікном контексту, якщо це трапляється часто. + - Використовуйте `/compact` перед довгими завданнями, а `/new` — коли перемикаєте тему. + - Зберігайте важливий контекст у робочій області й просіть бота перечитувати його. + - Використовуйте субагентів для довгої або паралельної роботи, щоб основний чат залишався меншим. + - Виберіть модель із більшим вікном контексту, якщо це часто трапляється. - Використовуйте команду reset: + Використовуйте команду скидання: ```bash openclaw reset ``` - Неінтерактивне повне скидання: + Повне неінтерактивне скидання: ```bash openclaw reset --scope full --yes --non-interactive ``` - Потім знову виконайте налаштування: + Потім знову запустіть налаштування: ```bash openclaw onboard --install-daemon @@ -2057,16 +2060,16 @@ x-i18n: Примітки: - - Onboarding також пропонує **Reset**, якщо бачить наявний config. Див. [Onboarding (CLI)](/uk/start/wizard). + - Онбординг також пропонує **Reset**, якщо бачить наявну конфігурацію. Див. [Онбординг (CLI)](/uk/start/wizard). - Якщо ви використовували профілі (`--profile` / `OPENCLAW_PROFILE`), скиньте кожен каталог стану (типово це `~/.openclaw-`). - - Скидання dev: `openclaw gateway --dev --reset` (лише для dev; стирає dev config + credentials + sessions + workspace). + - Скидання для dev: `openclaw gateway --dev --reset` (лише для dev; стирає конфігурацію dev + облікові дані + сесії + робочу область). - - Використайте один із цих варіантів: + + Використовуйте один із цих варіантів: - - **Compact** (зберігає розмову, але підсумовує старіші ходи): + - **Стиснути** (зберігає розмову, але підсумовує старіші повідомлення): ``` /compact @@ -2074,40 +2077,40 @@ x-i18n: або `/compact `, щоб спрямувати підсумок. - - **Reset** (новий ідентифікатор session для того самого ключа чату): + - **Скинути** (новий session ID для того самого ключа чату): ``` /new /reset ``` - Якщо це продовжує траплятися: + Якщо це повторюється: - - Увімкніть або налаштуйте **обрізання session** (`agents.defaults.contextPruning`), щоб прибирати старий вивід інструментів. + - Увімкніть або налаштуйте **обрізання сесії** (`agents.defaults.contextPruning`), щоб скорочувати старий вивід інструментів. - Використовуйте модель із більшим вікном контексту. - Документація: [Compaction](/uk/concepts/compaction), [Обрізання session](/uk/concepts/session-pruning), [Керування sessions](/uk/concepts/session). + Документація: [Compaction](/uk/concepts/compaction), [Обрізання сесії](/uk/concepts/session-pruning), [Керування сесіями](/uk/concepts/session). - Це помилка перевірки provider: модель згенерувала блок `tool_use` без обов’язкового - `input`. Зазвичай це означає, що історія session застаріла або пошкоджена (часто після довгих thread - або зміни tool/schema). + Це помилка валідації провайдера: модель видала блок `tool_use` без обов’язкового + `input`. Зазвичай це означає, що історія сесії застаріла або пошкоджена (часто після довгих потоків + або зміни інструмента/схеми). - Виправлення: почніть нову session за допомогою `/new` (окремим повідомленням). + Виправлення: почніть нову сесію командою `/new` (окремим повідомленням). - Heartbeat типово виконується кожні **30m** (**1h** при використанні OAuth auth). Налаштуйте або вимкніть це: + Heartbeat типово запускається кожні **30m** (**1h** при використанні OAuth-автентифікації). Налаштуйте або вимкніть його: ```json5 { agents: { defaults: { heartbeat: { - every: "2h", // або "0m", щоб вимкнути + every: "2h", // або "0m" для вимкнення }, }, }, @@ -2115,16 +2118,16 @@ x-i18n: ``` Якщо `HEARTBEAT.md` існує, але фактично порожній (лише порожні рядки та markdown-заголовки - на кшталт `# Heading`), OpenClaw пропускає запуск heartbeat, щоб заощадити API calls. - Якщо файла немає, heartbeat усе одно виконується, і модель сама вирішує, що робити. + на кшталт `# Heading`), OpenClaw пропускає запуск heartbeat, щоб заощадити виклики API. + Якщо файл відсутній, heartbeat усе одно виконується, і модель вирішує, що робити. - Для перевизначення на рівні agent використовуйте `agents.list[].heartbeat`. Документація: [Heartbeat](/uk/gateway/heartbeat). + Перевизначення на рівні агента використовують `agents.list[].heartbeat`. Документація: [Heartbeat](/uk/gateway/heartbeat). - Ні. OpenClaw працює від **вашого власного облікового запису**, тож якщо ви є в групі, OpenClaw може її бачити. - Типово відповіді в групах заблоковано, доки ви не дозволите відправників (`groupPolicy: "allowlist"`). + Ні. OpenClaw працює з **вашого власного облікового запису**, тож якщо ви є в групі, OpenClaw може її бачити. + За замовчуванням відповіді в групах заблоковано, доки ви не дозволите відправників (`groupPolicy: "allowlist"`). Якщо ви хочете, щоб запускати відповіді в групі могли лише **ви**: @@ -2142,71 +2145,71 @@ x-i18n: - Варіант 1 (найшвидший): переглядайте логи й надішліть тестове повідомлення в групу: + Варіант 1 (найшвидший): відстежуйте журнали й надішліть тестове повідомлення в групу: ```bash openclaw logs --follow --json ``` - Шукайте `chatId` (або `from`), що закінчується на `@g.us`, наприклад: + Знайдіть `chatId` (або `from`), що закінчується на `@g.us`, наприклад: `1234567890-1234567890@g.us`. - Варіант 2 (якщо вже налаштовано/додано в allowlist): перелічіть групи з config: + Варіант 2 (якщо вже налаштовано/додано в allowlist): перелічіть групи з конфігурації: ```bash openclaw directory groups list --channel whatsapp ``` - Документація: [WhatsApp](/uk/channels/whatsapp), [Directory](/uk/cli/directory), [Логи](/uk/cli/logs). + Документація: [WhatsApp](/uk/channels/whatsapp), [Directory](/uk/cli/directory), [Журнали](/uk/cli/logs). - Дві поширені причини: + Є дві поширені причини: - - Увімкнено обмеження за згадками (типово). Ви маєте @згадати бота (або відповідати `mentionPatterns`). - - Ви налаштували `channels.whatsapp.groups` без `"*"`, і групу не додано до allowlist. + - Увімкнено обмеження за згадуванням (типово). Ви маєте @згадати бота (або збігатися з `mentionPatterns`). + - Ви налаштували `channels.whatsapp.groups` без `"*"`, і цю групу не додано в allowlist. - Див. [Групи](/uk/channels/groups) і [Повідомлення в групах](/uk/channels/group-messages). + Див. [Групи](/uk/channels/groups) і [Групові повідомлення](/uk/channels/group-messages). - - Прямі чати типово згортаються до основної session. Групи/канали мають власні ключі session, а теми Telegram / threads Discord — це окремі sessions. Див. [Групи](/uk/channels/groups) і [Повідомлення в групах](/uk/channels/group-messages). + + Прямі чати типово згортаються в основну сесію. Групи/канали мають власні ключі сесій, а теми Telegram / потоки Discord — це окремі сесії. Див. [Групи](/uk/channels/groups) і [Групові повідомлення](/uk/channels/group-messages). - - Жорстких обмежень немає. Десятки (навіть сотні) — це нормально, але звертайте увагу на: + + Жорстких обмежень немає. Десятки (навіть сотні) — це нормально, але стежте за таким: - - **Зростання диска:** sessions + транскрипти зберігаються в `~/.openclaw/agents//sessions/`. - - **Вартість токенів:** більше agents означає більше одночасного використання моделей. - - **Операційні витрати:** профілі auth для окремих agents, workspaces і маршрутизація channel. + - **Зростання диска:** сесії + транскрипти зберігаються в `~/.openclaw/agents//sessions/`. + - **Вартість токенів:** більше агентів означає більше одночасного використання моделей. + - **Операційне навантаження:** профілі автентифікації, робочі області й маршрутизація каналів на рівні агента. Поради: - - Тримайте один **активний** workspace для кожного agent (`agents.defaults.workspace`). - - Очищуйте старі sessions (видаляйте JSONL або записи сховища), якщо диск розростається. - - Використовуйте `openclaw doctor`, щоб виявляти stray workspaces і невідповідності профілів. + - Тримайте одну **активну** робочу область на агента (`agents.defaults.workspace`). + - Очищуйте старі сесії (видаляйте JSONL або записи сховища), якщо диск розростається. + - Використовуйте `openclaw doctor`, щоб виявляти зайві робочі області й невідповідності профілів. - - Так. Використовуйте **Маршрутизацію Multi-Agent**, щоб запускати кілька ізольованих agents і маршрутизувати вхідні повідомлення за - channel/account/peer. Slack підтримується як channel і може бути прив’язаний до конкретних agents. + + Так. Використовуйте **Маршрутизацію мультиагентності**, щоб запускати кількох ізольованих агентів і маршрутизувати вхідні повідомлення за + каналом/обліковим записом/peer. Slack підтримується як канал і може бути прив’язаний до конкретних агентів. - Доступ до browser потужний, але це не «зробити все, що може людина» — anti-bot механізми, CAPTCHA і MFA - все одно можуть блокувати автоматизацію. Для найнадійнішого керування browser використовуйте локальний Chrome MCP на хості - або CDP на машині, яка фактично запускає browser. + Доступ до браузера дуже потужний, але це не «можна все, що може людина» — anti-bot, CAPTCHA та MFA + усе ще можуть блокувати автоматизацію. Для максимально надійного керування браузером використовуйте локальний Chrome MCP на хості + або використовуйте CDP на машині, яка фактично запускає браузер. - Рекомендоване налаштування: + Найкраща практика налаштування: - - Хост Gateway, що завжди ввімкнений (VPS/Mac mini). - - Один agent на роль (прив’язки). - - Slack channel(и), прив’язані до цих agents. - - Локальний browser через Chrome MCP або node за потреби. + - Хост Gateway, що завжди увімкнений (VPS/Mac mini). + - Один агент на роль (bindings). + - Канал(и) Slack, прив’язані до цих агентів. + - Локальний браузер через Chrome MCP або node за потреби. - Документація: [Маршрутизація Multi-Agent](/uk/concepts/multi-agent), [Slack](/uk/channels/slack), - [Browser](/uk/tools/browser), [Nodes](/uk/nodes). + Документація: [Маршрутизація мультиагентності](/uk/concepts/multi-agent), [Slack](/uk/channels/slack), + [Браузер](/uk/tools/browser), [Nodes](/uk/nodes). @@ -2215,86 +2218,86 @@ x-i18n: - Типова модель OpenClaw — це те, що ви задаєте як: + Модель OpenClaw за замовчуванням — це те, що ви задаєте як: ``` agents.defaults.model.primary ``` - На моделі посилаються як `provider/model` (приклад: `openai/gpt-5.4`). Якщо ви пропускаєте provider, OpenClaw спочатку пробує псевдонім, потім унікальний збіг налаштованого provider для точного id цієї моделі, і лише після цього переходить до налаштованого provider за замовчуванням як до застарілого шляху сумісності. Якщо цей provider більше не відкриває налаштовану модель за замовчуванням, OpenClaw переключається на перший налаштований provider/model замість того, щоб показувати застаріле типове значення з видаленого provider. Проте вам усе одно слід **явно** задавати `provider/model`. + На моделі посилаються як `provider/model` (приклад: `openai/gpt-5.4`). Якщо ви не вказуєте провайдера, OpenClaw спочатку пробує псевдонім, потім унікальний збіг налаштованого провайдера для точного id моделі, і лише потім повертається до налаштованого провайдера за замовчуванням як до застарілого шляху сумісності. Якщо цей провайдер більше не відкриває налаштовану модель за замовчуванням, OpenClaw повертається до першого налаштованого провайдера/моделі замість показу застарілого типового значення з видаленим провайдером. Вам усе одно слід **явно** задавати `provider/model`. - **Рекомендований варіант за замовчуванням:** використовуйте найсильнішу модель останнього покоління, доступну у вашому стеку providers. - **Для agents з увімкненими tools або з недовіреним входом:** ставте силу моделі вище за вартість. - **Для звичайного/низькоризикового чату:** використовуйте дешевші резервні моделі й маршрутизуйте за роллю agent. + **Рекомендований варіант за замовчуванням:** використовуйте найсильнішу модель останнього покоління, доступну у вашому стеку провайдерів. + **Для агентів з увімкненими інструментами або ненадійним входом:** віддавайте перевагу силі моделі над вартістю. + **Для звичайного/низькоризикового чату:** використовуйте дешевші резервні моделі й маршрутизуйте за роллю агента. Для MiniMax є окрема документація: [MiniMax](/uk/providers/minimax) і [Локальні моделі](/uk/gateway/local-models). Практичне правило: використовуйте **найкращу модель, яку можете собі дозволити** для високоризикової роботи, і дешевшу - модель для звичайного чату або підсумків. Ви можете маршрутизувати моделі для кожного agent і використовувати sub-agents для - паралелізації довгих завдань (кожен sub-agent споживає токени). Див. [Моделі](/uk/concepts/models) і - [Sub-agents](/uk/tools/subagents). + модель для звичайного чату або підсумків. Ви можете маршрутизувати моделі на рівні агента й використовувати субагентів для + паралелізації довгих завдань (кожен субагент витрачає токени). Див. [Моделі](/uk/concepts/models) і + [Субагенти](/uk/tools/subagents). - Серйозне попередження: слабші/надто квантизовані моделі вразливіші до prompt + Сильне попередження: слабші/надто квантизовані моделі більш вразливі до prompt injection і небезпечної поведінки. Див. [Безпека](/uk/gateway/security). Більше контексту: [Моделі](/uk/concepts/models). - - Використовуйте **команди моделей** або редагуйте лише поля **model**. Уникайте повної заміни config. + + Використовуйте **команди моделі** або редагуйте лише поля **model**. Уникайте повної заміни конфігурації. Безпечні варіанти: - - `/model` у чаті (швидко, для окремої session) - - `openclaw models set ...` (оновлює лише config model) + - `/model` у чаті (швидко, на рівні сесії) + - `openclaw models set ...` (оновлює лише конфігурацію моделі) - `openclaw configure --section model` (інтерактивно) - редагуйте `agents.defaults.model` у `~/.openclaw/openclaw.json` - Уникайте `config.apply` з частковим об’єктом, якщо ви не хочете замінити весь config. - Для редагування RPC спочатку перевіряйте через `config.schema.lookup` і надавайте перевагу `config.patch`. Payload lookup дає вам нормалізований шлях, документацію/обмеження поверхневої схеми та підсумки безпосередніх дочірніх елементів + Уникайте `config.apply` з частковим об’єктом, якщо ви не маєте наміру замінити всю конфігурацію. + Для RPC-редагувань спочатку перевіряйте через `config.schema.lookup` і віддавайте перевагу `config.patch`. Payload lookup дає вам нормалізований шлях, поверхневу документацію/обмеження схеми та зведення безпосередніх дочірніх елементів для часткових оновлень. - Якщо ви таки перезаписали config, відновіть його з резервної копії або повторно виконайте `openclaw doctor` для виправлення. + Якщо ви все ж перезаписали конфігурацію, відновіть її з резервної копії або повторно запустіть `openclaw doctor` для виправлення. - Документація: [Моделі](/uk/concepts/models), [Configure](/uk/cli/configure), [Config](/uk/cli/config), [Doctor](/uk/gateway/doctor). + Документація: [Моделі](/uk/concepts/models), [Налаштування](/uk/cli/configure), [Конфігурація](/uk/cli/config), [Doctor](/uk/gateway/doctor). - - Так. Ollama — найпростіший шлях для локальних моделей. + + Так. Ollama — найпростіший шлях до локальних моделей. Найшвидше налаштування: 1. Встановіть Ollama з `https://ollama.com/download` 2. Завантажте локальну модель, наприклад `ollama pull gemma4` - 3. Якщо вам потрібні також хмарні моделі, виконайте `ollama signin` - 4. Виконайте `openclaw onboard` і виберіть `Ollama` + 3. Якщо ви також хочете хмарні моделі, виконайте `ollama signin` + 4. Запустіть `openclaw onboard` і виберіть `Ollama` 5. Виберіть `Local` або `Cloud + Local` Примітки: - `Cloud + Local` дає вам хмарні моделі плюс ваші локальні моделі Ollama - - хмарні моделі, як-от `kimi-k2.5:cloud`, не потребують локального завантаження + - хмарні моделі, такі як `kimi-k2.5:cloud`, не потребують локального завантаження - для ручного перемикання використовуйте `openclaw models list` і `openclaw models set ollama/` - Примітка з безпеки: менші або сильно квантизовані моделі вразливіші до prompt - injection. Ми наполегливо рекомендуємо **великі моделі** для будь-якого бота, який може використовувати tools. - Якщо ви все ж хочете малі моделі, увімкніть ізоляцію та строгі allowlist для tools. + Примітка щодо безпеки: менші або сильно квантизовані моделі більш вразливі до prompt + injection. Ми наполегливо рекомендуємо **великі моделі** для будь-якого бота, який може використовувати інструменти. + Якщо ви все одно хочете малі моделі, увімкніть sandboxing і суворі allowlist-и інструментів. Документація: [Ollama](/uk/providers/ollama), [Локальні моделі](/uk/gateway/local-models), [Провайдери моделей](/uk/concepts/model-providers), [Безпека](/uk/gateway/security), - [Ізоляція](/uk/gateway/sandboxing). + [Sandboxing](/uk/gateway/sandboxing). - - У цих розгортаннях усе може відрізнятися й змінюватися з часом; фіксованої рекомендації щодо provider немає. - - Перевіряйте поточне налаштування під час роботи на кожному gateway через `openclaw models status`. - - Для чутливих до безпеки agents / agents з увімкненими tools використовуйте найсильнішу модель останнього покоління з доступних. + - У цих розгортаннях це може відрізнятися й змінюватися з часом; фіксованої рекомендації щодо провайдера немає. + - Перевіряйте поточне налаштування під час виконання на кожному gateway через `openclaw models status`. + - Для безпеково чутливих агентів / агентів з увімкненими інструментами використовуйте найсильнішу доступну модель останнього покоління. @@ -2310,27 +2313,27 @@ x-i18n: /model gemini-flash-lite ``` - Це вбудовані псевдоніми. Користувацькі псевдоніми можна додати через `agents.defaults.models`. + Це вбудовані псевдоніми. Власні псевдоніми можна додавати через `agents.defaults.models`. - Ви можете перелічити доступні моделі через `/model`, `/model list` або `/model status`. + Список доступних моделей можна переглянути через `/model`, `/model list` або `/model status`. - `/model` (і `/model list`) показує компактний нумерований вибір. Вибір за номером: + `/model` (і `/model list`) показує компактний нумерований вибір. Виберіть за номером: ``` /model 3 ``` - Ви також можете примусово вибрати конкретний профіль auth для provider (для окремої session): + Ви також можете примусово вибрати конкретний профіль автентифікації для провайдера (на рівні сесії): ``` /model opus@anthropic:default /model opus@anthropic:work ``` - Порада: `/model status` показує, який agent активний, який файл `auth-profiles.json` використовується і який профіль auth буде спробовано наступним. - Він також показує налаштований endpoint provider (`baseUrl`) і режим API (`api`), коли вони доступні. + Порада: `/model status` показує, який агент активний, який файл `auth-profiles.json` використовується і який профіль автентифікації буде спробовано наступним. + Він також показує налаштовану кінцеву точку провайдера (`baseUrl`) і режим API (`api`), коли вони доступні. - **Як зняти закріплення профілю, який я задав через @profile?** + **Як скасувати закріплення профілю, який я задав через @profile?** Повторно виконайте `/model` **без** суфікса `@profile`: @@ -2338,28 +2341,28 @@ x-i18n: /model anthropic/claude-opus-4-6 ``` - Якщо ви хочете повернутися до типового значення, виберіть його через `/model` (або надішліть `/model `). - Використовуйте `/model status`, щоб підтвердити, який профіль auth активний. + Якщо ви хочете повернутися до значення за замовчуванням, виберіть його через `/model` (або надішліть `/model `). + Використовуйте `/model status`, щоб підтвердити, який профіль автентифікації активний. - - Так. Задайте одну модель як типову й перемикайтеся за потреби: + + Так. Задайте одну як значення за замовчуванням і перемикайте за потреби: - - **Швидке перемикання (для окремої session):** `/model gpt-5.4` для щоденних завдань, `/model openai-codex/gpt-5.4` для кодування через OAuth Codex. - - **Типове значення + перемикання:** задайте `agents.defaults.model.primary` як `openai/gpt-5.4`, а потім перемикайтеся на `openai-codex/gpt-5.4` під час кодування (або навпаки). - - **Sub-agents:** маршрутизуйте завдання кодування до sub-agents з іншою типовою моделлю. + - **Швидке перемикання (на рівні сесії):** `/model gpt-5.4` для щоденних завдань, `/model openai-codex/gpt-5.4` для програмування з Codex OAuth. + - **Типове значення + перемикання:** задайте `agents.defaults.model.primary` як `openai/gpt-5.4`, а потім перемикайтеся на `openai-codex/gpt-5.4` під час програмування (або навпаки). + - **Субагенти:** маршрутизуйте завдання програмування до субагентів з іншою моделлю за замовчуванням. - Див. [Моделі](/uk/concepts/models) і [Слеш-команди](/uk/tools/slash-commands). + Див. [Моделі](/uk/concepts/models) і [Slash commands](/uk/tools/slash-commands). - Використовуйте або перемикач session, або типове значення в config: + Використовуйте або перемикач на рівні сесії, або типове значення в конфігурації: - - **Для окремої session:** надішліть `/fast on`, поки session використовує `openai/gpt-5.4` або `openai-codex/gpt-5.4`. - - **Типове значення для моделі:** задайте `agents.defaults.models["openai/gpt-5.4"].params.fastMode` як `true`. - - **Також для OAuth Codex:** якщо ви також використовуєте `openai-codex/gpt-5.4`, задайте той самий прапорець і там. + - **На рівні сесії:** надішліть `/fast on`, поки сесія використовує `openai/gpt-5.4` або `openai-codex/gpt-5.4`. + - **Типове значення на рівні моделі:** задайте `agents.defaults.models["openai/gpt-5.4"].params.fastMode` як `true`. + - **Також для Codex OAuth:** якщо ви також використовуєте `openai-codex/gpt-5.4`, задайте там той самий прапорець. Приклад: @@ -2384,39 +2387,39 @@ x-i18n: } ``` - Для OpenAI fast mode відображається в `service_tier = "priority"` у підтримуваних нативних запитах Responses. `/fast` для session перевизначає типові значення config. + Для OpenAI fast mode відповідає `service_tier = "priority"` у підтримуваних нативних запитах Responses. Сесійний `/fast` має вищий пріоритет за типові значення конфігурації. - Див. [Thinking і fast mode](/uk/tools/thinking) та [OpenAI fast mode](/uk/providers/openai#openai-fast-mode). + Див. [Thinking і fast mode](/uk/tools/thinking) і [OpenAI fast mode](/uk/providers/openai#openai-fast-mode). - Якщо задано `agents.defaults.models`, це стає **allowlist** для `/model` і будь-яких - перевизначень session. Вибір моделі, якої немає в цьому списку, повертає: + Якщо задано `agents.defaults.models`, воно стає **allowlist** для `/model` і будь-яких + перевизначень сесії. Вибір моделі, якої немає в цьому списку, повертає: ``` Model "provider/model" is not allowed. Use /model to list available models. ``` Ця помилка повертається **замість** звичайної відповіді. Виправлення: додайте модель до - `agents.defaults.models`, приберіть allowlist або виберіть модель із `/model list`. + `agents.defaults.models`, приберіть allowlist або виберіть модель зі списку `/model list`. - Це означає, що **provider не налаштований** (не знайдено config provider MiniMax або - профіль auth), тому модель не вдається розв’язати. + Це означає, що **провайдер не налаштований** (не знайдено конфігурації провайдера MiniMax або профілю + автентифікації), тому модель неможливо розв’язати. - Чекліст виправлення: + Контрольний список для виправлення: 1. Оновіться до актуального релізу OpenClaw (або запускайте з вихідного коду `main`), а потім перезапустіть gateway. - 2. Переконайтеся, що MiniMax налаштовано (майстром або через JSON), або що auth MiniMax - існує в env/auth profiles, щоб можна було інжектувати відповідний provider + 2. Переконайтеся, що MiniMax налаштовано (майстром або через JSON), або що автентифікація MiniMax + існує в env/профілях автентифікації, щоб відповідний провайдер можна було інжектувати (`MINIMAX_API_KEY` для `minimax`, `MINIMAX_OAUTH_TOKEN` або збережений MiniMax OAuth для `minimax-portal`). - 3. Використовуйте точний id моделі (з урахуванням регістру) для вашого шляху auth: - `minimax/MiniMax-M2.7` або `minimax/MiniMax-M2.7-highspeed` для налаштування - з API key, або `minimax-portal/MiniMax-M2.7` / + 3. Використовуйте точний id моделі (з урахуванням регістру) для вашого шляху автентифікації: + `minimax/MiniMax-M2.7` або `minimax/MiniMax-M2.7-highspeed` для + налаштування з API-ключем, або `minimax-portal/MiniMax-M2.7` / `minimax-portal/MiniMax-M2.7-highspeed` для налаштування з OAuth. 4. Виконайте: @@ -2430,11 +2433,11 @@ x-i18n: - - Так. Використовуйте **MiniMax як типову модель** і перемикайте моделі **для окремої session** за потреби. - Fallback призначені для **помилок**, а не для «складних завдань», тому використовуйте `/model` або окремий agent. + + Так. Використовуйте **MiniMax як значення за замовчуванням** і перемикайте моделі **на рівні сесії** за потреби. + Fallback-и призначені для **помилок**, а не для «складних завдань», тож використовуйте `/model` або окремого агента. - **Варіант A: перемикання для окремої session** + **Варіант A: перемикання на рівні сесії** ```json5 { @@ -2457,18 +2460,18 @@ x-i18n: /model gpt ``` - **Варіант B: окремі agents** + **Варіант B: окремі агенти** - - Типова модель agent A: MiniMax - - Типова модель agent B: OpenAI - - Маршрутизуйте за agent або використовуйте `/agent` для перемикання + - Типове значення агента A: MiniMax + - Типове значення агента B: OpenAI + - Маршрутизуйте за агентом або використовуйте `/agent` для перемикання - Документація: [Моделі](/uk/concepts/models), [Маршрутизація Multi-Agent](/uk/concepts/multi-agent), [MiniMax](/uk/providers/minimax), [OpenAI](/uk/providers/openai). + Документація: [Моделі](/uk/concepts/models), [Маршрутизація мультиагентності](/uk/concepts/multi-agent), [MiniMax](/uk/providers/minimax), [OpenAI](/uk/providers/openai). - Так. OpenClaw постачається з кількома типовими скороченнями (застосовуються лише тоді, коли модель існує в `agents.defaults.models`): + Так. OpenClaw постачається з кількома скороченнями за замовчуванням (застосовуються лише коли модель існує в `agents.defaults.models`): - `opus` → `anthropic/claude-opus-4-6` - `sonnet` → `anthropic/claude-sonnet-4-6` @@ -2479,12 +2482,12 @@ x-i18n: - `gemini-flash` → `google/gemini-3-flash-preview` - `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview` - Якщо ви задасте власний псевдонім із такою самою назвою, ваше значення матиме пріоритет. + Якщо ви задасте власний псевдонім із тією самою назвою, ваше значення матиме пріоритет. - - Псевдоніми беруться з `agents.defaults.models..alias`. Приклад: + + Псевдоніми задаються через `agents.defaults.models..alias`. Приклад: ```json5 { @@ -2501,12 +2504,12 @@ x-i18n: } ``` - Тоді `/model sonnet` (або `/`, коли це підтримується) розв’язується в цей id моделі. + Тоді `/model sonnet` (або `/`, коли це підтримується) розв’язується до цього ID моделі. - - OpenRouter (оплата за токени; багато моделей): + + OpenRouter (оплата за токен; багато моделей): ```json5 { @@ -2534,11 +2537,11 @@ x-i18n: } ``` - Якщо ви посилаєтеся на `provider/model`, але потрібний ключ provider відсутній, ви отримаєте помилку auth під час роботи (наприклад `No API key found for provider "zai"`). + Якщо ви посилаєтеся на `provider/model`, але потрібний ключ провайдера відсутній, ви отримаєте помилку автентифікації під час виконання (наприклад, `No API key found for provider "zai"`). - **No API key found for provider після додавання нового agent** + **Після додавання нового агента з’являється "No API key found for provider"** - Зазвичай це означає, що **новий agent** має порожнє сховище auth. Auth є окремим для кожного agent і + Зазвичай це означає, що **новий агент** має порожнє сховище автентифікації. Автентифікація прив’язана до агента і зберігається в: ``` @@ -2547,119 +2550,120 @@ x-i18n: Варіанти виправлення: - - Виконайте `openclaw agents add ` і налаштуйте auth під час майстра. - - Або скопіюйте `auth-profiles.json` з `agentDir` основного agent до `agentDir` нового agent. + - Виконайте `openclaw agents add ` і налаштуйте автентифікацію під час роботи майстра. + - Або скопіюйте `auth-profiles.json` з `agentDir` основного агента в `agentDir` нового агента. - **Не** використовуйте повторно `agentDir` між agents; це спричиняє конфлікти auth/session. + **Не** використовуйте спільний `agentDir` для кількох агентів; це спричиняє конфлікти автентифікації/сесій. -## Перемикання моделей у разі збою та «All models failed» +## Резервне перемикання моделей і "All models failed" - - Перемикання в разі збою відбувається у два етапи: + + Резервне перемикання відбувається у два етапи: - 1. **Ротація профілів auth** у межах того самого provider. + 1. **Ротація профілів автентифікації** в межах одного провайдера. 2. **Fallback моделі** до наступної моделі в `agents.defaults.model.fallbacks`. - До профілів, що дають збої, застосовуються cooldown (експоненційний backoff), тож OpenClaw може продовжувати відповідати навіть тоді, коли provider упирається в rate limit або тимчасово недоступний. + До профілів, що зазнали збою, застосовуються cooldown-и (експоненційний backoff), тому OpenClaw може продовжувати відповідати, навіть коли провайдер обмежений за rate limit або тимчасово недоступний. - Кошик rate-limit включає більше, ніж просто відповіді `429`. OpenClaw - також вважає такими, що варті failover, повідомлення на кшталт `Too many concurrent requests`, + Кошик rate limit включає не лише звичайні відповіді `429`. OpenClaw + також вважає повідомлення на кшталт `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, `resource exhausted` і періодичні - обмеження вікна використання (`weekly/monthly limit reached`). + ліміти вікна використання (`weekly/monthly limit reached`) гідними + резервного перемикання rate limit-ами. - Деякі відповіді, схожі на billing, не є `402`, а деякі відповіді HTTP `402` - також залишаються в цьому тимчасовому кошику. Якщо provider повертає - явний текст billing у `401` або `403`, OpenClaw все одно може залишити це - в смузі billing, але text matcher, специфічні для provider, залишаються в межах - provider, якому вони належать (наприклад, OpenRouter `Key limit exceeded`). Якщо ж повідомлення `402` - більше схоже на повторюване вікно використання або - обмеження витрат організації/робочого простору (`daily limit reached, resets tomorrow`, + Деякі відповіді, схожі на проблеми з білінгом, не є `402`, і деякі HTTP `402` + також залишаються в цьому транзитному кошику. Якщо провайдер повертає + явний текст про білінг із `401` або `403`, OpenClaw усе одно може залишити це + в гілці білінгу, але текстові зіставлення, специфічні для провайдера, залишаються обмеженими + провайдером, якому вони належать (наприклад, OpenRouter `Key limit exceeded`). Якщо ж повідомлення `402` + більше схоже на повторюваний ліміт вікна використання або + ліміт витрат організації/робочої області (`daily limit reached, resets tomorrow`, `organization spending limit exceeded`), OpenClaw трактує це як - `rate_limit`, а не як довготривале вимкнення через billing. + `rate_limit`, а не як довготривале відключення через білінг. Помилки переповнення контексту — інші: сигнатури на кшталт `request_too_large`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model` або `ollama error: context length - exceeded` залишаються на шляху compaction/retry замість переходу до model - fallback. + exceeded` залишаються на шляху compaction/retry замість просування + fallback моделі. - Узагальнений текст server-error навмисно вужчий, ніж «усе, де є - unknown/error». OpenClaw вважає вартими failover перехідні форми, - обмежені provider, як-от голе Anthropic `An unknown error occurred`, голе OpenRouter - `Provider returned error`, помилки stop-reason на кшталт `Unhandled stop reason: - error`, JSON payload `api_error` з перехідним серверним текстом + Загальний текст server error навмисно вужчий за «будь-що зі словами + unknown/error усередині». OpenClaw вважає гідними резервного перемикання + транзитні форми в межах контексту провайдера, такі як голе Anthropic `An unknown error occurred`, голе OpenRouter + `Provider returned error`, помилки причини зупинки на кшталт `Unhandled stop reason: + error`, JSON payload-и `api_error` із транзитним текстом сервера (`internal server error`, `unknown error, 520`, `upstream error`, `backend - error`) і помилки зайнятості provider на кшталт `ModelNotReadyException` як - сигнали timeout/перевантаження, що варті failover, коли контекст provider + error`) і помилки «провайдер зайнятий», такі як `ModelNotReadyException`, + як сигнали тайм-ауту/перевантаження, коли контекст провайдера збігається. - Узагальнений внутрішній fallback-текст на кшталт `LLM request failed with an unknown - error.` навмисно обробляється обережно і сам по собі не запускає model fallback. + Загальний внутрішній fallback-текст на кшталт `LLM request failed with an unknown + error.` лишається консервативним і сам по собі не запускає fallback моделі. - Це означає, що система намагалася використати id профілю auth `anthropic:default`, але не змогла знайти облікові дані для нього в очікуваному сховищі auth. + Це означає, що система спробувала використати ID профілю автентифікації `anthropic:default`, але не змогла знайти для нього облікові дані в очікуваному сховищі автентифікації. - **Чекліст виправлення:** + **Контрольний список для виправлення:** - - **Підтвердьте, де зберігаються профілі auth** (нові чи застарілі шляхи) - - Поточний: `~/.openclaw/agents//agent/auth-profiles.json` - - Застарілий: `~/.openclaw/agent/*` (мігрується через `openclaw doctor`) - - **Підтвердьте, що ваш env var завантажується Gateway** - - Якщо ви задали `ANTHROPIC_API_KEY` у своїй оболонці, але запускаєте Gateway через systemd/launchd, він може його не успадкувати. Розмістіть його в `~/.openclaw/.env` або увімкніть `env.shellEnv`. - - **Переконайтеся, що ви редагуєте правильного agent** - - У multi-agent налаштуваннях може бути кілька файлів `auth-profiles.json`. - - **Перевірте стан model/auth** - - Використовуйте `openclaw models status`, щоб побачити налаштовані моделі й те, чи пройшли providers автентифікацію. + - **Підтвердьте, де зберігаються профілі автентифікації** (нові й застарілі шляхи) + - Поточний шлях: `~/.openclaw/agents//agent/auth-profiles.json` + - Застарілий шлях: `~/.openclaw/agent/*` (мігрується через `openclaw doctor`) + - **Підтвердьте, що Gateway завантажує вашу env var** + - Якщо ви задали `ANTHROPIC_API_KEY` у своїй оболонці, але запускаєте Gateway через systemd/launchd, він може її не успадкувати. Помістіть її в `~/.openclaw/.env` або ввімкніть `env.shellEnv`. + - **Переконайтеся, що ви редагуєте правильного агента** + - У мультиагентних налаштуваннях може бути кілька файлів `auth-profiles.json`. + - **Швидко перевірте стан моделі/автентифікації** + - Використовуйте `openclaw models status`, щоб побачити налаштовані моделі й чи проходять провайдери автентифікацію. - **Чекліст виправлення для "No credentials found for profile anthropic"** + **Контрольний список для виправлення "No credentials found for profile anthropic"** - Це означає, що запуск прив’язаний до профілю auth Anthropic, але Gateway - не може знайти його у своєму сховищі auth. + Це означає, що запуск закріплено за профілем автентифікації Anthropic, але Gateway + не може знайти його у своєму сховищі автентифікації. - **Використовуйте Claude CLI** - Виконайте `openclaw models auth login --provider anthropic --method cli --set-default` на хості gateway. - - **Якщо ви хочете натомість використовувати API key** - - Розмістіть `ANTHROPIC_API_KEY` у `~/.openclaw/.env` на **хості gateway**. - - Очистьте будь-який закріплений порядок, який примушує використовувати відсутній профіль: + - **Якщо ви хочете використовувати API-ключ** + - Помістіть `ANTHROPIC_API_KEY` у `~/.openclaw/.env` на **хості gateway**. + - Очистьте будь-який закріплений порядок, який примусово вимагає відсутній профіль: ```bash openclaw models auth order clear --provider anthropic ``` - - **Підтвердьте, що ви виконуєте команди на хості gateway** - - У remote mode профілі auth живуть на машині gateway, а не на вашому ноутбуці. + - **Підтвердьте, що ви запускаєте команди саме на хості gateway** + - У віддаленому режимі профілі автентифікації живуть на машині gateway, а не на вашому ноутбуці. - - Якщо ваш config model містить Google Gemini як fallback (або ви переключилися на скорочення Gemini), OpenClaw спробує його під час model fallback. Якщо ви не налаштували облікові дані Google, ви побачите `No API key found for provider "google"`. + + Якщо конфігурація вашої моделі включає Google Gemini як fallback (або ви перемкнулися на скорочення Gemini), OpenClaw спробує його під час fallback моделі. Якщо ви не налаштували облікові дані Google, ви побачите `No API key found for provider "google"`. - Виправлення: або надайте auth Google, або приберіть/уникайте моделей Google в `agents.defaults.model.fallbacks` / псевдонімах, щоб fallback не маршрутизував туди. + Виправлення: або надайте автентифікацію Google, або приберіть/не використовуйте моделі Google в `agents.defaults.model.fallbacks` / псевдонімах, щоб fallback не маршрутизував туди. **LLM request rejected: thinking signature required (Google Antigravity)** - Причина: історія session містить **блоки thinking без підписів** (часто від - перерваного/часткового потоку). Google Antigravity вимагає підписів для блоків thinking. + Причина: історія сесії містить **блоки thinking без сигнатур** (часто через + перерваний/частковий потік). Google Antigravity вимагає сигнатур для блоків thinking. - Виправлення: OpenClaw тепер видаляє непідписані блоки thinking для Google Antigravity Claude. Якщо це все ще з’являється, почніть **нову session** або задайте `/thinking off` для цього agent. + Виправлення: тепер OpenClaw прибирає блоки thinking без сигнатур для Google Antigravity Claude. Якщо це все ще трапляється, почніть **нову сесію** або задайте `/thinking off` для цього агента. -## Профілі auth: що це таке і як ними керувати +## Профілі автентифікації: що це таке і як ними керувати Пов’язане: [/concepts/oauth](/uk/concepts/oauth) (потоки OAuth, зберігання токенів, шаблони для кількох облікових записів) - - Профіль auth — це іменований запис облікових даних (OAuth або API key), прив’язаний до provider. Профілі зберігаються в: + + Профіль автентифікації — це іменований запис облікових даних (OAuth або API-ключ), прив’язаний до провайдера. Профілі зберігаються в: ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -2667,41 +2671,41 @@ x-i18n: - - OpenClaw використовує id з префіксом provider, наприклад: + + OpenClaw використовує ID з префіксом провайдера, наприклад: - - `anthropic:default` (поширено, коли немає ідентичності email) - - `anthropic:` для ідентичностей OAuth - - користувацькі id, які ви задаєте (наприклад `anthropic:work`) + - `anthropic:default` (поширений варіант, коли немає email-ідентичності) + - `anthropic:` для OAuth-ідентичностей + - власні ID на ваш вибір (наприклад, `anthropic:work`) - - Так. Config підтримує необов’язкові метадані для профілів і порядок для кожного provider (`auth.order.`). Це **не** зберігає секрети; воно зіставляє id із provider/mode і задає порядок ротації. + + Так. Конфігурація підтримує необов’язкові метадані для профілів і порядок для кожного провайдера (`auth.order.`). Тут **не** зберігаються секрети; це лише зіставляє ID із провайдером/режимом і задає порядок ротації. - OpenClaw може тимчасово пропустити профіль, якщо він перебуває в короткому **cooldown** (rate limits/timeouts/auth failures) або в довшому стані **disabled** (billing/insufficient credits). Щоб перевірити це, виконайте `openclaw models status --json` і перевірте `auth.unusableProfiles`. Налаштування: `auth.cooldowns.billingBackoffHours*`. + OpenClaw може тимчасово пропустити профіль, якщо він перебуває в короткому **cooldown** (rate limit-и/тайм-аути/збої автентифікації) або в довшому стані **disabled** (білінг/недостатньо коштів). Щоб перевірити це, виконайте `openclaw models status --json` і перегляньте `auth.unusableProfiles`. Налаштування: `auth.cooldowns.billingBackoffHours*`. - Cooldown для rate-limit можуть бути прив’язані до моделі. Профіль, який перебуває в cooldown - для однієї моделі, усе ще може бути придатним для спорідненої моделі в того самого provider, - тоді як вікна billing/disabled як і раніше блокують увесь профіль. + Cooldown-и rate limit можуть бути прив’язані до моделі. Профіль, який перебуває в cooldown + для однієї моделі, все ще може бути придатним для сусідньої моделі того самого провайдера, + тоді як вікна billing/disabled усе ще блокують увесь профіль. - Ви також можете задати **перевизначення порядку для окремого agent** (зберігається в `auth-state.json` цього agent) через CLI: + Ви також можете задати **перевизначення порядку для конкретного агента** (зберігається в `auth-state.json` цього агента) через CLI: ```bash - # Типово націлюється на типового agent з config (пропустіть --agent) + # Типово використовується налаштований агент за замовчуванням (omit --agent) openclaw models auth order get --provider anthropic - # Заблокувати ротацію до одного профілю (пробувати лише його) + # Зафіксувати ротацію на одному профілі (пробувати лише цей) openclaw models auth order set --provider anthropic anthropic:default - # Або задати явний порядок (fallback у межах provider) + # Або задати явний порядок (fallback у межах провайдера) openclaw models auth order set --provider anthropic anthropic:work anthropic:default - # Очистити перевизначення (повернутися до config auth.order / round-robin) + # Очистити перевизначення (повернення до config auth.order / round-robin) openclaw models auth order clear --provider anthropic ``` - Щоб націлитися на конкретного agent: + Щоб націлитися на конкретного агента: ```bash openclaw models auth order set --provider anthropic --agent main anthropic:default @@ -2714,22 +2718,22 @@ x-i18n: ``` Якщо збережений профіль пропущено в явному порядку, probe повідомить - `excluded_by_auth_order` для цього профілю замість того, щоб мовчки його пробувати. + `excluded_by_auth_order` для цього профілю замість того, щоб тихо його спробувати. - + OpenClaw підтримує обидва варіанти: - **OAuth** часто використовує доступ за підпискою (де це застосовно). - - **API keys** використовують білінг за токени. + - **API-ключі** використовують тарифікацію pay-per-token. - Майстер явно підтримує Anthropic Claude CLI, OpenAI Codex OAuth і API keys. + Майстер явно підтримує Anthropic Claude CLI, OpenAI Codex OAuth і API-ключі. -## Gateway: порти, «already running» і remote mode +## Gateway: порти, "already running" і віддалений режим @@ -2743,19 +2747,19 @@ x-i18n: - - Тому що "running" — це погляд **supervisor** (launchd/systemd/schtasks). А connectivity probe — це фактичне підключення CLI до Gateway WebSocket. + + Тому що "running" — це погляд **supervisor-а** (launchd/systemd/schtasks). Перевірка з’єднання — це фактичне підключення CLI до gateway WebSocket. - Використовуйте `openclaw gateway status` і довіряйте цим рядкам: + Використовуйте `openclaw gateway status` і довіряйте таким рядкам: - - `Probe target:` (URL, який probe реально використав) - - `Listening:` (що насправді прив’язано до порту) - - `Last gateway error:` (типова коренева причина, коли процес живий, але порт не слухає) + - `Probe target:` (URL, який перевірка фактично використала) + - `Listening:` (що реально прив’язано до порту) + - `Last gateway error:` (поширена першопричина, коли процес живий, але порт не слухає) - - Ви редагуєте один файл config, а служба працює з іншим (часто через невідповідність `--profile` / `OPENCLAW_STATE_DIR`). + + Ви редагуєте один файл конфігурації, а сервіс запущено з іншим (часто через невідповідність `--profile` / `OPENCLAW_STATE_DIR`). Виправлення: @@ -2763,19 +2767,19 @@ x-i18n: openclaw gateway install --force ``` - Виконуйте це з того самого `--profile` / середовища, яке служба має використовувати. + Запустіть це з того самого `--profile` / середовища, яке ви хочете використовувати для сервісу. - OpenClaw примусово забезпечує блокування під час роботи, негайно прив’язуючи слухач WebSocket під час запуску (типово `ws://127.0.0.1:18789`). Якщо прив’язка завершується помилкою `EADDRINUSE`, викидається `GatewayLockError`, що означає: інший екземпляр уже слухає. + OpenClaw забезпечує runtime-lock, негайно прив’язуючи слухач WebSocket під час запуску (типово `ws://127.0.0.1:18789`). Якщо прив’язка завершується помилкою `EADDRINUSE`, викидається `GatewayLockError`, який означає, що інший екземпляр уже слухає. - Виправлення: зупиніть інший екземпляр, звільніть порт або запускайте з `openclaw gateway --port `. + Виправлення: зупиніть інший екземпляр, звільніть порт або запустіть з `openclaw gateway --port `. - - Задайте `gateway.mode: "remote"` і вкажіть URL віддаленого WebSocket, за потреби додавши віддалені облікові дані зі спільним секретом: + + Задайте `gateway.mode: "remote"` і вкажіть віддалену URL-адресу WebSocket, за бажанням із віддаленими обліковими даними за спільним секретом: ```json5 { @@ -2792,90 +2796,90 @@ x-i18n: Примітки: - - `openclaw gateway` запускається лише тоді, коли `gateway.mode` дорівнює `local` (або ви передали прапорець перевизначення). - - Застосунок macOS стежить за файлом config і перемикає режими наживо, коли ці значення змінюються. - - `gateway.remote.token` / `.password` — це лише віддалені облікові дані на боці client; самі по собі вони не вмикають auth локального gateway. + - `openclaw gateway` запускається лише коли `gateway.mode` має значення `local` (або ви передаєте прапорець перевизначення). + - Застосунок macOS відстежує файл конфігурації та живо перемикає режими, коли ці значення змінюються. + - `gateway.remote.token` / `.password` — це лише віддалені облікові дані на стороні клієнта; самі по собі вони не вмикають локальну автентифікацію gateway. - - Ваш шлях auth gateway і метод auth у UI не збігаються. + + Шлях автентифікації вашого gateway і метод автентифікації UI не збігаються. Факти (з коду): - - Control UI зберігає токен у `sessionStorage` для поточної сесії вкладки браузера і вибраного URL gateway, тому оновлення в тій самій вкладці продовжують працювати без відновлення довготривалого зберігання токена в localStorage. - - За `AUTH_TOKEN_MISMATCH` довірені clients можуть виконати одну обмежену повторну спробу з кешованим токеном пристрою, коли gateway повертає підказки для повтору (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`). - - Ця повторна спроба з кешованим токеном тепер повторно використовує кешовані схвалені scope, збережені разом із токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` усе одно зберігають запитаний набір scope замість успадковування кешованих scope. - - Поза цим шляхом повторної спроби пріоритет auth для підключення такий: спочатку явний спільний токен/пароль, потім явний `deviceToken`, потім збережений токен пристрою, потім bootstrap-токен. - - Перевірки scope bootstrap-токена мають префікс ролі. Вбудований allowlist bootstrap-operator задовольняє лише запити operator; node або інші ролі, відмінні від operator, усе одно потребують scope під власним префіксом ролі. + - Control UI зберігає токен у `sessionStorage` для поточної сесії вкладки браузера й вибраної URL-адреси gateway, тому оновлення в тій самій вкладці продовжують працювати без відновлення довготривалого збереження токена в localStorage. + - У разі `AUTH_TOKEN_MISMATCH` довірені клієнти можуть зробити одну обмежену повторну спробу з кешованим токеном пристрою, коли gateway повертає підказки для повтору (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`). + - Цей повтор із кешованим токеном тепер повторно використовує кешовані затверджені scopes, збережені разом із токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` як і раніше зберігають свій запитаний набір scopes замість успадкування кешованих. + - Поза цим шляхом повторної спроби пріоритет автентифікації connect такий: спочатку явний спільний токен/пароль, потім явний `deviceToken`, потім збережений токен пристрою, потім bootstrap token. + - Перевірки scope для bootstrap token мають префікс ролі. Вбудований allowlist bootstrap operator задовольняє лише запити operator; node або інші ролі, відмінні від operator, усе ще потребують scopes під власним префіксом ролі. Виправлення: - - Найшвидше: `openclaw dashboard` (друкує + копіює URL dashboard, намагається відкрити; якщо середовище headless, показує підказку для SSH). + - Найшвидше: `openclaw dashboard` (виводить + копіює URL-адресу dashboard, намагається відкрити; показує SSH-підказку, якщо режим headless). - Якщо у вас ще немає токена: `openclaw doctor --generate-gateway-token`. - - Якщо ви працюєте віддалено, спочатку створіть tunnel: `ssh -N -L 18789:127.0.0.1:18789 user@host`, а потім відкрийте `http://127.0.0.1:18789/`. - - Режим зі спільним секретом: задайте `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` або `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`, а потім вставте відповідний секрет у налаштуваннях Control UI. - - Режим Tailscale Serve: переконайтеся, що `gateway.auth.allowTailscale` увімкнено і ви відкриваєте URL Serve, а не сирий URL loopback/tailnet, який обходить заголовки ідентичності Tailscale. - - Режим trusted-proxy: переконайтеся, що ви заходите через налаштований не-loopback proxy з awareness ідентичності, а не через loopback proxy на тому самому хості чи сирий URL gateway. - - Якщо невідповідність зберігається після однієї повторної спроби, ротуйте/повторно схваліть токен paired device: + - Якщо режим віддалений, спочатку створіть тунель: `ssh -N -L 18789:127.0.0.1:18789 user@host`, а потім відкрийте `http://127.0.0.1:18789/`. + - Режим спільного секрету: задайте `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` або `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`, а потім вставте відповідний секрет у налаштуваннях Control UI. + - Режим Tailscale Serve: переконайтеся, що `gateway.auth.allowTailscale` увімкнено і ви відкриваєте саме URL-адресу Serve, а не сиру loopback/tailnet URL, яка обходить заголовки ідентичності Tailscale. + - Режим trusted-proxy: переконайтеся, що ви заходите через налаштований identity-aware proxy без loopback, а не через loopback-проксі на тому самому хості чи сиру URL-адресу gateway. + - Якщо невідповідність зберігається після однієї повторної спроби, замініть/повторно затвердьте токен спареного пристрою: - `openclaw devices list` - `openclaw devices rotate --device --role operator` - - Якщо виклик rotate каже, що його відхилено, перевірте дві речі: - - сесії paired-device можуть ротувати лише **власний** пристрій, якщо лише вони не мають також `operator.admin` - - явні значення `--scope` не можуть перевищувати поточні scope operator викликача - - Усе ще застрягли? Виконайте `openclaw status --all` і дотримуйтесь [Усунення несправностей](/uk/gateway/troubleshooting). Деталі auth див. у [Dashboard](/uk/web/dashboard). + - Якщо виклик rotate каже, що йому відмовлено, перевірте дві речі: + - сесії paired-device можуть замінювати лише **власний** пристрій, якщо тільки вони також не мають `operator.admin` + - явні значення `--scope` не можуть перевищувати поточні operator scopes викликача + - Усе ще застрягли? Виконайте `openclaw status --all` і дотримуйтеся [Усунення несправностей](/uk/gateway/troubleshooting). Подробиці автентифікації див. в [Dashboard](/uk/web/dashboard). - - Bind `tailnet` вибирає IP Tailscale з мережевих інтерфейсів (100.64.0.0/10). Якщо машина не в Tailscale (або інтерфейс вимкнено), прив’язуватися нема до чого. + + Прив’язка `tailnet` вибирає Tailscale IP з мережевих інтерфейсів (100.64.0.0/10). Якщо машина не в Tailscale (або інтерфейс неактивний), прив’язуватися нема до чого. Виправлення: - Запустіть Tailscale на цьому хості (щоб він мав адресу 100.x), або - - переключіться на `gateway.bind: "loopback"` / `"lan"`. + - Перемкніться на `gateway.bind: "loopback"` / `"lan"`. - Примітка: `tailnet` — явний режим. `auto` надає перевагу loopback; використовуйте `gateway.bind: "tailnet"`, коли вам потрібна прив’язка лише до tailnet. + Примітка: `tailnet` є явним значенням. `auto` віддає перевагу loopback; використовуйте `gateway.bind: "tailnet"`, коли вам потрібна прив’язка лише до tailnet. - Зазвичай ні — один Gateway може обслуговувати кілька channels і agents. Використовуйте кілька Gateway лише тоді, коли вам потрібне резервування (наприклад, аварійний бот) або жорстка ізоляція. + Зазвичай ні — один Gateway може обслуговувати кілька каналів обміну повідомленнями й агентів. Використовуйте кілька Gateway лише тоді, коли вам потрібна резервність (наприклад, аварійний бот) або жорстка ізоляція. - Так, але потрібно ізолювати: + Так, але вам потрібно ізолювати: - - `OPENCLAW_CONFIG_PATH` (config для кожного екземпляра) - - `OPENCLAW_STATE_DIR` (state для кожного екземпляра) - - `agents.defaults.workspace` (ізоляція workspace) + - `OPENCLAW_CONFIG_PATH` (окрема конфігурація для кожного екземпляра) + - `OPENCLAW_STATE_DIR` (окремий стан для кожного екземпляра) + - `agents.defaults.workspace` (ізоляція робочої області) - `gateway.port` (унікальні порти) Швидке налаштування (рекомендовано): - Використовуйте `openclaw --profile ...` для кожного екземпляра (автоматично створює `~/.openclaw-`). - - Задайте унікальний `gateway.port` у config кожного профілю (або передавайте `--port` для ручних запусків). - - Встановіть службу для кожного профілю: `openclaw --profile gateway install`. + - Задайте унікальний `gateway.port` у конфігурації кожного профілю (або передайте `--port` для ручних запусків). + - Встановіть сервіс для кожного профілю: `openclaw --profile gateway install`. - Профілі також додають суфікси до назв служб (`ai.openclaw.`; застарілі `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`). + Профілі також додають суфікси до назв сервісів (`ai.openclaw.`; застарілі `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`). Повний посібник: [Кілька Gateway](/uk/gateway/multiple-gateways). - - Gateway — це **сервер WebSocket**, і він очікує, що першим повідомленням - буде кадр `connect`. Якщо він отримує щось інше, він закриває з’єднання + + Gateway — це **WebSocket-сервер**, і він очікує, що найперше повідомлення + буде кадром `connect`. Якщо він отримує щось інше, то закриває з’єднання з **кодом 1008** (порушення політики). Поширені причини: - - Ви відкрили URL **HTTP** у браузері (`http://...`) замість клієнта WS. + - Ви відкрили **HTTP** URL у браузері (`http://...`) замість WS-клієнта. - Ви використали неправильний порт або шлях. - - Proxy або tunnel прибрав заголовки auth чи надіслав запит, що не належить Gateway. + - Проксі або тунель прибрали заголовки автентифікації або надіслали не-Gateway запит. Швидкі виправлення: - 1. Використовуйте URL WS: `ws://:18789` (або `wss://...`, якщо HTTPS). - 2. Не відкривайте порт WS у звичайній вкладці браузера. - 3. Якщо auth увімкнено, включіть токен/пароль у кадр `connect`. + 1. Використовуйте WS URL: `ws://:18789` (або `wss://...`, якщо HTTPS). + 2. Не відкривайте WS-порт у звичайній вкладці браузера. + 3. Якщо автентифікацію ввімкнено, додайте токен/пароль у кадр `connect`. Якщо ви використовуєте CLI або TUI, URL має виглядати так: @@ -2888,36 +2892,36 @@ x-i18n: -## Логи й налагодження +## Журналювання та налагодження - - Файлові логи (структуровані): + + Файлові журнали (структуровані): ``` /tmp/openclaw/openclaw-YYYY-MM-DD.log ``` - Ви можете задати стабільний шлях через `logging.file`. Рівень файлового логування контролюється `logging.level`. Докладність консолі контролюється через `--verbose` і `logging.consoleLevel`. + Ви можете задати стабільний шлях через `logging.file`. Рівень файлового журналу задається `logging.level`. Деталізація консолі керується через `--verbose` і `logging.consoleLevel`. - Найшвидший перегляд хвоста логів: + Найшвидший перегляд хвоста журналу: ```bash openclaw logs --follow ``` - Логи служби/supervisor (коли gateway працює через launchd/systemd): + Журнали сервісу/supervisor-а (коли gateway працює через launchd/systemd): - macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` і `gateway.err.log` (типово: `~/.openclaw/logs/...`; профілі використовують `~/.openclaw-/logs/...`) - Linux: `journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager` - Windows: `schtasks /Query /TN "OpenClaw Gateway ()" /V /FO LIST` - Більше див. в [Усуненні несправностей](/uk/gateway/troubleshooting). + Докладніше див. в [Усунення несправностей](/uk/gateway/troubleshooting). - - Використовуйте допоміжні команди gateway: + + Використовуйте helper-и gateway: ```bash openclaw gateway status @@ -2929,7 +2933,7 @@ x-i18n: - Є **два режими встановлення у Windows**: + Є **два режими встановлення на Windows**: **1) WSL2 (рекомендовано):** Gateway працює всередині Linux. @@ -2941,13 +2945,13 @@ x-i18n: openclaw gateway restart ``` - Якщо ви ніколи не встановлювали службу, запустіть її на передньому плані: + Якщо ви ніколи не встановлювали сервіс, запустіть його на передньому плані: ```bash openclaw gateway run ``` - **2) Нативна Windows (не рекомендовано):** Gateway працює безпосередньо у Windows. + **2) Нативний Windows (не рекомендовано):** Gateway працює безпосередньо у Windows. Відкрийте PowerShell і виконайте: @@ -2956,18 +2960,18 @@ x-i18n: openclaw gateway restart ``` - Якщо ви запускаєте його вручну (без служби), використовуйте: + Якщо ви запускаєте його вручну (без сервісу), використовуйте: ```powershell openclaw gateway run ``` - Документація: [Windows (WSL2)](/uk/platforms/windows), [Runbook служби Gateway](/uk/gateway). + Документація: [Windows (WSL2)](/uk/platforms/windows), [Операційний посібник сервісу Gateway](/uk/gateway). - - Почніть із швидкої перевірки стану: + + Почніть зі швидкої перевірки стану: ```bash openclaw status @@ -2978,14 +2982,14 @@ x-i18n: Поширені причини: - - Auth моделі не завантажено на **хості gateway** (перевірте `models status`). - - Pairing/allowlist channel блокує відповіді (перевірте config channel + логи). + - Автентифікацію моделі не завантажено на **хості gateway** (перевірте `models status`). + - Прив’язка каналу/allowlist блокує відповіді (перевірте конфігурацію каналу + журнали). - WebChat/Dashboard відкрито без правильного токена. - Якщо ви працюєте віддалено, переконайтеся, що tunnel/Tailscale-з’єднання активне і що + Якщо ви в віддаленому режимі, переконайтеся, що тунель/Tailscale-підключення активне і Gateway WebSocket доступний. - Документація: [Channels](/uk/channels), [Усунення несправностей](/uk/gateway/troubleshooting), [Віддалений доступ](/uk/gateway/remote). + Документація: [Канали](/uk/channels), [Усунення несправностей](/uk/gateway/troubleshooting), [Віддалений доступ](/uk/gateway/remote). @@ -2995,9 +2999,9 @@ x-i18n: 1. Чи працює Gateway? `openclaw gateway status` 2. Чи справний Gateway? `openclaw status` 3. Чи має UI правильний токен? `openclaw dashboard` - 4. Якщо ви працюєте віддалено, чи активне з’єднання tunnel/Tailscale? + 4. Якщо режим віддалений, чи активне тунельне/Tailscale-підключення? - Потім перегляньте хвіст логів: + Потім подивіться журнали: ```bash openclaw logs --follow @@ -3008,7 +3012,7 @@ x-i18n: - Почніть із логів і стану channel: + Почніть із журналів і стану каналу: ```bash openclaw channels status @@ -3017,17 +3021,17 @@ x-i18n: Потім зіставте помилку: - - `BOT_COMMANDS_TOO_MUCH`: у меню Telegram забагато записів. OpenClaw уже обрізає список до ліміту Telegram і повторює спробу з меншою кількістю команд, але деякі пункти меню все одно треба прибрати. Зменште кількість команд Plugin/skill/custom або вимкніть `channels.telegram.commands.native`, якщо меню вам не потрібне. - - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!` або подібні мережеві помилки: якщо ви на VPS або за proxy, переконайтеся, що вихідний HTTPS дозволено й DNS працює для `api.telegram.org`. + - `BOT_COMMANDS_TOO_MUCH`: меню Telegram має забагато записів. OpenClaw уже обрізає його до ліміту Telegram і повторює спробу з меншою кількістю команд, але деякі записи меню все одно треба прибрати. Зменште кількість Plugin/Skill/власних команд або вимкніть `channels.telegram.commands.native`, якщо вам не потрібне меню. + - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!` або схожі мережеві помилки: якщо ви працюєте на VPS або за проксі, переконайтеся, що вихідний HTTPS дозволено і DNS працює для `api.telegram.org`. - Якщо Gateway віддалений, переконайтеся, що ви дивитеся логи на хості Gateway. + Якщо Gateway віддалений, переконайтеся, що ви дивитеся журнали саме на хості Gateway. Документація: [Telegram](/uk/channels/telegram), [Усунення несправностей каналів](/uk/channels/troubleshooting). - Спочатку переконайтеся, що Gateway доступний і agent може працювати: + Спочатку переконайтеся, що Gateway доступний і агент може працювати: ```bash openclaw status @@ -3035,23 +3039,23 @@ x-i18n: openclaw logs --follow ``` - У TUI використовуйте `/status`, щоб побачити поточний стан. Якщо ви очікуєте відповіді в chat - channel, переконайтеся, що доставку ввімкнено (`/deliver on`). + У TUI використовуйте `/status`, щоб побачити поточний стан. Якщо ви очікуєте відповіді в чаті + каналу, переконайтеся, що доставку ввімкнено (`/deliver on`). - Документація: [TUI](/uk/web/tui), [Слеш-команди](/uk/tools/slash-commands). + Документація: [TUI](/uk/web/tui), [Slash commands](/uk/tools/slash-commands). - Якщо ви встановили службу: + Якщо ви встановили сервіс: ```bash openclaw gateway stop openclaw gateway start ``` - Це зупиняє/запускає **керовану службу** (launchd на macOS, systemd на Linux). - Використовуйте це, коли Gateway працює у фоновому режимі як daemon. + Це зупиняє/запускає **керований сервіс** (launchd на macOS, systemd на Linux). + Використовуйте це, коли Gateway працює у фоновому режимі як демон. Якщо ви запускаєте його на передньому плані, зупиніть через Ctrl-C, а потім: @@ -3059,29 +3063,29 @@ x-i18n: openclaw gateway run ``` - Документація: [Runbook служби Gateway](/uk/gateway). + Документація: [Операційний посібник сервісу Gateway](/uk/gateway). - - - `openclaw gateway restart`: перезапускає **фонову службу** (launchd/systemd). + + - `openclaw gateway restart`: перезапускає **фоновий сервіс** (launchd/systemd). - `openclaw gateway`: запускає gateway **на передньому плані** для цієї сесії термінала. - Якщо ви встановили службу, використовуйте команди gateway. Використовуйте `openclaw gateway`, коли + Якщо ви встановили сервіс, використовуйте команди gateway. Використовуйте `openclaw gateway`, коли вам потрібен одноразовий запуск на передньому плані. - - Запустіть Gateway з `--verbose`, щоб отримати більше деталей у консолі. Потім перевірте файл логу на предмет auth каналу, маршрутизації моделей і помилок RPC. + + Запустіть Gateway з `--verbose`, щоб отримати детальніший вивід у консоль. Потім перегляньте файл журналу на предмет автентифікації каналу, маршрутизації моделі та RPC-помилок. -## Медіа й вкладення +## Медіа та вкладення - Вихідні вкладення від agent мають містити рядок `MEDIA:` (в окремому рядку). Див. [Налаштування assistant OpenClaw](/uk/start/openclaw) і [Надсилання Agent](/uk/tools/agent-send). + Вихідні вкладення від агента мають містити рядок `MEDIA:` (в окремому рядку). Див. [Налаштування помічника OpenClaw](/uk/start/openclaw) і [Надсилання агентом](/uk/tools/agent-send). Надсилання через CLI: @@ -3091,123 +3095,123 @@ x-i18n: Також перевірте: - - Цільовий channel підтримує вихідні медіа і не заблокований allowlist. - - Файл не перевищує обмеження розміру provider (зображення змінюються до максимуму 2048px). - - `tools.fs.workspaceOnly=true` обмежує надсилання локальних шляхів workspace, temp/media-store і файлами, перевіреними ізоляцією. - - `tools.fs.workspaceOnly=false` дозволяє `MEDIA:` надсилати локальні файли хоста, які agent уже може читати, але лише для медіа плюс безпечних типів документів (зображення, аудіо, відео, PDF і документи Office). Звичайний текст і файли, схожі на секрети, усе одно блокуються. + - Цільовий канал підтримує вихідні медіа й не заблокований allowlist-ами. + - Файл не перевищує ліміти розміру провайдера (зображення масштабуються максимум до 2048px). + - `tools.fs.workspaceOnly=true` обмежує надсилання локальних шляхів робочою областю, temp/media-store і файлами, перевіреними sandbox. + - `tools.fs.workspaceOnly=false` дозволяє `MEDIA:` надсилати локальні файли хоста, які агент уже може читати, але лише для медіа плюс безпечних типів документів (зображення, аудіо, відео, PDF і документи Office). Звичайні текстові та схожі на секрети файли все одно блокуються. Див. [Зображення](/uk/nodes/images). -## Безпека й контроль доступу +## Безпека та контроль доступу - Ставтеся до вхідних DM як до недовіреного входу. Типові значення налаштовано так, щоб зменшувати ризик: + Ставтеся до вхідних DM як до ненадійного вводу. Значення за замовчуванням розроблено для зниження ризику: - - Типова поведінка в channels із підтримкою DM — це **pairing**: + - Типова поведінка на каналах із підтримкою DM — це **pairing**: - Невідомі відправники отримують код pairing; бот не обробляє їхнє повідомлення. - - Схвалення: `openclaw pairing approve --channel [--account ] ` + - Підтвердження: `openclaw pairing approve --channel [--account ] ` - Кількість очікуваних запитів обмежена **3 на канал**; перевіряйте `openclaw pairing list --channel [--account ]`, якщо код не надійшов. - - Публічне відкриття DM вимагає явного увімкнення (`dmPolicy: "open"` і allowlist `"*"`). + - Публічне відкриття DM вимагає явного opt-in (`dmPolicy: "open"` і allowlist `"*"`). Запустіть `openclaw doctor`, щоб виявити ризиковані політики DM. - - Ні. Prompt injection — це про **недовірений вміст**, а не лише про те, хто може надсилати боту DM. - Якщо ваш assistant читає зовнішній вміст (web search/fetch, сторінки browser, emails, - docs, вкладення, вставлені логи), цей вміст може містити інструкції, які намагаються - перехопити керування моделлю. Це може статися, навіть якщо **ви єдиний відправник**. + + Ні. Prompt injection — це про **ненадійний контент**, а не лише про те, хто може писати боту в DM. + Якщо ваш помічник читає зовнішній контент (web search/fetch, сторінки браузера, листи, + документи, вкладення, вставлені журнали), цей контент може містити інструкції, які намагаються + перехопити контроль над моделлю. Це може статися, навіть якщо **ви єдиний відправник**. - Найбільший ризик виникає, коли ввімкнено tools: модель можна обдурити й змусити - ексфільтрувати контекст або викликати tools від вашого імені. Зменшуйте радіус ураження так: + Найбільший ризик виникає, коли увімкнені інструменти: модель можна обдурити й змусити + ексфільтрувати контекст або викликати інструменти від вашого імені. Зменшуйте радіус ураження так: - - використовуйте лише для читання або без tools agent типу «reader» для підсумування недовіреного вмісту - - тримайте `web_search` / `web_fetch` / `browser` вимкненими для agents з увімкненими tools - - також ставтеся до декодованого тексту файлів/документів як до недовіреного: OpenResponses - `input_file` і витягування тексту з медіавкладень обгортають витягнутий текст у - явні маркери меж зовнішнього вмісту замість передавання сирого тексту файла - - використовуйте ізоляцію та строгі allowlist для tools + - використовуйте "reader"-агента лише для читання або без інструментів, щоб підсумовувати ненадійний контент + - тримайте `web_search` / `web_fetch` / `browser` вимкненими для агентів з увімкненими інструментами + - також ставтеся до декодованого тексту файлів/документів як до ненадійного: OpenResponses + `input_file` і витяг тексту з медіавкладень обгортають витягнутий текст у + явні маркери меж зовнішнього контенту замість передавання сирого тексту файла + - використовуйте sandboxing і суворі allowlist-и інструментів Подробиці: [Безпека](/uk/gateway/security). - - Так, для більшості сценаріїв. Ізоляція бота за допомогою окремих облікових записів і номерів телефону - зменшує радіус ураження, якщо щось піде не так. Це також полегшує ротацію + + Так, для більшості конфігурацій. Ізоляція бота окремими обліковими записами й номерами телефону + зменшує радіус ураження, якщо щось піде не так. Це також спрощує заміну облікових даних або відкликання доступу без впливу на ваші особисті облікові записи. - Починайте з малого. Надавайте доступ лише до тих tools і облікових записів, які справді потрібні, і розширюйте - його пізніше за потреби. + Починайте з малого. Надавайте доступ лише до тих інструментів і облікових записів, які вам справді потрібні, і розширюйте + пізніше за потреби. Документація: [Безпека](/uk/gateway/security), [Pairing](/uk/channels/pairing). - Ми **не** рекомендуємо повну автономність над вашими особистими повідомленнями. Найбезпечніший шаблон такий: + Ми **не** рекомендуємо повну автономність над вашими особистими повідомленнями. Найбезпечніший шаблон: - - Тримайте DM у режимі **pairing** або в жорсткому allowlist. + - Тримайте DM у **режимі pairing** або в суворому allowlist. - Використовуйте **окремий номер або обліковий запис**, якщо хочете, щоб він надсилав повідомлення від вашого імені. - - Нехай він створює чернетку, а ви **схвалюєте перед надсиланням**. + - Дозвольте йому створити чернетку, а потім **затверджуйте перед надсиланням**. Якщо хочете поекспериментувати, робіть це на окремому обліковому записі й тримайте його ізольованим. Див. [Безпека](/uk/gateway/security). - - Так, **якщо** agent працює лише в чаті, а вхід є довіреним. Менші рівні - більш уразливі до перехоплення інструкціями, тож уникайте їх для agents з увімкненими tools - або коли читаєте недовірений вміст. Якщо вам усе ж потрібна менша модель, жорстко обмежте - tools і запускайте в ізольованому середовищі. Див. [Безпека](/uk/gateway/security). + + Так, **якщо** агент працює лише в чаті, а вхідні дані є довіреними. Молодші рівні + більше схильні до перехоплення інструкціями, тому уникайте їх для агентів з увімкненими інструментами + або під час читання ненадійного контенту. Якщо вам усе ж потрібно використовувати меншу модель, жорстко обмежте + інструменти й запускайте все всередині sandbox. Див. [Безпека](/uk/gateway/security). - + Коди pairing надсилаються **лише** тоді, коли невідомий відправник пише боту і - ввімкнено `dmPolicy: "pairing"`. Сам по собі `/start` не генерує код. + увімкнено `dmPolicy: "pairing"`. Сам по собі `/start` не генерує код. - Перевірте очікувані запити: + Перевірте запити, що очікують: ```bash openclaw pairing list telegram ``` - Якщо вам потрібен негайний доступ, додайте свій sender id до allowlist або задайте `dmPolicy: "open"` + Якщо вам потрібен негайний доступ, додайте свій sender id в allowlist або задайте `dmPolicy: "open"` для цього облікового запису. - Ні. Типова політика WhatsApp DM — **pairing**. Невідомі відправники лише отримують код pairing, а їхнє повідомлення **не обробляється**. OpenClaw відповідає лише в чатах, які сам отримує, або через явні надсилання, які ви запускаєте. + Ні. Типова політика WhatsApp DM — **pairing**. Невідомі відправники отримують лише код pairing, і їхнє повідомлення **не обробляється**. OpenClaw відповідає лише на чати, які отримує, або на явні надсилання, які ви запускаєте. - Схвалення pairing: + Підтвердження pairing: ```bash openclaw pairing approve whatsapp ``` - Список очікуваних запитів: + Перелік запитів, що очікують: ```bash openclaw pairing list whatsapp ``` - Запит номера телефону в майстрі: він використовується для налаштування вашого **allowlist/owner**, щоб ваші власні DM були дозволені. Він не використовується для автоматичного надсилання. Якщо ви запускаєте систему на своєму особистому номері WhatsApp, використовуйте цей номер і ввімкніть `channels.whatsapp.selfChatMode`. + Запит номера телефону в майстрі: він використовується для налаштування вашого **allowlist/owner**, щоб дозволити ваші власні DM. Він не використовується для автоматичного надсилання. Якщо ви працюєте зі своїм особистим номером WhatsApp, використовуйте цей номер і ввімкніть `channels.whatsapp.selfChatMode`. -## Команди чату, переривання завдань і «воно не зупиняється» +## Команди чату, переривання завдань і "воно не зупиняється" - Більшість внутрішніх або tool-повідомлень з’являються лише тоді, коли для цієї session увімкнено **verbose**, **trace** або **reasoning**. + Більшість внутрішніх або інструментальних повідомлень з’являються лише тоді, коли для цієї сесії ввімкнено **verbose**, **trace** або **reasoning**. Виправлення в чаті, де ви це бачите: @@ -3217,16 +3221,16 @@ x-i18n: /reasoning off ``` - Якщо все одно занадто шумно, перевірте налаштування session у Control UI і встановіть verbose - у значення **inherit**. Також переконайтеся, що ви не використовуєте профіль бота з `verboseDefault`, заданим - як `on` у config. + Якщо шум усе ще є, перевірте налаштування сесії в Control UI і встановіть verbose + на **inherit**. Також переконайтеся, що ви не використовуєте профіль бота з `verboseDefault`, заданим + як `on` у конфігурації. Документація: [Thinking і verbose](/uk/tools/thinking), [Безпека](/uk/gateway/security#reasoning-verbose-output-in-groups). - - Надішліть будь-яке з наведеного **як окреме повідомлення** (без слеша): + + Надішліть будь-яке з цього **як окреме повідомлення** (без слеша): ``` stop @@ -3250,25 +3254,25 @@ x-i18n: interrupt ``` - Це тригери переривання (не слеш-команди). + Це тригери переривання (не slash commands). - Для фонових процесів (із tool exec) ви можете попросити agent виконати: + Для фонових процесів (з інструмента exec) ви можете попросити агента виконати: ``` process action:kill sessionId:XXX ``` - Огляд слеш-команд див. у [Слеш-командах](/uk/tools/slash-commands). + Огляд slash commands: див. [Slash commands](/uk/tools/slash-commands). - Більшість команд треба надсилати як **окреме** повідомлення, що починається з `/`, але деякі скорочення (наприклад `/status`) також працюють inline для відправників з allowlist. + Більшість команд потрібно надсилати як **окреме** повідомлення, що починається з `/`, але деякі скорочення (наприклад `/status`) також працюють inline для відправників із allowlist. - - OpenClaw типово блокує повідомлення **між різними providers**. Якщо виклик tool прив’язаний + + OpenClaw типово блокує повідомлення **між різними провайдерами**. Якщо виклик інструмента прив’язаний до Telegram, він не надсилатиме в Discord, якщо ви явно цього не дозволите. - Увімкніть крос-provider повідомлення для agent: + Увімкніть міжпровайдерне надсилання повідомлень для агента: ```json5 { @@ -3283,20 +3287,20 @@ x-i18n: } ``` - Після редагування config перезапустіть gateway. + Перезапустіть gateway після редагування конфігурації. - Режим queue керує тим, як нові повідомлення взаємодіють із запуском, що вже виконується. Використовуйте `/queue`, щоб змінити режими: + Режим черги визначає, як нові повідомлення взаємодіють із поточним запуском. Використовуйте `/queue`, щоб змінити режими: - - `steer` — нові повідомлення перенаправляють поточне завдання - - `followup` — повідомлення виконуються по одному - - `collect` — повідомлення збираються в пакет і надсилається одна відповідь (типово) - - `steer-backlog` — перенаправити зараз, а потім обробити backlog - - `interrupt` — перервати поточний запуск і почати заново + - `steer` - нові повідомлення перенаправляють поточне завдання + - `followup` - запускати повідомлення по одному + - `collect` - об’єднувати повідомлення в пакет і відповідати один раз (типово) + - `steer-backlog` - спочатку перенаправити, потім обробити беклог + - `interrupt` - перервати поточний запуск і почати заново - Ви можете додавати параметри, як-от `debounce:2s cap:25 drop:summarize`, для режимів followup. + Ви можете додавати параметри на кшталт `debounce:2s cap:25 drop:summarize` для режимів followup. @@ -3304,11 +3308,11 @@ x-i18n: ## Різне - - В OpenClaw облікові дані й вибір моделі — це окремі речі. Задання `ANTHROPIC_API_KEY` (або збереження ключа Anthropic API у профілях auth) вмикає автентифікацію, але фактична типова модель — це те, що ви налаштовуєте в `agents.defaults.model.primary` (наприклад, `anthropic/claude-sonnet-4-6` або `anthropic/claude-opus-4-6`). Якщо ви бачите `No credentials found for profile "anthropic:default"`, це означає, що Gateway не зміг знайти облікові дані Anthropic в очікуваному `auth-profiles.json` для agent, який виконується. + + В OpenClaw облікові дані та вибір моделі — це окремі речі. Задання `ANTHROPIC_API_KEY` (або збереження API-ключа Anthropic у профілях автентифікації) вмикає автентифікацію, але фактична модель за замовчуванням — це те, що ви налаштовуєте в `agents.defaults.model.primary` (наприклад, `anthropic/claude-sonnet-4-6` або `anthropic/claude-opus-4-6`). Якщо ви бачите `No credentials found for profile "anthropic:default"`, це означає, що Gateway не зміг знайти облікові дані Anthropic в очікуваному `auth-profiles.json` для агента, який зараз працює. --- -Усе ще застрягли? Запитайте в [Discord](https://discord.com/invite/clawd) або відкрийте [обговорення GitHub](https://github.com/openclaw/openclaw/discussions). +Усе ще застрягли? Запитайте в [Discord](https://discord.com/invite/clawd) або відкрийте [обговорення на GitHub](https://github.com/openclaw/openclaw/discussions). diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index c1920edd1..05b86b7cc 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,162 +1,159 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресійних тестів для помилок моделі/провайдера - - Налагодження поведінки Gateway та агента -summary: 'Набір для тестування: unit/e2e/live набори, Docker-ранери та що охоплює кожен тест' + - Додавання регресійних тестів для багів моделі/провайдера + - Налагодження поведінки Gateway + агента +summary: 'Набір для тестування: набори unit/e2e/live, ранери Docker і що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-23T14:49:06Z" + generated_at: "2026-04-23T18:24:14Z" model: gpt-5.4 provider: openai - source_hash: fbec4996699577321116c94f60c01d205d7594ed41aca27c821f1c3d65a7dca3 + source_hash: e895fc7a9e4528035e87e360fa345caf22f89009ea52be9f2ba04bf5c5af4f55 source_path: help/testing.md workflow: 15 --- -# Тестування +OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір +ранерів Docker. Цей документ — посібник «як ми тестуємо»: -OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-ранерів. - -Цей документ — посібник «як ми тестуємо»: - -- Що охоплює кожен набір (і що він навмисно _не_ охоплює) -- Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження) -- Як live-тести знаходять облікові дані та вибирають моделі/провайдерів -- Як додавати регресійні тести для реальних проблем моделей/провайдерів +- Що охоплює кожен набір (і що він навмисно _не_ охоплює). +- Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження). +- Як live-тести знаходять облікові дані та вибирають моделі/провайдерів. +- Як додавати регресійні тести для реальних проблем із моделями/провайдерами. ## Швидкий старт У більшості випадків: -- Повний бар’єр перевірок (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- Швидший локальний запуск повного набору на продуктивній машині: `pnpm test:max` -- Прямий цикл Vitest watch: `pnpm test:watch` +- Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- Швидший локальний запуск усього набору на потужній машині: `pnpm test:max` +- Безпосередній цикл спостереження Vitest: `pnpm test:watch` - Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Якщо ви ітеруєтеся над одним падінням, спочатку віддавайте перевагу цільовим запускам. -- QA-сайт на основі Docker: `pnpm qa:lab:up` -- QA-смуга на основі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Під час ітерації над одним збоєм спершу надавайте перевагу цільовим запускам. +- QA-сайт на базі Docker: `pnpm qa:lab:up` +- QA-lane на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Коли ви змінюєте тести або хочете більше впевненості: +Коли ви змінюєте тести або хочете додаткової впевненості: -- Бар’єр перевірки покриття: `pnpm test:coverage` +- Gate покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): - Live-набір (моделі + перевірки інструментів/зображень Gateway): `pnpm test:live` -- Запустити один live-файл без зайвого виводу: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Docker live-перевірка моделей: `pnpm test:docker:live-models` - - Кожна вибрана модель тепер виконує текстовий хід плюс невелику перевірку в стилі читання файла. - Моделі, метадані яких вказують на вхід `image`, також виконують невеликий хід із зображенням. +- Тихо націлитися на один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Перевірка live-моделей у Docker: `pnpm test:docker:live-models` + - Кожна вибрана модель тепер запускає текстовий хід плюс невелику перевірку в стилі читання файлу. + Моделі, у метаданих яких вказано вхід `image`, також запускають невеликий хід із зображенням. Вимкніть додаткові перевірки через `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0`, коли ізолюєте збої провайдера. - Покриття в CI: щоденні `OpenClaw Scheduled Live And E2E Checks` і ручні `OpenClaw Release Checks` обидва викликають повторно використовуваний workflow live/E2E з - `include_live_suites: true`, що включає окремі матричні завдання Docker live model, - розшардовані за провайдером. - - Для цільових повторних запусків у CI викличте `OpenClaw Live And E2E Checks (Reusable)` + `include_live_suites: true`, який включає окремі matrix jobs Docker live model, + розбиті за провайдерами. + - Для цільових повторних запусків у CI викликайте `OpenClaw Live And E2E Checks (Reusable)` з `include_live_suites: true` і `live_models_only: true`. - - Додайте нові high-signal секрети провайдерів до `scripts/ci-hydrate-live-auth.sh`, + - Додавайте нові високосигнальні секрети провайдерів до `scripts/ci-hydrate-live-auth.sh`, а також до `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його - викликів scheduled/release. -- Moonshot/Kimi cost smoke: якщо встановлено `MOONSHOT_API_KEY`, виконайте - `openclaw models list --provider moonshot --json`, а потім виконайте ізольований + викликачів за розкладом/релізом. +- Перевірка вартості Moonshot/Kimi: якщо встановлено `MOONSHOT_API_KEY`, виконайте + `openclaw models list --provider moonshot --json`, а потім запустіть ізольований `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` для `moonshot/kimi-k2.6`. Переконайтеся, що JSON повідомляє про Moonshot/K2.6 і що транскрипт помічника зберігає нормалізоване `usage.cost`. -Порада: коли потрібен лише один проблемний випадок, краще звужувати live-тести через змінні середовища allowlist, описані нижче. +Порада: коли вам потрібен лише один збійний випадок, надавайте перевагу звуженню live-тестів через allowlist-змінні середовища, описані нижче. -## QA-специфічні ранери +## Спеціалізовані QA-ранери -Ці команди розташовані поруч з основними наборами тестів, коли вам потрібен реалізм qa-lab: +Ці команди розміщені поруч з основними наборами тестів, коли вам потрібен реалізм qa-lab: -CI запускає QA Lab в окремих workflow. `Parity gate` запускається на відповідних PR і -через ручний запуск із mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на -`main` і через ручний запуск з mock parity gate, live Matrix lane та -керованою Convex live Telegram lane як паралельними завданнями. `OpenClaw Release Checks` -запускає ті самі смуги перед затвердженням релізу. +CI запускає QA Lab в окремих workflow. `Parity gate` запускається для відповідних PR і +через ручний dispatch із mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на +`main` і через ручний dispatch із mock parity gate, live Matrix lane та +live Telegram lane під керуванням Convex як паралельні jobs. `OpenClaw Release Checks` +запускає ті самі lane перед затвердженням релізу. - `pnpm openclaw qa suite` - - Запускає QA-сценарії на основі репозиторію безпосередньо на хості. + - Запускає сценарії QA з репозиторію безпосередньо на хості. - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими - воркерами Gateway. `qa-channel` за замовчуванням використовує concurrency 4 (обмежується - кількістю вибраних сценаріїв). Використовуйте `--concurrency ` для налаштування - кількості воркерів або `--concurrency 1` для старішої послідовної смуги. - - Завершується з ненульовим кодом, якщо будь-який сценарій не пройшов. Використовуйте `--allow-failures`, якщо + worker-процесами gateway. `qa-channel` за замовчуванням має concurrency 4 (обмежену + кількістю вибраних сценаріїв). Використовуйте `--concurrency ` для налаштування кількості + worker-процесів або `--concurrency 1` для старішого послідовного lane. + - Завершується з ненульовим кодом, якщо будь-який сценарій зазнає збою. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. - `aimock` запускає локальний сервер провайдера на основі AIMock для експериментального - покриття фікстур і протокольних mock-сценаріїв без заміни сценарно-орієнтованої - смуги `mock-openai`. + `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального + покриття фікстур і моків протоколу без заміни lane `mock-openai`, орієнтованого на сценарії. - `pnpm openclaw qa suite --runner multipass` - Запускає той самий QA-набір усередині тимчасової Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски пересилають підтримувані QA-входи автентифікації, які практично використовувати в гостьовому середовищі: - ключі провайдера через env, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він присутній. - - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гість міг записувати назад через + - У live-запусках пересилає підтримувані входи автентифікації QA, практичні для гостьової системи: + ключі провайдерів на основі env, шлях до конфігурації live-провайдера QA і `CODEX_HOME`, + якщо він присутній. + - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через змонтований workspace. - - Записує звичайні QA-звіт і підсумок, а також логи Multipass у + - Записує звичайний QA-звіт і підсумок, а також журнали Multipass у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає QA-сайт на основі Docker для QA-роботи в операторському стилі. + - Запускає QA-сайт на базі Docker для QA-роботи в операторському стилі. - `pnpm test:docker:npm-onboard-channel-agent` - - Збирає npm tarball з поточного checkout, глобально встановлює його в - Docker, виконує неінтерактивний онбординг OpenAI API key, за замовчуванням налаштовує Telegram, - перевіряє, що ввімкнення plugin встановлює runtime-залежності за потреби, - запускає doctor і виконує один локальний хід агента проти mock endpoint OpenAI. - - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити ту саму смугу - packaged-install з Discord. + - Збирає npm tarball із поточного checkout, глобально встановлює його в + Docker, виконує неінтерактивний онбординг OpenAI API-key, за замовчуванням налаштовує Telegram, + перевіряє, що ввімкнення plugin встановлює runtime-залежності на вимогу, + запускає doctor і виконує один локальний хід агента проти моканого endpoint OpenAI. + - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити той самий lane + пакетного встановлення з Discord. - `pnpm test:docker:bundled-channel-deps` - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway - з налаштованим OpenAI, а потім вмикає вбудовані channel/plugin через редагування config. - - Перевіряє, що виявлення setup не залишає неналаштовані runtime-залежності plugin присутніми, - що перший налаштований запуск Gateway або doctor встановлює runtime-залежності кожного вбудованого - plugin за потреби, і що другий перезапуск не перевстановлює залежності, + з налаштованим OpenAI, а потім вмикає вбудовані channel/plugin через + редагування конфігурації. + - Перевіряє, що під час виявлення налаштувань runtime-залежності + неналаштованих plugin відсутні, що перший налаштований запуск Gateway або doctor встановлює runtime-залежності + кожного вбудованого plugin на вимогу, і що другий перезапуск не перевстановлює залежності, які вже були активовані. - - Також встановлює відому старішу базову версію npm, вмикає Telegram перед виконанням - `openclaw update --tag ` і перевіряє, що - `doctor` кандидата після оновлення відновлює runtime-залежності вбудованих channel - без postinstall-виправлення з боку тестового оточення. + - Також встановлює відому старішу базову версію npm, вмикає Telegram перед запуском + `openclaw update --tag ` і перевіряє, що post-update doctor кандидата + відновлює runtime-залежності вбудованого channel без postinstall-відновлення + з боку harness. - `pnpm openclaw qa aimock` - - Запускає лише локальний сервер провайдера AIMock для прямого - smoke-тестування протоколу. + - Запускає лише локальний сервер провайдера AIMock для безпосереднього smoke-тестування протоколу. - `pnpm openclaw qa matrix` - - Запускає live QA-смугу Matrix проти тимчасового Docker-based homeserver Tuwunel. - - Сьогодні цей QA-хост призначений лише для repo/dev. Packaged-інсталяції OpenClaw не постачають - `qa-lab`, тому вони не надають `openclaw qa`. - - Checkout репозиторію завантажує вбудований раннер безпосередньо; окремий крок встановлення plugin не потрібен. - - Створює трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, після чого запускає дочірній QA gateway з реальним Matrix plugin як транспортом SUT. - - За замовчуванням використовує зафіксований стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначайте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, якщо потрібно протестувати інший образ. - - Matrix не надає спільних прапорців джерела облікових даних, оскільки ця смуга локально створює тимчасових користувачів. - - Записує Matrix QA report, summary, артефакт observed-events і об’єднаний лог виводу stdout/stderr у `.artifacts/qa-e2e/...`. + - Запускає live QA lane Matrix проти тимчасового homeserver Tuwunel на базі Docker. + - Цей QA-хост наразі призначений лише для репозиторію/розробки. Пакетні встановлення OpenClaw не постачають + `qa-lab`, тому не надають `openclaw qa`. + - Checkout-и репозиторію завантажують вбудований раннер безпосередньо; окремий крок встановлення plugin не потрібен. + - Налаштовує трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) і одну приватну кімнату, після чого запускає дочірній QA gateway із реальним plugin Matrix як транспортом SUT. + - За замовчуванням використовує закріплений стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначайте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, якщо потрібно протестувати інший образ. + - Matrix не надає спільних прапорців джерела облікових даних, оскільки lane локально створює тимчасових користувачів. + - Записує QA-звіт Matrix, підсумок, артефакт observed-events і комбінований журнал виводу stdout/stderr до `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Запускає live QA-смугу Telegram проти реальної приватної групи з використанням токенів ботів driver і SUT із env. - - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим chat id Telegram. - - Підтримує `--credential-source convex` для спільних пулових облікових даних. За замовчуванням використовуйте режим env, або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб перейти на pooled leases. - - Завершується з ненульовим кодом, якщо будь-який сценарій не пройшов. Використовуйте `--allow-failures`, якщо + - Запускає live QA lane Telegram проти реальної приватної групи, використовуючи токени ботів driver і SUT із env. + - Потрібні `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. ID групи має бути числовим ID чату Telegram. + - Підтримує `--credential-source convex` для спільних пулових облікових даних. За замовчуванням використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути орендовані з пулу облікові дані. + - Завершується з ненульовим кодом, якщо будь-який сценарій зазнає збою. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. - - Потребує двох різних ботів в одній приватній групі, причому бот SUT має мати username Telegram. - - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати bot-трафік у групі. - - Записує Telegram QA report, summary і артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту на надсилання driver до спостереженої відповіді SUT. + - Потребує двох різних ботів в одній приватній групі, причому бот SUT має мати ім’я користувача Telegram. + - Для стабільного спостереження bot-to-bot увімкніть режим Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати трафік ботів у групі. + - Записує QA-звіт Telegram, підсумок і артефакт observed-messages до `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту надсилання driver до спостереженої відповіді SUT. -Live transport lanes використовують один стандартний контракт, щоб нові транспорти не дрейфували: +Live transport lane використовують один стандартний контракт, щоб нові транспорти не відхилялися від нього: -`qa-channel` залишається широким синтетичним QA-набором і не є частиною матриці live -transport coverage. +`qa-channel` залишається широким синтетичним QA-набором і не є частиною матриці покриття live transport. -| Lane | Canary | Гейтінг згадувань | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша взаємодія в треді | Ізоляція тредів | Спостереження за реакціями | Команда help | -| -------- | ------ | ----------------- | -------------------- | ------------------------- | ----------------------------- | -------------------------- | --------------- | -------------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Lane | Canary | Гейтінг згадок | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальші повідомлення в треді | Ізоляція тредів | Спостереження за реакціями | Команда help | +| -------- | ------ | -------------- | -------------------- | ------------------------- | ----------------------------- | ----------------------------- | --------------- | -------------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Спільні облікові дані Telegram через Convex (v1) -Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), -QA lab отримує ексклюзивну оренду з пулу на основі Convex, надсилає Heartbeat -для цієї оренди, поки смуга виконується, і звільняє оренду під час завершення роботи. +Коли для +`openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), +QA lab отримує ексклюзивну оренду з пулу на базі Convex, надсилає Heartbeat +для цієї оренди, поки lane працює, і звільняє оренду під час завершення роботи. Еталонний каркас проєкту Convex: @@ -164,13 +161,13 @@ QA lab отримує ексклюзивну оренду з пулу на ос Обов’язкові змінні середовища: -- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад, `https://your-deployment.convex.site`) +- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад `https://your-deployment.convex.site`) - Один секрет для вибраної ролі: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` для `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` - Вибір ролі облікових даних: - CLI: `--credential-role maintainer|ci` - - Значення env за замовчуванням: `OPENCLAW_QA_CREDENTIAL_ROLE` (у CI за замовчуванням `ci`, інакше `maintainer`) + - Значення env за замовчуванням: `OPENCLAW_QA_CREDENTIAL_ROLE` (за замовчуванням `ci` у CI, інакше `maintainer`) Необов’язкові змінні середовища: @@ -179,15 +176,15 @@ QA lab отримує ексклюзивну оренду з пулу на ос - `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (за замовчуванням `90000`) - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (за замовчуванням `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (за замовчуванням `/qa-credentials/v1`) -- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов’язковий trace id) +- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов’язковий trace ID) - `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL Convex лише для локальної розробки. -У звичайному режимі роботи `OPENCLAW_QA_CONVEX_SITE_URL` має використовувати `https://`. +`OPENCLAW_QA_CONVEX_SITE_URL` у звичайному режимі роботи має використовувати `https://`. -Команди адміністрування для мейнтейнерів (додавання/видалення/список пулу) потребують +Адміністративні команди maintainer (додавання/видалення/перелік пулу) вимагають саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -CLI-хелпери для мейнтейнерів: +Допоміжні CLI-команди для maintainer: ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -195,7 +192,7 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Використовуйте `--json` для машиночитаного виводу в скриптах і утилітах CI. +Використовуйте `--json` для машинозчитуваного виводу в скриптах і CI-утилітах. Контракт endpoint за замовчуванням (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): @@ -220,63 +217,63 @@ pnpm openclaw qa credentials remove --credential-id - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` -Форма payload для типу Telegram: +Форма payload для kind Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` має бути рядком із числовим Telegram chat id. +- `groupId` має бути рядком із числовим ID чату Telegram. - `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректні payload. ### Додавання channel до QA -Додавання channel до markdown-системи QA потребує рівно двох речей: +Додавання channel до markdown-системи QA вимагає рівно двох речей: -1. Адаптер транспорту для channel. -2. Набір сценаріїв, що перевіряє контракт channel. +1. Адаптер транспорту для цього channel. +2. Набір сценаріїв, який перевіряє контракт channel. Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` може -взяти цей потік на себе. +керувати цим потоком. -`qa-lab` володіє спільною хост-механікою: +`qa-lab` керує спільною хост-механікою: -- кореневою командою `openclaw qa` +- кореневим командним простором `openclaw qa` - запуском і завершенням набору -- паралелізмом воркерів +- concurrency worker-процесів - записом артефактів - генерацією звітів - виконанням сценаріїв -- aliases сумісності для старіших сценаріїв `qa-channel` +- alias сумісності для старіших сценаріїв `qa-channel` -Runner-плагіни володіють транспортним контрактом: +Runner plugins керують транспортним контрактом: - як `openclaw qa ` монтується під спільним коренем `qa` -- як Gateway налаштовується для цього транспорту +- як налаштовується gateway для цього транспорту - як перевіряється готовність - як інжектуються вхідні події - як спостерігаються вихідні повідомлення - як надаються транскрипти та нормалізований стан транспорту -- як виконуються дії, підтримувані транспортом -- як обробляється транспортно-специфічний скидання або очищення +- як виконуються дії, підтримані транспортом +- як обробляються специфічні для транспорту скидання або очищення -Мінімальний поріг впровадження для нового channel: +Мінімальний поріг упровадження для нового channel: 1. Залишайте `qa-lab` власником спільного кореня `qa`. -2. Реалізуйте transport runner на спільному хостовому seam `qa-lab`. -3. Залишайте транспортно-специфічну механіку всередині runner plugin або harness channel. +2. Реалізуйте transport runner на спільному хост-інтерфейсі `qa-lab`. +3. Зберігайте специфічну для транспорту механіку всередині runner plugin або harness channel. 4. Монтуйте runner як `openclaw qa ` замість реєстрації конкуруючої кореневої команди. - Runner plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. - Тримайте `runtime-api.ts` легким; лінивий CLI і виконання runner мають залишатися за окремими entrypoint. + Runner plugins повинні оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` із `runtime-api.ts`. + Тримайте `runtime-api.ts` легким; відкладений CLI і виконання runner мають залишатися за окремими entrypoint. 5. Створюйте або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. -6. Використовуйте узагальнені helper для нових сценаріїв. -7. Зберігайте наявні aliases сумісності працездатними, якщо лише репозиторій не виконує навмисну міграцію. +6. Використовуйте загальні helper-функції сценаріїв для нових сценаріїв. +7. Зберігайте наявні alias сумісності працездатними, якщо тільки репозиторій не виконує навмисну міграцію. -Правило ухвалення рішення суворе: +Правило прийняття рішення суворе: -- Якщо поведінку можна один раз виразити в `qa-lab`, поміщайте її в `qa-lab`. -- Якщо поведінка залежить від одного транспорту channel, залишайте її в цьому runner plugin або harness plugin. -- Якщо сценарій потребує нової можливості, яку може використовувати більше ніж один channel, додавайте узагальнений helper замість channel-специфічної гілки в `suite.ts`. -- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій транспортно-специфічним і явно вказуйте це в контракті сценарію. +- Якщо поведінку можна виразити один раз у `qa-lab`, розміщуйте її в `qa-lab`. +- Якщо поведінка залежить від одного channel transport, зберігайте її в цьому runner plugin або plugin harness. +- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один channel, додайте загальний helper замість channel-specific гілки в `suite.ts`. +- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій transport-specific і явно вказуйте це в контракті сценарію. -Бажані назви узагальнених helper для нових сценаріїв: +Для нових сценаріїв бажані такі назви загальних helper-функцій: - `waitForTransportReady` - `waitForChannelReady` @@ -291,7 +288,7 @@ Runner-плагіни володіють транспортним контрак - `formatTransportTranscript` - `resetTransport` -Aliases сумісності залишаються доступними для наявних сценаріїв, зокрема: +Alias сумісності залишаються доступними для наявних сценаріїв, зокрема: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -299,105 +296,137 @@ Aliases сумісності залишаються доступними для - `formatConversationTranscript` - `resetBus` -Нова робота з channel має використовувати узагальнені назви helper. -Aliases сумісності існують, щоб уникнути міграції за схемою flag day, а не як модель для +Нова робота над channel повинна використовувати загальні назви helper-функцій. +Alias сумісності існують, щоб уникнути міграції «в один день», а не як модель для створення нових сценаріїв. ## Набори тестів (що де запускається) -Сприймайте набори як «зростання реалізму» (і зростання нестабільності/вартості): +Сприймайте набори як «зростання реалістичності» (і зростання нестабільності/вартості): -### Unit / integration (типово) +### Unit / integration (за замовчуванням) - Команда: `pnpm test` -- Конфіг: ненаправлені запуски використовують набір шардів `vitest.full-*.config.ts` і можуть розгортати multi-project шарди в окремі project-конфіги для паралельного планування -- Файли: core/unit inventory у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, які охоплює `vitest.unit.config.ts` +- Конфігурація: нетаргетовані запуски використовують набір шардів `vitest.full-*.config.ts` і можуть розгортати multi-project shards у конфігурації для окремих проєктів для паралельного планування +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, що покриваються `vitest.unit.config.ts` - Обсяг: - Чисті unit-тести - - In-process integration-тести (автентифікація gateway, маршрутизація, tooling, парсинг, config) + - In-process integration-тести (автентифікація gateway, маршрутизація, інструменти, парсинг, конфігурація) - Детерміновані регресії для відомих багів - Очікування: - - Запускається в CI + - Запускаються в CI - Реальні ключі не потрібні - - Має бути швидким і стабільним -- Примітка щодо project: - - Ненаправлений `pnpm test` тепер запускає дванадцять менших shard-конфігів (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project процесу. Це зменшує піковий RSS на завантажених машинах і не дозволяє роботі auto-reply/extension блокувати не пов’язані набори. - - `pnpm test --watch` усе ще використовує native root-граф project із `vitest.config.ts`, тому що multi-shard цикл watch не є практичним. - - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файл/каталог через scoped lanes, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної ціни запуску root project. - - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff торкається лише маршрутизованих source/test-файлів; редагування config/setup усе ще повертаються до широкого повторного запуску root-project. - - `pnpm check:changed` — це звичайний розумний локальний бар’єр перевірки для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, metadata релізу та tooling, а потім запускає відповідні lane typecheck/lint/test. Зміни публічного Plugin SDK і plugin-contract включають перевірку extension, тому що extensions залежать від цих core-контрактів. Підвищення версії лише в metadata релізу запускають цільові перевірки version/config/root-dependency замість повного набору, із захистом, який відхиляє зміни package поза полем version верхнього рівня. - - Unit-тести з легкими імпортами з agents, commands, plugins, helper `auto-reply`, `plugin-sdk` та подібних суто утилітарних областей маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. - - Вибрані source-файли helper у `plugin-sdk` і `commands` також зіставляють changed-mode запуски з явними sibling-тестами в цих легких lanes, тож редагування helper уникають повторного запуску всього важкого набору для цього каталогу. - - `auto-reply` тепер має три окремі кошики: helper верхнього рівня core, integration-тести верхнього рівня `reply.*` і піддерево `src/auto-reply/reply/**`. Це не дає найважчій роботі harness reply потрапляти до дешевих тестів status/chunk/token. -- Примітка щодо embedded runner: - - Коли ви змінюєте входи виявлення message-tool або runtime-контекст Compaction, - зберігайте обидва рівні покриття. - - Додавайте цільові регресії helper для чистих меж маршрутизації/нормалізації. - - Також підтримуйте healthy integration-набори embedded runner: - `src/agents/pi-embedded-runner/compact.hooks.test.ts`, - `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і - `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped id і поведінка Compaction все ще проходять - через реальні шляхи `run.ts` / `compact.ts`; тести лише helper не є - достатньою заміною для цих integration-шляхів. -- Примітка щодо pool: - - Базовий конфіг Vitest тепер за замовчуванням використовує `threads`. - - Спільний конфіг Vitest також фіксує `isolate: false` і використовує неізольований runner у root project, e2e і live-конфігах. - - Root UI lane зберігає свій `jsdom` setup і optimizer, але тепер також працює на спільному неізольованому runner. - - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільного конфігу Vitest. - - Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити V8 compile churn під час великих локальних запусків. Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. -- Примітка щодо швидкої локальної ітерації: - - `pnpm changed:lanes` показує, які архітектурні lane запускає diff. - - Хук pre-commit запускає `pnpm check:changed --staged` після staged formatting/linting, тому core-only коміти не оплачують вартість тестів extension, якщо вони не торкаються публічних контрактів, орієнтованих на extension. Коміти лише з metadata релізу залишаються на цільовій lane version/config/root-dependency. - - Якщо точний staged-набір змін уже було перевірено рівноцінними або сильнішими бар’єрами, використовуйте `scripts/committer --fast "" `, щоб пропустити лише повторний запуск changed-scope hook. Staged format/lint усе ще запускаються. Згадайте виконані бар’єри перевірки у вашому handoff. Це також припустимо після повторного запуску ізольованого flaky hook failure, який пройшов із scoped proof. - - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи чітко зіставляються з меншим набором. - - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищим обмеженням воркерів. - - Автомасштабування локальних воркерів тепер навмисно консервативне й також знижує навантаження, коли host load average вже високе, тому кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. - - Базовий конфіг Vitest позначає файли projects/config як `forceRerunTriggers`, щоб повторні запуски в changed-mode залишалися коректними, коли змінюється обв’язка тестів. - - Конфіг зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних host; встановіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання. -- Примітка щодо perf-debug: - - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпорту плюс вивід розбивки імпорту. - - `pnpm test:perf:imports:changed` обмежує той самий профільований перегляд файлами, зміненими від `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` з native root-project шляхом для цього зафіксованого diff і виводить wall time плюс macOS max RSS. -- `pnpm test:perf:changed:bench -- --worktree` бенчмаркує поточне брудне дерево, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root-конфіг Vitest. - - `pnpm test:perf:profile:main` записує main-thread CPU profile для накладних витрат запуску й трансформації Vitest/Vite. - - `pnpm test:perf:profile:runner` записує runner CPU+heap profiles для unit-набору з вимкненим файловим паралелізмом. + - Мають бути швидкими й стабільними + + - Нетаргетований `pnpm test` запускає дванадцять менших shard-конфігурацій (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського нативного root-project process. Це зменшує піковий RSS на завантажених машинах і не дозволяє роботі auto-reply/extension виснажувати не пов’язані набори. - `pnpm test --watch` усе ще використовує граф проєктів нативного root `vitest.config.ts`, тому що multi-shard watch-цикл непрактичний. - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped lanes, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` не платить повну ціну запуску root project. - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff торкається лише маршрутизованих source/test-файлів; редагування config/setup усе ще повертаються до широкого повторного запуску root-project. - `pnpm check:changed` — це стандартний smart local gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata і tooling, а потім запускає відповідні lanes typecheck/lint/test. Зміни у публічному Plugin SDK і plugin-contract включають перевірку extension, тому що extensions залежать від цих core-контрактів. Підвищення версії лише в release metadata запускають цільові перевірки version/config/root-dependency замість повного набору, із захистом, який відхиляє зміни package поза полем version верхнього рівня. - Легкі щодо імпортів unit-тести з agents, commands, plugins, helper-функцій auto-reply, `plugin-sdk` та подібних чистих утилітних ділянок маршрутизуються через lane `unit-fast`, яка пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. - Вибрані helper source-файли `plugin-sdk` і `commands` також зіставляють запуски changed-mode з явними sibling tests у цих легких lanes, тож редагування helper-функцій не призводить до повторного запуску всього важкого набору для цього каталогу. - `auto-reply` має три окремі кошики: helper-функції core верхнього рівня, integration-тести верхнього рівня `reply.*` і піддерево `src/auto-reply/reply/**`. Це утримує найважчу роботу harness reply подалі від дешевих тестів status/chunk/token. + + + + - Коли ви змінюєте входи виявлення message-tool або runtime-контекст compaction, зберігайте обидва рівні покриття. + - Додавайте цільові helper-регресії для чистих меж маршрутизації та нормалізації. + - Підтримуйте в здоровому стані integration-набори embedded runner: + `src/agents/pi-embedded-runner/compact.hooks.test.ts`, + `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і + `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. + - Ці набори перевіряють, що scoped ID і поведінка compaction усе ще проходять + через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є + достатньою заміною для цих integration-шляхів. + + + + - Базова конфігурація Vitest за замовчуванням використовує `threads`. + - Спільна конфігурація Vitest фіксує `isolate: false` і використовує + неізольований runner у root projects, e2e та live configs. + - Root UI lane зберігає свій `jsdom` setup та optimizer, але теж працює на + спільному неізольованому runner. + - Кожен shard `pnpm test` успадковує ті самі значення за замовчуванням `threads` + `isolate: false` + зі спільної конфігурації Vitest. + - `scripts/run-vitest.mjs` за замовчуванням додає `--no-maglev` для дочірніх Node-процесів Vitest, + щоб зменшити churn компіляції V8 під час великих локальних запусків. + Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною + поведінкою V8. + + + + - `pnpm changed:lanes` показує, які архітектурні lanes запускає diff. + - Pre-commit hook запускає `pnpm check:changed --staged` після staged + форматування/linting, тож commit-и лише для core не оплачують вартість extension tests, + якщо не торкаються публічних контрактів, орієнтованих на extension. Commit-и лише з + release metadata залишаються в цільовому lane + version/config/root-dependency. + - Якщо точний набір staged changes уже було перевірено + рівними або сильнішими gate, використовуйте + `scripts/committer --fast "" `, щоб пропустити лише + повторний запуск hook changed-scope. Staged format/lint все одно запускаються. Згадайте + завершені gates у вашому handoff. Це також прийнятно після повторного запуску + ізольованого нестабільного збою hook, якщо він проходить із scoped proof. + - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи + чітко зіставляються з меншим набором. + - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, + лише з вищим обмеженням worker-процесів. + - Автомасштабування локальних worker-процесів навмисно консервативне й зменшується, + коли середнє навантаження хоста вже високе, тож кілька одночасних + запусків Vitest за замовчуванням завдають менше шкоди. + - Базова конфігурація Vitest позначає проєкти/конфігураційні файли як + `forceRerunTriggers`, щоб повторні запуски в changed-mode залишалися коректними, коли змінюється wiring тестів. + - Конфігурація тримає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних + хостах; встановіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете + одну явну локацію кешу для безпосереднього профілювання. + + + + - `pnpm test:perf:imports` вмикає звітність Vitest про тривалість імпорту плюс + вивід деталізації імпортів. + - `pnpm test:perf:imports:changed` обмежує те саме профілювання + файлами, зміненими від `origin/main`. + - `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований + `test:changed` із нативним шляхом root-project для цього закоміченого diff + і виводить wall time та macOS max RSS. + - `pnpm test:perf:changed:bench -- --worktree` проводить benchmark поточного + брудного дерева, маршрутизуючи список змінених файлів через + `scripts/test-projects.mjs` і root-конфігурацію Vitest. + - `pnpm test:perf:profile:main` записує CPU-профіль головного потоку для + накладних витрат запуску та трансформації Vitest/Vite. + - `pnpm test:perf:profile:runner` записує профілі CPU+heap для runner + unit-набору з вимкненим паралелізмом файлів. + + ### Stability (gateway) - Команда: `pnpm test:stability:gateway` -- Конфіг: `vitest.gateway.config.ts`, примусово один воркер +- Конфігурація: `vitest.gateway.config.ts`, примусово один worker - Обсяг: - - Запускає реальний loopback Gateway з diagnostics, увімкненими за замовчуванням - - Проганяє синтетичне churn повідомлень gateway, пам’яті та великих payload через шлях diagnostic event - - Опитує `diagnostics.stability` через WS RPC Gateway - - Охоплює helper збереження diagnostic stability bundle - - Перевіряє, що recorder залишається обмеженим, синтетичні RSS-samples не перевищують бюджет тиску, а глибини черги для кожної сесії зменшуються назад до нуля + - Запускає реальний loopback Gateway із diagnostics, увімкненими за замовчуванням + - Пропускає синтетичне навантаження повідомленнями gateway, пам’яттю та великими payload через шлях діагностичних подій + - Виконує запит до `diagnostics.stability` через WS RPC Gateway + - Покриває helper-функції збереження пакета діагностичної стабільності + - Перевіряє, що recorder залишається обмеженим, синтетичні вибірки RSS залишаються в межах бюджету тиску, а глибина черг для кожної сесії зменшується назад до нуля - Очікування: - - Безпечно для CI і без ключів - - Вузька lane для подальшої роботи над регресіями стабільності, а не заміна повного набору Gateway + - Безпечний для CI і без ключів + - Вузький lane для подальшої роботи над регресіями стабільності, а не заміна повного набору Gateway ### E2E (gateway smoke) - Команда: `pnpm test:e2e` -- Конфіг: `vitest.e2e.config.ts` -- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести bundled-plugin у `extensions/` -- Типові параметри runtime: +- Конфігурація: `vitest.e2e.config.ts` +- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести вбудованих plugin у `extensions/` +- Типові значення runtime: - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - - Використовує адаптивну кількість воркерів (CI: до 2, локально: 1 за замовчуванням). - - За замовчуванням запускається в silent-режимі, щоб зменшити накладні витрати на console I/O. + - Використовує адаптивну кількість worker-процесів (CI: до 2, локально: 1 за замовчуванням). + - За замовчуванням працює в silent mode, щоб зменшити накладні витрати на консольний I/O. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=`, щоб примусово задати кількість воркерів (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути докладний вивід у консоль. + - `OPENCLAW_E2E_WORKERS=`, щоб примусово задати кількість worker-процесів (не більше 16). + - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути докладний консольний вивід. - Обсяг: - - End-to-end поведінка gateway з кількома екземплярами - - Поверхні WebSocket/HTTP, pairing Node і важчий networking + - End-to-end-поведінка gateway з кількома інстансами + - Поверхні WebSocket/HTTP, pairing вузлів і важче мережеве навантаження - Очікування: - - Запускається в CI (коли увімкнено в pipeline) + - Запускається в CI (коли ввімкнено в pipeline) - Реальні ключі не потрібні - - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) + - Має більше рухомих частин, ніж unit-тести (може бути повільнішим) -### E2E: smoke для backend OpenShell +### E2E: backend smoke OpenShell - Команда: `pnpm test:e2e:openshell` - Файл: `extensions/openshell/src/backend.e2e.test.ts` @@ -405,157 +434,157 @@ Aliases сумісності існують, щоб уникнути мігра - Запускає ізольований Gateway OpenShell на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Перевіряє поведінку файлової системи, canonical для віддаленого середовища, через sandbox fs bridge + - Перевіряє канонічну для віддаленої системи поведінку файлової системи через fs bridge sandbox - Очікування: - Лише за явним увімкненням; не входить до типового запуску `pnpm test:e2e` - Потребує локального CLI `openshell` і працездатного Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, після чого знищує test gateway і sandbox + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, після чого знищує тестовий gateway і sandbox - Корисні перевизначення: - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого набору e2e - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб вказати нестандартний CLI binary або wrapper script + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб указати нестандартний CLI-бінарник або wrapper script ### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` -- Конфіг: `vitest.live.config.ts` -- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live-тести bundled-plugin у `extensions/` +- Конфігурація: `vitest.live.config.ts` +- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live-тести вбудованих plugin у `extensions/` - За замовчуванням: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін формату провайдера, особливостей виклику інструментів, проблем автентифікації та поведінки обмеження частоти запитів + - «Чи справді цей провайдер/модель _сьогодні_ працює з реальними обліковими даними?» + - Виявлення змін форматів провайдерів, особливостей виклику інструментів, проблем автентифікації та поведінки rate limit - Очікування: - - За задумом не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - - Коштує грошей / витрачає ліміти частоти + - За задумом нестабільний для CI (реальні мережі, реальні політики провайдерів, квоти, збої) + - Коштує грошей / використовує rate limit - Краще запускати звужені підмножини, а не «все» -- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API-ключі. -- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють config/auth-матеріали в тимчасовий test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. -- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. -- `pnpm test:live` тепер за замовчуванням використовує тихіший режим: він зберігає вивід прогресу `[live] ...`, але приглушує додаткове повідомлення про `~/.profile` і вимикає логи завантаження Gateway/шум Bonjour. Встановіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні логи запуску. -- Ротація API-ключів (специфічна для провайдера): встановіть `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або використайте перевизначення для live через `OPENCLAW_LIVE_*_KEY`; тести повторюють спроби у відповідь на rate limit. +- Live-запуски читають `~/.profile`, щоб підхопити відсутні API-ключі. +- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють конфігурацію/матеріали автентифікації до тимчасового тестового home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. +- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли ви навмисно хочете, щоб live-тести використовували ваш реальний домашній каталог. +- `pnpm test:live` тепер за замовчуванням працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення `~/.profile` і приглушує журнали запуску gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні журнали запуску. +- Ротація API-ключів (специфічна для провайдера): установіть `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) чи перевизначення для live через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. - Вивід прогресу/Heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, щоб довгі виклики провайдерів було видно як активні навіть тоді, коли захоплення консолі Vitest тихе. - - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб рядки прогресу провайдера/Gateway одразу транслювалися під час live-запусків. + - Live-набори тепер виводять рядки прогресу до stderr, тож тривалі виклики провайдерів помітно активні, навіть коли захоплення консолі Vitest працює тихо. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тож рядки прогресу провайдера/gateway одразу транслюються під час live-запусків. - Налаштовуйте Heartbeat для direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте Heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Налаштовуйте Heartbeat gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? Використовуйте цю таблицю рішень: -- Редагування логіки/тестів: запускайте `pnpm test` (і `pnpm test:coverage`, якщо ви багато що змінили) -- Зміни в мережевій частині gateway / WS protocol / pairing: додайте `pnpm test:e2e` -- Налагодження «мій бот не працює» / збоїв, специфічних для провайдера / виклику інструментів: запускайте звужений `pnpm test:live` +- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) +- Торкаєтесь мережевої взаємодії gateway / протоколу WS / pairing: додайте `pnpm test:e2e` +- Налагоджуєте «мій бот не працює» / специфічні для провайдера збої / виклики інструментів: запускайте звужений `pnpm test:live` ## Live: перевірка можливостей Android Node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яку наразі оголошує** під’єднаний Android Node, і перевірити поведінку контракту команд. +- Мета: викликати **кожну команду, яка наразі оголошена** підключеним Android Node, і перевірити поведінку контракту команд. - Обсяг: - - Попередньо підготовлене/ручне налаштування (набір не встановлює/не запускає/не виконує pairing app). - - Перевірка `node.invoke` Gateway команда за командою для вибраного Android Node. -- Обов’язкове попереднє налаштування: - - Android app вже під’єднано та виконано pairing із gateway. - - App утримується на передньому плані. - - Для можливостей, які мають пройти, надано дозволи/згоду на захоплення. + - Попередньо підготовлене/ручне налаштування (набір не встановлює/не запускає/не виконує pairing застосунку). + - Перевірка `node.invoke` gateway для вибраного Android Node, команда за командою. +- Необхідне попереднє налаштування: + - Android-застосунок уже підключено й виконано pairing із gateway. + - Застосунок утримується на передньому плані. + - Для можливостей, які мають проходити, надано дозволи/згоду на захоплення. - Необов’язкові перевизначення цілі: - `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Повні подробиці налаштування Android: [Android App](/uk/platforms/android) +- Повні відомості про налаштування Android: [Android App](/uk/platforms/android) -## Live: smoke для моделі (ключі профілів) +## Live: smoke моделей (ключі профілів) -Live-тести поділено на два шари, щоб ми могли ізолювати збої: +Live-тести поділено на два шари, щоб можна було ізолювати збої: -- «Direct model» показує, чи може провайдер/модель взагалі відповісти з наданим ключем. -- «Gateway smoke» показує, чи працює повний конвеєр gateway+agent для цієї моделі (сесії, історія, інструменти, політика sandbox тощо). +- «Direct model» показує, що провайдер/модель узагалі може відповісти з цим ключем. +- «Gateway smoke» показує, що для цієї моделі працює повний pipeline gateway+agent (сесії, історія, інструменти, політика sandbox тощо). ### Шар 1: Direct model completion (без gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - - Перерахувати виявлені моделі - - Використати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані - - Виконати невелике completion для кожної моделі (і цільові регресії, де потрібно) + - Перелічити виявлені моделі + - Використати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані + - Запустити невелике completion для кожної моделі (і цільові регресії, де потрібно) - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest безпосередньо) -- Встановіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, alias для modern), щоб справді запустити цей набір; інакше його буде пропущено, щоб `pnpm test:live` залишався зосередженим на gateway smoke + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) +- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, alias для modern), щоб цей набір справді запускався; інакше він буде пропущений, щоб `pnpm test:live` залишався зосередженим на gateway smoke - Як вибирати моделі: - - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` — це alias для сучасного allowlist + - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` — це alias для modern allowlist - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist через кому) - - Сучасні/all-прогони за замовчуванням використовують curated high-signal cap; встановіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного сучасного прогону або додатне число для меншого cap. + - Для modern/all sweep за замовчуванням використовується curated high-signal cap; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для повного modern sweep або додатне число для меншого ліміту. - Як вибирати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - За замовчуванням: сховище профілів і резервні env-значення - - Встановіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** + - За замовчуванням: сховище профілів і резервні значення з env + - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** - Навіщо це існує: - - Відокремлює «API провайдера зламане / ключ недійсний» від «конвеєр gateway agent зламаний» - - Містить невеликі ізольовані регресії (приклад: повторне відтворення reasoning у OpenAI Responses/Codex Responses + потоки tool-call) + - Відокремлює «API провайдера зламаний / ключ недійсний» від «pipeline gateway agent зламаний» + - Містить невеликі ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки tool-call) -### Шар 2: Gateway + smoke для dev agent (те, що фактично робить "@openclaw") +### Шар 2: smoke Gateway + dev agent (те, що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - - Підняти in-process gateway + - Запустити in-process gateway - Створити/оновити сесію `agent:dev:*` (перевизначення моделі для кожного запуску) - - Ітеруватися по моделях-із-ключами та перевіряти: + - Перебрати моделі-з-ключами і перевірити: - «змістовну» відповідь (без інструментів) - - що реальний виклик інструмента працює (перевірка читання) - - необов’язкові додаткові перевірки інструментів (перевірка exec+read) - - що шляхи регресій OpenAI (лише tool-call → подальший хід) продовжують працювати + - що працює реальний виклик інструмента (read probe) + - необов’язкові додаткові перевірки інструментів (exec+read probe) + - що шляхи регресій OpenAI (лише tool-call → наступний крок) продовжують працювати - Деталі probe (щоб ви могли швидко пояснювати збої): - probe `read`: тест записує nonce-файл у workspace і просить агента `read` його та повернути nonce. - - probe `exec+read`: тест просить агента через `exec` записати nonce в тимчасовий файл, а потім через `read` прочитати його назад. + - probe `exec+read`: тест просить агента через `exec` записати nonce у тимчасовий файл, а потім через `read` зчитати його назад. - image probe: тест прикріплює згенерований PNG (cat + рандомізований код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest безпосередньо) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) - Як вибирати моделі: - - За замовчуванням: сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це alias для сучасного allowlist + - За замовчуванням: modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це alias для modern allowlist - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір - - Сучасні/all-прогони gateway за замовчуванням використовують curated high-signal cap; встановіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного сучасного прогону або додатне число для меншого cap. -- Як вибирати провайдерів (уникнути «всього OpenRouter»): + - Для modern/all gateway sweep за замовчуванням використовується curated high-signal cap; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для повного modern sweep або додатне число для меншого ліміту. +- Як вибирати провайдерів (уникаючи «усе з OpenRouter»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) -- Tool + image probe у цьому live-тесті завжди увімкнені: - - probe `read` + probe `exec+read` (навантаження на інструменти) - - image probe запускається, коли модель оголошує підтримку вхідних зображень - - Потік (високорівнево): - - Тест генерує крихітний PNG із “CAT” + випадковим кодом (`src/gateway/live-image-probe.ts`) +- У цьому live-тесті tool + image probe завжди ввімкнені: + - probe `read` + probe `exec+read` (стрес для інструментів) + - image probe запускається, коли модель заявляє підтримку image input + - Потік (високий рівень): + - Тест генерує маленький PNG із “CAT” + випадковим кодом (`src/gateway/live-image-probe.ts`) - Надсилає його через `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - Gateway розбирає attachments у `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - Embedded agent пересилає мультимодальне повідомлення користувача моделі - - Перевірка: відповідь містить `cat` + код (OCR tolerance: незначні помилки дозволені) + - Gateway розбирає вкладення у `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Embedded agent передає моделі мультимодальне повідомлення користувача + - Перевірка: відповідь містить `cat` + код (допуск OCR: незначні помилки дозволені) -Порада: щоб побачити, що саме можна тестувати на вашій машині (і точні id `provider/model`), виконайте: +Порада: щоб побачити, що можна тестувати на вашій машині (і точні ID `provider/model`), виконайте: ```bash openclaw models list openclaw models list --json ``` -## Live: smoke для backend CLI (Claude, Codex, Gemini або інші локальні CLI) +## Live: smoke backend CLI (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити конвеєр Gateway + agent із використанням локального backend CLI, не торкаючись вашого типового config. -- Типові параметри smoke, специфічні для backend, зберігаються у визначенні `cli-backend.ts` extension-власника. +- Мета: перевірити pipeline Gateway + agent, використовуючи локальний CLI-backend, не торкаючись вашої типової конфігурації. +- Типові значення smoke, специфічні для backend, розміщені у визначенні `cli-backend.ts` відповідного extension. - Увімкнення: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest безпосередньо) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Типові значення: - - Типовий провайдер/модель: `claude-cli/claude-sonnet-4-6` - - Поведінка command/args/image береться з метаданих plugin-власника CLI backend. + - Провайдер/модель за замовчуванням: `claude-cli/claude-sonnet-4-6` + - Поведінка command/args/image береться з метаданих plugin CLI-backend, якому вона належить. - Перевизначення (необов’язково): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати реальне вкладення-зображення (шляхи інжектуються в prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до файлів зображень як CLI args замість інжекції в prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати передаванням аргументів зображення, коли встановлено `IMAGE_ARG`. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий хід і перевірити потік відновлення. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типову перевірку безперервності тієї ж сесії Claude Sonnet -> Opus (встановіть `1`, щоб примусово увімкнути її, коли вибрана модель підтримує ціль переключення). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати реальне image-вкладення (шляхи інжектуються в prompt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до image-файлів як аргументи CLI замість інжекції в prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати передаванням image-аргументів, коли встановлено `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий хід і перевірити flow відновлення. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типову перевірку безперервності в тій самій сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль перемикання). Приклад: @@ -582,29 +611,29 @@ pnpm test:docker:live-cli-backend:gemini Примітки: -- Docker-ранер розташований у `scripts/test-live-cli-backend-docker.sh`. -- Він запускає live smoke для CLI-backend усередині образу Docker репозиторію як непривілейований користувач `node`. -- Він визначає метадані CLI smoke з extension-власника, а потім встановлює відповідний Linux CLI package (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований каталог із правом запису за префіксом `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` потребує portable Claude Code subscription OAuth через або `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` з `claude setup-token`. Спочатку він підтверджує прямий `claude -p` у Docker, а потім запускає два ходи Gateway CLI-backend без збереження env-змінних API-ключа Anthropic. Ця subscription lane за замовчуванням вимикає Claude MCP/tool та image probes, тому що Claude наразі маршрутизує використання сторонніх app через білінг extra-usage замість звичайних лімітів subscription plan. -- Live smoke для CLI-backend тепер перевіряє той самий наскрізний потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, а потім виклик інструмента MCP `cron`, перевірений через Gateway CLI. -- Типовий smoke для Claude також оновлює сесію із Sonnet до Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. +- Ранер Docker розміщено в `scripts/test-live-cli-backend-docker.sh`. +- Він запускає live smoke CLI-backend усередині Docker-образу репозиторію від імені непривілейованого користувача `node`. +- Він визначає метадані smoke CLI з extension-власника, потім встановлює відповідний Linux CLI-пакет (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований доступний для запису префікс у `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` вимагає переносної OAuth-підписки Claude Code через або `~/.claude/.credentials.json` із `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` із `claude setup-token`. Спочатку він підтверджує прямий `claude -p` у Docker, а потім виконує два ходи Gateway CLI-backend без збереження змінних середовища ключа Anthropic API. Цей lane підписки за замовчуванням вимикає probes Claude MCP/tool та image, тому що Claude наразі маршрутизує використання сторонніх застосунків через білінг extra-usage замість звичайних лімітів плану підписки. +- Live smoke CLI-backend тепер перевіряє той самий end-to-end-потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, а потім виклик інструмента MCP `cron`, перевірений через CLI gateway. +- Типовий smoke Claude також оновлює сесію із Sonnet на Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. -## Live: smoke для ACP bind (`/acp spawn ... --bind here`) +## Live: smoke ACP bind (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний потік conversation-bind ACP із live ACP agent: +- Мета: перевірити реальний потік conversation-bind ACP із live ACP-агентом: - надіслати `/acp spawn --bind here` - - прив’язати synthetic message-channel conversation на місці - - надіслати звичайний подальший хід у тій самій conversation - - перевірити, що подальший хід потрапляє в transcript прив’язаної ACP session + - прив’язати синтетичну розмову message-channel на місці + - надіслати звичайне подальше повідомлення в тій самій розмові + - перевірити, що подальше повідомлення потрапляє до транскрипту прив’язаної сесії ACP - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Типові значення: - - ACP agents у Docker: `claude,codex,gemini` - - ACP agent для прямого `pnpm test:live ...`: `claude` - - Synthetic channel: контекст conversation у стилі Slack DM - - ACP backend: `acpx` + - ACP-агенти в Docker: `claude,codex,gemini` + - ACP-агент для прямого `pnpm test:live ...`: `claude` + - Синтетичний channel: контекст розмови в стилі Slack DM + - ACP-backend: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` @@ -613,7 +642,7 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.4` - Примітки: - - Ця lane використовує поверхню gateway `chat.send` з synthetic полями originating-route лише для адміністратора, щоб тести могли прикріплювати контекст message-channel без імітації зовнішньої доставки. + - Цей lane використовує поверхню gateway `chat.send` з admin-only синтетичними полями originating-route, щоб тести могли прикріплювати контекст message-channel без удавання зовнішньої доставки. - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр агентів plugin `acpx` для вибраного ACP harness agent. Приклад: @@ -640,34 +669,35 @@ pnpm test:docker:live-acp-bind:gemini Примітки щодо Docker: -- Docker-ранер розташований у `scripts/test-live-acp-bind-docker.sh`. -- За замовчуванням він послідовно запускає ACP bind smoke для всіх підтримуваних live CLI agents: `claude`, `codex`, потім `gemini`. +- Ранер Docker розміщено в `scripts/test-live-acp-bind-docker.sh`. +- За замовчуванням він запускає smoke ACP bind послідовно для всіх підтримуваних live CLI-агентів: `claude`, `codex`, потім `gemini`. - Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, щоб звузити матрицю. -- Він використовує `~/.profile`, підготовлює відповідні auth-матеріали CLI в контейнері, встановлює `acpx` у npm prefix із правом запису, а потім встановлює запитаний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його бракує. -- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб `acpx` зберігав env-змінні провайдера з використаного profile доступними для дочірнього harness CLI. +- Він читає `~/.profile`, переносить відповідні матеріали CLI-автентифікації в контейнер, встановлює `acpx` у доступний для запису npm-префікс, а потім за потреби встановлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`). +- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав змінні середовища провайдера із прочитаного профілю доступними для дочірнього harness CLI. -## Live: smoke для harness app-server Codex +## Live: smoke harness app-server Codex -- Мета: перевірити harness Codex, що належить plugin, через звичайний метод gateway - `agent`: - - завантажити bundled plugin `codex` +- Мета: перевірити harness Codex, яким володіє plugin, через звичайний + метод gateway `agent`: + - завантажити вбудований plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - - надіслати перший хід gateway agent до `codex/gpt-5.4` - - надіслати другий хід у ту саму сесію OpenClaw і перевірити, що thread app-server - може відновитися - - запустити `/codex status` і `/codex models` через той самий шлях команд gateway - - за потреби виконати дві перевірки escalated shell, переглянуті Guardian: одну нешкідливу - команду, яку слід схвалити, і одне фальшиве завантаження секрету, яке має бути - відхилене, щоб агент перепитав + - надіслати перший хід агента gateway до `codex/gpt-5.4` + - надіслати другий хід до тієї самої сесії OpenClaw і перевірити, що thread + app-server може відновитися + - виконати `/codex status` і `/codex models` через той самий командний + шлях gateway + - за потреби виконати дві shell-перевірки з підвищенням прав, переглянуті Guardian: одну нешкідливу + команду, яку має бути схвалено, і одне фальшиве завантаження секрету, яке має бути + відхилено, щоб агент перепитав - Тест: `src/gateway/gateway-codex-harness.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Типова модель: `codex/gpt-5.4` -- Необов’язковий image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Необов’язковий MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- Необов’язковий Guardian probe: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` -- Smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний harness Codex - не міг пройти тихо, просто переключившись на PI. -- Auth: `OPENAI_API_KEY` із shell/profile, плюс необов’язково скопійовані +- Необов’язкова image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Необов’язкова MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- Необов’язкова Guardian probe: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` +- Цей smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний harness Codex + не міг пройти, непомітно переключившись на PI. +- Автентифікація: `OPENAI_API_KEY` із shell/profile, плюс необов’язково скопійовані `~/.codex/auth.json` і `~/.codex/config.toml` Локальний рецепт: @@ -691,20 +721,22 @@ pnpm test:docker:live-codex-harness Примітки щодо Docker: -- Docker-ранер розташований у `scripts/test-live-codex-harness-docker.sh`. -- Він використовує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли - auth Codex CLI, якщо вони присутні, встановлює `@openai/codex` у змонтований npm - prefix із правом запису, підготовлює дерево source, а потім запускає лише live-тест Codex-harness. -- У Docker probes image, MCP/tool і Guardian увімкнені за замовчуванням. Встановіть - `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` або - `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` або - `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, коли потрібен вужчий запуск для налагодження. -- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, як і конфігурація live-тесту, - тож fallback `openai-codex/*` або PI не може приховати регресію harness Codex. +- Ранер Docker розміщено в `scripts/test-live-codex-harness-docker.sh`. +- Він читає змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли + автентифікації CLI Codex, якщо вони є, встановлює `@openai/codex` у доступний для запису змонтований npm- + префікс, переносить дерево вихідного коду, а потім запускає лише live-тест Codex-harness. +- Docker за замовчуванням вмикає probes image, MCP/tool і Guardian. Установіть + `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0`, або + `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`, або + `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, коли потрібен вужчий режим + налагодження. +- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, як і live- + конфігурація тесту, тож fallback `openai-codex/*` або PI не може приховати регресію + harness Codex. ### Рекомендовані live-рецепти -Вузькі, явні allowlist працюють найшвидше і найменш нестабільно: +Вузькі, явні allowlist — найшвидші й найменш нестабільні: - Одна модель, direct (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` @@ -712,29 +744,29 @@ pnpm test:docker:live-codex-harness - Одна модель, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Виклик інструментів для кількох провайдерів: +- Виклик інструментів через кількох провайдерів: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Фокус на Google (API key Gemini + Antigravity): - - Gemini (API key): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- Фокус на Google (API-ключ Gemini + Antigravity): + - Gemini (API-ключ): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` Примітки: -- `google/...` використовує Gemini API (API key). -- `google-antigravity/...` використовує OAuth-міст Antigravity (endpoint агента в стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема auth + особливості tooling). +- `google/...` використовує Gemini API (API-ключ). +- `google-antigravity/...` використовує міст Antigravity OAuth (endpoint агента в стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості інструментів). - Gemini API проти Gemini CLI: - - API: OpenClaw викликає хостований Google Gemini API через HTTP (API key / auth профілю); саме це більшість користувачів мають на увазі під «Gemini». - - CLI: OpenClaw викликає локальний binary `gemini`; він має власну auth і може поводитися інакше (streaming/tool support/version skew). + - API: OpenClaw викликає розміщений Google Gemini API через HTTP (автентифікація API-ключем / профілем); саме це більшість користувачів мають на увазі під «Gemini». + - CLI: OpenClaw виконує локальний бінарник `gemini`; він має власну автентифікацію й може поводитися інакше (streaming/підтримка інструментів/розбіжність версій). ## Live: матриця моделей (що ми покриваємо) -Фіксованого «списку моделей CI» не існує (live запускається за явним увімкненням), але це **рекомендовані** моделі для регулярного покриття на dev-машині з ключами. +Немає фіксованого «списку моделей CI» (live вмикається за потреби), але це **рекомендовані** моделі для регулярного покриття на машині розробника з ключами. ### Сучасний набір smoke (виклик інструментів + image) -Це запуск «поширених моделей», який ми очікуємо підтримувати працездатним: +Це запуск «поширених моделей», який, як очікується, має залишатися працездатним: - OpenAI (не Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` @@ -744,12 +776,12 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запуск gateway smoke з tools + image: +Запускати gateway smoke з інструментами + image: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Базове покриття: виклик інструментів (Read + необов’язковий Exec) +### Базовий рівень: виклик інструментів (Read + необов’язковий Exec) -Вибирайте принаймні одну модель для кожного сімейства провайдерів: +Виберіть принаймні одну модель із кожної сім’ї провайдерів: - OpenAI: `openai/gpt-5.4` (або `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -757,76 +789,76 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Необов’язкове додаткове покриття (приємно мати): +Необов’язкове додаткове покриття (бажано мати): - xAI: `xai/grok-4` (або найновішу доступну) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою tools, яку у вас увімкнено) -- Cerebras: `cerebras/`… (якщо у вас є доступ) +- Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яку у вас ввімкнено) +- Cerebras: `cerebras/`… (якщо маєте доступ) - LM Studio: `lmstudio/`… (локально; виклик інструментів залежить від режиму API) -### Vision: надсилання зображення (вкладення → мультимодальне повідомлення) +### Vision: надсилання image (вкладення → мультимодальне повідомлення) -Включайте принаймні одну модель із підтримкою зображень у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI vision-capable варіанти тощо), щоб перевірити image probe. +Додайте щонайменше одну модель із підтримкою image до `OPENCLAW_LIVE_GATEWAY_MODELS` (варіанти Claude/Gemini/OpenAI із підтримкою vision тощо), щоб перевірити image probe. -### Агрегатори / альтернативні gateway +### Aggregators / альтернативні gateway -Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: +Якщо у вас увімкнено ключі, ми також підтримуємо тестування через: -- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) -- OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (auth через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти відповідні кандидати з підтримкою tool+image) +- OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (автентифікація через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Більше провайдерів, які можна включити до live-матриці (якщо у вас є облікові дані/config): +Більше провайдерів, які можна включити до live-матриці (якщо у вас є облікові дані/конфігурація): - Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Через `models.providers` (custom endpoint): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-сумісний proxy (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (власні endpoint): `minimax` (хмара/API), а також будь-який proxy, сумісний з OpenAI/Anthropic (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко прописати в документації «всі моделі». Авторитетний список — це все, що повертає `discoverModels(...)` на вашій машині, плюс усі доступні ключі. +Порада: не намагайтеся жорстко закодувати «всі моделі» в документації. Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс ті ключі, що доступні. ## Облікові дані (ніколи не комітьте) -Live-тести знаходять облікові дані так само, як це робить CLI. Практичні наслідки: +Live-тести знаходять облікові дані так само, як і CLI. Практичні наслідки: -- Якщо CLI працює, live-тести мають знайти ті самі ключі. +- Якщо CLI працює, live-тести повинні знаходити ті самі ключі. - Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. -- Профілі auth для кожного агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «ключі профілю» у live-тестах) -- Config: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється до staged live home, якщо присутній, але не є основним сховищем ключів профілю) -- Локальні live-запуски за замовчуванням копіюють активний config, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні каталоги auth CLI в тимчасовий test home; staged live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probes не торкалися вашого реального workspace хоста. +- Профілі автентифікації для кожного агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «ключі профілів» у live-тестах) +- Конфігурація: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) +- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється до staged live home, якщо присутній, але не є основним сховищем ключів профілів) +- Локальні live-запуски за замовчуванням копіюють активну конфігурацію, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні каталоги CLI-автентифікації до тимчасового тестового home; staged live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probes не використовували ваш реальний workspace хоста. -Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на ключі з env (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте наведені нижче ранери Docker (вони можуть монтувати `~/.profile` у контейнер). -## Deepgram live (транскрипція аудіо) +## Live Deepgram (транскрибування аудіо) - Тест: `extensions/deepgram/audio.live.test.ts` - Увімкнення: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts` -## BytePlus coding plan live +## Live BytePlus coding plan - Тест: `extensions/byteplus/live.test.ts` - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts` - Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## ComfyUI workflow media live +## Live ComfyUI workflow media - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Обсяг: - - Перевіряє вбудовані шляхи comfy image, video і `music_generate` - - Пропускає кожну можливість, якщо `models.providers.comfy.` не налаштовано - - Корисно після змін у надсиланні workflow comfy, polling, завантаженнях або реєстрації plugin + - Перевіряє вбудовані шляхи comfy для зображень, відео та `music_generate` + - Пропускає кожну можливість, якщо не налаштовано `models.providers.comfy.` + - Корисно після змін у надсиланні workflow comfy, опитуванні, завантаженнях або реєстрації plugin -## Live для генерації зображень +## Live generation зображень - Тест: `test/image-generation.runtime.live.test.ts` - Команда: `pnpm test:live test/image-generation.runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Обсяг: - - Перераховує всі зареєстровані provider plugin для генерації зображень - - Завантажує відсутні env-змінні провайдерів із вашого login shell (`~/.profile`) перед перевіркою - - За замовчуванням використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі test-ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатної auth/profile/model - - Проганяє стандартні варіанти генерації зображень через спільну runtime capability: + - Перелічує кожен зареєстрований provider plugin для generation зображень + - Перед probe завантажує відсутні змінні середовища provider із вашого login shell (`~/.profile`) + - За замовчуванням використовує live/env API-ключі раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Запускає стандартні варіанти generation зображень через спільну runtime-можливість: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` @@ -842,98 +874,98 @@ Live-тести знаходять облікові дані так само, я - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google,xai"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,xai:default-generate,xai:default-edit"` -- Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env +- Необов’язкова поведінка автентифікації: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише з env -## Music generation live +## Live generation музики - Тест: `extensions/music-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Обсяг: - - Перевіряє спільний шлях bundled provider для генерації музики - - Наразі охоплює Google і MiniMax - - Завантажує env-змінні провайдерів із вашого login shell (`~/.profile`) перед перевіркою - - За замовчуванням використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі test-ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатної auth/profile/model - - Запускає обидва оголошені runtime-режими, коли вони доступні: - - `generate` з вхідними даними лише у вигляді prompt + - Перевіряє спільний шлях вбудованих провайдерів generation музики + - Наразі покриває Google і MiniMax + - Перед probe завантажує змінні середовища provider із вашого login shell (`~/.profile`) + - За замовчуванням використовує live/env API-ключі раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Запускає обидва оголошені runtime-режими, якщо вони доступні: + - `generate` з input лише у вигляді prompt - `edit`, коли провайдер оголошує `capabilities.edit.enabled` - - Поточне покриття спільної lane: + - Поточне покриття спільного lane: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: окремий live-файл Comfy, не цей спільний прогін + - `comfy`: окремий live-файл Comfy, а не цей спільний sweep - Необов’язкове звуження: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env +- Необов’язкова поведінка автентифікації: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише з env -## Video generation live +## Live generation відео - Тест: `extensions/video-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Обсяг: - - Перевіряє спільний шлях bundled provider для генерації відео - - За замовчуванням використовує безпечний для релізу smoke-шлях: провайдери без FAL, один запит text-to-video на провайдера, секундний prompt про лобстера та ліміт операції для кожного провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` за замовчуванням) - - За замовчуванням пропускає FAL, оскільки затримка черги на стороні провайдера може домінувати в часі релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб явно його запустити - - Завантажує env-змінні провайдерів із вашого login shell (`~/.profile`) перед перевіркою - - За замовчуванням використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі test-ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатної auth/profile/model + - Перевіряє спільний шлях вбудованих провайдерів generation відео + - За замовчуванням використовує безпечний для релізу smoke-шлях: провайдери без FAL, один запит text-to-video на провайдера, prompt з односекундним лобстером і ліміт операції на провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` за замовчуванням) + - За замовчуванням пропускає FAL, оскільки затримка черги на боці провайдера може домінувати над часом релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб запустити його явно + - Перед probe завантажує змінні середовища provider із вашого login shell (`~/.profile`) + - За замовчуванням використовує live/env API-ключі раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Пропускає провайдерів без придатної автентифікації/профілю/моделі - За замовчуванням запускає лише `generate` - - Встановіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими трансформації, коли вони доступні: - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід зображення на основі buffer у спільному прогоні - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід відео на основі buffer у спільному прогоні - - Поточні оголошені, але пропущені провайдери `imageToVideo` у спільному прогоні: - - `vydra`, тому що bundled `veo3` є лише text-only, а bundled `kling` вимагає віддалений URL зображення - - Специфічне для провайдера покриття Vydra: + - Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими трансформації, якщо вони доступні: + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальний image input на основі buffer у спільному sweep + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальний video input на основі buffer у спільному sweep + - Поточні провайдери `imageToVideo`, які оголошено, але пропускаються у спільному sweep: + - `vydra`, тому що вбудований `veo3` підтримує лише text, а вбудований `kling` вимагає віддалений URL зображення + - Покриття Vydra, специфічне для провайдера: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає `veo3` text-to-video плюс lane `kling`, яка за замовчуванням використовує fixture з віддаленим URL зображення + - цей файл запускає `veo3` text-to-video плюс lane `kling`, який за замовчуванням використовує фікстуру з віддаленим URL зображення - Поточне live-покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні оголошені, але пропущені провайдери `videoToVideo` у спільному прогоні: - - `alibaba`, `qwen`, `xai`, тому що ці шляхи наразі вимагають віддалені еталонні URL `http(s)` / MP4 - - `google`, тому що поточна спільна lane Gemini/Veo використовує локальний вхід на основі buffer, і цей шлях не приймається у спільному прогоні - - `openai`, тому що поточна спільна lane не гарантує доступу до org-специфічного inpaint/remix для відео + - Поточні провайдери `videoToVideo`, які оголошено, але пропускаються у спільному sweep: + - `alibaba`, `qwen`, `xai`, тому що ці шляхи наразі вимагають віддалені URL посилань `http(s)` / MP4 + - `google`, тому що поточний спільний lane Gemini/Veo використовує локальний input на основі buffer, і цей шлях не приймається у спільному sweep + - `openai`, тому що поточний спільний lane не гарантує наявність організаційного доступу до video inpaint/remix - Необов’язкове звуження: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типового прогону, зокрема FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити ліміт операції для кожного провайдера під час агресивного smoke-запуску -- Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типового sweep, включно з FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити ліміт операції для кожного провайдера для агресивного smoke-запуску +- Необов’язкова поведінка автентифікації: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише з env -## Media live harness +## Harness media live - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні live-набори image, music і video через один нативний entrypoint репозиторію - - Автоматично завантажує відсутні env-змінні провайдерів із `~/.profile` - - За замовчуванням автоматично звужує кожен набір до провайдерів, які наразі мають придатну auth - - Повторно використовує `scripts/test-live.mjs`, тому поведінка Heartbeat і quiet-mode залишається узгодженою + - Запускає спільні live-набори для image, music і video через один рідний для репозиторію entrypoint + - Автоматично завантажує відсутні змінні середовища provider із `~/.profile` + - За замовчуванням автоматично звужує кожен набір до провайдерів, які зараз мають придатну автентифікацію + - Повторно використовує `scripts/test-live.mjs`, тож поведінка Heartbeat і quiet mode залишається сталою - Приклади: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Docker-ранери (необов’язкові перевірки «працює в Linux») +## Ранери Docker (необов’язкові перевірки «працює в Linux») -Ці Docker-ранери поділяються на дві групи: +Ці ранери Docker поділяються на дві групи: -- Live-model ранери: `test:docker:live-models` і `test:docker:live-gateway` запускають лише свій відповідний live-файл із ключами профілів усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог config і workspace (а також використовують `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint — `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker live-ранери за замовчуванням використовують менший smoke-cap, щоб повний Docker-прогін залишався практичним: +- Ранери live-model: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний файл live з ключами профілів усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтуючи ваш локальний каталог конфігурації та workspace (і читаючи `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint — `test:live:models-profiles` і `test:live:gateway-profiles`. +- Live-ранери Docker за замовчуванням використовують менший smoke-ліміт, щоб повний Docker sweep залишався практичним: `test:docker:live-models` за замовчуванням використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а `test:docker:live-gateway` — `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env-змінні, коли - вам явно потрібен більший вичерпний прогін. -- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох Docker live lane. Він також збирає один спільний образ `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для E2E container smoke-ранерів, які перевіряють зібраний app. -- Container smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` піднімають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env vars, коли + вам явно потрібне більше повне сканування. +- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох live Docker lane. Він також збирає один спільний образ `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для раннерів container smoke E2E, які перевіряють зібраний застосунок. +- Ранери container smoke: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Docker-ранери live-model також bind-mount лише потрібні auth-home для CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без змін у host auth store: +Ранери Docker для live-model також bind-mount лише потрібні каталоги CLI-автентифікації (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб зовнішня OAuth-автентифікація CLI могла оновлювати токени без зміни сховища автентифікації хоста: - Direct models: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) - ACP bind smoke: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) @@ -942,17 +974,17 @@ Docker-ранери live-model також bind-mount лише потрібні a - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) - Open WebUI live smoke: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) - Майстер онбордингу (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Smoke для npm tarball onboarding/channel/agent: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через env-ref onboarding і за замовчуванням Telegram, перевіряє, що ввімкнення plugin встановлює його runtime deps за потреби, запускає doctor і виконує один mock-хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть host rebuild через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або перемкніть channel через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Мережа Gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Мінімальна reasoning-регресія OpenAI Responses `web_search`: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає mock-сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` з `minimal` до `low`, а потім примусово викликає відхилення схеми провайдера і перевіряє, що сирі деталі з’являються в логах Gateway. -- Міст MCP channel (seeded Gateway + stdio bridge + raw Claude smoke notification-frame): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Інструменти Pi bundle MCP (реальний stdio MCP server + embedded smoke allow/deny для профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Очищення MCP Cron/subagent (реальний Gateway + завершення дочірнього stdio MCP після ізольованих запусків cron і одноразового subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Smoke онбордингу/channel/agent через npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через онбординг env-ref і за замовчуванням Telegram, перевіряє, що ввімкнення plugin встановлює його runtime-залежності на вимогу, запускає doctor і виконує один змоканий хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть перебудову на хості через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або перемкніть channel через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Мережева взаємодія Gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) +- Мінімальна reasoning-регресія OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає змоканий сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` із `minimal` до `low`, потім примусово викликає відхилення provider schema і перевіряє, що сирі деталі з’являються в журналах Gateway. +- Міст MCP channel (seeded Gateway + stdio bridge + smoke сирого notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Інструменти Pi bundle MCP (реальний stdio MCP server + smoke allow/deny вбудованого профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Очищення MCP Cron/subagent (реальний Gateway + завершення дочірнього stdio MCP після ізольованого Cron і одноразових запусків subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) - Plugins (smoke встановлення + alias `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) - Smoke незмінного оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Smoke метаданих перезавантаження config: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) -- Runtime deps bundled plugin: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає невеликий Docker-образ раннера, один раз збирає та пакує OpenClaw на host, а потім монтує цей tarball у кожен Linux-сценарій встановлення. Повторно використовуйте образ через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропустіть host rebuild після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вкажіть наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. -- Звужуйте runtime deps bundled plugin під час ітерацій, вимикаючи не пов’язані сценарії, наприклад: +- Smoke метаданих перезавантаження конфігурації: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) +- Runtime-залежності вбудованого plugin: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає невеликий образ Docker runner, один раз збирає й пакує OpenClaw на хості, а потім монтує цей tarball у кожен сценарій встановлення Linux. Повторно використовуйте образ через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропустіть перебудову на хості після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вкажіть на наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. +- Звужуйте перевірку runtime-залежностей вбудованого plugin під час ітерації, вимикаючи не пов’язані сценарії, наприклад: `OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps`. Щоб вручну попередньо зібрати і повторно використовувати спільний образ built-app: @@ -962,112 +994,111 @@ OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -Перевизначення образів, специфічні для набору, наприклад `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо їх задано. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний образ, скрипти завантажують його, якщо він ще не є локальним. Docker-тести QR та інсталятора зберігають власні Dockerfile, оскільки вони перевіряють поведінку пакування/встановлення, а не спільний runtime зібраного app. +Перевизначення образів для конкретних наборів, такі як `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо встановлені. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` указує на віддалений спільний образ, скрипти завантажують його, якщо його ще немає локально. Docker-тести QR та installer зберігають власні Dockerfile, оскільки вони перевіряють поведінку пакетування/встановлення, а не спільний runtime built-app. -Docker-ранери live-model також монтують поточний checkout лише для читання та -підготовлюють його в тимчасовий workdir усередині контейнера. Це зберігає runtime -image компактним, але все одно дозволяє запускати Vitest точно проти ваших локальних source/config. -Етап підготовки пропускає великі локальні кеші та виходи збірки app, наприклад -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для app каталоги `.build` або -виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання -машинно-специфічних артефактів. -Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб Gateway live probes не запускали -реальні воркери channel Telegram/Discord тощо всередині контейнера. +Ранери Docker для live-model також bind-mount поточний checkout у режимі лише читання і +переносять його до тимчасового workdir усередині контейнера. Це зберігає runtime- +образ компактним і водночас дозволяє запускати Vitest точно на вашому локальному source/config. +Крок staging пропускає великі локальні кеші й результати збірки застосунків, такі як +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків каталоги `.build` або +виводу Gradle, щоб live-запуски Docker не витрачали хвилини на копіювання +артефактів, специфічних для машини. +Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probes gateway не запускали +реальні worker-процеси channel Telegram/Discord тощо всередині контейнера. `test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити gateway -live-покриття з цієї Docker lane. -`test:docker:openwebui` — це smoke перевірки сумісності вищого рівня: він запускає -контейнер Gateway OpenClaw з увімкненими HTTP endpoint, сумісними з OpenAI, -запускає pinned контейнер Open WebUI проти цього gateway, виконує вхід через +`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити live-покриття gateway з цього Docker lane. +`test:docker:openwebui` — це smoke сумісності вищого рівня: він запускає +контейнер Gateway OpenClaw з увімкненими OpenAI-compatible HTTP endpoint, +запускає закріплений контейнер Open WebUI проти цього gateway, виконує вхід через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає реальний chat-запит через proxy `/api/chat/completions` Open WebUI. Перший запуск може бути помітно повільнішим, оскільки Docker може знадобитися завантажити -образ Open WebUI, а самому Open WebUI — завершити власне cold-start налаштування. -Ця lane очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` -(`~/.profile` за замовчуванням) є основним способом надати його в Dockerized-запусках. +образ Open WebUI, а самому Open WebUI може знадобитися завершити власне cold-start налаштування. +Цей lane очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` +(`~/.profile` за замовчуванням) — основний спосіб надати його в Dockerized-запусках. Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` є навмисно детермінованим і не потребує -реального акаунта Telegram, Discord або iMessage. Він піднімає seeded контейнер Gateway, -запускає другий контейнер, який викликає `openclaw mcp serve`, а потім -перевіряє routed discovery conversation, читання transcript, метадані вкладень, -поведінку live event queue, маршрутизацію вихідного надсилання, а також channel у стилі Claude + -сповіщення про дозволи через реальний stdio MCP bridge. Перевірка сповіщень -напряму інспектує raw stdio MCP frames, тому smoke перевіряє те, що міст -справді випромінює, а не лише те, що випадково показує певний client SDK. -`test:docker:pi-bundle-mcp-tools` є детермінованим і не потребує ключа live-моделі. -Він збирає Docker-образ репозиторію, запускає реальний stdio MCP probe server -усередині контейнера, матеріалізує цей server через embedded runtime bundle MCP Pi, +`test:docker:mcp-channels` навмисно детермінований і не потребує +реального облікового запису Telegram, Discord чи iMessage. Він запускає seeded Gateway- +контейнер, запускає другий контейнер, який виконує `openclaw mcp serve`, а потім +перевіряє виявлення маршрутизованих розмов, читання транскриптів, метадані вкладень, +поведінку черги live-подій, маршрутизацію вихідного надсилання та сповіщення channel + +дозволів у стилі Claude через реальний stdio MCP bridge. Перевірка notification +безпосередньо інспектує сирі stdio MCP frames, тож smoke перевіряє те, що міст +справді виводить, а не лише те, що показує конкретний клієнтський SDK. +`test:docker:pi-bundle-mcp-tools` детермінований і не потребує ключа live- +моделі. Він збирає Docker-образ репозиторію, запускає всередині контейнера реальний stdio MCP probe server, +матеріалізує цей server через вбудований runtime bundle MCP Pi, виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх відфільтровують. -`test:docker:cron-mcp-cleanup` є детермінованим і не потребує ключа live-моделі. -Він запускає seeded Gateway з реальним stdio MCP probe server, виконує +`test:docker:cron-mcp-cleanup` детермінований і не потребує ключа live-моделі. +Він запускає seeded Gateway із реальним stdio MCP probe server, виконує ізольований хід Cron і одноразовий дочірній хід `/subagents spawn`, а потім перевіряє, що дочірній процес MCP завершується після кожного запуску. -Ручний smoke для ACP plain-language thread (не для CI): +Ручний smoke plain-language thread ACP (не для CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для workflow регресій/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тому не видаляйте його. +- Зберігайте цей скрипт для робочих процесів регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тому не видаляйте його. -Корисні env-змінні: +Корисні env vars: -- `OPENCLAW_CONFIG_DIR=...` (за замовчуванням: `~/.openclaw`), монтується в `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...` (за замовчуванням: `~/.openclaw/workspace`), монтується в `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (за замовчуванням: `~/.profile`), монтується в `/home/node/.profile` і використовується перед запуском тестів -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env-змінні, використані з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без монтування зовнішньої auth CLI -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`), монтується в `/home/node/.npm-global` для кешованих встановлень CLI у Docker -- Зовнішні auth-каталоги/файли CLI в `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` до початку тестів +- `OPENCLAW_CONFIG_DIR=...` (за замовчуванням: `~/.openclaw`) монтується в `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...` (за замовчуванням: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...` (за замовчуванням: `~/.profile`) монтується в `/home/node/.profile` і читається перед запуском тестів +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env vars, прочитані з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без монтування зовнішньої CLI-автентифікації +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих установлень CLI всередині Docker +- Зовнішні каталоги/файли CLI-автентифікації в `$HOME` монтуються лише для читання в `/host-auth...`, а потім копіюються в `/home/node/...` перед початком тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Перевизначайте вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, визначені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Перевизначайте вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому на кшталт `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб відфільтрувати провайдерів усередині контейнера - `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використовувати наявний образ `openclaw:local-live` для повторних запусків, яким не потрібна перебудова -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані надходять зі сховища профілів (а не з env) +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані беруться зі сховища профілів (а не з env) - `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway показує для smoke Open WebUI - `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt перевірки nonce, який використовує smoke Open WebUI -- `OPENWEBUI_IMAGE=...`, щоб перевизначити pinned tag образу Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег образу Open WebUI ## Перевірка документації -Після редагування документації запускайте перевірки: `pnpm check:docs`. -Запускайте повну перевірку anchors у Mintlify, коли також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. +Після редагування документації запускайте перевірки документації: `pnpm check:docs`. +Запускайте повну перевірку якорів Mintlify, коли також потрібні перевірки заголовків усередині сторінки: `pnpm docs:check-links:anchors`. -## Офлайнова регресія (безпечна для CI) +## Офлайн-регресія (безпечна для CI) -Це регресії «реального конвеєра» без реальних провайдерів: +Це регресії «реального pipeline» без реальних провайдерів: -- Виклик інструментів Gateway (mock OpenAI, реальний gateway + цикл agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Майстер Gateway (WS `wizard.start`/`wizard.next`, запис config + примусова auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Виклик інструментів Gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Майстер Gateway (WS `wizard.start`/`wizard.next`, примусовий запис config + auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") -## Оцінювання надійності агента (Skills) +## Оцінювання надійності агентів (Skills) -У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: +У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агентів»: -- Mock-виклик інструментів через реальний gateway + цикл agent (`src/gateway/gateway.test.ts`). -- Наскрізні потоки майстра, які перевіряють прив’язку сесії та ефекти config (`src/gateway/gateway.test.ts`). +- Mock-виклик інструментів через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). +- Наскрізні потоки майстра, які перевіряють підключення сесії та вплив конфігурації (`src/gateway/gateway.test.ts`). -Що ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Чого все ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Вибір рішення:** коли Skills перелічені в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? -- **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/args? -- **Контракти workflow:** multi-turn сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. +- **Decisioning:** коли Skills перелічені в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? +- **Compliance:** чи читає агент `SKILL.md` перед використанням і чи дотримується обов’язкових кроків/аргументів? +- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. -Майбутні eval мають спершу залишатися детермінованими: +Майбутні evals мають спочатку залишатися детермінованими: -- Runner сценаріїв із mock-провайдерами для перевірки викликів інструментів + їхнього порядку, читання skill-файлів і прив’язки сесії. -- Невеликий набір сценаріїв, сфокусованих на Skills (використовувати чи уникати, гейтінг, prompt injection). -- Необов’язкові live eval (за явним увімкненням, під контролем env) лише після того, як буде готовий безпечний для CI набір. +- Runner сценаріїв із mock-провайдерами для перевірки викликів інструментів і їх порядку, читання skill-файлів і підключення сесії. +- Невеликий набір сценаріїв, орієнтованих на skills (використати чи уникнути, gate, prompt injection). +- Необов’язкові live-evals (явно увімкнені, керовані env) лише після того, як буде готовий безпечний для CI набір. ## Контрактні тести (форма plugin і channel) Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає -контракту свого інтерфейсу. Вони ітеруються по всіх виявлених plugins і запускають -набір перевірок форми та поведінки. Типова unit lane `pnpm test` навмисно +своєму інтерфейсному контракту. Вони перебирають усі виявлені plugins і запускають набір +перевірок форми та поведінки. Типовий unit lane `pnpm test` навмисно пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно, -коли торкаєтеся спільних поверхонь channel або provider. +коли торкаєтесь спільних поверхонь channel або provider. ### Команди @@ -1077,55 +1108,55 @@ Open WebUI, перевіряє, що `/api/models` показує `openclaw/defa ### Контракти channel -Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: +Розміщені в `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Базова форма plugin (id, name, capabilities) -- **setup** - Контракт майстра setup +- **plugin** - Базова форма Plugin (id, name, capabilities) +- **setup** - Контракт майстра налаштування - **session-binding** - Поведінка прив’язки сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій channel - **threading** - Обробка ID thread - **directory** - API каталогу/реєстру -- **group-policy** - Примусове застосування групової policy +- **group-policy** - Застосування групової політики ### Контракти статусу provider -Розташовані в `src/plugins/contracts/*.contract.test.ts`. +Розміщені в `src/plugins/contracts/*.contract.test.ts`. - **status** - Перевірки статусу channel -- **registry** - Форма реєстру plugin +- **registry** - Форма реєстру Plugin ### Контракти provider -Розташовані в `src/plugins/contracts/*.contract.test.ts`: +Розміщені в `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Контракт потоку auth -- **auth-choice** - Вибір/відбір auth +- **auth** - Контракт потоку автентифікації +- **auth-choice** - Вибір/селекція автентифікації - **catalog** - API каталогу моделей -- **discovery** - Виявлення plugin -- **loader** - Завантаження plugin -- **runtime** - Runtime provider -- **shape** - Форма/інтерфейс plugin -- **wizard** - Майстер setup +- **discovery** - Виявлення Plugin +- **loader** - Завантаження Plugin +- **runtime** - Runtime провайдера +- **shape** - Форма/інтерфейс Plugin +- **wizard** - Майстер налаштування ### Коли запускати -- Після змін експортів або subpath у plugin-sdk +- Після змін експорту або підшляхів plugin-sdk - Після додавання або зміни channel чи provider plugin - Після рефакторингу реєстрації або виявлення plugin Контрактні тести запускаються в CI і не потребують реальних API-ключів. -## Додавання регресійних тестів (настанови) +## Додавання регресій (рекомендації) Коли ви виправляєте проблему провайдера/моделі, виявлену в live: -- Якщо можливо, додайте безпечну для CI регресію (mock/stub провайдера або зафіксуйте точну трансформацію форми запиту) -- Якщо вона за своєю природою лише для live (rate limits, policy auth), залишайте live-тест вузьким і за явним увімкненням через env-змінні -- Віддавайте перевагу націлюванню на найменший шар, який виявляє баг: - - баг перетворення/повторення запиту provider → direct models test - - баг конвеєра session/history/tool gateway → gateway live smoke або безпечний для CI mock-тест gateway -- Захисне обмеження обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибрану ціль для кожного класу SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id для segment обходу відхиляються. - - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не можна було тихо пропустити. +- Додайте безпечну для CI регресію, якщо це можливо (mock/stub провайдера або фіксація точного перетворення форми запиту) +- Якщо це властиво лише live-середовищу (rate limit, політики автентифікації), залишайте live-тест вузьким і з явним увімкненням через env vars +- Надавайте перевагу найменшому шару, який виявляє баг: + - баг перетворення/відтворення запиту провайдера → тест direct models + - баг pipeline сесії/історії/інструментів gateway → gateway live smoke або безпечний для CI mock-тест gateway +- Захист обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль для кожного класу SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів обходу відхиляються. + - Якщо ви додаєте нову сім’ю цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих ID цілей, щоб нові класи не можна було тихо пропустити. diff --git a/docs/uk/help/troubleshooting.md b/docs/uk/help/troubleshooting.md index dd88828ae..89b5bd133 100644 --- a/docs/uk/help/troubleshooting.md +++ b/docs/uk/help/troubleshooting.md @@ -1,25 +1,25 @@ --- read_when: - OpenClaw не працює, і вам потрібен найшвидший шлях до виправлення - - Ви хочете пройти потік тріажу, перш ніж занурюватися в детальні інструкції щодо усунення проблем + - Ви хочете пройти процес тріажу, перш ніж заглиблюватися в докладні інструкції з усунення проблем summary: Центр усунення несправностей OpenClaw за симптомами title: Загальне усунення несправностей x-i18n: - generated_at: "2026-04-20T06:31:12Z" + generated_at: "2026-04-23T18:24:13Z" model: gpt-5.4 provider: openai - source_hash: cc5d8c9f804084985c672c5a003ce866e8142ab99fe81abb7a0d38e22aea4b88 + source_hash: c6931ea9a8f29de0aa42c0afdf554e223fd2a794e95dce4f4795db99301d2c44 source_path: help/troubleshooting.md workflow: 15 --- # Усунення несправностей -Якщо у вас є лише 2 хвилини, використайте цю сторінку як початкову точку тріажу. +Якщо у вас є лише 2 хвилини, використовуйте цю сторінку як вхідну точку для тріажу. ## Перші 60 секунд -Виконайте цю точну послідовність команд по порядку: +Виконайте цю точну послідовність команд у вказаному порядку: ```bash openclaw status @@ -31,14 +31,14 @@ openclaw channels status --probe openclaw logs --follow ``` -Ознаки коректного виводу в одному рядку: +Хороший результат в один рядок: -- `openclaw status` → показує налаштовані канали й відсутність очевидних помилок автентифікації. -- `openclaw status --all` → повний звіт присутній і ним можна поділитися. -- `openclaw gateway probe` → очікуваний Gateway призначення доступний (`Reachable: yes`). `Capability: ...` показує, який рівень автентифікації змогла підтвердити перевірка, а `Read probe: limited - missing scope: operator.read` означає погіршену діагностику, а не збій з’єднання. -- `openclaw gateway status` → `Runtime: running`, `Connectivity probe: ok` і правдоподібний рядок `Capability: ...`. Використовуйте `--require-rpc`, якщо вам також потрібне підтвердження RPC з доступом на читання. -- `openclaw doctor` → немає блокувальних помилок конфігурації/сервісу. -- `openclaw channels status --probe` → доступний Gateway повертає поточний стан транспорту для кожного облікового запису разом із результатами перевірки/аудиту, наприклад `works` або `audit ok`; якщо Gateway недоступний, команда повертається до зведень лише за конфігурацією. +- `openclaw status` → показує налаштовані канали та відсутність явних помилок автентифікації. +- `openclaw status --all` → повний звіт наявний і ним можна поділитися. +- `openclaw gateway probe` → очікувана ціль Gateway доступна (`Reachable: yes`). `Capability: ...` показує, який рівень автентифікації вдалося підтвердити перевіркою, а `Read probe: limited - missing scope: operator.read` означає погіршену діагностику, а не збій з’єднання. +- `openclaw gateway status` → `Runtime: running`, `Connectivity probe: ok` і правдоподібний рядок `Capability: ...`. Використовуйте `--require-rpc`, якщо вам також потрібне підтвердження RPC з областю читання. +- `openclaw doctor` → відсутні блокувальні помилки конфігурації або сервісу. +- `openclaw channels status --probe` → доступний Gateway повертає живий стан транспорту для кожного облікового запису разом із результатами probe/audit, такими як `works` або `audit ok`; якщо Gateway недоступний, команда повертається до зведень лише на основі конфігурації. - `openclaw logs --follow` → стабільна активність, без повторюваних фатальних помилок. ## 429 для довгого контексту Anthropic @@ -49,23 +49,16 @@ openclaw logs --follow ## Локальний OpenAI-compatible бекенд працює напряму, але не працює в OpenClaw -Якщо ваш локальний або self-hosted бекенд `/v1` відповідає на малі прямі перевірки -`/v1/chat/completions`, але завершується помилкою на `openclaw infer model run` або під час звичайних -ходів агента: +Якщо ваш локальний або самостійно розгорнутий `/v1` бекенд відповідає на невеликі прямі перевірки `/v1/chat/completions`, але не працює з `openclaw infer model run` або під час звичайних ходів агента: -1. Якщо в помилці згадується, що `messages[].content` очікує рядок, установіть - `models.providers..models[].compat.requiresStringContent: true`. -2. Якщо бекенд і далі дає збій лише під час ходів агента OpenClaw, установіть - `models.providers..models[].compat.supportsTools: false` і повторіть спробу. -3. Якщо крихітні прямі виклики все ще працюють, але більші запити OpenClaw аварійно завершують - бекенд, вважайте решту проблеми обмеженням моделі/сервера на боці вищого рівня і - продовжуйте в детальній інструкції: +1. Якщо в помилці згадується, що `messages[].content` очікує рядок, встановіть `models.providers..models[].compat.requiresStringContent: true`. +2. Якщо бекенд і далі не працює лише під час ходів агента OpenClaw, встановіть `models.providers..models[].compat.supportsTools: false` і повторіть спробу. +3. Якщо крихітні прямі виклики все ще працюють, але більші підказки OpenClaw аварійно завершують роботу бекенда, розглядайте решту проблеми як обмеження моделі/сервера на боці upstream і переходьте до докладної інструкції: [/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail](/uk/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail) ## Не вдається встановити Plugin через відсутні openclaw extensions -Якщо встановлення завершується помилкою `package.json missing openclaw.extensions`, пакет Plugin -використовує стару структуру, яку OpenClaw більше не приймає. +Якщо встановлення завершується помилкою `package.json missing openclaw.extensions`, пакет Plugin використовує старий формат, який OpenClaw більше не приймає. Виправлення в пакеті Plugin: @@ -97,8 +90,8 @@ flowchart TD B --> E[Gateway не запускається або сервіс не працює] B --> F[Канал підключається, але повідомлення не проходять] B --> G[Cron або Heartbeat не спрацював чи не доставив повідомлення] - B --> H[Node спарено, але не працює інструмент camera canvas screen exec] - B --> I[Не працює інструмент browser] + B --> H[Node спарено, але camera canvas screen exec не працює] + B --> I[Не працює інструмент браузера] C --> C1[/Розділ «Немає відповідей»/] D --> D1[/Розділ «Control UI»/] @@ -106,7 +99,7 @@ flowchart TD F --> F1[/Розділ «Потік каналу»/] G --> G1[/Розділ «Автоматизація»/] H --> H1[/Розділ «Інструменти Node»/] - I --> I1[/Розділ «Browser»/] + I --> I1[/Розділ «Браузер»/] ``` @@ -119,21 +112,21 @@ flowchart TD openclaw logs --follow ``` - Коректний вивід виглядає так: + Хороший результат виглядає так: - `Runtime: running` - `Connectivity probe: ok` - `Capability: read-only`, `write-capable` або `admin-capable` - Ваш канал показує підключений транспорт і, де це підтримується, `works` або `audit ok` у `channels status --probe` - - Відправника показано як схваленого (або політика DM відкрита/є в allowlist) + - Відправника показано як схваленого (або політика DM відкрита/дозволений список) - Типові сигнатури в журналах: + Поширені сигнатури в журналах: - - `drop guild message (mention required` → обробку повідомлення було заблоковано вимогою згадки в Discord. - - `pairing request` → відправника не схвалено, він очікує на схвалення спарювання в DM. - - `blocked` / `allowlist` у журналах каналу → відправника, кімнату або групу відфільтровано. + - `drop guild message (mention required` → у Discord повідомлення було заблоковане вимогою згадки. + - `pairing request` → відправник не схвалений і очікує підтвердження спарювання DM. + - `blocked` / `allowlist` у журналах каналу → відправник, кімната або група фільтруються. - Детальні сторінки: + Докладні сторінки: - [/gateway/troubleshooting#no-replies](/uk/gateway/troubleshooting#no-replies) - [/channels/troubleshooting](/uk/channels/troubleshooting) @@ -150,28 +143,28 @@ flowchart TD openclaw channels status --probe ``` - Коректний вивід виглядає так: + Хороший результат виглядає так: - `Dashboard: http://...` показано в `openclaw gateway status` - `Connectivity probe: ok` - `Capability: read-only`, `write-capable` або `admin-capable` - У журналах немає циклу автентифікації - Типові сигнатури в журналах: + Поширені сигнатури в журналах: - `device identity required` → HTTP/незахищений контекст не може завершити автентифікацію пристрою. - - `origin not allowed` → `Origin` браузера не дозволений для Gateway призначення Control UI. - - `AUTH_TOKEN_MISMATCH` із підказками повторної спроби (`canRetryWithDeviceToken=true`) → автоматично може відбутися одна повторна спроба з довіреним токеном пристрою. - - Ця повторна спроба з кешованим токеном повторно використовує кешований набір scope, збережений разом зі спареним токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` натомість зберігають запитаний ними набір scope. - - На асинхронному шляху Tailscale Serve для Control UI невдалі спроби для одного й того ж `{scope, ip}` серіалізуються до того, як лімітер зафіксує збій, тому друга одночасна хибна повторна спроба вже може показувати `retry later`. - - `too many failed authentication attempts (retry later)` з браузерного localhost-origin → повторні невдалі спроби з того самого `Origin` тимчасово блокуються; інший localhost-origin використовує окремий bucket. - - повторювані `unauthorized` після цієї повторної спроби → неправильний токен/пароль, невідповідність режиму автентифікації або застарілий спарений токен пристрою. - - `gateway connect failed:` → UI націлено на неправильний URL/порт або Gateway недоступний. + - `origin not allowed` → `Origin` браузера не дозволений для цілі Gateway у Control UI. + - `AUTH_TOKEN_MISMATCH` із підказками для повтору (`canRetryWithDeviceToken=true`) → одна довірена повторна спроба з токеном пристрою може відбутися автоматично. + - Ця повторна спроба з кешованим токеном повторно використовує кешований набір областей, збережений разом зі спареним токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` замість цього зберігають власний запитаний набір областей. + - В асинхронному шляху Tailscale Serve для Control UI невдалі спроби для того самого `{scope, ip}` серіалізуються до того, як обмежувач зафіксує збій, тому друга одночасна хибна повторна спроба вже може показувати `retry later`. + - `too many failed authentication attempts (retry later)` з локального джерела браузера localhost → повторні невдалі спроби з цього самого `Origin` тимчасово блокуються; інше джерело localhost використовує окремий bucket. + - повторюване `unauthorized` після цієї повторної спроби → неправильний токен/пароль, невідповідний режим автентифікації або застарілий спарений токен пристрою. + - `gateway connect failed:` → UI націлений на неправильний URL/порт або Gateway недоступний. - Детальні сторінки: + Докладні сторінки: - [/gateway/troubleshooting#dashboard-control-ui-connectivity](/uk/gateway/troubleshooting#dashboard-control-ui-connectivity) - - [/web/control-ui](/web/control-ui) + - [/web/control-ui](/uk/web/control-ui) - [/gateway/authentication](/uk/gateway/authentication) @@ -185,20 +178,20 @@ flowchart TD openclaw channels status --probe ``` - Коректний вивід виглядає так: + Хороший результат виглядає так: - `Service: ... (loaded)` - `Runtime: running` - `Connectivity probe: ok` - `Capability: read-only`, `write-capable` або `admin-capable` - Типові сигнатури в журналах: + Поширені сигнатури в журналах: - - `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → режим Gateway встановлено як remote, або у файлі конфігурації відсутня позначка local-mode і його слід виправити. - - `refusing to bind gateway ... without auth` → прив’язка не до loopback без дійсного шляху автентифікації Gateway (token/password або trusted-proxy, де налаштовано). - - `another gateway instance is already listening` або `EADDRINUSE` → порт уже зайнято. + - `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → режим Gateway віддалений, або у файлі конфігурації відсутня позначка локального режиму і його слід відновити. + - `refusing to bind gateway ... without auth` → прив’язка не-loopback без дійсного шляху автентифікації Gateway (токен/пароль або trusted-proxy, якщо налаштовано). + - `another gateway instance is already listening` або `EADDRINUSE` → порт уже зайнятий. - Детальні сторінки: + Докладні сторінки: - [/gateway/troubleshooting#gateway-service-not-running](/uk/gateway/troubleshooting#gateway-service-not-running) - [/gateway/background-process](/uk/gateway/background-process) @@ -215,19 +208,19 @@ flowchart TD openclaw channels status --probe ``` - Коректний вивід виглядає так: + Хороший результат виглядає так: - Транспорт каналу підключений. - - Перевірки pairing/allowlist проходять. - - Згадки визначаються там, де вони обов’язкові. + - Перевірки pairing/allowlist успішні. + - Згадки виявляються там, де вони потрібні. - Типові сигнатури в журналах: + Поширені сигнатури в журналах: - `mention required` → обробку заблоковано вимогою згадки в групі. - - `pairing` / `pending` → відправника DM ще не схвалено. + - `pairing` / `pending` → відправника в DM ще не схвалено. - `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → проблема з токеном дозволів каналу. - Детальні сторінки: + Докладні сторінки: - [/gateway/troubleshooting#channel-connected-messages-not-flowing](/uk/gateway/troubleshooting#channel-connected-messages-not-flowing) - [/channels/troubleshooting](/uk/channels/troubleshooting) @@ -244,147 +237,147 @@ flowchart TD openclaw logs --follow ``` - Коректний вивід виглядає так: + Хороший результат виглядає так: - - `cron.status` показує, що його ввімкнено, і вказує час наступного пробудження. - - `cron runs` показує нещодавні записи `ok`. - - Heartbeat увімкнено й він не поза межами активних годин. + - `cron.status` показує, що все ввімкнено і є наступне пробудження. + - `cron runs` показує недавні записи `ok`. + - Heartbeat увімкнено і він не поза межами активних годин. - Типові сигнатури в журналах: + Поширені сигнатури в журналах: - `cron: scheduler disabled; jobs will not run automatically` → Cron вимкнено. - `heartbeat skipped` з `reason=quiet-hours` → поза налаштованими активними годинами. - - `heartbeat skipped` з `reason=empty-heartbeat-file` → `HEARTBEAT.md` існує, але містить лише порожній/header-only каркас. - - `heartbeat skipped` з `reason=no-tasks-due` → увімкнено режим завдань `HEARTBEAT.md`, але час для жодного з інтервалів завдань ще не настав. + - `heartbeat skipped` з `reason=empty-heartbeat-file` → `HEARTBEAT.md` існує, але містить лише порожній/лише-заголовки каркас. + - `heartbeat skipped` з `reason=no-tasks-due` → у `HEARTBEAT.md` активний режим завдань, але ще не настав час для жодного з інтервалів завдань. - `heartbeat skipped` з `reason=alerts-disabled` → усю видимість Heartbeat вимкнено (`showOk`, `showAlerts` і `useIndicator` усі вимкнені). - - `requests-in-flight` → основна смуга зайнята; пробудження Heartbeat було відкладено. - - `unknown accountId` → цільовий account доставки Heartbeat не існує. + - `requests-in-flight` → основна смуга зайнята; пробудження Heartbeat було відкладене. + - `unknown accountId` → цільовий обліковий запис доставки Heartbeat не існує. - Детальні сторінки: + Докладні сторінки: - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/uk/gateway/troubleshooting#cron-and-heartbeat-delivery) - [/automation/cron-jobs#troubleshooting](/uk/automation/cron-jobs#troubleshooting) - [/gateway/heartbeat](/uk/gateway/heartbeat) - + - - ```bash - openclaw status - openclaw gateway status - openclaw nodes status - openclaw nodes describe --node - openclaw logs --follow - ``` + + ```bash + openclaw status + openclaw gateway status + openclaw nodes status + openclaw nodes describe --node + openclaw logs --follow + ``` - Коректний вивід виглядає так: + Хороший результат виглядає так: - - Node показано як підключений і спарений для ролі `node`. - - Для команди, яку ви викликаєте, існує Capability. - - Для інструмента надано стан дозволу. + - Node указано як підключений і спарений для ролі `node`. + - Для команди, яку ви викликаєте, існує Capability. + - Стан дозволів для інструмента надано. - Типові сигнатури в журналах: + Поширені сигнатури в журналах: - - `NODE_BACKGROUND_UNAVAILABLE` → переведіть застосунок Node на передній план. - - `*_PERMISSION_REQUIRED` → дозвіл ОС було відхилено/він відсутній. - - `SYSTEM_RUN_DENIED: approval required` → очікується схвалення exec. - - `SYSTEM_RUN_DENIED: allowlist miss` → команди немає в allowlist для exec. + - `NODE_BACKGROUND_UNAVAILABLE` → переведіть застосунок node на передній план. + - `*_PERMISSION_REQUIRED` → дозвіл ОС було відхилено/відсутній. + - `SYSTEM_RUN_DENIED: approval required` → очікується схвалення exec. + - `SYSTEM_RUN_DENIED: allowlist miss` → команди немає в allowlist exec. - Детальні сторінки: + Докладні сторінки: - - [/gateway/troubleshooting#node-paired-tool-fails](/uk/gateway/troubleshooting#node-paired-tool-fails) - - [/nodes/troubleshooting](/uk/nodes/troubleshooting) - - [/tools/exec-approvals](/uk/tools/exec-approvals) + - [/gateway/troubleshooting#node-paired-tool-fails](/uk/gateway/troubleshooting#node-paired-tool-fails) + - [/nodes/troubleshooting](/uk/nodes/troubleshooting) + - [/tools/exec-approvals](/uk/tools/exec-approvals) - + - - ```bash - openclaw config get tools.exec.host - openclaw config get tools.exec.security - openclaw config get tools.exec.ask - openclaw gateway restart - ``` + + ```bash + openclaw config get tools.exec.host + openclaw config get tools.exec.security + openclaw config get tools.exec.ask + openclaw gateway restart + ``` - Що змінилося: + Що змінилося: - - Якщо `tools.exec.host` не встановлено, значенням за замовчуванням є `auto`. - - `host=auto` визначається як `sandbox`, коли активне sandbox runtime, і як `gateway` в іншому разі. - - `host=auto` впливає лише на маршрутизацію; поведінка "YOLO" без запитів походить від `security=full` разом із `ask=off` на gateway/node. - - Для `gateway` і `node`, якщо `tools.exec.security` не встановлено, значенням за замовчуванням є `full`. - - Якщо `tools.exec.ask` не встановлено, значенням за замовчуванням є `off`. - - Результат: якщо ви бачите запити на схвалення, значить якась локальна для хоста або поточної сесії політика зробила exec суворішим порівняно з поточними значеннями за замовчуванням. + - Якщо `tools.exec.host` не задано, значенням за замовчуванням є `auto`. + - `host=auto` перетворюється на `sandbox`, коли активне runtime sandbox, і на `gateway` в іншому випадку. + - `host=auto` відповідає лише за маршрутизацію; поведінка без запитів "YOLO" походить від `security=full` разом із `ask=off` на gateway/node. + - Для `gateway` і `node`, якщо `tools.exec.security` не задано, за замовчуванням використовується `full`. + - Якщо `tools.exec.ask` не задано, за замовчуванням використовується `off`. + - Результат: якщо ви бачите запити на схвалення, це означає, що якась локальна для хоста або поточної сесії політика зробила exec суворішим порівняно з поточними значеннями за замовчуванням. - Відновіть поточну поведінку без схвалень за замовчуванням: + Відновлення поточної стандартної поведінки без схвалення: - ```bash - openclaw config set tools.exec.host gateway - openclaw config set tools.exec.security full - openclaw config set tools.exec.ask off - openclaw gateway restart - ``` + ```bash + openclaw config set tools.exec.host gateway + openclaw config set tools.exec.security full + openclaw config set tools.exec.ask off + openclaw gateway restart + ``` - Безпечніші альтернативи: + Безпечніші альтернативи: - - Установіть лише `tools.exec.host=gateway`, якщо вам потрібна просто стабільна маршрутизація хоста. - - Використовуйте `security=allowlist` разом із `ask=on-miss`, якщо хочете exec на хості, але все одно хочете перевірку для промахів повз allowlist. - - Увімкніть sandbox mode, якщо хочете, щоб `host=auto` знову визначався як `sandbox`. + - Встановіть лише `tools.exec.host=gateway`, якщо вам просто потрібна стабільна маршрутизація хоста. + - Використовуйте `security=allowlist` разом із `ask=on-miss`, якщо вам потрібен host exec, але ви все ще хочете перевірку в разі промахів по allowlist. + - Увімкніть режим sandbox, якщо хочете, щоб `host=auto` знову перетворювався на `sandbox`. - Типові сигнатури в журналах: + Поширені сигнатури в журналах: - - `Approval required.` → команда очікує на `/approve ...`. - - `SYSTEM_RUN_DENIED: approval required` → очікується схвалення exec на вузлі-хості. - - `exec host=sandbox requires a sandbox runtime for this session` → неявний/явний вибір sandbox, але sandbox mode вимкнено. + - `Approval required.` → команда очікує на `/approve ...`. + - `SYSTEM_RUN_DENIED: approval required` → очікується схвалення exec для хоста node. + - `exec host=sandbox requires a sandbox runtime for this session` → неявно/явно вибрано sandbox, але режим sandbox вимкнено. - Детальні сторінки: + Докладні сторінки: - - [/tools/exec](/uk/tools/exec) - - [/tools/exec-approvals](/uk/tools/exec-approvals) - - [/gateway/security#what-the-audit-checks-high-level](/uk/gateway/security#what-the-audit-checks-high-level) + - [/tools/exec](/uk/tools/exec) + - [/tools/exec-approvals](/uk/tools/exec-approvals) + - [/gateway/security#what-the-audit-checks-high-level](/uk/gateway/security#what-the-audit-checks-high-level) - + - - ```bash - openclaw status - openclaw gateway status - openclaw browser status - openclaw logs --follow - openclaw doctor - ``` + + ```bash + openclaw status + openclaw gateway status + openclaw browser status + openclaw logs --follow + openclaw doctor + ``` - Коректний вивід виглядає так: + Хороший результат виглядає так: - - Статус browser показує `running: true` і вибраний browser/profile. - - `openclaw` запускається, або `user` може бачити локальні вкладки Chrome. + - Стан браузера показує `running: true` і вибраний браузер/профіль. + - `openclaw` запускається, або `user` може бачити локальні вкладки Chrome. - Типові сигнатури в журналах: + Поширені сигнатури в журналах: - - `unknown command "browser"` або `unknown command 'browser'` → встановлено `plugins.allow`, і воно не містить `browser`. - - `Failed to start Chrome CDP on port` → не вдалося запустити локальний browser Chrome. - - `browser.executablePath not found` → налаштований шлях до бінарного файла неправильний. - - `browser.cdpUrl must be http(s) or ws(s)` → налаштований CDP URL використовує непідтримувану схему. - - `browser.cdpUrl has invalid port` → налаштований CDP URL має неправильний або неприпустимий порт. - - `No Chrome tabs found for profile="user"` → профіль приєднання Chrome MCP не має відкритих локальних вкладок Chrome. - - `Remote CDP for profile "" is not reachable` → налаштована віддалена кінцева точка CDP недоступна з цього хоста. - - `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → профіль attach-only не має активної цілі CDP. - - застарілі перевизначення viewport / dark-mode / locale / offline на профілях attach-only або remote CDP → виконайте `openclaw browser stop --browser-profile `, щоб закрити активну керовану сесію й скинути стан емуляції без перезапуску gateway. + - `unknown command "browser"` або `unknown command 'browser'` → задано `plugins.allow`, і воно не містить `browser`. + - `Failed to start Chrome CDP on port` → не вдалося запустити локальний браузер. + - `browser.executablePath not found` → налаштований шлях до бінарного файла неправильний. + - `browser.cdpUrl must be http(s) or ws(s)` → налаштований URL CDP використовує непідтримувану схему. + - `browser.cdpUrl has invalid port` → налаштований URL CDP містить неправильний або недопустимий порт. + - `No Chrome tabs found for profile="user"` → у профілі Chrome MCP attach немає відкритих локальних вкладок Chrome. + - `Remote CDP for profile "" is not reachable` → налаштована віддалена кінцева точка CDP недоступна з цього хоста. + - `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → для профілю attach-only немає живої цілі CDP. + - застарілі перевизначення viewport / dark-mode / locale / offline для профілів attach-only або remote CDP → виконайте `openclaw browser stop --browser-profile `, щоб закрити активну керувальну сесію та звільнити стан емуляції без перезапуску gateway. - Детальні сторінки: + Докладні сторінки: - - [/gateway/troubleshooting#browser-tool-fails](/uk/gateway/troubleshooting#browser-tool-fails) - - [/tools/browser#missing-browser-command-or-tool](/uk/tools/browser#missing-browser-command-or-tool) - - [/tools/browser-linux-troubleshooting](/uk/tools/browser-linux-troubleshooting) - - [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/uk/tools/browser-wsl2-windows-remote-cdp-troubleshooting) + - [/gateway/troubleshooting#browser-tool-fails](/uk/gateway/troubleshooting#browser-tool-fails) + - [/tools/browser#missing-browser-command-or-tool](/uk/tools/browser#missing-browser-command-or-tool) + - [/tools/browser-linux-troubleshooting](/uk/tools/browser-linux-troubleshooting) + - [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/uk/tools/browser-wsl2-windows-remote-cdp-troubleshooting) - + - + -## Пов’язане +## Пов’язані матеріали -- [FAQ](/uk/help/faq) — поширені запитання +- [FAQ](/uk/help/faq) — часті запитання - [Усунення несправностей Gateway](/uk/gateway/troubleshooting) — проблеми, пов’язані з Gateway -- [Doctor](/uk/gateway/doctor) — автоматизовані перевірки стану й виправлення +- [Doctor](/uk/gateway/doctor) — автоматизовані перевірки стану та відновлення - [Усунення несправностей каналів](/uk/channels/troubleshooting) — проблеми з підключенням каналів - [Усунення несправностей автоматизації](/uk/automation/cron-jobs#troubleshooting) — проблеми з Cron і Heartbeat diff --git a/docs/uk/tools/exec-approvals.md b/docs/uk/tools/exec-approvals.md index 8371fe210..3cd7396fa 100644 --- a/docs/uk/tools/exec-approvals.md +++ b/docs/uk/tools/exec-approvals.md @@ -1,66 +1,70 @@ --- read_when: - - Налаштування підтверджень виконання або списків дозволених елементів - - Реалізація UX підтвердження виконання в застосунку для macOS - - Перегляд запитів на вихід із пісочниці та їхніх наслідків -summary: Підтвердження виконання, списки дозволених елементів і запити на вихід із пісочниці -title: Підтвердження виконання + - Налаштування схвалень виконання або списків дозволених дій + - Реалізація UX схвалення виконання в застосунку macOS + - Перегляд підказок виходу з пісочниці та їхніх наслідків +summary: Підказки щодо схвалення виконання, списків дозволених дій і виходу з пісочниці +title: Схвалення виконання x-i18n: - generated_at: "2026-04-23T17:53:33Z" + generated_at: "2026-04-23T18:24:14Z" model: gpt-5.4 provider: openai - source_hash: 942d09665ff9d567361b0c5ee195a5a6b8c893ea1c9412caa33a02acd8e5e5be + source_hash: 1a5aca24c739cd4edfe5389c4897cb6f2efc07141217a70610c247aaa71a5284 source_path: tools/exec-approvals.md workflow: 15 --- -# Підтвердження виконання +# Схвалення виконання -Підтвердження виконання — це **захисний механізм застосунку-компаньйона / хоста node** для надання агенту в пісочниці можливості запускати команди на реальному хості (`gateway` або `node`). Це запобіжник безпеки: команди дозволяються лише тоді, коли збігаються політика + список дозволених елементів + (необов’язково) підтвердження користувача. Підтвердження виконання накладаються **поверх** політики інструментів і підвищеного доступу (окрім випадку, коли elevated встановлено в `full`, що пропускає підтвердження). +Схвалення виконання — це **захисний механізм companion app / хоста вузла** для того, щоб дозволити агенту в пісочниці запускати команди на реальному хості (`gateway` або `node`). Це запобіжник: команди дозволяються лише тоді, коли збігаються політика + список дозволених дій + (необов’язкове) схвалення користувача. Схвалення виконання нашаровуються **поверх** політики інструментів і контролю elevated (якщо тільки elevated не встановлено в `full`, що пропускає схвалення). -Ефективна політика є **суворішою** з `tools.exec.*` і типових значень підтверджень; якщо якесь поле підтверджень пропущене, використовується значення `tools.exec`. Виконання на хості також використовує локальний стан підтверджень на цій машині — локальне для хоста `ask: "always"` у `~/.openclaw/exec-approvals.json` продовжить показувати запити, навіть якщо сеанс або типові значення конфігурації вимагають `ask: "on-miss"`. +Ефективна політика — **суворіша** з `tools.exec.*` і типових значень схвалень; якщо поле схвалень не вказане, використовується значення `tools.exec`. Виконання на хості також використовує локальний стан схвалень на цій машині — локальне для хоста `ask: "always"` у `~/.openclaw/exec-approvals.json` продовжує показувати запити навіть якщо параметри сеансу або конфігурації вимагають `ask: "on-miss"`. ## Перегляд ефективної політики - `openclaw approvals get`, `... --gateway`, `... --node ` — показують запитану політику, джерела політики хоста та ефективний результат. -- `openclaw exec-policy show` — об’єднане представлення для локальної машини. -- `openclaw exec-policy set|preset` — синхронізує локально запитану політику з локальним файлом підтверджень хоста в один крок. +- `openclaw exec-policy show` — об’єднане подання для локальної машини. +- `openclaw exec-policy set|preset` — синхронізує локально запитану політику з локальним файлом схвалень хоста за один крок. -Коли локальна область видимості запитує `host=node`, `exec-policy show` повідомляє, що ця область керується node під час виконання, замість того щоб удавати, ніби локальний файл підтверджень є джерелом істини. +Коли локальна область запитує `host=node`, `exec-policy show` повідомляє, що ця область під час виконання керується вузлом, замість того щоб удавати, ніби локальний файл схвалень є джерелом істини. -Якщо UI застосунку-компаньйона **недоступний**, будь-який запит, який зазвичай вимагав би підтвердження, обробляється через **резервний режим ask** (типово: deny). +Якщо UI companion app **недоступний**, будь-який запит, який зазвичай мав би викликати запит на схвалення, вирішується через **резервний режим ask** (типово: deny). -Нативні клієнти підтвердження в чаті можуть додавати специфічні для каналу елементи керування до повідомлення про очікуване підтвердження. Наприклад, Matrix додає швидкі реакції (`✅` -дозволити один раз, `❌` відхилити, `♾️` завжди дозволяти), водночас залишаючи команди `/approve ...` у повідомленні як запасний варіант. +Нативні клієнти схвалення в чаті можуть додавати специфічні для каналу зручності до повідомлення з очікуванням схвалення. Наприклад, Matrix додає скорочення через реакції (`✅` +дозволити один раз, `❌` відхилити, `♾️` дозволити завжди), водночас залишаючи в повідомленні команди `/approve ...` як запасний варіант. ## Де це застосовується -Підтвердження виконання застосовуються локально на хості виконання: +Схвалення виконання примусово застосовуються локально на хості виконання: -- **хост gateway** → процес `openclaw` на машині gateway -- **хост node** → раннер node (застосунок-компаньйон для macOS або безголовий хост node) +- **хост gateway** → процес `openclaw` на машині Gateway +- **хост node** → раннер вузла (macOS companion app або headless-хост вузла) Примітка щодо моделі довіри: -- Викликаючі сторони, автентифіковані через Gateway, є довіреними операторами для цього Gateway. -- Прив’язані nodes поширюють цю можливість довіреного оператора на хост node. -- Підтвердження виконання зменшують ризик випадкового виконання, але не є межею автентифікації на рівні користувача. -- Схвалені запуски на хості node прив’язують канонічний контекст виконання: канонічний cwd, точний argv, прив’язку env за наявності та зафіксований шлях до виконуваного файла, де це застосовно. -- Для shell-скриптів і прямих викликів файлів інтерпретатора/середовища виконання OpenClaw також намагається прив’язати один конкретний локальний файловий операнд. Якщо цей прив’язаний файл змінюється після підтвердження, але до виконання, запуск відхиляється замість виконання зміненого вмісту. -- Ця прив’язка файлу навмисно реалізована за принципом максимально можливого наближення, а не як повна семантична модель для кожного шляху завантаження інтерпретатора/середовища виконання. Якщо режим підтвердження не може точно визначити один конкретний локальний файл для прив’язки, він відмовляється створювати запуск, підкріплений підтвердженням, замість того щоб удавати повне покриття. +- Викликачі, автентифіковані через Gateway, є довіреними операторами для цього Gateway. +- Спарені вузли розширюють цю можливість довіреного оператора на хост вузла. +- Схвалення виконання знижують ризик випадкового виконання, але не є межею автентифікації на рівні окремого користувача. +- Схвалені запуски на хості вузла прив’язують канонічний контекст виконання: канонічний cwd, точний argv, прив’язку env за наявності та зафіксований шлях до виконуваного файла, де це застосовно. +- Для shell-скриптів і прямих викликів файлів через інтерпретатор/середовище виконання OpenClaw також намагається прив’язати + один конкретний локальний файловий операнд. Якщо цей прив’язаний файл змінюється після схвалення, але до виконання, + запуск відхиляється замість виконання зміненого вмісту. +- Ця файлова прив’язка навмисно є best-effort, а не повною семантичною моделлю для кожного + шляху завантаження інтерпретатора/середовища виконання. Якщо режим схвалення не може точно визначити один конкретний локальний + файл для прив’язки, він відмовляється створювати запуск із підкріпленням схваленням, замість того щоб удавати повне покриття. -Поділ у macOS: +Розділення на macOS: -- **служба хоста node** пересилає `system.run` до **застосунку macOS** через локальний IPC. -- **застосунок macOS** застосовує підтвердження + виконує команду в контексті UI. +- **служба хоста вузла** пересилає `system.run` до **застосунку macOS** через локальний IPC. +- **застосунок macOS** застосовує схвалення + виконує команду в контексті UI. -## Налаштування і зберігання +## Налаштування та зберігання -Підтвердження зберігаються в локальному JSON-файлі на хості виконання: +Схвалення зберігаються в локальному JSON-файлі на хості виконання: `~/.openclaw/exec-approvals.json` @@ -99,27 +103,27 @@ x-i18n: } ``` -## Режим "YOLO" без підтверджень +## Режим "YOLO" без схвалень -Якщо ви хочете, щоб виконання на хості працювало без запитів на підтвердження, потрібно відкрити **обидва** шари політики: +Якщо ви хочете, щоб виконання на хості працювало без запитів на схвалення, потрібно відкрити **обидва** шари політики: -- запитану політику виконання в конфігурації OpenClaw (`tools.exec.*`) -- локальну політику підтверджень хоста в `~/.openclaw/exec-approvals.json` +- запитана політика виконання в конфігурації OpenClaw (`tools.exec.*`) +- локальна для хоста політика схвалень у `~/.openclaw/exec-approvals.json` Тепер це типова поведінка хоста, якщо ви явно не зробите її суворішою: - `tools.exec.security`: `full` на `gateway`/`node` - `tools.exec.ask`: `off` -- `host askFallback`: `full` +- хостове `askFallback`: `full` Важлива відмінність: -- `tools.exec.host=auto` вибирає, де запускається виконання: у пісочниці, якщо вона доступна, інакше на gateway. -- YOLO вибирає, як схвалюється виконання на хості: `security=full` плюс `ask=off`. -- У режимі YOLO OpenClaw не додає окремий евристичний бар’єр підтвердження для обфускації команд або додатковий шар відхилення скриптів перед запуском поверх налаштованої політики виконання на хості. -- `auto` не робить маршрутизацію через gateway вільним обхідним шляхом із сеансу в пісочниці. Запит `host=node` для окремого виклику дозволений із `auto`, а `host=gateway` дозволяється з `auto` лише тоді, коли активного середовища пісочниці немає. Якщо вам потрібне стабільне типове значення не `auto`, встановіть `tools.exec.host` або використовуйте `/exec host=...` явно. +- `tools.exec.host=auto` визначає, де виконується exec: у пісочниці, якщо вона доступна, інакше на gateway. +- YOLO визначає, як схвалюється виконання на хості: `security=full` плюс `ask=off`. +- У режимі YOLO OpenClaw не додає окремий евристичний бар’єр схвалення для обфускації команд або рівень відхилення скриптів перед виконанням поверх налаштованої політики виконання на хості. +- `auto` не робить маршрутизацію через gateway безкоштовним обходом із сеансу в пісочниці. Запит `host=node` для окремого виклику дозволений із `auto`, а `host=gateway` дозволений із `auto` лише коли не активне середовище пісочниці. Якщо вам потрібне стабільне типове значення не `auto`, установіть `tools.exec.host` або використовуйте `/exec host=...` явно. -Якщо вам потрібне більш консервативне налаштування, зробіть будь-який із шарів суворішим, повернувши `allowlist` / `on-miss` +Якщо вам потрібніше більш консервативне налаштування, знову зробіть будь-який із шарів суворішим, установивши `allowlist` / `on-miss` або `deny`. Постійне налаштування "ніколи не запитувати" для хоста gateway: @@ -131,7 +135,7 @@ openclaw config set tools.exec.ask off openclaw gateway restart ``` -Потім налаштуйте файл підтверджень хоста відповідним чином: +Потім налаштуйте файл схвалень хоста так, щоб він відповідав цьому: ```bash openclaw approvals set --stdin <<'EOF' @@ -146,22 +150,22 @@ openclaw approvals set --stdin <<'EOF' EOF ``` -Локальний скорочений варіант для тієї ж політики хоста gateway на поточній машині: +Локальне скорочення для тієї самої політики хоста gateway на поточній машині: ```bash openclaw exec-policy preset yolo ``` -Цей локальний скорочений варіант оновлює обидва значення: +Це локальне скорочення оновлює обидва параметри: - локальні `tools.exec.host/security/ask` - локальні типові значення в `~/.openclaw/exec-approvals.json` -Він навмисно працює лише локально. Якщо вам потрібно змінити підтвердження хоста gateway або хоста node -віддалено, і надалі використовуйте `openclaw approvals set --gateway` або +Воно навмисно працює лише локально. Якщо вам потрібно змінити схвалення хоста gateway або хоста node +віддалено, продовжуйте використовувати `openclaw approvals set --gateway` або `openclaw approvals set --node `. -Для хоста node застосуйте той самий файл підтверджень на цьому node: +Для хоста вузла застосуйте той самий файл схвалень на цьому вузлі: ```bash openclaw approvals set --node --stdin <<'EOF' @@ -176,45 +180,45 @@ openclaw approvals set --node --stdin <<'EOF' EOF ``` -Важливе обмеження лише для локального використання: +Важливе обмеження лише для локальної машини: -- `openclaw exec-policy` не синхронізує підтвердження node +- `openclaw exec-policy` не синхронізує схвалення вузла - `openclaw exec-policy set --host node` відхиляється -- підтвердження виконання для node отримуються з node під час виконання, тому оновлення, націлені на node, потрібно виконувати через `openclaw approvals --node ...` +- схвалення виконання на вузлі отримуються з вузла під час виконання, тому оновлення, націлені на вузол, потрібно робити через `openclaw approvals --node ...` -Скорочений варіант лише для сеансу: +Скорочення лише для сеансу: - `/exec security=full ask=off` змінює лише поточний сеанс. -- `/elevated full` — це аварійний скорочений варіант, який також пропускає підтвердження виконання для цього сеансу. +- `/elevated full` — це аварійне скорочення, яке також пропускає схвалення виконання для цього сеансу. -Якщо файл підтверджень хоста залишається суворішим за конфігурацію, все одно перемагає суворіша політика хоста. +Якщо файл схвалень хоста залишається суворішим за конфігурацію, усе одно застосовується суворіша політика хоста. -## Перемикачі політики +## Параметри політики -### Security (`exec.security`) +### Безпека (`exec.security`) - **deny**: блокувати всі запити на виконання на хості. -- **allowlist**: дозволяти лише команди зі списку дозволених елементів. +- **allowlist**: дозволяти лише команди зі списку дозволених дій. - **full**: дозволяти все (еквівалентно elevated). ### Ask (`exec.ask`) - **off**: ніколи не запитувати. -- **on-miss**: запитувати лише тоді, коли список дозволених елементів не збігається. +- **on-miss**: запитувати лише тоді, коли немає збігу зі списком дозволених дій. - **always**: запитувати для кожної команди. -- довготривала довіра `allow-always` не пригнічує запити, коли ефективний режим ask має значення `always` +- Тривала довіра `allow-always` не пригнічує запити, коли ефективний режим ask — `always` -### Ask fallback (`askFallback`) +### Резервний режим Ask (`askFallback`) -Якщо потрібне підтвердження, але жоден UI недосяжний, резервний режим визначає результат: +Якщо потрібен запит на схвалення, але UI недосяжний, резервний режим визначає дію: - **deny**: блокувати. -- **allowlist**: дозволяти лише за збігу зі списком дозволених елементів. +- **allowlist**: дозволяти лише за наявності збігу зі списком дозволених дій. - **full**: дозволяти. -### Посилений режим для inline eval в інтерпретаторах (`tools.exec.strictInlineEval`) +### Посилення для inline eval інтерпретатора (`tools.exec.strictInlineEval`) -Коли `tools.exec.strictInlineEval=true`, OpenClaw трактує форми inline code-eval як такі, що потребують лише явного підтвердження, навіть якщо сам бінарний файл інтерпретатора додано до списку дозволених елементів. +Коли `tools.exec.strictInlineEval=true`, OpenClaw розглядає форми inline code-eval як такі, що потребують окремого схвалення, навіть якщо сам виконуваний файл інтерпретатора є в allowlist. Приклади: @@ -226,15 +230,18 @@ EOF - `lua -e` - `osascript -e` -Це захист у глибину для завантажувачів інтерпретаторів, які не зіставляються однозначно з одним стабільним файловим операндом. У строгому режимі: +Це захист у глибину для завантажувачів інтерпретаторів, які не прив’язуються чисто до одного стабільного файлового операнда. У строгому режимі: -- ці команди все одно потребують явного підтвердження; -- `allow-always` не зберігає автоматично нові записи списку дозволених елементів для них. +- ці команди все одно потребують явного схвалення; +- `allow-always` не зберігає для них нові записи allowlist автоматично. -## Список дозволених елементів (для кожного агента) +## Список дозволених дій (для кожного агента) -Списки дозволених елементів є **окремими для кожного агента**. Якщо існує кілька агентів, перемкніть агента, який редагується, у застосунку для macOS. Шаблони — це **глоб-збіги без урахування регістру**. Шаблони мають вказувати на **шляхи до бінарних файлів** (записи лише з базовою назвою ігноруються). Застарілі записи `agents.default` мігрують у `agents.main` під час завантаження. -Shell-ланцюжки на кшталт `echo ok && pwd` однаково вимагають, щоб кожен сегмент верхнього рівня відповідав правилам списку дозволених елементів. +Списки дозволених дій є **окремими для кожного агента**. Якщо існує кілька агентів, перемкніть, якого агента ви +редагуєте, у застосунку macOS. Шаблони — це **нечутливі до регістру glob-збіги**. +Шаблони повинні розгортатися до **шляхів до двійкових файлів** (записи лише з базовою назвою ігноруються). +Застарілі записи `agents.default` під час завантаження мігрують до `agents.main`. +Ланцюжки shell, наприклад `echo ok && pwd`, усе одно вимагають, щоб кожен сегмент верхнього рівня відповідав правилам allowlist. Приклади: @@ -242,37 +249,37 @@ Shell-ланцюжки на кшталт `echo ok && pwd` однаково ви - `~/.local/bin/*` - `/opt/homebrew/bin/rg` -Кожен запис списку дозволених елементів відстежує: +Кожен запис allowlist відстежує: -- **id** — стабільний UUID для ідентичності в UI (необов’язково) -- **останнє використання** — часову позначку -- **остання використана команда** -- **останній визначений шлях** +- **id** — стабільний UUID, що використовується для ідентичності в UI (необов’язково) +- **last used** — мітка часу останнього використання +- **last used command** +- **last resolved path** ## Автодозвіл для CLI зі Skills Коли ввімкнено **Автодозвіл для CLI зі Skills**, виконувані файли, на які посилаються відомі Skills, -вважаються такими, що входять до списку дозволених елементів на nodes (macOS node або безголовий хост node). Для цього використовується -`skills.bins` через Gateway RPC, щоб отримати список бінарних файлів Skill. Вимкніть це, якщо вам потрібні суворі ручні списки дозволених елементів. +вважаються такими, що входять до allowlist на вузлах (macOS node або headless-хост вузла). Для цього використовується +`skills.bins` через Gateway RPC, щоб отримати список bin зі Skills. Вимкніть це, якщо вам потрібні суворі ручні allowlist. Важливі примітки щодо довіри: -- Це **неявний зручний список дозволених елементів**, окремий від ручних записів списку шляхів. -- Він призначений для середовищ довірених операторів, де Gateway і node перебувають в одній межі довіри. -- Якщо вам потрібна сувора явна довіра, залиште `autoAllowSkills: false` і використовуйте лише ручні записи списку дозволених шляхів. +- Це **неявний допоміжний allowlist**, окремий від ручних записів allowlist за шляхами. +- Він призначений для довірених операторських середовищ, де Gateway і вузол перебувають в одній межі довіри. +- Якщо вам потрібна сувора явна довіра, залишайте `autoAllowSkills: false` і використовуйте лише ручні записи allowlist за шляхами. -## Safe bins (лише stdin) +## Безпечні bin (лише stdin) -`tools.exec.safeBins` визначає невеликий список **бінарних файлів лише для stdin** (наприклад, -`cut`), які можуть працювати в режимі allowlist **без** явних записів у списку дозволених елементів. Safe bins відхиляють позиційні файлові аргументи та токени, схожі на шляхи, тож -вони можуть працювати лише з вхідним потоком. Сприймайте це як вузький швидкий шлях для +`tools.exec.safeBins` визначає невеликий список **двійкових файлів лише для stdin** (наприклад, `cut`), які можуть працювати в режимі allowlist **без** явних записів allowlist. +Безпечні bin відхиляють позиційні файлові аргументи й токени, схожі на шляхи, тому +можуть працювати лише з вхідним потоком. Розглядайте це як вузький швидкий шлях для потокових фільтрів, а не як загальний список довіри. -**Не** додавайте бінарні файли інтерпретаторів або середовищ виконання (наприклад `python3`, `node`, -`ruby`, `bash`, `sh`, `zsh`) до `safeBins`. Якщо команда може обчислювати код, -виконувати підкоманди або читати файли за своєю природою, надавайте перевагу явним записам у списку дозволених елементів -і залишайте запити на підтвердження ввімкненими. Користувацькі safe bins мають визначати явний +**Не** додавайте двійкові файли інтерпретаторів або середовищ виконання (наприклад, `python3`, `node`, +`ruby`, `bash`, `sh`, `zsh`) до `safeBins`. Якщо команда за своєю природою може обчислювати код, +виконувати підкоманди або читати файли, віддавайте перевагу явним записам allowlist +і залишайте запити на схвалення увімкненими. Користувацькі safe bins мають визначати явний профіль у `tools.exec.safeBinProfiles.`. @@ -284,291 +291,284 @@ Shell-ланцюжки на кшталт `echo ok && pwd` однаково ви [//]: # "SAFE_BIN_DEFAULTS:END" -`grep` і `sort` не входять до типового списку. Якщо ви явно вмикаєте їх, зберігайте явні -записи списку дозволених елементів для їхніх робочих сценаріїв, відмінних від stdin. Для `grep` у режимі safe-bin +`grep` і `sort` не входять до типового списку. Якщо ви явно їх увімкнете, залишайте явні +записи allowlist для їхніх сценаріїв, що не обмежуються stdin. Для `grep` у режимі safe-bin вказуйте шаблон через `-e`/`--regexp`; позиційна форма шаблону відхиляється, щоб файлові операнди не можна було приховано передати як неоднозначні позиційні аргументи. - - - Перевірка є детермінованою лише за формою argv (без перевірок існування - файлів у файловій системі хоста), що запобігає поведінці оракула існування файлів через відмінності між - дозволом і відмовою. Для типових safe bins файлово-орієнтовані параметри заборонені; довгі параметри перевіряються за принципом fail-closed (невідомі прапорці й неоднозначні скорочення відхиляються). +### Перевірка Argv і заборонені прапорці - Заборонені прапорці за профілем safe-bin: +Перевірка є детермінованою лише за формою argv (без перевірок наявності файлів у файловій системі хоста), +що запобігає поведінці файлового оракула через відмінності між allow/deny. +Параметри, орієнтовані на файли, для типових safe bins заборонені; довгі параметри перевіряються за принципом fail-closed (невідомі прапорці та неоднозначні скорочення +відхиляються). - [//]: # "SAFE_BIN_DENIED_FLAGS:START" +Заборонені прапорці за профілем safe-bin: + +[//]: # "SAFE_BIN_DENIED_FLAGS:START" - `grep`: `--dereference-recursive`, `--directories`, `--exclude-from`, `--file`, `--recursive`, `-R`, `-d`, `-f`, `-r` - `jq`: `--argfile`, `--from-file`, `--library-path`, `--rawfile`, `--slurpfile`, `-L`, `-f` - `sort`: `--compress-program`, `--files0-from`, `--output`, `--random-source`, `--temporary-directory`, `-T`, `-o` - `wc`: `--files0-from` - [//]: # "SAFE_BIN_DENIED_FLAGS:END" +[//]: # "SAFE_BIN_DENIED_FLAGS:END" - Safe bins також примусово трактують токени argv як **буквальний текст** під - час виконання (без globbing і без розгортання `$VARS`) для сегментів лише зі stdin, - тому шаблони на кшталт `*` або `$HOME/...` не можна використати для прихованого читання - файлів. +Safe bins також змушують обробляти токени argv як **буквальний текст** під час виконання +(без globbing і без розгортання `$VARS`) для сегментів лише зі stdin, тому шаблони +на кшталт `*` або `$HOME/...` не можна використати для прихованого читання файлів. - +### Довірені каталоги двійкових файлів - - Safe bins мають визначатися з довірених каталогів бінарних файлів (системні типові - значення плюс необов’язкові `tools.exec.safeBinTrustedDirs`). Записи `PATH` ніколи не - вважаються довіреними автоматично. Типові довірені каталоги навмисно мінімальні: - `/bin`, `/usr/bin`. Якщо ваш виконуваний файл safe-bin розташований у - шляхах менеджера пакетів/користувача (наприклад `/opt/homebrew/bin`, - `/usr/local/bin`, `/opt/local/bin`, `/snap/bin`), додайте їх явно до - `tools.exec.safeBinTrustedDirs`. - +Безпечні bin мають розгортатися з довірених каталогів двійкових файлів (системні типові значення плюс +необов’язковий `tools.exec.safeBinTrustedDirs`). Записи `PATH` ніколи не вважаються довіреними автоматично. +Типові довірені каталоги навмисно мінімальні: `/bin`, `/usr/bin`. Якщо +ваш виконуваний файл safe-bin знаходиться в шляхах менеджера пакетів/користувача (наприклад +`/opt/homebrew/bin`, `/usr/local/bin`, `/opt/local/bin`, `/snap/bin`), додайте їх +явно до `tools.exec.safeBinTrustedDirs`. - - Shell-ланцюжки (`&&`, `||`, `;`) дозволені, якщо кожен сегмент верхнього рівня - відповідає списку дозволених елементів - (включно з safe bins або автодозволом для Skills). - Перенаправлення в режимі allowlist, як і раніше, не підтримуються. Підстановка команд - (`$()` / зворотні лапки) відхиляється під час аналізу allowlist, зокрема всередині - подвійних лапок; використовуйте одинарні лапки, якщо вам потрібен буквальний текст `$()`. +### Ланцюжки shell, обгортки та мультиплексори - У підтвердженнях застосунку-компаньйона для macOS необроблений shell-текст, що містить shell-керування - або синтаксис розгортання (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, - `)`), вважається промахом allowlist, якщо сам shell-бінарний файл не входить до - списку дозволених елементів. +Ланцюжки shell (`&&`, `||`, `;`) дозволені, коли кожен сегмент верхнього рівня +відповідає allowlist (зокрема safe bins або автодозвіл для Skills). Переспрямування +залишаються непідтримуваними в режимі allowlist. Підстановка команд (`$()` / зворотні лапки) +відхиляється під час розбору allowlist, зокрема всередині подвійних лапок; використовуйте одинарні +лапки, якщо вам потрібен буквальний текст `$()`. - Для shell-обгорток (`bash|sh|zsh ... -c/-lc`) перевизначення env в межах запиту - зводяться до невеликого явного списку дозволених елементів (`TERM`, `LANG`, - `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). +У схваленнях companion app на macOS сирий текст shell, що містить керувальний або +розширювальний синтаксис shell (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`), +вважається промахом allowlist, якщо сам двійковий файл shell не входить до allowlist. - Для рішень `allow-always` у режимі allowlist відомі обгортки-диспетчери - (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) зберігають шлях внутрішнього виконуваного файла - замість шляху обгортки. Shell-мультиплексори (`busybox`, `toybox`) - так само розгортаються для shell-аплетів (`sh`, `ash` тощо). Якщо - обгортку або мультиплексор неможливо безпечно розгорнути, запис allowlist не зберігається автоматично. +Для обгорток shell (`bash|sh|zsh ... -c/-lc`) перевизначення env в межах запиту +зводяться до невеликого явного allowlist (`TERM`, `LANG`, `LC_*`, `COLORTERM`, +`NO_COLOR`, `FORCE_COLOR`). - Якщо ви додаєте до allowlist інтерпретатори на кшталт `python3` або `node`, краще - встановити `tools.exec.strictInlineEval=true`, щоб inline eval і далі вимагав - явного підтвердження. У строгому режимі `allow-always` усе ще може зберігати нешкідливі - виклики інтерпретатора/скрипта, але носії inline-eval автоматично не зберігаються. +Для рішень `allow-always` у режимі allowlist відомі обгортки-диспетчери (`env`, +`nice`, `nohup`, `stdbuf`, `timeout`) зберігають шлях до внутрішнього виконуваного файла +замість шляху до обгортки. Мультиплексори shell (`busybox`, `toybox`) розгортаються для +аплетів shell (`sh`, `ash` тощо) таким самим чином. Якщо обгортку або мультиплексор +не можна безпечно розгорнути, жоден запис allowlist не зберігається автоматично. - - +Якщо ви додаєте до allowlist інтерпретатори на кшталт `python3` або `node`, надавайте перевагу +`tools.exec.strictInlineEval=true`, щоб inline eval і далі вимагав явного +схвалення. У строгому режимі `allow-always` усе ще може зберігати нешкідливі +виклики інтерпретатора/скрипта, але носії inline-eval не зберігаються +автоматично. -### Safe bins порівняно зі списком allowlist +### Безпечні bin проти allowlist | Тема | `tools.exec.safeBins` | Allowlist (`exec-approvals.json`) | | ---------------- | ------------------------------------------------------ | ------------------------------------------------------------ | | Мета | Автодозвіл для вузьких stdin-фільтрів | Явна довіра до конкретних виконуваних файлів | -| Тип збігу | Ім’я виконуваного файла + політика argv safe-bin | Glob-шаблон шляху до визначеного виконуваного файла | -| Обсяг аргументів | Обмежений профілем safe-bin і правилами буквальних токенів | Лише збіг шляху; за аргументи в іншому відповідаєте ви | +| Тип збігу | Назва виконуваного файла + політика argv safe-bin | Glob-шаблон розгорнутого шляху виконуваного файла | +| Область аргументів | Обмежена профілем safe-bin і правилами буквальних токенів | Лише збіг шляху; аргументи в іншому — на вашій відповідальності | | Типові приклади | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, користувацькі CLI | | Найкраще використання | Низькоризикові текстові перетворення в конвеєрах | Будь-який інструмент із ширшою поведінкою або побічними ефектами | Розташування конфігурації: -- `safeBins` надходить із конфігурації (`tools.exec.safeBins` або `agents.list[].tools.exec.safeBins` для агента). -- `safeBinTrustedDirs` надходить із конфігурації (`tools.exec.safeBinTrustedDirs` або `agents.list[].tools.exec.safeBinTrustedDirs` для агента). -- `safeBinProfiles` надходить із конфігурації (`tools.exec.safeBinProfiles` або `agents.list[].tools.exec.safeBinProfiles` для агента). Ключі профілю для агента перевизначають глобальні ключі. -- записи allowlist зберігаються в локальному для хоста `~/.openclaw/exec-approvals.json` у `agents..allowlist` (або через Control UI / `openclaw approvals allowlist ...`). -- `openclaw security audit` попереджає за допомогою `tools.exec.safe_bins_interpreter_unprofiled`, коли бінарні файли інтерпретатора/середовища виконання з’являються в `safeBins` без явних профілів. -- `openclaw doctor --fix` може створити відсутні користувацькі записи `safeBinProfiles.` у вигляді `{}` (після цього перегляньте й посильте їх). Бінарні файли інтерпретатора/середовища виконання автоматично не створюються. +- `safeBins` надходить із конфігурації (`tools.exec.safeBins` або `agents.list[].tools.exec.safeBins` для окремого агента). +- `safeBinTrustedDirs` надходить із конфігурації (`tools.exec.safeBinTrustedDirs` або `agents.list[].tools.exec.safeBinTrustedDirs` для окремого агента). +- `safeBinProfiles` надходить із конфігурації (`tools.exec.safeBinProfiles` або `agents.list[].tools.exec.safeBinProfiles` для окремого агента). Ключі профілів для окремого агента мають пріоритет над глобальними ключами. +- записи allowlist зберігаються в локальному для хоста `~/.openclaw/exec-approvals.json` у `agents..allowlist` (або через UI Control / `openclaw approvals allowlist ...`). +- `openclaw security audit` попереджає через `tools.exec.safe_bins_interpreter_unprofiled`, коли двійкові файли інтерпретатора/середовища виконання з’являються в `safeBins` без явних профілів. +- `openclaw doctor --fix` може створити заготовки для відсутніх користувацьких записів `safeBinProfiles.` як `{}` (після цього перегляньте й посильте їх). Для двійкових файлів інтерпретатора/середовища виконання заготовки автоматично не створюються. Приклад користувацького профілю: __OC_I18N_900005__ -Якщо ви явно додаєте `jq` до `safeBins`, OpenClaw усе одно відхиляє вбудовану команду `env` у режимі safe-bin, +Якщо ви явно додаєте `jq` до `safeBins`, OpenClaw усе одно відхиляє builtin `env` у режимі safe-bin, щоб `jq -n env` не міг вивантажити середовище процесу хоста без явного шляху allowlist -або запиту на підтвердження. +або запиту на схвалення. -## Редагування в Control UI +## Редагування в UI Control -Використовуйте картку **Control UI → Nodes → Exec approvals**, щоб редагувати типові значення, перевизначення -для окремих агентів і списки allowlist. Виберіть область видимості (типові значення або агент), змініть політику, -додайте/видаліть шаблони allowlist, а потім натисніть **Save**. UI показує метадані **останнього використання** -для кожного шаблону, щоб список було зручно підтримувати в порядку. +Використовуйте картку **UI Control → Nodes → Exec approvals**, щоб редагувати типові значення, перевизначення для окремих агентів +і allowlist. Виберіть область (типові значення або агента), скоригуйте політику, +додайте/видаліть шаблони allowlist, а потім натисніть **Save**. UI показує метадані **last used** +для кожного шаблону, щоб список залишався впорядкованим. -Селектор цілі вибирає **Gateway** (локальні підтвердження) або **Node**. Nodes -мають оголошувати `system.execApprovals.get/set` (застосунок для macOS або безголовий хост node). -Якщо node ще не оголошує підтримку підтверджень виконання, редагуйте його локальний -`~/.openclaw/exec-approvals.json` безпосередньо. +Селектор цілі вибирає **Gateway** (локальні схвалення) або **Node**. Вузли +мають оголошувати `system.execApprovals.get/set` (застосунок macOS або headless-хост вузла). +Якщо вузол ще не оголошує схвалення виконання, відредагуйте його локальний +`~/.openclaw/exec-approvals.json` напряму. -CLI: `openclaw approvals` підтримує редагування для gateway або node (див. [CLI підтверджень](/cli/approvals)). +CLI: `openclaw approvals` підтримує редагування gateway або вузла (див. [CLI схвалень](/cli/approvals)). -## Потік підтвердження +## Потік схвалення -Коли потрібне підтвердження, gateway транслює `exec.approval.requested` клієнтам-операторам. -Control UI і застосунок для macOS обробляють це через `exec.approval.resolve`, після чого gateway пересилає -схвалений запит до хоста node. +Коли потрібен запит на схвалення, gateway транслює `exec.approval.requested` клієнтам операторів. +UI Control і застосунок macOS розв’язують його через `exec.approval.resolve`, а потім gateway пересилає +схвалений запит на хост вузла. -Для `host=node` запити на підтвердження включають канонічне корисне навантаження `systemRunPlan`. Gateway використовує +Для `host=node` запити на схвалення містять канонічне корисне навантаження `systemRunPlan`. Gateway використовує цей план як авторитетний контекст команди/cwd/сеансу під час пересилання схвалених запитів `system.run`. -Це важливо для затримки асинхронного підтвердження: +Це важливо для затримки асинхронного схвалення: -- шлях виконання node заздалегідь готує один канонічний план -- запис підтвердження зберігає цей план і його метадані прив’язки -- після схвалення остаточний пересланий виклик `system.run` повторно використовує збережений план, - замість того щоб довіряти пізнішим змінам викликача +- шлях виконання вузла готує один канонічний план наперед +- запис схвалення зберігає цей план і його метадані прив’язки +- після схвалення фінальний пересланий виклик `system.run` повторно використовує збережений план + замість довіри до пізніших змін викликача - якщо викликач змінює `command`, `rawCommand`, `cwd`, `agentId` або - `sessionKey` після створення запиту на підтвердження, gateway відхиляє - пересланий запуск як невідповідність підтвердженню + `sessionKey` після створення запиту на схвалення, gateway відхиляє + пересланий запуск як невідповідність схваленню ## Команди інтерпретатора/середовища виконання -Запуски інтерпретатора/середовища виконання, підкріплені підтвердженням, навмисно зроблено консервативними: +Запуски інтерпретатора/середовища виконання, підкріплені схваленням, навмисно є консервативними: -- Точний контекст argv/cwd/env завжди прив’язується. -- Форми прямого shell-скрипта і прямого файла середовища виконання прив’язуються за принципом максимально можливого наближення до одного конкретного - знімка локального файла. -- Поширені форми обгорток менеджерів пакетів, які все ще визначаються до одного прямого локального файла (наприклад +- Завжди прив’язуються точний контекст argv/cwd/env. +- Форми прямих shell-скриптів і прямих файлів середовища виконання прив’язуються за best-effort до одного конкретного локального + знімка файла. +- Типові форми обгорток менеджерів пакетів, які все ще розгортаються до одного прямого локального файла (наприклад `pnpm exec`, `pnpm node`, `npm exec`, `npx`), розгортаються перед прив’язкою. - Якщо OpenClaw не може визначити рівно один конкретний локальний файл для команди інтерпретатора/середовища виконання - (наприклад, для пакетних скриптів, форм eval, специфічних для середовища виконання ланцюжків завантаження або неоднозначних багатофайлових - форм), виконання, підкріплене підтвердженням, відхиляється замість того, щоб заявляти семантичне покриття, якого + (наприклад скрипти пакетів, форми eval, специфічні для середовища виконання ланцюжки завантаження або неоднозначні форми + з кількома файлами), виконання, підкріплене схваленням, відхиляється замість заяви про семантичне покриття, якого насправді немає. -- Для таких сценаріїв краще використовувати пісочницю, окрему межу хоста або явний довірений - процес allowlist/full, де оператор приймає ширшу семантику середовища виконання. +- Для таких сценаріїв надавайте перевагу пісочниці, окремій межі хоста або явному + довіреному процесу allowlist/full, де оператор приймає ширшу семантику середовища виконання. -Коли потрібні підтвердження, інструмент exec відразу повертає id підтвердження. Використовуйте цей id, щоб -зіставляти пізніші системні події (`Exec finished` / `Exec denied`). Якщо до завершення -тайм-ауту не надходить рішення, запит вважається тайм-аутом підтвердження і відображається як причина відмови. +Коли потрібні схвалення, інструмент exec одразу повертає ідентифікатор схвалення. Використовуйте цей ідентифікатор, щоб +співвідносити пізніші системні події (`Exec finished` / `Exec denied`). Якщо рішення не надходить до завершення +часу очікування, запит вважається тайм-аутом схвалення й відображається як причина відмови. ### Поведінка доставки подальших повідомлень -Після завершення схваленого асинхронного виконання OpenClaw надсилає подальший хід `agent` до того самого сеансу. +Після завершення схваленого асинхронного exec OpenClaw надсилає подальший хід `agent` у той самий сеанс. -- Якщо існує дійсна зовнішня ціль доставки (канал, який підтримує доставку, плюс ціль `to`), доставка подальших повідомлень використовує цей канал. -- У потоках лише webchat або внутрішнього сеансу без зовнішньої цілі доставка подальших повідомлень залишається лише в межах сеансу (`deliver: false`). -- Якщо викликач явно запитує сувору зовнішню доставку без зовнішнього каналу, який можна визначити, запит завершується помилкою `INVALID_REQUEST`. -- Якщо ввімкнено `bestEffortDeliver` і жоден зовнішній канал не вдається визначити, доставка знижується до лише-сеансової замість помилки. +- Якщо існує коректна зовнішня ціль доставки (канал доставки плюс ціль `to`), подальша доставка використовує цей канал. +- У потоках лише webchat або внутрішніх сеансів без зовнішньої цілі подальша доставка залишається лише в межах сеансу (`deliver: false`). +- Якщо викликач явно вимагає сувору зовнішню доставку без можливості розв’язати зовнішній канал, запит завершується помилкою `INVALID_REQUEST`. +- Якщо ввімкнено `bestEffortDeliver` і неможливо розв’язати жоден зовнішній канал, доставка знижується до режиму лише для сеансу замість помилки. Діалог підтвердження містить: - команду + аргументи - cwd - id агента -- визначений шлях до виконуваного файла -- хост + метадані політики +- розгорнутий шлях до виконуваного файла +- метадані хоста + політики Дії: -- **Allow once** → запустити зараз -- **Always allow** → додати до allowlist + запустити +- **Allow once** → виконати зараз +- **Always allow** → додати до allowlist + виконати - **Deny** → заблокувати -## Пересилання підтверджень до чат-каналів +## Пересилання схвалення до чат-каналів -Ви можете пересилати запити на підтвердження exec до будь-якого чат-каналу (включно з каналами Plugin) і схвалювати +Ви можете пересилати запити на схвалення exec до будь-якого чат-каналу (зокрема каналів Plugin) і схвалювати їх через `/approve`. Для цього використовується звичайний конвеєр вихідної доставки. Конфігурація: __OC_I18N_900006__ Відповідь у чаті: __OC_I18N_900007__ -Команда `/approve` обробляє як підтвердження exec, так і підтвердження Plugin. Якщо ID не збігається з очікуваним підтвердженням exec, вона автоматично перевіряє підтвердження Plugin. +Команда `/approve` обробляє і схвалення exec, і схвалення Plugin. Якщо ідентифікатор не відповідає жодному очікуваному схваленню exec, вона автоматично перевіряє схвалення Plugin. -### Пересилання підтверджень Plugin +### Пересилання схвалень Plugin -Пересилання підтверджень Plugin використовує той самий конвеєр доставки, що й підтвердження exec, але має власну +Пересилання схвалень Plugin використовує той самий конвеєр доставки, що й схвалення exec, але має власну незалежну конфігурацію в `approvals.plugin`. Увімкнення або вимкнення одного не впливає на інше. __OC_I18N_900008__ Форма конфігурації ідентична `approvals.exec`: `enabled`, `mode`, `agentFilter`, -`sessionFilter` і `targets` працюють так само. +`sessionFilter` і `targets` працюють однаково. -Канали, що підтримують спільні інтерактивні відповіді, відображають однакові кнопки підтвердження як для exec, так і для -підтверджень Plugin. Канали без спільного інтерактивного UI повертаються до звичайного тексту з інструкціями -`/approve`. +Канали, які підтримують спільні інтерактивні відповіді, відображають ті самі кнопки схвалення як для exec, так і для +схвалень Plugin. Канали без спільного інтерактивного UI повертаються до звичайного тексту з інструкціями `/approve`. -### Підтвердження в тому самому чаті на будь-якому каналі +### Схвалення в тому самому чаті на будь-якому каналі -Коли запит на підтвердження exec або Plugin походить із чат-поверхні, що підтримує доставку, цей самий чат -тепер типово може схвалити його через `/approve`. Це застосовується до таких каналів, як Slack, Matrix і -Microsoft Teams, на додачу до вже наявних потоків у Web UI та terminal UI. +Коли запит на схвалення exec або Plugin походить із чат-поверхні, придатної для доставки, цей самий чат +тепер типово може схвалювати його через `/approve`. Це застосовується до таких каналів, як Slack, Matrix і +Microsoft Teams, на додачу до вже наявних потоків Web UI і terminal UI. -Цей спільний шлях текстової команди використовує звичайну модель автентифікації каналу для цієї розмови. Якщо -початковий чат уже може надсилати команди й отримувати відповіді, для запитів на підтвердження більше не потрібен -окремий нативний адаптер доставки лише для того, щоб вони залишалися очікуваними. +Цей спільний шлях текстових команд використовує звичайну модель автентифікації каналу для цієї розмови. Якщо +чат-джерело вже може надсилати команди й отримувати відповіді, запити на схвалення більше не потребують +окремого нативного адаптера доставки лише для того, щоб залишатися в очікуванні. Discord і Telegram також підтримують `/approve` у тому самому чаті, але ці канали все ще використовують свій -визначений список затверджувачів для авторизації, навіть коли нативну доставку підтверджень вимкнено. +розв’язаний список схвалювачів для авторизації, навіть коли нативну доставку схвалень вимкнено. -Для Telegram та інших нативних клієнтів підтвердження, які викликають Gateway безпосередньо, -цей запасний механізм навмисно обмежено помилками типу «підтвердження не знайдено». Справжня -відмова/помилка підтвердження exec не повторюється мовчки як підтвердження Plugin. +Для Telegram та інших нативних клієнтів схвалення, які звертаються безпосередньо до Gateway, +цей запасний варіант навмисно обмежений помилками типу «схвалення не знайдено». Реальна +відмова/помилка схвалення exec не повторюється мовчки як схвалення Plugin. -### Нативна доставка підтверджень +### Нативна доставка схвалень -Деякі канали також можуть діяти як нативні клієнти підтвердження. Нативні клієнти додають DM для затверджувачів, fanout до початкового чату -та специфічний для каналу інтерактивний UX підтвердження поверх спільного потоку `/approve` +Деякі канали також можуть діяти як нативні клієнти схвалення. Нативні клієнти додають DM схвалювачам, fanout у чаті походження +та специфічний для каналу інтерактивний UX схвалення поверх спільного потоку `/approve` у тому самому чаті. -Коли доступні нативні картки/кнопки підтвердження, цей нативний UI є основним -шляхом, видимим агенту. Агент також не повинен дублювати звичайну чат-команду -`/approve`, якщо результат інструмента не вказує, що чат-підтвердження недоступні або -ручне підтвердження є єдиним шляхом, що залишився. +Коли доступні нативні картки/кнопки схвалення, цей нативний UI є основним +шляхом для агента. Агент також не повинен дублювати звичайну чат-команду +`/approve`, якщо тільки результат інструмента не вказує, що чат-схвалення недоступні або +ручне схвалення є єдиним шляхом, що залишився. Загальна модель: -- політика виконання на хості все одно визначає, чи потрібне підтвердження exec -- `approvals.exec` керує пересиланням запитів на підтвердження до інших чат-цілей -- `channels..execApprovals` керує тим, чи діє цей канал як нативний клієнт підтвердження +- політика виконання на хості все ще визначає, чи потрібне схвалення exec +- `approvals.exec` керує пересиланням запитів на схвалення до інших цілей чату +- `channels..execApprovals` керує тим, чи діє цей канал як нативний клієнт схвалення -Нативні клієнти підтвердження автоматично вмикають доставку спочатку в DM, коли всі наведені умови істинні: +Нативні клієнти схвалення автоматично вмикають доставку спочатку в DM, коли всі наведені умови істинні: -- канал підтримує нативну доставку підтверджень -- затверджувачів можна визначити з явних `execApprovals.approvers` або з документованих резервних джерел цього - каналу -- `channels..execApprovals.enabled` не встановлено або має значення `"auto"` +- канал підтримує нативну доставку схвалень +- схвалювачів можна розв’язати з явних `execApprovals.approvers` або з + документованих резервних джерел цього каналу +- `channels..execApprovals.enabled` не задано або дорівнює `"auto"` -Установіть `enabled: false`, щоб явно вимкнути нативний клієнт підтвердження. Установіть `enabled: true`, щоб примусово -увімкнути його, коли затверджувачі визначаються. Публічна доставка до початкового чату й надалі явно керується через +Установіть `enabled: false`, щоб явно вимкнути нативний клієнт схвалення. Установіть `enabled: true`, щоб примусово +увімкнути його, коли схвалювачів вдається розв’язати. Публічна доставка в чаті походження залишається явною через `channels..execApprovals.target`. -FAQ: [Чому для підтверджень exec у чаті є дві конфігурації?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals) +FAQ: [Чому для чат-схвалень існують дві конфігурації схвалення exec?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals) - Discord: `channels.discord.execApprovals.*` - Slack: `channels.slack.execApprovals.*` - Telegram: `channels.telegram.execApprovals.*` -Ці нативні клієнти підтвердження додають маршрутизацію в DM і необов’язковий fanout до каналу поверх спільного -потоку `/approve` у тому самому чаті та спільних кнопок підтвердження. +Ці нативні клієнти схвалення додають маршрутизацію в DM і необов’язковий fanout у каналі поверх спільного +потоку `/approve` у тому самому чаті та спільних кнопок схвалення. Спільна поведінка: -- Slack, Matrix, Microsoft Teams та подібні чати з підтримкою доставки використовують звичайну модель автентифікації каналу +- Slack, Matrix, Microsoft Teams та подібні чати з доставкою використовують звичайну модель автентифікації каналу для `/approve` у тому самому чаті -- коли нативний клієнт підтвердження вмикається автоматично, типовою нативною ціллю доставки є DM затверджувачів -- для Discord і Telegram лише визначені затверджувачі можуть схвалювати або відхиляти -- затверджувачі Discord можуть бути явними (`execApprovals.approvers`) або виводитися з `commands.ownerAllowFrom` -- затверджувачі Telegram можуть бути явними (`execApprovals.approvers`) або виводитися з наявної конфігурації власника (`allowFrom`, плюс `defaultTo` для direct-message, де це підтримується) -- затверджувачі Slack можуть бути явними (`execApprovals.approvers`) або виводитися з `commands.ownerAllowFrom` -- нативні кнопки Slack зберігають тип id підтвердження, тому id `plugin:` можуть визначати підтвердження Plugin - без другого локального для Slack резервного шару -- нативна маршрутизація Matrix у DM/канал і швидкі реакції обробляють як підтвердження exec, так і Plugin; - авторизація Plugin і далі надходить із `channels.matrix.dm.allowFrom` -- запитувач не обов’язково має бути затверджувачем -- початковий чат може підтвердити запит безпосередньо через `/approve`, коли цей чат уже підтримує команди та відповіді -- нативні кнопки підтвердження Discord маршрутизують за типом id підтвердження: id `plugin:` переходять - безпосередньо до підтверджень Plugin, усе інше — до підтверджень exec -- нативні кнопки підтвердження Telegram дотримуються того самого обмеженого резервного переходу від exec до Plugin, що й `/approve` -- коли нативний `target` вмикає доставку до початкового чату, запити на підтвердження включають текст команди -- очікувані підтвердження exec типово спливають через 30 хвилин -- якщо жоден UI оператора або налаштований клієнт підтвердження не може прийняти запит, підтвердження переходить до `askFallback` +- коли нативний клієнт схвалення вмикається автоматично, типовою ціллю нативної доставки є DM схвалювачів +- для Discord і Telegram лише розв’язані схвалювачі можуть схвалювати або відхиляти +- схвалювачі Discord можуть бути явними (`execApprovals.approvers`) або виводитися з `commands.ownerAllowFrom` +- схвалювачі Telegram можуть бути явними (`execApprovals.approvers`) або виводитися з наявної конфігурації owner (`allowFrom`, а також `defaultTo` для direct-message, де це підтримується) +- схвалювачі Slack можуть бути явними (`execApprovals.approvers`) або виводитися з `commands.ownerAllowFrom` +- нативні кнопки Slack зберігають тип id схвалення, тому id `plugin:` можуть розв’язувати схвалення Plugin + без другого локального для Slack резервного рівня +- нативна маршрутизація DM/каналу й скорочення через реакції в Matrix обробляють і exec, і схвалення Plugin; + авторизація Plugin усе ще надходить із `channels.matrix.dm.allowFrom` +- запитувач не обов’язково має бути схвалювачем +- чат походження може схвалити запит безпосередньо через `/approve`, якщо цей чат уже підтримує команди й відповіді +- нативні кнопки схвалення Discord маршрутизують за типом id схвалення: id `plugin:` переходять + безпосередньо до схвалень Plugin, усе інше переходить до схвалень exec +- нативні кнопки схвалення Telegram дотримуються того самого обмеженого резервного переходу з exec до Plugin, що й `/approve` +- коли нативний `target` вмикає доставку в чат походження, запити на схвалення містять текст команди +- очікувані схвалення exec типово спливають через 30 хвилин +- якщо жоден UI оператора або налаштований клієнт схвалення не може прийняти запит, запит переходить до `askFallback` -Для Telegram типовим є DM затверджувачів (`target: "dm"`). Ви можете переключитися на `channel` або `both`, якщо -хочете, щоб запити на підтвердження також з’являлися в початковому чаті/темі Telegram. Для тем форуму Telegram -OpenClaw зберігає тему для запиту на підтвердження і подальшого повідомлення після підтвердження. +Telegram типово використовує DM схвалювачів (`target: "dm"`). Ви можете перемкнути на `channel` або `both`, коли +хочете, щоб запити на схвалення також з’являлися в початковому чаті/темі Telegram. Для тем форуму Telegram +OpenClaw зберігає тему для запиту на схвалення та подальшого повідомлення після схвалення. -Дивіться: +Див. також: - [Discord](/channels/discord) - [Telegram](/channels/telegram) -### Потік IPC у macOS +### Потік IPC на macOS __OC_I18N_900009__ Примітки щодо безпеки: -- Режим Unix socket `0600`, токен зберігається в `exec-approvals.json`. -- Перевірка однотипного UID. +- Режим Unix socket `0600`, token зберігається в `exec-approvals.json`. +- Перевірка однотипного UID вузла. - Challenge/response (nonce + HMAC token + hash запиту) + короткий TTL. ## Системні події @@ -579,34 +579,34 @@ __OC_I18N_900009__ - `Exec finished` - `Exec denied` -Вони публікуються в сеансі агента після того, як node повідомляє про подію. -Підтвердження exec на хості gateway генерують ті самі події життєвого циклу, коли команда завершується (і, за потреби, під час виконання довше за поріг). -Exec, які проходять через підтвердження, повторно використовують id підтвердження як `runId` у цих повідомленнях для зручного зіставлення. +Вони публікуються в сеанс агента після того, як вузол повідомляє про подію. +Схвалення виконання для хоста gateway генерують ті самі події життєвого циклу, коли команда завершується (і, за потреби, коли виконується довше за поріг). +Exec із контролем схвалення повторно використовують id схвалення як `runId` у цих повідомленнях для зручної кореляції. -## Поведінка при відхиленні підтвердження +## Поведінка у разі відхиленого схвалення -Коли асинхронне підтвердження exec відхиляється, OpenClaw не дозволяє агенту повторно використовувати +Коли асинхронне схвалення exec відхиляється, OpenClaw не дозволяє агенту повторно використовувати вивід будь-якого попереднього запуску тієї самої команди в межах сеансу. Причина відмови -передається з явною вказівкою, що жодного виводу команди немає, що зупиняє -агента від заяв про новий вивід або повторення відхиленої команди зі +передається з явною вказівкою, що вивід команди недоступний, що не дає +агенту стверджувати, ніби новий вивід існує, або повторювати відхилену команду зі застарілими результатами попереднього успішного запуску. ## Наслідки -- **full** має широкі повноваження; де можливо, віддавайте перевагу allowlist. -- **ask** тримає вас у контурі, водночас дозволяючи швидкі підтвердження. -- Списки allowlist для окремих агентів не дають підтвердженням одного агента просочуватися до інших. -- Підтвердження застосовуються лише до запитів host exec від **авторизованих відправників**. Неавторизовані відправники не можуть викликати `/exec`. -- `/exec security=full` — це зручний варіант на рівні сеансу для авторизованих операторів, який навмисно пропускає підтвердження. Щоб жорстко заблокувати host exec, установіть для security підтверджень значення `deny` або забороніть інструмент `exec` через політику інструментів. +- **full** має широкі можливості; за можливості віддавайте перевагу allowlist. +- **ask** залишає вас у циклі ухвалення рішень, водночас дозволяючи швидкі схвалення. +- Окремі allowlist для кожного агента запобігають витоку схвалень одного агента до інших. +- Схвалення застосовуються лише до запитів host exec від **авторизованих відправників**. Неавторизовані відправники не можуть виконувати `/exec`. +- `/exec security=full` — це зручність на рівні сеансу для авторизованих операторів, яка навмисно пропускає схвалення. Щоб жорстко заблокувати host exec, установіть для схвалень безпеку `deny` або забороніть інструмент `exec` через політику інструментів. ## Пов’язане - + Інструмент виконання shell-команд. - Аварійний шлях, який також пропускає підтвердження. + Аварійний шлях, який також пропускає схвалення. Режими пісочниці та доступ до робочого простору. @@ -615,7 +615,7 @@ Exec, які проходять через підтвердження, повт Модель безпеки та посилення захисту. - Коли слід використовувати кожен із цих механізмів керування. + Коли варто використовувати кожен із цих механізмів контролю. Поведінка автодозволу на основі Skills.