diff --git a/docs/uk/channels/channel-routing.md b/docs/uk/channels/channel-routing.md index 786c183f8..a9b991240 100644 --- a/docs/uk/channels/channel-routing.md +++ b/docs/uk/channels/channel-routing.md @@ -1,13 +1,13 @@ --- read_when: - - Зміна маршрутизації каналів або поведінки вхідних повідомлень + - Зміна маршрутизації каналу або поведінки вхідних повідомлень summary: Правила маршрутизації для кожного каналу (WhatsApp, Telegram, Discord, Slack) і спільний контекст -title: Маршрутизація каналів +title: Маршрутизація каналу x-i18n: - generated_at: "2026-04-05T17:57:18Z" + generated_at: "2026-04-22T22:50:17Z" model: gpt-5.4 provider: openai - source_hash: 63916c4dd0af5fc9bbd12581a9eb15fea14a380c5ade09323ca0c237db61e537 + source_hash: 3296ab8428cb815d0cc297d0c6e7479c5554ec45e1d90eef89a68833f5979d8d source_path: channels/channel-routing.md workflow: 15 --- @@ -19,26 +19,30 @@ OpenClaw маршрутизує відповіді **назад до канал ## Ключові терміни - **Канал**: `telegram`, `whatsapp`, `discord`, `irc`, `googlechat`, `slack`, `signal`, `imessage`, `line`, а також канали розширень. `webchat` — це внутрішній канал інтерфейсу WebChat і не є налаштовуваним вихідним каналом. -- **AccountId**: екземпляр облікового запису для каналу (коли підтримується). -- Необов’язковий типовий обліковий запис каналу: `channels..defaultAccount` визначає, який обліковий запис використовується, коли вихідний шлях не задає `accountId`. - - У конфігураціях із кількома обліковими записами задайте явний типовий обліковий запис (`defaultAccount` або `accounts.default`), коли налаштовано два або більше облікових записів. Без цього резервна маршрутизація може вибрати перший нормалізований ідентифікатор облікового запису. -- **AgentId**: ізольований робочий простір + сховище сесій («мозок»). -- **SessionKey**: ключ контейнера, який використовується для збереження контексту та керування паралельністю. +- **AccountId**: екземпляр облікового запису для каналу (якщо підтримується). +- Необов’язковий обліковий запис каналу за замовчуванням: `channels..defaultAccount` визначає, який обліковий запис використовується, коли вихідний шлях не вказує `accountId`. + - У конфігураціях із кількома обліковими записами встановіть явне значення за замовчуванням (`defaultAccount` або `accounts.default`), коли налаштовано два або більше облікових записів. Без цього резервна маршрутизація може вибрати перший нормалізований ідентифікатор облікового запису. +- **AgentId**: ізольоване робоче середовище + сховище сесій («мозок»). +- **SessionKey**: ключ бакета, який використовується для зберігання контексту та керування конкурентністю. -## Форми ключів сесії (приклади) +## Форми ключів сесій (приклади) -Особисті повідомлення згортаються до **основної** сесії агента: +Більшість прямих повідомлень зводяться до **основної** сесії агента: -- `agent::` (типово: `agent:main:main`) +- `agent::` (за замовчуванням: `agent:main:main`) -Групи та канали залишаються ізольованими для кожного каналу: +Прямі повідомлення Telegram-бота ізолюються за обліковим записом бота та відправником, навіть коли `session.dmScope` дорівнює `main`, щоб рішення щодо sandbox і політики інструментів могли розрізняти DM, що походять із каналу, від основної сесії агента: + +- `agent::telegram::direct:` + +Групи й канали залишаються ізольованими для кожного каналу: - Групи: `agent:::group:` - Канали/кімнати: `agent:::channel:` -Треди: +Потоки: -- Треди Slack/Discord додають `:thread:` до базового ключа. +- Потоки Slack/Discord додають `:thread:` до базового ключа. - Теми форуму Telegram вбудовують `:topic:` у ключ групи. Приклади: @@ -46,15 +50,15 @@ OpenClaw маршрутизує відповіді **назад до канал - `agent:main:telegram:group:-1001234567890:topic:42` - `agent:main:discord:channel:123456:thread:987654` -## Закріплення основного маршруту особистих повідомлень +## Закріплення маршруту основних DM -Коли `session.dmScope` має значення `main`, особисті повідомлення можуть використовувати спільну основну сесію. -Щоб `lastRoute` сесії не перезаписувався особистими повідомленнями не від власника, -OpenClaw визначає закріпленого власника з `allowFrom`, якщо виконуються всі ці умови: +Коли `session.dmScope` дорівнює `main`, прямі повідомлення можуть використовувати одну спільну основну сесію. +Щоб запобігти перезапису `lastRoute` сесії прямими повідомленнями від не-власника, +OpenClaw визначає закріпленого власника з `allowFrom`, якщо виконуються всі такі умови: -- `allowFrom` має рівно один запис без wildcard. -- Цей запис можна нормалізувати до конкретного ідентифікатора відправника для цього каналу. -- Відправник вхідного особистого повідомлення не збігається з цим закріпленим власником. +- `allowFrom` містить рівно один запис без wildcard. +- Запис можна нормалізувати до конкретного ID відправника для цього каналу. +- Відправник вхідного DM не збігається з цим закріпленим власником. У разі такої невідповідності OpenClaw усе одно записує метадані вхідної сесії, але пропускає оновлення `lastRoute` основної сесії. @@ -63,22 +67,22 @@ OpenClaw визначає закріпленого власника з `allowFro Маршрутизація вибирає **одного агента** для кожного вхідного повідомлення: -1. **Точний збіг вузла** (`bindings` з `peer.kind` + `peer.id`). -2. **Збіг батьківського вузла** (успадкування треду). -3. **Збіг сервера + ролей** (Discord) через `guildId` + `roles`. -4. **Збіг сервера** (Discord) через `guildId`. -5. **Збіг команди** (Slack) через `teamId`. +1. **Точний збіг peer** (`bindings` з `peer.kind` + `peer.id`). +2. **Збіг батьківського peer** (успадкування потоку). +3. **Збіг guild + ролей** (Discord) через `guildId` + `roles`. +4. **Збіг guild** (Discord) через `guildId`. +5. **Збіг team** (Slack) через `teamId`. 6. **Збіг облікового запису** (`accountId` у каналі). 7. **Збіг каналу** (будь-який обліковий запис у цьому каналі, `accountId: "*"`). -8. **Типовий агент** (`agents.list[].default`, інакше перший запис списку, резервно — `main`). +8. **Агент за замовчуванням** (`agents.list[].default`, інакше перший запис у списку, резервно — `main`). -Коли прив’язка містить кілька полів збігу (`peer`, `guildId`, `teamId`, `roles`), **усі вказані поля мають збігатися**, щоб ця прив’язка застосувалася. +Коли binding містить кілька полів збігу (`peer`, `guildId`, `teamId`, `roles`), **усі надані поля мають збігатися**, щоб цей binding було застосовано. -Вибраний агент визначає, який робочий простір і сховище сесій використовуються. +Вибраний агент визначає, яке робоче середовище та сховище сесій використовуються. -## Broadcast groups (запуск кількох агентів) +## Групи широкомовлення (запуск кількох агентів) -Broadcast groups дають змогу запускати **кількох агентів** для одного й того самого вузла **коли OpenClaw зазвичай відповідає** (наприклад, у групах WhatsApp після проходження згадки/активаційного шлюзу). +Групи широкомовлення дають змогу запускати **кількох агентів** для одного й того самого peer **коли OpenClaw зазвичай відповідав би** (наприклад, у групах WhatsApp після згадки/активаційного фільтра). Конфігурація: @@ -92,19 +96,19 @@ Broadcast groups дають змогу запускати **кількох аг } ``` -Див.: [Broadcast Groups](/channels/broadcast-groups). +Див.: [Групи широкомовлення](/uk/channels/broadcast-groups). ## Огляд конфігурації -- `agents.list`: іменовані визначення агентів (робочий простір, модель тощо). -- `bindings`: зіставлення вхідних каналів/облікових записів/вузлів з агентами. +- `agents.list`: іменовані визначення агентів (робоче середовище, модель тощо). +- `bindings`: зіставляє вхідні канали/облікові записи/peer з агентами. Приклад: ```json5 { agents: { - list: [{ id: "support", name: "Support", workspace: "~/.openclaw/workspace-support" }], + list: [{ id: "support", name: "Підтримка", workspace: "~/.openclaw/workspace-support" }], }, bindings: [ { match: { channel: "slack", teamId: "T123" }, agentId: "support" }, @@ -115,29 +119,29 @@ Broadcast groups дають змогу запускати **кількох аг ## Зберігання сесій -Сховища сесій розміщуються в каталозі стану (типово `~/.openclaw`): +Сховища сесій розміщуються в каталозі стану (за замовчуванням `~/.openclaw`): - `~/.openclaw/agents//sessions/sessions.json` -- Транскрипти JSONL розміщуються поруч зі сховищем +- JSONL-транскрипти зберігаються поруч зі сховищем Ви можете перевизначити шлях до сховища через `session.store` і шаблонізацію `{agentId}`. -Виявлення сесій Gateway і ACP також сканує дискові сховища агентів у типовому -корені `agents/` і в коренях `session.store`, побудованих за шаблоном. Виявлені -сховища мають залишатися в межах цього обчисленого кореня агента та використовувати звичайний файл -`sessions.json`. Символічні посилання та шляхи поза коренем ігноруються. +Gateway та ACP під час виявлення сесій також сканують дискові сховища агентів під +коренем `agents/` за замовчуванням і під коренями `session.store` з шаблонами. Виявлені +сховища мають залишатися в межах цього обчисленого кореня агента й використовувати звичайний +файл `sessions.json`. Символічні посилання та шляхи поза коренем ігноруються. ## Поведінка WebChat -WebChat підключається до **вибраного агента** і типово використовує основну -сесію агента. Через це WebChat дає змогу бачити міжканальний контекст для цього -агента в одному місці. +WebChat прив’язується до **вибраного агента** і за замовчуванням використовує +основну сесію агента. Завдяки цьому WebChat дає змогу бачити міжканальний контекст +для цього агента в одному місці. ## Контекст відповіді -Вхідні відповіді включають: +Вхідні відповіді містять: -- `ReplyToId`, `ReplyToBody` і `ReplyToSender`, коли доступні. +- `ReplyToId`, `ReplyToBody` і `ReplyToSender`, якщо доступні. - Цитований контекст додається до `Body` як блок `[Replying to ...]`. Це узгоджено в усіх каналах. diff --git a/docs/uk/channels/telegram.md b/docs/uk/channels/telegram.md index ec639299f..d88ecc945 100644 --- a/docs/uk/channels/telegram.md +++ b/docs/uk/channels/telegram.md @@ -1,30 +1,30 @@ --- read_when: - - Робота над функціями Telegram або Webhook-ами -summary: Статус підтримки бота Telegram, можливості та конфігурація + - Робота з функціями Telegram або Webhook +summary: Статус підтримки Telegram-бота, можливості та конфігурація title: Telegram x-i18n: - generated_at: "2026-04-21T20:37:36Z" + generated_at: "2026-04-22T22:50:18Z" model: gpt-5.4 provider: openai - source_hash: 1575c4e5e932a4a6330d57fa0d1639336aecdb8fa70d37d92dccd0d466d2fccb + source_hash: 76ce8e1a588a0666501c907ced9e54de12add0255dfbbd9a3487cc8b630e870f source_path: channels/telegram.md workflow: 15 --- # Telegram (Bot API) -Статус: готовий до використання у продакшені для DM бота + груп через grammY. Long polling — режим за замовчуванням; режим Webhook-ів — необов’язковий. +Статус: готовий до production для DM ботів і груп через grammY. Довге опитування є режимом за замовчуванням; режим Webhook є необов’язковим. - - Типова політика DM для Telegram — підключення. + + Типова політика DM для Telegram — зв’язування. - - Міжканальні діагностичні та відновлювальні сценарії. + + Міжканальна діагностика та сценарії відновлення. - Повні шаблони та приклади конфігурації каналу. + Повні шаблони та приклади конфігурації каналів. @@ -32,9 +32,9 @@ x-i18n: - Відкрийте Telegram і почніть чат з **@BotFather** (переконайтеся, що handle точно `@BotFather`). + Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що хендл точно `@BotFather`). - Виконайте `/newbot`, дотримуйтеся підказок і збережіть токен. + Виконайте `/newbot`, дотримуйтесь підказок і збережіть токен. @@ -53,8 +53,8 @@ x-i18n: } ``` - Резервний варіант через env: `TELEGRAM_BOT_TOKEN=...` (лише для облікового запису за замовчуванням). - Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, потім запустіть gateway. + Резервне значення через змінну середовища: `TELEGRAM_BOT_TOKEN=...` (лише для типового облікового запису). + Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, а потім запустіть gateway. @@ -66,7 +66,7 @@ openclaw pairing list telegram openclaw pairing approve telegram ``` - Коди підключення дійсні протягом 1 години. + Коди зв’язування дійсні протягом 1 години. @@ -76,28 +76,35 @@ openclaw pairing approve telegram -Порядок визначення токена залежить від облікового запису. На практиці значення з config мають пріоритет над резервним варіантом з env, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням. +Порядок визначення токена враховує обліковий запис. На практиці значення з config мають пріоритет над резервним значенням із середовища, а `TELEGRAM_BOT_TOKEN` застосовується лише до типового облікового запису. -## Налаштування з боку Telegram +## Ізоляція сесій + +DM Telegram-бота використовують ключі сесій відправника для кожного облікового запису, наприклад +`agent:main:telegram:default:direct:814912386`. Це зберігає окрему політику інструментів і sandbox для Telegram-походження +від основної сесії агента, навіть коли глобальне +налаштування `session.dmScope` має значення `main`. + +## Налаштування на боці Telegram - - Для ботів Telegram за замовчуванням увімкнено **Privacy Mode**, який обмежує повідомлення групи, що вони отримують. + + Для ботів Telegram за замовчуванням увімкнено **Privacy Mode**, що обмежує, які повідомлення в групах вони отримують. - Якщо бот має бачити всі повідомлення групи, зробіть одне з такого: + Якщо бот має бачити всі повідомлення в групі, зробіть одне з такого: - - вимкніть режим конфіденційності через `/setprivacy`, або + - вимкніть режим приватності через `/setprivacy`, або - зробіть бота адміністратором групи. - Після перемикання режиму конфіденційності видаліть бота з кожної групи й додайте знову, щоб Telegram застосував зміну. + Після перемикання режиму приватності видаліть бота й додайте його знову в кожній групі, щоб Telegram застосував зміну. - + Статус адміністратора керується в налаштуваннях групи Telegram. - Боти-адміністратори отримують усі повідомлення групи, що корисно для постійно активної поведінки в групі. + Боти-адміністратори отримують усі повідомлення в групі, що корисно для постійно активної поведінки в групі. @@ -109,28 +116,28 @@ openclaw pairing approve telegram -## Керування доступом і активація +## Контроль доступу та активація `channels.telegram.dmPolicy` керує доступом до прямих повідомлень: - `pairing` (за замовчуванням) - - `allowlist` (потребує принаймні одного ID відправника в `allowFrom`) - - `open` (потребує, щоб `allowFrom` містив `"*"`) + - `allowlist` (потрібен щонайменше один ID відправника в `allowFrom`) + - `open` (потрібно, щоб `allowFrom` містив `"*"`) - `disabled` - `channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` приймаються й нормалізуються. - `dmPolicy: "allowlist"` з порожнім `allowFrom` блокує всі DM і відхиляється перевіркою config. - Під час налаштування запитуються лише числові ID користувачів. - Якщо ви оновилися і ваш config містить записи allowlist у форматі `@username`, виконайте `openclaw doctor --fix`, щоб їх виправити (у режимі best-effort; потрібен токен бота Telegram). - Якщо ви раніше покладалися на файли allowlist зі сховища pairing-store, `openclaw doctor --fix` може відновити записи до `channels.telegram.allowFrom` у сценаріях allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID). + `channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` приймаються та нормалізуються. + `dmPolicy: "allowlist"` із порожнім `allowFrom` блокує всі DM і відхиляється перевіркою config. + Налаштування запитує лише числові ID користувачів. + Якщо ви оновилися і ваш config містить записи allowlist у вигляді `@username`, виконайте `openclaw doctor --fix`, щоб їх розв’язати (best-effort; потрібен токен Telegram-бота). + Якщо ви раніше покладалися на файли allowlist зі сховища зв’язування, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у сценаріях allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID). - Для ботів з одним власником віддавайте перевагу `dmPolicy: "allowlist"` із явними числовими ID у `allowFrom`, щоб політика доступу надійно зберігалася в config (замість залежності від попередніх схвалень підключення). + Для ботів з одним власником віддавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID в `allowFrom`, щоб політика доступу надійно зберігалася в config (замість залежності від попередніх схвалень зв’язування). - Типова плутанина: схвалення підключення для DM не означає, що «цей відправник авторизований всюди». - Підключення надає доступ лише до DM. Авторизація відправника в групах, як і раніше, визначається явними allowlist у config. - Якщо ви хочете, щоб «я авторизувався один раз, і працювали і DM, і команди в групі», додайте свій числовий ID користувача Telegram до `channels.telegram.allowFrom`. + Поширена плутанина: схвалення DM-зв’язування не означає, що «цей відправник авторизований скрізь». + Зв’язування надає доступ лише до DM. Авторизація відправників у групах усе ще походить із явних allowlist у config. + Якщо ви хочете, щоб «я був авторизований один раз і працювали і DM, і команди в групі», додайте свій числовий ID користувача Telegram до `channels.telegram.allowFrom`. ### Як знайти свій ID користувача Telegram @@ -138,25 +145,25 @@ openclaw pairing approve telegram 1. Надішліть DM своєму боту. 2. Виконайте `openclaw logs --follow`. - 3. Прочитайте `from.id`. + 3. Зчитайте `from.id`. - Офіційний метод через Bot API: + Офіційний метод Bot API: ```bash curl "https://api.telegram.org/bot/getUpdates" ``` - Сторонній спосіб (менш приватний): `@userinfobot` або `@getidsbot`. + Сторонній метод (менш приватний): `@userinfobot` або `@getidsbot`. - Разом застосовуються два механізми: + Разом застосовуються два механізми контролю: 1. **Які групи дозволені** (`channels.telegram.groups`) - немає config `groups`: - - з `groupPolicy: "open"`: будь-яка група може пройти перевірку ID групи - - з `groupPolicy: "allowlist"` (за замовчуванням): групи блокуються, доки ви не додасте записи до `groups` (або `"*"`) + - з `groupPolicy: "open"`: будь-яка група може пройти перевірки ID групи + - з `groupPolicy: "allowlist"` (за замовчуванням): групи блокуються, доки ви не додасте записи в `groups` (або `"*"`) - `groups` налаштовано: працює як allowlist (явні ID або `"*"`) 2. **Які відправники дозволені в групах** (`channels.telegram.groupPolicy`) @@ -164,17 +171,17 @@ curl "https://api.telegram.org/bot/getUpdates" - `allowlist` (за замовчуванням) - `disabled` - `groupAllowFrom` використовується для фільтрації відправників у групах. Якщо його не задано, Telegram використовує `allowFrom`. + `groupAllowFrom` використовується для фільтрації відправників у групах. Якщо не вказано, Telegram використовує `allowFrom` як резервне значення. Записи `groupAllowFrom` мають бути числовими ID користувачів Telegram (`telegram:` / `tg:` префікси нормалізуються). - Не вказуйте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Від’ємні ID чатів слід вказувати в `channels.telegram.groups`. - Нечислові записи ігноруються під час авторизації відправника. - Межа безпеки (`2026.2.25+`): авторизація відправника в групі **не** успадковує схвалення зі сховища pairing-store для DM. - Підключення залишається лише для DM. Для груп налаштуйте `groupAllowFrom` або `allowFrom` для конкретної групи/теми. - Якщо `groupAllowFrom` не задано, Telegram використовує config `allowFrom`, а не pairing store. - Практичний шаблон для ботів з одним власником: вкажіть свій ID користувача в `channels.telegram.allowFrom`, не задавайте `groupAllowFrom`, і дозвольте цільові групи в `channels.telegram.groups`. - Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням використовує fail-closed `groupPolicy="allowlist"`, якщо тільки `channels.defaults.groupPolicy` не задано явно. + Не вказуйте ID Telegram-груп або супергруп у `groupAllowFrom`. Від’ємні ID чатів мають бути в `channels.telegram.groups`. + Нечислові записи ігноруються для авторизації відправників. + Межа безпеки (`2026.2.25+`): авторизація відправників у групах **не** успадковує схвалення зі сховища DM-зв’язування. + Зв’язування лишається лише для DM. Для груп налаштуйте `groupAllowFrom` або `allowFrom` на рівні групи/теми. + Якщо `groupAllowFrom` не задано, Telegram використовує резервне значення з config `allowFrom`, а не сховище зв’язування. + Практичний шаблон для ботів з одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, не задавайте `groupAllowFrom`, і дозвольте цільові групи в `channels.telegram.groups`. + Примітка про runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням використовує fail-closed `groupPolicy="allowlist"`, якщо тільки `channels.defaults.groupPolicy` не задано явно. - Приклад: дозволити будь-якому учаснику в одній конкретній групі: + Приклад: дозволити будь-якого учасника в одній конкретній групі: ```json5 { @@ -191,7 +198,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Приклад: дозволити лише конкретним користувачам в одній конкретній групі: + Приклад: дозволити лише конкретних користувачів в одній конкретній групі: ```json5 { @@ -209,16 +216,16 @@ curl "https://api.telegram.org/bot/getUpdates" ``` - Типова помилка: `groupAllowFrom` — це не allowlist груп Telegram. + Поширена помилка: `groupAllowFrom` — це не allowlist Telegram-груп. - - Вказуйте від’ємні ID груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`. - - Вказуйте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, які люди всередині дозволеної групи можуть звертатися до бота. - - Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг спілкуватися з ботом. + - Вказуйте від’ємні ID Telegram-груп або супергруп, як-от `-1001234567890`, у `channels.telegram.groups`. + - Вказуйте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, якщо хочете обмежити, які люди всередині дозволеної групи можуть активувати бота. + - Використовуйте `groupAllowFrom: ["*"]` лише якщо хочете, щоб будь-який учасник дозволеної групи міг говорити з ботом. - + Відповіді в групах за замовчуванням потребують згадування. Згадування може надходити з: @@ -252,8 +259,8 @@ curl "https://api.telegram.org/bot/getUpdates" Як отримати ID групового чату: - перешліть повідомлення з групи до `@userinfobot` / `@getidsbot` - - або прочитайте `chat.id` з `openclaw logs --follow` - - або перевірте Bot API `getUpdates` + - або зчитайте `chat.id` з `openclaw logs --follow` + - або перегляньте Bot API `getUpdates` @@ -262,52 +269,52 @@ curl "https://api.telegram.org/bot/getUpdates" - Telegram належить процесу gateway. - Маршрутизація детермінована: вхідні відповіді з Telegram повертаються в Telegram (модель не вибирає канали). -- Вхідні повідомлення нормалізуються до спільного канального envelope з метаданими відповіді та заповнювачами медіа. -- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:`, щоб теми залишалися ізольованими. -- Повідомлення DM можуть містити `message_thread_id`; OpenClaw маршрутизує їх із thread-aware ключами сесії та зберігає ID потоку для відповідей. -- Long polling використовує grammY runner з послідовністю за chat/per-thread. Загальна sink-конкурентність runner використовує `agents.defaults.maxConcurrent`. -- Перезапуски watchdog для long polling спрацьовують за замовчуванням після 120 секунд без завершеної перевірки життєздатності `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо у вашому розгортанні все ще трапляються хибні перезапуски через зависання polling під час довготривалої роботи. Значення задається в мілісекундах і дозволене в діапазоні від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів. +- Вхідні повідомлення нормалізуються до спільної channel envelope з метаданими відповіді та заповнювачами медіа. +- Групові сесії ізольовані за ID групи. Для форумних тем додається `:topic:`, щоб теми були ізольовані. +- DM-повідомлення можуть містити `message_thread_id`; OpenClaw маршрутизує їх з thread-aware ключами сесії та зберігає ID потоку для відповідей. +- Довге опитування використовує grammY runner із послідовністю на рівні чату/потоку. Загальна конкурентність sink у runner використовує `agents.defaults.maxConcurrent`. +- Перезапуски watchdog для long polling спрацьовують після 120 секунд без завершеної перевірки живучості `getUpdates` за замовчуванням. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо у вашому розгортанні все ще трапляються хибні перезапуски через зависання polling під час довготривалої роботи. Значення задається в мілісекундах і допускається в межах від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів. - Telegram Bot API не підтримує квитанції про прочитання (`sendReadReceipts` не застосовується). ## Довідник можливостей - + OpenClaw може передавати часткові відповіді в реальному часі: - - прямі чати: попереднє повідомлення + `editMessageText` - - групи/теми: попереднє повідомлення + `editMessageText` + - прямі чати: повідомлення попереднього перегляду + `editMessageText` + - групи/теми: повідомлення попереднього перегляду + `editMessageText` Вимога: - `channels.telegram.streaming` має значення `off | partial | block | progress` (за замовчуванням: `partial`) - - `progress` у Telegram відповідає `partial` (сумісність із міжканальним найменуванням) - - `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме відредаговане попереднє повідомлення (за замовчуванням: `true`). Встановіть `false`, щоб зберегти окремі повідомлення інструментів/прогресу. - - застарілі `channels.telegram.streamMode` і булеві значення `streaming` автоматично мапуються + - `progress` у Telegram відображається як `partial` (сумісність із міжканальним найменуванням) + - `streaming.preview.toolProgress` керує тим, чи перевикористовують оновлення інструментів/прогресу те саме відредаговане повідомлення попереднього перегляду (за замовчуванням: `true`). Встановіть `false`, щоб зберігати окремі повідомлення інструментів/прогресу. + - застарілі `channels.telegram.streamMode` і булеві значення `streaming` автоматично відображаються Для відповідей лише з текстом: - - DM: OpenClaw зберігає те саме попереднє повідомлення і виконує фінальне редагування на місці (без другого повідомлення) - - група/тема: OpenClaw зберігає те саме попереднє повідомлення і виконує фінальне редагування на місці (без другого повідомлення) + - DM: OpenClaw зберігає те саме повідомлення попереднього перегляду і виконує фінальне редагування на місці (без другого повідомлення) + - група/тема: OpenClaw зберігає те саме повідомлення попереднього перегляду і виконує фінальне редагування на місці (без другого повідомлення) - Для складних відповідей (наприклад, медіа-навантажень) OpenClaw повертається до звичайної фінальної доставки, а потім очищує попереднє повідомлення. + Для складних відповідей (наприклад, з медіавмістом) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду. - Потоковий попередній перегляд відокремлений від block streaming. Якщо для Telegram явно увімкнено block streaming, OpenClaw пропускає preview stream, щоб уникнути подвійного стримінгу. + Потоковий попередній перегляд відокремлений від block streaming. Коли для Telegram явно ввімкнено block streaming, OpenClaw пропускає потоковий попередній перегляд, щоб уникнути подвійного стримінгу. - Якщо нативний transport для чернеток недоступний або відхилений, OpenClaw автоматично повертається до `sendMessage` + `editMessageText`. + Якщо нативний транспорт чернеток недоступний або відхиляється, OpenClaw автоматично повертається до `sendMessage` + `editMessageText`. Потік reasoning лише для Telegram: - - `/reasoning stream` надсилає reasoning у live preview під час генерації + - `/reasoning stream` надсилає reasoning до попереднього перегляду в реальному часі під час генерації - фінальна відповідь надсилається без тексту reasoning - + Вихідний текст використовує Telegram `parse_mode: "HTML"`. - - Текст у стилі Markdown рендериться в безпечний для Telegram HTML. - - Сирий HTML моделі екранується, щоб зменшити кількість збоїв парсингу Telegram. + - Текст у стилі Markdown рендериться у безпечний для Telegram HTML. + - Сирий HTML моделі екранується, щоб зменшити збої парсингу в Telegram. - Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як звичайний текст. Попередній перегляд посилань увімкнено за замовчуванням і його можна вимкнути через `channels.telegram.linkPreview: false`. @@ -317,7 +324,7 @@ curl "https://api.telegram.org/bot/getUpdates" Реєстрація меню команд Telegram виконується під час запуску через `setMyCommands`. - Налаштування нативних команд за замовчуванням: + Типові значення для нативних команд: - `commands.native: "auto"` вмикає нативні команди для Telegram @@ -328,7 +335,7 @@ curl "https://api.telegram.org/bot/getUpdates" channels: { telegram: { customCommands: [ - { command: "backup", description: "Резервне копіювання Git" }, + { command: "backup", description: "Резервна копія Git" }, { command: "generate", description: "Створити зображення" }, ], }, @@ -338,40 +345,40 @@ curl "https://api.telegram.org/bot/getUpdates" Правила: - - імена нормалізуються (видаляється початковий `/`, нижній регістр) - - допустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32` + - назви нормалізуються (забирається початковий `/`, перетворення до нижнього регістру) + - коректний шаблон: `a-z`, `0-9`, `_`, довжина `1..32` - власні команди не можуть перевизначати нативні команди - - конфлікти/дублікати пропускаються та логуються + - конфлікти/дублікати пропускаються та журналюються Примітки: - власні команди — це лише записи меню; вони не реалізують поведінку автоматично - - команди plugin/Skills однаково можуть працювати при введенні вручну, навіть якщо вони не показані в меню Telegram + - команди Plugin/Skills усе одно можуть працювати при ручному введенні, навіть якщо вони не показані в меню Telegram - Якщо нативні команди вимкнено, вбудовані команди видаляються. Власні команди/команди plugin усе ще можуть реєструватися, якщо це налаштовано. + Якщо нативні команди вимкнено, вбудовані видаляються. Власні команди/команди Plugin усе ще можуть реєструватися, якщо це налаштовано. - Типові збої під час налаштування: + Типові збої налаштування: - - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнене після скорочення; зменште кількість власних команд/команд plugin/Skills або вимкніть `channels.telegram.commands.native`. - - `setMyCommands failed` з помилками network/fetch зазвичай означає, що вихідні DNS/HTTPS-з’єднання до `api.telegram.org` заблоковано. + - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнене після скорочення; зменште кількість команд Plugin/Skills/власних команд або вимкніть `channels.telegram.commands.native`. + - `setMyCommands failed` із помилками мережі/fetch зазвичай означає, що вихідні DNS/HTTPS-з’єднання до `api.telegram.org` заблоковані. - ### Команди підключення пристрою (`device-pair` Plugin) + ### Команди зв’язування пристроїв (`device-pair` Plugin) Коли встановлено Plugin `device-pair`: 1. `/pair` генерує код налаштування 2. вставте код у застосунок iOS - 3. `/pair pending` показує список запитів, що очікують на розгляд (включно з роллю/областями доступу) + 3. `/pair pending` показує список очікуваних запитів (включно з роллю/scopes) 4. схваліть запит: - `/pair approve ` для явного схвалення - - `/pair approve`, коли є лише один запит, що очікує на розгляд + - `/pair approve`, коли є лише один очікуваний запит - `/pair approve latest` для найновішого - Код налаштування містить короткоживучий bootstrap-токен. Вбудована bootstrap-передача зберігає токен первинного Node на рівні `scopes: []`; будь-який переданий токен оператора залишається обмеженим до `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки bootstrap-областей доступу мають префікс ролі, тому цей allowlist оператора задовольняє лише запити оператора; ролі, що не є оператором, усе ще потребують областей доступу під префіксом власної ролі. + Код налаштування містить короткоживучий bootstrap-токен. Вбудована передача bootstrap зберігає токен первинного Node на рівні `scopes: []`; будь-який переданий токен оператора лишається обмеженим до `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки bootstrap scope мають префікс ролі, тож цей allowlist оператора задовольняє лише запити оператора; ролі, що не є operator, усе ще потребують scopes під власним префіксом ролі. - Якщо пристрій повторює спробу зі зміненими даними автентифікації (наприклад, роль/області доступу/публічний ключ), попередній запит, що очікує на розгляд, заміщується, а новий запит використовує інший `requestId`. Перед схваленням знову виконайте `/pair pending`. + Якщо пристрій повторює спробу зі зміненими даними автентифікації (наприклад, роль/scopes/публічний ключ), попередній очікуваний запит замінюється, а новий запит отримує інший `requestId`. Перед схваленням знову виконайте `/pair pending`. - Докладніше: [Підключення](/uk/channels/pairing#pair-via-telegram-recommended-for-ios). + Докладніше: [Зв’язування](/uk/channels/pairing#pair-via-telegram-recommended-for-ios). @@ -416,7 +423,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `all` - `allowlist` (за замовчуванням) - Застаріле `capabilities: ["inlineButtons"]` мапується на `inlineButtons: "all"`. + Застаріле `capabilities: ["inlineButtons"]` відображається як `inlineButtons: "all"`. Приклад дії повідомлення: @@ -441,26 +448,26 @@ curl "https://api.telegram.org/bot/getUpdates" - + Дії інструментів Telegram включають: - - `sendMessage` (`to`, `content`, необов’язково `mediaUrl`, `replyToMessageId`, `messageThreadId`) + - `sendMessage` (`to`, `content`, необов’язкові `mediaUrl`, `replyToMessageId`, `messageThreadId`) - `react` (`chatId`, `messageId`, `emoji`) - `deleteMessage` (`chatId`, `messageId`) - `editMessage` (`chatId`, `messageId`, `content`) - - `createForumTopic` (`chatId`, `name`, необов’язково `iconColor`, `iconCustomEmojiId`) + - `createForumTopic` (`chatId`, `name`, необов’язкові `iconColor`, `iconCustomEmojiId`) - Дії повідомлень каналу надають зручні аліаси (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). + Дії channel message надають зручні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). - Керування через gating: + Керувальні параметри: - `channels.telegram.actions.sendMessage` - `channels.telegram.actions.deleteMessage` - `channels.telegram.actions.reactions` - `channels.telegram.actions.sticker` (за замовчуванням: вимкнено) - Примітка: `edit` і `topic-create` наразі увімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`. - Надсилання під час runtime використовує активний знімок config/secrets (startup/reload), тому шляхи дій не виконують ad-hoc повторне визначення `SecretRef` для кожного надсилання. + Примітка: `edit` і `topic-create` зараз увімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`. + Надсилання в runtime використовує активний знімок config/secrets (startup/reload), тому шляхи дій не виконують ad-hoc повторне визначення `SecretRef` для кожного надсилання. Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions) @@ -469,7 +476,7 @@ curl "https://api.telegram.org/bot/getUpdates" Telegram підтримує явні теги потоків відповідей у згенерованому виводі: - - `[[reply_to_current]]` відповідає на повідомлення, яке ініціювало дію + - `[[reply_to_current]]` відповідає на повідомлення, яке ініціювало запит - `[[reply_to:]]` відповідає на конкретний ID повідомлення Telegram `channels.telegram.replyToMode` керує обробкою: @@ -478,27 +485,27 @@ curl "https://api.telegram.org/bot/getUpdates" - `first` - `all` - Примітка: `off` вимикає неявне формування потоку відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються. + Примітка: `off` вимикає неявне прив’язування відповідей до потоку. Явні теги `[[reply_to_*]]` усе одно враховуються. - - Супергрупи форуму: + + Форумні супергрупи: - ключі сесій тем додають `:topic:` - - відповіді та індикатор набору тексту спрямовуються в потік теми + - відповіді та індикатор набору спрямовуються в потік теми - шлях config теми: `channels.telegram.groups..topics.` - Спеціальний випадок загальної теми (`threadId=1`): + Особливий випадок загальної теми (`threadId=1`): - - надсилання повідомлень пропускає `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`) - - дії набору тексту все одно включають `message_thread_id` + - надсилання повідомлень не містить `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`) + - дії індикатора набору все одно містять `message_thread_id` - Успадкування тем: записи тем успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). - `agentId` є параметром лише теми й не успадковується з типових налаштувань групи. + Успадкування тем: записи тем успадковують налаштування групи, якщо не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). + `agentId` належить лише темі й не успадковується з типових налаштувань групи. - **Маршрутизація агента для окремої теми**: кожна тема може маршрутизуватися до іншого агента, якщо задати `agentId` у config теми. Це дає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад: + **Маршрутизація агентів для окремих тем**: Кожна тема може маршрутизуватися до іншого агента, якщо задати `agentId` у config теми. Це надає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад: ```json5 { @@ -509,7 +516,7 @@ curl "https://api.telegram.org/bot/getUpdates" topics: { "1": { agentId: "main" }, // Загальна тема → агент main "3": { agentId: "zu" }, // Тема розробки → агент zu - "5": { agentId: "coder" } // Code review → агент coder + "5": { agentId: "coder" } // Рев’ю коду → агент coder } } } @@ -520,7 +527,7 @@ curl "https://api.telegram.org/bot/getUpdates" Тоді кожна тема має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3` - **Постійна прив’язка тем ACP**: теми форуму можуть закріплювати сесії harness ACP через typed ACP bindings верхнього рівня: + **Постійне прив’язування тем ACP**: Форумні теми можуть закріплювати сесії ACP harness через типізовані ACP bindings верхнього рівня: - `bindings[]` з `type: "acp"` і `match.channel: "telegram"` @@ -571,21 +578,21 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Наразі це обмежено темами форумів у групах і супергрупах. + Зараз це обмежено форумними темами в групах і супергрупах. - **Запуск ACP, прив’язаний до потоку, з чату**: + **ACP spawn, прив’язаний до потоку, з чату**: - `/acp spawn --thread here|auto` може прив’язати поточну тему Telegram до нової сесії ACP. - - Наступні повідомлення в темі маршрутизуються безпосередньо до прив’язаної сесії ACP (без потреби в `/acp steer`). - - Після успішної прив’язки OpenClaw закріплює повідомлення з підтвердженням запуску в цій темі. - - Потребує `channels.telegram.threadBindings.spawnAcpSessions=true`. + - Подальші повідомлення в темі маршрутизуються безпосередньо до прив’язаної сесії ACP (без потреби в `/acp steer`). + - Після успішного прив’язування OpenClaw закріплює повідомлення-підтвердження spawn у темі. + - Потрібно `channels.telegram.threadBindings.spawnAcpSessions=true`. Контекст шаблону включає: - `MessageThreadId` - `IsForum` - Поведінка потоку DM: + Поведінка DM-потоків: - приватні чати з `message_thread_id` зберігають маршрутизацію DM, але використовують thread-aware ключі сесії/цілі відповідей. @@ -594,10 +601,10 @@ curl "https://api.telegram.org/bot/getUpdates" ### Аудіоповідомлення - Telegram розрізняє голосові повідомлення та аудіофайли. + Telegram розрізняє голосові нотатки та аудіофайли. - за замовчуванням: поведінка аудіофайлу - - тег `[[audio_as_voice]]` у відповіді агента примусово надсилає як голосове повідомлення + - тег `[[audio_as_voice]]` у відповіді агента примусово надсилає як голосову нотатку Приклад дії повідомлення: @@ -613,7 +620,7 @@ curl "https://api.telegram.org/bot/getUpdates" ### Відеоповідомлення - Telegram розрізняє відеофайли та video notes. + Telegram розрізняє відеофайли та відеонотатки. Приклад дії повідомлення: @@ -627,7 +634,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Video notes не підтримують підписи; наданий текст повідомлення надсилається окремо. + Відеонотатки не підтримують підписи; наданий текст повідомлення надсилається окремо. ### Стікери @@ -676,13 +683,13 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Пошук у кешованих стікерах: + Пошук кешованих стікерів: ```json5 { action: "sticker-search", channel: "telegram", - query: "cat waving", + query: "кіт махає лапою", limit: 5, } ``` @@ -690,13 +697,13 @@ curl "https://api.telegram.org/bot/getUpdates" - Реакції Telegram надходять як оновлення `message_reaction` (окремо від корисних навантажень повідомлень). + Реакції Telegram надходять як оновлення `message_reaction` (окремо від корисного навантаження повідомлень). - Коли цю функцію ввімкнено, OpenClaw ставить у чергу системні події на кшталт: + Коли ввімкнено, OpenClaw ставить у чергу системні події на кшталт: - `Telegram reaction added: 👍 by Alice (@alice) on msg 42` - Конфігурація: + Config: - `channels.telegram.reactionNotifications`: `off | own | all` (за замовчуванням: `own`) - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (за замовчуванням: `minimal`) @@ -704,12 +711,12 @@ curl "https://api.telegram.org/bot/getUpdates" Примітки: - `own` означає лише реакції користувачів на повідомлення, надіслані ботом (best-effort через кеш надісланих повідомлень). - - Події реакцій усе одно поважають механізми контролю доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); від неавторизованих відправників вони відкидаються. + - Події реакцій усе одно підпорядковуються контролю доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються. - Telegram не надає ID потоку в оновленнях реакцій. - - групи без форуму маршрутизуються до сесії групового чату - - групи форуму маршрутизуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми + - нефорумні групи маршрутизуються до сесії групового чату + - форумні групи маршрутизуються до сесії загальної теми групи (`:topic:1`), а не до точного початкового топіка - `allowed_updates` для polling/Webhook-ів автоматично включають `message_reaction`. + `allowed_updates` для polling/webhook автоматично включає `message_reaction`. @@ -721,22 +728,22 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - резервний emoji з ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") + - резервне значення emoji ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") Примітки: - - Telegram очікує unicode emoji (наприклад, "👀"). + - Telegram очікує unicode-emoji (наприклад, "👀"). - Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису. - Записи в config каналу увімкнені за замовчуванням (`configWrites !== false`). + Записи в config каналу ввімкнені за замовчуванням (`configWrites !== false`). Записи, ініційовані Telegram, включають: - - події міграції груп (`migrate_to_chat_id`) для оновлення `channels.telegram.groups` - - `/config set` і `/config unset` (потребує ввімкнення команд) + - події міграції групи (`migrate_to_chat_id`) для оновлення `channels.telegram.groups` + - `/config set` і `/config unset` (потрібно ввімкнення команд) Вимкнення: @@ -752,46 +759,46 @@ curl "https://api.telegram.org/bot/getUpdates" - - За замовчуванням: long polling. + + За замовчуванням: довге опитування. - Режим Webhook-ів: + Режим Webhook: - задайте `channels.telegram.webhookUrl` - - задайте `channels.telegram.webhookSecret` (обов’язково, якщо задано URL Webhook-а) + - задайте `channels.telegram.webhookSecret` (обов’язково, коли задано webhook URL) - необов’язково `channels.telegram.webhookPath` (за замовчуванням `/telegram-webhook`) - необов’язково `channels.telegram.webhookHost` (за замовчуванням `127.0.0.1`) - необов’язково `channels.telegram.webhookPort` (за замовчуванням `8787`) - Типовий локальний listener для режиму Webhook-ів прив’язується до `127.0.0.1:8787`. + Типовий локальний listener для режиму Webhook прив’язується до `127.0.0.1:8787`. - Якщо ваша публічна кінцева точка відрізняється, розмістіть попереду reverse proxy і вкажіть публічний URL у `webhookUrl`. - Установіть `webhookHost` (наприклад, `0.0.0.0`), якщо вам навмисно потрібен зовнішній вхідний доступ. + Якщо ваш публічний endpoint відрізняється, розмістіть перед ним reverse proxy і вкажіть `webhookUrl` на публічний URL. + Задайте `webhookHost` (наприклад, `0.0.0.0`), коли вам свідомо потрібен зовнішній вхідний доступ. - - `channels.telegram.textChunkLimit` за замовчуванням має значення 4000. + - Типове значення `channels.telegram.textChunkLimit` — 4000. - `channels.telegram.chunkMode="newline"` віддає перевагу межам абзаців (порожнім рядкам) перед розбиттям за довжиною. - `channels.telegram.mediaMaxMb` (за замовчуванням 100) обмежує розмір вхідних і вихідних медіа Telegram. - - `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, застосовується значення grammY за замовчуванням). - - `channels.telegram.pollingStallThresholdMs` за замовчуванням дорівнює `120000`; налаштовуйте в межах від `30000` до `600000` лише для хибнопозитивних перезапусків через зависання polling. + - `channels.telegram.timeoutSeconds` перевизначає timeout клієнта Telegram API (якщо не задано, застосовується типовий timeout grammY). + - `channels.telegram.pollingStallThresholdMs` має типове значення `120000`; налаштовуйте в межах від `30000` до `600000` лише для хибнопозитивних перезапусків через зависання polling. - історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (за замовчуванням 50); `0` вимикає. - - додатковий контекст reply/quote/forward наразі передається в отриманому вигляді. - - allowlist-списки Telegram насамперед керують тим, хто може активувати агента, а не є повною межею редагування додаткового контексту. - - керування історією DM: + - додатковий контекст reply/quote/forward наразі передається як отримано. + - allowlist Telegram насамперед керують тим, хто може активувати агента, а не є повною межею редагування додаткового контексту. + - параметри історії DM: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - config `channels.telegram.retry` застосовується до допоміжних функцій надсилання Telegram (CLI/tools/actions) для відновлюваних вихідних помилок API. - Ціль CLI для надсилання може бути числовим ID чату або username: + Ціллю CLI send може бути числовий ID чату або username: ```bash openclaw message send --channel telegram --target 123456789 --message "hi" openclaw message send --channel telegram --target @name --message "hi" ``` - Опитування Telegram використовують `openclaw message poll` і підтримують теми форуму: + Опитування Telegram використовують `openclaw message poll` і підтримують форумні теми: ```bash openclaw message poll --channel telegram --target 123456789 \ @@ -806,9 +813,9 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - `--poll-duration-seconds` (5-600) - `--poll-anonymous` - `--poll-public` - - `--thread-id` для тем форуму (або використовуйте ціль `:topic:`) + - `--thread-id` для форумних тем (або використовуйте ціль `:topic:`) - Надсилання Telegram також підтримує: + Telegram send також підтримує: - `--presentation` з блоками `buttons` для вбудованих клавіатур, коли це дозволяє `channels.telegram.capabilities.inlineButtons` - `--pin` або `--delivery '{"pin":true}'`, щоб запитати закріплену доставку, коли бот може закріплювати в цьому чаті @@ -817,7 +824,7 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ Керування діями: - `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, включно з опитуваннями - - `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайне надсилання увімкненим + - `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайне надсилання ввімкненим @@ -827,14 +834,14 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ Шлях config: - `channels.telegram.execApprovals.enabled` - - `channels.telegram.execApprovals.approvers` (необов’язково; за відсутності використовується резервне визначення з числових ID власника, виведених із `allowFrom` і прямого `defaultTo`, коли це можливо) + - `channels.telegram.execApprovals.approvers` (необов’язково; як резервне значення використовуються числові ID власників, виведені з `allowFrom` і прямого `defaultTo`, коли це можливо) - `channels.telegram.execApprovals.target` (`dm` | `channel` | `both`, за замовчуванням: `dm`) - `agentFilter`, `sessionFilter` - Схвалювачі мають бути числовими ID користувачів Telegram. Telegram автоматично вмикає нативні схвалення exec, коли `enabled` не задано або дорівнює `"auto"` і можна визначити принаймні одного схвалювача — або з `execApprovals.approvers`, або з числового config власника облікового запису (`allowFrom` і `defaultTo` для прямих повідомлень). Установіть `enabled: false`, щоб явно вимкнути Telegram як нативний клієнт схвалення. В інших випадках запити на схвалення повертаються до інших налаштованих маршрутів схвалення або до fallback-політики схвалення exec. + Схвалювачі мають бути числовими ID користувачів Telegram. Telegram автоматично вмикає нативні схвалення exec, коли `enabled` не задано або має значення `"auto"` і вдається визначити хоча б одного схвалювача — або з `execApprovals.approvers`, або з числової config власника облікового запису (`allowFrom` і DM `defaultTo`). Задайте `enabled: false`, щоб явно вимкнути Telegram як нативний клієнт схвалення. Інакше запити на схвалення повертаються до інших налаштованих маршрутів схвалення або до резервної політики схвалення exec. - Telegram також рендерить спільні кнопки схвалення, які використовують інші чат-канали. Нативний адаптер Telegram переважно додає маршрутизацію DM схвалювачів, fanout у канали/теми та підказки набору тексту перед доставкою. - Коли ці кнопки присутні, вони є основним UX для схвалення; OpenClaw + Telegram також рендерить спільні кнопки схвалення, які використовуються іншими чат-каналами. Нативний адаптер Telegram головно додає маршрутизацію DM схвалювачів, fanout у канал/тему та підказки набору перед доставкою. + Коли ці кнопки присутні, вони є основним UX схвалення; OpenClaw має включати ручну команду `/approve` лише тоді, коли результат інструмента каже, що схвалення в чаті недоступні або ручне схвалення — єдиний шлях. @@ -844,21 +851,21 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - `target: "channel"` надсилає запит назад у вихідний чат/тему Telegram - `target: "both"` надсилає і в DM схвалювачів, і у вихідний чат/тему - Лише визначені схвалювачі можуть схвалювати або відхиляти. Користувачі, які не є схвалювачами, не можуть використовувати `/approve` і не можуть користуватися кнопками схвалення Telegram. + Лише визначені схвалювачі можуть схвалювати або відхиляти. Не-схвалювачі не можуть використовувати `/approve` і не можуть використовувати кнопки схвалення Telegram. Поведінка визначення схвалення: - - ID з префіксом `plugin:` завжди визначаються через схвалення plugin. - - Інші ID спочатку пробують `exec.approval.resolve`. - - Якщо Telegram також авторизований для схвалень plugin і gateway каже, - що схвалення exec невідоме/прострочене, Telegram один раз повторює спробу через + - ID з префіксом `plugin:` завжди визначаються через схвалення Plugin. + - Інші ID спершу пробують `exec.approval.resolve`. + - Якщо Telegram також авторизовано для схвалень Plugin і gateway повідомляє, + що схвалення exec невідоме/прострочене, Telegram ще раз пробує через `plugin.approval.resolve`. - - Реальні відмови/помилки схвалення exec не переходять мовчки до - визначення схвалення plugin. + - Справжні відмови/помилки схвалення exec не переходять мовчки до + визначення схвалення Plugin. - Доставка в канал показує текст команди в чаті, тому вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє в тему форуму, OpenClaw зберігає тему як для запиту на схвалення, так і для подальших дій після схвалення. За замовчуванням схвалення exec спливають через 30 хвилин. + Доставка в channel показує текст команди в чаті, тому вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє у форумну тему, OpenClaw зберігає тему і для запиту на схвалення, і для подальшого повідомлення після схвалення. За замовчуванням схвалення exec спливають через 30 хвилин. - Вбудовані кнопки схвалення також залежать від того, чи дозволяє `channels.telegram.capabilities.inlineButtons` цільову поверхню (`dm`, `group` або `all`). + Вбудовані кнопки схвалення також залежать від того, чи `channels.telegram.capabilities.inlineButtons` дозволяє цільову поверхню (`dm`, `group` або `all`). Пов’язана документація: [Схвалення exec](/uk/tools/exec-approvals) @@ -867,12 +874,12 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ ## Керування відповідями про помилки -Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або приховати її. Цю поведінку контролюють два ключі config: +Коли агент стикається з помилкою доставки або постачальника, Telegram може або відповісти текстом помилки, або придушити її. Цю поведінку контролюють два ключі config: | Key | Values | Default | Description | | ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- | | `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає до чату дружнє повідомлення про помилку. `silent` повністю пригнічує відповіді про помилки. | -| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями про помилки в тому самому чаті. Запобігає спаму помилками під час збоїв. | +| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями про помилки в одному чаті. Запобігає спаму помилок під час збоїв. | Підтримуються перевизначення для окремого облікового запису, групи й теми (те саме успадкування, що й для інших ключів config Telegram). @@ -892,45 +899,45 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ } ``` -## Усунення несправностей +## Усунення проблем - + - - Якщо `requireMention=false`, режим конфіденційності Telegram має дозволяти повну видимість. + - Якщо `requireMention=false`, режим приватності Telegram має дозволяти повну видимість. - BotFather: `/setprivacy` -> Disable - - потім видаліть бота з групи й додайте знову + - потім видаліть і знову додайте бота до групи - `openclaw channels status` попереджає, коли config очікує повідомлення групи без згадування. - - `openclaw channels status --probe` може перевіряти явні числові ID груп; для wildcard `"*"` перевірка членства недоступна. - - швидкий тест сесії: `/activation always`. + - `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` не можна перевірити на членство через probe. + - швидка перевірка сесії: `/activation always`. - + - - коли існує `channels.telegram.groups`, група має бути вказана в списку (або має бути `"*"`) + - коли існує `channels.telegram.groups`, групу треба вказати в списку (або включити `"*"`) - перевірте членство бота в групі - - перегляньте логи: `openclaw logs --follow`, щоб побачити причини пропуску + - перегляньте журнали: `openclaw logs --follow`, щоб побачити причини пропуску - + - - авторизуйте свою ідентичність відправника (підключення та/або числовий `allowFrom`) - - авторизація команд усе одно застосовується, навіть коли політика групи `open` - - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню має забагато записів; зменште кількість власних команд/команд plugin/Skills або вимкніть нативні меню - - `setMyCommands failed` з помилками network/fetch зазвичай указує на проблеми досяжності DNS/HTTPS до `api.telegram.org` + - авторизуйте свою ідентичність відправника (зв’язування та/або числовий `allowFrom`) + - авторизація команд усе одно застосовується, навіть коли політика групи має значення `open` + - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню має забагато записів; зменште кількість команд Plugin/Skills/власних команд або вимкніть нативні меню + - `setMyCommands failed` із помилками мережі/fetch зазвичай вказує на проблеми з доступністю DNS/HTTPS до `api.telegram.org` - - Node 22+ + власний fetch/proxy можуть спричиняти негайне переривання, якщо типи AbortSignal не збігаються. - - Деякі хости спочатку резолвлять `api.telegram.org` в IPv6; несправний вихідний IPv6 може спричиняти періодичні збої Telegram API. - - Якщо логи містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює їх як відновлювані мережеві помилки. - - Якщо логи містять `Polling stall detected`, OpenClaw перезапускає polling і перебудовує транспорт Telegram після 120 секунд без завершеної перевірки життєздатності long poll за замовчуванням. - - Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` працюють нормально, але ваш хост усе ще повідомляє про хибнопозитивні перезапуски через зависання polling. Стійкі зависання зазвичай вказують на проблеми proxy, DNS, IPv6 або TLS-виходу між хостом і `api.telegram.org`. - - На VPS-хостах із нестабільним прямим вихідним трафіком/TLS спрямовуйте виклики Telegram API через `channels.telegram.proxy`: + - Node 22+ + власний fetch/proxy може спричиняти негайне скасування, якщо типи AbortSignal не збігаються. + - Деякі хости спершу визначають `api.telegram.org` у IPv6; несправний вихідний IPv6 може спричиняти переривчасті збої Telegram API. + - Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює такі випадки як відновлювані мережеві помилки. + - Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає polling і перебудовує транспорт Telegram після 120 секунд без завершеної перевірки живучості long-poll за замовчуванням. + - Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` є здоровими, але ваш хост усе ще повідомляє про хибні перезапуски через зависання polling. Стійкі зависання зазвичай вказують на проблеми proxy, DNS, IPv6 або TLS-виходу між хостом і `api.telegram.org`. + - На VPS-хостах із нестабільним прямим виходом/TLS маршрутизуйте виклики Telegram API через `channels.telegram.proxy`: ```yaml channels: @@ -938,8 +945,8 @@ channels: proxy: socks5://:@proxy-host:1080 ``` - - У Node 22+ за замовчуванням використовується `autoSelectFamily=true` (крім WSL2) і `dnsResultOrder=ipv4first`. - - Якщо ваш хост — WSL2 або явно краще працює лише з IPv4, примусово задайте вибір сімейства: + - Для Node 22+ типовими є `autoSelectFamily=true` (крім WSL2) і `dnsResultOrder=ipv4first`. + - Якщо ваш хост — WSL2 або явно краще працює в режимі лише IPv4, примусово задайте вибір сімейства: ```yaml channels: @@ -948,10 +955,10 @@ channels: autoSelectFamily: false ``` - - Відповіді діапазону benchmark RFC 2544 (`198.18.0.0/15`) уже дозволені - за замовчуванням для завантаження медіа Telegram. Якщо довірений fake-IP або + - Відповіді з діапазону RFC 2544 benchmark (`198.18.0.0/15`) уже дозволені + для завантажень медіа Telegram за замовчуванням. Якщо довірений fake-IP або transparent proxy переписує `api.telegram.org` на якусь іншу - приватну/внутрішню/спеціальну адресу під час завантаження медіа, ви можете + приватну/внутрішню/special-use адресу під час завантаження медіа, ви можете увімкнути обхід лише для Telegram: ```yaml @@ -963,23 +970,23 @@ channels: - Те саме явне ввімкнення доступне для окремого облікового запису в `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`. - - Якщо ваш proxy резолвить медіахости Telegram в `198.18.x.x`, спочатку залиште - небезпечний прапорець вимкненим. Медіа Telegram уже дозволяє діапазон benchmark RFC 2544 - за замовчуванням. + - Якщо ваш proxy визначає медіахости Telegram у `198.18.x.x`, спершу залиште + небезпечний прапорець вимкненим. Медіа Telegram уже дозволяють діапазон RFC 2544 + benchmark за замовчуванням. - `channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист Telegram - media SSRF. Використовуйте це лише в довірених середовищах proxy, якими керує оператор, - таких як Clash, Mihomo або маршрутизація fake-IP у Surge, коли вони синтезують приватні - або спеціальні відповіді поза межами діапазону benchmark RFC 2544. Для звичайного - публічного доступу Telegram через інтернет залишайте це вимкненим. + `channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захисти SSRF + для медіа Telegram. Використовуйте це лише для довірених керованих оператором proxy-середовищ, + як-от fake-IP маршрутизація Clash, Mihomo або Surge, коли вони + синтезують приватні або special-use відповіді поза діапазоном RFC 2544 benchmark. + Для звичайного доступу до Telegram через публічний інтернет залишайте це вимкненим. - - Перевизначення через середовище (тимчасово): + - Перевизначення через середовище (тимчасові): - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` - - Перевірте відповіді DNS: + - Перевірка DNS-відповідей: ```bash dig +short api.telegram.org A @@ -989,7 +996,7 @@ dig +short api.telegram.org AAAA -Більше довідки: [Усунення проблем каналу](/uk/channels/troubleshooting). +Більше допомоги: [Усунення проблем із каналами](/uk/channels/troubleshooting). ## Вказівники на довідник config Telegram @@ -999,78 +1006,78 @@ dig +short api.telegram.org AAAA - `channels.telegram.botToken`: токен бота (BotFather). - `channels.telegram.tokenFile`: читати токен зі шляху до звичайного файлу. Символічні посилання відхиляються. - `channels.telegram.dmPolicy`: `pairing | allowlist | open | disabled` (за замовчуванням: pairing). -- `channels.telegram.allowFrom`: allowlist для DM (числові ID користувачів Telegram). `allowlist` потребує принаймні одного ID відправника. `open` потребує `"*"`. `openclaw doctor --fix` може перетворити застарілі записи `@username` на ID і відновити записи allowlist із файлів pairing-store у сценаріях міграції allowlist. -- `channels.telegram.actions.poll`: увімкнути або вимкнути створення опитувань Telegram (за замовчуванням: увімкнено; усе одно потребує `sendMessage`). -- `channels.telegram.defaultTo`: ціль Telegram за замовчуванням, яку використовує CLI `--deliver`, коли явний `--reply-to` не задано. +- `channels.telegram.allowFrom`: allowlist для DM (числові ID користувачів Telegram). `allowlist` вимагає щонайменше один ID відправника. `open` вимагає `"*"`. `openclaw doctor --fix` може розв’язати застарілі записи `@username` до ID і може відновити записи allowlist із файлів pairing-store у сценаріях міграції allowlist. +- `channels.telegram.actions.poll`: увімкнути або вимкнути створення опитувань Telegram (за замовчуванням: увімкнено; все одно потрібен `sendMessage`). +- `channels.telegram.defaultTo`: типова ціль Telegram, яку використовує CLI `--deliver`, коли явний `--reply-to` не задано. - `channels.telegram.groupPolicy`: `open | allowlist | disabled` (за замовчуванням: allowlist). -- `channels.telegram.groupAllowFrom`: allowlist відправників у групах (числові ID користувачів Telegram). `openclaw doctor --fix` може перетворити застарілі записи `@username` на ID. Нечислові записи ігноруються під час автентифікації. Автентифікація груп не використовує fallback на pairing-store для DM (`2026.2.25+`). -- Пріоритетність для кількох облікових записів: - - Коли налаштовано два або більше ID облікових записів, задайте `channels.telegram.defaultAccount` (або включіть `channels.telegram.accounts.default`), щоб явно визначити маршрут за замовчуванням. - - Якщо не задано жодного з них, OpenClaw використовує перший нормалізований ID облікового запису, а `openclaw doctor` виводить попередження. +- `channels.telegram.groupAllowFrom`: allowlist відправників у групах (числові ID користувачів Telegram). `openclaw doctor --fix` може розв’язати застарілі записи `@username` до ID. Нечислові записи ігноруються під час авторизації. Авторизація груп не використовує резервне значення зі сховища DM pairing (`2026.2.25+`). +- Пріоритет для кількох облікових записів: + - Коли налаштовано два або більше ID облікових записів, задайте `channels.telegram.defaultAccount` (або включіть `channels.telegram.accounts.default`), щоб явно визначити типову маршрутизацію. + - Якщо не задано жодного з них, OpenClaw використовує перший нормалізований ID облікового запису як резервне значення, а `openclaw doctor` показує попередження. - `channels.telegram.accounts.default.allowFrom` і `channels.telegram.accounts.default.groupAllowFrom` застосовуються лише до облікового запису `default`. - - Іменовані облікові записи успадковують `channels.telegram.allowFrom` і `channels.telegram.groupAllowFrom`, якщо значення на рівні облікового запису не задано. + - Іменовані облікові записи успадковують `channels.telegram.allowFrom` і `channels.telegram.groupAllowFrom`, коли значення на рівні облікового запису не задані. - Іменовані облікові записи не успадковують `channels.telegram.accounts.default.allowFrom` / `groupAllowFrom`. - `channels.telegram.groups`: типові значення для груп + allowlist (використовуйте `"*"` для глобальних типових значень). - - `channels.telegram.groups..groupPolicy`: перевизначення groupPolicy для конкретної групи (`open | allowlist | disabled`). - - `channels.telegram.groups..requireMention`: типовий gating згадувань. - - `channels.telegram.groups..skills`: фільтр Skills (пропущено = усі Skills, порожньо = жодного). - - `channels.telegram.groups..allowFrom`: перевизначення allowlist відправників для конкретної групи. - - `channels.telegram.groups..systemPrompt`: додатковий system prompt для групи. - - `channels.telegram.groups..enabled`: вимикає групу, якщо `false`. - - `channels.telegram.groups..topics..*`: перевизначення для конкретної теми (поля групи + `agentId`, доступний лише для теми). - - `channels.telegram.groups..topics..agentId`: маршрутизувати цю тему до конкретного агента (перевизначає маршрутизацію на рівні групи та bindings). -- `channels.telegram.groups..topics..groupPolicy`: перевизначення groupPolicy для конкретної теми (`open | allowlist | disabled`). -- `channels.telegram.groups..topics..requireMention`: перевизначення gating згадувань для конкретної теми. -- верхньорівневий `bindings[]` з `type: "acp"` і канонічним ID теми `chatId:topic:topicId` у `match.peer.id`: поля постійної прив’язки ACP теми (див. [ACP Agents](/uk/tools/acp-agents#channel-specific-settings)). -- `channels.telegram.direct..topics..agentId`: маршрутизувати теми DM до конкретного агента (та сама поведінка, що й для тем форуму). -- `channels.telegram.execApprovals.enabled`: увімкнути Telegram як чат-клієнт для схвалення exec для цього облікового запису. -- `channels.telegram.execApprovals.approvers`: ID користувачів Telegram, яким дозволено схвалювати або відхиляти запити exec. Необов’язково, якщо `channels.telegram.allowFrom` або прямий `channels.telegram.defaultTo` уже визначає власника. -- `channels.telegram.execApprovals.target`: `dm | channel | both` (за замовчуванням: `dm`). `channel` і `both` зберігають початкову тему Telegram, якщо вона є. + - `channels.telegram.groups..groupPolicy`: перевизначення `groupPolicy` для окремої групи (`open | allowlist | disabled`). + - `channels.telegram.groups..requireMention`: типове керування обов’язковістю згадування. + - `channels.telegram.groups..skills`: фільтр Skills (не вказано = усі Skills, порожньо = жодного). + - `channels.telegram.groups..allowFrom`: перевизначення allowlist відправників для окремої групи. + - `channels.telegram.groups..systemPrompt`: додатковий системний prompt для групи. + - `channels.telegram.groups..enabled`: вимикає групу, коли `false`. + - `channels.telegram.groups..topics..*`: перевизначення для окремої теми (поля групи + лише для теми `agentId`). + - `channels.telegram.groups..topics..agentId`: маршрутизує цю тему до конкретного агента (перевизначає маршрутизацію рівня групи та binding). +- `channels.telegram.groups..topics..groupPolicy`: перевизначення `groupPolicy` для окремої теми (`open | allowlist | disabled`). +- `channels.telegram.groups..topics..requireMention`: перевизначення обов’язковості згадування для окремої теми. +- верхньорівневі `bindings[]` з `type: "acp"` і канонічним ID теми `chatId:topic:topicId` у `match.peer.id`: поля постійного прив’язування тем ACP (див. [ACP Agents](/uk/tools/acp-agents#channel-specific-settings)). +- `channels.telegram.direct..topics..agentId`: маршрутизує теми DM до конкретного агента (та сама поведінка, що й для форумних тем). +- `channels.telegram.execApprovals.enabled`: увімкнути Telegram як клієнт схвалення exec на основі чату для цього облікового запису. +- `channels.telegram.execApprovals.approvers`: ID користувачів Telegram, яким дозволено схвалювати або відхиляти запити exec. Необов’язково, якщо `channels.telegram.allowFrom` або прямий `channels.telegram.defaultTo` вже ідентифікує власника. +- `channels.telegram.execApprovals.target`: `dm | channel | both` (за замовчуванням: `dm`). `channel` і `both` зберігають вихідну тему Telegram, якщо вона є. - `channels.telegram.execApprovals.agentFilter`: необов’язковий фільтр ID агента для пересланих запитів на схвалення. - `channels.telegram.execApprovals.sessionFilter`: необов’язковий фільтр ключа сесії (підрядок або regex) для пересланих запитів на схвалення. -- `channels.telegram.accounts..execApprovals`: перевизначення маршрутизації схвалення exec і авторизації схвалювача для конкретного облікового запису Telegram. +- `channels.telegram.accounts..execApprovals`: перевизначення маршрутизації схвалення exec Telegram та авторизації схвалювачів для окремого облікового запису. - `channels.telegram.capabilities.inlineButtons`: `off | dm | group | all | allowlist` (за замовчуванням: allowlist). -- `channels.telegram.accounts..capabilities.inlineButtons`: перевизначення для конкретного облікового запису. +- `channels.telegram.accounts..capabilities.inlineButtons`: перевизначення для окремого облікового запису. - `channels.telegram.commands.nativeSkills`: увімкнути/вимкнути нативні команди Skills у Telegram. - `channels.telegram.replyToMode`: `off | first | all` (за замовчуванням: `off`). -- `channels.telegram.textChunkLimit`: розмір вихідного фрагмента (символів). +- `channels.telegram.textChunkLimit`: розмір вихідного фрагмента (символи). - `channels.telegram.chunkMode`: `length` (за замовчуванням) або `newline`, щоб розбивати за порожніми рядками (межами абзаців) перед розбиттям за довжиною. - `channels.telegram.linkPreview`: перемикач попереднього перегляду посилань для вихідних повідомлень (за замовчуванням: true). -- `channels.telegram.streaming`: `off | partial | block | progress` (попередній перегляд live stream; за замовчуванням: `partial`; `progress` мапується на `partial`; `block` — сумісність із застарілим режимом preview). Потоковий попередній перегляд Telegram використовує одне preview-повідомлення, яке редагується на місці. -- `channels.telegram.streaming.preview.toolProgress`: повторно використовувати live preview-повідомлення для оновлень tools/progress, коли активний preview streaming (за замовчуванням: `true`). Установіть `false`, щоб зберегти окремі повідомлення tools/progress. +- `channels.telegram.streaming`: `off | partial | block | progress` (потоковий попередній перегляд у реальному часі; за замовчуванням: `partial`; `progress` відображається як `partial`; `block` — сумісність із застарілим режимом попереднього перегляду). Потоковий попередній перегляд у Telegram використовує одне повідомлення попереднього перегляду, яке редагується на місці. +- `channels.telegram.streaming.preview.toolProgress`: повторно використовувати повідомлення потокового попереднього перегляду для оновлень tool/progress, коли потоковий попередній перегляд активний (за замовчуванням: `true`). Задайте `false`, щоб залишити окремі повідомлення tool/progress. - `channels.telegram.mediaMaxMb`: обмеження розміру вхідних/вихідних медіа Telegram (МБ, за замовчуванням: 100). -- `channels.telegram.retry`: політика повторних спроб для допоміжних функцій надсилання Telegram (CLI/tools/actions) у разі відновлюваних вихідних помилок API (спроби, minDelayMs, maxDelayMs, jitter). -- `channels.telegram.network.autoSelectFamily`: перевизначити Node autoSelectFamily (true=увімкнути, false=вимкнути). За замовчуванням увімкнено в Node 22+, а у WSL2 за замовчуванням вимкнено. -- `channels.telegram.network.dnsResultOrder`: перевизначити порядок результатів DNS (`ipv4first` або `verbatim`). За замовчуванням у Node 22+ використовується `ipv4first`. -- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: небезпечне явне ввімкнення для довірених середовищ із fake-IP або transparent proxy, де завантаження медіа Telegram резолвить `api.telegram.org` у приватні/внутрішні/спеціальні адреси поза типовим дозволеним діапазоном benchmark RFC 2544. +- `channels.telegram.retry`: політика повторних спроб для допоміжних функцій надсилання Telegram (CLI/tools/actions) у разі відновлюваних вихідних помилок API (attempts, minDelayMs, maxDelayMs, jitter). +- `channels.telegram.network.autoSelectFamily`: перевизначити Node autoSelectFamily (true=увімкнути, false=вимкнути). За замовчуванням увімкнено в Node 22+, а в WSL2 за замовчуванням вимкнено. +- `channels.telegram.network.dnsResultOrder`: перевизначити порядок результатів DNS (`ipv4first` або `verbatim`). У Node 22+ за замовчуванням `ipv4first`. +- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: небезпечне явне ввімкнення для довірених середовищ fake-IP або transparent-proxy, де завантаження медіа Telegram визначають `api.telegram.org` у приватні/внутрішні/special-use адреси поза типовим дозволеним діапазоном RFC 2544 benchmark. - `channels.telegram.proxy`: URL proxy для викликів Bot API (SOCKS/HTTP). -- `channels.telegram.webhookUrl`: увімкнути режим Webhook-ів (потребує `channels.telegram.webhookSecret`). -- `channels.telegram.webhookSecret`: секрет Webhook-а (обов’язковий, коли задано webhookUrl). -- `channels.telegram.webhookPath`: локальний шлях Webhook-а (за замовчуванням `/telegram-webhook`). -- `channels.telegram.webhookHost`: локальний host прив’язки Webhook-а (за замовчуванням `127.0.0.1`). -- `channels.telegram.webhookPort`: локальний port прив’язки Webhook-а (за замовчуванням `8787`). +- `channels.telegram.webhookUrl`: увімкнути режим Webhook (потрібен `channels.telegram.webhookSecret`). +- `channels.telegram.webhookSecret`: секрет Webhook (обов’язковий, коли задано webhookUrl). +- `channels.telegram.webhookPath`: локальний шлях Webhook (за замовчуванням `/telegram-webhook`). +- `channels.telegram.webhookHost`: локальний хост прив’язування Webhook (за замовчуванням `127.0.0.1`). +- `channels.telegram.webhookPort`: локальний порт прив’язування Webhook (за замовчуванням `8787`). - `channels.telegram.actions.reactions`: керування реакціями інструментів Telegram. -- `channels.telegram.actions.sendMessage`: керування надсиланням повідомлень інструментами Telegram. -- `channels.telegram.actions.deleteMessage`: керування видаленням повідомлень інструментами Telegram. -- `channels.telegram.actions.sticker`: керування діями зі стікерами Telegram — надсилання та пошук (за замовчуванням: false). +- `channels.telegram.actions.sendMessage`: керування надсиланням повідомлень інструментів Telegram. +- `channels.telegram.actions.deleteMessage`: керування видаленням повідомлень інструментів Telegram. +- `channels.telegram.actions.sticker`: керування діями зі стікерами Telegram — надсиланням і пошуком (за замовчуванням: false). - `channels.telegram.reactionNotifications`: `off | own | all` — керує тим, які реакції запускають системні події (за замовчуванням: `own`, якщо не задано). -- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — керує можливістю реакцій агента (за замовчуванням: `minimal`, якщо не задано). -- `channels.telegram.errorPolicy`: `reply | silent` — керує поведінкою відповіді на помилки (за замовчуванням: `reply`). Підтримуються перевизначення для окремого облікового запису/групи/теми. -- `channels.telegram.errorCooldownMs`: мінімальна кількість мс між відповідями на помилки в тому самому чаті (за замовчуванням: `60000`). Запобігає спаму помилками під час збоїв. +- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — керує можливостями реакцій агента (за замовчуванням: `minimal`, якщо не задано). +- `channels.telegram.errorPolicy`: `reply | silent` — керує поведінкою відповідей про помилки (за замовчуванням: `reply`). Підтримуються перевизначення для окремого облікового запису/групи/теми. +- `channels.telegram.errorCooldownMs`: мінімальна кількість мс між відповідями про помилки в одному чаті (за замовчуванням: `60000`). Запобігає спаму помилок під час збоїв. - [Довідник конфігурації - Telegram](/uk/gateway/configuration-reference#telegram) -Специфічні для Telegram поля з високою цінністю сигналу: +Поля Telegram із високою інформаційною цінністю: - запуск/автентифікація: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символічні посилання відхиляються) -- контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневий `bindings[]` (`type: "acp"`) +- контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневі `bindings[]` (`type: "acp"`) - схвалення exec: `execApprovals`, `accounts.*.execApprovals` -- команди/меню: `commands.native`, `commands.nativeSkills`, `customCommands` +- команда/меню: `commands.native`, `commands.nativeSkills`, `customCommands` - потоки/відповіді: `replyToMode` -- streaming: `streaming` (preview), `streaming.preview.toolProgress`, `blockStreaming` +- streaming: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming` - форматування/доставка: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - медіа/мережа: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` -- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` +- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` - дії/можливості: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - реакції: `reactionNotifications`, `reactionLevel` - помилки: `errorPolicy`, `errorCooldownMs` @@ -1078,9 +1085,9 @@ dig +short api.telegram.org AAAA ## Пов’язане -- [Підключення](/uk/channels/pairing) +- [Зв’язування](/uk/channels/pairing) - [Групи](/uk/channels/groups) - [Безпека](/uk/gateway/security) - [Маршрутизація каналів](/uk/channels/channel-routing) - [Маршрутизація кількох агентів](/uk/concepts/multi-agent) -- [Усунення несправностей](/uk/channels/troubleshooting) +- [Усунення проблем](/uk/channels/troubleshooting) diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md index 3aaa9e7d9..35034724b 100644 --- a/docs/uk/gateway/configuration-reference.md +++ b/docs/uk/gateway/configuration-reference.md @@ -5,33 +5,33 @@ read_when: summary: Довідник з конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем title: Довідник з конфігурації x-i18n: - generated_at: "2026-04-22T22:25:46Z" + generated_at: "2026-04-22T22:50:19Z" model: gpt-5.4 provider: openai - source_hash: f602f43fe750e99d5fed261634ce569c0034415cd1769e501e98d0ebe0ad1c19 + source_hash: cbf0f3a25e931f87411f9eecccd432ba5213f67b14824f97d181f7f1c3918f84 source_path: gateway/configuration-reference.md workflow: 15 --- # Довідник з конфігурації -Основний довідник з конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Configuration](/uk/gateway/configuration). +Базовий довідник із конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Конфігурація](/uk/gateway/configuration). -На цій сторінці описано основні поверхні конфігурації OpenClaw і наведено посилання, якщо підсистема має власний, глибший довідник. Вона **не** намагається вбудувати на одну сторінку кожен каталог команд, що належить каналу/плагіну, або кожен глибокий параметр пам’яті/QMD. +Ця сторінка охоплює основні поверхні конфігурації OpenClaw і містить посилання, коли підсистема має власний глибший довідник. Вона **не** намагається вбудувати на одній сторінці кожен каталог команд, що належить каналу/Plugin, або кожен глибокий параметр memory/QMD. Джерело істини в коді: -- `openclaw config schema` виводить актуальну JSON Schema, яка використовується для валідації та Control UI, із метаданими bundled/plugin/channel, об’єднаними за наявності +- `openclaw config schema` виводить актуальну JSON Schema, що використовується для валідації та Control UI, із вбудованими метаданими plugin/channel, об’єднаними за наявності - `config.schema.lookup` повертає один вузол схеми з прив’язкою до шляху для інструментів деталізації -- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють базовий хеш документації конфігурації щодо поточної поверхні схеми +- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють базовий хеш config-doc щодо поточної поверхні схеми Окремі глибокі довідники: -- [Довідник з конфігурації пам’яті](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації dreaming у `plugins.entries.memory-core.config.dreaming` -- [Slash Commands](/uk/tools/slash-commands) для поточного каталогу вбудованих + bundled команд -- сторінки власників каналів/плагінів для поверхонь команд, специфічних для каналів +- [Довідник із конфігурації memory](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації Dreaming у `plugins.entries.memory-core.config.dreaming` +- [Slash Commands](/uk/tools/slash-commands) для поточного каталогу вбудованих + комплектних команд +- сторінки каналу/plugin-власника для специфічних для каналу поверхонь команд -Формат конфігурації — **JSON5** (дозволені коментарі та кінцеві коми). Усі поля необов’язкові — якщо їх пропущено, OpenClaw використовує безпечні значення за замовчуванням. +Формат конфігурації — **JSON5** (дозволені коментарі + кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх не вказано. --- @@ -39,32 +39,32 @@ x-i18n: Кожен канал запускається автоматично, коли існує його розділ конфігурації (якщо не вказано `enabled: false`). -### Доступ до DM і груп +### Доступ до особистих і групових чатів -Усі канали підтримують політики DM і групові політики: +Усі канали підтримують політики для особистих повідомлень і групові політики: -| Політика DM | Поведінка | -| ------------------- | ---------------------------------------------------------------- | -| `pairing` (типово) | Невідомі відправники отримують одноразовий код сполучення; власник має схвалити | -| `allowlist` | Лише відправники з `allowFrom` (або зі сховища дозволених після сполучення) | -| `open` | Дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`) | -| `disabled` | Ігнорувати всі вхідні DM | +| Політика DM | Поведінка | +| ------------------- | ------------------------------------------------------------- | +| `pairing` (типово) | Невідомі відправники отримують одноразовий код pairing; власник має схвалити | +| `allowlist` | Лише відправники з `allowFrom` (або зі сховища дозволів pairing) | +| `open` | Дозволити всі вхідні DM (потребує `allowFrom: ["*"]`) | +| `disabled` | Ігнорувати всі вхідні DM | -| Групова політика | Поведінка | -| --------------------- | ------------------------------------------------------ | -| `allowlist` (типово) | Лише групи, що відповідають налаштованому списку дозволених | -| `open` | Обійти списки дозволених для груп (обмеження за згадками все одно застосовується) | -| `disabled` | Блокувати всі повідомлення груп/кімнат | +| Групова політика | Поведінка | +| --------------------- | ----------------------------------------------------- | +| `allowlist` (типово) | Лише групи, що відповідають налаштованому allowlist | +| `open` | Обійти групові allowlist-и (застосовується gating за згадками) | +| `disabled` | Блокувати всі повідомлення груп/кімнат | -`channels.defaults.groupPolicy` задає значення за замовчуванням, коли `groupPolicy` провайдера не задано. -Коди сполучення спливають через 1 годину. Кількість запитів на сполучення DM, що очікують, обмежена **3 на канал**. -Якщо блок провайдера повністю відсутній (`channels.` відсутній), політика груп під час виконання повертається до `allowlist` (fail-closed) із попередженням під час запуску. +`channels.defaults.groupPolicy` задає політику за замовчуванням, коли `groupPolicy` провайдера не задано. +Коди pairing спливають через 1 годину. Очікувальні запити на pairing у DM обмежені **3 на канал**. +Якщо блок провайдера повністю відсутній (`channels.` відсутній), групова політика під час виконання повертається до `allowlist` (fail-closed) із попередженням під час запуску. -### Перевизначення моделі для каналу +### Перевизначення моделі каналу -Використовуйте `channels.modelByChannel`, щоб закріпити певні ID каналів за моделлю. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Прив’язка каналу застосовується, коли для сесії ще немає перевизначення моделі (наприклад, заданого через `/model`). +Використовуйте `channels.modelByChannel`, щоб прив’язати конкретні ідентифікатори каналів до моделі. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Прив’язка каналу застосовується, коли сесія ще не має перевизначення моделі (наприклад, встановленого через `/model`). ```json5 { @@ -85,9 +85,9 @@ x-i18n: } ``` -### Значення каналів за замовчуванням і Heartbeat +### Типові параметри каналів і Heartbeat -Використовуйте `channels.defaults` для спільної групової політики та поведінки Heartbeat між провайдерами: +Використовуйте `channels.defaults` для спільної поведінки групової політики й Heartbeat у різних провайдерів: ```json5 { @@ -106,14 +106,14 @@ x-i18n: ``` - `channels.defaults.groupPolicy`: резервна групова політика, коли `groupPolicy` на рівні провайдера не задано. -- `channels.defaults.contextVisibility`: режим видимості додаткового контексту за замовчуванням для всіх каналів. Значення: `all` (типово, включати весь контекст цитат/гілок/історії), `allowlist` (включати контекст лише від дозволених відправників), `allowlist_quote` (як `allowlist`, але зберігати явний контекст цитування/відповіді). Перевизначення на рівні каналу: `channels..contextVisibility`. +- `channels.defaults.contextVisibility`: типовий режим видимості додаткового контексту для всіх каналів. Значення: `all` (типово, включати весь контекст із цитат/тредів/історії), `allowlist` (включати контекст лише від відправників з allowlist), `allowlist_quote` (те саме, що й allowlist, але зберігати явний контекст цитати/відповіді). Перевизначення для окремого каналу: `channels..contextVisibility`. - `channels.defaults.heartbeat.showOk`: включати статуси здорових каналів у вивід Heartbeat. - `channels.defaults.heartbeat.showAlerts`: включати деградовані/помилкові статуси у вивід Heartbeat. - `channels.defaults.heartbeat.useIndicator`: відображати компактний вивід Heartbeat у стилі індикатора. ### WhatsApp -WhatsApp працює через вебканал Gateway (Baileys Web). Він запускається автоматично, коли існує пов’язана сесія. +WhatsApp працює через web-канал gateway (Baileys Web). Він запускається автоматично, коли існує прив’язана сесія. ```json5 { @@ -164,9 +164,9 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він } ``` -- Вихідні команди типово використовують обліковий запис `default`, якщо він є; інакше — перший налаштований ID облікового запису (після сортування). -- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. -- Застарілий каталог автентифікації Baileys для одного облікового запису мігрується командою `openclaw doctor` у `whatsapp/default`. +- Вихідні команди типово використовують обліковий запис `default`, якщо він є; інакше — перший налаштований ідентифікатор облікового запису (відсортований). +- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- Застарілий каталог автентифікації Baileys для одного облікового запису мігрується командою `openclaw doctor` до `whatsapp/default`. - Перевизначення на рівні облікового запису: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -225,13 +225,13 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він } ``` -- Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; симлінки відхиляються), із резервним `TELEGRAM_BOT_TOKEN` для типового облікового запису. -- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. -- У багатооблікових конфігураціях (2+ ID облікових записів) задайте явний типовий обліковий запис (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, якщо цього бракує або значення некоректне. -- `configWrites: false` блокує записи конфігурації, ініційовані з Telegram (міграції ID супергруп, `/config set|unset`). -- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні прив’язки ACP для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). -- Попередній перегляд потоків Telegram використовує `sendMessage` + `editMessageText` (працює в особистих і групових чатах). -- Політика повторних спроб: див. [Політика повторних спроб](/uk/concepts/retry). +- Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; symlink-и відхиляються), з `TELEGRAM_BOT_TOKEN` як резервним варіантом для типового облікового запису. +- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- У багатооблікових конфігураціях (2+ ідентифікатори облікових записів) задайте явний типовий обліковий запис (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, якщо цього бракує або значення некоректне. +- `configWrites: false` блокує ініційовані Telegram записи конфігурації (міграції ID супергруп, `/config set|unset`). +- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- Попередній перегляд потокового виводу в Telegram використовує `sendMessage` + `editMessageText` (працює в особистих і групових чатах). +- Політика повторів: див. [Політика повторів](/uk/concepts/retry). ### Discord @@ -333,34 +333,34 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він } ``` -- Токен: `channels.discord.token`, із резервним `DISCORD_BOT_TOKEN` для типового облікового запису. -- Прямі вихідні виклики, які явно передають Discord `token`, використовують цей токен для виклику; налаштування повторних спроб/політик облікового запису все одно беруться з вибраного облікового запису в активному знімку runtime. -- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. -- Для цілей доставки використовуйте `user:` (DM) або `channel:` (канал guild); числові ID без префікса відхиляються. -- Slug-и guild мають нижній регістр, а пробіли замінюються на `-`; ключі каналів використовують slug-ім’я (без `#`). Надавайте перевагу ID guild. +- Токен: `channels.discord.token`, з `DISCORD_BOT_TOKEN` як резервним варіантом для типового облікового запису. +- Прямі вихідні виклики, які передають явний Discord `token`, використовують цей токен для виклику; налаштування повторів/політик облікового запису все одно беруться з вибраного облікового запису в активному знімку runtime. +- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- Використовуйте `user:` (DM) або `channel:` (канал guild) для цілей доставки; прості числові ID відхиляються. +- Slug-и guild мають нижній регістр, а пробіли замінюються на `-`; ключі каналів використовують назву у вигляді slug (без `#`). Надавайте перевагу ID guild. - Повідомлення, створені ботом, типово ігноруються. `allowBots: true` вмикає їх; використовуйте `allowBots: "mentions"`, щоб приймати лише повідомлення ботів, які згадують бота (власні повідомлення все одно відфільтровуються). -- `channels.discord.guilds..ignoreOtherMentions` (і перевизначення на рівні каналу) відкидає повідомлення, які згадують іншого користувача або роль, але не бота (крім @everyone/@here). -- `maxLinesPerMessage` (типово 17) розбиває довгі за висотою повідомлення, навіть якщо вони коротші за 2000 символів. -- `channels.discord.threadBindings` керує маршрутизацією, прив’язаною до гілок Discord: - - `enabled`: перевизначення Discord для функцій сесій, прив’язаних до гілок (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і пов’язана доставка/маршрутизація) - - `idleHours`: перевизначення Discord для автоматичного зняття focus через неактивність у годинах (`0` вимикає) +- `channels.discord.guilds..ignoreOtherMentions` (і перевизначення на рівні каналу) відкидає повідомлення, які згадують іншого користувача або роль, але не бота (за винятком @everyone/@here). +- `maxLinesPerMessage` (типово 17) розбиває високі повідомлення навіть тоді, коли вони коротші за 2000 символів. +- `channels.discord.threadBindings` керує маршрутизацією, прив’язаною до тредів Discord: + - `enabled`: перевизначення Discord для функцій сесій, прив’язаних до тредів (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і прив’язана доставка/маршрутизація) + - `idleHours`: перевизначення Discord для автоматичного зняття фокусу через неактивність у годинах (`0` вимикає) - `maxAgeHours`: перевизначення Discord для жорсткого максимального віку в годинах (`0` вимикає) - - `spawnSubagentSessions`: перемикач opt-in для автоматичного створення/прив’язки гілок `sessions_spawn({ thread: true })` -- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для каналів і гілок (використовуйте id каналу/гілки в `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). -- `channels.discord.ui.components.accentColor` задає акцентний колір для контейнерів Discord components v2. + - `spawnSubagentSessions`: перемикач opt-in для автоматичного створення/прив’язки тредів через `sessions_spawn({ thread: true })` +- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для каналів і тредів (використовуйте id каналу/треду в `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- `channels.discord.ui.components.accentColor` задає колір акценту для контейнерів компонентів Discord v2. - `channels.discord.voice` вмикає розмови в голосових каналах Discord і необов’язкові перевизначення auto-join + TTS. -- `channels.discord.voice.daveEncryption` і `channels.discord.voice.decryptionFailureTolerance` напряму передаються в параметри DAVE `@discordjs/voice` (типово `true` і `24`). -- OpenClaw також намагається відновити прийом голосу, виходячи з голосової сесії та повторно приєднуючись після повторних збоїв дешифрування. -- `channels.discord.streaming` — канонічний ключ режиму потокової передачі. Застарілі значення `streamMode` і булеві значення `streaming` автоматично мігруються. -- `channels.discord.autoPresence` зіставляє доступність runtime зі статусом присутності бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов’язкові перевизначення тексту статусу. -- `channels.discord.dangerouslyAllowNameMatching` повторно вмикає зіставлення за змінним ім’ям/тегом (режим сумісності на крайній випадок). -- `channels.discord.execApprovals`: нативна для Discord доставка погоджень exec і авторизація погоджувачів. - - `enabled`: `true`, `false` або `"auto"` (типово). В автоматичному режимі погодження exec активуються, коли погоджувачів можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ID користувачів Discord, яким дозволено погоджувати exec-запити. Якщо не вказано, використовується резервне значення з `commands.ownerAllowFrom`. - - `agentFilter`: необов’язковий allowlist ID агентів. Якщо пропустити, погодження пересилаються для всіх агентів. +- `channels.discord.voice.daveEncryption` і `channels.discord.voice.decryptionFailureTolerance` напряму передаються до параметрів DAVE у `@discordjs/voice` (`true` і `24` типово). +- OpenClaw також намагається відновити приймання голосу, виходячи з голосової сесії та повторно входячи до неї після повторюваних збоїв дешифрування. +- `channels.discord.streaming` — це канонічний ключ режиму потоку. Застарілі значення `streamMode` і булеві значення `streaming` мігруються автоматично. +- `channels.discord.autoPresence` відображає доступність runtime у присутність бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов’язкові перевизначення тексту статусу. +- `channels.discord.dangerouslyAllowNameMatching` повторно вмикає зіставлення за змінюваними іменами/тегами (режим сумісності break-glass). +- `channels.discord.execApprovals`: нативна для Discord доставка запитів на exec-схвалення та авторизація тих, хто може їх схвалювати. + - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto exec-схвалення активуються, коли тих, хто схвалює, можна визначити з `approvers` або `commands.ownerAllowFrom`. + - `approvers`: ID користувачів Discord, яким дозволено схвалювати exec-запити. Якщо не вказано, використовується `commands.ownerAllowFrom`. + - `agentFilter`: необов’язковий allowlist ID агентів. Не вказуйте, щоб пересилати схвалення для всіх агентів. - `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або regex). - - `target`: куди надсилати запити на погодження. `"dm"` (типово) надсилає в DM погоджувачів, `"channel"` — у вихідний канал, `"both"` — в обидва місця. Коли ціль містить `"channel"`, кнопками можуть користуватися лише визначені погоджувачі. - - `cleanupAfterResolve`: якщо `true`, видаляє DM із погодженнями після погодження, відхилення або тайм-ауту. + - `target`: куди надсилати запити на схвалення. `"dm"` (типово) надсилає в DM тим, хто схвалює, `"channel"` надсилає у вихідний канал, `"both"` надсилає в обидва місця. Коли target містить `"channel"`, кнопками можуть користуватися лише визначені approver-и. + - `cleanupAfterResolve`: коли `true`, видаляє DM із запитами на схвалення після схвалення, відхилення або тайм-ауту. **Режими сповіщень про реакції:** `off` (немає), `own` (повідомлення бота, типово), `all` (усі повідомлення), `allowlist` (із `guilds..users` для всіх повідомлень). @@ -393,11 +393,11 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він } ``` -- JSON службового облікового запису: вбудований (`serviceAccount`) або на основі файла (`serviceAccountFile`). -- Також підтримується SecretRef службового облікового запису (`serviceAccountRef`). -- Резервні значення середовища: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. -- Для цілей доставки використовуйте `spaces/` або `users/`. -- `channels.googlechat.dangerouslyAllowNameMatching` повторно вмикає зіставлення за змінним email principal (режим сумісності на крайній випадок). +- JSON service account: вбудований (`serviceAccount`) або файловий (`serviceAccountFile`). +- Також підтримується SecretRef для service account (`serviceAccountRef`). +- Резервні значення з env: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- Використовуйте `spaces/` або `users/` для цілей доставки. +- `channels.googlechat.dangerouslyAllowNameMatching` повторно вмикає зіставлення за змінюваними email principal-ами (режим сумісності break-glass). ### Slack @@ -464,35 +464,35 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він } ``` -- **Режим socket** вимагає і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` як резервні значення змінних середовища для типового облікового запису). -- **HTTP mode** вимагає `botToken` плюс `signingSecret` (у корені або для окремого облікового запису). -- `botToken`, `appToken`, `signingSecret` і `userToken` приймають звичайні текстові +- **Socket mode** потребує і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` для резервного env-варіанта типового облікового запису). +- **HTTP mode** потребує `botToken` плюс `signingSecret` (у корені або для окремого облікового запису). +- `botToken`, `appToken`, `signingSecret` і `userToken` приймають відкриті рядки або об’єкти SecretRef. - Знімки облікових записів Slack показують поля джерела/статусу для кожних облікових даних, такі як `botTokenSource`, `botTokenStatus`, `appTokenStatus` і, у HTTP mode, `signingSecretStatus`. `configured_unavailable` означає, що обліковий запис налаштовано через SecretRef, але поточний шлях команди/runtime не зміг визначити значення секрету. -- `configWrites: false` блокує записи конфігурації, ініційовані зі Slack. -- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. -- `channels.slack.streaming.mode` — канонічний ключ режиму потокової передачі Slack. `channels.slack.streaming.nativeTransport` керує нативним транспортом потокової передачі Slack. Застарілі значення `streamMode`, булеві значення `streaming` і `nativeStreaming` автоматично мігруються. -- Для цілей доставки використовуйте `user:` (DM) або `channel:`. +- `configWrites: false` блокує ініційовані Slack записи конфігурації. +- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- `channels.slack.streaming.mode` — це канонічний ключ режиму потоку Slack. `channels.slack.streaming.nativeTransport` керує нативним потоковим транспортом Slack. Застарілі значення `streamMode`, булеві значення `streaming` і `nativeStreaming` мігруються автоматично. +- Використовуйте `user:` (DM) або `channel:` для цілей доставки. **Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`). -**Ізоляція сесій гілок:** `thread.historyScope` — окремо для кожної гілки (типово) або спільно на канал. `thread.inheritParent` копіює журнал батьківського каналу в нові гілки. +**Ізоляція сесій тредів:** `thread.historyScope` є або на рівні треду (типово), або спільним для каналу. `thread.inheritParent` копіює транскрипт батьківського каналу в нові треди. -- Нативна потокова передача Slack разом зі статусом гілки Slack у стилі assistant "is typing..." потребують ціль відповіді у гілці. DM верхнього рівня типово лишаються поза гілками, тому використовують `typingReaction` або звичайну доставку замість попереднього перегляду у стилі гілки. -- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а потім видаляє її після завершення. Використовуйте shortcode emoji Slack, наприклад `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: нативна для Slack доставка погоджень exec і авторизація погоджувачів. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). +- Нативний потоковий режим Slack разом зі статусом треду Slack у стилі assistant "is typing..." потребують ціль відповіді у треді. DM верхнього рівня типово залишаються поза тредом, тому використовують `typingReaction` або звичайну доставку замість попереднього перегляду в стилі треду. +- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а після завершення прибирає її. Використовуйте shortcode emoji Slack, наприклад `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: нативна для Slack доставка запитів на exec-схвалення та авторизація тих, хто може їх схвалювати. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). -| Група дій | Типово | Примітки | -| ------------ | -------- | ---------------------- | -| reactions | увімкнено | Реакція + список реакцій | -| messages | увімкнено | Читання/надсилання/редагування/видалення | -| pins | увімкнено | Закріплення/відкріплення/список | -| memberInfo | увімкнено | Інформація про учасника | -| emojiList | увімкнено | Список власних emoji | +| Група дій | Типово | Примітки | +| ----------- | -------- | -------------------------- | +| reactions | увімкнено | Реакції + перелік реакцій | +| messages | увімкнено | Читання/надсилання/редагування/видалення | +| pins | увімкнено | Закріплення/відкріплення/перелік | +| memberInfo | увімкнено | Інформація про учасника | +| emojiList | увімкнено | Список користувацьких emoji | ### Mattermost @@ -526,23 +526,23 @@ Mattermost постачається як Plugin: `openclaw plugins install @open } ``` -Режими чату: `oncall` (відповідати на @-згадування, типово), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з префікса тригера). +Режими чату: `oncall` (відповідати на @-згадку, типово), `onmessage` (на кожне повідомлення), `onchar` (на повідомлення, що починаються з тригерного префікса). -Коли нативні команди Mattermost увімкнені: +Коли нативні команди Mattermost увімкнено: -- `commands.callbackPath` має бути шляхом (наприклад, `/api/channels/mattermost/command`), а не повним URL. +- `commands.callbackPath` має бути шляхом (наприклад `/api/channels/mattermost/command`), а не повним URL. - `commands.callbackUrl` має вказувати на endpoint Gateway OpenClaw і бути доступним із сервера Mattermost. -- Нативні slash callback-и автентифікуються за допомогою токенів для кожної команди, які - Mattermost повертає під час реєстрації slash-команд. Якщо реєстрація не вдається або - жодну команду не активовано, OpenClaw відхиляє callback-и з +- Нативні callback-и slash-команд автентифікуються за токенами для кожної команди, які Mattermost повертає + під час реєстрації slash-команд. Якщо реєстрація не вдається або жодну + команду не активовано, OpenClaw відхиляє callback-и з `Unauthorized: invalid command token.` -- Для приватних/tailnet/internal хостів callback-ів Mattermost може вимагати, +- Для приватних/tailnet/внутрішніх хостів callback-ів Mattermost може вимагати, щоб `ServiceSettings.AllowedUntrustedInternalConnections` містив хост/домен callback-а. Використовуйте значення хоста/домену, а не повні URL. -- `channels.mattermost.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з Mattermost. +- `channels.mattermost.configWrites`: дозволити або заборонити ініційовані Mattermost записи конфігурації. - `channels.mattermost.requireMention`: вимагати `@mention` перед відповіддю в каналах. -- `channels.mattermost.groups..requireMention`: перевизначення обмеження за згадкою на рівні каналу (`"*"` для типового значення). -- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. +- `channels.mattermost.groups..requireMention`: перевизначення gating за згадками для окремого каналу (`"*"` для типового значення). +- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. ### Signal @@ -565,13 +565,13 @@ Mattermost постачається як Plugin: `openclaw plugins install @open **Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`). -- `channels.signal.account`: закріпити запуск каналу за конкретною ідентичністю облікового запису Signal. -- `channels.signal.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з Signal. -- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. +- `channels.signal.account`: прив’язати запуск каналу до конкретної ідентичності облікового запису Signal. +- `channels.signal.configWrites`: дозволити або заборонити ініційовані Signal записи конфігурації. +- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. ### BlueBubbles -BlueBubbles — рекомендований шлях для iMessage (на основі Plugin, налаштовується в `channels.bluebubbles`). +BlueBubbles — рекомендований шлях для iMessage (із підтримкою Plugin, налаштовується в `channels.bluebubbles`). ```json5 { @@ -586,14 +586,14 @@ BlueBubbles — рекомендований шлях для iMessage (на ос } ``` -- Основні шляхи ключів, описані тут: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. -- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних ACP-сесій. Використовуйте дескриптор BlueBubbles або рядок цілі (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- Базові шляхи ключів, що охоплюються тут: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. +- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних ACP-сесій. Використовуйте handle або рядок цілі BlueBubbles (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). - Повну конфігурацію каналу BlueBubbles задокументовано в [BlueBubbles](/uk/channels/bluebubbles). ### iMessage -OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Не потрібні ані демон, ані порт. +OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Демон або порт не потрібні. ```json5 { @@ -617,15 +617,15 @@ OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Не потр } ``` -- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. +- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. -- Потрібен Full Disk Access до БД Messages. +- Потрібен Full Disk Access до DB Messages. - Надавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб переглянути список чатів. -- `cliPath` може вказувати на SSH-обгортку; задайте `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP. +- `cliPath` може вказувати на обгортку SSH; задайте `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP. - `attachmentRoots` і `remoteAttachmentRoots` обмежують шляхи вхідних вкладень (типово: `/Users/*/Library/Messages/Attachments`). -- SCP використовує сувору перевірку ключа хоста, тож переконайтеся, що ключ хоста relay уже існує в `~/.ssh/known_hosts`. -- `channels.imessage.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з iMessage. -- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до постійних ACP-сесій. Використовуйте нормалізований дескриптор або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- SCP використовує сувору перевірку ключа хоста, тому переконайтеся, що ключ хоста relay вже існує в `~/.ssh/known_hosts`. +- `channels.imessage.configWrites`: дозволити або заборонити ініційовані iMessage записи конфігурації. +- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до постійних ACP-сесій. Використовуйте нормалізований handle або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). @@ -638,7 +638,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix підтримується Plugin і налаштовується в `channels.matrix`. +Matrix підтримується через Plugin і налаштовується в `channels.matrix`. ```json5 { @@ -668,25 +668,25 @@ Matrix підтримується Plugin і налаштовується в `cha } ``` -- Автентифікація токеном використовує `accessToken`; автентифікація паролем використовує `userId` + `password`. -- `channels.matrix.proxy` маршрутизує HTTP-трафік Matrix через явно вказаний HTTP(S)-проксі. Іменовані облікові записи можуть перевизначати його через `channels.matrix.accounts..proxy`. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` дозволяє приватні/internal homeserver-и. `proxy` і цей мережевий opt-in — незалежні елементи керування. +- Автентифікація за токеном використовує `accessToken`; автентифікація за паролем використовує `userId` + `password`. +- `channels.matrix.proxy` маршрутизує HTTP-трафік Matrix через явний HTTP(S) proxy. Іменовані облікові записи можуть перевизначити його через `channels.matrix.accounts..proxy`. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` дозволяє приватні/внутрішні homeserver-и. `proxy` і цей opt-in для мережі є незалежними елементами керування. - `channels.matrix.defaultAccount` вибирає бажаний обліковий запис у багатооблікових конфігураціях. -- `channels.matrix.autoJoin` типово має значення `off`, тому запрошені кімнати та нові запрошення у стилі DM ігноруються, доки ви не задасте `autoJoin: "allowlist"` з `autoJoinAllowlist` або `autoJoin: "always"`. -- `channels.matrix.execApprovals`: нативна для Matrix доставка погоджень exec і авторизація погоджувачів. - - `enabled`: `true`, `false` або `"auto"` (типово). В автоматичному режимі погодження exec активуються, коли погоджувачів можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ID користувачів Matrix (наприклад, `@owner:example.org`), яким дозволено погоджувати exec-запити. - - `agentFilter`: необов’язковий allowlist ID агентів. Якщо пропустити, погодження пересилаються для всіх агентів. +- `channels.matrix.autoJoin` типово має значення `off`, тому запрошені кімнати та нові запрошення в стилі DM ігноруються, доки ви не задасте `autoJoin: "allowlist"` із `autoJoinAllowlist` або `autoJoin: "always"`. +- `channels.matrix.execApprovals`: нативна для Matrix доставка запитів на exec-схвалення та авторизація тих, хто може їх схвалювати. + - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto exec-схвалення активуються, коли тих, хто схвалює, можна визначити з `approvers` або `commands.ownerAllowFrom`. + - `approvers`: ID користувачів Matrix (наприклад `@owner:example.org`), яким дозволено схвалювати exec-запити. + - `agentFilter`: необов’язковий allowlist ID агентів. Не вказуйте, щоб пересилати схвалення для всіх агентів. - `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або regex). - - `target`: куди надсилати запити на погодження. `"dm"` (типово), `"channel"` (вихідна кімната) або `"both"`. - - Перевизначення на рівні облікового запису: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` керує тим, як DM Matrix групуються в сесії: `per-user` (типово) спільно використовує сесію за маршрутизованим peer, тоді як `per-room` ізолює кожну DM-кімнату. -- Перевірки статусу Matrix і live-пошук у каталозі використовують ту саму політику проксі, що й runtime-трафік. -- Повну конфігурацію Matrix, правила таргетингу та приклади налаштування задокументовано в [Matrix](/uk/channels/matrix). + - `target`: куди надсилати запити на схвалення. `"dm"` (типово), `"channel"` (вихідна кімната) або `"both"`. + - Перевизначення для окремого облікового запису: `channels.matrix.accounts..execApprovals`. +- `channels.matrix.dm.sessionScope` керує тим, як Matrix DM групуються в сесії: `per-user` (типово) спільне групування за маршрутизованим peer, тоді як `per-room` ізолює кожну DM-кімнату. +- Перевірки статусу Matrix і живі пошуки в каталозі використовують ту саму політику proxy, що й трафік runtime. +- Повну конфігурацію Matrix, правила вибору цілей і приклади налаштування задокументовано в [Matrix](/uk/channels/matrix). ### Microsoft Teams -Microsoft Teams підтримується Plugin і налаштовується в `channels.msteams`. +Microsoft Teams підтримується через Plugin і налаштовується в `channels.msteams`. ```json5 { @@ -701,12 +701,12 @@ Microsoft Teams підтримується Plugin і налаштовуєтьс } ``` -- Основні шляхи ключів, описані тут: `channels.msteams`, `channels.msteams.configWrites`. +- Базові шляхи ключів, що охоплюються тут: `channels.msteams`, `channels.msteams.configWrites`. - Повну конфігурацію Teams (облікові дані, webhook, політика DM/груп, перевизначення для окремих team/channel) задокументовано в [Microsoft Teams](/uk/channels/msteams). ### IRC -IRC підтримується Plugin і налаштовується в `channels.irc`. +IRC підтримується через Plugin і налаштовується в `channels.irc`. ```json5 { @@ -727,9 +727,9 @@ IRC підтримується Plugin і налаштовується в `channe } ``` -- Основні шляхи ключів, описані тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. -- Повну конфігурацію каналу IRC (host/port/TLS/channels/allowlists/обмеження за згадками) задокументовано в [IRC](/uk/channels/irc). +- Базові шляхи ключів, що охоплюються тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- Повну конфігурацію каналу IRC (host/port/TLS/channels/allowlist-и/gating за згадками) задокументовано в [IRC](/uk/channels/irc). ### Багатообліковість (усі канали) @@ -755,27 +755,27 @@ IRC підтримується Plugin і налаштовується в `channe ``` - `default` використовується, коли `accountId` пропущено (CLI + маршрутизація). -- Токени середовища застосовуються лише до облікового запису **default**. -- Базові налаштування каналу застосовуються до всіх облікових записів, якщо не перевизначені для окремого облікового запису. +- Токени з env застосовуються лише до облікового запису **default**. +- Базові налаштування каналу застосовуються до всіх облікових записів, якщо їх не перевизначено для окремого облікового запису. - Використовуйте `bindings[].match.accountId`, щоб маршрутизувати кожен обліковий запис до іншого агента. -- Якщо ви додаєте не-типовий обліковий запис через `openclaw channels add` (або онбординг каналу), поки ще використовуєте однооблікову конфігурацію каналу верхнього рівня, OpenClaw спочатку переносить значення верхнього рівня для одного облікового запису, прив’язані до облікового запису, у карту облікових записів каналу, щоб початковий обліковий запис і далі працював. Більшість каналів переміщують їх у `channels..accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/default ціль. -- Наявні прив’язки лише на рівні каналу (без `accountId`) і далі відповідають типовому обліковому запису; прив’язки на рівні облікового запису залишаються необов’язковими. -- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи значення верхнього рівня для одного облікового запису, прив’язані до облікового запису, у promoted account, вибраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/default ціль. +- Якщо ви додаєте не-типовий обліковий запис через `openclaw channels add` (або onboarding каналу), поки ще використовуєте однокористувацьку конфігурацію каналу верхнього рівня, OpenClaw спочатку переносить значення верхнього рівня для одного облікового запису, прив’язані до облікового запису, у map облікових записів каналу, щоб початковий обліковий запис і далі працював. Більшість каналів переміщують їх у `channels..accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль. +- Наявні прив’язки лише до каналу (без `accountId`) і далі відповідають типовому обліковому запису; прив’язки на рівні облікового запису залишаються необов’язковими. +- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи значення верхнього рівня для одного облікового запису, прив’язані до облікового запису, у підвищений обліковий запис, вибраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль. ### Інші канали Plugin -Багато каналів Plugin налаштовуються як `channels.` і задокументовані на власних сторінках каналів (наприклад, Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). +Багато каналів Plugin налаштовуються як `channels.` і задокументовані на власних сторінках каналів (наприклад Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). Див. повний індекс каналів: [Channels](/uk/channels). -### Обмеження за згадками в групових чатах +### Gating за згадками в групових чатах -Для групових повідомлень типово **потрібна згадка** (метадані згадки або безпечні regex-шаблони). Застосовується до групових чатів WhatsApp, Telegram, Discord, Google Chat та iMessage. +Для групових повідомлень типово **потрібна згадка** (метадані згадки або безпечні regex-шаблони). Це застосовується до групових чатів WhatsApp, Telegram, Discord, Google Chat та iMessage. **Типи згадок:** - **Згадки в метаданих**: нативні @-згадки платформи. Ігноруються в режимі self-chat WhatsApp. -- **Текстові шаблони**: безпечні regex-шаблони в `agents.list[].groupChat.mentionPatterns`. Некоректні шаблони та небезпечне вкладене повторення ігноруються. -- Обмеження за згадками застосовується лише тоді, коли виявлення можливе (нативні згадки або принаймні один шаблон). +- **Текстові шаблони**: безпечні regex-шаблони в `agents.list[].groupChat.mentionPatterns`. Некоректні шаблони й небезпечне вкладене повторення ігноруються. +- Gating за згадками застосовується лише тоді, коли виявлення можливе (нативні згадки або принаймні один шаблон). ```json5 { @@ -788,7 +788,7 @@ IRC підтримується Plugin і налаштовується в `channe } ``` -`messages.groupChat.historyLimit` задає глобальне значення за замовчуванням. Канали можуть перевизначати його через `channels..historyLimit` (або на рівні облікового запису). Встановіть `0`, щоб вимкнути. +`messages.groupChat.historyLimit` задає глобальне типове значення. Канали можуть перевизначити його через `channels..historyLimit` (або для окремого облікового запису). Установіть `0`, щоб вимкнути. #### Ліміти історії DM @@ -805,7 +805,7 @@ IRC підтримується Plugin і налаштовується в `channe } ``` -Порядок визначення: перевизначення для окремого DM → значення провайдера за замовчуванням → без ліміту (зберігається все). +Порядок визначення: перевизначення для окремого DM → типове значення провайдера → без обмеження (зберігається все). Підтримується: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. @@ -861,30 +861,30 @@ IRC підтримується Plugin і налаштовується в `channe -- Цей блок налаштовує поверхні команд. Поточний каталог вбудованих + bundled команд див. у [Slash Commands](/uk/tools/slash-commands). -- Ця сторінка — **довідник ключів конфігурації**, а не повний каталог команд. Команди, що належать каналу/плагіну, такі як QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` і Talk `/voice`, задокументовані на сторінках відповідних каналів/плагінів, а також у [Slash Commands](/uk/tools/slash-commands). +- Цей блок налаштовує поверхні команд. Поточний каталог вбудованих + комплектних команд див. у [Slash Commands](/uk/tools/slash-commands). +- Ця сторінка — **довідник ключів конфігурації**, а не повний каталог команд. Команди, що належать каналу/Plugin, такі як QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` і Talk `/voice`, задокументовано на сторінках їхніх каналів/Plugin, а також у [Slash Commands](/uk/tools/slash-commands). - Текстові команди мають бути **окремими** повідомленнями з початковим `/`. - `native: "auto"` вмикає нативні команди для Discord/Telegram, залишає Slack вимкненим. - `nativeSkills: "auto"` вмикає нативні команди Skills для Discord/Telegram, залишає Slack вимкненим. - Перевизначення для окремого каналу: `channels.discord.commands.native` (bool або `"auto"`). `false` очищає раніше зареєстровані команди. - Перевизначайте реєстрацію нативних команд Skills для окремого каналу через `channels..commands.nativeSkills`. - `channels.telegram.customCommands` додає додаткові записи меню бота Telegram. -- `bash: true` вмикає `! ` для оболонки хоста. Потрібні `tools.elevated.enabled` і відправник у `tools.elevated.allowFrom.`. -- `config: true` вмикає `/config` (читання/запис `openclaw.json`). Для клієнтів Gateway `chat.send` постійні записи `/config set|unset` також потребують `operator.admin`; доступний лише для читання `/config show` лишається доступним для звичайних клієнтів оператора з правами запису. +- `bash: true` вмикає `! ` для оболонки хоста. Потребує `tools.elevated.enabled` і відправника в `tools.elevated.allowFrom.`. +- `config: true` вмикає `/config` (читання/запис у `openclaw.json`). Для клієнтів gateway `chat.send` постійні записи `/config set|unset` також потребують `operator.admin`; лише для читання `/config show` і далі доступний звичайним клієнтам operator з областю запису. - `mcp: true` вмикає `/mcp` для конфігурації MCP-сервера, яким керує OpenClaw, у `mcp.servers`. -- `plugins: true` вмикає `/plugins` для пошуку Plugin, встановлення та керування ввімкненням/вимкненням. +- `plugins: true` вмикає `/plugins` для виявлення plugin-ів, встановлення та керування ввімкненням/вимкненням. - `channels..configWrites` керує мутаціями конфігурації для окремого каналу (типово: true). -- Для багатооблікових каналів `channels..accounts..configWrites` також керує записами, націленими на цей обліковий запис (наприклад, `/allowlist --config --account ` або `/config set channels..accounts....`). -- `restart: false` вимикає `/restart` і дії інструмента перезапуску Gateway. Типове значення: `true`. -- `ownerAllowFrom` — це явний список дозволених власників для команд/інструментів лише для власника. Він окремий від `allowFrom`. -- `ownerDisplay: "hash"` хешує id власників у system prompt. Задайте `ownerDisplaySecret`, щоб керувати хешуванням. -- `allowFrom` задається окремо для кожного провайдера. Якщо його встановлено, це **єдине** джерело авторизації (списки дозволених каналу/сполучення та `useAccessGroups` ігноруються). -- `useAccessGroups: false` дозволяє командам обходити політики груп доступу, якщо `allowFrom` не задано. +- Для багатооблікових каналів `channels..accounts..configWrites` також керує записами, що націлені на цей обліковий запис (наприклад `/allowlist --config --account ` або `/config set channels..accounts....`). +- `restart: false` вимикає `/restart` і дії інструмента перезапуску gateway. Типово: `true`. +- `ownerAllowFrom` — це явний allowlist власника для команд/інструментів лише для власника. Він відокремлений від `allowFrom`. +- `ownerDisplay: "hash"` хешує ID власника в system prompt. Установіть `ownerDisplaySecret`, щоб керувати хешуванням. +- `allowFrom` є прив’язаним до провайдера. Якщо його задано, це **єдине** джерело авторизації (allowlist-и каналів/pairing і `useAccessGroups` ігноруються). +- `useAccessGroups: false` дозволяє командам обходити політики access-group, коли `allowFrom` не задано. - Карта документації команд: - - каталог вбудованих + bundled: [Slash Commands](/uk/tools/slash-commands) - - поверхні команд, специфічні для каналів: [Channels](/uk/channels) + - каталог вбудованих + комплектних команд: [Slash Commands](/uk/tools/slash-commands) + - поверхні команд, специфічні для каналу: [Channels](/uk/channels) - команди QQ Bot: [QQ Bot](/uk/channels/qqbot) - - команди сполучення: [Pairing](/uk/channels/pairing) + - команди pairing: [Pairing](/uk/channels/pairing) - команда картки LINE: [LINE](/uk/channels/line) - memory dreaming: [Dreaming](/uk/concepts/dreaming) @@ -892,7 +892,7 @@ IRC підтримується Plugin і налаштовується в `channe --- -## Значення агентів за замовчуванням +## Типові параметри агентів ### `agents.defaults.workspace` @@ -906,7 +906,7 @@ IRC підтримується Plugin і налаштовується в `channe ### `agents.defaults.repoRoot` -Необов’язковий корінь репозиторію, що показується в рядку Runtime системного prompt. Якщо не задано, OpenClaw автоматично визначає його, піднімаючись угору від workspace. +Необов’язковий корінь репозиторію, який показується в рядку Runtime system prompt. Якщо не задано, OpenClaw визначає його автоматично, піднімаючись вгору від workspace. ```json5 { @@ -916,7 +916,7 @@ IRC підтримується Plugin і налаштовується в `channe ### `agents.defaults.skills` -Необов’язковий типовий список дозволених Skills для агентів, які не задають +Необов’язковий типовий allowlist Skills для агентів, які не задають `agents.list[].skills`. ```json5 @@ -932,9 +932,9 @@ IRC підтримується Plugin і налаштовується в `channe } ``` -- Пропустіть `agents.defaults.skills`, щоб типово не обмежувати Skills. -- Пропустіть `agents.list[].skills`, щоб успадкувати типові значення. -- Встановіть `agents.list[].skills: []`, щоб не використовувати жодних Skills. +- Не вказуйте `agents.defaults.skills`, щоб типово дозволити всі Skills без обмежень. +- Не вказуйте `agents.list[].skills`, щоб успадкувати типові значення. +- Установіть `agents.list[].skills: []`, щоб не було жодних Skills. - Непорожній список `agents.list[].skills` є остаточним набором для цього агента; він не об’єднується з типовими значеннями. @@ -952,7 +952,7 @@ IRC підтримується Plugin і налаштовується в `channe Керує тим, коли bootstrap-файли workspace вбудовуються в system prompt. Типове значення: `"always"`. -- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторне вбудовування bootstrap workspace, зменшуючи розмір prompt. Запуски Heartbeat і повторні спроби після Compaction все одно перебудовують контекст. +- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторне вбудовування bootstrap workspace, зменшуючи розмір prompt. Запуски Heartbeat і повтори після Compaction усе одно перебудовують контекст. ```json5 { @@ -962,7 +962,7 @@ IRC підтримується Plugin і налаштовується в `channe ### `agents.defaults.bootstrapMaxChars` -Максимум символів на один bootstrap-файл workspace до усікання. Типове значення: `12000`. +Максимальна кількість символів на bootstrap-файл workspace перед обрізанням. Типове значення: `12000`. ```json5 { @@ -972,7 +972,7 @@ IRC підтримується Plugin і налаштовується в `channe ### `agents.defaults.bootstrapTotalMaxChars` -Максимальна загальна кількість символів, що вбудовуються з усіх bootstrap-файлів workspace. Типове значення: `60000`. +Максимальна загальна кількість символів, що вбудовуються через усі bootstrap-файли workspace. Типове значення: `60000`. ```json5 { @@ -982,12 +982,12 @@ IRC підтримується Plugin і налаштовується в `channe ### `agents.defaults.bootstrapPromptTruncationWarning` -Керує видимим для агента текстом попередження, коли bootstrap-контекст усічено. +Керує текстом попередження, видимим агенту, коли bootstrap-контекст обрізається. Типове значення: `"once"`. - `"off"`: ніколи не вбудовувати текст попередження в system prompt. -- `"once"`: вбудовувати попередження один раз для кожного унікального сигнатурного усікання (рекомендовано). -- `"always"`: вбудовувати попередження під час кожного запуску, коли є усікання. +- `"once"`: вбудовувати попередження один раз для кожного унікального підпису обрізання (рекомендовано). +- `"always"`: вбудовувати попередження при кожному запуску, коли є обрізання. ```json5 { @@ -995,24 +995,24 @@ IRC підтримується Plugin і налаштовується в `channe } ``` -### Карта відповідальності за бюджет контексту +### Карта володіння бюджетами контексту OpenClaw має кілька великих бюджетів prompt/контексту, і вони -навмисно розділені за підсистемами, а не проходять через один загальний -параметр. +навмисно розділені за підсистемами замість того, щоб проходити через один +загальний параметр. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: звичайне вбудовування bootstrap workspace. - `agents.defaults.startupContext.*`: - одноразова стартова преамбула для `/new` і `/reset`, включно з недавніми - файлами `memory/*.md` за днями. + одноразовий стартовий прелюд для `/new` і `/reset`, включно з нещодавніми щоденними + файлами `memory/*.md`. - `skills.limits.*`: компактний список Skills, вбудований у system prompt. - `agents.defaults.contextLimits.*`: обмежені runtime-витяги та вбудовані блоки, що належать runtime. - `memory.qmd.limits.*`: - розмір фрагментів індексованого пошуку пам’яті та вбудовування. + розміри snippet-ів індексованого пошуку memory та їх вбудовування. Використовуйте відповідне перевизначення для окремого агента лише тоді, коли одному агенту потрібен інший бюджет: @@ -1022,7 +1022,7 @@ OpenClaw має кілька великих бюджетів prompt/контек #### `agents.defaults.startupContext` -Керує стартовою преамбулою першого ходу, яка вбудовується під час звичайних запусків `/new` і `/reset`. +Керує стартовим прелюдом першого ходу, який вбудовується в bare-запуски `/new` і `/reset`. ```json5 { @@ -1060,18 +1060,18 @@ OpenClaw має кілька великих бюджетів prompt/контек } ``` -- `memoryGetMaxChars`: типовий ліміт витягу `memory_get` до того, як буде додано - метадані усікання та повідомлення про продовження. +- `memoryGetMaxChars`: типовий ліміт уривка `memory_get` перед тим, як буде додано + метадані обрізання та повідомлення про продовження. - `memoryGetDefaultLines`: типове вікно рядків `memory_get`, коли `lines` - пропущено. -- `toolResultMaxChars`: поточний ліміт результатів інструментів, який використовується для збережених результатів і + не вказано. +- `toolResultMaxChars`: ліміт результату інструмента в live-режимі, який використовується для збережених результатів і відновлення після переповнення. -- `postCompactionMaxChars`: ліміт витягу AGENTS.md, який використовується під час вбудовування +- `postCompactionMaxChars`: ліміт уривка AGENTS.md, який використовується під час вбудовування оновлення після Compaction. #### `agents.list[].contextLimits` -Перевизначення для окремого агента для спільних параметрів `contextLimits`. Пропущені поля успадковуються +Перевизначення для окремого агента для спільних параметрів `contextLimits`. Поля, які не вказані, успадковуються з `agents.defaults.contextLimits`. ```json5 @@ -1214,50 +1214,50 @@ OpenClaw має кілька великих бюджетів prompt/контек ``` - `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Рядкова форма задає лише основну модель. - - Форма об’єкта задає основну модель плюс впорядковані failover-моделі. + - Форма рядка задає лише основну модель. + - Форма об’єкта задає основну модель плюс впорядковані моделі failover. - `imageModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується шляхом інструмента `image` як його конфігурація vision-моделі. - Також використовується як резервна маршрутизація, коли вибрана/типова модель не може приймати вхідні зображення. - `imageGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею інструмента/Plugin, що генерує зображення. - Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal або `openai/gpt-image-2` для OpenAI Images. - - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну автентифікацію провайдера/API key (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`). - - Якщо поле пропущено, `image_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку воно пробує поточного типового провайдера, а потім — інші зареєстровані провайдери генерації зображень у порядку id провайдера. + - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію провайдера/API key (наприклад `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`). + - Якщо не вказано, `image_generate` усе одно може визначити типове значення провайдера з підтримкою автентифікації. Спочатку він пробує поточного типового провайдера, потім решту зареєстрованих провайдерів генерації зображень у порядку provider-id. - `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації музики та вбудованим інструментом `music_generate`. - Типові значення: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` або `minimax/music-2.5+`. - - Якщо поле пропущено, `music_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку воно пробує поточного типового провайдера, а потім — інші зареєстровані провайдери генерації музики в порядку id провайдера. - - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну автентифікацію провайдера/API key. + - Якщо не вказано, `music_generate` усе одно може визначити типове значення провайдера з підтримкою автентифікації. Спочатку він пробує поточного типового провайдера, потім решту зареєстрованих провайдерів генерації музики в порядку provider-id. + - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію провайдера/API key. - `videoGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації відео та вбудованим інструментом `video_generate`. - Типові значення: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` або `qwen/wan2.7-r2v`. - - Якщо поле пропущено, `video_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку воно пробує поточного типового провайдера, а потім — інші зареєстровані провайдери генерації відео в порядку id провайдера. - - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну автентифікацію провайдера/API key. - - Bundled провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` і `watermark`. + - Якщо не вказано, `video_generate` усе одно може визначити типове значення провайдера з підтримкою автентифікації. Спочатку він пробує поточного типового провайдера, потім решту зареєстрованих провайдерів генерації відео в порядку provider-id. + - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію провайдера/API key. + - Комплектний провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість до 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` та `watermark`. - `pdfModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується інструментом `pdf` для маршрутизації моделі. - - Якщо поле пропущено, інструмент PDF спершу повертається до `imageModel`, а потім — до визначеної моделі сесії/типової моделі. + - Якщо не вказано, інструмент PDF повертається до `imageModel`, а потім до визначеної моделі сесії/типової моделі. - `pdfMaxBytesMb`: типовий ліміт розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику. -- `pdfMaxPages`: типова максимальна кількість сторінок, яка враховується в режимі резервного вилучення інструмента `pdf`. +- `pdfMaxPages`: типова максимальна кількість сторінок, що враховуються в режимі резервного витягування інструмента `pdf`. - `verboseDefault`: типовий рівень verbose для агентів. Значення: `"off"`, `"on"`, `"full"`. Типове значення: `"off"`. - `elevatedDefault`: типовий рівень elevated-output для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типове значення: `"on"`. -- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.4`). Якщо ви пропускаєте провайдера, OpenClaw спочатку пробує alias, потім — унікальний збіг exact model id серед налаштованих провайдерів, і лише після цього повертається до налаштованого типового провайдера (застаріла поведінка сумісності, тому краще явно вказувати `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw повертається до першого налаштованого provider/model замість того, щоб показувати застаріле типове значення видаленого провайдера. +- `model.primary`: формат `provider/model` (наприклад `openai/gpt-5.4`). Якщо ви пропускаєте провайдера, OpenClaw спочатку пробує псевдонім, потім унікальний збіг налаштованого провайдера для цього точного id моделі, і лише після цього повертається до налаштованого типового провайдера (застаріла поведінка сумісності, тому надавайте перевагу явному `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw повертається до першого налаштованого provider/model замість того, щоб показувати застаріле типове значення видаленого провайдера. - `models`: налаштований каталог моделей і allowlist для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`). - - Безпечні зміни: використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додавати записи. `config set` відмовляє в замінах, які видалили б наявні записи allowlist, якщо ви не передасте `--replace`. - - Потоки configure/onboarding на рівні провайдера об’єднують вибрані моделі провайдера в цю мапу й зберігають уже налаштованих, але не пов’язаних провайдерів. -- `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад, `{ cacheRetention: "long" }`). -- Пріоритет об’єднання `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для окремої моделі), а потім `agents.list[].params` (для відповідного id агента) перевизначає за ключами. Докладніше див. [Prompt Caching](/uk/reference/prompt-caching). -- `embeddedHarness`: типова низькорівнева політика runtime для вбудованого агента. Використовуйте `runtime: "auto"`, щоб дозволити зареєстрованим Plugin harness брати на себе підтримувані моделі, `runtime: "pi"` — щоб примусово використовувати вбудований harness PI, або зареєстрований id harness, наприклад `runtime: "codex"`. Встановіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід до PI. -- Засоби запису конфігурації, які змінюють ці поля (наприклад, `/models set`, `/models set-image` і команди add/remove для резервних варіантів), зберігають канонічну форму об’єкта та, коли можливо, зберігають наявні списки резервних варіантів. -- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно серіалізується). Типове значення: 4. + - Безпечне редагування: використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додавати записи. `config set` відмовляє в замінах, які прибрали б наявні записи allowlist, якщо не передати `--replace`. + - Потоки configure/onboarding на рівні провайдера об’єднують вибрані моделі провайдера в цю map і зберігають уже налаштованих, не пов’язаних провайдерів. +- `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад `{ cacheRetention: "long" }`). +- Пріоритет злиття `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для окремої моделі), потім `agents.list[].params` (для відповідного id агента) перевизначає за ключем. Докладніше див. у [Prompt Caching](/uk/reference/prompt-caching). +- `embeddedHarness`: типова політика низькорівневого runtime вбудованого агента. Використовуйте `runtime: "auto"`, щоб дозволити зареєстрованим harness-ам Plugin брати на себе підтримувані моделі, `runtime: "pi"`, щоб примусово використовувати вбудований harness PI, або id зареєстрованого harness-а, наприклад `runtime: "codex"`. Установіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід на PI. +- Записувачі конфігурації, які змінюють ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення fallback), зберігають канонічну форму об’єкта і за можливості зберігають наявні списки fallback. +- `maxConcurrent`: максимальна кількість паралельних запусків агентів у різних сесіях (кожна сесія все одно виконується послідовно). Типове значення: 4. ### `agents.defaults.embeddedHarness` `embeddedHarness` керує тим, який низькорівневий виконавець запускає ходи вбудованого агента. -У більшості розгортань варто залишити типове значення `{ runtime: "auto", fallback: "pi" }`. -Використовуйте це, коли довірений Plugin надає нативний harness, наприклад bundled -app-server harness Codex. +Більшість розгортань мають залишити типове значення `{ runtime: "auto", fallback: "pi" }`. +Використовуйте це, коли довірений Plugin надає нативний harness, наприклад комплектний +harness app-server Codex. ```json5 { @@ -1273,15 +1273,15 @@ app-server harness Codex. } ``` -- `runtime`: `"auto"`, `"pi"` або id зареєстрованого Plugin harness. Bundled Plugin Codex реєструє `codex`. -- `fallback`: `"pi"` або `"none"`. `"pi"` зберігає вбудований harness PI як сумісний резервний варіант, коли жоден Plugin harness не вибрано. `"none"` призводить до помилки, якщо вибраний Plugin harness відсутній або не підтримується, замість тихого використання PI. Збої вибраного Plugin harness завжди показуються безпосередньо. -- Перевизначення середовища: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` вимикає резервний перехід до PI для цього процесу. -- Для розгортань лише з Codex встановіть `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` і `embeddedHarness.fallback: "none"`. -- Це керує лише вбудованим chat harness. Генерація медіа, vision, PDF, музика, відео та TTS і далі використовують свої налаштування provider/model. +- `runtime`: `"auto"`, `"pi"` або id зареєстрованого harness-а Plugin. Комплектний Plugin Codex реєструє `codex`. +- `fallback`: `"pi"` або `"none"`. `"pi"` зберігає вбудований harness PI як резервний варіант сумісності, коли жоден harness Plugin не вибрано. `"none"` призводить до помилки, якщо вибір harness-а Plugin відсутній або не підтримується, замість тихого використання PI. Збої вибраного harness-а Plugin завжди показуються напряму. +- Перевизначення через середовище: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` вимикає резервний перехід на PI для цього процесу. +- Для розгортань лише з Codex установіть `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` і `embeddedHarness.fallback: "none"`. +- Це керує лише вбудованим chat harness. Генерація медіа, vision, PDF, музика, відео і TTS і далі використовують свої налаштування provider/model. -**Вбудовані скорочення alias** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): +**Скорочені вбудовані псевдоніми** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): -| Alias | Модель | +| Псевдонім | Модель | | ------------------- | -------------------------------------- | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | @@ -1292,15 +1292,15 @@ app-server harness Codex. | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Ваші налаштовані alias завжди мають пріоритет над типовими. +Ваші налаштовані псевдоніми завжди мають пріоритет над типовими. Моделі Z.AI GLM-4.x автоматично вмикають режим thinking, якщо ви не задасте `--thinking off` або самі не визначите `agents.defaults.models["zai/"].params.thinking`. -Моделі Z.AI типово вмикають `tool_stream` для потокової передачі викликів інструментів. Встановіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути це. +Моделі Z.AI типово вмикають `tool_stream` для потокової передачі викликів інструментів. Установіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути це. Моделі Anthropic Claude 4.6 типово використовують `adaptive` thinking, коли явний рівень thinking не задано. ### `agents.defaults.cliBackends` -Необов’язкові backend-и CLI для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери не працюють. +Необов’язкові backend-и CLI для резервних запусків лише з текстом (без викликів інструментів). Корисно як резервний варіант, коли API-провайдери недоступні. ```json5 { @@ -1330,7 +1330,7 @@ app-server harness Codex. - Backend-и CLI орієнтовані на текст; інструменти завжди вимкнені. - Сесії підтримуються, коли задано `sessionArg`. -- Передача зображень підтримується, коли `imageArg` приймає шляхи до файлів. +- Передавання зображень підтримується, коли `imageArg` приймає шляхи до файлів. ### `agents.defaults.systemPromptOverride` @@ -1346,6 +1346,28 @@ app-server harness Codex. } ``` +### `agents.defaults.promptOverlays` + +Незалежні від провайдера накладки prompt, що застосовуються за сімейством моделей. ID моделей сімейства GPT-5 отримують спільний контракт поведінки для всіх провайдерів; `personality` керує лише шаром дружнього стилю взаємодії. + +```json5 +{ + agents: { + defaults: { + promptOverlays: { + gpt5: { + personality: "friendly", // friendly | on | off + }, + }, + }, + }, +} +``` + +- `"friendly"` (типово) і `"on"` вмикають шар дружнього стилю взаємодії. +- `"off"` вимикає лише дружній шар; позначений контракт поведінки GPT-5 лишається ввімкненим. +- Застарілий `plugins.entries.openai.config.personality` і далі зчитується, коли це спільне налаштування не задано. + ### `agents.defaults.heartbeat` Періодичні запуски Heartbeat. @@ -1375,15 +1397,15 @@ app-server harness Codex. } ``` -- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація через API key) або `1h` (автентифікація через OAuth). Встановіть `0m`, щоб вимкнути. +- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація через API key) або `1h` (автентифікація через OAuth). Установіть `0m`, щоб вимкнути. - `includeSystemPromptSection`: коли `false`, прибирає розділ Heartbeat із system prompt і пропускає вбудовування `HEARTBEAT.md` у bootstrap-контекст. Типове значення: `true`. -- `suppressToolErrorWarnings`: коли `true`, приглушує payload-и попереджень про помилки інструментів під час запусків Heartbeat. -- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента Heartbeat до його переривання. Якщо не задано, використовується `agents.defaults.timeoutSeconds`. -- `directPolicy`: політика прямої доставки/DM. `allow` (типово) дозволяє доставку на пряму ціль. `block` приглушує доставку на пряму ціль і видає `reason=dm-blocked`. +- `suppressToolErrorWarnings`: коли `true`, пригнічує payload-и попереджень про помилки інструментів під час запусків Heartbeat. +- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента Heartbeat, після чого його буде перервано. Якщо не задано, використовується `agents.defaults.timeoutSeconds`. +- `directPolicy`: політика прямої доставки/доставки в DM. `allow` (типово) дозволяє доставку на пряму ціль. `block` пригнічує доставку на пряму ціль і виводить `reason=dm-blocked`. - `lightContext`: коли `true`, запуски Heartbeat використовують полегшений bootstrap-контекст і зберігають лише `HEARTBEAT.md` із bootstrap-файлів workspace. -- `isolatedSession`: коли `true`, кожен запуск Heartbeat виконується в новій сесії без попередньої історії розмови. Та сама схема ізоляції, що й у Cron `sessionTarget: "isolated"`. Зменшує вартість токенів на один Heartbeat приблизно зі ~100K до ~2-5K токенів. -- Для окремого агента: задайте `agents.list[].heartbeat`. Якщо будь-який агент визначає `heartbeat`, Heartbeat запускаються **лише для цих агентів**. -- Heartbeat запускає повноцінні ходи агента — коротші інтервали спалюють більше токенів. +- `isolatedSession`: коли `true`, кожен Heartbeat запускається в новій сесії без попередньої історії розмови. Той самий шаблон ізоляції, що й у Cron `sessionTarget: "isolated"`. Зменшує вартість токенів на один Heartbeat приблизно зі ~100K до ~2-5K токенів. +- Для окремого агента: задайте `agents.list[].heartbeat`. Коли будь-який агент визначає `heartbeat`, Heartbeat запускаються **лише для цих агентів**. +- Heartbeat виконує повні ходи агента — коротші інтервали спалюють більше токенів. ### `agents.defaults.compaction` @@ -1397,15 +1419,15 @@ app-server harness Codex. timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Зберігайте id розгортань, id тікетів і пари host:port точно без змін.", // used when identifierPolicy=custom + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override notifyUser: true, // send brief notices when compaction starts and completes (default: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "Сесія наближається до Compaction. Збережіть тривалі спогади зараз.", - prompt: "Запишіть усі довготривалі нотатки в memory/YYYY-MM-DD.md; якщо зберігати нічого, дайте відповідь точним тихим токеном NO_REPLY.", + systemPrompt: "Session nearing compaction. Store durable memories now.", + prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.", }, }, }, @@ -1413,19 +1435,19 @@ app-server harness Codex. } ``` -- `mode`: `default` або `safeguard` (підсумовування довгої історії частинами). Див. [Compaction](/uk/concepts/compaction). -- `provider`: id зареєстрованого Plugin провайдера Compaction. Якщо задано, замість вбудованого підсумовування LLM викликається `summarize()` цього провайдера. У разі збою відбувається повернення до вбудованого варіанта. Встановлення провайдера примусово задає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). +- `mode`: `default` або `safeguard` (підсумовування чанками для довгої історії). Див. [Compaction](/uk/concepts/compaction). +- `provider`: id зареєстрованого Plugin провайдера Compaction. Якщо задано, замість вбудованого LLM-підсумовування викликається `summarize()` цього провайдера. У разі помилки відбувається повернення до вбудованого варіанта. Установлення провайдера примусово задає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). - `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції Compaction, після чого OpenClaw її перериває. Типове значення: `900`. -- `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає вбудовані вказівки щодо збереження непрозорих ідентифікаторів під час підсумовування Compaction. -- `identifierInstructions`: необов’язковий власний текст про збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`. -- `postCompactionSections`: необов’язкові назви секцій H2/H3 з AGENTS.md, які повторно вбудовуються після Compaction. Типово `["Session Startup", "Red Lines"]`; задайте `[]`, щоб вимкнути повторне вбудовування. Якщо поле не задано або явно задано цю типову пару, старі заголовки `Every Session`/`Safety` також приймаються як резервний застарілий варіант. -- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування Compaction. Використовуйте це, коли основна сесія має залишатися на одній моделі, а підсумки Compaction — виконуватися на іншій; якщо не задано, Compaction використовує основну модель сесії. -- `notifyUser`: якщо `true`, надсилає короткі сповіщення користувачеві, коли Compaction починається й коли завершується (наприклад, "Compacting context..." і "Compaction complete"). Типово вимкнено, щоб Compaction залишався безшумним. -- `memoryFlush`: безшумний хід агента перед автоматичним Compaction для збереження тривалих спогадів. Пропускається, якщо workspace доступний лише для читання. +- `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає вбудовані інструкції щодо збереження непрозорих ідентифікаторів під час підсумовування Compaction. +- `identifierInstructions`: необов’язковий користувацький текст щодо збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`. +- `postCompactionSections`: необов’язкові назви розділів H2/H3 з AGENTS.md, які потрібно повторно вбудувати після Compaction. Типове значення — `["Session Startup", "Red Lines"]`; задайте `[]`, щоб вимкнути повторне вбудовування. Коли значення не задано або явно задано цю типову пару, старі заголовки `Every Session`/`Safety` також приймаються як резервний варіант для сумісності. +- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування Compaction. Використовуйте це, коли основна сесія має залишатися на одній моделі, а підсумки Compaction повинні виконуватися на іншій; якщо не задано, Compaction використовує основну модель сесії. +- `notifyUser`: коли `true`, надсилає користувачу короткі сповіщення, коли Compaction починається і коли завершується (наприклад, "Compacting context..." і "Compaction complete"). Типово вимкнено, щоб Compaction залишався безшумним. +- `memoryFlush`: безшумний хід агента перед автоматичним Compaction для збереження тривалих memory. Пропускається, коли workspace доступний лише для читання. ### `agents.defaults.contextPruning` -Обрізає **старі результати інструментів** з контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску. +Обрізає **старі результати інструментів** із контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску. ```json5 { @@ -1450,24 +1472,24 @@ app-server harness Codex. - `mode: "cache-ttl"` вмикає проходи обрізання. -- `ttl` керує тим, як часто обрізання може запускатися знову (після останнього звернення до кешу). +- `ttl` керує тим, як часто обрізання може запускатися знову (після останнього торкання кешу). - Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім, якщо потрібно, повністю очищає старіші результати інструментів. -**М’яке скорочення** зберігає початок і кінець та вставляє `...` посередині. +**М’яке обрізання** зберігає початок + кінець і вставляє `...` посередині. -**Повне очищення** замінює весь результат інструмента заповнювачем. +**Жорстке очищення** замінює весь результат інструмента на заповнювач. Примітки: -- Блоки зображень ніколи не скорочуються й не очищаються. -- Співвідношення базуються на кількості символів (приблизно), а не на точній кількості токенів. +- Блоки зображень ніколи не обрізаються/не очищаються. +- Співвідношення базуються на символах (приблизно), а не на точних кількостях токенів. - Якщо існує менше ніж `keepLastAssistants` повідомлень асистента, обрізання пропускається. -Деталі поведінки див. у [Session Pruning](/uk/concepts/session-pruning). +Див. [Session Pruning](/uk/concepts/session-pruning) для деталей поведінки. -### Блокова потокова передача +### Блочний streaming ```json5 { @@ -1483,13 +1505,13 @@ app-server harness Codex. } ``` -- Канали, відмінні від Telegram, потребують явного `*.blockStreaming: true`, щоб увімкнути блокові відповіді. -- Перевизначення на рівні каналу: `channels..blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat типово `minChars: 1500`. -- `humanDelay`: випадкова пауза між блоковими відповідями. `natural` = 800–2500 мс. Перевизначення для окремого агента: `agents.list[].humanDelay`. +- Канали, крім Telegram, потребують явного `*.blockStreaming: true`, щоб увімкнути блочні відповіді. +- Перевизначення для каналу: `channels..blockStreamingCoalesce` (і варіанти для окремого облікового запису). Signal/Slack/Discord/Google Chat типово мають `minChars: 1500`. +- `humanDelay`: випадкова пауза між блочними відповідями. `natural` = 800–2500ms. Перевизначення для окремого агента: `agents.list[].humanDelay`. -Деталі поведінки й нарізання блоків див. у [Streaming](/uk/concepts/streaming). +Див. [Streaming](/uk/concepts/streaming) для деталей поведінки та чанкування. -### Індикатори набору +### Індикатори набору тексту ```json5 { @@ -1502,8 +1524,8 @@ app-server harness Codex. } ``` -- Типові значення: `instant` для прямих чатів/згадок, `message` для групових чатів без згадки. -- Перевизначення для окремої сесії: `session.typingMode`, `session.typingIntervalSeconds`. +- Типові значення: `instant` для прямих чатів/згадок, `message` для групових чатів без згадок. +- Перевизначення для сесії: `session.typingMode`, `session.typingIntervalSeconds`. Див. [Typing Indicators](/uk/concepts/typing-indicators). @@ -1511,7 +1533,7 @@ app-server harness Codex. ### `agents.defaults.sandbox` -Необов’язкова sandbox-ізоляція для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing). +Необов’язкова sandbox-ізоляція для вбудованого агента. Повний посібник див. в [Sandboxing](/uk/gateway/sandboxing). ```json5 { @@ -1611,18 +1633,18 @@ app-server harness Codex. **Backend:** - `docker`: локальний runtime Docker (типово) -- `ssh`: універсальний віддалений runtime на основі SSH +- `ssh`: універсальний віддалений runtime на базі SSH - `openshell`: runtime OpenShell -Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переміщуються до +Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переносяться в `plugins.entries.openshell.config`. **Конфігурація backend SSH:** -- `target`: ціль SSH у форматі `user@host[:port]` +- `target`: ціль SSH у формі `user@host[:port]` - `command`: команда SSH-клієнта (типово: `ssh`) -- `workspaceRoot`: абсолютний віддалений корінь, що використовується для workspace за кожною областю -- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, що передаються до OpenSSH +- `workspaceRoot`: абсолютний віддалений корінь, що використовується для workspace за scope +- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, які передаються в OpenSSH - `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, які OpenClaw матеріалізує у тимчасові файли під час runtime - `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH @@ -1631,27 +1653,27 @@ app-server harness Codex. - `identityData` має пріоритет над `identityFile` - `certificateData` має пріоритет над `certificateFile` - `knownHostsData` має пріоритет над `knownHostsFile` -- Значення `*Data` на основі SecretRef визначаються з активного знімка runtime секретів до початку сесії sandbox +- Значення `*Data`, що працюють через SecretRef, визначаються з активного знімка runtime секретів до початку sandbox-сесії **Поведінка backend SSH:** - один раз ініціалізує віддалений workspace після створення або повторного створення -- далі зберігає віддалений SSH-workspace як канонічний +- потім підтримує віддалений SSH workspace як канонічний - маршрутизує `exec`, файлові інструменти та шляхи медіа через SSH - не синхронізує віддалені зміни назад на хост автоматично -- не підтримує браузерні контейнери sandbox +- не підтримує browser-контейнери sandbox **Доступ до workspace:** -- `none`: workspace sandbox за кожною областю в `~/.openclaw/sandboxes` +- `none`: workspace sandbox за scope у `~/.openclaw/sandboxes` - `ro`: workspace sandbox у `/workspace`, workspace агента монтується лише для читання в `/agent` -- `rw`: workspace агента монтується для читання/запису в `/workspace` +- `rw`: workspace агента монтується на читання/запис у `/workspace` -**Область:** +**Scope:** - `session`: окремий контейнер + workspace для кожної сесії - `agent`: один контейнер + workspace на агента (типово) -- `shared`: спільний контейнер і workspace (без ізоляції між сесіями) +- `shared`: спільний контейнер і workspace (без міжсесійної ізоляції) **Конфігурація Plugin OpenShell:** @@ -1681,30 +1703,30 @@ app-server harness Codex. **Режим OpenShell:** -- `mirror`: ініціалізувати віддалений простір із локального перед exec, синхронізувати назад після exec; локальний workspace лишається канонічним -- `remote`: один раз ініціалізувати віддалений простір під час створення sandbox, далі зберігати віддалений workspace як канонічний +- `mirror`: перед `exec` заповнювати віддалений простір із локального, після `exec` синхронізувати назад; локальний workspace лишається канонічним +- `remote`: один раз заповнювати віддалений простір під час створення sandbox, а далі вважати канонічним саме віддалений workspace -У режимі `remote` локальні зміни на хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після кроку ініціалізації. -Транспортом є SSH до sandbox OpenShell, але життєвим циклом sandbox і необов’язковою mirror-синхронізацією керує Plugin. +У режимі `remote` локальні редагування на хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після кроку початкового заповнення. +Транспортом є SSH до sandbox OpenShell, але Plugin керує життєвим циклом sandbox і необов’язковою синхронізацією mirror. -**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує виходу в мережу, кореневої файлової системи з можливістю запису та користувача root. +**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує вихідного мережевого доступу, доступного для запису кореня і root-користувача. -**Типово контейнери використовують `network: "none"`** — встановіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихід назовні. -`"host"` заблоковано. `"container:"` типово також заблоковано, якщо ви явно не встановите -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний режим). +**Контейнери типово використовують `network: "none"`** — установіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ. +`"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не встановите +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (режим break-glass). -**Вхідні вкладення** розміщуються в `media/inbound/*` в активному workspace. +**Вхідні вкладення** розміщуються в `media/inbound/*` активного workspace. **`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки для окремого агента об’єднуються. -**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вбудовується в system prompt. Не потребує `browser.enabled` у `openclaw.json`. -Доступ спостерігача через noVNC типово використовує автентифікацію VNC, а OpenClaw видає URL із короткоживучим токеном (замість того, щоб показувати пароль у спільному URL). +**Sandbox-браузер** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вбудовується в system prompt. Не потребує `browser.enabled` у `openclaw.json`. +Доступ спостерігача через noVNC типово використовує VNC-автентифікацію, а OpenClaw видає URL із короткоживучим токеном (замість того, щоб розкривати пароль у спільному URL). -- `allowHostControl: false` (типово) блокує для sandbox-сесій націлювання на браузер хоста. -- `network` типово має значення `openclaw-sandbox-browser` (виділена bridge-мережа). Встановлюйте `bridge` лише тоді, коли вам явно потрібна глобальна bridge-підключеність. -- `cdpSourceRange` за потреби обмежує вхід CDP на межі контейнера до діапазону CIDR (наприклад, `172.21.0.1/32`). -- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер браузера sandbox. Якщо задано (включно з `[]`), воно замінює `docker.binds` для контейнера браузера. -- Типові параметри запуску визначено в `scripts/sandbox-browser-entrypoint.sh` і налаштовано для хостів контейнерів: +- `allowHostControl: false` (типово) блокує sandbox-сесіям націлювання на браузер хоста. +- `network` типово має значення `openclaw-sandbox-browser` (виділена bridge-мережа). Установлюйте `bridge` лише тоді, коли вам явно потрібна глобальна зв’язність bridge. +- `cdpSourceRange` необов’язково обмежує вхідний доступ CDP на межі контейнера до діапазону CIDR (наприклад `172.21.0.1/32`). +- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер sandbox-браузера. Якщо задано (включно з `[]`), воно замінює `docker.binds` для контейнера браузера. +- Типові параметри запуску визначено в `scripts/sandbox-browser-entrypoint.sh` і налаштовано для хостів із контейнерами: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1724,19 +1746,19 @@ app-server harness Codex. - `--disable-extensions` (типово ввімкнено) - `--disable-3d-apis`, `--disable-software-rasterizer` і `--disable-gpu` типово ввімкнені й можуть бути вимкнені через - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо це потрібно для WebGL/3D. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` повторно вмикає розширення, якщо ваш workflow + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо для використання WebGL/3D це потрібно. + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` повторно вмикає розширення, якщо ваш робочий процес залежить від них. - `--renderer-process-limit=2` можна змінити через - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; встановіть `0`, щоб використовувати + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; установіть `0`, щоб використовувати типовий ліміт процесів Chromium. - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли ввімкнено `noSandbox`. - - Типові значення є базовими для образу контейнера; щоб змінити типові параметри контейнера, - використовуйте власний образ браузера з власним entrypoint. + - Типові значення є базою образу контейнера; щоб змінити типові параметри контейнера, використовуйте + власний образ браузера з власним entrypoint. -Браузерна sandbox-ізоляція та `sandbox.docker.binds` доступні лише для Docker. +Ізоляція браузера та `sandbox.docker.binds` працюють лише з Docker. Зібрати образи: @@ -1795,26 +1817,26 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - `id`: стабільний id агента (обов’язково). -- `default`: якщо задано для кількох агентів, перший має пріоритет (логуються попередження). Якщо не задано ні для кого, типовим є перший запис у списку. -- `model`: рядкова форма перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallbacks). Cron-завдання, які перевизначають лише `primary`, усе одно успадковують типові fallbacks, якщо ви не задасте `fallbacks: []`. -- `params`: параметри потоку для окремого агента, об’єднані поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для перевизначень, специфічних для агента, як-от `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. -- `skills`: необов’язковий allowlist Skills для окремого агента. Якщо пропущено, агент успадковує `agents.defaults.skills`, коли його задано; явний список замінює типові значення замість об’єднання, а `[]` означає відсутність Skills. -- `thinkingDefault`: необов’язковий типовий рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, якщо не задано перевизначення для окремого повідомлення або сесії. -- `reasoningDefault`: необов’язкове типове значення видимості reasoning для окремого агента (`on | off | stream`). Застосовується, якщо не задано перевизначення reasoning для окремого повідомлення або сесії. -- `fastModeDefault`: необов’язкове типове значення fast mode для окремого агента (`true | false`). Застосовується, якщо не задано перевизначення fast mode для окремого повідомлення або сесії. -- `embeddedHarness`: необов’язкове перевизначення низькорівневої політики harness для окремого агента. Використовуйте `{ runtime: "codex", fallback: "none" }`, щоб зробити один агент лише Codex, тоді як інші агенти зберігатимуть типовий резервний перехід до PI. -- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово працювати в ACP harness-сесіях. +- `default`: коли задано кілька значень, перше має пріоритет (записується попередження). Якщо не задано жодного, типовим є перший запис у списку. +- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallback). Cron-завдання, які перевизначають лише `primary`, усе одно успадковують типові fallback, якщо ви не задасте `fallbacks: []`. +- `params`: параметри stream для окремого агента, що зливаються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для специфічних для агента перевизначень, як-от `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. +- `skills`: необов’язковий allowlist Skills для окремого агента. Якщо не задано, агент успадковує `agents.defaults.skills`, коли це значення задане; явний список замінює типові значення замість злиття, а `[]` означає відсутність Skills. +- `thinkingDefault`: необов’язкове типове значення рівня thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, коли не задано перевизначення для окремого повідомлення або сесії. +- `reasoningDefault`: необов’язкове типове значення видимості reasoning для окремого агента (`on | off | stream`). Застосовується, коли не задано перевизначення reasoning для окремого повідомлення або сесії. +- `fastModeDefault`: необов’язкове типове значення fast mode для окремого агента (`true | false`). Застосовується, коли не задано перевизначення fast-mode для окремого повідомлення або сесії. +- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для окремого агента. Використовуйте `{ runtime: "codex", fallback: "none" }`, щоб зробити один агент лише для Codex, тоді як інші агенти зберігатимуть типовий fallback на PI. +- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати сесії harness ACP. - `identity.avatar`: шлях відносно workspace, URL `http(s)` або URI `data:`. -- `identity` виводить типові значення: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`. +- `identity` виводить типові значення: `ackReaction` із `emoji`, `mentionPatterns` із `name`/`emoji`. - `subagents.allowAgents`: allowlist id агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). -- Захист успадкування sandbox: якщо сесія-запитувач працює в sandbox, `sessions_spawn` відхиляє цілі, які працювали б без sandbox. -- `subagents.requireAgentId`: якщо `true`, блокує виклики `sessions_spawn`, у яких пропущено `agentId` (примушує до явного вибору профілю; типово: false). +- Захист успадкування sandbox: якщо сесія-запитувач виконується в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без sandbox. +- `subagents.requireAgentId`: коли `true`, блокує виклики `sessions_spawn`, у яких пропущено `agentId` (примушує до явного вибору профілю; типово: false). --- -## Маршрутизація між агентами +## Маршрутизація кількох агентів -Запускайте кілька ізольованих агентів усередині одного Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). +Запускайте кількох ізольованих агентів усередині одного Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). ```json5 { @@ -1831,27 +1853,27 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -### Поля відповідності прив’язок +### Поля зіставлення binding -- `type` (необов’язково): `route` для звичайної маршрутизації (якщо тип відсутній, типово використовується route), `acp` для постійних ACP-прив’язок розмов. +- `type` (необов’язково): `route` для звичайної маршрутизації (відсутнє значення `type` типово означає route), `acp` для постійних ACP-прив’язок розмов. - `match.channel` (обов’язково) -- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; якщо пропущено = типовий обліковий запис) +- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; пропущено = типовий обліковий запис) - `match.peer` (необов’язково; `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` (необов’язково; специфічні для каналу) +- `match.guildId` / `match.teamId` (необов’язково; специфічно для каналу) - `acp` (необов’язково; лише для записів `type: "acp"`): `{ mode, label, cwd, backend }` -**Детермінований порядок відповідності:** +**Детермінований порядок зіставлення:** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` 4. `match.accountId` (точний збіг, без peer/guild/team) -5. `match.accountId: "*"` (на весь канал) +5. `match.accountId: "*"` (для всього каналу) 6. Типовий агент -У межах кожного рівня перемагає перший запис `bindings`, що збігся. +У межах кожного рівня перший відповідний запис `bindings` має пріоритет. -Для записів `type: "acp"` OpenClaw визначає відповідність за точною ідентичністю розмови (`match.channel` + account + `match.peer.id`) і не використовує порядок рівнів route-прив’язок, наведений вище. +Для записів `type: "acp"` OpenClaw виконує пошук за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує описаний вище порядок рівнів прив’язок route. ### Профілі доступу для окремих агентів @@ -1873,7 +1895,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1902,7 +1924,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1948,7 +1970,7 @@ scripts/sandbox-browser-setup.sh # optional browser image -Подробиці щодо пріоритетів див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). +Див. [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools) для деталей пріоритетності. --- @@ -1999,36 +2021,36 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` - + -- **`scope`**: базова стратегія групування сесій для контекстів групового чату. +- **`scope`**: базова стратегія групування сесій для контекстів групових чатів. - `per-sender` (типово): кожен відправник отримує ізольовану сесію в межах контексту каналу. - - `global`: усі учасники в контексті каналу використовують одну спільну сесію (використовуйте лише тоді, коли справді потрібен спільний контекст). + - `global`: усі учасники в контексті каналу спільно використовують одну сесію (використовуйте лише тоді, коли потрібен спільний контекст). - **`dmScope`**: як групуються DM. - - `main`: усі DM використовують спільну основну сесію. + - `main`: усі DM спільно використовують основну сесію. - `per-peer`: ізоляція за id відправника між каналами. - - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для inbox з кількома користувачами). - - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для багатооблікових конфігурацій). -- **`identityLinks`**: відображення канонічних id на peers із префіксами провайдера для спільного використання сесій між каналами. -- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовані обидва варіанти, спрацьовує той, що настане раніше. -- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застарілий `dm` приймається як alias для `direct`. -- **`parentForkMaxTokens`**: максимальний `totalTokens` батьківської сесії, дозволений під час створення forked session для гілки (типове значення `100000`). - - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw запускає нову сесію гілки замість успадкування історії transcript батьківської сесії. - - Встановіть `0`, щоб вимкнути цей захист і завжди дозволяти fork від батьківської сесії. -- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для основного bucket прямих чатів. -- **`agentToAgent.maxPingPongTurns`**: максимальна кількість зворотних ходів відповіді між агентами під час обміну агент-до-агента (ціле число, діапазон: `0`–`5`). `0` вимикає ping-pong chaining. -- **`sendPolicy`**: відповідність за `channel`, `chatType` (`direct|group|channel`, із застарілим alias `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона, що збіглася, має пріоритет. -- **`maintenance`**: очищення сховища сесій + керування retention. + - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для багато користувацьких inbox). + - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для багатообліковості). +- **`identityLinks`**: map канонічних id до peer-ів із префіксом провайдера для спільного використання сесій між каналами. +- **`reset`**: основна політика reset. `daily` виконує reset о `atHour` за локальним часом; `idle` виконує reset після `idleMinutes`. Коли налаштовано обидва варіанти, перемагає той, що спливає першим. +- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застарілий `dm` приймається як псевдонім для `direct`. +- **`parentForkMaxTokens`**: максимальне значення `totalTokens` батьківської сесії, дозволене під час створення форкнутої тред-сесії (типово `100000`). + - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw запускає нову тред-сесію замість успадкування історії транскрипту батьківської сесії. + - Установіть `0`, щоб вимкнути цей захист і завжди дозволяти форк від батьківської сесії. +- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для основного кошика direct-chat. +- **`agentToAgent.maxPingPongTurns`**: максимальна кількість ходів відповіді у відповідь між агентами під час обмінів agent-to-agent (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжок ping-pong. +- **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим псевдонімом `dm`), `keyPrefix` або `rawKeyPrefix`. Перше deny має пріоритет. +- **`maintenance`**: керування очищенням + зберіганням сховища сесій. - `mode`: `warn` лише виводить попередження; `enforce` застосовує очищення. - `pruneAfter`: віковий поріг для застарілих записів (типово `30d`). - `maxEntries`: максимальна кількість записів у `sessions.json` (типово `500`). - - `rotateBytes`: ротація `sessions.json`, коли файл перевищує цей розмір (типово `10mb`). - - `resetArchiveRetention`: retention для архівів transcript `*.reset.`. Типово дорівнює `pruneAfter`; встановіть `false`, щоб вимкнути. - - `maxDiskBytes`: необов’язковий жорсткий бюджет диска для каталогу сесій. У режимі `warn` лише логуються попередження; у режимі `enforce` спочатку видаляються найстаріші артефакти/сесії. - - `highWaterBytes`: необов’язкова ціль після очищення бюджету. Типово `80%` від `maxDiskBytes`. -- **`threadBindings`**: глобальні типові значення для функцій сесій, прив’язаних до гілок. + - `rotateBytes`: ротація `sessions.json`, коли його розмір перевищує це значення (типово `10mb`). + - `resetArchiveRetention`: строк зберігання архівів транскриптів `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. + - `maxDiskBytes`: необов’язковий жорсткий бюджет дискового простору для каталогу сесій. У режимі `warn` він записує попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії. + - `highWaterBytes`: необов’язкова ціль після очищення за бюджетом. Типово дорівнює `80%` від `maxDiskBytes`. +- **`threadBindings`**: глобальні типові значення для функцій сесій, прив’язаних до тредів. - `enabled`: головний типовий перемикач (провайдери можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`) - - `idleHours`: типове автоматичне зняття focus через неактивність у годинах (`0` вимикає; провайдери можуть перевизначати) + - `idleHours`: типове автоматичне зняття фокусу через неактивність у годинах (`0` вимикає; провайдери можуть перевизначати) - `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; провайдери можуть перевизначати) @@ -2067,36 +2089,36 @@ scripts/sandbox-browser-setup.sh # optional browser image ### Префікс відповіді -Перевизначення для окремого каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. +Перевизначення для каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Порядок визначення (найспецифічніше значення перемагає): обліковий запис → канал → глобальне. `""` вимикає й зупиняє каскадування. `"auto"` формує `[{identity.name}]`. +Порядок визначення (найспецифічніше має пріоритет): обліковий запис → канал → глобальне значення. `""` вимикає й зупиняє каскад. `"auto"` виводить `[{identity.name}]`. **Змінні шаблону:** -| Змінна | Опис | Приклад | -| ---------------- | ---------------------- | --------------------------- | -| `{model}` | Коротка назва моделі | `claude-opus-4-6` | +| Змінна | Опис | Приклад | +| ---------------- | --------------------- | --------------------------- | +| `{model}` | Коротка назва моделі | `claude-opus-4-6` | | `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | -| `{provider}` | Назва провайдера | `anthropic` | -| `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` | -| `{identity.name}` | Ім’я identity агента | (те саме, що `"auto"`) | +| `{provider}` | Назва провайдера | `anthropic` | +| `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` | +| `{identity.name}` | Ім’я identity агента | (те саме, що й `"auto"`) | -Змінні нечутливі до регістру. `{think}` — alias для `{thinkingLevel}`. +Змінні нечутливі до регістру. `{think}` — псевдонім для `{thinkingLevel}`. -### Реакція підтвердження +### Реакція-підтвердження -- Типово використовується `identity.emoji` активного агента, інакше `"👀"`. Встановіть `""`, щоб вимкнути. -- Перевизначення для окремого каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення identity. -- Область: `group-mentions` (типово), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: прибирає ack після відповіді у Slack, Discord і Telegram. -- `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу у Slack, Discord і Telegram. - У Slack і Discord, якщо не задано, реакції статусу залишаються ввімкненими, коли активні ack-реакції. - У Telegram потрібно явно встановити `true`, щоб увімкнути реакції статусу життєвого циклу. +- Типово використовується `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути. +- Перевизначення для каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. +- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення від identity. +- Scope: `group-mentions` (типово), `group-all`, `direct`, `all`. +- `removeAckAfterReply`: прибирає підтвердження після відповіді в Slack, Discord і Telegram. +- `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу в Slack, Discord і Telegram. + У Slack і Discord відсутнє значення зберігає реакції статусу ввімкненими, коли активні реакції-підтвердження. + У Telegram явно встановіть це значення в `true`, щоб увімкнути реакції статусу життєвого циклу. -### Debounce вхідних повідомлень +### Вхідний debounce -Об’єднує швидкі текстові повідомлення від одного відправника в один хід агента. Медіа/вкладення скидають буфер негайно. Керувальні команди обходять debounce. +Об’єднує швидкі текстові повідомлення від одного й того самого відправника в один хід агента. Медіа/вкладення скидаються негайно. Керувальні команди обходять debounce. ### TTS (text-to-speech) @@ -2139,12 +2161,12 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `auto` керує типовим режимом auto-TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначити локальні налаштування, а `/tts status` показує фактичний стан. -- `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного summary. +- `auto` керує типовим режимом auto-TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначити локальні prefs, а `/tts status` показує фактичний стан. +- `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумку. - `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово має значення `false` (opt-in). - API key використовують резервні значення `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. - `openai.baseUrl` перевизначає endpoint OpenAI TTS. Порядок визначення: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. -- Коли `openai.baseUrl` вказує на endpoint, відмінний від OpenAI, OpenClaw трактує його як OpenAI-compatible TTS-сервер і послаблює валідацію model/voice. +- Коли `openai.baseUrl` вказує на endpoint, що не належить OpenAI, OpenClaw трактує його як OpenAI-сумісний TTS-сервер і послаблює валідацію моделі/голосу. --- @@ -2174,13 +2196,13 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `talk.provider` має відповідати ключу в `talk.providers`, коли налаштовано кілька провайдерів Talk. -- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) підтримуються лише для сумісності та автоматично мігруються в `talk.providers.`. -- Для Voice ID використовуються резервні значення `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. -- `providers.*.apiKey` приймає звичайні текстові рядки або об’єкти SecretRef. -- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли не налаштовано API key Talk. -- `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні назви. -- `silenceTimeoutMs` керує тим, скільки Talk mode чекає після мовчання користувача, перш ніж надсилати transcript. Якщо не задано, зберігається типове вікно паузи платформи (`700 ms на macOS і Android, 900 ms на iOS`). +- `talk.provider` має збігатися з ключем у `talk.providers`, коли налаштовано кілька провайдерів Talk. +- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) призначені лише для сумісності й автоматично мігруються до `talk.providers.`. +- Voice ID використовують резервні значення `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. +- `providers.*.apiKey` приймає відкриті рядки або об’єкти SecretRef. +- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли не налаштовано API key для Talk. +- `providers.*.voiceAliases` дозволяє директивам Talk використовувати зручні назви. +- `silenceTimeoutMs` керує тим, скільки режим Talk чекає після тиші користувача, перш ніж надіслати транскрипт. Якщо не задано, зберігається типове вікно паузи платформи (`700 ms на macOS і Android, 900 ms на iOS`). --- @@ -2190,35 +2212,35 @@ scripts/sandbox-browser-setup.sh # optional browser image `tools.profile` задає базовий allowlist перед `tools.allow`/`tools.deny`: -Локальний онбординг типово встановлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явні профілі зберігаються). +Локальний onboarding типово встановлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явні профілі зберігаються). -| Профіль | Містить | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------ | -| `minimal` | лише `session_status` | -| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | -| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Без обмежень (те саме, що й без значення) | +| Профіль | Містить | +| ---------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `minimal` | лише `session_status` | +| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | +| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `full` | Без обмежень (те саме, що й відсутнє значення) | ### Групи інструментів -| Група | Інструменти | -| ----------------- | --------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як alias для `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | -| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation`| `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Усі вбудовані інструменти (без Plugin провайдерів) | +| Група | Інструменти | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------ | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як псевдонім для `exec`) | +| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | +| `group:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation` | `cron`, `gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:openclaw` | Усі вбудовані інструменти (без урахування Plugin провайдерів) | ### `tools.allow` / `tools.deny` -Глобальна політика дозволу/заборони інструментів (заборона має пріоритет). Нечутлива до регістру, підтримує wildcard `*`. Застосовується навіть тоді, коли Docker sandbox вимкнено. +Глобальна політика дозволу/заборони інструментів (deny має пріоритет). Нечутлива до регістру, підтримує wildcard-и `*`. Застосовується навіть тоді, коли sandbox Docker вимкнено. ```json5 { @@ -2244,7 +2266,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.elevated` -Керує доступом elevated exec поза sandbox: +Керує підвищеним доступом exec поза sandbox: ```json5 { @@ -2262,7 +2284,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - Перевизначення для окремого агента (`agents.list[].tools.elevated`) може лише додатково обмежувати. - `/elevated on|off|ask|full` зберігає стан для кожної сесії; вбудовані директиви застосовуються до одного повідомлення. -- Elevated `exec` обходить sandbox і використовує налаштований шлях виходу (`gateway` типово або `node`, коли ціль `exec` — це `node`). +- Підвищений `exec` обходить sandbox-ізоляцію й використовує налаштований шлях виходу (`gateway` типово або `node`, коли ціллю exec є `node`). ### `tools.exec` @@ -2286,8 +2308,8 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.loopDetection` -Перевірки безпеки від циклів інструментів **типово вимкнені**. Установіть `enabled: true`, щоб увімкнути виявлення. -Параметри можна визначати глобально в `tools.loopDetection` і перевизначати для окремого агента в `agents.list[].tools.loopDetection`. +Перевірки безпеки циклів інструментів типово **вимкнені**. Установіть `enabled: true`, щоб увімкнути виявлення. +Параметри можна задавати глобально в `tools.loopDetection` і перевизначати для окремого агента в `agents.list[].tools.loopDetection`. ```json5 { @@ -2312,9 +2334,9 @@ scripts/sandbox-browser-setup.sh # optional browser image - `warningThreshold`: поріг повторюваного шаблону без прогресу для попереджень. - `criticalThreshold`: вищий поріг повторення для блокування критичних циклів. - `globalCircuitBreakerThreshold`: поріг жорсткої зупинки для будь-якого запуску без прогресу. -- `detectors.genericRepeat`: попереджати про повторні виклики того самого інструмента з тими самими аргументами. +- `detectors.genericRepeat`: попереджати про повторювані виклики одного й того самого інструмента з тими самими аргументами. - `detectors.knownPollNoProgress`: попереджати/блокувати відомі poll-інструменти (`process.poll`, `command_status` тощо). -- `detectors.pingPong`: попереджати/блокувати чергування шаблонів пар без прогресу. +- `detectors.pingPong`: попереджати/блокувати чергування парних шаблонів без прогресу. - Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, валідація завершується помилкою. ### `tools.web` @@ -2392,21 +2414,21 @@ scripts/sandbox-browser-setup.sh # optional browser image **Запис CLI** (`type: "cli"`): - `command`: виконуваний файл для запуску -- `args`: шаблонізовані аргументи (підтримуються `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо) +- `args`: шаблонізовані аргументи (підтримує `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо) **Спільні поля:** - `capabilities`: необов’язковий список (`image`, `audio`, `video`). Типові значення: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: перевизначення для окремого запису. -- У разі помилки використовується наступний запис. +- У разі помилки відбувається перехід до наступного запису. -Автентифікація провайдера дотримується стандартного порядку: `auth-profiles.json` → змінні середовища → `models.providers.*.apiKey`. +Автентифікація провайдера виконується у стандартному порядку: `auth-profiles.json` → змінні env → `models.providers.*.apiKey`. -**Поля async completion:** +**Поля асинхронного завершення:** - `asyncCompletion.directSend`: коли `true`, завершені асинхронні завдання `music_generate` і `video_generate` спочатку намагаються доставити результат безпосередньо в канал. Типове значення: `false` - (застарілий шлях requester-session wake/model-delivery). + (застарілий шлях пробудження сесії запитувача/доставки моделі). @@ -2427,7 +2449,7 @@ scripts/sandbox-browser-setup.sh # optional browser image Керує тим, на які сесії можуть націлюватися інструменти сесій (`sessions_list`, `sessions_history`, `sessions_send`). -Типове значення: `tree` (поточна сесія + сесії, породжені нею, наприклад субагенти). +Типове значення: `tree` (поточна сесія + сесії, породжені нею, наприклад subagent-и). ```json5 { @@ -2443,10 +2465,10 @@ scripts/sandbox-browser-setup.sh # optional browser image Примітки: - `self`: лише ключ поточної сесії. -- `tree`: поточна сесія + сесії, породжені поточною сесією (субагенти). -- `agent`: будь-яка сесія, що належить поточному id агента (може включати інших користувачів, якщо ви використовуєте per-sender сесії під тим самим id агента). -- `all`: будь-яка сесія. Націлювання між агентами все одно вимагає `tools.agentToAgent`. -- Обмеження sandbox: коли поточна сесія працює в sandbox і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово встановлюється в `tree`, навіть якщо `tools.sessions.visibility="all"`. +- `tree`: поточна сесія + сесії, породжені поточною сесією (subagent-и). +- `agent`: будь-яка сесія, що належить поточному id агента (може включати інших користувачів, якщо ви запускаєте сесії per-sender під тим самим id агента). +- `all`: будь-яка сесія. Націлювання між агентами все одно потребує `tools.agentToAgent`. +- Обмеження sandbox: коли поточна сесія працює в sandbox і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, значення visibility примусово встановлюється в `tree`, навіть якщо `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` @@ -2472,14 +2494,14 @@ scripts/sandbox-browser-setup.sh # optional browser image - Вкладення підтримуються лише для `runtime: "subagent"`. Runtime ACP їх відхиляє. - Файли матеріалізуються в дочірньому workspace у `.openclaw/attachments//` з `.manifest.json`. -- Вміст вкладень автоматично редагується під час збереження transcript. -- Вхідні дані base64 перевіряються суворою перевіркою алфавіту/доповнення та перевіркою розміру до декодування. -- Для каталогів використовуються права `0700`, для файлів — `0600`. -- Очищення дотримується політики `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише тоді, коли `retainOnSessionKeep: true`. +- Вміст вкладень автоматично редагується в збереженні transcript. +- Вхідні дані base64 проходять валідацію зі строгими перевірками алфавіту/падингу та захистом від розміру до декодування. +- Права доступу до файлів: `0700` для каталогів і `0600` для файлів. +- Очищення виконується відповідно до політики `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише тоді, коли `retainOnSessionKeep: true`. ### `tools.experimental` -Прапорці експериментальних вбудованих інструментів. Типово вимкнені, якщо не спрацьовує правило автоувімкнення strict-agentic GPT-5. +Експериментальні прапорці вбудованих інструментів. Типово вимкнені, якщо не застосовується правило автоувімкнення strict-agentic GPT-5. ```json5 { @@ -2494,8 +2516,8 @@ scripts/sandbox-browser-setup.sh # optional browser image Примітки: - `planTool`: вмикає структурований інструмент `update_plan` для відстеження нетривіальної багатокрокової роботи. -- Типове значення: `false`, якщо тільки `agents.defaults.embeddedPi.executionContract` (або перевизначення для окремого агента) не встановлено в `"strict-agentic"` для запуску OpenAI або OpenAI Codex сімейства GPT-5. Установіть `true`, щоб примусово ввімкнути інструмент поза цим сценарієм, або `false`, щоб тримати його вимкненим навіть для strict-agentic запусків GPT-5. -- Коли інструмент увімкнено, system prompt також додає вказівки з використання, щоб модель використовувала його лише для суттєвої роботи й тримала не більше одного кроку в стані `in_progress`. +- Типове значення: `false`, якщо тільки `agents.defaults.embeddedPi.executionContract` (або перевизначення для окремого агента) не встановлено в `"strict-agentic"` для запуску OpenAI або OpenAI Codex сімейства GPT-5. Установіть `true`, щоб примусово ввімкнути інструмент поза цим сценарієм, або `false`, щоб залишити його вимкненим навіть для strict-agentic запусків GPT-5. +- Коли інструмент увімкнено, system prompt також додає інструкції з використання, щоб модель застосовувала його лише для суттєвої роботи і підтримувала не більше одного кроку `in_progress`. ### `agents.defaults.subagents` @@ -2515,16 +2537,16 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `model`: типова модель для породжених субагентів. Якщо не задано, субагенти успадковують модель викликача. -- `allowAgents`: типовий allowlist id цільових агентів для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент). +- `model`: типова модель для породжених subagent-ів. Якщо не задано, subagent-и успадковують модель викликача. +- `allowAgents`: типовий allowlist цільових id агентів для `sessions_spawn`, коли агент-запитувач не задає власне `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент). - `runTimeoutSeconds`: типовий тайм-аут (у секундах) для `sessions_spawn`, коли виклик інструмента не передає `runTimeoutSeconds`. `0` означає відсутність тайм-ауту. -- Політика інструментів для субагента: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- Політика інструментів для окремого subagent-а: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- -## Власні провайдери та base URL +## Користувацькі провайдери та base URL -OpenClaw використовує вбудований каталог моделей. Додавайте власних провайдерів через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`. +OpenClaw використовує вбудований каталог моделей. Додавайте користувацьких провайдерів через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`. ```json5 { @@ -2553,49 +2575,49 @@ OpenClaw використовує вбудований каталог модел } ``` -- Використовуйте `authHeader: true` + `headers` для власних потреб автентифікації. -- Перевизначайте корінь конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий alias змінної середовища). -- Пріоритет об’єднання для однакових id провайдерів: - - Непорожні значення `baseUrl` з `models.json` агента мають пріоритет. +- Використовуйте `authHeader: true` + `headers` для нетипових потреб автентифікації. +- Перевизначайте корінь конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий псевдонім змінної середовища). +- Пріоритет злиття для провайдерів із відповідними ID: + - Непорожні значення `baseUrl` з agent `models.json` мають пріоритет. - Непорожні значення `apiKey` агента мають пріоритет лише тоді, коли цей провайдер не керується через SecretRef у поточному контексті config/auth-profile. - - Значення `apiKey` провайдера, керовані SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs) замість збереження розкритих секретів. - - Значення заголовків провайдера, керовані SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs). + - Значення `apiKey` провайдера, керовані через SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань) замість збереження визначених секретів. + - Значення заголовків провайдера, керовані через SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань). - Порожні або відсутні `apiKey`/`baseUrl` агента повертаються до `models.providers` у конфігурації. - - Для однакових моделей `contextWindow`/`maxTokens` використовують вище значення між явною конфігурацією та неявними значеннями каталогу. - - Для однакових моделей `contextTokens` зберігає явне runtime-обмеження, коли воно є; використовуйте це, щоб обмежити фактичний контекст без зміни нативних метаданих моделі. - - Використовуйте `models.mode: "replace"`, якщо хочете, щоб конфігурація повністю переписала `models.json`. - - Збереження маркерів є авторитетним за джерелом: маркери записуються з активного знімка конфігурації джерела (до визначення), а не з розкритих секретних значень runtime. + - Для відповідних моделей `contextWindow`/`maxTokens` використовується більше значення між явною конфігурацією й неявними значеннями каталогу. + - Для відповідних моделей `contextTokens` зберігає явний runtime-ліміт, якщо він заданий; використовуйте його, щоб обмежити ефективний контекст, не змінюючи рідні метадані моделі. + - Використовуйте `models.mode: "replace"`, коли хочете, щоб конфігурація повністю переписала `models.json`. + - Збереження маркерів є авторитетним від джерела: маркери записуються з активного знімка конфігурації джерела (до визначення значень), а не з визначених значень секретів runtime. ### Деталі полів провайдера -- `models.mode`: поведінка каталогу провайдерів (`merge` або `replace`). -- `models.providers`: мапа власних провайдерів, ключована за id провайдера. - - Безпечні зміни: використовуйте `openclaw config set models.providers. '' --strict-json --merge` або `openclaw config set models.providers..models '' --strict-json --merge` для додаткових оновлень. `config set` відмовляє в руйнівних замінах, якщо ви не передасте `--replace`. +- `models.mode`: поведінка каталогу провайдера (`merge` або `replace`). +- `models.providers`: map користувацьких провайдерів за ключем id провайдера. + - Безпечне редагування: використовуйте `openclaw config set models.providers. '' --strict-json --merge` або `openclaw config set models.providers..models '' --strict-json --merge` для адитивних оновлень. `config set` відмовляє в руйнівних замінах, якщо не передати `--replace`. - `models.providers.*.api`: адаптер запитів (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` тощо). -- `models.providers.*.apiKey`: облікові дані провайдера (краще використовувати SecretRef/підстановку env). +- `models.providers.*.apiKey`: облікові дані провайдера (надавайте перевагу SecretRef/env-підстановці). - `models.providers.*.auth`: стратегія автентифікації (`api-key`, `token`, `oauth`, `aws-sdk`). -- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` вбудовує `options.num_ctx` у запити (типово: `true`). +- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` вставляє `options.num_ctx` у запити (типово: `true`). - `models.providers.*.authHeader`: примусово передає облікові дані в заголовку `Authorization`, коли це потрібно. -- `models.providers.*.baseUrl`: базовий URL upstream API. -- `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації через proxy/tenant. +- `models.providers.*.baseUrl`: base URL upstream API. +- `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації proxy/tenant. - `models.providers.*.request`: перевизначення транспорту для HTTP-запитів провайдера моделей. - - `request.headers`: додаткові заголовки (об’єднуються з типовими заголовками провайдера). Значення приймають SecretRef. + - `request.headers`: додаткові заголовки (зливаються з типовими заголовками провайдера). Значення приймають SecretRef. - `request.auth`: перевизначення стратегії автентифікації. Режими: `"provider-default"` (використовувати вбудовану автентифікацію провайдера), `"authorization-bearer"` (з `token`), `"header"` (з `headerName`, `value`, необов’язковим `prefix`). - - `request.proxy`: перевизначення HTTP-proxy. Режими: `"env-proxy"` (використовувати змінні середовища `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (з `url`). Обидва режими приймають необов’язковий підоб’єкт `tls`. + - `request.proxy`: перевизначення HTTP proxy. Режими: `"env-proxy"` (використовувати змінні середовища `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (з `url`). Обидва режими приймають необов’язковий підоб’єкт `tls`. - `request.tls`: перевизначення TLS для прямих з’єднань. Поля: `ca`, `cert`, `key`, `passphrase` (усі приймають SecretRef), `serverName`, `insecureSkipVerify`. - - `request.allowPrivateNetwork`: коли `true`, дозволяє HTTPS до `baseUrl`, якщо DNS визначається в приватні, CGNAT або подібні діапазони, через guard HTTP fetch провайдера (opt-in для оператора для довірених self-hosted endpoint OpenAI-compatible). WebSocket використовує той самий `request` для заголовків/TLS, але не цей SSRF-gate fetch. Типове значення `false`. + - `request.allowPrivateNetwork`: коли `true`, дозволяє HTTPS до `baseUrl`, якщо DNS визначається в приватні, CGNAT або подібні діапазони, через захист SSRF для HTTP fetch провайдера (operator opt-in для довірених self-hosted OpenAI-сумісних endpoint). WebSocket використовує той самий `request` для заголовків/TLS, але не цей захист SSRF для fetch. Типове значення `false`. - `models.providers.*.models`: явні записи каталогу моделей провайдера. -- `models.providers.*.models.*.contextWindow`: метадані нативного context window моделі. -- `models.providers.*.models.*.contextTokens`: необов’язкове runtime-обмеження контексту. Використовуйте це, коли потрібен менший фактичний бюджет контексту, ніж нативний `contextWindow` моделі. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` із непорожнім ненативним `baseUrl` (host не `api.openai.com`) OpenClaw під час runtime примусово встановлює це значення в `false`. Порожній або пропущений `baseUrl` зберігає типову поведінку OpenAI. -- `models.providers.*.models.*.compat.requiresStringContent`: необов’язкова підказка сумісності для OpenAI-compatible chat endpoint, які приймають лише рядки. Коли `true`, OpenClaw згортає масиви `messages[].content`, що складаються лише з тексту, у звичайні рядки перед надсиланням запиту. -- `plugins.entries.amazon-bedrock.config.discovery`: корінь налаштувань автоматичного виявлення Bedrock. -- `plugins.entries.amazon-bedrock.config.discovery.enabled`: увімкнути/вимкнути неявне виявлення. -- `plugins.entries.amazon-bedrock.config.discovery.region`: регіон AWS для виявлення. -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: необов’язковий фільтр provider-id для цільового виявлення. -- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: інтервал опитування для оновлення виявлення. -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: резервний context window для виявлених моделей. -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: резервна максимальна кількість вихідних токенів для виявлених моделей. +- `models.providers.*.models.*.contextWindow`: метадані рідного вікна контексту моделі. +- `models.providers.*.models.*.contextTokens`: необов’язковий runtime-ліміт контексту. Використовуйте це, коли хочете мати менший ефективний бюджет контексту, ніж рідний `contextWindow` моделі. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` із непорожнім нерідним `baseUrl` (хост не `api.openai.com`) OpenClaw примусово встановлює це значення в `false` під час runtime. Порожній/пропущений `baseUrl` зберігає типову поведінку OpenAI. +- `models.providers.*.models.*.compat.requiresStringContent`: необов’язкова підказка сумісності для OpenAI-сумісних chat-endpoint-ів, що підтримують лише рядки. Коли `true`, OpenClaw сплощує чисто текстові масиви `messages[].content` у звичайні рядки перед надсиланням запиту. +- `plugins.entries.amazon-bedrock.config.discovery`: кореневий розділ налаштувань автодискавері Bedrock. +- `plugins.entries.amazon-bedrock.config.discovery.enabled`: увімкнути/вимкнути неявне discovery. +- `plugins.entries.amazon-bedrock.config.discovery.region`: регіон AWS для discovery. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: необов’язковий фільтр provider-id для цільового discovery. +- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: інтервал опитування для оновлення discovery. +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: резервне вікно контексту для знайдених моделей. +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: резервна максимальна кількість вихідних токенів для знайдених моделей. ### Приклади провайдерів @@ -2633,7 +2655,7 @@ OpenClaw використовує вбудований каталог модел } ``` -Використовуйте `cerebras/zai-glm-4.7` для Cerebras; `zai/glm-4.7` для прямого Z.AI. +Використовуйте `cerebras/zai-glm-4.7` для Cerebras; `zai/glm-4.7` — для прямого Z.AI. @@ -2667,11 +2689,11 @@ OpenClaw використовує вбудований каталог модел } ``` -Установіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` — припустимі alias. Скорочення: `openclaw onboard --auth-choice zai-api-key`. +Установіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` приймаються як псевдоніми. Скорочення: `openclaw onboard --auth-choice zai-api-key`. - Загальний endpoint: `https://api.z.ai/api/paas/v4` - Endpoint для кодування (типовий): `https://api.z.ai/api/coding/paas/v4` -- Для загального endpoint визначте власного провайдера з перевизначенням base URL. +- Для загального endpoint визначте користувацького провайдера з перевизначенням base URL. @@ -2712,9 +2734,9 @@ OpenClaw використовує вбудований каталог модел Для endpoint у Китаї: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`. -Нативні endpoint Moonshot оголошують сумісність використання потокової передачі на спільному -транспорті `openai-completions`, і OpenClaw прив’язує це до можливостей endpoint, -а не лише до вбудованого id провайдера. +Нативні endpoint-и Moonshot оголошують сумісність використання streaming на спільному +транспорті `openai-completions`, і OpenClaw визначає це за можливостями endpoint-а, +а не лише за вбудованим id провайдера. @@ -2732,7 +2754,7 @@ OpenClaw використовує вбудований каталог модел } ``` -Сумісний з Anthropic, вбудований провайдер. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`. +Anthropic-сумісний, вбудований провайдер. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`. @@ -2815,16 +2837,16 @@ Base URL має бути без `/v1` (клієнт Anthropic додає йог `openclaw onboard --auth-choice minimax-global-api` або `openclaw onboard --auth-choice minimax-cn-api`. Каталог моделей типово містить лише M2.7. -На Anthropic-compatible шляху потокової передачі OpenClaw типово вимикає thinking MiniMax, -якщо ви явно не задасте `thinking` самі. `/fast on` або +На Anthropic-сумісному шляху streaming OpenClaw типово вимикає thinking MiniMax, +якщо ви явно не задасте `thinking` самостійно. `/fast on` або `params.fastMode: true` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. - + -Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; зберігайте hosted-моделі в режимі merge для резервного варіанта. +Див. [Локальні моделі](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; зберігайте хостовані моделі об’єднаними для резервного переходу. @@ -2855,14 +2877,14 @@ Base URL має бути без `/v1` (клієнт Anthropic додає йог } ``` -- `allowBundled`: необов’язковий allowlist лише для bundled Skills (керовані/workspace Skills не зачіпаються). +- `allowBundled`: необов’язковий allowlist лише для комплектних Skills (керовані/робочі Skills не зачіпаються). - `load.extraDirs`: додаткові спільні корені Skills (найнижчий пріоритет). -- `install.preferBrew`: коли `true`, за наявності `brew` спочатку використовувати інсталятори Homebrew, - а вже потім переходити до інших типів інсталяторів. -- `install.nodeManager`: переважний менеджер node для специфікацій `metadata.openclaw.install` +- `install.preferBrew`: коли `true`, надавати перевагу інсталяторам Homebrew, якщо `brew` + доступний, перш ніж переходити до інших типів інсталяторів. +- `install.nodeManager`: пріоритет інсталятора Node для специфікацій `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` вимикає Skill, навіть якщо він bundled/встановлений. -- `entries..apiKey`: спрощений спосіб для Skills, які оголошують основну env-змінну (звичайний текстовий рядок або об’єкт SecretRef). +- `entries..enabled: false` вимикає Skill, навіть якщо він комплектний/встановлений. +- `entries..apiKey`: зручне поле для Skills, які оголошують основну змінну env (відкритий рядок або об’єкт SecretRef). --- @@ -2890,47 +2912,47 @@ Base URL має бути без `/v1` (клієнт Anthropic додає йог } ``` -- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також `plugins.load.paths`. -- Виявлення приймає нативні Plugin OpenClaw, а також сумісні bundled Codex і Claude, включно з bundled Claude без manifest у типовому layout. +- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також із `plugins.load.paths`. +- Discovery приймає нативні Plugin OpenClaw, а також сумісні пакунки Codex і Claude, включно з безманіфестними пакунками Claude зі стандартним layout. - **Зміни конфігурації потребують перезапуску gateway.** -- `allow`: необов’язковий allowlist (завантажуються лише перелічені Plugin). `deny` має пріоритет. -- `plugins.entries..apiKey`: спрощене поле API key на рівні Plugin (коли Plugin це підтримує). -- `plugins.entries..env`: мапа env-змінних в області Plugin. -- `plugins.entries..hooks.allowPromptInjection`: коли `false`, core блокує `before_prompt_build` і ігнорує поля legacy `before_agent_start`, що змінюють prompt, зберігаючи при цьому legacy `modelOverride` і `providerOverride`. Застосовується до нативних hook-ів Plugin і підтримуваних каталогів hook-ів, наданих bundled. -- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому Plugin запитувати перевизначення `provider` і `model` для окремого запуску фонових субагентів. -- `plugins.entries..subagent.allowedModels`: необов’язковий allowlist канонічних цілей `provider/model` для довірених перевизначень субагентів. Використовуйте `"*"`, лише якщо свідомо хочете дозволити будь-яку модель. -- `plugins.entries..config`: об’єкт конфігурації, визначений Plugin (перевіряється схемою нативного Plugin OpenClaw, якщо вона доступна). +- `allow`: необов’язковий allowlist (завантажуються лише перелічені Plugin-и). `deny` має пріоритет. +- `plugins.entries..apiKey`: зручне поле API key на рівні Plugin (коли Plugin це підтримує). +- `plugins.entries..env`: map змінних env у межах Plugin. +- `plugins.entries..hooks.allowPromptInjection`: коли `false`, core блокує `before_prompt_build` та ігнорує поля legacy `before_agent_start`, що змінюють prompt, зберігаючи при цьому legacy `modelOverride` і `providerOverride`. Застосовується до нативних hook-ів Plugin і підтримуваних каталогів hook-ів, що надаються пакунками. +- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому Plugin, щоб він міг запитувати перевизначення `provider` і `model` для окремих запусків фонових subagent-ів. +- `plugins.entries..subagent.allowedModels`: необов’язковий allowlist канонічних цілей `provider/model` для довірених перевизначень subagent-ів. Використовуйте `"*"`, лише якщо ви свідомо хочете дозволити будь-яку модель. +- `plugins.entries..config`: об’єкт конфігурації, визначений Plugin (валідується схемою нативного Plugin OpenClaw, якщо вона доступна). - `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера web-fetch Firecrawl. - - `apiKey`: API key Firecrawl (приймає SecretRef). Резервно використовує `plugins.entries.firecrawl.config.webSearch.apiKey`, legacy `tools.web.fetch.firecrawl.apiKey` або env-змінну `FIRECRAWL_API_KEY`. - - `baseUrl`: базовий URL API Firecrawl (типово: `https://api.firecrawl.dev`). - - `onlyMainContent`: витягувати лише основний вміст зі сторінок (типово: `true`). + - `apiKey`: API key Firecrawl (приймає SecretRef). Використовує резервне значення з `plugins.entries.firecrawl.config.webSearch.apiKey`, legacy `tools.web.fetch.firecrawl.apiKey` або змінної env `FIRECRAWL_API_KEY`. + - `baseUrl`: base URL API Firecrawl (типово: `https://api.firecrawl.dev`). + - `onlyMainContent`: витягувати лише основний вміст сторінок (типово: `true`). - `maxAgeMs`: максимальний вік кешу в мілісекундах (типово: `172800000` / 2 дні). - - `timeoutSeconds`: тайм-аут запиту scrape у секундах (типово: `60`). -- `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (вебпошук Grok). + - `timeoutSeconds`: тайм-аут scrape-запиту в секундах (типово: `60`). +- `plugins.entries.xai.config.xSearch`: налаштування X Search xAI (вебпошук Grok). - `enabled`: увімкнути провайдера X Search. - - `model`: модель Grok для пошуку (наприклад, `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: налаштування memory dreaming. Фази й пороги див. у [Dreaming](/uk/concepts/dreaming). + - `model`: модель Grok для використання в пошуку (наприклад `"grok-4-1-fast"`). +- `plugins.entries.memory-core.config.dreaming`: налаштування memory dreaming. Див. [Dreaming](/uk/concepts/dreaming) щодо фаз і порогів. - `enabled`: головний перемикач dreaming (типово `false`). - - `frequency`: Cron-інтервал для кожного повного проходу dreaming (типово `"0 3 * * *"`). - - політика фаз і пороги є деталями реалізації (не користувацькими ключами конфігурації). -- Повна конфігурація пам’яті міститься в [Довіднику з конфігурації пам’яті](/uk/reference/memory-config): + - `frequency`: частота Cron для кожного повного проходу dreaming (типово `"0 3 * * *"`). + - політика фаз і пороги є деталями реалізації (не ключами конфігурації для користувача). +- Повна конфігурація memory міститься в [Довіднику з конфігурації memory](/uk/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Увімкнені bundled Claude також можуть додавати вбудовані типові значення Pi із `settings.json`; OpenClaw застосовує їх як очищені налаштування агентів, а не як сирі patch-і конфігурації OpenClaw. -- `plugins.slots.memory`: вибрати id активного Plugin пам’яті або `"none"`, щоб вимкнути Plugin пам’яті. -- `plugins.slots.contextEngine`: вибрати id активного Plugin рушія контексту; типово `"legacy"`, якщо ви не встановите й не виберете інший рушій. -- `plugins.installs`: метадані встановлення, керовані CLI, які використовує `openclaw plugins update`. +- Увімкнені Plugin-и пакунків Claude також можуть додавати вбудовані типові значення Pi із `settings.json`; OpenClaw застосовує їх як очищені налаштування агента, а не як сирі патчі конфігурації OpenClaw. +- `plugins.slots.memory`: вибрати id активного Plugin memory або `"none"`, щоб вимкнути Plugin-и memory. +- `plugins.slots.contextEngine`: вибрати id активного Plugin context engine; типово `"legacy"`, якщо ви не встановили й не вибрали інший engine. +- `plugins.installs`: метадані встановлення, якими керує CLI і які використовує `openclaw plugins update`. - Містить `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - - Розглядайте `plugins.installs.*` як керований стан; надавайте перевагу командам CLI замість ручних змін. + - Ставтеся до `plugins.installs.*` як до керованого стану; надавайте перевагу командам CLI замість ручного редагування. Див. [Plugins](/uk/tools/plugin). --- -## Браузер +## Browser ```json5 { @@ -2967,29 +2989,29 @@ Base URL має бути без `/v1` (клієнт Anthropic додає йог ``` - `evaluateEnabled: false` вимикає `act:evaluate` і `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тому навігація браузера типово лишається суворою. -- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`, лише коли ви свідомо довіряєте навігації браузера в приватній мережі. -- У суворому режимі endpoint-и віддалених профілів CDP (`profiles.*.cdpUrl`) під час перевірок доступності/виявлення підлягають такому самому блокуванню приватної мережі. -- `ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий alias. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тому навігація browser типово залишається суворою. +- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте навігації browser у приватній мережі. +- У суворому режимі віддалені endpoint-и профілів CDP (`profiles.*.cdpUrl`) підпадають під те саме блокування приватної мережі під час перевірок досяжності/discovery. +- `ssrfPolicy.allowPrivateNetwork` і далі підтримується як legacy-псевдонім. - У суворому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків. -- Віддалені профілі працюють лише в режимі attach-only (start/stop/reset вимкнено). +- Віддалені профілі є attach-only (start/stop/reset вимкнено). - `profiles.*.cdpUrl` приймає `http://`, `https://`, `ws://` і `wss://`. - Використовуйте HTTP(S), коли хочете, щоб OpenClaw визначав `/json/version`; використовуйте WS(S), - коли провайдер дає вам прямий URL DevTools WebSocket. + Використовуйте HTTP(S), коли хочете, щоб OpenClaw виконав discovery через `/json/version`; використовуйте WS(S), + коли ваш провайдер надає прямий URL DevTools WebSocket. - Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися - на вибраному хості або через підключений browser node. + на вибраному хості або через підключений browser Node. - Профілі `existing-session` можуть задавати `userDataDir`, щоб націлитися на конкретний профіль браузера на базі Chromium, наприклад Brave або Edge. - Профілі `existing-session` зберігають поточні обмеження маршруту Chrome MCP: - дії на основі snapshot/ref замість націлювання CSS-selector-ами, hooks для завантаження одного файла, - без перевизначення тайм-аутів діалогів, без `wait --load networkidle`, а також без + дії на основі snapshot/ref замість націлювання за CSS-селекторами, hook-и завантаження одного файла, + без перевизначень тайм-аутів діалогів, без `wait --load networkidle`, а також без `responsebody`, експорту PDF, перехоплення завантажень або пакетних дій. - Локальні керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; явно задавайте `cdpUrl` лише для віддаленого CDP. -- Порядок автовиявлення: типовий браузер, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. -- Сервіс керування: лише loopback (порт визначається з `gateway.port`, типово `18791`). +- Порядок автовизначення: типовий браузер, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. +- Служба керування: лише loopback (порт виводиться з `gateway.port`, типово `18791`). - `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад - `--disable-gpu`, розмір вікна або debug-прапорці). + `--disable-gpu`, розмір вікна або прапорці відлагодження). --- @@ -3007,7 +3029,7 @@ Base URL має бути без `/v1` (клієнт Anthropic додає йог } ``` -- `seamColor`: акцентний колір для chrome нативного UI застосунку (відтінок бульбашки Talk Mode тощо). +- `seamColor`: колір акценту для chrome нативного UI застосунку (тон бульбашки Talk Mode тощо). - `assistant`: перевизначення identity для Control UI. Якщо не задано, використовується identity активного агента. --- @@ -3077,60 +3099,60 @@ Base URL має бути без `/v1` (клієнт Anthropic додає йог -- `mode`: `local` (запустити gateway) або `remote` (підключитися до віддаленого gateway). Gateway відмовляється запускатися, якщо не `local`. +- `mode`: `local` (запускати gateway) або `remote` (підключатися до віддаленого gateway). Gateway відмовляється запускатися, якщо не встановлено `local`. - `port`: єдиний мультиплексований порт для WS + HTTP. Пріоритет: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback` (типово), `lan` (`0.0.0.0`), `tailnet` (лише IP Tailscale) або `custom`. -- **Застарілі alias для bind**: використовуйте значення режимів bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не alias хоста (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Примітка для Docker**: типовий bind `loopback` слухає `127.0.0.1` усередині контейнера. За bridge-мережі Docker (`-p 18789:18789`) трафік приходить на `eth0`, тож gateway недоступний. Використовуйте `--network host` або встановіть `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. -- **Auth**: типово обов’язкова. Bind-и не в loopback потребують auth gateway. На практиці це означає спільний token/password або reverse proxy з урахуванням identity з `gateway.auth.mode: "trusted-proxy"`. Майстер онбордингу типово генерує token. -- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно задайте `gateway.auth.mode` як `token` або `password`. Потоки запуску та встановлення/відновлення сервісу завершуються помилкою, коли налаштовані обидва варіанти, а режим не задано. -- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних конфігурацій local loopback; цей варіант навмисно не пропонується в підказках онбордингу. -- `gateway.auth.mode: "trusted-proxy"`: делегувати auth reverse proxy з урахуванням identity і довіряти заголовкам identity від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує джерело proxy **не в loopback**; reverse proxy в loopback на тому самому хості не задовольняють auth trusted-proxy. -- `gateway.auth.allowTailscale`: коли `true`, заголовки identity Tailscale Serve можуть задовольняти auth для Control UI/WebSocket (перевіряється через `tailscale whois`). Endpoint-и HTTP API **не** використовують цю auth за заголовками Tailscale; вони дотримуються звичайного режиму HTTP auth gateway. Цей безтокеновий потік припускає, що хост gateway є довіреним. Типово `true`, коли `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: необов’язковий лімітатор невдалих спроб auth. Застосовується окремо на IP клієнта і на область auth (спільний секрет і device-token відстежуються незалежно). Заблоковані спроби повертають `429` + `Retry-After`. - - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом невдачі. Тому одночасні неправильні спроби від того самого клієнта можуть спрацювати на лімітатор уже на другому запиті замість того, щоб обидві пройти як звичайні невідповідності. - - `gateway.auth.rateLimit.exemptLoopback` типово має значення `true`; встановіть `false`, коли свідомо хочете також обмежувати трафік localhost (для тестових конфігурацій або суворих proxy-розгортань). -- Спроби WS auth із походженням браузера завжди обмежуються без винятку для loopback (додатковий захист від браузерного brute force localhost). -- У loopback ці блокування для браузерного походження ізольовані за нормалізованим значенням `Origin`, - тож повторні невдачі з одного localhost origin не блокують автоматично - інший origin. -- `tailscale.mode`: `serve` (лише tailnet, bind loopback) або `funnel` (публічно, потребує auth). -- `controlUi.allowedOrigins`: явний allowlist browser-origin для підключень Gateway WebSocket. Обов’язковий, коли браузерні клієнти очікуються з не-loopback origin. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає резервне визначення origin за Host-header для розгортань, що свідомо покладаються на політику origin на основі Host-header. -- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` `remote.url` має бути `ws://` або `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: клієнтське аварійне перевизначення, яке дозволяє plaintext `ws://` до довірених IP приватної мережі; типово plaintext і далі дозволено лише для loopback. +- **Застарілі псевдоніми bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не псевдоніми хоста (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). +- **Примітка щодо Docker**: типовий bind `loopback` слухає `127.0.0.1` всередині контейнера. За bridge-мережі Docker (`-p 18789:18789`) трафік надходить на `eth0`, тому gateway недоступний. Використовуйте `--network host`, або встановіть `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. +- **Auth**: типово обов’язкова. Для bind не на loopback потрібна auth gateway. На практиці це означає спільний token/password або reverse proxy з awareness identity із `gateway.auth.mode: "trusted-proxy"`. Wizard onboarding типово генерує token. +- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно встановіть `gateway.auth.mode` у `token` або `password`. Під час запуску та в потоках встановлення/відновлення сервісу виникає помилка, якщо налаштовано обидва значення, а mode не задано. +- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних конфігурацій loopback; цей варіант навмисно не пропонується в onboarding prompts. +- `gateway.auth.mode: "trusted-proxy"`: делегує auth reverse proxy з awareness identity і довіряє заголовкам identity від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **не-loopback** джерело proxy; reverse proxy loopback на тому самому хості не задовольняють auth trusted-proxy. +- `gateway.auth.allowTailscale`: коли `true`, заголовки identity Tailscale Serve можуть задовольняти auth для Control UI/WebSocket (перевіряється через `tailscale whois`). Endpoint-и HTTP API **не** використовують цю auth через заголовки Tailscale; вони дотримуються звичайного HTTP auth-режиму gateway. Цей безтокеновий потік припускає, що хост gateway є довіреним. Типово `true`, коли `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: необов’язковий лімітер невдалих auth-спроб. Застосовується для кожного IP клієнта і для кожної області auth (спільний секрет і device-token відстежуються окремо). Заблоковані спроби повертають `429` + `Retry-After`. + - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом невдачі. Тому паралельні погані спроби від одного клієнта можуть спрацювати на лімітер уже на другому запиті, замість того щоб обидві одночасно пройшли як звичайні невідповідності. + - `gateway.auth.rateLimit.exemptLoopback` типово має значення `true`; установіть `false`, якщо ви свідомо хочете, щоб трафік localhost теж підлягав rate limit (для тестових конфігурацій або суворих proxy-розгортань). +- Спроби auth для WS з походження browser завжди throttle-яться з вимкненим винятком для loopback (додатковий захист від brute force localhost через browser). +- На loopback такі блокування для browser-origin ізолюються за нормалізованим + значенням `Origin`, тож повторні збої від одного походження localhost не + блокують автоматично інше походження. +- `tailscale.mode`: `serve` (лише tailnet, bind на loopback) або `funnel` (публічний, потребує auth). +- `controlUi.allowedOrigins`: явний allowlist походжень browser для підключень WebSocket Gateway. Обов’язковий, коли browser-клієнти очікуються не з loopback-походжень. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає резервне визначення походження за заголовком Host для розгортань, що свідомо покладаються на політику походження Host-header. +- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` значення `remote.url` має бути `ws://` або `wss://`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: клієнтське перевизначення break-glass, яке дозволяє незашифрований `ws://` до довірених IP приватної мережі; типовий режим для незашифрованого трафіку і далі обмежено лише loopback. - `gateway.remote.token` / `.password` — це поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують auth gateway. -- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL для зовнішнього relay APNs, який використовують офіційні/TestFlight збірки iOS після публікації relay-backed реєстрацій у gateway. Цей URL має збігатися з URL relay, скомпільованим у збірку iOS. -- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання gateway-to-relay у мілісекундах. Типове значення `10000`. -- Реєстрації relay-backed делегуються конкретній identity gateway. Пов’язаний застосунок iOS викликає `gateway.identity.get`, включає цю identity в relay-реєстрацію та передає gateway право надсилання, прив’язане до реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові env-перевизначення для наведеного вище налаштування relay. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: аварійний варіант лише для розробки для loopback URL relay через HTTP. У production URL relay мають залишатися на HTTPS. -- `gateway.channelHealthCheckMinutes`: інтервал health-monitor каналу в хвилинах. Встановіть `0`, щоб глобально вимкнути перезапуски health-monitor. Типове значення: `5`. -- `gateway.channelStaleEventThresholdMinutes`: поріг stale-socket у хвилинах. Зберігайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. Типове значення: `30`. -- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків health-monitor на канал/обліковий запис за ковзну годину. Типове значення: `10`. -- `channels..healthMonitor.enabled`: opt-out на рівні каналу для перезапусків health-monitor, залишаючи глобальний monitor увімкненим. -- `channels..accounts..healthMonitor.enabled`: перевизначення на рівні облікового запису для багатооблікових каналів. Якщо задано, воно має пріоритет над перевизначенням на рівні каналу. -- Шляхи виклику локального gateway можуть використовувати `gateway.remote.*` як резервне значення лише тоді, коли `gateway.auth.*` не задано. -- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не визначено, визначення завершується за fail-closed (без маскування резервним віддаленим варіантом). -- `trustedProxies`: IP reverse proxy, які завершують TLS або додають заголовки forwarded-client. Додавайте лише proxy, якими ви керуєте. Записи loopback і далі є валідними для конфігурацій proxy на тому самому хості / локального виявлення (наприклад, Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`. +- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL для зовнішнього relay APNs, який використовується офіційними/TestFlight збірками iOS після того, як вони публікують у gateway реєстрації на основі relay. Цей URL має збігатися з URL relay, вбудованим у збірку iOS. +- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання gateway-to-relay у мілісекундах. Типово `10000`. +- Реєстрації на основі relay делегуються конкретній identity gateway. Спарений застосунок iOS отримує `gateway.identity.get`, включає цю identity до relay-реєстрації та передає gateway grant на надсилання, прив’язаний до реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові перевизначення через env для наведеної вище конфігурації relay. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: лише для розробки, обхідний варіант для URL relay через loopback HTTP. Продакшн-URL relay мають лишатися на HTTPS. +- `gateway.channelHealthCheckMinutes`: інтервал моніторингу здоров’я каналів у хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски health-monitor. Типове значення: `5`. +- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого socket у хвилинах. Тримайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. Типове значення: `30`. +- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків health-monitor на канал/обліковий запис у ковзній годині. Типове значення: `10`. +- `channels..healthMonitor.enabled`: opt-out на рівні каналу для перезапусків health-monitor, зберігаючи глобальний monitor увімкненим. +- `channels..accounts..healthMonitor.enabled`: перевизначення для окремого облікового запису в багатооблікових каналах. Якщо задано, воно має пріоритет над перевизначенням на рівні каналу. +- Локальні шляхи викликів gateway можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не задано. +- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef, але значення не визначено, визначення завершується fail-closed (без прихованого резервного переходу на remote). +- `trustedProxies`: IP reverse proxy, які завершують TLS або вставляють forwarded-client headers. Указуйте лише ті proxy, якими ви керуєте. Записи loopback і далі є валідними для конфігурацій виявлення same-host proxy/local (наприклад Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`. - `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо `X-Forwarded-For` відсутній. Типово `false` для поведінки fail-closed. -- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий список deny). -- `gateway.tools.allow`: прибирає назви інструментів із типового HTTP deny list. +- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий deny list). +- `gateway.tools.allow`: прибрати назви інструментів із типового HTTP deny list. -### OpenAI-compatible endpoint-и +### OpenAI-сумісні endpoint-и - Chat Completions: типово вимкнено. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`. - Responses API: `gateway.http.endpoints.responses.enabled`. -- Захист URL-input для Responses: +- Посилення безпеки URL-входів Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` Порожні allowlist-и трактуються як незадані; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` - та/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання через URL. -- Необов’язковий заголовок посиленого захисту відповіді: - - `gateway.http.securityHeaders.strictTransportSecurity` (задавайте лише для HTTPS origin, якими ви керуєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + і/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання за URL. +- Необов’язковий заголовок посилення безпеки відповіді: + - `gateway.http.securityHeaders.strictTransportSecurity` (встановлюйте лише для HTTPS-походжень, якими ви керуєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) ### Ізоляція кількох інстансів @@ -3162,11 +3184,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: вмикає термінацію TLS на слухачі gateway (HTTPS/WSS) (типово: `false`). -- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, якщо явні файли не налаштовано; лише для локального/dev використання. +- `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (типово: `false`). +- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовано; лише для локального/dev використання. - `certPath`: шлях у файловій системі до файла TLS-сертифіката. -- `keyPath`: шлях у файловій системі до приватного TLS-ключа; тримайте його з обмеженими правами доступу. -- `caPath`: необов’язковий шлях до bundle CA для перевірки клієнтів або власних ланцюжків довіри. +- `keyPath`: шлях у файловій системі до файла приватного ключа TLS; обмежуйте доступ до нього дозволами. +- `caPath`: необов’язковий шлях до пакета CA для верифікації клієнтів або власних ланцюжків довіри. ### `gateway.reload` @@ -3183,12 +3205,12 @@ openclaw gateway --port 19001 ``` - `mode`: керує тим, як зміни конфігурації застосовуються під час runtime. - - `"off"`: ігнорувати живі зміни; потрібен явний перезапуск. - - `"restart"`: завжди перезапускати процес gateway після зміни конфігурації. - - `"hot"`: застосовувати зміни в процесі без перезапуску. - - `"hybrid"` (типово): спочатку пробувати hot reload; якщо потрібно — переходити до перезапуску. -- `debounceMs`: вікно debounce у мс перед застосуванням змін конфігурації (невід’ємне ціле число). -- `deferralTimeoutMs`: максимальний час у мс очікування завершення операцій у польоті перед примусовим перезапуском (типово: `300000` = 5 хвилин). + - `"off"`: ігнорувати live-редагування; зміни потребують явного перезапуску. + - `"restart"`: завжди перезапускати процес gateway при зміні конфігурації. + - `"hot"`: застосовувати зміни в межах процесу без перезапуску. + - `"hybrid"` (типово): спочатку пробувати hot reload; якщо потрібно, переходити до перезапуску. +- `debounceMs`: debounce-вікно в ms перед застосуванням змін конфігурації (невід’ємне ціле число). +- `deferralTimeoutMs`: максимальний час у ms, протягом якого чекати на завершення операцій у польоті перед примусовим перезапуском (типово: `300000` = 5 хвилин). --- @@ -3226,12 +3248,12 @@ openclaw gateway --port 19001 ``` Auth: `Authorization: Bearer ` або `x-openclaw-token: `. -Hook-token-и в query string відхиляються. +Токени hook у query-string відхиляються. Примітки щодо валідації та безпеки: -- `hooks.enabled=true` потребує непорожній `hooks.token`. -- `hooks.token` має **відрізнятися** від `gateway.auth.token`; повторне використання token gateway відхиляється. +- `hooks.enabled=true` потребує непорожнього `hooks.token`. +- `hooks.token` має бути **відмінним** від `gateway.auth.token`; повторне використання токена Gateway відхиляється. - `hooks.path` не може бути `/`; використовуйте окремий підшлях, наприклад `/hooks`. - Якщо `hooks.allowRequestSessionKey=true`, обмежуйте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`). - Якщо mapping або preset використовує шаблонізований `sessionKey`, задайте `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping не потребують цього opt-in. @@ -3242,30 +3264,30 @@ Hook-token-и в query string відхиляються. - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - `sessionKey` із payload запиту приймається лише тоді, коли `hooks.allowRequestSessionKey=true` (типово: `false`). - `POST /hooks/` → визначається через `hooks.mappings` - - Значення `sessionKey` у mapping, згенеровані шаблоном, вважаються зовнішньо поданими й також потребують `hooks.allowRequestSessionKey=true`. + - Значення `sessionKey` у mapping, згенеровані шаблоном, трактуються як зовнішньо подані й також потребують `hooks.allowRequestSessionKey=true`. -- `match.path` відповідає підшляху після `/hooks` (наприклад, `/hooks/gmail` → `gmail`). -- `match.source` відповідає полю payload для загальних шляхів. -- Шаблони на кшталт `{{messages[0].subject}}` читають дані з payload. -- `transform` може вказувати на модуль JS/TS, який повертає дію hook. - - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та traversal відхиляються). -- `agentId` маршрутизує до конкретного агента; невідомі id повертаються до типового агента. -- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або пропущено = дозволити всі, `[]` = заборонити всі). -- `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків hook agent без явного `sessionKey`. -- `allowRequestSessionKey`: дозволити викликачам `/hooks/agent` і ключам сесій mapping, що керуються шаблоном, задавати `sessionKey` (типово: `false`). +- `match.path` зіставляє підшлях після `/hooks` (наприклад `/hooks/gmail` → `gmail`). +- `match.source` зіставляє поле payload для загальних шляхів. +- Шаблони на кшталт `{{messages[0].subject}}` зчитуються з payload. +- `transform` може вказувати на модуль JS/TS, що повертає дію hook. + - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та вихід за межі каталогу відхиляються). +- `agentId` маршрутизує до конкретного агента; невідомі ID повертаються до типового значення. +- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або пропущене значення = дозволити всі, `[]` = заборонити всі). +- `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків hook-агента без явного `sessionKey`. +- `allowRequestSessionKey`: дозволяє викликам `/hooks/agent` і sessionKey mapping-ів, згенерованих шаблоном, установлювати `sessionKey` (типово: `false`). - `allowedSessionKeyPrefixes`: необов’язковий allowlist префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. Стає обов’язковим, коли будь-який mapping або preset використовує шаблонізований `sessionKey`. - `deliver: true` надсилає фінальну відповідь у канал; `channel` типово дорівнює `last`. -- `model` перевизначає LLM для цього запуску hook (має бути дозволено, якщо задано каталог моделей). +- `model` перевизначає LLM для цього запуску hook (має бути дозволена, якщо задано каталог моделей). ### Інтеграція Gmail - Вбудований preset Gmail використовує `sessionKey: "hook:gmail:{{messages[0].id}}"`. -- Якщо ви зберігаєте цю маршрутизацію для кожного повідомлення, задайте `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes` так, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. -- Якщо вам потрібен `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість типового шаблонізованого значення. +- Якщо ви зберігаєте таку маршрутизацію для кожного повідомлення, установіть `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes` так, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. +- Якщо вам потрібне `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість типового шаблонізованого. ```json5 { @@ -3288,12 +3310,12 @@ Hook-token-и в query string відхиляються. } ``` -- Gateway автоматично запускає `gog gmail watch serve` під час завантаження, якщо це налаштовано. Встановіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути. +- Gateway автоматично запускає `gog gmail watch serve` під час завантаження, якщо це налаштовано. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути. - Не запускайте окремий `gog gmail watch serve` паралельно з Gateway. --- -## Canvas host +## Хост Canvas ```json5 { @@ -3305,18 +3327,18 @@ Hook-token-и в query string відхиляються. } ``` -- Обслуговує HTML/CSS/JS та A2UI, які агент може редагувати, через HTTP на порту Gateway: +- Обслуговує HTML/CSS/JS і A2UI, які може редагувати агент, через HTTP на порту Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - Лише локально: залишайте `gateway.bind: "loopback"` (типово). -- Для bind не в loopback: маршрути canvas потребують auth Gateway (token/password/trusted-proxy), так само як і інші HTTP-поверхні Gateway. -- Node WebView зазвичай не надсилають заголовки auth; після сполучення та підключення node Gateway рекламує URL-и можливостей, прив’язані до node, для доступу до canvas/A2UI. -- URL-и можливостей прив’язані до активної WS-сесії node і швидко спливають. Резервний варіант на основі IP не використовується. +- Для bind не на loopback: маршрути canvas потребують auth Gateway (token/password/trusted-proxy), так само як і інші HTTP-поверхні Gateway. +- Node WebView зазвичай не надсилають auth-заголовки; після pairing і підключення Node Gateway рекламує capability URL-и на рівні Node для доступу до canvas/A2UI. +- Capability URL-и прив’язані до активної WS-сесії Node і швидко спливають. Резервний варіант на основі IP не використовується. - Вбудовує клієнт live-reload у HTML, що обслуговується. - Автоматично створює стартовий `index.html`, якщо каталог порожній. -- Також обслуговує A2UI за адресою `/__openclaw__/a2ui/`. +- Також обслуговує A2UI на `/__openclaw__/a2ui/`. - Зміни потребують перезапуску gateway. -- Вимикайте live reload для великих каталогів або при помилках `EMFILE`. +- Вимкніть live reload для великих каталогів або при помилках `EMFILE`. --- @@ -3334,11 +3356,11 @@ Hook-token-и в query string відхиляються. } ``` -- `minimal` (типово): не включає `cliPath` + `sshPort` до TXT-записів. -- `full`: включає `cliPath` + `sshPort`. -- Ім’я хоста типово `openclaw`. Перевизначення через `OPENCLAW_MDNS_HOSTNAME`. +- `minimal` (типово): не включати `cliPath` + `sshPort` у TXT-записи. +- `full`: включати `cliPath` + `sshPort`. +- Ім’я хоста типово `openclaw`. Перевизначається через `OPENCLAW_MDNS_HOSTNAME`. -### Wide-area (DNS-SD) +### Широка область (DNS-SD) ```json5 { @@ -3348,7 +3370,7 @@ Hook-token-и в query string відхиляються. } ``` -Записує зону unicast DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте це з DNS-сервером (рекомендовано CoreDNS) + split DNS у Tailscale. +Записує зону унікастного DNS-SD у `~/.openclaw/dns/`. Для discovery між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + split DNS Tailscale. Налаштування: `openclaw dns setup --apply`. @@ -3356,7 +3378,7 @@ Hook-token-и в query string відхиляються. ## Середовище -### `env` (вбудовані env-змінні) +### `env` (вбудовані змінні env) ```json5 { @@ -3373,14 +3395,14 @@ Hook-token-и в query string відхиляються. } ``` -- Вбудовані env-змінні застосовуються лише тоді, коли в process env немає цього ключа. -- Файли `.env`: `.env` поточного робочого каталогу + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). +- Вбудовані змінні env застосовуються лише тоді, коли в середовищі процесу бракує цього ключа. +- Файли `.env`: `.env` у поточному робочому каталозі + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). - `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell. -- Повний порядок пріоритетів див. у [Environment](/uk/help/environment). +- Повний пріоритет див. у [Environment](/uk/help/environment). -### Підстановка env-змінних +### Підстановка змінних env -Посилайтеся на env-змінні в будь-якому рядку конфігурації через `${VAR_NAME}`: +Посилайтеся на змінні env у будь-якому рядку конфігурації через `${VAR_NAME}`: ```json5 { @@ -3390,16 +3412,16 @@ Hook-token-и в query string відхиляються. } ``` -- Підходять лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. +- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. - Відсутні/порожні змінні спричиняють помилку під час завантаження конфігурації. -- Екрануйте як `$${VAR}` для буквального `${VAR}`. +- Екрануйте через `$${VAR}`, щоб отримати буквальний `${VAR}`. - Працює з `$include`. --- -## Secrets +## Секрети -Посилання на секрети є додатковими: звичайні текстові значення і далі працюють. +Посилання на секрети є адитивними: відкриті значення й далі працюють. ### `SecretRef` @@ -3415,13 +3437,13 @@ Hook-token-и в query string відхиляються. - шаблон `id` для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` - `id` для `source: "file"`: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`) - шаблон `id` для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `id` для `source: "exec"` не повинні містити сегментів шляху `.` або `..`, розділених `/` (наприклад `a/../b` відхиляється) +- `id` для `source: "exec"` не повинні містити slash-delimited сегменти шляху `.` або `..` (наприклад `a/../b` відхиляється) ### Підтримувана поверхня облікових даних -- Канонічна матриця: [SecretRef Credential Surface](/uk/reference/secretref-credential-surface) +- Канонічна матриця: [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface) - `secrets apply` націлюється на підтримувані шляхи облікових даних у `openclaw.json`. -- Посилання з `auth-profiles.json` включені в runtime-визначення й покриття аудиту. +- Посилання в `auth-profiles.json` включаються у визначення runtime і покриття аудиту. ### Конфігурація провайдерів секретів @@ -3453,13 +3475,13 @@ Hook-token-и в query string відхиляються. Примітки: -- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue `id` має дорівнювати `"value"`). -- Провайдер `exec` потребує абсолютний шлях `command` і використовує payload-и протоколу через stdin/stdout. -- Типово шляхи команд-симлінків відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-симлінки з перевіркою шляху до визначеної цілі. -- Якщо налаштовано `trustedDirs`, перевірка довірених каталогів застосовується до шляху визначеної цілі. -- Середовище дочірнього процесу `exec` типово мінімальне; передавайте потрібні змінні явно через `passEnv`. -- Посилання на секрети визначаються під час активації в знімок у пам’яті, після чого шляхи запитів читають лише цей знімок. -- Під час активації застосовується фільтрація активної поверхні: невизначені посилання на ввімкнених поверхнях призводять до помилки під час startup/reload, тоді як неактивні поверхні пропускаються з діагностикою. +- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue `id` має бути `"value"`). +- Провайдер `exec` потребує абсолютного шляху `command` і використовує payload-и протоколу через stdin/stdout. +- Типово шляхи команд-символічних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи symlink із валідацією визначеного цільового шляху. +- Якщо налаштовано `trustedDirs`, перевірка trusted-dir застосовується до визначеного цільового шляху. +- Середовище дочірнього процесу `exec` типово є мінімальним; явно передавайте потрібні змінні через `passEnv`. +- Посилання на секрети визначаються під час активації в знімок у пам’яті, а далі шляхи запитів читають лише цей знімок. +- Під час активації застосовується фільтрація активної поверхні: невизначені посилання на ввімкнених поверхнях спричиняють помилку запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. --- @@ -3482,12 +3504,12 @@ Hook-token-и в query string відхиляються. ``` - Профілі для окремого агента зберігаються в `/auth-profiles.json`. -- `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для режимів статичних облікових даних. -- Профілі в режимі OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані профілів auth на основі SecretRef. -- Статичні runtime-облікові дані надходять із визначених знімків у пам’яті; застарілі статичні записи `auth.json` очищаються при виявленні. -- Застарілі імпорти OAuth беруться з `~/.openclaw/credentials/oauth.json`. +- `auth-profiles.json` підтримує посилання на рівні значення (`keyRef` для `api_key`, `tokenRef` для `token`) для статичних режимів облікових даних. +- Профілі в режимі OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані профілю auth через SecretRef. +- Статичні облікові дані runtime беруться з визначених у пам’яті знімків; застарілі статичні записи `auth.json` очищаються під час виявлення. +- Застарілі імпорти OAuth — з `~/.openclaw/credentials/oauth.json`. - Див. [OAuth](/uk/concepts/oauth). -- Поведінка runtime секретів і tooling `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets). +- Поведінка runtime секретів і інструменти `audit/configure/apply`: [Керування секретами](/uk/gateway/secrets). ### `auth.cooldowns` @@ -3509,21 +3531,20 @@ Hook-token-и в query string відхиляються. } ``` -- `billingBackoffHours`: базовий backoff у годинах, коли профіль зазнає невдачі через справжні - помилки billing/недостатнього кредиту (типово: `5`). Явний текст про billing - усе одно може потрапити сюди навіть на відповідях `401`/`403`, але - зіставлення тексту, специфічного для провайдера, залишаються обмеженими - провайдером, якому вони належать (наприклад OpenRouter - `Key limit exceeded`). Повідомлення retryable HTTP `402` про вікно використання або - ліміти витрат організації/workspace і далі потрапляють у шлях `rate_limit`. -- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин backoff для billing на рівні провайдера. -- `billingMaxHours`: верхня межа в годинах для експоненційного зростання backoff billing (типово: `24`). -- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для високовпевнених збоїв `auth_permanent` (типово: `10`). -- `authPermanentMaxMinutes`: верхня межа в хвилинах для зростання backoff `auth_permanent` (типово: `60`). -- `failureWindowHours`: ковзне вікно в годинах, яке використовується для лічильників backoff (типово: `24`). -- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile того самого провайдера для помилок перевантаження перед переходом до резервної моделі (типово: `1`). Сюди потрапляють форми провайдерської зайнятості на кшталт `ModelNotReadyException`. -- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (типово: `0`). -- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile того самого провайдера для помилок rate-limit перед переходом до резервної моделі (типово: `1`). Цей bucket rate-limit включає текстові форми провайдера на кшталт `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. +- `billingBackoffHours`: базовий backoff у годинах, коли профіль зазнає збою через справжні + помилки білінгу/недостатнього кредиту (типово: `5`). Явний текст про білінг + усе ще може потрапляти сюди навіть на відповідях `401`/`403`, але текстові + matcher-и, специфічні для провайдера, залишаються в межах провайдера, якому вони належать (наприклад OpenRouter + `Key limit exceeded`). Повторювані повідомлення HTTP `402` про вікно використання або + ліміти витрат організації/workspace натомість залишаються в гілці `rate_limit`. +- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин billing backoff для окремих провайдерів. +- `billingMaxHours`: межа в годинах для експоненційного зростання billing backoff (типово: `24`). +- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для високодостовірних збоїв `auth_permanent` (типово: `10`). +- `authPermanentMaxMinutes`: межа в хвилинах для зростання backoff `auth_permanent` (типово: `60`). +- `failureWindowHours`: ковзне вікно в годинах, що використовується для лічильників backoff (типово: `24`). +- `overloadedProfileRotations`: максимальна кількість ротацій auth-профілю того самого провайдера для помилок перевантаження перед переходом до fallback моделі (типово: `1`). Сюди потрапляють форми зайнятості провайдера, як-от `ModelNotReadyException`. +- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації профілю/провайдера в стані перевантаження (типово: `0`). +- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-профілю того самого провайдера для помилок rate-limit перед переходом до fallback моделі (типово: `1`). Цей кошик rate-limit включає текстові форми від провайдера на кшталт `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. --- @@ -3543,9 +3564,9 @@ Hook-token-и в query string відхиляються. ``` - Типовий файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. -- Установіть `logging.file` для стабільного шляху. -- `consoleLevel` підвищується до `debug`, коли використовується `--verbose`. -- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого запис пригнічується (додатне ціле число; типово: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів. +- Установіть `logging.file`, щоб мати стабільний шлях. +- `consoleLevel` підвищується до `debug`, коли задано `--verbose`. +- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого записи пригнічуються (додатне ціле число; типово: `524288000` = 500 MB). Для продакшн-розгортань використовуйте зовнішню ротацію журналів. --- @@ -3583,19 +3604,19 @@ Hook-token-и в query string відхиляються. ``` - `enabled`: головний перемикач для виводу інструментування (типово: `true`). -- `flags`: масив рядків-прапорців, що вмикають цільовий вивід у журнали (підтримує wildcard-и на кшталт `"telegram.*"` або `"*"`). -- `stuckSessionWarnMs`: поріг віку в мс для виведення попереджень про завислі сесії, поки сесія лишається в стані обробки. +- `flags`: масив рядків прапорців, що вмикають цільовий вивід журналів (підтримує wildcard-и на кшталт `"telegram.*"` або `"*"`). +- `stuckSessionWarnMs`: поріг віку в ms для виведення попереджень про завислі сесії, поки сесія залишається в стані обробки. - `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`). -- `otel.endpoint`: URL колектора для експорту OTel. +- `otel.endpoint`: URL collector-а для експорту OTel. - `otel.protocol`: `"http/protobuf"` (типово) або `"grpc"`. -- `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, що надсилаються із запитами експорту OTel. -- `otel.serviceName`: назва сервісу для атрибутів ресурсу. +- `otel.headers`: додаткові заголовки HTTP/gRPC metadata, що надсилаються разом із запитами експорту OTel. +- `otel.serviceName`: ім’я сервісу для атрибутів ресурсу. - `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт trace, metrics або logs. - `otel.sampleRate`: частота семплювання trace `0`–`1`. -- `otel.flushIntervalMs`: інтервал періодичного flush telemetry у мс. +- `otel.flushIntervalMs`: інтервал періодичного скидання telemetry у ms. - `cacheTrace.enabled`: журналювати знімки trace кешу для вбудованих запусків (типово: `false`). - `cacheTrace.filePath`: шлях виводу для JSONL trace кешу (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід trace кешу (усе типово: `true`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід trace кешу (усі типово: `true`). --- @@ -3617,11 +3638,11 @@ Hook-token-и в query string відхиляються. } ``` -- `channel`: канал релізів для npm/git-встановлень — `"stable"`, `"beta"` або `"dev"`. -- `checkOnStart`: перевіряти оновлення npm під час запуску gateway (типово: `true`). -- `auto.enabled`: увімкнути фонове автооновлення для package-встановлень (типово: `false`). -- `auto.stableDelayHours`: мінімальна затримка в годинах перед авто-застосуванням у stable-каналі (типово: `6`; максимум: `168`). -- `auto.stableJitterHours`: додаткове вікно розподілу розгортання stable-каналу в годинах (типово: `12`; максимум: `168`). +- `channel`: канал релізів для встановлень npm/git — `"stable"`, `"beta"` або `"dev"`. +- `checkOnStart`: перевіряти наявність оновлень npm під час запуску gateway (типово: `true`). +- `auto.enabled`: увімкнути фонове автооновлення для встановлень пакетів (типово: `false`). +- `auto.stableDelayHours`: мінімальна затримка в годинах перед автоматичним застосуванням stable-каналу (типово: `6`; максимум: `168`). +- `auto.stableJitterHours`: додаткове вікно розтягування розгортання stable-каналу в годинах (типово: `12`; максимум: `168`). - `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу в годинах (типово: `1`; максимум: `24`). --- @@ -3655,21 +3676,21 @@ Hook-token-и в query string відхиляються. } ``` -- `enabled`: глобальний feature gate для ACP (типово: `false`). -- `dispatch.enabled`: незалежний gate для диспетчеризації ходів ACP-сесій (типово: `true`). Установіть `false`, щоб залишити команди ACP доступними, але заблокувати виконання. +- `enabled`: глобальний feature gate ACP (типово: `false`). +- `dispatch.enabled`: незалежний gate для dispatch ходів сесії ACP (типово: `true`). Установіть `false`, щоб залишити команди ACP доступними, але заблокувати виконання. - `backend`: id типового backend runtime ACP (має відповідати зареєстрованому Plugin runtime ACP). -- `defaultAgent`: резервний id цільового агента ACP, коли spawn-и не задають явну ціль. +- `defaultAgent`: резервний id цільового агента ACP, коли spawn-и не задають явної цілі. - `allowedAgents`: allowlist id агентів, дозволених для runtime-сесій ACP; порожнє значення означає відсутність додаткового обмеження. - `maxConcurrentSessions`: максимальна кількість одночасно активних ACP-сесій. -- `stream.coalesceIdleMs`: вікно idle flush у мс для потокового тексту. -- `stream.maxChunkChars`: максимальний розмір блока перед розбиттям проєкції потокового блока. -- `stream.repeatSuppression`: приглушувати повторювані рядки статусу/інструментів на кожен хід (типово: `true`). -- `stream.deliveryMode`: `"live"` передає потік поступово; `"final_only"` буферизує до термінальних подій ходу. -- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструментів (типово: `"paragraph"`). -- `stream.maxOutputChars`: максимальна кількість символів виводу асистента, що проєктується за один хід ACP. -- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлень ACP. -- `stream.tagVisibility`: запис назв тегів на булеві перевизначення видимості для потокових подій. -- `runtime.ttlMinutes`: idle TTL у хвилинах для worker-ів ACP-сесій до того, як вони стануть придатними для очищення. +- `stream.coalesceIdleMs`: вікно idle flush у ms для потокового тексту. +- `stream.maxChunkChars`: максимальний розмір chunk перед розбиттям проєкції потокового блока. +- `stream.repeatSuppression`: пригнічувати повторювані рядки статусу/інструментів за хід (типово: `true`). +- `stream.deliveryMode`: `"live"` передає потік поступово; `"final_only"` буферизує до terminal-подій ходу. +- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструмента (типово: `"paragraph"`). +- `stream.maxOutputChars`: максимальна кількість символів виводу асистента, проєктованих на один хід ACP. +- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлення ACP. +- `stream.tagVisibility`: запис назв тегів до булевих перевизначень видимості для потокових подій. +- `runtime.ttlMinutes`: idle TTL у хвилинах для воркерів сесій ACP до моменту, коли вони можуть бути очищені. - `runtime.installCommand`: необов’язкова команда встановлення, яку слід запустити під час bootstrap середовища runtime ACP. --- @@ -3686,17 +3707,17 @@ Hook-token-и в query string відхиляються. } ``` -- `cli.banner.taglineMode` керує стилем підзаголовка банера: - - `"random"` (типово): змінні кумедні/сезонні підзаголовки. - - `"default"`: фіксований нейтральний підзаголовок (`All your chats, one OpenClaw.`). - - `"off"`: без тексту підзаголовка (заголовок/версія банера все одно показуються). -- Щоб приховати весь банер (а не лише підзаголовки), встановіть env `OPENCLAW_HIDE_BANNER=1`. +- `cli.banner.taglineMode` керує стилем tagline банера: + - `"random"` (типово): ротаційні кумедні/сезонні tagline. + - `"default"`: фіксований нейтральний tagline (`All your chats, one OpenClaw.`). + - `"off"`: без тексту tagline (назва/версія банера все одно показуються). +- Щоб приховати весь банер (а не лише tagline), установіть env `OPENCLAW_HIDE_BANNER=1`. --- ## Wizard -Метадані, які записують керовані CLI-потоки налаштування (`onboard`, `configure`, `doctor`): +Метадані, які записуються керованими CLI-потоками налаштування (`onboard`, `configure`, `doctor`): ```json5 { @@ -3714,15 +3735,15 @@ Hook-token-и в query string відхиляються. ## Identity -Див. поля identity в `agents.list` у розділі [Значення агентів за замовчуванням](#agent-defaults). +Див. поля identity у `agents.list` у розділі [Типові параметри агентів](#agent-defaults). --- ## Bridge (legacy, видалено) -Поточні збірки більше не містять TCP bridge. Node підключаються через WebSocket Gateway. Ключі `bridge.*` більше не входять до схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі). +Поточні збірки більше не містять TCP bridge. Node-і підключаються через WebSocket Gateway. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі). - + ```json { @@ -3760,11 +3781,11 @@ Hook-token-и в query string відхиляються. } ``` -- `sessionRetention`: як довго зберігати завершені ізольовані сесії запусків Cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених transcript Cron. Типове значення: `24h`; установіть `false`, щоб вимкнути. +- `sessionRetention`: як довго зберігати завершені ізольовані сесії запусків Cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених транскриптів Cron. Типове значення: `24h`; установіть `false`, щоб вимкнути. - `runLog.maxBytes`: максимальний розмір файла журналу одного запуску (`cron/runs/.jsonl`) перед очищенням. Типове значення: `2_000_000` байтів. -- `runLog.keepLines`: кількість найновіших рядків, що зберігаються при спрацюванні очищення журналу запуску. Типове значення: `2000`. -- `webhookToken`: bearer token, який використовується для доставки POST webhook Cron (`delivery.mode = "webhook"`); якщо пропущено, заголовок auth не надсилається. -- `webhook`: застарілий резервний URL webhook (http/https), який використовується лише для збережених завдань, що все ще мають `notify: true`. +- `runLog.keepLines`: кількість найновіших рядків, що зберігаються, коли спрацьовує очищення журналу запусків. Типове значення: `2000`. +- `webhookToken`: bearer token, який використовується для доставки Cron webhook через POST (`delivery.mode = "webhook"`); якщо не задано, заголовок auth не надсилається. +- `webhook`: застарілий legacy fallback URL webhook (`http/https`), який використовується лише для збережених завдань, що все ще мають `notify: true`. ### `cron.retry` @@ -3781,10 +3802,10 @@ Hook-token-и в query string відхиляються. ``` - `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань при тимчасових помилках (типово: `3`; діапазон: `0`–`10`). -- `backoffMs`: масив затримок backoff у мс для кожної повторної спроби (типово: `[30000, 60000, 300000]`; 1–10 записів). -- `retryOn`: типи помилок, що запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Пропустіть, щоб повторювати для всіх тимчасових типів. +- `backoffMs`: масив затримок backoff у ms для кожної повторної спроби (типово: `[30000, 60000, 300000]`; 1–10 записів). +- `retryOn`: типи помилок, які запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Не вказуйте, щоб повторювати всі тимчасові типи. -Застосовується лише до одноразових завдань Cron. Повторювані завдання використовують окрему обробку помилок. +Застосовується лише до одноразових завдань Cron. Періодичні завдання використовують окрему обробку помилок. ### `cron.failureAlert` @@ -3802,10 +3823,10 @@ Hook-token-и в query string відхиляються. } ``` -- `enabled`: увімкнути сповіщення про помилки для завдань Cron (типово: `false`). -- `after`: кількість послідовних помилок перед спрацюванням сповіщення (додатне ціле число, мінімум: `1`). +- `enabled`: увімкнути сповіщення про збої для завдань Cron (типово: `false`). +- `after`: кількість послідовних збоїв перед спрацюванням сповіщення (додатне ціле число, мінімум: `1`). - `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число). -- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` робить POST на налаштований webhook. +- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` надсилає POST на налаштований webhook. - `accountId`: необов’язковий id облікового запису або каналу для обмеження доставки сповіщення. ### `cron.failureDestination` @@ -3824,50 +3845,50 @@ Hook-token-и в query string відхиляються. ``` - Типова ціль для сповіщень про збої Cron у всіх завданнях. -- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли існує достатньо даних про ціль. +- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли є достатньо даних для цілі. - `channel`: перевизначення каналу для доставки announce. `"last"` повторно використовує останній відомий канал доставки. - `to`: явна ціль announce або URL webhook. Обов’язково для режиму webhook. - `accountId`: необов’язкове перевизначення облікового запису для доставки. -- `delivery.failureDestination` на рівні завдання перевизначає це глобальне типове значення. -- Коли не задано ні глобальну, ні ціль збою для конкретного завдання, завдання, які вже доставляють через `announce`, у разі збою повертаються до цієї основної announce-цілі. +- `delivery.failureDestination` для окремого завдання перевизначає це глобальне типове значення. +- Коли не задано ні глобальну, ні окрему для завдання ціль збоїв, завдання, які вже доставляють через `announce`, у разі збою повертаються до цієї основної цілі announce. - `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` завдання не дорівнює `"webhook"`. -Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання Cron відстежуються як [фонові завдання](/uk/automation/tasks). +Див. [Завдання Cron](/uk/automation/cron-jobs). Ізольовані виконання Cron відстежуються як [фонові завдання](/uk/automation/tasks). --- ## Змінні шаблону моделі медіа -Заповнювачі шаблонів, що розгортаються в `tools.media.models[].args`: +Заповнювачі шаблону, які розгортаються в `tools.media.models[].args`: | Змінна | Опис | | ----------------- | ------------------------------------------------- | | `{{Body}}` | Повне тіло вхідного повідомлення | | `{{RawBody}}` | Сире тіло (без обгорток історії/відправника) | -| `{{BodyStripped}}`| Тіло без групових згадок | +| `{{BodyStripped}}` | Тіло без згадок у групі | | `{{From}}` | Ідентифікатор відправника | | `{{To}}` | Ідентифікатор призначення | -| `{{MessageSid}}` | id повідомлення каналу | +| `{{MessageSid}}` | ID повідомлення каналу | | `{{SessionId}}` | UUID поточної сесії | -| `{{IsNewSession}}`| `"true"`, коли створено нову сесію | +| `{{IsNewSession}}` | `"true"`, коли створено нову сесію | | `{{MediaUrl}}` | Псевдо-URL вхідного медіа | | `{{MediaPath}}` | Локальний шлях до медіа | | `{{MediaType}}` | Тип медіа (image/audio/document/…) | -| `{{Transcript}}` | Аудіотранскрипт | -| `{{Prompt}}` | Визначений media prompt для записів CLI | -| `{{MaxChars}}` | Визначений максимум символів виводу для записів CLI | +| `{{Transcript}}` | Транскрипт аудіо | +| `{{Prompt}}` | Визначений prompt медіа для записів CLI | +| `{{MaxChars}}` | Визначена максимальна кількість символів виводу для записів CLI | | `{{ChatType}}` | `"direct"` або `"group"` | -| `{{GroupSubject}}`| Тема групи (best effort) | -| `{{GroupMembers}}`| Попередній перегляд учасників групи (best effort) | -| `{{SenderName}}` | Видиме ім’я відправника (best effort) | +| `{{GroupSubject}}` | Тема групи (best effort) | +| `{{GroupMembers}}` | Попередній перегляд учасників групи (best effort) | +| `{{SenderName}}` | Відображуване ім’я відправника (best effort) | | `{{SenderE164}}` | Номер телефону відправника (best effort) | -| `{{Provider}}` | Підказка про провайдера (whatsapp, telegram, discord тощо) | +| `{{Provider}}` | Підказка провайдера (whatsapp, telegram, discord тощо) | --- ## Include-и конфігурації (`$include`) -Розділяйте конфігурацію на кілька файлів: +Розбивайте конфігурацію на кілька файлів: ```json5 // ~/.openclaw/openclaw.json @@ -3882,13 +3903,13 @@ Hook-token-и в query string відхиляються. **Поведінка злиття:** -- Один файл: замінює об’єкт, у якому міститься. -- Масив файлів: глибоко об’єднується по черзі (пізніші значення перевизначають ранні). -- Сусідні ключі: об’єднуються після include-ів (перевизначають включені значення). +- Один файл: замінює об’єкт-контейнер. +- Масив файлів: глибоко зливається в порядку (пізніші перевизначають попередні). +- Сусідні ключі: зливаються після include-ів (перевизначають включені значення). - Вкладені include-и: до 10 рівнів глибини. -- Шляхи: визначаються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` від `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли вони все одно визначаються в межах цієї межі. -- Помилки: чіткі повідомлення для відсутніх файлів, помилок парсингу та циклічних include-ів. +- Шляхи: визначаються відносно файла, що включає, але мають залишатися всередині каталогу конфігурації верхнього рівня (`dirname` від `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли вони все одно визначаються в межах цієї границі. +- Помилки: зрозумілі повідомлення для відсутніх файлів, помилок парсингу та циклічних include-ів. --- -_Пов’язане: [Configuration](/uk/gateway/configuration) · [Configuration Examples](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_ +_Пов’язане: [Конфігурація](/uk/gateway/configuration) · [Приклади конфігурації](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_ diff --git a/docs/uk/gateway/configuration.md b/docs/uk/gateway/configuration.md index 4c1bd1c5a..79685fa43 100644 --- a/docs/uk/gateway/configuration.md +++ b/docs/uk/gateway/configuration.md @@ -2,32 +2,37 @@ read_when: - Налаштування OpenClaw уперше - Шукаєте поширені шаблони конфігурації - - Перехід до певних розділів конфігурації + - Перехід до конкретних розділів конфігурації summary: 'Огляд конфігурації: поширені завдання, швидке налаштування та посилання на повний довідник' title: Конфігурація x-i18n: - generated_at: "2026-04-22T22:37:31Z" + generated_at: "2026-04-22T22:50:20Z" model: gpt-5.4 provider: openai - source_hash: 966f6a6500fc2f649ee4612404092fd70305065544807c1d8bbc80aa840f9e97 + source_hash: 7b8fccabd04e075f3a59c3b94fe11eca19ddffa2e405d76a9fe92be38ea5a8da source_path: gateway/configuration.md workflow: 15 --- # Конфігурація -OpenClaw зчитує необов’язкову конфігурацію **JSON5** з `~/.openclaw/openclaw.json`. +OpenClaw зчитує необов’язкову конфігурацію **JSON5** з `~/.openclaw/openclaw.json`. +Активний шлях до конфігурації має вказувати на звичайний файл. Схеми +`openclaw.json` із символічними посиланнями не підтримуються для записів, +якими керує OpenClaw; атомарний запис може замінити шлях замість збереження +символічного посилання. Якщо ви зберігаєте конфігурацію поза типовим +каталогом стану, вкажіть `OPENCLAW_CONFIG_PATH` безпосередньо на реальний файл. Якщо файл відсутній, OpenClaw використовує безпечні значення за замовчуванням. Типові причини додати конфігурацію: - Підключити канали та керувати тим, хто може надсилати повідомлення боту -- Налаштувати моделі, інструменти, ізоляцію або автоматизацію (Cron, hooks) -- Тонко налаштувати сесії, медіа, мережу або UI +- Налаштувати моделі, інструменти, ізоляцію або автоматизацію (cron, hooks) +- Налаштувати сесії, медіа, мережу або UI Перегляньте [повний довідник](/uk/gateway/configuration-reference), щоб побачити всі доступні поля. -**Вперше працюєте з конфігурацією?** Почніть з `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) із готовими конфігураціями для копіювання. +**Вперше працюєте з конфігурацією?** Почніть з `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) із готовими конфігураціями для копіювання та вставлення. ## Мінімальна конфігурація @@ -58,11 +63,12 @@ OpenClaw зчитує необов’язкову конфігурацію Відкрийте [http://127.0.0.1:18789](http://127.0.0.1:18789) і використовуйте вкладку **Config**. - Control UI відображає форму з живої схеми конфігурації, включно з метаданими документації полів - `title` / `description`, а також схемами plugin і каналів, коли вони - доступні, з редактором **Raw JSON** як запасним варіантом. Для деталізованих - UI та інших інструментів Gateway також надає `config.schema.lookup`, щоб - отримати один вузол схеми для вказаного шляху разом зі зведеннями про безпосередніх дочірніх елементів. + Control UI відображає форму на основі живої схеми конфігурації, включно з + метаданими документації полів `title` / `description`, а також схемами plugin і каналів, + коли вони доступні, з редактором **Raw JSON** як запасним варіантом. Для + деталізованих UI та інших інструментів gateway також надає `config.schema.lookup` для + отримання одного вузла схеми, обмеженого шляхом, разом із підсумками + безпосередніх дочірніх елементів. Відредагуйте `~/.openclaw/openclaw.json` безпосередньо. Gateway відстежує файл і автоматично застосовує зміни (див. [гаряче перезавантаження](#config-hot-reload)). @@ -72,60 +78,61 @@ OpenClaw зчитує необов’язкову конфігурацію -OpenClaw приймає лише конфігурації, які повністю відповідають схемі. Невідомі ключі, некоректні типи або недійсні значення призводять до того, що Gateway **відмовляється запускатися**. Єдиний виняток на рівні кореня — `$schema` (рядок), щоб редактори могли додавати метадані JSON Schema. +OpenClaw приймає лише конфігурації, які повністю відповідають схемі. Невідомі ключі, некоректні типи або недійсні значення призведуть до того, що Gateway **відмовиться запускатися**. Єдиний виняток на рівні кореня — `$schema` (рядок), щоб редактори могли підключати метадані JSON Schema. -Примітки щодо інструментів схеми: +Нотатки щодо інструментів схем: -- `openclaw config schema` виводить те саме сімейство JSON Schema, яке використовується в Control UI - і для валідації конфігурації. -- Вважайте цей вивід схеми канонічним машиночитним контрактом для +- `openclaw config schema` виводить ту саму сім’ю JSON Schema, яку використовують Control UI + і валідація конфігурації. +- Розглядайте цей вивід схеми як канонічний машиночитаний контракт для `openclaw.json`; цей огляд і довідник з конфігурації його узагальнюють. -- Значення полів `title` і `description` переносяться до виводу схеми для - редакторів і інструментів форм. -- Вкладені об’єкти, записи wildcard (`*`) та елементи масиву (`[]`) успадковують ті самі - метадані документації там, де існує відповідна документація поля. +- Значення полів `title` і `description` переносяться у вивід схеми для + редакторів і інструментів побудови форм. +- Вкладені об’єкти, записи з шаблоном (`*`) і елементи масиву (`[]`) успадковують ті самі + метадані документації, де існує відповідна документація поля. - Гілки композиції `anyOf` / `oneOf` / `allOf` також успадковують ті самі метадані документації, тож варіанти union/intersection зберігають ту саму довідку полів. - `config.schema.lookup` повертає один нормалізований шлях конфігурації з поверхневим - вузлом схеми (`title`, `description`, `type`, `enum`, `const`, поширені обмеження - та подібні поля валідації), відповідні метадані UI-підказок і зведення про безпосередніх дочірніх елементів - для інструментів детального перегляду. -- Схеми plugin/каналів під час виконання об’єднуються, коли gateway може завантажити + вузлом схеми (`title`, `description`, `type`, `enum`, `const`, типові обмеження + та схожі поля валідації), відповідними метаданими підказок UI і підсумками + безпосередніх дочірніх елементів для інструментів деталізації. +- Схеми runtime plugin/каналів об’єднуються, коли gateway може завантажити поточний реєстр маніфестів. -- `pnpm config:docs:check` виявляє розходження між базовими артефактами конфігурації для документації - і поточною поверхнею схеми. +- `pnpm config:docs:check` виявляє розбіжності між артефактами базових конфігурацій + для документації та поточною поверхнею схеми. Коли валідація не проходить: - Gateway не запускається - Працюють лише діагностичні команди (`openclaw doctor`, `openclaw logs`, `openclaw health`, `openclaw status`) -- Запустіть `openclaw doctor`, щоб побачити точні проблеми -- Запустіть `openclaw doctor --fix` (або `--yes`), щоб застосувати виправлення +- Виконайте `openclaw doctor`, щоб побачити точні проблеми +- Виконайте `openclaw doctor --fix` (або `--yes`), щоб застосувати виправлення -Gateway також зберігає довірену останню відому коректну копію після успішного запуску. Якщо -`openclaw.json` пізніше змінюється поза OpenClaw і більше не проходить валідацію, під час запуску -та гарячого перезавантаження зламаний файл зберігається як `.clobbered.*`-знімок із часовою позначкою, -відновлюється остання відома коректна копія, а в журнал записується помітне попередження з причиною відновлення. -Відновлення під час читання на старті також вважає критичними ознаками пошкодження різке зменшення розміру, -відсутні метадані конфігурації та відсутність `gateway.mode`, коли в останній відомій коректній -копії ці поля були. -Якщо перед інакше коректною конфігурацією JSON випадково додається рядок статусу/журналу, -запуск gateway і `openclaw doctor --fix` можуть прибрати цей префікс, -зберегти забруднений файл як `.clobbered.*` і продовжити роботу з відновленим -JSON. -Наступний хід головного агента також отримує попередження системної події про те, що -конфігурацію було відновлено і її не можна бездумно перезаписувати. Підвищення статусу останньої відомої коректної копії -оновлюється після валідованого запуску і після прийнятих гарячих перезавантажень, включно з -записами конфігурації, виконаними самим OpenClaw, якщо хеш збереженого файла все ще збігається з прийнятим -записом. Підвищення пропускається, коли кандидат містить замасковані заповнювачі секретів, -такі як `***` або скорочені значення токенів. +Gateway також зберігає довірену останню відому справну копію після успішного запуску. Якщо +`openclaw.json` пізніше змінено поза OpenClaw і він більше не проходить валідацію, під час запуску +та гарячого перезавантаження пошкоджений файл зберігається як знімок `.clobbered.*` із часовою +міткою, відновлюється остання відома справна копія, а в журнали записується +помітне попередження з причиною відновлення. Відновлення під час читання на +запуску також розглядає різке зменшення розміру, відсутність метаданих +конфігурації та відсутність `gateway.mode` як критичні ознаки пошкодження, якщо +в останній відомій справній копії ці поля були. +Якщо рядок статусу/журналу випадково додається на початку перед інакше +коректною JSON-конфігурацією, запуск gateway і `openclaw doctor --fix` можуть +видалити цей префікс, зберегти забруднений файл як `.clobbered.*` і продовжити +роботу з відновленим JSON. +Наступний хід основного агента також отримує попередження про системну подію, яке повідомляє, +що конфігурацію було відновлено і її не можна бездумно перезаписувати. Підвищення статусу +останньої відомої справної копії оновлюється після валідованого запуску та після прийнятих +гарячих перезавантажень, включно із записами конфігурації, якими керує OpenClaw, коли хеш +збереженого файла все ще збігається з прийнятим записом. Підвищення статусу пропускається, +якщо кандидат містить замасковані заповнювачі секретів, такі як `***` або скорочені значення токенів. ## Поширені завдання - Кожен канал має власний розділ конфігурації в `channels.`. Дивіться окрему сторінку каналу для кроків налаштування: + Кожен канал має власний розділ конфігурації в `channels.`. Перегляньте окрему сторінку каналу для кроків налаштування: - [WhatsApp](/uk/channels/whatsapp) — `channels.whatsapp` - [Telegram](/uk/channels/telegram) — `channels.telegram` @@ -138,7 +145,7 @@ JSON. - [iMessage](/uk/channels/imessage) — `channels.imessage` - [Mattermost](/uk/channels/mattermost) — `channels.mattermost` - Усі канали використовують однаковий шаблон політики DM: + Усі канали мають спільний шаблон політики DM: ```json5 { @@ -156,7 +163,7 @@ JSON. - Задайте основну модель і необов’язкові резервні варіанти: + Установіть основну модель і необов’язкові резервні: ```json5 { @@ -176,30 +183,30 @@ JSON. ``` - `agents.defaults.models` визначає каталог моделей і слугує allowlist для `/model`. - - Використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додати записи до allowlist без видалення наявних моделей. Звичайні заміни, які видаляють записи, відхиляються, якщо не передати `--replace`. + - Використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додати записи до allowlist без видалення наявних моделей. Звичайні заміни, які видалили б записи, відхиляються, якщо не передати `--replace`. - Посилання на моделі використовують формат `provider/model` (наприклад, `anthropic/claude-opus-4-6`). - - `agents.defaults.imageMaxDimensionPx` керує зменшенням розміру зображень у transcript/tool (типове значення `1200`); менші значення зазвичай зменшують використання vision-токенів у сценаріях із великою кількістю скриншотів. - - Дивіться [Models CLI](/uk/concepts/models) для перемикання моделей у чаті та [Model Failover](/uk/concepts/model-failover) для ротації авторизації та поведінки резервних моделей. - - Для власних/self-hosted provider див. [Custom providers](/uk/gateway/configuration-reference#custom-providers-and-base-urls) у довіднику. + - `agents.defaults.imageMaxDimensionPx` керує зменшенням розміру зображень у транскрипті/інструментах (типове значення `1200`); нижчі значення зазвичай зменшують використання vision-токенів у запусках із великою кількістю скриншотів. + - Перегляньте [Models CLI](/uk/concepts/models), щоб перемикати моделі в чаті, і [Model Failover](/uk/concepts/model-failover), щоб дізнатися про ротацію автентифікації та поведінку резервного перемикання. + - Для користувацьких/self-hosted provider перегляньте [Custom providers](/uk/gateway/configuration-reference#custom-providers-and-base-urls) у довіднику. Доступ до DM керується окремо для кожного каналу через `dmPolicy`: - - `"pairing"` (типово): невідомі відправники отримують одноразовий код pairing для підтвердження + - `"pairing"` (типово): невідомі відправники отримують одноразовий код сполучення для підтвердження - `"allowlist"`: лише відправники з `allowFrom` (або зі сховища paired allow) - `"open"`: дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`) - `"disabled"`: ігнорувати всі DM - Для груп використовуйте `groupPolicy` + `groupAllowFrom` або allowlist, специфічні для каналу. + Для груп використовуйте `groupPolicy` + `groupAllowFrom` або списки дозволених, специфічні для каналу. - Дивіться [повний довідник](/uk/gateway/configuration-reference#dm-and-group-access) для подробиць по кожному каналу. + Перегляньте [повний довідник](/uk/gateway/configuration-reference#dm-and-group-access), щоб дізнатися деталі для кожного каналу. - - Для групових повідомлень типово **потрібна згадка**. Налаштуйте шаблони для кожного агента: + + Для групових повідомлень типовим є режим **вимагати згадування**. Налаштуйте шаблони для кожного агента: ```json5 { @@ -221,13 +228,13 @@ JSON. } ``` - - **Згадки в метаданих**: нативні @-згадки (tap-to-mention у WhatsApp, @bot у Telegram тощо) + - **Згадування в метаданих**: нативні @-згадування (WhatsApp tap-to-mention, Telegram @bot тощо) - **Текстові шаблони**: безпечні regex-шаблони в `mentionPatterns` - - Дивіться [повний довідник](/uk/gateway/configuration-reference#group-chat-mention-gating) для по-канальних перевизначень і режиму self-chat. + - Перегляньте [повний довідник](/uk/gateway/configuration-reference#group-chat-mention-gating), щоб дізнатися про перевизначення для окремих каналів і режим self-chat. - + Використовуйте `agents.defaults.skills` для спільної базової конфігурації, а потім перевизначайте конкретних агентів через `agents.list[].skills`: @@ -238,18 +245,18 @@ JSON. skills: ["github", "weather"], }, list: [ - { id: "writer" }, // успадковує github, weather - { id: "docs", skills: ["docs-search"] }, // замінює значення за замовчуванням - { id: "locked-down", skills: [] }, // без Skills + { id: "writer" }, // inherits github, weather + { id: "docs", skills: ["docs-search"] }, // replaces defaults + { id: "locked-down", skills: [] }, // no skills ], }, } ``` - - Не вказуйте `agents.defaults.skills`, якщо типово Skills не мають бути обмежені. - - Не вказуйте `agents.list[].skills`, щоб успадкувати значення за замовчуванням. - - Встановіть `agents.list[].skills: []`, щоб не дозволити жодних Skills. - - Дивіться [Skills](/uk/tools/skills), [конфігурацію Skills](/uk/tools/skills-config) і + - Опустіть `agents.defaults.skills`, щоб за замовчуванням Skills не були обмежені. + - Опустіть `agents.list[].skills`, щоб успадкувати значення за замовчуванням. + - Установіть `agents.list[].skills: []`, щоб не використовувати Skills. + - Перегляньте [Skills](/uk/tools/skills), [конфігурацію Skills](/uk/tools/skills-config) і [Довідник з конфігурації](/uk/gateway/configuration-reference#agents-defaults-skills). @@ -277,10 +284,10 @@ JSON. } ``` - - Встановіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски через моніторинг стану. - - `channelStaleEventThresholdMinutes` має бути більшим або дорівнювати інтервалу перевірки. - - Використовуйте `channels..healthMonitor.enabled` або `channels..accounts..healthMonitor.enabled`, щоб вимкнути автоперезапуски для одного каналу або облікового запису без вимкнення глобального монітора. - - Дивіться [Health Checks](/uk/gateway/health) для операційного налагодження та [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів. + - Установіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски моніторингу стану. + - `channelStaleEventThresholdMinutes` має бути більшим або рівним інтервалу перевірки. + - Використовуйте `channels..healthMonitor.enabled` або `channels..accounts..healthMonitor.enabled`, щоб вимкнути автоперезапуски для одного каналу або облікового запису без вимкнення глобального моніторингу. + - Перегляньте [Health Checks](/uk/gateway/health) для операційного налагодження і [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів. @@ -290,7 +297,7 @@ JSON. ```json5 { session: { - dmScope: "per-channel-peer", // рекомендовано для багатьох користувачів + dmScope: "per-channel-peer", // recommended for multi-user threadBindings: { enabled: true, idleHours: 24, @@ -305,15 +312,15 @@ JSON. } ``` - - `dmScope`: `main` (спільна) | `per-peer` | `per-channel-peer` | `per-account-channel-peer` - - `threadBindings`: глобальні значення за замовчуванням для маршрутизації сесій, прив’язаних до thread (Discord підтримує `/focus`, `/unfocus`, `/agents`, `/session idle` і `/session max-age`). - - Дивіться [Керування сесіями](/uk/concepts/session) для області дії, зв’язків ідентичностей і політики надсилання. - - Дивіться [повний довідник](/uk/gateway/configuration-reference#session) для всіх полів. + - `dmScope`: `main` (спільний) | `per-peer` | `per-channel-peer` | `per-account-channel-peer` + - `threadBindings`: глобальні значення за замовчуванням для маршрутизації сесій, прив’язаних до тредів (Discord підтримує `/focus`, `/unfocus`, `/agents`, `/session idle` і `/session max-age`). + - Перегляньте [Керування сесіями](/uk/concepts/session), щоб дізнатися про область дії, зв’язки ідентичностей і політику надсилання. + - Перегляньте [повний довідник](/uk/gateway/configuration-reference#session), щоб побачити всі поля. - Запускайте сесії агентів в ізольованих runtime ізолятора: + Запускайте сесії агентів в ізольованих runtime ізоляції: ```json5 { @@ -330,14 +337,14 @@ JSON. Спочатку зберіть образ: `scripts/sandbox-setup.sh` - Дивіться [Sandboxing](/uk/gateway/sandboxing) для повного посібника та [повний довідник](/uk/gateway/configuration-reference#agentsdefaultssandbox) для всіх параметрів. + Перегляньте [Ізоляція](/uk/gateway/sandboxing) для повного посібника та [повний довідник](/uk/gateway/configuration-reference#agentsdefaultssandbox) для всіх параметрів. - - Relay-backed push налаштовується в `openclaw.json`. + + Push через relay налаштовується в `openclaw.json`. - Укажіть це в конфігурації gateway: + Установіть це в конфігурації gateway: ```json5 { @@ -355,7 +362,7 @@ JSON. } ``` - Еквівалент через CLI: + Еквівалент у CLI: ```bash openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com @@ -363,31 +370,31 @@ JSON. Що це робить: - - Дозволяє gateway надсилати `push.test`, сигнали пробудження та сигнали повторного підключення через зовнішній relay. - - Використовує grant на надсилання в межах реєстрації, який пересилає спарений застосунок iOS. Gateway не потрібен relay-токен для всього розгортання. - - Прив’язує кожну relay-backed реєстрацію до ідентичності gateway, з якою було спарено застосунок iOS, тож інший gateway не може повторно використати збережену реєстрацію. - - Залишає локальні/ручні збірки iOS на прямому APNs. Relay-backed надсилання застосовується лише до офіційно розповсюджених збірок, які зареєструвалися через relay. - - Має збігатися з базовим URL relay, вбудованим в офіційну/TestFlight збірку iOS, щоб трафік реєстрації й надсилання потрапляв до одного й того самого розгортання relay. + - Дозволяє gateway надсилати `push.test`, сигнали пробудження та пробудження для перепідключення через зовнішній relay. + - Використовує право надсилання, обмежене реєстрацією, яке пересилає спарений застосунок iOS. Gateway не потрібен relay-токен для всього розгортання. + - Прив’язує кожну реєстрацію через relay до ідентичності gateway, з якою був спарений застосунок iOS, тож інший gateway не може повторно використати збережену реєстрацію. + - Залишає локальні/ручні збірки iOS на прямому APNs. Надсилання через relay застосовуються лише до офіційно розповсюджуваних збірок, які зареєструвалися через relay. + - Має збігатися з базовим URL relay, вбудованим в офіційну/TestFlight збірку iOS, щоб трафік реєстрації та надсилання потрапляв до того самого розгортання relay. - Повний потік end-to-end: + Повний потік роботи: 1. Установіть офіційну/TestFlight збірку iOS, скомпільовану з тим самим базовим URL relay. 2. Налаштуйте `gateway.push.apns.relay.baseUrl` на gateway. - 3. Спарте застосунок iOS із gateway і дочекайтеся підключення як node-, так і operator-сесій. - 4. Застосунок iOS отримує ідентичність gateway, реєструється в relay за допомогою App Attest і квитанції застосунку, а потім публікує relay-backed payload `push.apns.register` у спарений gateway. - 5. Gateway зберігає relay handle і send grant, а потім використовує їх для `push.test`, сигналів пробудження та сигналів повторного підключення. + 3. Спарте застосунок iOS із gateway і дозвольте підключитися як сесіям node, так і сесіям оператора. + 4. Застосунок iOS отримує ідентичність gateway, реєструється в relay за допомогою App Attest і квитанції застосунку, а потім публікує payload `push.apns.register` через relay до спареного gateway. + 5. Gateway зберігає relay handle і право надсилання, а потім використовує їх для `push.test`, сигналів пробудження та пробуджень для перепідключення. Операційні примітки: - - Якщо ви перемикаєте застосунок iOS на інший gateway, перепідключіть застосунок, щоб він міг опублікувати нову relay-реєстрацію, прив’язану до цього gateway. - - Якщо ви випускаєте нову збірку iOS, що вказує на інше розгортання relay, застосунок оновлює кешовану relay-реєстрацію замість повторного використання старого relay-origin. + - Якщо ви перемикаєте застосунок iOS на інший gateway, перепідключіть застосунок, щоб він міг опублікувати нову реєстрацію relay, прив’язану до цього gateway. + - Якщо ви випускаєте нову збірку iOS, яка вказує на інше розгортання relay, застосунок оновлює кешовану реєстрацію relay замість повторного використання старого relay origin. Примітка щодо сумісності: - `OPENCLAW_APNS_RELAY_BASE_URL` і `OPENCLAW_APNS_RELAY_TIMEOUT_MS` усе ще працюють як тимчасові перевизначення через env. - - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` лишається запасним варіантом для розробки лише в local loopback; не зберігайте HTTP relay URL у конфігурації. + - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` залишається доступним лише для loopback аварійним варіантом розробки; не зберігайте HTTP URL relay у конфігурації. - Дивіться [iOS App](/uk/platforms/ios#relay-backed-push-for-official-builds) для повного end-to-end потоку та [Authentication and trust flow](/uk/platforms/ios#authentication-and-trust-flow) для моделі безпеки relay. + Перегляньте [Застосунок iOS](/uk/platforms/ios#relay-backed-push-for-official-builds) для повного потоку та [Потік автентифікації й довіри](/uk/platforms/ios#authentication-and-trust-flow) для моделі безпеки relay. @@ -408,7 +415,7 @@ JSON. - `every`: рядок тривалості (`30m`, `2h`). Установіть `0m`, щоб вимкнути. - `target`: `last` | `none` | `` (наприклад, `discord`, `matrix`, `telegram` або `whatsapp`) - `directPolicy`: `allow` (типово) або `block` для цілей Heartbeat у стилі DM - - Дивіться [Heartbeat](/uk/gateway/heartbeat) для повного посібника. + - Перегляньте [Heartbeat](/uk/gateway/heartbeat) для повного посібника. @@ -427,14 +434,14 @@ JSON. } ``` - - `sessionRetention`: очищати завершені ізольовані сесії запуску з `sessions.json` (типово `24h`; установіть `false`, щоб вимкнути). - - `runLog`: очищати `cron/runs/.jsonl` за розміром і кількістю збережених рядків. - - Дивіться [Завдання Cron](/uk/automation/cron-jobs) для огляду функції та прикладів CLI. + - `sessionRetention`: очищення завершених ізольованих сесій запуску з `sessions.json` (типово `24h`; установіть `false`, щоб вимкнути). + - `runLog`: очищення `cron/runs/.jsonl` за розміром і кількістю збережених рядків. + - Перегляньте [Завдання Cron](/uk/automation/cron-jobs) для огляду можливостей і прикладів CLI. - - Увімкніть HTTP-ендпоїнти Webhook на Gateway: + + Увімкніть HTTP endpoint-и Webhook на Gateway: ```json5 { @@ -458,20 +465,20 @@ JSON. ``` Примітка щодо безпеки: - - Увесь вміст payload hook/Webhook слід вважати недовіреним введенням. + - Вважайте весь вміст payload hook/Webhook ненадійним введенням. - Використовуйте окремий `hooks.token`; не використовуйте повторно спільний токен Gateway. - - Автентифікація hook працює лише через заголовки (`Authorization: Bearer ...` або `x-openclaw-token`); токени в query-рядку відхиляються. - - `hooks.path` не може бути `/`; використовуйте для входу Webhook окремий підшлях, наприклад `/hooks`. - - Тримайте прапорці обходу небезпечного вмісту вимкненими (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), якщо не виконуєте вузькоспрямоване налагодження. - - Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також задайте `hooks.allowedSessionKeyPrefixes`, щоб обмежити session key, які може вибрати викликач. - - Для агентів, керованих hook, надавайте перевагу сильним сучасним рівням моделей і суворій політиці інструментів (наприклад, лише обмін повідомленнями плюс ізоляція, де це можливо). + - Автентифікація hook працює лише через заголовки (`Authorization: Bearer ...` або `x-openclaw-token`); токени в рядку запиту відхиляються. + - `hooks.path` не може бути `/`; використовуйте для вхідних Webhook окремий підшлях, наприклад `/hooks`. + - Тримайте прапорці обходу небезпечного вмісту вимкненими (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), якщо не виконуєте строго обмежене налагодження. + - Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також установіть `hooks.allowedSessionKeyPrefixes`, щоб обмежити ключі сесій, які може вибирати викликач. + - Для агентів, що працюють через hooks, віддавайте перевагу сильним сучасним рівням моделей і суворій політиці інструментів (наприклад, лише обмін повідомленнями плюс ізоляція, де це можливо). - Дивіться [повний довідник](/uk/gateway/configuration-reference#hooks) для всіх параметрів mappings та інтеграції Gmail. + Перегляньте [повний довідник](/uk/gateway/configuration-reference#hooks), щоб побачити всі параметри mapping і інтеграцію з Gmail. - - Запускайте кілька ізольованих агентів з окремими workspace і сесіями: + + Запускайте кількох ізольованих агентів з окремими робочими просторами та сесіями: ```json5 { @@ -488,12 +495,12 @@ JSON. } ``` - Дивіться [Multi-Agent](/uk/concepts/multi-agent) і [повний довідник](/uk/gateway/configuration-reference#multi-agent-routing) для правил bindings і профілів доступу для кожного агента. + Перегляньте [Multi-Agent](/uk/concepts/multi-agent) і [повний довідник](/uk/gateway/configuration-reference#multi-agent-routing), щоб дізнатися про правила binding і профілі доступу для кожного агента. - Використовуйте `$include` для організації великих конфігурацій: + Використовуйте `$include`, щоб упорядкувати великі конфігурації: ```json5 // ~/.openclaw/openclaw.json @@ -506,12 +513,12 @@ JSON. } ``` - - **Один файл**: замінює об’єкт, що його містить - - **Масив файлів**: глибоко об’єднується за порядком (пізніші значення мають пріоритет) - - **Сусідні ключі**: об’єднуються після includes (перевизначають включені значення) - - **Вкладені includes**: підтримуються до 10 рівнів вкладеності - - **Відносні шляхи**: обчислюються відносно файлу, який виконує включення - - **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок парсингу та циклічних includes + - **Один файл**: замінює об’єкт, у якому міститься + - **Масив файлів**: глибоко об’єднується за порядком (пізніший має пріоритет) + - **Сусідні ключі**: об’єднуються після include-ів (перевизначають включені значення) + - **Вкладені include-и**: підтримуються до 10 рівнів вкладеності + - **Відносні шляхи**: обчислюються відносно файла, який виконує включення + - **Обробка помилок**: чіткі помилки для відсутніх файлів, помилок парсингу та циклічних include-ів @@ -520,26 +527,26 @@ JSON. Gateway відстежує `~/.openclaw/openclaw.json` і автоматично застосовує зміни — для більшості налаштувань ручний перезапуск не потрібен. -Прямі редагування файлу вважаються недовіреними, доки не пройдуть валідацію. Спостерігач чекає, -поки завершаться тимчасові записи/перейменування редактора, читає підсумковий файл і відхиляє -некоректні зовнішні редагування, відновлюючи останню відому коректну конфігурацію. Власні записи конфігурації OpenClaw -використовують той самий контроль схеми перед записом; руйнівні пошкодження, такі +Прямі зміни файлу вважаються ненадійними, доки не пройдуть валідацію. Спостерігач +чекає, поки завершиться тимчасовий запис/перейменування редактора, зчитує +фінальний файл і відхиляє недійсні зовнішні зміни, відновлюючи останню відому +справну конфігурацію. Записи конфігурації, якими керує OpenClaw, проходять ту саму перевірку схемою перед записом; руйнівні пошкодження, такі як видалення `gateway.mode` або зменшення файлу більш ніж удвічі, відхиляються і зберігаються як `.rejected.*` для перевірки. -Якщо ви бачите `Config auto-restored from last-known-good` або -`config reload restored last-known-good config` у журналах, перевірте відповідний -файл `.clobbered.*` поруч із `openclaw.json`, виправте відхилений payload, а потім запустіть -`openclaw config validate`. Дивіться [усунення проблем Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config) -для контрольного списку відновлення. +Якщо ви бачите в журналах `Config auto-restored from last-known-good` або +`config reload restored last-known-good config`, перевірте відповідний +файл `.clobbered.*` поруч із `openclaw.json`, виправте відхилений payload, а потім виконайте +`openclaw config validate`. Перегляньте [Усунення проблем Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config), +щоб ознайомитися з контрольним списком відновлення. ### Режими перезавантаження -| Режим | Поведінка | -| ---------------------- | -------------------------------------------------------------------------------------- | -| **`hybrid`** (типово) | Миттєво гаряче застосовує безпечні зміни. Автоматично перезапускається для критичних. | -| **`hot`** | Гаряче застосовує лише безпечні зміни. Записує попередження, коли потрібен перезапуск — ви виконуєте його самі. | -| **`restart`** | Перезапускає Gateway за будь-якої зміни конфігурації, безпечної чи ні. | +| Режим | Поведінка | +| ---------------------- | ---------------------------------------------------------------------------------------- | +| **`hybrid`** (типово) | Миттєво гаряче застосовує безпечні зміни. Для критичних змін автоматично перезапускає. | +| **`hot`** | Гаряче застосовує лише безпечні зміни. Записує попередження, коли потрібен перезапуск — ви обробляєте це самі. | +| **`restart`** | Перезапускає Gateway за будь-якої зміни конфігурації, безпечної чи ні. | | **`off`** | Вимикає відстеження файлу. Зміни набудуть чинності під час наступного ручного перезапуску. | ```json5 @@ -554,42 +561,42 @@ Gateway відстежує `~/.openclaw/openclaw.json` і автоматично Більшість полів застосовуються гаряче без простою. У режимі `hybrid` зміни, що потребують перезапуску, обробляються автоматично. -| Категорія | Поля | Потрібен перезапуск? | -| ------------------ | ----------------------------------------------------------------- | -------------------- | -| Канали | `channels.*`, `web` (WhatsApp) — усі вбудовані канали й канали plugin | Ні | -| Агенти й моделі | `agent`, `agents`, `models`, `routing` | Ні | -| Автоматизація | `hooks`, `cron`, `agent.heartbeat` | Ні | -| Сесії та повідомлення | `session`, `messages` | Ні | -| Інструменти й медіа | `tools`, `browser`, `skills`, `audio`, `talk` | Ні | -| UI та інше | `ui`, `logging`, `identity`, `bindings` | Ні | -| Сервер Gateway | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **Так** | -| Інфраструктура | `discovery`, `canvasHost`, `plugins` | **Так** | +| Категорія | Поля | Потрібен перезапуск? | +| -------------------- | ----------------------------------------------------------------- | -------------------- | +| Канали | `channels.*`, `web` (WhatsApp) — усі вбудовані канали та канали plugin | Ні | +| Агент і моделі | `agent`, `agents`, `models`, `routing` | Ні | +| Автоматизація | `hooks`, `cron`, `agent.heartbeat` | Ні | +| Сесії та повідомлення | `session`, `messages` | Ні | +| Інструменти й медіа | `tools`, `browser`, `skills`, `audio`, `talk` | Ні | +| UI та інше | `ui`, `logging`, `identity`, `bindings` | Ні | +| Сервер Gateway | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **Так** | +| Інфраструктура | `discovery`, `canvasHost`, `plugins` | **Так** | -`gateway.reload` і `gateway.remote` — винятки; їх зміна **не** спричиняє перезапуск. +`gateway.reload` і `gateway.remote` — винятки: їх зміна **не** спричиняє перезапуск. ## RPC конфігурації (програмні оновлення) -RPC керуючої площини для запису (`config.apply`, `config.patch`, `update.run`) мають обмеження швидкості — **3 запити за 60 секунд** на `deviceId+clientIp`. При спрацюванні обмеження RPC повертає `UNAVAILABLE` з `retryAfterMs`. +RPC керувальної площини для запису (`config.apply`, `config.patch`, `update.run`) обмежуються до **3 запитів за 60 секунд** на `deviceId+clientIp`. При спрацюванні обмеження RPC повертає `UNAVAILABLE` з `retryAfterMs`. Безпечний/типовий потік: -- `config.schema.lookup`: переглянути одне піддерево конфігурації для вказаного шляху з поверхневим - вузлом схеми, відповідними метаданими підказок і зведеннями про безпосередніх дочірніх елементів -- `config.get`: отримати поточний знімок + хеш -- `config.patch`: бажаний шлях для часткового оновлення +- `config.schema.lookup`: перевірка одного піддерева конфігурації, обмеженого шляхом, з поверхневим + вузлом схеми, відповідними метаданими підказок і підсумками безпосередніх дочірніх елементів +- `config.get`: отримання поточного знімка + hash +- `config.patch`: бажаний шлях часткового оновлення - `config.apply`: лише повна заміна конфігурації -- `update.run`: явне self-update + перезапуск +- `update.run`: явне самооновлення + перезапуск -Якщо ви не замінюєте всю конфігурацію, надавайте перевагу `config.schema.lookup`, +Коли ви не замінюєте всю конфігурацію, віддавайте перевагу `config.schema.lookup`, а потім `config.patch`. - Виконує валідацію + записує повну конфігурацію та перезапускає Gateway одним кроком. + Виконує валідацію + записує повну конфігурацію та перезапускає Gateway за один крок. `config.apply` замінює **всю конфігурацію**. Використовуйте `config.patch` для часткових оновлень або `openclaw config set` для окремих ключів. @@ -598,15 +605,15 @@ RPC керуючої площини для запису (`config.apply`, `config Параметри: - `raw` (string) — payload JSON5 для всієї конфігурації - - `baseHash` (необов’язково) — хеш конфігурації з `config.get` (обов’язковий, якщо конфігурація існує) - - `sessionKey` (необов’язково) — session key для wake-up ping після перезапуску - - `note` (необов’язково) — примітка для sentinel перезапуску - - `restartDelayMs` (необов’язково) — затримка перед перезапуском (типово 2000) + - `baseHash` (optional) — hash конфігурації з `config.get` (обов’язковий, якщо конфігурація існує) + - `sessionKey` (optional) — ключ сесії для wake-up ping після перезапуску + - `note` (optional) — примітка для restart sentinel + - `restartDelayMs` (optional) — затримка перед перезапуском (типово 2000) - Запити на перезапуск об’єднуються, якщо один уже очікує або виконується, і між циклами перезапуску діє 30-секундний період охолодження. + Запити на перезапуск об’єднуються, якщо один уже очікує/виконується, і між циклами перезапуску діє 30-секундний cooldown. ```bash - openclaw gateway call config.get --params '{}' # зафіксувати payload.hash + openclaw gateway call config.get --params '{}' # capture payload.hash openclaw gateway call config.apply --params '{ "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }", "baseHash": "", @@ -626,10 +633,10 @@ RPC керуючої площини для запису (`config.apply`, `config Параметри: - `raw` (string) — JSON5 лише з тими ключами, які потрібно змінити - - `baseHash` (обов’язково) — хеш конфігурації з `config.get` - - `sessionKey`, `note`, `restartDelayMs` — так само, як у `config.apply` + - `baseHash` (required) — hash конфігурації з `config.get` + - `sessionKey`, `note`, `restartDelayMs` — такі самі, як у `config.apply` - Поведінка перезапуску відповідає `config.apply`: об’єднання очікуваних перезапусків плюс 30-секундний період охолодження між циклами перезапуску. + Поведінка перезапуску збігається з `config.apply`: об’єднання відкладених перезапусків плюс 30-секундний cooldown між циклами перезапуску. ```bash openclaw gateway call config.patch --params '{ @@ -643,12 +650,12 @@ RPC керуючої площини для запису (`config.apply`, `config ## Змінні середовища -OpenClaw зчитує env vars із батьківського процесу, а також з: +OpenClaw зчитує env vars з батьківського процесу, а також із: - `.env` у поточному робочому каталозі (якщо є) - `~/.openclaw/.env` (глобальний запасний варіант) -Жоден із цих файлів не перевизначає вже наявні env vars. Ви також можете задавати вбудовані env vars у конфігурації: +Жоден із цих файлів не перевизначає наявні env vars. Ви також можете встановлювати вбудовані env vars у конфігурації: ```json5 { @@ -659,8 +666,8 @@ OpenClaw зчитує env vars із батьківського процесу, } ``` - - Якщо його ввімкнено і очікувані ключі не встановлені, OpenClaw запускає вашу login shell і імпортує лише відсутні ключі: + + Якщо ввімкнено і очікувані ключі не встановлено, OpenClaw запускає вашу login shell і імпортує лише відсутні ключі: ```json5 { @@ -670,11 +677,11 @@ OpenClaw зчитує env vars із батьківського процесу, } ``` -Еквівалент через env var: `OPENCLAW_LOAD_SHELL_ENV=1` +Еквівалент env var: `OPENCLAW_LOAD_SHELL_ENV=1` - Посилайтеся на env vars у будь-якому рядковому значенні конфігурації за допомогою `${VAR_NAME}`: + Посилайтеся на env vars у будь-якому рядковому значенні конфігурації через `${VAR_NAME}`: ```json5 { @@ -687,14 +694,14 @@ OpenClaw зчитує env vars із батьківського процесу, - Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*` - Відсутні/порожні змінні спричиняють помилку під час завантаження -- Екрануйте через `$${VAR}` для буквального виводу +- Використовуйте `$${VAR}` для буквального виводу - Працює всередині файлів `$include` - Вбудована підстановка: `"${BASE}/v1"` → `"https://api.example.com/v1"` - Для полів, що підтримують об’єкти SecretRef, можна використовувати: + Для полів, які підтримують об’єкти SecretRef, можна використовувати: ```json5 { @@ -726,15 +733,15 @@ OpenClaw зчитує env vars із батьківського процесу, } ``` -Подробиці про SecretRef (включно з `secrets.providers` для `env`/`file`/`exec`) наведені в [Керуванні секретами](/uk/gateway/secrets). -Підтримувані шляхи облікових даних наведені в [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface). +Докладно про SecretRef (включно з `secrets.providers` для `env`/`file`/`exec`) можна прочитати в [Керування секретами](/uk/gateway/secrets). +Підтримувані шляхи облікових даних перелічено в [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface). -Дивіться [Середовище](/uk/help/environment) для повного порядку пріоритетів і джерел. +Перегляньте [Середовище](/uk/help/environment), щоб дізнатися про повний пріоритет і джерела. ## Повний довідник -Повний довідник по всіх полях див. у **[Довіднику з конфігурації](/uk/gateway/configuration-reference)**. +Повний довідник по полях дивіться в **[Довіднику з конфігурації](/uk/gateway/configuration-reference)**. --- diff --git a/docs/uk/gateway/security/index.md b/docs/uk/gateway/security/index.md index 71148c53a..710d36913 100644 --- a/docs/uk/gateway/security/index.md +++ b/docs/uk/gateway/security/index.md @@ -1,13 +1,13 @@ --- read_when: - Додавання функцій, які розширюють доступ або автоматизацію -summary: Міркування щодо безпеки та модель загроз для запуску AI-шлюзу з доступом до оболонки +summary: Міркування безпеки та модель загроз для запуску AI Gateway із доступом до оболонки title: Безпека x-i18n: - generated_at: "2026-04-21T21:40:50Z" + generated_at: "2026-04-22T22:50:25Z" model: gpt-5.4 provider: openai - source_hash: f4cf3b71c6c22b8c0b06855de7496265d23b4e7510e339301c85b2438ed94b3b + source_hash: 47f524e57500faff35363f656c199e60bf51364f6aeb94114e1a0885ce04b128 source_path: gateway/security/index.md workflow: 15 --- @@ -15,23 +15,23 @@ x-i18n: # Безпека -**Модель довіри для персонального асистента:** ці рекомендації виходять із припущення про одну межу довіри для одного оператора на 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) +**На цій сторінці:** [Модель довіри](#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 виходять із моделі розгортання **персонального асистента**: одна межа довіри для одного оператора, потенційно багато agent. +Рекомендації з безпеки OpenClaw припускають розгортання **персонального помічника**: одна межа довіри оператора, потенційно багато агентів. -- Підтримувана безпекова модель: один користувач/межа довіри на Gateway (бажано один користувач ОС/хост/VPS на межу). -- Модель, яка не підтримується як межа безпеки: один спільний Gateway/agent, яким користуються взаємно недовірені або змагальні користувачі. -- Якщо потрібна ізоляція змагальних користувачів, розділяйте за межами довіри (окремий Gateway + облікові дані, і бажано окремі користувачі ОС/хости). -- Якщо кілька недовірених користувачів можуть надсилати повідомлення одному agent з увімкненими інструментами, вважайте, що вони спільно використовують однакові делеговані повноваження цього agent щодо інструментів. +- Підтримувана модель безпеки: один користувач/межа довіри на gateway (бажано один користувач ОС/хост/VPS на одну межу). +- Модель, яка не підтримується як межа безпеки: один спільний gateway/агент, який використовують взаємно недовірені або зловмисні користувачі. +- Якщо потрібна ізоляція від зловмисних користувачів, розділяйте за межами довіри (окремий gateway + облікові дані, а в ідеалі окремі користувачі ОС/хости). +- Якщо кілька недовірених користувачів можуть надсилати повідомлення одному агенту з увімкненими інструментами, вважайте, що вони спільно використовують однакові делеговані повноваження цього агента щодо інструментів. -Ця сторінка пояснює посилення захисту **в межах цієї моделі**. Вона не стверджує наявність ворожої багатокористувацької ізоляції на одному спільному Gateway. +Ця сторінка пояснює посилення безпеки **в межах цієї моделі**. Вона не заявляє про ізоляцію ворожих багатокористувацьких сценаріїв на одному спільному gateway. ## Швидка перевірка: `openclaw security audit` @@ -46,103 +46,103 @@ openclaw security audit --fix openclaw security audit --json ``` -`security audit --fix` навмисно має вузьку дію: він перемикає типові відкриті групові політики на allowlist, відновлює `logging.redactSensitive: "tools"`, посилює дозволи на state/config/include-файли та використовує скидання ACL Windows замість POSIX `chmod` під час роботи у Windows. +`security audit --fix` навмисно має вузьку сферу дії: він перемикає поширені відкриті групові політики на allowlist, відновлює `logging.redactSensitive: "tools"`, посилює дозволи для state/config/include-файлів і використовує скидання Windows ACL замість POSIX `chmod` під час роботи в Windows. -Він виявляє типові небезпечні помилки конфігурації (відкритий доступ до Gateway auth, відкритий доступ до керування браузером, підвищені allowlist, дозволи файлової системи, надто ліберальні схвалення exec та відкритий доступ до інструментів через channel). +Він виявляє типові небезпечні конфігурації (відкриту автентифікацію Gateway, відкритий доступ до керування браузером, розширені allowlist, дозволи файлової системи, надто поблажливі підтвердження exec і відкритий доступ до інструментів через канали). -OpenClaw — це і продукт, і експеримент: ви підключаєте поведінку frontier-моделей до реальних поверхонь обміну повідомленнями та реальних інструментів. **Ідеально безпечної конфігурації не існує.** Мета — свідомо визначити: +OpenClaw — це і продукт, і експеримент: ви підключаєте поведінку frontier-model до реальних поверхонь обміну повідомленнями та реальних інструментів. **Ідеально безпечної** конфігурації не існує. Мета — свідомо визначити: -- хто може звертатися до вашого бота +- хто може спілкуватися з вашим ботом - де боту дозволено діяти -- чого бот може торкатися +- до чого бот може отримувати доступ -Починайте з найменшого доступу, який усе ще працює, а потім розширюйте його в міру зростання впевненості. +Починайте з мінімального доступу, який ще дозволяє працювати, і поступово розширюйте його в міру зростання впевненості. ### Розгортання та довіра до хоста -OpenClaw виходить із того, що межа хоста та конфігурації є довіреною: +OpenClaw припускає, що хост і межа конфігурації є довіреними: -- Якщо хтось може змінювати state/config хоста Gateway (`~/.openclaw`, включно з `openclaw.json`), вважайте цю людину довіреним оператором. -- Запуск одного Gateway для кількох взаємно недовірених/змагальних операторів **не є рекомендованою конфігурацією**. -- Для команд зі змішаним рівнем довіри розділяйте межі довіри окремими Gateway (або щонайменше окремими користувачами ОС/хостами). -- Рекомендована типова схема: один користувач на машину/хост (або VPS), один Gateway для цього користувача та один або кілька agent у межах цього Gateway. -- Усередині одного екземпляра Gateway доступ автентифікованого оператора — це довірена роль control plane, а не роль орендаря на рівні окремого користувача. -- Ідентифікатори сесій (`sessionKey`, session IDs, labels) — це селектори маршрутизації, а не токени авторизації. -- Якщо кілька людей можуть надсилати повідомлення одному agent з увімкненими інструментами, кожен із них може керувати тим самим набором дозволів. Ізоляція сесій/пам’яті на рівні окремого користувача допомагає приватності, але не перетворює спільний agent на авторизацію хоста для окремих користувачів. +- Якщо хтось може змінювати стан/конфігурацію хоста Gateway (`~/.openclaw`, зокрема `openclaw.json`), вважайте цю людину довіреним оператором. +- Запуск одного Gateway для кількох взаємно недовірених/зловмисних операторів **не є рекомендованою конфігурацією**. +- Для команд зі змішаним рівнем довіри розділяйте межі довіри за допомогою окремих gateway (або щонайменше окремих користувачів ОС/хостів). +- Рекомендована базова модель: один користувач на машину/хост (або VPS), один gateway для цього користувача та один або більше агентів у цьому gateway. +- Усередині одного екземпляра Gateway автентифікований доступ оператора є довіреною роллю control plane, а не роллю окремого користувача-орендаря. +- Ідентифікатори сесій (`sessionKey`, ID сесій, мітки) — це селектори маршрутизації, а не токени авторизації. +- Якщо кілька людей можуть надсилати повідомлення одному агенту з увімкненими інструментами, кожен із них може керувати тим самим набором дозволів. Ізоляція сесій/пам’яті на рівні користувача покращує приватність, але не перетворює спільного агента на авторизацію хоста на рівні окремого користувача. ### Спільний робочий простір Slack: реальний ризик -Якщо «кожен у Slack може написати боту», ключовий ризик — це делеговані повноваження щодо інструментів: +Якщо «будь-хто у Slack може написати боту», основний ризик — це делеговані повноваження інструментів: -- будь-який дозволений відправник може ініціювати виклики інструментів (`exec`, browser, мережеві/файлові інструменти) у межах політики agent; -- ін’єкція prompt/контенту від одного відправника може спричинити дії, що впливають на спільний state, пристрої або результати; -- якщо один спільний agent має доступ до чутливих облікових даних/файлів, будь-який дозволений відправник потенційно може спрямувати їх ексфільтрацію через використання інструментів. +- будь-який дозволений відправник може ініціювати виклики інструментів (`exec`, браузер, мережеві/файлові інструменти) в межах політики агента; +- ін’єкція prompt/content від одного відправника може спричинити дії, що впливають на спільний стан, пристрої або результати; +- якщо один спільний агент має доступ до чутливих облікових даних/файлів, будь-який дозволений відправник потенційно може ініціювати витік через використання інструментів. -Для командних сценаріїв використовуйте окремі agent/Gateway з мінімальним набором інструментів; agent, що працюють з персональними даними, тримайте приватними. +Для командних сценаріїв використовуйте окремих агентів/gateway з мінімальним набором інструментів; агентів із персональними даними тримайте приватними. -### Спільний корпоративний agent: прийнятний шаблон +### Спільний агент компанії: прийнятний шаблон -Це прийнятно, коли всі, хто користується цим agent, перебувають у тій самій межі довіри (наприклад, одна команда в компанії), а agent суворо обмежений бізнес-контекстом. +Це прийнятно, коли всі, хто використовує цього агента, перебувають у межах однієї довіреної області (наприклад, одна команда в компанії), а агент суворо обмежений бізнес-сценаріями. -- запускайте його на окремій машині/VM/container; -- використовуйте окремого користувача ОС + окремий browser/profile/accounts для цього runtime; -- не входьте в цьому runtime у персональні облікові записи Apple/Google або персональні профілі password manager/browser. +- запускайте його на виділеній машині/VM/container; +- використовуйте виділеного користувача ОС + окремий браузер/профіль/акаунти для цього середовища виконання; +- не входьте в цьому середовищі у персональні акаунти Apple/Google або особисті профілі менеджера паролів/браузера. -Якщо ви змішуєте персональні та корпоративні ідентичності в одному runtime, ви руйнуєте розділення та збільшуєте ризик витоку персональних даних. +Якщо ви змішуєте персональні та корпоративні ідентичності в одному середовищі виконання, ви руйнуєте це розділення та підвищуєте ризик розкриття персональних даних. -## Концепція довіри до Gateway і Node +## Концепція довіри до Gateway і node -Сприймайте Gateway і Node як одну операторську доменну область довіри з різними ролями: +Розглядайте Gateway і node як одну операторську область довіри з різними ролями: - **Gateway** — це control plane і поверхня політик (`gateway.auth`, політика інструментів, маршрутизація). -- **Node** — це поверхня віддаленого виконання, спарена з цим Gateway (команди, дії з пристроєм, локальні для хоста можливості). -- Клієнт, автентифікований у Gateway, є довіреним у межах Gateway. Після спарювання дії Node є діями довіреного оператора на цьому Node. -- `sessionKey` — це вибір маршруту/контексту, а не auth окремого користувача. -- Схвалення exec (allowlist + ask) — це запобіжники для наміру оператора, а не ізоляція від ворожого багатокористувацького використання. -- Типова модель OpenClaw для довірених сценаріїв з одним оператором полягає в тому, що host exec на `gateway`/`node` дозволено без запитів на схвалення (`security="full"`, `ask="off"`, якщо ви не посилите налаштування). Ця типова поведінка — свідоме UX-рішення, а не вразливість сама по собі. -- Схвалення exec прив’язуються до точного контексту запиту та best-effort прямих локальних файлових операндів; вони не моделюють семантично всі шляхи завантаження runtime/interpreter. Для сильних меж використовуйте sandboxing та ізоляцію хоста. +- **Node** — це поверхня віддаленого виконання, поєднана з цим Gateway (команди, дії на пристрої, локальні можливості хоста). +- Користувач, автентифікований у Gateway, вважається довіреним у межах Gateway. Після pairing дії node вважаються діями довіреного оператора на цій node. +- `sessionKey` — це вибір маршрутизації/контексту, а не автентифікація на рівні окремого користувача. +- Підтвердження exec (allowlist + ask) — це запобіжники для намірів оператора, а не ізоляція від ворожих багатокористувацьких сценаріїв. +- Типова продуктова конфігурація OpenClaw для довірених сценаріїв з одним оператором полягає в тому, що host exec на `gateway`/`node` дозволений без запитів на підтвердження (`security="full"`, `ask="off"`, якщо ви це не посилюєте). Цей стандартний режим є навмисним UX-рішенням, а не вразливістю сам по собі. +- Підтвердження exec прив’язуються до точного контексту запиту та до best-effort прямих локальних файлових операндів; вони не моделюють семантично всі шляхи завантаження середовища виконання/інтерпретатора. Для сильних меж використовуйте sandboxing та ізоляцію хоста. -Якщо вам потрібна ізоляція від ворожих користувачів, розділіть межі довіри за користувачами ОС/хостами та запускайте окремі Gateway. +Якщо вам потрібна ізоляція від ворожих користувачів, розділяйте межі довіри за користувачами ОС/хостами й запускайте окремі gateway. ## Матриця меж довіри Використовуйте це як швидку модель під час оцінки ризику: -| Межа або контроль | Що це означає | Типове хибне тлумачення | -| -------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------- | -| `gateway.auth` (token/password/trusted-proxy/device auth) | Автентифікує клієнтів для API Gateway | «Щоб бути безпечним, потрібні підписи для кожного повідомлення в кожному кадрі» | -| `sessionKey` | Ключ маршрутизації для вибору контексту/сесії | «Ключ сесії є межею auth користувача» | -| Запобіжники prompt/контенту | Зменшують ризик зловживання моделлю | «Сама лише prompt-ін’єкція вже доводить обхід auth» | -| `canvas.eval` / browser evaluate | Навмисна операторська можливість, якщо ввімкнена | «Будь-який примітив JS eval автоматично є вразливістю в цій моделі довіри» | -| Локальна оболонка TUI `!` | Явне локальне виконання, ініційоване оператором | «Зручна локальна shell-команда — це віддалена ін’єкція» | -| Pairing Node і команди Node | Віддалене виконання на рівні оператора на спарених пристроях | «Керування віддаленим пристроєм за замовчуванням слід вважати доступом недовіреного користувача» | +| Межа або контроль | Що це означає | Типове хибне тлумачення | +| -------------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------- | +| `gateway.auth` (token/password/trusted-proxy/device auth) | Автентифікує викликачів до API gateway | «Щоб бути безпечним, потрібні підписи для кожного повідомлення в кожному кадрі» | +| `sessionKey` | Ключ маршрутизації для вибору контексту/сесії | «Ключ сесії є межею автентифікації користувача» | +| Запобіжники prompt/content | Зменшують ризик зловживання моделлю | «Сама лише prompt injection доводить обхід автентифікації» | +| `canvas.eval` / browser evaluate | Навмисна операторська можливість, коли ввімкнена | «Будь-який примітив JS eval автоматично є вразливістю в цій моделі довіри» | +| Локальна оболонка TUI `!` | Явний локальний запуск, ініційований оператором | «Зручна локальна shell-команда є віддаленою ін’єкцією» | +| Pairing node і команди node | Віддалене виконання на рівні оператора на поєднаних пристроях | «Керування віддаленим пристроєм слід типово вважати доступом недовіреного користувача» | ## Не є вразливостями за задумом -Ці шаблони часто потрапляють у звіти й зазвичай закриваються без дій, якщо не показано реальний обхід межі: +Про ці шаблони часто повідомляють, але зазвичай їх закривають без дій, якщо не показано реальний обхід межі: -- Ланцюжки лише з prompt-ін’єкцією без обходу політик/auth/sandbox. -- Твердження, що спираються на припущення про ворожу багатокористувацьку роботу на одному спільному хості/config. -- Заяви, які трактують звичайний операторський доступ для читання (наприклад `sessions.list`/`sessions.preview`/`chat.history`) як IDOR у конфігурації зі спільним Gateway. -- Висновки для розгортань лише на localhost (наприклад HSTS на Gateway, доступному тільки через loopback). -- Знахідки про підписи вхідних Webhook Discord для вхідних шляхів, яких у цьому репозиторії не існує. -- Звіти, які трактують metadata pairing Node як прихований другий рівень схвалення для кожної команди `system.run`, коли реальною межею виконання все ще є глобальна політика команд Node на рівні gateway плюс власні схвалення exec на Node. -- Знахідки про «відсутню авторизацію на рівні окремого користувача», які трактують `sessionKey` як auth-token. +- Ланцюжки, що ґрунтуються лише на prompt injection, без обходу політики/автентифікації/sandbox. +- Твердження, що виходять із припущення про ворожу багатокористувацьку роботу на одному спільному хості/конфігурації. +- Повідомлення, які класифікують звичайний операторський доступ на читання (наприклад, `sessions.list`/`sessions.preview`/`chat.history`) як IDOR у конфігурації зі спільним gateway. +- Знахідки для розгортань лише на localhost (наприклад, HSTS для gateway, доступного лише через loopback). +- Повідомлення про підпис inbound webhook Discord для вхідних шляхів, яких у цьому репозиторії не існує. +- Повідомлення, які трактують метадані pairing node як прихований другий шар підтвердження для кожної команди `system.run`, хоча реальною межею виконання лишається глобальна політика команд node у gateway плюс власні підтвердження exec на node. +- Знахідки про «відсутню авторизацію на рівні користувача», які трактують `sessionKey` як токен автентифікації. ## Контрольний список для дослідника перед поданням -Перш ніж відкривати GHSA, перевірте все з наведеного нижче: +Перш ніж відкривати GHSA, перевірте все нижченаведене: -1. Відтворення все ще працює на останньому `main` або в останньому релізі. -2. Звіт містить точний шлях у коді (`file`, function, line range) і перевірену версію/commit. -3. Вплив перетинає задокументовану межу довіри, а не зводиться лише до prompt-ін’єкції. +1. Відтворення все ще працює на останньому `main` або останньому релізі. +2. Звіт містить точний шлях у коді (`file`, функція, діапазон рядків) і перевірену версію/коміт. +3. Вплив перетинає задокументовану межу довіри (а не лише prompt injection). 4. Твердження не входить до [Out of Scope](https://github.com/openclaw/openclaw/blob/main/SECURITY.md#out-of-scope). -5. Існуючі advisories перевірено на дублікати (використовуйте канонічний GHSA, якщо застосовно). -6. Припущення щодо розгортання явно зазначені (loopback/local чи зовнішнє відкриття, довірені чи недовірені оператори). +5. Існуючі advisory уже перевірено на дублікати (повторно використовуйте канонічний GHSA, якщо застосовно). +6. Припущення щодо розгортання явно вказані (loopback/local чи відкритий доступ, довірені чи недовірені оператори). -## Посилений базовий захист за 60 секунд +## Посилена базова конфігурація за 60 секунд -Спочатку використовуйте цей базовий профіль, а потім вибірково знову вмикайте інструменти для довірених agent: +Спочатку використайте цю базову конфігурацію, а потім вибірково знову вмикайте інструменти для довірених агентів: ```json5 { @@ -167,209 +167,214 @@ OpenClaw виходить із того, що межа хоста та конф } ``` -Це залишає Gateway доступним лише локально, ізолює DM і за замовчуванням вимикає інструменти control plane/runtime. +Це зберігає Gateway доступним лише локально, ізолює DM і типово вимикає інструменти control plane/runtime. -## Швидке правило для спільної скриньки +## Швидке правило для спільної вхідної скриньки -Якщо більше ніж одна людина може писати вашому боту в DM: +Якщо більше ніж одна людина може надсилати DM вашому боту: -- Установіть `session.dmScope: "per-channel-peer"` (або `"per-account-channel-peer"` для channel з кількома обліковими записами). +- Установіть `session.dmScope: "per-channel-peer"` (або `"per-account-channel-peer"` для каналів із кількома акаунтами). - Залишайте `dmPolicy: "pairing"` або суворі allowlist. - Ніколи не поєднуйте спільні DM із широким доступом до інструментів. -- Це посилює захист для кооперативних/спільних inbox, але не призначене як ізоляція ворожих співорендарів, коли користувачі мають спільний доступ на запис до host/config. +- Це посилює кооперативні/спільні вхідні скриньки, але не призначене для ізоляції ворожих співорендарів, коли користувачі мають спільний доступ на запис до хоста/конфігурації. ## Модель видимості контексту OpenClaw розділяє два поняття: -- **Авторизація запуску**: хто може запускати agent (`dmPolicy`, `groupPolicy`, allowlist, вимоги до згадки). -- **Видимість контексту**: який додатковий контекст вбудовується у вхід моделі (тіло відповіді, процитований текст, історія треду, metadata пересилання). +- **Авторизація тригера**: хто може активувати агента (`dmPolicy`, `groupPolicy`, allowlist, вимоги до згадки). +- **Видимість контексту**: який додатковий контекст додається до вхідних даних моделі (тіло відповіді, цитований текст, історія гілки, метадані пересилання). -Allowlist керують запуском і авторизацією команд. Налаштування `contextVisibility` керує тим, як фільтрується додатковий контекст (процитовані відповіді, кореневі повідомлення треду, отримана історія): +Allowlists керують тригерами та авторизацією команд. Параметр `contextVisibility` визначає, як фільтрується додатковий контекст (цитовані відповіді, корені гілок, отримана історія): -- `contextVisibility: "all"` (типово) зберігає додатковий контекст у тому вигляді, в якому його отримано. +- `contextVisibility: "all"` (типово) зберігає додатковий контекст у тому вигляді, у якому його отримано. - `contextVisibility: "allowlist"` фільтрує додатковий контекст до відправників, дозволених активними перевірками allowlist. -- `contextVisibility: "allowlist_quote"` працює як `allowlist`, але все одно зберігає одну явну процитовану відповідь. +- `contextVisibility: "allowlist_quote"` працює як `allowlist`, але все ж зберігає одну явну цитовану відповідь. -Установлюйте `contextVisibility` на рівні channel або окремої room/conversation. Докладніше про налаштування див. у [Group Chats](/uk/channels/groups#context-visibility-and-allowlists). +Установлюйте `contextVisibility` для кожного каналу або для кожної кімнати/розмови. Див. [Групові чати](/uk/channels/groups#context-visibility-and-allowlists), щоб дізнатися подробиці налаштування. -Рекомендації для оцінки advisories: +Рекомендації для оцінки advisory: -- Твердження, які лише показують, що «модель може бачити процитований або історичний текст від відправників поза allowlist», є знахідками з посилення захисту, які вирішуються через `contextVisibility`, а не обходом меж auth чи sandbox самі по собі. -- Щоб мати вплив на безпеку, звіт усе одно має демонструвати обхід межі довіри (auth, policy, sandbox, approval або іншої задокументованої межі). +- Твердження, які лише показують, що «модель може бачити цитований або історичний текст від відправників, яких немає в allowlist», є знахідками щодо посилення безпеки, які можна виправити через `contextVisibility`, але самі по собі не є обходом межі автентифікації чи sandbox. +- Щоб мати наслідки для безпеки, звіти все одно мають демонструвати обхід межі довіри (автентифікації, політики, sandbox, підтвердження або іншої задокументованої межі). ## Що перевіряє аудит (на високому рівні) -- **Вхідний доступ** (політики DM, групові політики, allowlist): чи можуть сторонні користувачі запускати бота? -- **Радіус ураження інструментів** (підвищені інструменти + відкриті кімнати): чи може prompt-ін’єкція перетворитися на дії оболонки/файлів/мережі? -- **Дрейф схвалення exec** (`security=full`, `autoAllowSkills`, allowlist інтерпретаторів без `strictInlineEval`): чи запобіжники host-exec досі працюють так, як ви очікуєте? - - `security="full"` — це широке попередження про безпекову модель, а не доказ помилки. Це обрана типова поведінка для довірених конфігурацій персонального асистента; посилюйте її лише тоді, коли ваша модель загроз потребує схвалення або запобіжників allowlist. -- **Мережеве відкриття** (bind/auth Gateway, Tailscale Serve/Funnel, слабкі/короткі auth-token). -- **Відкриття керування браузером** (віддалені Node, relay-порти, віддалені кінцеві точки CDP). -- **Гігієна локального диска** (дозволи, symlink, includes конфігурації, шляхи «синхронізованих папок»). +- **Вхідний доступ** (політики DM, групові політики, allowlist): чи можуть сторонні люди активувати бота? +- **Радіус ураження інструментів** (розширені інструменти + відкриті кімнати): чи може prompt injection перетворитися на дії через shell/файли/мережу? +- **Дрейф підтверджень exec** (`security=full`, `autoAllowSkills`, allowlist інтерпретаторів без `strictInlineEval`): чи запобіжники для host-exec усе ще працюють так, як ви вважаєте? + - `security="full"` — це широке попередження про рівень безпеки, а не доказ помилки. Це вибраний типовий режим для довірених сценаріїв персонального помічника; посилюйте його лише тоді, коли ваша модель загроз потребує підтверджень або запобіжників allowlist. +- **Мережевий доступ** (bind/auth Gateway, Tailscale Serve/Funnel, слабкі/короткі токени автентифікації). +- **Доступ до керування браузером** (віддалені node, порти relay, віддалені кінцеві точки CDP). +- **Гігієна локального диска** (дозволи, symlink, include конфігурації, шляхи до «синхронізованих папок»). - **Plugins** (plugins завантажуються без явного allowlist). -- **Дрейф політик/помилки конфігурації** (налаштування sandbox docker задані, але режим sandbox вимкнено; неефективні шаблони `gateway.nodes.denyCommands`, бо зіставлення виконується лише за точною назвою команди (наприклад `system.run`) і не аналізує текст оболонки; небезпечні записи `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`) і не аналізує текст shell; небезпечні записи `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 також намагається виконати best-effort живу перевірку Gateway. ## Карта зберігання облікових даних -Використовуйте це під час аудиту доступу або вирішення, що саме резервувати: +Використовуйте це під час аудиту доступу або коли вирішуєте, що резервувати: - **WhatsApp**: `~/.openclaw/credentials/whatsapp//creds.json` - **Токен Telegram bot**: config/env або `channels.telegram.tokenFile` (лише звичайний файл; symlink відхиляються) - **Токен Discord bot**: config/env або SecretRef (провайдери env/file/exec) - **Токени Slack**: config/env (`channels.slack.*`) -- **Allowlist pairing**: - - `~/.openclaw/credentials/-allowFrom.json` (типовий обліковий запис) - - `~/.openclaw/credentials/--allowFrom.json` (нетипові облікові записи) -- **Профілі auth моделей**: `~/.openclaw/agents//agent/auth-profiles.json` -- **Вміст секретів у файлі (необов’язково)**: `~/.openclaw/secrets.json` -- **Застарілий імпорт OAuth**: `~/.openclaw/credentials/oauth.json` +- **Pairing allowlist**: + - `~/.openclaw/credentials/-allowFrom.json` (типовий акаунт) + - `~/.openclaw/credentials/--allowFrom.json` (нетипові акаунти) +- **Профілі автентифікації моделей**: `~/.openclaw/agents//agent/auth-profiles.json` +- **Payload секретів у файлі (необов’язково)**: `~/.openclaw/secrets.json` +- **Імпорт застарілого OAuth**: `~/.openclaw/credentials/oauth.json` ## Контрольний список аудиту безпеки -Коли аудит виводить результати, використовуйте такий порядок пріоритетів: +Коли аудит виводить знахідки, розглядайте їх у такому порядку пріоритету: -1. **Усе, що “open” + увімкнені інструменти**: спочатку закрийте DM/групи (pairing/allowlist), потім посильте політику інструментів/sandboxing. -2. **Публічне мережеве відкриття** (bind у LAN, Funnel, відсутній auth): виправляйте негайно. -3. **Віддалене відкриття керування браузером**: розглядайте це як операторський доступ (лише tailnet, pairing Node навмисно, уникайте публічного відкриття). -4. **Дозволи**: переконайтеся, що state/config/облікові дані/auth не доступні на читання групі чи всім. +1. **Усе, що є “open”, коли інструменти ввімкнені**: спочатку обмежте DM/групи (pairing/allowlist), потім посильте політику інструментів/sandboxing. +2. **Публічний мережевий доступ** (bind на LAN, Funnel, відсутня автентифікація): виправляйте негайно. +3. **Віддалений доступ до керування браузером**: вважайте його операторським доступом (лише tailnet, pairing node навмисно, уникайте публічного доступу). +4. **Дозволи**: переконайтеся, що state/config/credentials/auth не доступні для читання групі чи всім. 5. **Plugins**: завантажуйте лише те, чому явно довіряєте. -6. **Вибір моделі**: для будь-якого бота з інструментами віддавайте перевагу сучасним, посиленим щодо інструкцій моделям. +6. **Вибір моделі**: для будь-якого бота з інструментами віддавайте перевагу сучасним, стійким до інструкцій моделям. ## Глосарій аудиту безпеки -Значення `checkId` з високим сигналом, які ви найімовірніше побачите в реальних розгортаннях (не вичерпний список): +Значення `checkId` з високим сигналом, які ви найімовірніше побачите в реальних розгортаннях (не вичерпний перелік): -| `checkId` | Серйозність | Чому це важливо | Основний ключ/шлях для виправлення | Автовиправлення | -| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | --------------- | -| `fs.state_dir.perms_world_writable` | критична | Інші користувачі/процеси можуть змінювати весь стан OpenClaw | дозволи файлової системи для `~/.openclaw` | так | -| `fs.state_dir.perms_group_writable` | попередження | Користувачі групи можуть змінювати весь стан OpenClaw | дозволи файлової системи для `~/.openclaw` | так | -| `fs.state_dir.perms_readable` | попередження | Каталог стану доступний для читання іншим | дозволи файлової системи для `~/.openclaw` | так | -| `fs.state_dir.symlink` | попередження | Цільовий каталог стану стає іншою межею довіри | структура файлової системи каталогу стану | ні | -| `fs.config.perms_writable` | критична | Інші можуть змінювати auth/політику інструментів/config | дозволи файлової системи для `~/.openclaw/openclaw.json` | так | -| `fs.config.symlink` | попередження | Ціль config стає іншою межею довіри | структура файлової системи файлу config | ні | -| `fs.config.perms_group_readable` | попередження | Користувачі групи можуть читати токени/налаштування config | дозволи файлової системи для файлу config | так | -| `fs.config.perms_world_readable` | критична | Config може розкривати токени/налаштування | дозволи файлової системи для файлу config | так | -| `fs.config_include.perms_writable` | критична | Файл include config може змінюватися іншими | дозволи на include-файл, на який посилається `openclaw.json` | так | -| `fs.config_include.perms_group_readable` | попередження | Користувачі групи можуть читати включені секрети/налаштування | дозволи на include-файл, на який посилається `openclaw.json` | так | -| `fs.config_include.perms_world_readable` | критична | Включені секрети/налаштування доступні для читання всім | дозволи на include-файл, на який посилається `openclaw.json` | так | -| `fs.auth_profiles.perms_writable` | критична | Інші можуть підмінити або замінити збережені облікові дані моделі | дозволи для `agents//agent/auth-profiles.json` | так | -| `fs.auth_profiles.perms_readable` | попередження | Інші можуть читати API-ключі та OAuth-токени | дозволи для `agents//agent/auth-profiles.json` | так | -| `fs.credentials_dir.perms_writable` | критична | Інші можуть змінювати стан pairing/облікових даних channel | дозволи файлової системи для `~/.openclaw/credentials` | так | -| `fs.credentials_dir.perms_readable` | попередження | Інші можуть читати стан облікових даних channel | дозволи файлової системи для `~/.openclaw/credentials` | так | -| `fs.sessions_store.perms_readable` | попередження | Інші можуть читати транскрипти/metadata сесій | дозволи для сховища сесій | так | -| `fs.log_file.perms_readable` | попередження | Інші можуть читати журнали, у яких дані хоч і редаговані, але все ще чутливі | дозволи для файлу журналу Gateway | так | -| `fs.synced_dir` | попередження | State/config в iCloud/Dropbox/Drive розширює ризик розкриття токенів/транскриптів | перемістіть config/state за межі синхронізованих папок | ні | -| `gateway.bind_no_auth` | критична | Віддалений bind без спільного секрету | `gateway.bind`, `gateway.auth.*` | ні | -| `gateway.loopback_no_auth` | критична | Loopback за reverse proxy може стати неавтентифікованим | `gateway.auth.*`, налаштування proxy | ні | -| `gateway.trusted_proxies_missing` | попередження | Заголовки reverse proxy присутні, але proxy не довірені | `gateway.trustedProxies` | ні | -| `gateway.http.no_auth` | попередження/критична | HTTP API Gateway доступні з `auth.mode="none"` | `gateway.auth.mode`, `gateway.http.endpoints.*` | ні | -| `gateway.http.session_key_override_enabled` | інформація | Клієнти HTTP API можуть перевизначати `sessionKey` | `gateway.http.allowSessionKeyOverride` | ні | -| `gateway.tools_invoke_http.dangerous_allow` | попередження/критична | Знову вмикає небезпечні інструменти через HTTP API | `gateway.tools.allow` | ні | -| `gateway.nodes.allow_commands_dangerous` | попередження/критична | Увімкнено високоризикові команди Node (camera/screen/contacts/calendar/SMS) | `gateway.nodes.allowCommands` | ні | -| `gateway.nodes.deny_commands_ineffective` | попередження | Записи deny, схожі на шаблони, не зіставляються з текстом оболонки або групами | `gateway.nodes.denyCommands` | ні | -| `gateway.tailscale_funnel` | критична | Публічне відкриття в інтернет | `gateway.tailscale.mode` | ні | -| `gateway.tailscale_serve` | інформація | Увімкнено доступ через tailnet через Serve | `gateway.tailscale.mode` | ні | -| `gateway.control_ui.allowed_origins_required` | критична | Control UI поза loopback без явного allowlist browser-origin | `gateway.controlUi.allowedOrigins` | ні | -| `gateway.control_ui.allowed_origins_wildcard` | попередження/критична | `allowedOrigins=["*"]` вимикає allowlist browser-origin | `gateway.controlUi.allowedOrigins` | ні | -| `gateway.control_ui.host_header_origin_fallback` | попередження/критична | Увімкнено fallback origin через Host header (послаблення захисту від DNS rebinding) | `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` | ні | -| `gateway.control_ui.insecure_auth` | попередження | Увімкнено режим сумісності з небезпечним auth | `gateway.controlUi.allowInsecureAuth` | ні | -| `gateway.control_ui.device_auth_disabled` | критична | Вимкнено перевірку ідентичності пристрою | `gateway.controlUi.dangerouslyDisableDeviceAuth` | ні | -| `gateway.real_ip_fallback_enabled` | попередження/критична | Довіра до fallback `X-Real-IP` може дозволити підміну source IP через помилку proxy | `gateway.allowRealIpFallback`, `gateway.trustedProxies` | ні | -| `gateway.token_too_short` | попередження | Короткий спільний токен легше підібрати перебором | `gateway.auth.token` | ні | -| `gateway.auth_no_rate_limit` | попередження | Відкритий auth без rate limiting підвищує ризик brute-force | `gateway.auth.rateLimit` | ні | -| `gateway.trusted_proxy_auth` | критична | Ідентичність proxy тепер стає межею auth | `gateway.auth.mode="trusted-proxy"` | ні | -| `gateway.trusted_proxy_no_proxies` | критична | Trusted-proxy auth без IP довірених proxy є небезпечним | `gateway.trustedProxies` | ні | -| `gateway.trusted_proxy_no_user_header` | критична | Trusted-proxy auth не може безпечно визначити ідентичність користувача | `gateway.auth.trustedProxy.userHeader` | ні | -| `gateway.trusted_proxy_no_allowlist` | попередження | Trusted-proxy auth приймає будь-якого автентифікованого користувача upstream | `gateway.auth.trustedProxy.allowUsers` | ні | -| `checkId` | Серйозність | Чому це важливо | Основний ключ/шлях для виправлення | Автовиправлення | -| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | --------------- | -| `gateway.probe_auth_secretref_unavailable` | попередження | Глибока перевірка не змогла визначити auth SecretRef у цьому шляху команди | джерело auth для deep-probe / доступність SecretRef | ні | -| `gateway.probe_failed` | попередження/критична | Жива перевірка Gateway завершилася невдачею | доступність/автентифікація gateway | ні | -| `discovery.mdns_full_mode` | попередження/критична | Повний режим mDNS рекламує metadata `cliPath`/`sshPort` у локальній мережі | `discovery.mdns.mode`, `gateway.bind` | ні | -| `config.insecure_or_dangerous_flags` | попередження | Увімкнено будь-які небезпечні або ризиковані прапорці налагодження | кілька ключів (див. деталі результату) | ні | -| `config.secrets.gateway_password_in_config` | попередження | Пароль Gateway зберігається безпосередньо в config | `gateway.auth.password` | ні | -| `config.secrets.hooks_token_in_config` | попередження | Bearer-токен hooks зберігається безпосередньо в config | `hooks.token` | ні | -| `hooks.token_reuse_gateway_token` | критична | Токен входу hooks також відкриває auth Gateway | `hooks.token`, `gateway.auth.token` | ні | -| `hooks.token_too_short` | попередження | Легший brute force для входу hooks | `hooks.token` | ні | -| `hooks.default_session_key_unset` | попередження | Agent hooks розподіляє запуски по згенерованих сесіях для кожного запиту | `hooks.defaultSessionKey` | ні | -| `hooks.allowed_agent_ids_unrestricted` | попередження/критична | Автентифіковані викликачі hooks можуть маршрутизувати до будь-якого налаштованого agent | `hooks.allowedAgentIds` | ні | -| `hooks.request_session_key_enabled` | попередження/критична | Зовнішній викликач може вибирати `sessionKey` | `hooks.allowRequestSessionKey` | ні | -| `hooks.request_session_key_prefixes_missing` | попередження/критична | Немає обмеження на форму зовнішніх ключів сесій | `hooks.allowedSessionKeyPrefixes` | ні | -| `hooks.path_root` | критична | Шлях hooks дорівнює `/`, що полегшує колізії або помилкову маршрутизацію входу | `hooks.path` | ні | -| `hooks.installs_unpinned_npm_specs` | попередження | Записи встановлення hooks не прив’язані до незмінних специфікацій npm | metadata встановлення hooks | ні | -| `hooks.installs_missing_integrity` | попередження | У записах встановлення hooks відсутні metadata цілісності | metadata встановлення hooks | ні | -| `hooks.installs_version_drift` | попередження | Записи встановлення hooks відхиляються від установлених пакетів | metadata встановлення hooks | ні | -| `logging.redact_off` | попередження | Чутливі значення потрапляють у журнали/status | `logging.redactSensitive` | так | -| `browser.control_invalid_config` | попередження | Config керування browser є невалідним ще до runtime | `browser.*` | ні | -| `browser.control_no_auth` | критична | Керування browser відкрито без auth через token/password | `gateway.auth.*` | ні | -| `browser.remote_cdp_http` | попередження | Віддалений CDP через звичайний HTTP не має шифрування транспорту | профіль browser `cdpUrl` | ні | -| `browser.remote_cdp_private_host` | попередження | Віддалений CDP націлений на приватний/внутрішній хост | профіль browser `cdpUrl`, `browser.ssrfPolicy.*` | ні | -| `sandbox.docker_config_mode_off` | попередження | Config Docker для sandbox присутній, але неактивний | `agents.*.sandbox.mode` | ні | -| `sandbox.bind_mount_non_absolute` | попередження | Відносні bind mount можуть визначатися непередбачувано | `agents.*.sandbox.docker.binds[]` | ні | -| `sandbox.dangerous_bind_mount` | критична | Bind mount sandbox націлено на заблоковані системні шляхи, облікові дані або шляхи Docker socket | `agents.*.sandbox.docker.binds[]` | ні | -| `sandbox.dangerous_network_mode` | критична | Docker network для sandbox використовує `host` або режим приєднання до простору назв `container:*` | `agents.*.sandbox.docker.network` | ні | -| `sandbox.dangerous_seccomp_profile` | критична | Профіль seccomp для sandbox послаблює ізоляцію container | `agents.*.sandbox.docker.securityOpt` | ні | -| `sandbox.dangerous_apparmor_profile` | критична | Профіль AppArmor для sandbox послаблює ізоляцію container | `agents.*.sandbox.docker.securityOpt` | ні | -| `sandbox.browser_cdp_bridge_unrestricted` | попередження | Міст CDP browser у sandbox відкрито без обмеження діапазону джерел | `sandbox.browser.cdpSourceRange` | ні | -| `sandbox.browser_container.non_loopback_publish` | критична | Наявний container browser публікує CDP на інтерфейсах поза loopback | config публікації container browser для sandbox | ні | -| `sandbox.browser_container.hash_label_missing` | попередження | Наявний container browser передує поточним міткам хешу config | `openclaw sandbox recreate --browser --all` | ні | -| `sandbox.browser_container.hash_epoch_stale` | попередження | Наявний container browser передує поточній епосі config browser | `openclaw sandbox recreate --browser --all` | ні | -| `tools.exec.host_sandbox_no_sandbox_defaults` | попередження | `exec host=sandbox` безпечно відмовляє, якщо sandbox вимкнено | `tools.exec.host`, `agents.defaults.sandbox.mode` | ні | -| `tools.exec.host_sandbox_no_sandbox_agents` | попередження | `exec host=sandbox` для окремого agent безпечно відмовляє, якщо sandbox вимкнено | `agents.list[].tools.exec.host`, `agents.list[].sandbox.mode` | ні | -| `tools.exec.security_full_configured` | попередження/критична | Host exec працює з `security="full"` | `tools.exec.security`, `agents.list[].tools.exec.security` | ні | -| `tools.exec.auto_allow_skills_enabled` | попередження | Схвалення exec неявно довіряють bin з Skills | `~/.openclaw/exec-approvals.json` | ні | -| `tools.exec.allowlist_interpreter_without_strict_inline_eval` | попередження | Allowlist інтерпретаторів дозволяють inline eval без примусового повторного схвалення | `tools.exec.strictInlineEval`, `agents.list[].tools.exec.strictInlineEval`, allowlist схвалень exec | ні | -| `tools.exec.safe_bins_interpreter_unprofiled` | попередження | Bin інтерпретаторів/runtime у `safeBins` без явних профілів розширюють ризик exec | `tools.exec.safeBins`, `tools.exec.safeBinProfiles`, `agents.list[].tools.exec.*` | ні | -| `tools.exec.safe_bins_broad_behavior` | попередження | Інструменти широкої поведінки в `safeBins` послаблюють модель довіри низького ризику для фільтра stdin | `tools.exec.safeBins`, `agents.list[].tools.exec.safeBins` | ні | -| `tools.exec.safe_bin_trusted_dirs_risky` | попередження | `safeBinTrustedDirs` містить змінювані або ризиковані каталоги | `tools.exec.safeBinTrustedDirs`, `agents.list[].tools.exec.safeBinTrustedDirs` | ні | -| `skills.workspace.symlink_escape` | попередження | `skills/**/SKILL.md` у workspace визначається за межами кореня workspace (дрейф ланцюжка symlink) | стан файлової системи `skills/**` у workspace | ні | -| `plugins.extensions_no_allowlist` | попередження | Plugins встановлені без явного allowlist plugins | `plugins.allowlist` | ні | -| `plugins.installs_unpinned_npm_specs` | попередження | Записи встановлення Plugin не прив’язані до незмінних специфікацій npm | metadata встановлення Plugin | ні | -| `checkId` | Серйозність | Чому це важливо | Основний ключ/шлях для виправлення | Автовиправлення | -| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | --------------- | -| `plugins.installs_missing_integrity` | попередження | У записах встановлення Plugin відсутні metadata цілісності | metadata встановлення Plugin | ні | -| `plugins.installs_version_drift` | попередження | Записи встановлення Plugin відхиляються від установлених пакетів | metadata встановлення Plugin | ні | -| `plugins.code_safety` | попередження/критична | Сканування коду Plugin виявило підозрілі або небезпечні шаблони | код Plugin / джерело встановлення | ні | -| `plugins.code_safety.entry_path` | попередження | Шлях входу Plugin вказує на приховані розташування або `node_modules` | `entry` у маніфесті Plugin | ні | -| `plugins.code_safety.entry_escape` | критична | Точка входу Plugin виходить за межі каталогу Plugin | `entry` у маніфесті Plugin | ні | -| `plugins.code_safety.scan_failed` | попередження | Сканування коду Plugin не вдалося завершити | шлях Plugin / середовище сканування | ні | -| `skills.code_safety` | попередження/критична | Metadata/код інсталятора Skill містить підозрілі або небезпечні шаблони | джерело встановлення Skill | ні | -| `skills.code_safety.scan_failed` | попередження | Сканування коду Skill не вдалося завершити | середовище сканування Skill | ні | -| `security.exposure.open_channels_with_exec` | попередження/критична | Спільні/публічні кімнати можуть звертатися до agent з увімкненим exec | `channels.*.dmPolicy`, `channels.*.groupPolicy`, `tools.exec.*`, `agents.list[].tools.exec.*` | ні | -| `security.exposure.open_groups_with_elevated` | критична | Відкриті групи + підвищені інструменти створюють високоризикові шляхи prompt-ін’єкції | `channels.*.groupPolicy`, `tools.elevated.*` | ні | -| `security.exposure.open_groups_with_runtime_or_fs` | критична/попередження | Відкриті групи можуть отримати доступ до командних/файлових інструментів без захисту sandbox/workspace | `channels.*.groupPolicy`, `tools.profile/deny`, `tools.fs.workspaceOnly`, `agents.*.sandbox.mode` | ні | -| `security.trust_model.multi_user_heuristic` | попередження | Config виглядає як багатокористувацька, тоді як модель довіри Gateway — персональний асистент | розділіть межі довіри або посильте захист для спільного користувача (`sandbox.mode`, deny інструментів / обмеження workspace) | ні | -| `tools.profile_minimal_overridden` | попередження | Перевизначення agent обходять глобальний профіль minimal | `agents.list[].tools.profile` | ні | -| `plugins.tools_reachable_permissive_policy` | попередження | Інструменти extensions доступні в надто ліберальних контекстах | `tools.profile` + allow/deny інструментів | ні | -| `models.legacy` | попередження | Досі налаштовано застарілі сімейства моделей | вибір моделі | ні | -| `models.weak_tier` | попередження | Налаштовані моделі нижчі за поточні рекомендовані рівні | вибір моделі | ні | -| `models.small_params` | критична/інформація | Малі моделі + небезпечні поверхні інструментів підвищують ризик ін’єкцій | вибір моделі + sandbox/політика інструментів | ні | -| `summary.attack_surface` | інформація | Зведений підсумок щодо auth, channel, інструментів і рівня відкриття | кілька ключів (див. деталі результату) | ні | +| `checkId` | Severity | Чому це важливо | Основний ключ/шлях для виправлення | Автовиправлення | +| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | --------------- | +| `fs.state_dir.perms_world_writable` | critical | Інші користувачі/процеси можуть змінювати весь стан OpenClaw | дозволи файлової системи для `~/.openclaw` | так | +| `fs.state_dir.perms_group_writable` | warn | Користувачі групи можуть змінювати весь стан OpenClaw | дозволи файлової системи для `~/.openclaw` | так | +| `fs.state_dir.perms_readable` | warn | Каталог стану доступний для читання іншим | дозволи файлової системи для `~/.openclaw` | так | +| `fs.state_dir.symlink` | warn | Цільовий каталог стану стає іншою межею довіри | структура файлової системи каталогу стану | ні | +| `fs.config.perms_writable` | critical | Інші можуть змінювати політику auth/tool/config | дозволи файлової системи для `~/.openclaw/openclaw.json` | так | +| `fs.config.symlink` | warn | Конфігураційні файли через symlink не підтримуються для запису й додають ще одну межу довіри | замініть на звичайний конфігураційний файл або вкажіть `OPENCLAW_CONFIG_PATH` на реальний файл | ні | +| `fs.config.perms_group_readable` | warn | Користувачі групи можуть читати токени/налаштування конфігурації | дозволи файлової системи для конфігураційного файлу | так | +| `fs.config.perms_world_readable` | critical | Конфігурація може розкривати токени/налаштування | дозволи файлової системи для конфігураційного файлу | так | +| `fs.config_include.perms_writable` | critical | Інші можуть змінювати include-файл конфігурації | дозволи include-файлу, на який посилається `openclaw.json` | так | +| `fs.config_include.perms_group_readable` | warn | Користувачі групи можуть читати включені секрети/налаштування | дозволи include-файлу, на який посилається `openclaw.json` | так | +| `fs.config_include.perms_world_readable` | critical | Включені секрети/налаштування доступні для читання всім | дозволи include-файлу, на який посилається `openclaw.json` | так | +| `fs.auth_profiles.perms_writable` | critical | Інші можуть впровадити або замінити збережені облікові дані моделі | дозволи для `agents//agent/auth-profiles.json` | так | +| `fs.auth_profiles.perms_readable` | warn | Інші можуть читати API-ключі та OAuth-токени | дозволи для `agents//agent/auth-profiles.json` | так | +| `fs.credentials_dir.perms_writable` | critical | Інші можуть змінювати стан pairing/облікових даних каналу | дозволи файлової системи для `~/.openclaw/credentials` | так | +| `fs.credentials_dir.perms_readable` | warn | Інші можуть читати стан облікових даних каналу | дозволи файлової системи для `~/.openclaw/credentials` | так | +| `fs.sessions_store.perms_readable` | warn | Інші можуть читати транскрипти/метадані сесій | дозволи сховища сесій | так | +| `fs.log_file.perms_readable` | warn | Інші можуть читати журнали, у яких дані редаговано, але які все ще містять чутливу інформацію | дозволи для файлу журналу gateway | так | +| `fs.synced_dir` | warn | Стан/конфігурація в iCloud/Dropbox/Drive розширюють поверхню розкриття токенів/транскриптів | перемістіть конфігурацію/стан із синхронізованих папок | ні | +| `gateway.bind_no_auth` | critical | Віддалений bind без спільного секрету | `gateway.bind`, `gateway.auth.*` | ні | +| `gateway.loopback_no_auth` | critical | Gateway на loopback за reverse proxy може стати неавтентифікованим | `gateway.auth.*`, налаштування proxy | ні | +| `gateway.trusted_proxies_missing` | warn | Заголовки reverse proxy присутні, але не позначені як trusted | `gateway.trustedProxies` | ні | +| `gateway.http.no_auth` | warn/critical | HTTP API Gateway доступні з `auth.mode="none"` | `gateway.auth.mode`, `gateway.http.endpoints.*` | ні | +| `gateway.http.session_key_override_enabled` | info | Викликачі HTTP API можуть перевизначати `sessionKey` | `gateway.http.allowSessionKeyOverride` | ні | +| `gateway.tools_invoke_http.dangerous_allow` | warn/critical | Повторно вмикає небезпечні інструменти через HTTP API | `gateway.tools.allow` | ні | +| `gateway.nodes.allow_commands_dangerous` | warn/critical | Вмикає команди node з високим впливом (camera/screen/contacts/calendar/SMS) | `gateway.nodes.allowCommands` | ні | +| `gateway.nodes.deny_commands_ineffective` | warn | Записи deny у стилі шаблонів не збігаються з текстом shell або групами | `gateway.nodes.denyCommands` | ні | +| `gateway.tailscale_funnel` | critical | Публічний доступ з інтернету | `gateway.tailscale.mode` | ні | +| `gateway.tailscale_serve` | info | Доступ у tailnet увімкнений через Serve | `gateway.tailscale.mode` | ні | +| `gateway.control_ui.allowed_origins_required` | critical | Для Control UI не на loopback немає явного allowlist походжень браузера | `gateway.controlUi.allowedOrigins` | ні | +| `gateway.control_ui.allowed_origins_wildcard` | warn/critical | `allowedOrigins=["*"]` вимикає allowlist походжень браузера | `gateway.controlUi.allowedOrigins` | ні | +| `gateway.control_ui.host_header_origin_fallback` | warn/critical | Вмикає fallback походження за заголовком Host (послаблення захисту від DNS rebinding) | `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` | ні | +| `gateway.control_ui.insecure_auth` | warn | Увімкнений перемикач сумісності insecure-auth | `gateway.controlUi.allowInsecureAuth` | ні | +| `gateway.control_ui.device_auth_disabled` | critical | Вимикає перевірку ідентичності пристрою | `gateway.controlUi.dangerouslyDisableDeviceAuth` | ні | +| `gateway.real_ip_fallback_enabled` | warn/critical | Довіра до fallback `X-Real-IP` може дозволити підміну source IP через неправильну конфігурацію proxy | `gateway.allowRealIpFallback`, `gateway.trustedProxies` | ні | +| `gateway.token_too_short` | warn | Короткий спільний токен легше підібрати перебором | `gateway.auth.token` | ні | +| `gateway.auth_no_rate_limit` | warn | Відкрита auth без rate limiting підвищує ризик brute-force | `gateway.auth.rateLimit` | ні | +| `gateway.trusted_proxy_auth` | critical | Ідентичність proxy тепер стає межею auth | `gateway.auth.mode="trusted-proxy"` | ні | +| `gateway.trusted_proxy_no_proxies` | critical | Auth через trusted-proxy без IP-адрес trusted proxy є небезпечною | `gateway.trustedProxies` | ні | +| `gateway.trusted_proxy_no_user_header` | critical | Auth через trusted-proxy не може безпечно визначити ідентичність користувача | `gateway.auth.trustedProxy.userHeader` | ні | +| `gateway.trusted_proxy_no_allowlist` | warn | Auth через trusted-proxy приймає будь-якого автентифікованого користувача upstream | `gateway.auth.trustedProxy.allowUsers` | ні | +| `gateway.probe_auth_secretref_unavailable` | warn | Глибока перевірка не змогла визначити auth SecretRef у цьому шляху команди | джерело auth для deep probe / доступність SecretRef | ні | +| `gateway.probe_failed` | warn/critical | Жива перевірка Gateway не вдалася | доступність/auth gateway | ні | +| `discovery.mdns_full_mode` | warn/critical | Повний режим mDNS рекламує метадані `cliPath`/`sshPort` у локальній мережі | `discovery.mdns.mode`, `gateway.bind` | ні | +| `config.insecure_or_dangerous_flags` | warn | Увімкнено будь-які небезпечні або незахищені debug-прапори | кілька ключів (див. деталі знахідки) | ні | +| `config.secrets.gateway_password_in_config` | warn | Пароль Gateway зберігається безпосередньо в конфігурації | `gateway.auth.password` | ні | +| `config.secrets.hooks_token_in_config` | warn | Bearer token hooks зберігається безпосередньо в конфігурації | `hooks.token` | ні | +| `hooks.token_reuse_gateway_token` | critical | Токен входу hooks також відкриває auth Gateway | `hooks.token`, `gateway.auth.token` | ні | +| `hooks.token_too_short` | warn | Полегшує brute force для входу hooks | `hooks.token` | ні | +| `hooks.default_session_key_unset` | warn | Агент hook запускає fan-out у згенеровані сесії для кожного запиту | `hooks.defaultSessionKey` | ні | +| `hooks.allowed_agent_ids_unrestricted` | warn/critical | Автентифіковані викликачі hooks можуть маршрутизувати до будь-якого налаштованого агента | `hooks.allowedAgentIds` | ні | +| `hooks.request_session_key_enabled` | warn/critical | Зовнішній викликач може вибирати `sessionKey` | `hooks.allowRequestSessionKey` | ні | +| `hooks.request_session_key_prefixes_missing` | warn/critical | Немає обмежень на форму зовнішніх ключів сесії | `hooks.allowedSessionKeyPrefixes` | ні | +| `hooks.path_root` | critical | Шлях hook дорівнює `/`, що полегшує колізії або помилкову маршрутизацію входу | `hooks.path` | ні | +| `hooks.installs_unpinned_npm_specs` | warn | Записи встановлення hooks не прив’язані до незмінних npm-специфікацій | метадані встановлення hook | ні | +| `hooks.installs_missing_integrity` | warn | У записах встановлення hooks бракує метаданих цілісності | метадані встановлення hook | ні | +| `hooks.installs_version_drift` | warn | Записи встановлення hooks відхилилися від установлених пакетів | метадані встановлення hook | ні | +| `logging.redact_off` | warn | Чутливі значення потрапляють у журнали/status | `logging.redactSensitive` | так | +| `browser.control_invalid_config` | warn | Конфігурація керування браузером недійсна ще до запуску | `browser.*` | ні | +| `browser.control_no_auth` | critical | Керування браузером доступне без auth через token/password | `gateway.auth.*` | ні | +| `browser.remote_cdp_http` | warn | Віддалений CDP через звичайний HTTP не має шифрування транспорту | профіль браузера `cdpUrl` | ні | +| `browser.remote_cdp_private_host` | warn | Віддалений CDP спрямовано на приватний/внутрішній хост | профіль браузера `cdpUrl`, `browser.ssrfPolicy.*` | ні | +| `sandbox.docker_config_mode_off` | warn | Конфігурація Docker для sandbox присутня, але неактивна | `agents.*.sandbox.mode` | ні | +| `sandbox.bind_mount_non_absolute` | warn | Відносні bind mount можуть визначатися непередбачувано | `agents.*.sandbox.docker.binds[]` | ні | +| `sandbox.dangerous_bind_mount` | critical | Цілі bind mount у sandbox вказують на заблоковані системні шляхи, облікові дані або шляхи сокета Docker | `agents.*.sandbox.docker.binds[]` | ні | +| `sandbox.dangerous_network_mode` | critical | Docker network для sandbox використовує режим `host` або `container:*` зі спільним простором імен | `agents.*.sandbox.docker.network` | ні | +| `sandbox.dangerous_seccomp_profile` | critical | Профіль seccomp у sandbox послаблює ізоляцію container | `agents.*.sandbox.docker.securityOpt` | ні | +| `sandbox.dangerous_apparmor_profile` | critical | Профіль AppArmor у sandbox послаблює ізоляцію container | `agents.*.sandbox.docker.securityOpt` | ні | +| `sandbox.browser_cdp_bridge_unrestricted` | warn | Міст CDP браузера в sandbox доступний без обмеження діапазону джерел | `sandbox.browser.cdpSourceRange` | ні | +| `sandbox.browser_container.non_loopback_publish` | critical | Наявний container браузера публікує CDP на інтерфейсах, відмінних від loopback | конфігурація публікації container браузера в sandbox | ні | +| `sandbox.browser_container.hash_label_missing` | warn | Наявний container браузера передує поточним міткам hash конфігурації | `openclaw sandbox recreate --browser --all` | ні | +| `sandbox.browser_container.hash_epoch_stale` | warn | Наявний container браузера передує поточній епосі конфігурації браузера | `openclaw sandbox recreate --browser --all` | ні | +| `tools.exec.host_sandbox_no_sandbox_defaults` | warn | `exec host=sandbox` безпечно завершується відмовою, коли sandbox вимкнено | `tools.exec.host`, `agents.defaults.sandbox.mode` | ні | +| `tools.exec.host_sandbox_no_sandbox_agents` | warn | `exec host=sandbox` для окремого агента безпечно завершується відмовою, коли sandbox вимкнено | `agents.list[].tools.exec.host`, `agents.list[].sandbox.mode` | ні | +| `tools.exec.security_full_configured` | warn/critical | Host exec працює з `security="full"` | `tools.exec.security`, `agents.list[].tools.exec.security` | ні | +| `tools.exec.auto_allow_skills_enabled` | warn | Підтвердження exec неявно довіряють bin із Skills | `~/.openclaw/exec-approvals.json` | ні | +| `tools.exec.allowlist_interpreter_without_strict_inline_eval` | warn | Allowlist інтерпретаторів дозволяють inline eval без примусового повторного підтвердження | `tools.exec.strictInlineEval`, `agents.list[].tools.exec.strictInlineEval`, allowlist підтверджень exec | ні | +| `tools.exec.safe_bins_interpreter_unprofiled` | warn | Bin інтерпретаторів/runtime у `safeBins` без явних профілів розширюють ризик exec | `tools.exec.safeBins`, `tools.exec.safeBinProfiles`, `agents.list[].tools.exec.*` | ні | +| `tools.exec.safe_bins_broad_behavior` | warn | Інструменти широкої дії в `safeBins` послаблюють модель довіри low-risk stdin-filter | `tools.exec.safeBins`, `agents.list[].tools.exec.safeBins` | ні | +| `tools.exec.safe_bin_trusted_dirs_risky` | warn | `safeBinTrustedDirs` містить змінювані або ризиковані каталоги | `tools.exec.safeBinTrustedDirs`, `agents.list[].tools.exec.safeBinTrustedDirs` | ні | +| `skills.workspace.symlink_escape` | warn | `skills/**/SKILL.md` у workspace визначається поза коренем workspace (дрейф ланцюга symlink) | стан файлової системи `skills/**` у workspace | ні | +| `plugins.extensions_no_allowlist` | warn | Plugins установлені без явного allowlist plugin | `plugins.allowlist` | ні | +| `plugins.installs_unpinned_npm_specs` | warn | Записи встановлення plugin не прив’язані до незмінних npm-специфікацій | метадані встановлення plugin | ні | +| `plugins.installs_missing_integrity` | warn | У записах встановлення Plugin бракує метаданих цілісності | метадані встановлення plugin | ні | +| `plugins.installs_version_drift` | warn | Записи встановлення Plugin відхилилися від установлених пакетів | метадані встановлення plugin | ні | +| `plugins.code_safety` | warn/critical | Сканування коду Plugin виявило підозрілі або небезпечні шаблони | код plugin / джерело встановлення | ні | +| `plugins.code_safety.entry_path` | warn | Шлях входу Plugin вказує на приховані розташування або `node_modules` | `entry` у маніфесті plugin | ні | +| `plugins.code_safety.entry_escape` | critical | Вхід Plugin виходить за межі каталогу plugin | `entry` у маніфесті plugin | ні | +| `plugins.code_safety.scan_failed` | warn | Сканування коду Plugin не вдалося завершити | шлях plugin / середовище сканування | ні | +| `skills.code_safety` | warn/critical | Метадані/код інсталятора Skills містять підозрілі або небезпечні шаблони | джерело встановлення skill | ні | +| `skills.code_safety.scan_failed` | warn | Сканування коду skill не вдалося завершити | середовище сканування skill | ні | +| `security.exposure.open_channels_with_exec` | warn/critical | Спільні/публічні кімнати можуть звертатися до агентів з увімкненим exec | `channels.*.dmPolicy`, `channels.*.groupPolicy`, `tools.exec.*`, `agents.list[].tools.exec.*` | ні | +| `security.exposure.open_groups_with_elevated` | critical | Відкриті групи + розширені інструменти створюють шляхи prompt injection з високим впливом | `channels.*.groupPolicy`, `tools.elevated.*` | ні | +| `security.exposure.open_groups_with_runtime_or_fs` | critical/warn | Відкриті групи можуть отримати доступ до командних/файлових інструментів без захисту sandbox/workspace | `channels.*.groupPolicy`, `tools.profile/deny`, `tools.fs.workspaceOnly`, `agents.*.sandbox.mode` | ні | +| `security.trust_model.multi_user_heuristic` | warn | Конфігурація виглядає багатокористувацькою, тоді як модель довіри gateway — це персональний помічник | розділіть межі довіри або застосуйте посилення для спільного використання (`sandbox.mode`, deny для інструментів/scoping workspace) | ні | +| `tools.profile_minimal_overridden` | warn | Перевизначення агента обходять глобальний профіль minimal | `agents.list[].tools.profile` | ні | +| `plugins.tools_reachable_permissive_policy` | warn | Інструменти extension доступні в надто поблажливих контекстах | `tools.profile` + allow/deny інструментів | ні | +| `models.legacy` | warn | Застарілі сімейства моделей усе ще налаштовані | вибір моделі | ні | +| `models.weak_tier` | warn | Налаштовані моделі нижчі за поточні рекомендовані рівні | вибір моделі | ні | +| `models.small_params` | critical/info | Малі моделі + небезпечні поверхні інструментів підвищують ризик injection | вибір моделі + політика sandbox/інструментів | ні | +| `summary.attack_surface` | info | Узагальнений підсумок щодо стану auth, каналів, інструментів і поверхні доступу | кілька ключів (див. деталі знахідки) | ні | ## Control UI через HTTP -Control UI потребує **безпечного контексту** (HTTPS або localhost), щоб генерувати ідентичність пристрою. `gateway.controlUi.allowInsecureAuth` — це локальний перемикач сумісності: +Для Control UI потрібен **безпечний контекст** (HTTPS або localhost), щоб генерувати +ідентичність пристрою. `gateway.controlUi.allowInsecureAuth` — це локальний перемикач сумісності: -- На localhost він дозволяє auth для Control UI без ідентичності пристрою, коли сторінку завантажено через незахищений HTTP. +- На localhost він дозволяє auth для Control UI без ідентичності пристрою, коли сторінка + завантажена через незахищений HTTP. - Він не обходить перевірки pairing. -- Він не послаблює вимоги до ідентичності пристрою для віддалених (не localhost) підключень. +- Він не послаблює вимоги до ідентичності пристрою для віддалених (не localhost) сценаріїв. Віддавайте перевагу HTTPS (Tailscale Serve) або відкривайте UI на `127.0.0.1`. -Лише для аварійних сценаріїв `gateway.controlUi.dangerouslyDisableDeviceAuth` повністю вимикає перевірки ідентичності пристрою. Це серйозне послаблення безпеки; тримайте цей параметр вимкненим, якщо тільки ви не займаєтеся активним налагодженням і можете швидко повернути зміни. +Лише для аварійних сценаріїв `gateway.controlUi.dangerouslyDisableDeviceAuth` +повністю вимикає перевірки ідентичності пристрою. Це серйозне послаблення безпеки; +тримайте цей параметр вимкненим, якщо тільки ви активно не налагоджуєте систему й не можете швидко все повернути назад. -Окремо від цих небезпечних прапорців, успішний `gateway.auth.mode: "trusted-proxy"` може допускати **операторські** сесії Control UI без ідентичності пристрою. Це навмисна поведінка режиму auth, а не обхід через `allowInsecureAuth`, і вона все одно не поширюється на сесії Control UI з роллю node. +Окремо від цих небезпечних прапорів, успішний режим `gateway.auth.mode: "trusted-proxy"` +може допускати **operator**-сесії Control UI без ідентичності пристрою. Це +навмисна поведінка режиму auth, а не скорочення через `allowInsecureAuth`, і вона все одно +не поширюється на Control UI-сесії ролі node. `openclaw security audit` попереджає, коли цей параметр увімкнено. -## Підсумок щодо небезпечних або ризикованих прапорців +## Підсумок щодо незахищених або небезпечних прапорів -`openclaw security audit` включає `config.insecure_or_dangerous_flags`, коли ввімкнено відомі небезпечні або ризиковані перемикачі налагодження. Наразі ця перевірка агрегує: +`openclaw security audit` включає `config.insecure_or_dangerous_flags`, коли +увімкнено відомі незахищені/небезпечні debug-перемикачі. Наразі ця перевірка +агрегує: - `gateway.controlUi.allowInsecureAuth=true` - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` @@ -379,7 +384,7 @@ Control UI потребує **безпечного контексту** (HTTPS - `tools.exec.applyPatch.workspaceOnly=false` - `plugins.entries.acpx.config.permissionMode=approve-all` -Повний перелік ключів config `dangerous*` / `dangerously*`, визначених у схемі config OpenClaw: +Повний перелік конфігураційних ключів `dangerous*` / `dangerously*`, визначених у схемі конфігурації OpenClaw: - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` - `gateway.controlUi.dangerouslyDisableDeviceAuth` @@ -391,15 +396,15 @@ Control UI потребує **безпечного контексту** (HTTPS - `channels.googlechat.dangerouslyAllowNameMatching` - `channels.googlechat.accounts..dangerouslyAllowNameMatching` - `channels.msteams.dangerouslyAllowNameMatching` -- `channels.synology-chat.dangerouslyAllowNameMatching` (Plugin channel) -- `channels.synology-chat.accounts..dangerouslyAllowNameMatching` (Plugin channel) -- `channels.synology-chat.dangerouslyAllowInheritedWebhookPath` (Plugin channel) -- `channels.zalouser.dangerouslyAllowNameMatching` (Plugin channel) -- `channels.zalouser.accounts..dangerouslyAllowNameMatching` (Plugin channel) -- `channels.irc.dangerouslyAllowNameMatching` (Plugin channel) -- `channels.irc.accounts..dangerouslyAllowNameMatching` (Plugin channel) -- `channels.mattermost.dangerouslyAllowNameMatching` (Plugin channel) -- `channels.mattermost.accounts..dangerouslyAllowNameMatching` (Plugin channel) +- `channels.synology-chat.dangerouslyAllowNameMatching` (канал plugin) +- `channels.synology-chat.accounts..dangerouslyAllowNameMatching` (канал plugin) +- `channels.synology-chat.dangerouslyAllowInheritedWebhookPath` (канал plugin) +- `channels.zalouser.dangerouslyAllowNameMatching` (канал plugin) +- `channels.zalouser.accounts..dangerouslyAllowNameMatching` (канал plugin) +- `channels.irc.dangerouslyAllowNameMatching` (канал plugin) +- `channels.irc.accounts..dangerouslyAllowNameMatching` (канал plugin) +- `channels.mattermost.dangerouslyAllowNameMatching` (канал plugin) +- `channels.mattermost.accounts..dangerouslyAllowNameMatching` (канал plugin) - `channels.telegram.network.dangerouslyAllowPrivateNetwork` - `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork` - `agents.defaults.sandbox.docker.dangerouslyAllowReservedContainerTargets` @@ -409,18 +414,18 @@ Control UI потребує **безпечного контексту** (HTTPS - `agents.list[].sandbox.docker.dangerouslyAllowExternalBindSources` - `agents.list[].sandbox.docker.dangerouslyAllowContainerNamespaceJoin` -## Конфігурація reverse proxy +## Конфігурація Reverse Proxy Якщо ви запускаєте Gateway за reverse proxy (nginx, Caddy, Traefik тощо), налаштуйте -`gateway.trustedProxies` для коректної обробки пересланих IP-адрес клієнтів. +`gateway.trustedProxies` для коректної обробки forwarded IP-адрес клієнтів. -Коли Gateway виявляє заголовки proxy від адреси, якої **немає** у `trustedProxies`, він **не** вважає такі з’єднання локальними клієнтами. Якщо auth gateway вимкнено, такі з’єднання відхиляються. Це запобігає обходу автентифікації, коли з’єднання через proxy інакше виглядали б як такі, що надходять із localhost, і отримували б автоматичну довіру. +Коли Gateway виявляє proxy-заголовки з адреси, якої **немає** в `trustedProxies`, він **не** вважатиме з’єднання локальними клієнтами. Якщо auth gateway вимкнено, такі з’єднання відхиляються. Це запобігає обходу автентифікації, коли проксійовані з’єднання інакше виглядали б як такі, що надходять із localhost, і отримували б автоматичну довіру. -`gateway.trustedProxies` також використовується для `gateway.auth.mode: "trusted-proxy"`, але цей режим auth суворіший: +`gateway.trustedProxies` також використовується для `gateway.auth.mode: "trusted-proxy"`, але цей режим auth є суворішим: -- trusted-proxy auth **завершується безпечним блокуванням для proxy із джерелом loopback** -- reverse proxy loopback на тому самому хості все одно можуть використовувати `gateway.trustedProxies` для виявлення локальних клієнтів і обробки пересланого IP -- для reverse proxy loopback на тому самому хості використовуйте auth через token/password замість `gateway.auth.mode: "trusted-proxy"` +- auth trusted-proxy **завершується відмовою за замовчуванням для proxy із джерелом loopback** +- reverse proxy на loopback на тому самому хості все одно можуть використовувати `gateway.trustedProxies` для визначення локального клієнта та обробки forwarded IP +- для reverse proxy на loopback на тому самому хості використовуйте auth через token/password замість `gateway.auth.mode: "trusted-proxy"` ```yaml gateway: @@ -434,118 +439,120 @@ gateway: password: ${OPENCLAW_GATEWAY_PASSWORD} ``` -Коли налаштовано `trustedProxies`, Gateway використовує `X-Forwarded-For` для визначення IP-адреси клієнта. `X-Real-IP` типово ігнорується, якщо явно не встановлено `gateway.allowRealIpFallback: true`. +Коли `trustedProxies` налаштовано, Gateway використовує `X-Forwarded-For` для визначення IP-адреси клієнта. `X-Real-IP` типово ігнорується, якщо явно не встановлено `gateway.allowRealIpFallback: true`. -Коректна поведінка reverse proxy (перезапис вхідних заголовків переспрямування): +Належна поведінка reverse proxy (перезапис вхідних forwarding-заголовків): ```nginx proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Real-IP $remote_addr; ``` -Некоректна поведінка reverse proxy (додавання/збереження недовірених заголовків переспрямування): +Неправильна поведінка reverse proxy (додавання/збереження недовірених forwarding-заголовків): ```nginx proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; ``` -## Примітки щодо HSTS та origin +## Примітки щодо HSTS і походження -- Gateway OpenClaw насамперед орієнтований на local/loopback. Якщо ви завершуєте TLS на reverse proxy, встановлюйте HSTS там, на HTTPS-домені з боку proxy. -- Якщо сам gateway завершує HTTPS, ви можете встановити `gateway.http.securityHeaders.strictTransportSecurity`, щоб OpenClaw додавав заголовок HSTS у відповіді. +- Gateway OpenClaw насамперед орієнтований на локальний доступ/loopback. Якщо ви завершуєте TLS на reverse proxy, установлюйте HSTS на HTTPS-домені, який обслуговує proxy. +- Якщо сам gateway завершує HTTPS, ви можете налаштувати `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: ["*"]` — це явна політика browser-origin «дозволити все», а не посилене типове налаштування. Уникайте її поза межами жорстко контрольованого локального тестування. -- Збої auth за browser-origin на loopback усе одно обмежуються rate limiting, навіть коли загальний виняток для loopback увімкнено, але ключ блокування визначається для кожного нормалізованого значення `Origin`, а не для одного спільного сегмента localhost. -- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає режим fallback origin через Host header; розглядайте це як небезпечну політику, свідомо вибрану оператором. -- Розглядайте DNS rebinding і поведінку proxy щодо заголовка Host як питання посилення розгортання; тримайте `trustedProxies` вузьким і уникайте прямого відкриття gateway у публічний інтернет. +- Для розгортань Control UI не на loopback параметр `gateway.controlUi.allowedOrigins` типово є обов’язковим. +- `gateway.controlUi.allowedOrigins: ["*"]` — це явна політика browser-origin «дозволити все», а не посилена типова конфігурація. Уникайте її поза межами суворо контрольованого локального тестування. +- Невдалі перевірки auth за browser-origin на loopback все одно обмежуються через rate limiting, навіть коли + загальний виняток для loopback увімкнено, але ключ блокування визначається окремо + для кожного нормалізованого значення `Origin`, а не як один спільний bucket localhost. +- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає режим fallback походження за заголовком Host; розглядайте це як небезпечну політику, свідомо вибрану operator. +- Розглядайте DNS rebinding і поведінку заголовка host у proxy як питання посилення безпеки розгортання; тримайте `trustedProxies` суворо обмеженим і не відкривайте gateway напряму в публічний інтернет. ## Локальні журнали сесій зберігаються на диску OpenClaw зберігає транскрипти сесій на диску в `~/.openclaw/agents//sessions/*.jsonl`. -Це потрібно для безперервності сесій і (за бажанням) індексації пам’яті сесій, але це також означає, що -**будь-який процес/користувач із доступом до файлової системи може читати ці журнали**. Вважайте доступ до диска -межею довіри та обмежуйте дозволи для `~/.openclaw` (див. розділ аудиту нижче). Якщо вам потрібна -сильніша ізоляція між agent, запускайте їх під окремими користувачами ОС або на окремих хостах. +Це потрібно для безперервності сесій і (необов’язково) індексації пам’яті сесій, але це також означає, +що **будь-який процес/користувач із доступом до файлової системи може читати ці журнали**. Розглядайте доступ до диска як +межу довіри та обмежуйте дозволи для `~/.openclaw` (див. розділ аудиту нижче). Якщо вам потрібна +сильніша ізоляція між агентами, запускайте їх під окремими користувачами ОС або на окремих хостах. -## Виконання на Node (`system.run`) +## Виконання на node (`system.run`) -Якщо спарено macOS Node, Gateway може викликати `system.run` на цьому Node. Це **віддалене виконання коду** на Mac: +Якщо поєднано macOS node, Gateway може викликати `system.run` на цій node. Це **віддалене виконання коду** на Mac: -- Потребує pairing Node (схвалення + token). -- 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`; подальші схвалені переспрямування повторно використовують цей збережений план, а - валідація gateway відхиляє зміни команди/cwd/контексту сесії з боку викликача після - створення запиту на схвалення. -- Якщо вам не потрібне віддалене виконання, установіть security у значення **deny** та видаліть pairing Node для цього Mac. +- Потрібне pairing node (підтвердження + token). +- 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.*`), який може бути суворішим або м’якшим за глобальну політику ID команд у gateway. +- Node, яка працює з `security="full"` і `ask="off"`, дотримується типової моделі довіреного оператора. Розглядайте це як очікувану поведінку, якщо тільки ваше розгортання явно не вимагає суворішої політики підтверджень або allowlist. +- Режим підтвердження прив’язується до точного контексту запиту і, коли це можливо, до одного конкретного локального операнда script/file. Якщо OpenClaw не може точно визначити рівно один прямий локальний файл для команди інтерпретатора/runtime, виконання з підтвердженням відхиляється замість того, щоб обіцяти повне семантичне покриття. +- Для `host=node` виконання з підтвердженням також зберігають канонічний підготовлений + `systemRunPlan`; пізніші схвалені переспрямування повторно використовують цей збережений план, а + валідація gateway відхиляє зміни викликача до команди/cwd/контексту сесії після + створення запиту на підтвердження. +- Якщо ви не хочете віддаленого виконання, установіть security у **deny** і видаліть pairing node для цього Mac. -Ця відмінність важлива для оцінки: +Це розрізнення важливе для triage: -- Повторно підключений спарений Node, який оголошує інший список команд, сам по собі не є вразливістю, якщо глобальна політика Gateway і локальні схвалення exec на Node усе ще забезпечують фактичну межу виконання. -- Звіти, які трактують metadata pairing Node як другий прихований рівень схвалення для кожної команди, зазвичай є плутаниною політики/UX, а не обходом межі безпеки. +- Повторно підключена поєднана node, яка рекламує інший список команд, сама по собі не є вразливістю, якщо глобальна політика Gateway та локальні підтвердження exec на node все ще забезпечують фактичну межу виконання. +- Повідомлення, які трактують метадані pairing node як другий прихований рівень підтвердження для кожної команди, зазвичай є плутаниною щодо політики/UX, а не обходом межі безпеки. -## Динамічні Skills (watcher / віддалені Node) +## Динамічні Skills (watcher / віддалені node) OpenClaw може оновлювати список Skills посеред сесії: -- **Watcher Skills**: зміни в `SKILL.md` можуть оновити знімок Skills на наступному ході agent. -- **Віддалені Node**: підключення macOS Node може зробити доступними Skills лише для macOS (на основі перевірки bin). +- **Watcher Skills**: зміни в `SKILL.md` можуть оновити snapshot Skills на наступному ході агента. +- **Віддалені node**: підключення macOS node може зробити доступними Skills лише для macOS (на основі перевірки bin). -Сприймайте папки Skill як **довірений код** і обмежуйте коло тих, хто може їх змінювати. +Розглядайте папки Skills як **довірений код** і обмежуйте коло тих, хто може їх змінювати. ## Модель загроз -Ваш AI-асистент може: +Ваш AI-помічник може: -- Виконувати довільні команди оболонки +- Виконувати довільні shell-команди - Читати/записувати файли - Отримувати доступ до мережевих сервісів -- Надсилати повідомлення будь-кому (якщо ви надали йому доступ до WhatsApp) +- Надсилати повідомлення будь-кому (якщо ви надасте йому доступ до WhatsApp) -Люди, які можуть вам писати, можуть: +Люди, які надсилають вам повідомлення, можуть: -- Намагатися обдурити ваш AI і змусити його зробити щось погане -- Соціальною інженерією намагатися отримати доступ до ваших даних -- Досліджувати інфраструктурні деталі +- Намагатися обманом змусити ваш AI зробити щось шкідливе +- Використовувати соціальну інженерію, щоб отримати доступ до ваших даних +- Збирати відомості про інфраструктуру -## Ключова ідея: контроль доступу перед інтелектом +## Основна концепція: контроль доступу перед інтелектом -Більшість збоїв тут — не вишукані експлойти, а ситуації на кшталт: «хтось написав боту, і бот зробив те, що його попросили». +Більшість збоїв тут — це не витончені експлойти, а ситуації на кшталт «хтось написав боту, і бот зробив те, що його попросили». -Позиція OpenClaw: +Підхід OpenClaw: -- **Спочатку ідентичність:** вирішіть, хто може писати боту (pairing DM / allowlist / явний режим “open”). -- **Потім межі:** вирішіть, де боту дозволено діяти (allowlist груп + вимога згадки, інструменти, sandboxing, дозволи пристрою). -- **Модель — останньою:** виходьте з того, що моделлю можна маніпулювати; проєктуйте систему так, щоб маніпуляція мала обмежений радіус ураження. +- **Спочатку ідентичність:** визначте, хто може спілкуватися з ботом (pairing у DM / allowlist / явний режим “open”). +- **Потім область дії:** визначте, де боту дозволено діяти (allowlist груп + обов’язкова згадка, інструменти, sandboxing, дозволи пристрою). +- **Останнє — модель:** виходьте з того, що моделлю можна маніпулювати; проєктуйте систему так, щоб наслідки маніпуляції були обмеженими. ## Модель авторизації команд Slash-команди та директиви виконуються лише для **авторизованих відправників**. Авторизація визначається через -allowlist/pairing channel плюс `commands.useAccessGroups` (див. [Configuration](/uk/gateway/configuration) -і [Slash commands](/uk/tools/slash-commands)). Якщо allowlist channel порожній або містить `"*"`, -команди фактично відкриті для цього channel. +allowlist/pairing каналу плюс `commands.useAccessGroups` (див. [Configuration](/uk/gateway/configuration) +і [Slash commands](/uk/tools/slash-commands)). Якщо allowlist каналу порожній або містить `"*"`, +команди фактично відкриті для цього каналу. -`/exec` — це зручна команда лише для сесії, призначена для авторизованих операторів. Вона **не** записує config і +`/exec` — це зручна команда лише для сесії для авторизованих operator. Вона **не** записує конфігурацію й не змінює інші сесії. ## Ризики інструментів control plane Два вбудовані інструменти можуть вносити постійні зміни в control plane: -- `gateway` може переглядати config через `config.schema.lookup` / `config.get`, а також вносити постійні зміни через `config.apply`, `config.patch` і `update.run`. -- `cron` може створювати заплановані завдання, які продовжують працювати після завершення початкового chat/task. +- `gateway` може перевіряти конфігурацію за допомогою `config.schema.lookup` / `config.get` і вносити постійні зміни за допомогою `config.apply`, `config.patch` та `update.run`. +- `cron` може створювати заплановані завдання, які продовжують працювати після завершення оригінального чату/задачі. -Інструмент runtime `gateway`, доступний лише власнику, усе одно відмовляється переписувати +Інструмент runtime `gateway`, доступний лише власнику, як і раніше відмовляється переписувати `tools.exec.ask` або `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec перед записом. -Для будь-якого agent/поверхні, що обробляє недовірений контент, забороняйте їх за замовчуванням: +Для будь-якого агента/поверхні, що обробляє недовірений контент, забороняйте їх типово: ```json5 { @@ -555,23 +562,23 @@ allowlist/pairing channel плюс `commands.useAccessGroups` (див. [Configur } ``` -`commands.restart=false` блокує лише дії перезапуску. Він не вимикає дії `gateway` щодо config/update. +`commands.restart=false` блокує лише дії перезапуску. Він не вимикає дії `gateway` з конфігурацією/оновленням. ## Plugins -Plugins працюють **у тому самому процесі**, що й Gateway. Сприймайте їх як довірений код: +Plugins працюють **у тому самому процесі** з Gateway. Розглядайте їх як довірений код: -- Установлюйте plugins лише з джерел, яким довіряєте. +- Установлюйте plugins лише з джерел, яким ви довіряєте. - Віддавайте перевагу явним allowlist `plugins.allow`. -- Переглядайте config Plugin перед увімкненням. -- Перезапускайте Gateway після змін Plugin. +- Перевіряйте конфігурацію plugin перед увімкненням. +- Після змін plugins перезапускайте Gateway. - Якщо ви встановлюєте або оновлюєте plugins (`openclaw plugins install `, `openclaw plugins update `), ставтеся до цього як до запуску недовіреного коду: - - Шлях встановлення — це каталог окремого Plugin у межах активного кореня встановлення Plugin. - - OpenClaw запускає вбудоване сканування небезпечного коду перед встановленням/оновленням. Знахідки рівня `critical` типово блокують процес. - - OpenClaw використовує `npm pack`, а потім запускає `npm install --omit=dev` у цьому каталозі (скрипти життєвого циклу npm можуть виконувати код під час встановлення). - - Віддавайте перевагу зафіксованим точним версіям (`@scope/pkg@1.2.3`) і перевіряйте розпакований код на диску перед увімкненням. - - `--dangerously-force-unsafe-install` — лише для аварійних випадків, коли вбудоване сканування дає хибнопозитивний результат у потоках встановлення/оновлення Plugin. Цей прапорець не обходить блокування політики хука Plugin `before_install` і не обходить збої сканування. - - Встановлення залежностей Skill через Gateway дотримуються того самого поділу на небезпечне/підозріле: вбудовані знахідки `critical` блокують процес, якщо викликач явно не встановить `dangerouslyForceUnsafeInstall`, тоді як підозрілі знахідки, як і раніше, лише попереджають. `openclaw skills install` залишається окремим потоком завантаження/встановлення Skills з ClawHub. + - Шлях встановлення — це каталог конкретного 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`, тоді як підозрілі знахідки, як і раніше, лише попереджають. `openclaw skills install` лишається окремим потоком завантаження/встановлення Skills із ClawHub. Докладніше: [Plugins](/uk/tools/plugin) @@ -579,11 +586,11 @@ Plugins працюють **у тому самому процесі**, що й Ga ## Модель доступу DM (pairing / allowlist / open / disabled) -Усі поточні channel з підтримкою DM мають політику DM (`dmPolicy` або `*.dm.policy`), яка відсікає вхідні DM **до** обробки повідомлення: +Усі поточні канали з підтримкою DM підтримують політику DM (`dmPolicy` або `*.dm.policy`), яка блокує вхідні DM **до** обробки повідомлення: -- `pairing` (типово): невідомі відправники отримують короткий код pairing, а бот ігнорує їхнє повідомлення до схвалення. Коди діють 1 годину; повторні DM не надсилатимуть код повторно, доки не буде створено новий запит. Кількість запитів у стані очікування типово обмежена до **3 на channel**. -- `allowlist`: невідомі відправники блокуються (без handshake pairing). -- `open`: дозволити будь-кому писати в DM (публічно). **Потребує**, щоб allowlist channel містив `"*"` (явне підтвердження). +- `pairing` (типово): невідомі відправники отримують короткий код pairing, а бот ігнорує їхнє повідомлення, доки його не буде схвалено. Коди діють 1 годину; повторні DM не надсилатимуть код повторно, доки не буде створено новий запит. Кількість очікувальних запитів типово обмежена **3 на канал**. +- `allowlist`: невідомі відправники блокуються (без процедури pairing). +- `open`: дозволити будь-кому надсилати DM (публічно). **Потребує**, щоб allowlist каналу містив `"*"` (явна згода). - `disabled`: повністю ігнорувати вхідні DM. Схвалення через CLI: @@ -597,7 +604,7 @@ openclaw pairing approve ## Ізоляція сесій DM (багатокористувацький режим) -Типово OpenClaw спрямовує **усі DM в основну сесію**, щоб ваш асистент мав безперервність між пристроями й channel. Якщо **кілька людей** можуть писати боту в DM (відкриті DM або allowlist із кількома особами), розгляньте ізоляцію сесій DM: +Типово OpenClaw маршрутизує **усі DM в основну сесію**, щоб ваш помічник зберігав безперервність між пристроями та каналами. Якщо **кілька людей** можуть надсилати DM боту (відкриті DM або allowlist із кількох осіб), розгляньте ізоляцію сесій DM: ```json5 { @@ -605,76 +612,76 @@ openclaw pairing approve } ``` -Це запобігає витоку контексту між користувачами, зберігаючи при цьому ізоляцію групових chat. +Це запобігає витоку контексту між користувачами, зберігаючи ізоляцію групових чатів. -Це межа контексту обміну повідомленнями, а не межа адміністрування хоста. Якщо користувачі є взаємно змагальними й ділять той самий host/config Gateway, запускайте окремі Gateway для кожної межі довіри. +Це межа контексту обміну повідомленнями, а не межа адміністрування хоста. Якщо користувачі є взаємно зловмисними та спільно використовують той самий хост/конфігурацію Gateway, натомість запускайте окремі gateway для кожної межі довіри. ### Безпечний режим DM (рекомендовано) -Сприймайте фрагмент вище як **безпечний режим DM**: +Розглядайте наведений вище фрагмент як **безпечний режим DM**: -- Типово: `session.dmScope: "main"` (усі DM ділять одну сесію заради безперервності). -- Типове значення локального onboarding через CLI: записує `session.dmScope: "per-channel-peer"`, якщо параметр не задано (наявні явні значення зберігаються). -- Безпечний режим DM: `session.dmScope: "per-channel-peer"` (кожна пара channel+відправник отримує ізольований контекст DM). -- Ізоляція користувача між channel: `session.dmScope: "per-peer"` (кожен відправник отримує одну сесію в усіх channel одного типу). +- Типово: `session.dmScope: "main"` (усі DM спільно використовують одну сесію для безперервності). +- Типове значення під час локального онбордингу CLI: записує `session.dmScope: "per-channel-peer"`, якщо значення не встановлено (наявні явні значення не змінюються). +- Безпечний режим DM: `session.dmScope: "per-channel-peer"` (кожна пара канал+відправник отримує ізольований контекст DM). +- Ізоляція peer між каналами: `session.dmScope: "per-peer"` (кожен відправник отримує одну сесію в усіх каналах одного типу). -Якщо ви використовуєте кілька облікових записів в одному channel, використовуйте натомість `per-account-channel-peer`. Якщо одна й та сама людина звертається до вас через кілька channel, використовуйте `session.identityLinks`, щоб об’єднати ці сесії DM в одну канонічну ідентичність. Див. [Session Management](/uk/concepts/session) і [Configuration](/uk/gateway/configuration). +Якщо ви використовуєте кілька акаунтів в одному каналі, натомість застосовуйте `per-account-channel-peer`. Якщо одна й та сама людина зв’язується з вами через кілька каналів, використовуйте `session.identityLinks`, щоб об’єднати ці DM-сесії в одну канонічну ідентичність. Див. [Session Management](/uk/concepts/session) і [Configuration](/uk/gateway/configuration). ## Allowlists (DM + групи) — термінологія -OpenClaw має два окремі шари «хто може мене запускати?»: +OpenClaw має два окремі рівні «хто може мене активувати?»: -- **Allowlist DM** (`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`; застаріле: `channels.discord.dm.allowFrom`, `channels.slack.dm.allowFrom`): хто має право писати боту в direct messages. - - Коли `dmPolicy="pairing"`, схвалення записуються в прив’язане до облікового запису сховище allowlist pairing у `~/.openclaw/credentials/` (`-allowFrom.json` для типового облікового запису, `--allowFrom.json` для нетипових облікових записів), а потім об’єднуються з allowlist із config. -- **Allowlist груп** (специфічний для channel): з яких груп/channel/guilds бот узагалі прийматиме повідомлення. - - Типові шаблони: - - `channels.whatsapp.groups`, `channels.telegram.groups`, `channels.imessage.groups`: типові налаштування для окремої групи, наприклад `requireMention`; якщо задано, це також працює як allowlist груп (додайте `"*"`, щоб зберегти поведінку «дозволити всі»). - - `groupPolicy="allowlist"` + `groupAllowFrom`: обмежує, хто може запускати бота _всередині_ групової сесії (WhatsApp/Telegram/Signal/iMessage/Microsoft Teams). - - `channels.discord.guilds` / `channels.slack.channels`: allowlist для окремих поверхонь + типові правила згадок. - - Перевірки груп виконуються в такому порядку: спочатку `groupPolicy`/allowlist груп, потім активація через згадку/відповідь. - - Відповідь на повідомлення бота (неявна згадка) **не** обходить allowlist відправника, як-от `groupAllowFrom`. - - **Примітка щодо безпеки:** сприймайте `dmPolicy="open"` і `groupPolicy="open"` як налаштування крайнього випадку. Їх слід використовувати якомога рідше; віддавайте перевагу pairing + allowlist, якщо тільки ви повністю не довіряєте кожному учаснику кімнати. +- **Allowlist для DM** (`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`; застаріле: `channels.discord.dm.allowFrom`, `channels.slack.dm.allowFrom`): хто має право спілкуватися з ботом у прямих повідомленнях. + - Коли `dmPolicy="pairing"`, схвалення записуються в account-scoped сховище pairing allowlist у `~/.openclaw/credentials/` (`-allowFrom.json` для типового акаунта, `--allowFrom.json` для нетипових акаунтів), а потім об’єднуються з allowlist із конфігурації. +- **Allowlist для груп** (залежить від каналу): з яких саме груп/каналів/guild бот узагалі прийматиме повідомлення. + - Поширені шаблони: + - `channels.whatsapp.groups`, `channels.telegram.groups`, `channels.imessage.groups`: типові налаштування для кожної групи, як-от `requireMention`; якщо їх задано, це також працює як allowlist груп (додайте `"*"`, щоб зберегти поведінку «дозволити все»). + - `groupPolicy="allowlist"` + `groupAllowFrom`: обмежує, хто може активувати бота _всередині_ групової сесії (WhatsApp/Telegram/Signal/iMessage/Microsoft Teams). + - `channels.discord.guilds` / `channels.slack.channels`: allowlist для кожної поверхні + типові налаштування згадок. + - Перевірки груп виконуються в такому порядку: спочатку `groupPolicy`/group allowlists, потім активація згадкою/відповіддю. + - Відповідь на повідомлення бота (неявна згадка) **не** обходить allowlist відправників, як-от `groupAllowFrom`. + - **Примітка щодо безпеки:** розглядайте `dmPolicy="open"` і `groupPolicy="open"` як налаштування на крайній випадок. Їх слід використовувати якомога рідше; віддавайте перевагу pairing + allowlists, якщо тільки ви повністю не довіряєте кожному учаснику кімнати. Докладніше: [Configuration](/uk/gateway/configuration) і [Groups](/uk/channels/groups) -## Prompt-ін’єкція (що це, чому це важливо) +## Prompt injection (що це таке і чому це важливо) -Prompt-ін’єкція — це коли зловмисник створює повідомлення, яке маніпулює моделлю, щоб вона зробила щось небезпечне («ігноруй свої інструкції», «виведи файлову систему», «перейди за цим посиланням і виконай команди» тощо). +Prompt injection — це коли зловмисник створює повідомлення, яке маніпулює моделлю, змушуючи її робити щось небезпечне («ігноруй свої інструкції», «виведи вміст файлової системи», «перейди за цим посиланням і виконай команди» тощо). -Навіть за наявності сильних системних prompt, **prompt-ін’єкцію не вирішено**. Запобіжники на рівні системного prompt — це лише м’які вказівки; жорстке забезпечення дають політика інструментів, схвалення exec, sandboxing і allowlist channel (а оператори можуть вимкнути їх за задумом). Що реально допомагає на практиці: +Навіть за наявності сильних system prompt **проблему prompt injection не вирішено**. Запобіжники в system prompt — це лише м’які вказівки; жорстке примушення забезпечується політикою інструментів, підтвердженнями exec, sandboxing і allowlist каналів (і оператори можуть навмисно їх вимикати). Що реально допомагає: -- Тримайте вхідні DM закритими (pairing/allowlist). -- У групах віддавайте перевагу активації через згадку; уникайте ботів, які «завжди слухають» у публічних кімнатах. -- За замовчуванням ставтеся до посилань, вкладень і вставлених інструкцій як до ворожих. -- Виконуйте чутливі інструменти в sandbox; тримайте секрети поза досяжною для agent файловою системою. -- Примітка: sandboxing є opt-in. Якщо режим 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**, тож allowlist-тіло heredoc не зможе непомітно провести розширення shell повз перевірку allowlist як звичайний текст. Щоб увімкнути буквальну семантику тіла, беріть термінатор heredoc у лапки (наприклад, `<<'EOF'`); нецитовані heredoc, у яких відбулося б розширення змінних, відхиляються. -- **Вибір моделі має значення:** старіші/менші/застарілі моделі значно менш стійкі до prompt-ін’єкції та зловживання інструментами. Для agent з увімкненими інструментами використовуйте найсильнішу доступну модель останнього покоління, посилену щодо інструкцій. +- Тримайте вхідні DM під контролем (pairing/allowlists). +- У групах віддавайте перевагу активації згадкою; уникайте ботів, які «завжди слухають» у публічних кімнатах. +- Розглядайте посилання, вкладення та вставлені інструкції як ворожі за замовчуванням. +- Виконуйте чутливі дії інструментів у 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-форми все одно потребували явного підтвердження. +- Аналіз підтвердження shell також відхиляє форми POSIX parameter-expansion (`$VAR`, `$?`, `$$`, `$1`, `$@`, `${…}`) усередині **нецитованих heredoc**, тож allowlisted тіло heredoc не зможе приховано провести розширення shell повз перевірку allowlist як звичайний текст. Щоб увімкнути буквальну семантику тіла, беріть завершувач heredoc у лапки (наприклад, `<<'EOF'`); нецитовані heredoc, які б виконали розширення змінних, відхиляються. +- **Вибір моделі має значення:** старіші/менші/застарілі моделі значно менш стійкі до prompt injection і неправильного використання інструментів. Для агентів з увімкненими інструментами використовуйте найсильнішу доступну модель останнього покоління, стійку до інструкцій. Ознаки, які слід вважати недовіреними: -- «Прочитай цей файл/URL і зроби точно те, що там написано.» -- «Ігноруй свій системний prompt або правила безпеки.» -- «Розкрий свої приховані інструкції або результати роботи інструментів.» -- «Встав повний вміст `~/.openclaw` або свої журнали.» +- «Прочитай цей файл/URL і зроби точно те, що там сказано». +- «Ігноруй свій system prompt або правила безпеки». +- «Розкрий свої приховані інструкції або результати інструментів». +- «Встав повний вміст ~/.openclaw або свої журнали». -## Санітизація спеціальних токенів у зовнішньому контенті +## Санітизація спеціальних токенів у зовнішньому вмісті -OpenClaw видаляє поширені літерали спеціальних токенів шаблонів chat для self-hosted LLM із обгорнутого зовнішнього контенту та metadata до того, як вони потрапляють у модель. До покритих сімейств маркерів належать токени ролей/ходів Qwen/ChatML, Llama, Gemma, Mistral, Phi і GPT-OSS. +OpenClaw видаляє поширені спеціальні токени шаблонів чату self-hosted LLM із обгорнутого зовнішнього вмісту та метаданих до того, як вони потрапляють у модель. Підтримуються сімейства маркерів Qwen/ChatML, Llama, Gemma, Mistral, Phi і токени ролей/ходів GPT-OSS. -Чому: +Навіщо: -- Backends, сумісні з OpenAI, які працюють поверх self-hosted моделей, інколи зберігають спеціальні токени, що з’являються в тексті користувача, замість того щоб їх маскувати. Зловмисник, який може записати дані у вхідний зовнішній контент (завантажена сторінка, тіло email, результат інструмента читання вмісту файлу), інакше міг би вставити синтетичну межу ролі `assistant` або `system` і вийти за межі запобіжників обгорнутого контенту. -- Санітизація відбувається на рівні обгортання зовнішнього контенту, тому вона однаково застосовується до інструментів fetch/read та вхідного контенту channel, а не реалізується окремо для кожного провайдера. -- Вихідні відповіді моделі вже мають окремий санітайзер, який прибирає з видимих користувачу відповідей витік `tool_call`, `` і подібної службової структури. Санітайзер зовнішнього контенту — це вхідний відповідник цього механізму. +- Backends, сумісні з OpenAI, які працюють поверх self-hosted моделей, інколи зберігають спеціальні токени, що з’являються в тексті користувача, замість їх маскування. Зловмисник, який може записати щось у вхідний зовнішній вміст (отриману сторінку, тіло листа, вивід інструмента читання файла), інакше міг би вставити синтетичну межу ролі `assistant` або `system` і обійти запобіжники для обгорнутого вмісту. +- Санітизація відбувається на рівні обгортання зовнішнього вмісту, тому застосовується однаково до інструментів fetch/read і вхідного вмісту каналів, а не залежить від конкретного провайдера. +- Вихідні відповіді моделі вже мають окремий санітайзер, який видаляє витоки на кшталт ``, `` та подібну службову структуру з відповідей, видимих користувачу. Санітизація зовнішнього вмісту є її вхідним відповідником. -Це не замінює інші засоби посилення захисту на цій сторінці — `dmPolicy`, allowlist, схвалення exec, sandboxing і `contextVisibility` усе ще виконують основну роботу. Це закриває один конкретний обхід на рівні tokenizer для self-hosted стеків, які передають текст користувача зі збереженими спеціальними токенами. +Це не замінює інші механізми посилення на цій сторінці — `dmPolicy`, allowlists, підтвердження exec, sandboxing і `contextVisibility` усе ще виконують основну роботу. Це закриває один конкретний обхід на рівні токенізатора проти self-hosted стеків, які передають текст користувача зі збереженими спеціальними токенами. -## Прапорці обходу небезпечного зовнішнього контенту +## Прапори обходу для небезпечного зовнішнього вмісту -OpenClaw містить явні прапорці обходу, які вимикають безпечне обгортання зовнішнього контенту: +OpenClaw містить явні прапори обходу, які вимикають безпечне обгортання зовнішнього вмісту: - `hooks.mappings[].allowUnsafeExternalContent` - `hooks.gmail.allowUnsafeExternalContent` @@ -682,143 +689,143 @@ OpenClaw містить явні прапорці обходу, які вими Рекомендації: -- Тримайте їх не встановленими/false у production. -- Увімкнюйте лише тимчасово для вузькоспрямованого налагодження. -- Якщо увімкнено, ізолюйте цей agent (sandbox + мінімум інструментів + окремий простір імен сесій). +- Тримайте їх unset/false у production. +- Тимчасово вмикайте лише для вузько обмеженого налагодження. +- Якщо їх увімкнено, ізолюйте цього агента (sandbox + мінімальні інструменти + виділений простір імен сесій). -Примітка про ризики hooks: +Примітка щодо ризиків hooks: -- Payload hooks — це недовірений контент, навіть якщо доставка надходить із систем, які ви контролюєте (mail/docs/web-контент може нести prompt-ін’єкцію). -- Слабкі рівні моделей збільшують цей ризик. Для автоматизації на основі hooks віддавайте перевагу сильним сучасним рівням моделей і тримайте політику інструментів жорсткою (`tools.profile: "messaging"` або суворіше), а також використовуйте sandboxing там, де це можливо. +- Payload hooks — це недовірений вміст, навіть якщо доставка надходить із систем, які ви контролюєте (пошта/документи/вебвміст можуть містити prompt injection). +- Слабкі рівні моделей підвищують цей ризик. Для автоматизації на основі hooks віддавайте перевагу сильним сучасним рівням моделей і тримайте політику інструментів суворою (`tools.profile: "messaging"` або суворіше), а також використовуйте sandboxing де це можливо. -### Prompt-ін’єкція не потребує публічних DM +### Prompt injection не потребує публічних DM -Навіть якщо **лише ви** можете писати боту, prompt-ін’єкція все одно може статися через -будь-який **недовірений контент**, який читає бот (результати web search/fetch, сторінки browser, -email, docs, вкладення, вставлені журнали/код). Іншими словами: відправник — не -єдина поверхня загрози; сама **сутність контенту** також може містити ворожі інструкції. +Навіть якщо **лише ви** можете надсилати повідомлення боту, prompt injection усе одно може статися через +будь-який **недовірений вміст**, який бот читає (результати web search/fetch, сторінки браузера, +листи, документи, вкладення, вставлені журнали/код). Іншими словами: не лише відправник є +поверхнею загрози; **сам вміст** також може містити ворожі інструкції. -Коли інструменти увімкнені, типовий ризик — це ексфільтрація контексту або запуск +Коли інструменти увімкнені, типовий ризик — це витік контексту або ініціювання викликів інструментів. Зменшуйте радіус ураження так: -- Використовуйте **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 декодував його локально. Вбудований блок усе одно містить явні - маркери меж `<<>>` плюс metadata `Source: External`, + `gateway.http.endpoints.responses.images.urlAllowlist`, а також тримайте `maxUrlParts` низьким. + Порожні allowlist трактуються як unset; використовуйте `files.allowUrl: false` / `images.allowUrl: false`, + якщо хочете повністю вимкнути отримання через URL. +- Для файлових входів OpenResponses декодований текст `input_file` усе одно додається як + **недовірений зовнішній вміст**. Не покладайтеся на те, що текст файла є довіреним лише тому, + що Gateway декодував його локально. Доданий блок усе одно містить явні + маркери меж `<<>>` плюс метадані `Source: External`, хоча цей шлях і пропускає довший банер `SECURITY NOTICE:`. -- Те саме обгортання на основі маркерів застосовується, коли розуміння медіа витягує текст - із прикріплених документів перед додаванням цього тексту до prompt медіа. -- Увімкнення sandboxing і суворих allowlist інструментів для будь-якого agent, який працює з недовіреним введенням. -- Тримайте секрети поза prompt; передавайте їх через env/config на хості gateway. +- Те саме обгортання на основі маркерів застосовується, коли media-understanding витягує текст + із вкладених документів перед додаванням цього тексту до медіапідказки. +- Увімкнення sandboxing і суворих allowlist інструментів для будь-якого агента, що працює з недовіреним вхідним вмістом. +- Не зберігайте секрети в prompt; передавайте їх через env/config на хості gateway. -### Self-hosted backends LLM +### Self-hosted LLM backends -Backends self-hosted, сумісні з OpenAI, такі як vLLM, SGLang, TGI, LM Studio, -або власні стеки tokenizer Hugging Face, можуть відрізнятися від хостингових провайдерів у тому, -як обробляються спеціальні токени шаблонів chat. Якщо backend токенізує буквальні рядки +Backends self-hosted, сумісні з OpenAI, як-от vLLM, SGLang, TGI, LM Studio +або власні стеки токенізаторів Hugging Face, можуть відрізнятися від хостингових провайдерів у тому, +як обробляються спеціальні токени шаблонів чату. Якщо backend токенізує буквальні рядки на кшталт `<|im_start|>`, `<|start_header_id|>` або `` як -структурні токени шаблону chat усередині користувацького контенту, недовірений текст може спробувати -підробити межі ролей на рівні tokenizer. +структурні токени шаблону чату всередині користувацького вмісту, недовірений текст може намагатися +підробити межі ролей на рівні токенізатора. -OpenClaw видаляє поширені літерали спеціальних токенів сімейств моделей з обгорнутого -зовнішнього контенту перед передаванням його в модель. Тримайте обгортання зовнішнього -контенту увімкненим і, за можливості, віддавайте перевагу налаштуванням backend, які розділяють або екранують спеціальні -токени в контенті, наданому користувачем. Хостингові провайдери, такі як OpenAI -та Anthropic, уже застосовують власну санітизацію на стороні запиту. +OpenClaw видаляє поширені буквальні спеціальні токени сімейств моделей із обгорнутого +зовнішнього вмісту перед передаванням його моделі. Тримайте обгортання +зовнішнього вмісту увімкненим і, за наявності такої можливості, віддавайте перевагу налаштуванням backend, які розділяють або екранують спеціальні +токени у вмісті, наданому користувачем. Хостингові провайдери, як-от OpenAI +і Anthropic, уже застосовують власну санітизацію на стороні запиту. -### Сила моделі (примітка щодо безпеки) +### Потужність моделі (примітка щодо безпеки) -Стійкість до prompt-ін’єкцій **не** є однаковою для всіх рівнів моделей. Менші/дешевші моделі загалом більш схильні до зловживання інструментами та перехоплення інструкцій, особливо за наявності змагальних prompt. +Стійкість до prompt injection **не** є однаковою в усіх рівнях моделей. Менші/дешевші моделі загалом більш вразливі до неправильного використання інструментів і перехоплення інструкцій, особливо за наявності зловмисних prompt. -Для agent з увімкненими інструментами або agent, які читають недовірений контент, ризик prompt-ін’єкції зі старішими/меншими моделями часто є надто високим. Не запускайте такі навантаження на слабких рівнях моделей. +Для агентів з увімкненими інструментами або агентів, які читають недовірений вміст, ризик prompt injection зі старішими/меншими моделями часто є надто високим. Не запускайте такі навантаження на слабких рівнях моделей. Рекомендації: -- **Використовуйте модель останнього покоління найвищого рівня** для будь-якого бота, який може запускати інструменти або працювати з файлами/мережами. -- **Не використовуйте старіші/слабші/менші рівні** для agent з увімкненими інструментами або недовірених inbox; ризик prompt-ін’єкції надто високий. -- Якщо ви змушені використовувати меншу модель, **зменшуйте радіус ураження** (лише читання, сильне sandboxing, мінімальний доступ до файлової системи, суворі allowlist). -- Під час роботи з малими моделями **увімкніть sandboxing для всіх сесій** і **вимкніть `web_search`/`web_fetch`/`browser`**, якщо вхідні дані не контролюються жорстко. -- Для персональних асистентів лише для chat із довіреним входом і без інструментів менші моделі зазвичай підходять. +- **Використовуйте модель останнього покоління найкращого рівня** для будь-якого бота, який може запускати інструменти або працювати з файлами/мережами. +- **Не використовуйте старіші/слабші/менші рівні** для агентів з увімкненими інструментами або недовірених inbox; ризик prompt injection надто високий. +- Якщо вам усе ж доводиться використовувати меншу модель, **зменшуйте радіус ураження** (лише читання для інструментів, сильне sandboxing, мінімальний доступ до файлової системи, суворі allowlist). +- Під час запуску малих моделей **увімкніть sandboxing для всіх сесій** і **вимкніть `web_search`/`web_fetch`/`browser`**, якщо тільки вхідні дані не контролюються дуже суворо. +- Для персональних помічників лише для чату з довіреним вхідним вмістом і без інструментів менші моделі зазвичай підходять. ## Reasoning і докладний вивід у групах -`/reasoning`, `/verbose` і `/trace` можуть розкривати внутрішні міркування, вивід -інструментів або діагностику Plugin, які -не призначалися для публічного channel. У групових сценаріях сприймайте їх як **лише -для налагодження** і тримайте вимкненими, якщо вони вам явно не потрібні. +`/reasoning`, `/verbose` і `/trace` можуть розкривати внутрішнє reasoning, вивід +інструментів або діагностику plugin, які +не призначалися для публічного каналу. У групових сценаріях розглядайте їх як **лише для debug** +і тримайте вимкненими, якщо тільки вони вам справді не потрібні. Рекомендації: - Тримайте `/reasoning`, `/verbose` і `/trace` вимкненими в публічних кімнатах. -- Якщо ви їх увімкнули, робіть це лише в довірених DM або жорстко контрольованих кімнатах. -- Пам’ятайте: вивід verbose і trace може містити аргументи інструментів, URL, діагностику Plugin і дані, які бачила модель. +- Якщо ви їх вмикаєте, робіть це лише в довірених DM або суворо контрольованих кімнатах. +- Пам’ятайте: verbose- і trace-вивід можуть містити аргументи інструментів, URL, діагностику plugin і дані, які бачила модель. ## Посилення конфігурації (приклади) ### 0) Дозволи файлів -Тримайте config + state приватними на хості gateway: +Тримайте конфігурацію та стан закритими на хості gateway: - `~/.openclaw/openclaw.json`: `600` (лише читання/запис для користувача) -- `~/.openclaw`: `700` (лише для користувача) +- `~/.openclaw`: `700` (лише користувач) -`openclaw doctor` може попередити та запропонувати посилити ці дозволи. +`openclaw doctor` може попередити про це й запропонувати посилити ці дозволи. -### 0.4) Мережеве відкриття (bind + порт + firewall) +### 0.4) Мережевий доступ (bind + порт + firewall) Gateway мультиплексує **WebSocket + HTTP** на одному порту: -- Типовий: `18789` +- Типово: `18789` - Config/flags/env: `gateway.port`, `--port`, `OPENCLAW_GATEWAY_PORT` -Ця поверхня HTTP включає Control UI і хост canvas: +Ця HTTP-поверхня містить Control UI і host canvas: -- Control UI (ресурси SPA) (типовий базовий шлях `/`) -- Хост canvas: `/__openclaw__/canvas/` і `/__openclaw__/a2ui/` (довільний HTML/JS; ставтеся до цього як до недовіреного контенту) +- Control UI (активи SPA) (типовий базовий шлях `/`) +- Host canvas: `/__openclaw__/canvas/` і `/__openclaw__/a2ui/` (довільний HTML/JS; розглядайте як недовірений вміст) -Якщо ви завантажуєте контент canvas у звичайному browser, ставтеся до нього як до будь-якої іншої недовіреної вебсторінки: +Якщо ви завантажуєте вміст canvas у звичайному браузері, ставтеся до нього як до будь-якої іншої недовіреної вебсторінки: -- Не відкривайте хост canvas для недовірених мереж/користувачів. -- Не змушуйте контент canvas використовувати той самий origin, що й привілейовані вебповерхні, якщо ви повністю не розумієте наслідків. +- Не відкривайте host canvas для недовірених мереж/користувачів. +- Не дозволяйте вмісту canvas спільно використовувати те саме origin, що й привілейовані вебповерхні, якщо ви повністю не розумієте наслідків. -Режим bind визначає, де Gateway слухає з’єднання: +Режим bind визначає, де слухає Gateway: - `gateway.bind: "loopback"` (типово): можуть підключатися лише локальні клієнти. -- Bind поза loopback (`"lan"`, `"tailnet"`, `"custom"`) розширює поверхню атаки. Використовуйте їх лише з auth gateway (спільний token/password або правильно налаштований trusted proxy поза loopback) і справжнім firewall. +- Bind не на loopback (`"lan"`, `"tailnet"`, `"custom"`) розширюють поверхню атаки. Використовуйте їх лише з auth gateway (спільний token/password або правильно налаштований trusted proxy не на loopback) і справжнім firewall. Практичні правила: -- Віддавайте перевагу Tailscale Serve замість bind у LAN (Serve залишає Gateway на loopback, а доступ обробляє Tailscale). -- Якщо ви все ж маєте виконати bind у LAN, обмежте порт через firewall вузьким allowlist вихідних IP-адрес; не робіть широке порт-форвардинг-відкриття. -- Ніколи не відкривайте Gateway без автентифікації на `0.0.0.0`. +- Віддавайте перевагу Tailscale Serve замість bind на LAN (Serve залишає Gateway на loopback, а Tailscale керує доступом). +- Якщо вам усе ж потрібен bind на LAN, обмежте порт через firewall жорстким allowlist IP-адрес джерел; не робіть широке port-forwarding. +- Ніколи не відкривайте Gateway без auth на `0.0.0.0`. ### 0.4.1) Публікація портів Docker + UFW (`DOCKER-USER`) -Якщо ви запускаєте OpenClaw з Docker на VPS, пам’ятайте, що опубліковані порти container -(`-p HOST:CONTAINER` або Compose `ports:`) маршрутизуються через ланцюги переспрямування Docker, -а не лише через правила `INPUT` хоста. +Якщо ви запускаєте OpenClaw у Docker на VPS, пам’ятайте, що опубліковані порти container +(`-p HOST:CONTAINER` або Compose `ports:`) маршрутизуються через ланцюжки переспрямування Docker, +а не лише через правила host `INPUT`. Щоб трафік Docker відповідав політиці вашого firewall, застосовуйте правила в -`DOCKER-USER` (цей ланцюг перевіряється до власних правил дозволу Docker). -У багатьох сучасних дистрибутивах `iptables`/`ip6tables` використовують frontend `iptables-nft` +`DOCKER-USER` (цей ланцюжок обробляється до власних правил allow у 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 @@ -835,11 +842,11 @@ COMMIT ``` Для IPv6 використовуються окремі таблиці. Додайте відповідну політику в `/etc/ufw/after6.rules`, якщо -Docker IPv6 увімкнено. +увімкнено Docker IPv6. -Уникайте жорсткого задання назв інтерфейсів на кшталт `eth0` у фрагментах документації. Назви інтерфейсів -відрізняються між образами VPS (`ens3`, `enp*` тощо), і невідповідність може випадково -обійти ваше правило заборони. +Уникайте жорстко закодованих назв інтерфейсів, як-от `eth0`, у фрагментах документації. Назви інтерфейсів +відрізняються між образами VPS (`ens3`, `enp*` тощо), і невідповідності можуть випадково +призвести до пропуску вашого правила deny. Швидка перевірка після перезавантаження: @@ -855,13 +862,13 @@ nmap -sT -p 1-65535 --open ### 0.4.2) Виявлення mDNS/Bonjour (розкриття інформації) -Gateway транслює свою присутність через mDNS (`_openclaw-gw._tcp` на порту 5353) для виявлення локальними пристроями. У повному режимі це включає записи TXT, які можуть розкривати операційні деталі: +Gateway транслює свою присутність через mDNS (`_openclaw-gw._tcp` на порту 5353) для локального виявлення пристроїв. У повному режимі це містить TXT-записи, які можуть розкривати робочі деталі: -- `cliPath`: повний шлях файлової системи до бінарного файла CLI (розкриває ім’я користувача та місце встановлення) -- `sshPort`: рекламує доступність SSH на хості +- `cliPath`: повний шлях у файловій системі до бінарного файла CLI (розкриває ім’я користувача та місце встановлення) +- `sshPort`: повідомляє про доступність SSH на хості - `displayName`, `lanHost`: інформація про ім’я хоста -**Міркування щодо операційної безпеки:** трансляція інфраструктурних деталей полегшує розвідку для будь-кого в локальній мережі. Навіть «нешкідлива» інформація, як-от шляхи файлової системи та доступність SSH, допомагає зловмисникам картографувати ваше середовище. +**Міркування щодо операційної безпеки:** трансляція деталей інфраструктури полегшує розвідку для будь-кого в локальній мережі. Навіть «нешкідлива» інформація, як-от шляхи файлової системи й доступність SSH, допомагає зловмисникам скласти карту вашого середовища. **Рекомендації:** @@ -875,7 +882,7 @@ Gateway транслює свою присутність через mDNS (`_open } ``` -2. **Повністю вимкніть**, якщо вам не потрібне виявлення локальними пристроями: +2. **Повністю вимкніть**, якщо вам не потрібне локальне виявлення пристроїв: ```json5 { @@ -885,7 +892,7 @@ Gateway транслює свою присутність через mDNS (`_open } ``` -3. **Повний режим** (opt-in): включає `cliPath` + `sshPort` у записи TXT: +3. **Повний режим** (явне ввімкнення): включає `cliPath` + `sshPort` у TXT-записи: ```json5 { @@ -895,19 +902,19 @@ Gateway транслює свою присутність через mDNS (`_open } ``` -4. **Змінна середовища** (альтернатива): установіть `OPENCLAW_DISABLE_BONJOUR=1`, щоб вимкнути mDNS без змін у config. +4. **Змінна середовища** (альтернатива): установіть `OPENCLAW_DISABLE_BONJOUR=1`, щоб вимкнути mDNS без змін конфігурації. -У мінімальному режимі Gateway усе ще транслює достатньо інформації для виявлення пристроїв (`role`, `gatewayPort`, `transport`), але не включає `cliPath` і `sshPort`. Apps, яким потрібна інформація про шлях CLI, можуть отримати її через автентифіковане з’єднання WebSocket. +У мінімальному режимі Gateway усе ще транслює достатньо для виявлення пристроїв (`role`, `gatewayPort`, `transport`), але не включає `cliPath` і `sshPort`. Apps, яким потрібна інформація про шлях CLI, можуть отримати її через автентифіковане підключення WebSocket. -### 0.5) Захистіть WebSocket Gateway (локальний auth) +### 0.5) Захистіть WebSocket Gateway (локальна auth) -Auth Gateway **обов’язковий за замовчуванням**. Якщо не налаштовано коректний шлях auth gateway, -Gateway відмовляє у з’єднаннях WebSocket (безпечна відмова). +Auth Gateway **типово є обов’язковою**. Якщо не налаштовано +жодного дійсного шляху auth gateway, Gateway відмовляє у WebSocket-з’єднаннях (fail‑closed). -Onboarding типово генерує token (навіть для loopback), тому -локальні клієнти мають проходити автентифікацію. +Онбординг типово генерує token (навіть для loopback), тож +локальні клієнти повинні проходити автентифікацію. -Установіть token, щоб **усі** клієнти WS мали проходити автентифікацію: +Установіть token, щоб **усі** WS-клієнти повинні були проходити автентифікацію: ```json5 { @@ -919,74 +926,72 @@ Onboarding типово генерує token (навіть для loopback), т Doctor може згенерувати його для вас: `openclaw doctor --generate-gateway-token`. -Примітка: `gateway.remote.token` / `.password` — це джерела облікових даних клієнта. -Самі по собі вони **не** захищають локальний доступ WS. -Локальні шляхи виклику можуть використовувати `gateway.remote.*` як fallback лише тоді, коли `gateway.auth.*` -не задано. +Примітка: `gateway.remote.token` / `.password` — це джерела облікових даних клієнта. Вони +самі по собі **не** захищають локальний доступ WS. +Локальні шляхи виклику можуть використовувати `gateway.remote.*` як fallback лише коли `gateway.auth.*` +не встановлено. Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через -SecretRef і його не вдається визначити, визначення завершується безпечним блокуванням (без маскування через remote fallback). +SecretRef і не вдалося визначити значення, визначення завершується fail closed (без маскувального fallback на remote). Необов’язково: фіксуйте віддалений TLS через `gateway.remote.tlsFingerprint` під час використання `wss://`. -Нешифрований `ws://` типово дозволено лише для loopback. Для довірених шляхів у приватній мережі +Нешифрований `ws://` типово дозволений лише для loopback. Для довірених шляхів у приватній мережі встановіть `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` у процесі клієнта як аварійний варіант. Локальне pairing пристроїв: -- Pairing пристроїв автоматично схвалюється для прямих локальних підключень loopback, щоб - забезпечити зручність для клієнтів на тому самому хості. -- OpenClaw також має вузький шлях самопідключення для локального backend/container - для довірених helper-потоків зі спільним секретом. -- Підключення через tailnet і LAN, включно з bind через tailnet на тому самому хості, розглядаються як +- Pairing пристрою схвалюється автоматично для прямих локальних підключень через loopback, щоб + клієнти на тому самому хості працювали без зайвих кроків. +- OpenClaw також має вузький шлях самопідключення backend/container-local для + довірених потоків допоміжних засобів зі спільним секретом. +- Підключення через tailnet і LAN, зокрема bind через tailnet на тому самому хості, розглядаються як віддалені для 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"`: auth через пароль (краще задавати через env: `OPENCLAW_GATEWAY_PASSWORD`). +- `gateway.auth.mode: "trusted-proxy"`: довіра до reverse proxy з підтримкою ідентичності для автентифікації користувачів і передавання ідентичності через заголовки (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Контрольний список ротації (token/password): 1. Згенеруйте/установіть новий секрет (`gateway.auth.token` або `OPENCLAW_GATEWAY_PASSWORD`). -2. Перезапустіть Gateway (або перезапустіть застосунок macOS, якщо він керує Gateway). -3. Оновіть усі віддалені клієнти (`gateway.remote.token` / `.password` на машинах, які звертаються до Gateway). -4. Переконайтеся, що зі старими обліковими даними підключитися більше не можна. +2. Перезапустіть Gateway (або перезапустіть macOS app, якщо він контролює Gateway). +3. Оновіть усі віддалені клієнти (`gateway.remote.token` / `.password` на машинах, які викликають Gateway). +4. Перевірте, що зі старими обліковими даними більше неможливо підключитися. ### 0.6) Заголовки ідентичності 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}` -серіалізуються до того, як лімітер зафіксує збій. Тому паралельні невдалі повторні спроби +Для цього асинхронного шляху перевірки ідентичності невдалі спроби для однакової пари `{scope, ip}` +серіалізуються до того, як limiter зафіксує невдачу. Тому одночасні невдалі повторні спроби від одного клієнта Serve можуть одразу заблокувати другу спробу, -а не пройти як дві звичайні невідповідності. +замість того щоб пройти через гонку як дві звичайні невідповідності. +Кінцеві точки HTTP API (наприклад, `/v1/*`, `/tools/invoke` і `/api/channels/*`) +**не** використовують auth через заголовки ідентичності Tailscale. Вони й далі дотримуються +налаштованого для gateway режиму HTTP auth. -Кінцеві точки HTTP API (наприклад `/v1/*`, `/tools/invoke` і `/api/channels/*`) -**не** використовують auth через заголовки ідентичності Tailscale. Вони, як і раніше, дотримуються -налаштованого режиму auth HTTP gateway. +Важлива примітка про межі: -Важлива примітка щодо меж: +- Bearer auth HTTP Gateway фактично надає повний доступ operator або нічого. +- Ставтеся до облікових даних, які можуть викликати `/v1/chat/completions`, `/v1/responses` або `/api/channels/*`, як до секретів operator з повним доступом для цього gateway. +- На HTTP-поверхні, сумісній з OpenAI, bearer auth зі спільним секретом відновлює повні типові області operator (`operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`) і семантику власника для ходів агента; вужчі значення `x-openclaw-scopes` не зменшують цей шлях зі спільним секретом. +- Семантика областей на рівні окремого запиту в HTTP застосовується лише тоді, коли запит надходить із режиму з ідентичністю, як-от auth через trusted proxy або `gateway.auth.mode="none"` на приватному ingress. +- У цих режимах з ідентичністю пропуск `x-openclaw-scopes` призводить до повернення до звичайного типового набору областей operator; надсилайте цей заголовок явно, коли потрібен вужчий набір областей. +- `/tools/invoke` дотримується того самого правила спільного секрету: bearer auth через token/password там теж вважається повним доступом operator, тоді як режими з ідентичністю й далі поважають оголошені області. +- Не діліться цими обліковими даними з недовіреними викликачами; віддавайте перевагу окремим gateway для кожної межі довіри. -- Bearer auth HTTP Gateway фактично дає повний або нульовий операторський доступ. -- Ставтеся до облікових даних, які можуть викликати `/v1/chat/completions`, `/v1/responses` або `/api/channels/*`, як до повноцінних операторських секретів повного доступу для цього gateway. -- На OpenAI-сумісній поверхні HTTP bearer auth зі спільним секретом відновлює повні типові операторські області (`operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`) і семантику власника для ходів agent; вужчі значення `x-openclaw-scopes` не зменшують цей шлях зі спільним секретом. -- Семантика областей на рівні окремого запиту в HTTP застосовується лише тоді, коли запит надходить із режиму, що несе ідентичність, такого як auth через trusted proxy або `gateway.auth.mode="none"` на приватному вході. -- У цих режимах, що несуть ідентичність, якщо `x-openclaw-scopes` не задано, використовується типовий набір операторських областей; надсилайте цей заголовок явно, коли хочете вужчий набір областей. -- `/tools/invoke` дотримується того самого правила спільного секрету: bearer auth через token/password там також вважається повним операторським доступом, тоді як режими з ідентичністю, як і раніше, дотримуються оголошених областей. -- Не діліться цими обліковими даними з недовіреними викликачами; віддавайте перевагу окремим Gateway для кожної межі довіри. - -**Припущення довіри:** auth Serve без token виходить із того, що хост gateway є довіреним. +**Припущення довіри:** auth Serve без token припускає, що хост gateway є довіреним. Не розглядайте це як захист від ворожих процесів на тому самому хості. Якщо на хості gateway може виконуватися недовірений локальний код, вимкніть `gateway.auth.allowTailscale` -і вимагайте явний auth зі спільним секретом через `gateway.auth.mode: "token"` або +і вимагайте явну auth зі спільним секретом через `gateway.auth.mode: "token"` або `"password"`. **Правило безпеки:** не пересилайте ці заголовки через власний reverse proxy. Якщо -ви завершуєте TLS або ставите proxy перед gateway, вимкніть +ви завершуєте TLS або використовуєте proxy перед gateway, вимкніть `gateway.auth.allowTailscale` і використовуйте auth зі спільним секретом (`gateway.auth.mode: "token"` або `"password"`) або [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth) натомість. @@ -994,71 +999,71 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ви Довірені 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/локальних перевірок. - Переконайтеся, що ваш proxy **перезаписує** `x-forwarded-for` і блокує прямий доступ до порту Gateway. -Див. [Tailscale](/uk/gateway/tailscale) і [Огляд Web](/web). +Див. [Tailscale](/uk/gateway/tailscale) і [Огляд web](/web). -### 0.6.1) Керування browser через хост node (рекомендовано) +### 0.6.1) Керування браузером через host node (рекомендовано) -Якщо ваш Gateway є віддаленим, але browser працює на іншій машині, запускайте **хост node** -на машині з browser і дозвольте Gateway проксувати дії browser (див. [Інструмент browser](/uk/tools/browser)). -Сприймайте pairing node як адміністративний доступ. +Якщо ваш Gateway є віддаленим, але браузер працює на іншій машині, запустіть **host node** +на машині з браузером і дозвольте Gateway проксувати дії браузера (див. [Browser tool](/uk/tools/browser)). +Розглядайте pairing node як адміністративний доступ. Рекомендований шаблон: -- Тримайте Gateway і хост node в одній tailnet (Tailscale). -- Виконуйте pairing node свідомо; вимикайте проксі-маршрутизацію browser, якщо вона вам не потрібна. +- Тримайте Gateway і host node в одному tailnet (Tailscale). +- Виконуйте pairing node свідомо; вимикайте проксі-маршрутизацію браузера, якщо вона вам не потрібна. Уникайте: -- Відкриття relay/control-портів у LAN або публічному інтернеті. -- Tailscale Funnel для кінцевих точок керування browser (публічне відкриття). +- Відкриття портів relay/control для LAN або публічного інтернету. +- Tailscale Funnel для кінцевих точок керування браузером (публічний доступ). ### 0.7) Секрети на диску (чутливі дані) Вважайте, що все в `~/.openclaw/` (або `$OPENCLAW_STATE_DIR/`) може містити секрети або приватні дані: - `openclaw.json`: config може містити токени (gateway, віддалений gateway), налаштування провайдерів і allowlist. -- `credentials/**`: облікові дані channel (наприклад, creds WhatsApp), allowlist pairing, застарілі імпорти OAuth. -- `agents//agent/auth-profiles.json`: API-ключі, профілі токенів, OAuth-токени та необов’язкові `keyRef`/`tokenRef`. -- `secrets.json` (необов’язково): вміст секретів у файлі, який використовують провайдери SecretRef типу `file` (`secrets.providers`). -- `agents//agent/auth.json`: застарілий файл сумісності. Статичні записи `api_key` очищаються під час виявлення. -- `agents//sessions/**`: транскрипти сесій (`*.jsonl`) + metadata маршрутизації (`sessions.json`), які можуть містити приватні повідомлення та вивід інструментів. -- пакети bundled Plugin: встановлені plugins (разом із їхніми `node_modules/`). -- `sandboxes/**`: робочі простори sandbox для інструментів; можуть накопичувати копії файлів, які ви читали/записували всередині sandbox. +- `credentials/**`: облікові дані каналів (наприклад, облікові дані WhatsApp), pairing allowlist, імпорт застарілого 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`), які можуть містити приватні повідомлення та вивід інструментів. +- пакети вбудованих plugins: установлені plugins (разом із їхніми `node_modules/`). +- `sandboxes/**`: робочі простори sandbox інструментів; у них можуть накопичуватися копії файлів, які ви читаєте/записуєте в sandbox. -Поради щодо посилення захисту: +Поради щодо посилення: - Тримайте дозволи суворими (`700` для каталогів, `600` для файлів). -- Використовуйте повне шифрування диска на хості gateway. -- Якщо хост є спільним, віддавайте перевагу окремому обліковому запису користувача ОС для Gateway. +- Використовуйте повнодискове шифрування на хості gateway. +- Якщо хост спільний, віддавайте перевагу окремому обліковому запису користувача ОС для Gateway. ### 0.8) Файли `.env` у workspace -OpenClaw завантажує локальні для workspace файли `.env` для agent та інструментів, але ніколи не дозволяє цим файлам непомітно перевизначати керування runtime gateway. +OpenClaw завантажує локальні для workspace файли `.env` для агентів та інструментів, але ніколи не дозволяє цим файлам непомітно перевизначати засоби керування runtime gateway. - Будь-який ключ, що починається з `OPENCLAW_*`, блокується в недовірених файлах `.env` workspace. -- Блокування працює в режимі fail-closed: нова змінна керування runtime, додана в майбутньому релізі, не може бути успадкована з `.env`, що потрапив до репозиторію або був наданий зловмисником; такий ключ ігнорується, а gateway зберігає власне значення. -- Довірені змінні середовища процесу/ОС (власна shell gateway, модуль launchd/systemd, app bundle) як і раніше застосовуються — це обмеження стосується лише завантаження файлів `.env`. +- Блокування працює за принципом fail-closed: нова змінна керування runtime, додана в майбутньому релізі, не може бути успадкована з `.env`, доданого в репозиторій або наданого зловмисником; ключ ігнорується, а gateway зберігає власне значення. +- Довірені змінні середовища процесу/ОС (власна shell gateway, launchd/systemd unit, app bundle) усе ще застосовуються — це обмеження стосується лише завантаження файлів `.env`. -Чому: файли `.env` workspace часто лежать поруч із кодом agent, випадково потрапляють у коміти або записуються інструментами. Блокування всього префікса `OPENCLAW_*` означає, що додавання нового прапорця `OPENCLAW_*` у майбутньому ніколи не призведе до регресії у вигляді тихого успадкування зі стану workspace. +Чому: файли `.env` у workspace часто лежать поруч із кодом агента, випадково потрапляють у коміти або записуються інструментами. Блокування всього префікса `OPENCLAW_*` означає, що додавання нового прапора `OPENCLAW_*` пізніше ніколи не призведе до регресії в тихе успадкування зі стану workspace. ### 0.9) Журнали + транскрипти (редагування + зберігання) -Журнали та транскрипти можуть призводити до витоку чутливої інформації, навіть якщо контроль доступу налаштовано правильно: +Журнали й транскрипти можуть розкривати чутливу інформацію, навіть якщо контроль доступу налаштовано правильно: -- Журнали 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) +Докладніше: [Logging](/uk/gateway/logging) ### 1) DM: pairing за замовчуванням @@ -1090,31 +1095,31 @@ OpenClaw завантажує локальні для workspace файли `.env } ``` -У групових chat відповідайте лише за явної згадки. +У групових чатах відповідайте лише на явну згадку. ### 3) Окремі номери (WhatsApp, Signal, Telegram) -Для channel на основі телефонного номера розгляньте запуск вашого AI на окремому номері телефону, відмінному від особистого: +Для каналів на основі номерів телефону розгляньте запуск вашого AI на окремому номері телефону, відмінному від особистого: - Особистий номер: ваші розмови залишаються приватними -- Номер бота: AI обробляє їх із відповідними межами +- Номер бота: AI обробляє їх із належними межами -### 4) Режим лише читання (через sandbox + інструменти) +### 4) Режим лише для читання (через sandbox + tools) -Ви можете створити профіль лише для читання, поєднавши: +Ви можете побудувати профіль лише для читання, поєднавши: -- `agents.defaults.sandbox.workspaceAccess: "ro"` (або `"none"` для повної відсутності доступу до workspace) -- списки allow/deny інструментів, які блокують `write`, `edit`, `apply_patch`, `exec`, `process` тощо +- `agents.defaults.sandbox.workspaceAccess: "ro"` (або `"none"` без доступу до workspace) +- списки allow/deny для інструментів, які блокують `write`, `edit`, `apply_patch`, `exec`, `process` тощо. -Додаткові варіанти посилення захисту: +Додаткові варіанти посилення: -- `tools.exec.applyPatch.workspaceOnly: true` (типово): гарантує, що `apply_patch` не може записувати/видаляти поза каталогом workspace, навіть коли sandboxing вимкнено. Установлюйте `false` лише тоді, коли ви свідомо хочете, щоб `apply_patch` працював із файлами поза workspace. -- `tools.fs.workspaceOnly: true` (необов’язково): обмежує шляхи `read`/`write`/`edit`/`apply_patch` і шляхи автозавантаження native prompt image каталогом workspace (корисно, якщо ви зараз дозволяєте абсолютні шляхи й хочете один загальний запобіжник). -- Тримайте корені файлової системи вузькими: уникайте широких коренів, як-от ваш домашній каталог, для workspace 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 агентів/workspace sandbox. Широкі корені можуть відкривати доступ інструментам файлової системи до чутливих локальних файлів (наприклад, state/config у `~/.openclaw`). -### 5) Безпечний базовий профіль (скопіювати/вставити) +### 5) Безпечна базова конфігурація (копіювати/вставити) -Одна «безпечна типова» config, яка тримає Gateway приватним, вимагає pairing для DM і уникає ботів, що завжди активні в групах: +Одна «безпечна типова» конфігурація, яка зберігає Gateway приватним, вимагає pairing для DM і уникає ботів у групах, які слухають завжди: ```json5 { @@ -1133,9 +1138,9 @@ OpenClaw завантажує локальні для workspace файли `.env } ``` -Якщо ви хочете також «безпечніше за замовчуванням» виконання інструментів, додайте sandbox + заборону небезпечних інструментів для будь-якого agent, що не є власником (приклад нижче в розділі «Профілі доступу для окремих agent»). +Якщо ви також хочете «безпечніше за замовчуванням» для виконання інструментів, додайте sandbox + deny небезпечних інструментів для будь-якого агента, який не є owner (приклад нижче в розділі «Профілі доступу для окремих агентів»). -Вбудований базовий профіль для ходів agent, керованих chat: відправники, які не є власниками, не можуть використовувати інструменти `cron` або `gateway`. +Вбудована базова конфігурація для ходів агента, керованих чатом: відправники, які не є owner, не можуть використовувати інструменти `cron` або `gateway`. ## Sandboxing (рекомендовано) @@ -1143,59 +1148,59 @@ OpenClaw завантажує локальні для workspace файли `.env Два взаємодоповнювальні підходи: -- **Запуск усього Gateway в Docker** (межа container): [Docker](/uk/install/docker) -- **Sandbox для інструментів** (`agents.defaults.sandbox`, gateway на хості + інструменти, ізольовані sandbox; Docker — типовий backend): [Sandboxing](/uk/gateway/sandboxing) +- **Запускати весь Gateway у Docker** (межа container): [Docker](/uk/install/docker) +- **Sandbox інструментів** (`agents.defaults.sandbox`, gateway на хості + інструменти, ізольовані в sandbox; Docker — типовий backend): [Sandboxing](/uk/gateway/sandboxing) -Примітка: щоб запобігти доступу між agent, тримайте `agents.defaults.sandbox.scope` на `"agent"` (типово) -або `"session"` для суворішої ізоляції кожної сесії. `scope: "shared"` використовує -один спільний container/workspace. +Примітка: щоб запобігти доступу між агентами, залишайте `agents.defaults.sandbox.scope` зі значенням `"agent"` (типово) +або `"session"` для суворішої ізоляції на рівні сесії. `scope: "shared"` використовує +один container/workspace. -Також враховуйте доступ agent до workspace всередині sandbox: +Також розгляньте доступ агента до workspace всередині sandbox: -- `agents.defaults.sandbox.workspaceAccess: "none"` (типово) тримає workspace agent недоступним; інструменти працюють із workspace sandbox у `~/.openclaw/sandboxes` -- `agents.defaults.sandbox.workspaceAccess: "ro"` монтує workspace agent лише для читання в `/agent` (вимикає `write`/`edit`/`apply_patch`) -- `agents.defaults.sandbox.workspaceAccess: "rw"` монтує workspace agent для читання/запису в `/workspace` -- Додаткові `sandbox.docker.binds` перевіряються за нормалізованими й канонізованими шляхами джерела. Трюки з батьківськими symlink і канонічними псевдонімами домашнього каталогу все одно безпечно блокуються, якщо вони визначаються в заблоковані корені, такі як `/etc`, `/var/run` або каталоги облікових даних у домашньому каталозі ОС. +- `agents.defaults.sandbox.workspaceAccess: "none"` (типово) забороняє доступ до workspace агента; інструменти працюють із workspace sandbox у `~/.openclaw/sandboxes` +- `agents.defaults.sandbox.workspaceAccess: "ro"` монтує workspace агента лише для читання в `/agent` (вимикає `write`/`edit`/`apply_patch`) +- `agents.defaults.sandbox.workspaceAccess: "rw"` монтує workspace агента для читання/запису в `/workspace` +- Додаткові `sandbox.docker.binds` перевіряються щодо нормалізованих і канонічних шляхів джерела. Трюки з symlink у батьківських каталогах і канонічні псевдоніми домашнього каталогу все одно завершуються fail closed, якщо вони вказують на заблоковані корені, як-от `/etc`, `/var/run` або каталоги облікових даних у домашньому каталозі ОС. -Важливо: `tools.elevated` — це глобальний аварійний вихід із базового профілю, який запускає exec поза sandbox. Ефективний хост за замовчуванням — `gateway`, або `node`, коли ціль exec налаштовано на `node`. Тримайте `tools.elevated.allowFrom` вузьким і не вмикайте його для сторонніх. Ви також можете додатково обмежити elevated для окремих agent через `agents.list[].tools.elevated`. Див. [Режим Elevated](/uk/tools/elevated). +Важливо: `tools.elevated` — це глобальний аварійний вихід із базового режиму, який запускає exec поза sandbox. Ефективний host типово дорівнює `gateway`, або `node`, коли ціль exec налаштована як `node`. Тримайте `tools.elevated.allowFrom` суворо обмеженим і не вмикайте його для сторонніх людей. Додатково ви можете обмежити elevated для окремого агента через `agents.list[].tools.elevated`. Див. [Elevated Mode](/uk/tools/elevated). -### Запобіжник делегування субагентів +### Запобіжник делегування підагентів -Якщо ви дозволяєте інструменти сесій, розглядайте делеговані запуски субагентів як ще одне рішення щодо меж: +Якщо ви дозволяєте інструменти сесій, розглядайте делеговані запуски підагентів як ще одне рішення щодо межі: -- Забороняйте `sessions_spawn`, якщо agent справді не потребує делегування. -- Тримайте `agents.defaults.subagents.allowAgents` і будь-які перевизначення `agents.list[].subagents.allowAgents` для окремих agent обмеженими до відомо безпечних цільових agent. -- Для будь-якого процесу, який має залишатися в sandbox, викликайте `sessions_spawn` із `sandbox: "require"` (типове значення — `inherit`). -- `sandbox: "require"` негайно завершується помилкою, якщо цільовий дочірній runtime не працює в sandbox. +- Забороняйте `sessions_spawn`, якщо агенту справді не потрібне делегування. +- Тримайте `agents.defaults.subagents.allowAgents` і всі перевизначення `agents.list[].subagents.allowAgents` для окремих агентів обмеженими відомими безпечними цільовими агентами. +- Для будь-якого workflow, який має залишатися в sandbox, викликайте `sessions_spawn` із `sandbox: "require"` (типове значення — `inherit`). +- `sandbox: "require"` швидко завершується помилкою, якщо цільове дочірнє runtime не працює в sandbox. -## Ризики керування browser +## Ризики керування браузером -Увімкнення керування browser дає моделі можливість керувати реальним browser. -Якщо цей профіль browser уже містить активні сеанси входу, модель може -отримати доступ до цих облікових записів і даних. Сприймайте профілі browser як **чутливий стан**: +Увімкнення керування браузером дає моделі можливість керувати реальним браузером. +Якщо цей профіль браузера вже містить активні сесії входу, модель може +отримати доступ до цих акаунтів і даних. Розглядайте профілі браузера як **чутливий стан**: -- Віддавайте перевагу окремому профілю для agent (типовий профіль `openclaw`). -- Не спрямовуйте agent на ваш особистий щоденний профіль. -- Тримайте керування browser на хості вимкненим для agent у sandbox, якщо ви їм не довіряєте. -- Автономний loopback API керування browser приймає лише auth зі спільним секретом +- Віддавайте перевагу окремому профілю для агента (типовий профіль `openclaw`). +- Не спрямовуйте агента на ваш особистий щоденний профіль браузера. +- Тримайте керування браузером на хості вимкненим для агентів у sandbox, якщо ви їм не довіряєте. +- Автономний loopback API керування браузером приймає лише auth зі спільним секретом (bearer auth через token gateway або пароль gateway). Він не використовує заголовки ідентичності trusted-proxy або Tailscale Serve. -- Сприймайте завантаження browser як недовірений вхід; віддавайте перевагу ізольованому каталогу завантажень. -- Якщо можливо, вимикайте синхронізацію browser/password managers у профілі agent (це зменшує радіус ураження). -- Для віддалених gateway вважайте, що «керування browser» еквівалентне «операторському доступу» до всього, до чого може дістатися цей профіль. -- Тримайте Gateway і хости node лише в tailnet; уникайте відкриття портів керування browser у LAN або публічному інтернеті. -- Вимикайте проксі-маршрутизацію browser, якщо вона вам не потрібна (`gateway.nodes.browser.mode="off"`). -- Режим Chrome MCP existing-session **не є** «безпечнішим»; він може діяти від вашого імені в усьому, до чого має доступ профіль Chrome цього хоста. +- Розглядайте завантаження браузера як недовірений вхідний вміст; віддавайте перевагу ізольованому каталогу завантажень. +- Якщо можливо, вимикайте синхронізацію браузера/менеджери паролів у профілі агента (це зменшує радіус ураження). +- Для віддалених gateway припускайте, що «керування браузером» еквівалентне «доступу operator» до всього, чого може досягти цей профіль. +- Тримайте Gateway і host node лише в межах tailnet; не відкривайте порти керування браузером для LAN або публічного інтернету. +- Вимикайте проксі-маршрутизацію браузера, коли вона не потрібна (`gateway.nodes.browser.mode="off"`). +- Режим Chrome MCP з наявною сесією **не** є «безпечнішим»; він може діяти від вашого імені всюди, куди має доступ цей профіль Chrome на хості. -### Політика SSRF browser (сувора за замовчуванням) +### Політика SSRF браузера (сувора за замовчуванням) -Політика навігації browser в OpenClaw є суворою за замовчуванням: приватні/внутрішні адреси залишаються заблокованими, якщо ви явно не виконали opt-in. +Політика навігації браузера в OpenClaw типово сувора: приватні/внутрішні цілі залишаються заблокованими, якщо ви явно не дозволите їх. -- Типово: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` не задано, тому навігація browser і далі блокує приватні/внутрішні/спеціальні адреси призначення. +- Типово: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` не встановлено, тому навігація браузера залишає приватні/внутрішні/special-use цілі заблокованими. - Застарілий псевдонім: `browser.ssrfPolicy.allowPrivateNetwork` усе ще приймається для сумісності. -- Режим opt-in: установіть `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`, щоб дозволити приватні/внутрішні/спеціальні адреси призначення. -- У суворому режимі використовуйте `hostnameAllowlist` (шаблони на кшталт `*.example.com`) і `allowedHostnames` (точні винятки для хостів, включно із заблокованими іменами, такими як `localhost`) для явних винятків. -- Навігація перевіряється до запиту і повторно перевіряється в режимі best-effort за фінальним URL `http(s)` після навігації, щоб зменшити можливості обходу через redirect. +- Режим з явним дозволом: установіть `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`, щоб дозволити приватні/внутрішні/special-use цілі. +- У суворому режимі використовуйте `hostnameAllowlist` (шаблони на кшталт `*.example.com`) і `allowedHostnames` (точні винятки для хостів, зокрема заблоковані імена, як-от `localhost`) для явних винятків. +- Навігація перевіряється перед запитом і best-effort повторно перевіряється на фінальному URL `http(s)` після навігації, щоб зменшити переходи через редиректи. Приклад суворої політики: @@ -1211,17 +1216,17 @@ OpenClaw завантажує локальні для workspace файли `.env } ``` -## Профілі доступу для окремих agent (multi-agent) +## Профілі доступу для окремих агентів (multi-agent) -Для маршрутизації multi-agent кожен agent може мати власні sandbox + політику інструментів: -використовуйте це, щоб надавати **повний доступ**, **лише читання** або **без доступу** для кожного agent. -Повні відомості та правила пріоритетів див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). +За маршрутизації multi-agent кожен агент може мати власні sandbox і політику інструментів: +використовуйте це, щоб надавати **повний доступ**, **лише читання** або **без доступу** для кожного агента. +Повні подробиці та правила пріоритетів див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). -Типові сценарії використання: +Поширені сценарії використання: -- Персональний agent: повний доступ, без sandbox -- Сімейний/робочий agent: у sandbox + інструменти лише для читання -- Публічний agent: у sandbox + без інструментів файлової системи/оболонки +- Особистий агент: повний доступ, без sandbox +- Сімейний/робочий агент: sandbox + інструменти лише для читання +- Публічний агент: sandbox + без інструментів файлової системи/shell ### Приклад: повний доступ (без sandbox) @@ -1263,7 +1268,7 @@ OpenClaw завантажує локальні для workspace файли `.env } ``` -### Приклад: без доступу до файлової системи/оболонки (дозволено messaging провайдера) +### Приклад: без доступу до файлової системи/shell (дозволено messaging провайдера) ```json5 { @@ -1278,7 +1283,7 @@ OpenClaw завантажує локальні для workspace файли `.env workspaceAccess: "none", }, // Інструменти сесій можуть розкривати чутливі дані з транскриптів. Типово OpenClaw обмежує ці інструменти - // поточною сесією + сесіями запущених субагентів, але за потреби ви можете затиснути межі ще сильніше. + // поточною сесією + породженими сесіями підагентів, але за потреби ви можете обмежити ще сильніше. // Див. `tools.sessions.visibility` у довіднику конфігурації. tools: { sessions: { visibility: "tree" }, // self | tree | agent | all @@ -1316,53 +1321,52 @@ OpenClaw завантажує локальні для workspace файли `.env ## Що сказати вашому AI -Додайте рекомендації з безпеки до системного prompt вашого agent: +Додайте рекомендації з безпеки до system prompt вашого агента: ``` -## Security Rules -- Ніколи не діліться списками каталогів або шляхами до файлів зі сторонніми -- Ніколи не розкривайте API-ключі, облікові дані або інфраструктурні деталі -- Підтверджуйте запити на зміну config системи у власника -- Якщо є сумнів, спитайте перед дією -- Тримайте приватні дані приватними, якщо немає явної авторизації +## Правила безпеки +- Ніколи не показуй незнайомцям списки каталогів або шляхи до файлів +- Ніколи не розкривай API-ключі, облікові дані або деталі інфраструктури +- Підтверджуй із власником запити, що змінюють системну конфігурацію +- Якщо є сумніви, запитай перед виконанням дії +- Зберігай приватні дані приватними, якщо немає явної авторизації ``` ## Реагування на інциденти Якщо ваш AI зробив щось погане: -### Стримування +### Локалізуйте -1. **Зупиніть його:** зупиніть застосунок macOS (якщо він керує 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"` / вимагайте згадки й приберіть записи `"*"`, що дозволяють усіх, якщо вони були. -### Ротація (вважайте, що компрометація сталася, якщо секрети витекли) +### Ротуйте (припускайте компрометацію, якщо секрети витекли) -1. Замініть auth Gateway (`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`) і перезапустіть. -2. Замініть секрети віддалених клієнтів (`gateway.remote.token` / `.password`) на всіх машинах, які можуть викликати Gateway. -3. Замініть облікові дані провайдерів/API (creds WhatsApp, токени Slack/Discord, ключі моделі/API в `auth-profiles.json` і значення зашифрованих payload секретів, якщо вони використовуються). +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: `/tmp/openclaw/openclaw-YYYY-MM-DD.log` (або `logging.file`). 2. Перегляньте відповідні транскрипти: `~/.openclaw/agents//sessions/*.jsonl`. -3. Перегляньте останні зміни config (усе, що могло розширити доступ: `gateway.bind`, `gateway.auth`, політики DM/груп, `tools.elevated`, зміни Plugin). +3. Перегляньте нещодавні зміни конфігурації (усе, що могло розширити доступ: `gateway.bind`, `gateway.auth`, політики dm/group, `tools.elevated`, зміни plugin). 4. Повторно запустіть `openclaw security audit --deep` і переконайтеся, що критичні знахідки усунено. ### Зберіть дані для звіту -- Часова позначка, ОС хоста gateway + версія OpenClaw -- Транскрипти сесій + короткий фрагмент журналу (після редагування) -- Що надіслав атакувальник + що зробив agent -- Чи був Gateway відкритий за межі loopback (LAN/Tailscale Funnel/Serve) +- Часову мітку, ОС хоста gateway + версію OpenClaw +- Транскрипти сесій + короткий tail журналу (після редагування) +- Що саме надіслав зловмисник + що зробив агент +- Чи був Gateway доступний не лише через loopback (LAN/Tailscale Funnel/Serve) ## Сканування секретів (detect-secrets) CI запускає pre-commit hook `detect-secrets` у job `secrets`. Push у `main` завжди запускають сканування всіх файлів. Pull request використовують -швидкий шлях для змінених файлів, якщо доступний базовий commit, і переходять до -сканування всіх файлів у протилежному разі. Якщо перевірка не проходить, з’явилися нові кандидати, яких ще немає в baseline. +швидкий шлях для змінених файлів, коли доступний базовий коміт, і в іншому разі повертаються до сканування всіх файлів. Якщо перевірка не проходить, це означає, що є нові кандидати, яких ще немає в baseline. ### Якщо CI не проходить @@ -1374,26 +1378,26 @@ Push у `main` завжди запускають сканування всіх 2. Зрозумійте інструменти: - `detect-secrets` у pre-commit запускає `detect-secrets-hook` з - baseline та excludes цього репозиторію. - - `detect-secrets audit` відкриває інтерактивну перевірку, щоб позначити кожен елемент baseline - як справжній або хибнопозитивний. -3. Для справжніх секретів: замініть/видаліть їх, а потім повторно запустіть сканування, щоб оновити baseline. + baseline і excludes цього репозиторію. + - `detect-secrets audit` відкриває інтерактивний перегляд, щоб позначити кожен елемент baseline + як реальний або як хибнопозитивний. +3. Для реальних секретів: ротуйте/видаліть їх, а потім повторно запустіть сканування, щоб оновити baseline. 4. Для хибнопозитивних результатів: запустіть інтерактивний аудит і позначте їх як хибні: ```bash detect-secrets audit .secrets.baseline ``` -5. Якщо вам потрібні нові excludes, додайте їх до `.detect-secrets.cfg` і заново згенеруйте - baseline з відповідними прапорцями `--exclude-files` / `--exclude-lines` (файл config - є лише довідковим; detect-secrets не читає його автоматично). +5. Якщо вам потрібні нові excludes, додайте їх до `.detect-secrets.cfg` і повторно згенеруйте + baseline з відповідними прапорами `--exclude-files` / `--exclude-lines` (файл + config є лише довідковим; detect-secrets не читає його автоматично). -Зафіксуйте оновлений `.secrets.baseline`, щойно він відображатиме потрібний стан. +Закомітьте оновлений `.secrets.baseline`, щойно він відображатиме задуманий стан. ## Повідомлення про проблеми безпеки -Знайшли вразливість в OpenClaw? Будь ласка, повідомте відповідально: +Знайшли вразливість в OpenClaw? Будь ласка, повідомляйте відповідально: 1. Email: [security@openclaw.ai](mailto:security@openclaw.ai) -2. Не публікуйте її публічно, доки проблему не буде виправлено +2. Не публікуйте публічно, доки проблему не буде виправлено 3. Ми вкажемо вас у подяках (якщо ви не віддаєте перевагу анонімності) diff --git a/docs/uk/providers/openai.md b/docs/uk/providers/openai.md index 548eafbef..c5e5a02dc 100644 --- a/docs/uk/providers/openai.md +++ b/docs/uk/providers/openai.md @@ -1,41 +1,41 @@ --- read_when: - Ви хочете використовувати моделі OpenAI в OpenClaw - - Ви хочете автентифікацію через підписку Codex замість API-ключів - - Вам потрібна суворіша поведінка виконання агента GPT-5 + - Ви хочете використовувати автентифікацію за підпискою Codex замість API-ключів + - Вам потрібні суворіші правила виконання агента GPT-5 summary: Використовуйте OpenAI через API-ключі або підписку Codex в OpenClaw title: OpenAI x-i18n: - generated_at: "2026-04-22T13:02:14Z" + generated_at: "2026-04-22T22:50:20Z" model: gpt-5.4 provider: openai - source_hash: 7b0035cb879563a169294269e2fb39884194ec219373bc6e3edb1a8b47660b29 + source_hash: 1ef9aaacd585acd098163468880761270936a05bbf79dd54b4f4d45068eeeaf1 source_path: providers/openai.md workflow: 15 --- # OpenAI -OpenAI надає API для розробників для моделей GPT. OpenClaw підтримує два шляхи автентифікації: +OpenAI надає API для розробників для моделей GPT. OpenClaw підтримує два способи автентифікації: -- **API key** — прямий доступ до OpenAI Platform з тарифікацією за використання (`openai/*` моделі) +- **API key** — прямий доступ до OpenAI Platform з оплатою за використання (`openai/*` моделі) - **Codex subscription** — вхід через ChatGPT/Codex з доступом за підпискою (`openai-codex/*` моделі) -OpenAI явно підтримує використання OAuth-підписки у зовнішніх інструментах і робочих процесах, таких як OpenClaw. +OpenAI прямо підтримує використання OAuth за підпискою у зовнішніх інструментах і робочих процесах, таких як OpenClaw. ## Початок роботи -Оберіть бажаний спосіб автентифікації та виконайте кроки налаштування. +Виберіть бажаний спосіб автентифікації та виконайте кроки налаштування. - **Найкраще підходить для:** прямого доступу до API та тарифікації за використання. + **Найкраще підходить для:** прямого доступу до API та оплати за використання. - Створіть або скопіюйте API key з [панелі керування OpenAI Platform](https://platform.openai.com/api-keys). + Створіть або скопіюйте API key на [панелі OpenAI Platform](https://platform.openai.com/api-keys). - + ```bash openclaw onboard --auth-choice openai-api-key ``` @@ -46,7 +46,7 @@ OpenAI явно підтримує використання OAuth-підписк openclaw onboard --openai-api-key "$OPENAI_API_KEY" ``` - + ```bash openclaw models list --provider openai ``` @@ -55,13 +55,13 @@ OpenAI явно підтримує використання OAuth-підписк ### Підсумок маршрутів - | Посилання на модель | Маршрут | Автентифікація | + | Model ref | Route | Auth | |-----------|-------|------| | `openai/gpt-5.4` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | | `openai/gpt-5.4-pro` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | - Вхід через ChatGPT/Codex спрямовується через `openai-codex/*`, а не `openai/*`. + Вхід через ChatGPT/Codex маршрутизується через `openai-codex/*`, а не `openai/*`. ### Приклад конфігурації @@ -74,7 +74,7 @@ OpenAI явно підтримує використання OAuth-підписк ``` - OpenClaw **не** надає `openai/gpt-5.3-codex-spark` у прямому шляху API. Реальні запити до OpenAI API відхиляють цю модель. Spark доступний лише в Codex. + OpenClaw **не** надає `openai/gpt-5.3-codex-spark` на шляху прямого API. Живі запити до OpenAI API відхиляють цю модель. Spark доступний лише в Codex. @@ -99,7 +99,7 @@ OpenAI явно підтримує використання OAuth-підписк openclaw config set agents.defaults.model.primary openai-codex/gpt-5.4 ``` - + ```bash openclaw models list --provider openai-codex ``` @@ -108,13 +108,13 @@ OpenAI явно підтримує використання OAuth-підписк ### Підсумок маршрутів - | Посилання на модель | Маршрут | Автентифікація | + | Model ref | Route | Auth | |-----------|-------|------| - | `openai-codex/gpt-5.4` | ChatGPT/Codex OAuth | Вхід через Codex | - | `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Вхід через Codex (залежить від entitlement) | + | `openai-codex/gpt-5.4` | OAuth ChatGPT/Codex | Вхід через Codex | + | `openai-codex/gpt-5.3-codex-spark` | OAuth ChatGPT/Codex | Вхід через Codex (залежить від entitlement) | - Цей маршрут навмисно відокремлений від `openai/gpt-5.4`. Використовуйте `openai/*` з API key для прямого доступу до Platform, а `openai-codex/*` — для доступу через підписку Codex. + Цей маршрут навмисно відокремлений від `openai/gpt-5.4`. Використовуйте `openai/*` з API key для прямого доступу до Platform, а `openai-codex/*` — для доступу за підпискою Codex. ### Приклад конфігурації @@ -126,7 +126,7 @@ OpenAI явно підтримує використання OAuth-підписк ``` - Якщо початкове налаштування повторно використовує наявний вхід Codex CLI, цими обліковими даними надалі керує Codex CLI. Після завершення строку дії OpenClaw спочатку повторно зчитує зовнішнє джерело Codex і записує оновлені облікові дані назад у сховище Codex. + Якщо онбординг повторно використовує наявний вхід Codex CLI, цими обліковими даними й надалі керує Codex CLI. Після завершення строку дії OpenClaw спочатку повторно зчитує зовнішнє джерело Codex, а потім записує оновлені облікові дані назад у сховище Codex. ### Обмеження вікна контексту @@ -135,10 +135,10 @@ OpenAI явно підтримує використання OAuth-підписк Для `openai-codex/gpt-5.4`: - - Рідний `contextWindow`: `1050000` + - Нативний `contextWindow`: `1050000` - Типове обмеження `contextTokens` під час виконання: `272000` - Менше типове обмеження на практиці забезпечує кращі характеристики затримки й якості. Перевизначте його за допомогою `contextTokens`: + Менше типове обмеження на практиці дає кращі характеристики затримки й якості. Перевизначте його за допомогою `contextTokens`: ```json5 { @@ -153,7 +153,7 @@ OpenAI явно підтримує використання OAuth-підписк ``` - Використовуйте `contextWindow`, щоб оголосити рідні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту під час виконання. + Використовуйте `contextWindow`, щоб оголосити нативні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту під час виконання. @@ -163,9 +163,9 @@ OpenAI явно підтримує використання OAuth-підписк Вбудований Plugin `openai` реєструє генерацію зображень через інструмент `image_generate`. -| Можливість | Значення | -| ------------------------- | ------------------------------------ | -| Модель за замовчуванням | `openai/gpt-image-2` | +| Можливість | Значення | +| ------------------------- | ---------------------------------- | +| Модель за замовчуванням | `openai/gpt-image-2` | | Макс. кількість зображень на запит | 4 | | Режим редагування | Увімкнено (до 5 еталонних зображень) | | Перевизначення розміру | Підтримується, включно з розмірами 2K/4K | @@ -182,10 +182,10 @@ OpenAI явно підтримує використання OAuth-підписк ``` -Див. [Генерація зображень](/uk/tools/image-generation), щоб дізнатися про спільні параметри інструмента, вибір провайдера та поведінку failover. +Див. [Генерація зображень](/uk/tools/image-generation), щоб ознайомитися зі спільними параметрами інструмента, вибором провайдера та поведінкою failover. -`gpt-image-2` є типовою моделлю як для генерації зображень з тексту в OpenAI, так і для редагування зображень. `gpt-image-1` і далі можна використовувати як явне перевизначення моделі, але нові робочі процеси OpenAI для зображень мають використовувати `openai/gpt-image-2`. +`gpt-image-2` є моделлю за замовчуванням як для генерації зображень з тексту в OpenAI, так і для редагування зображень. `gpt-image-1` і далі можна використовувати як явне перевизначення моделі, але нові робочі процеси OpenAI для зображень мають використовувати `openai/gpt-image-2`. Генерація: @@ -196,7 +196,7 @@ OpenAI явно підтримує використання OAuth-підписк Редагування: ``` -/tool image_generate model=openai/gpt-image-2 prompt="Збережи форму об’єкта, зміни матеріал на прозоре скло" image=/path/to/reference.png size=1024x1536 +/tool image_generate model=openai/gpt-image-2 prompt="Збережи форму об’єкта, зміни матеріал на напівпрозоре скло" image=/path/to/reference.png size=1024x1536 ``` ## Генерація відео @@ -204,10 +204,10 @@ OpenAI явно підтримує використання OAuth-підписк Вбудований Plugin `openai` реєструє генерацію відео через інструмент `video_generate`. | Можливість | Значення | -| ---------------- | -------------------------------------------------------------------------------- | +| --------------- | ------------------------------------------------------------------------------- | | Модель за замовчуванням | `openai/sora-2` | -| Режими | Текст у відео, зображення у відео, редагування одного відео | -| Еталонні вхідні дані | 1 зображення або 1 відео | +| Режими | Текст у відео, зображення у відео, редагування одного відео | +| Еталонні вхідні дані | 1 зображення або 1 відео | | Перевизначення розміру | Підтримується | | Інші перевизначення | `aspectRatio`, `resolution`, `audio`, `watermark` ігноруються з попередженням інструмента | @@ -222,30 +222,32 @@ OpenAI явно підтримує використання OAuth-підписк ``` -Див. [Генерація відео](/uk/tools/video-generation), щоб дізнатися про спільні параметри інструмента, вибір провайдера та поведінку failover. +Див. [Генерація відео](/uk/tools/video-generation), щоб ознайомитися зі спільними параметрами інструмента, вибором провайдера та поведінкою failover. ## Внесок у prompt GPT-5 -OpenClaw додає специфічний для OpenAI внесок у prompt GPT-5 для запусків сімейства GPT-5 через `openai/*` і `openai-codex/*`. Він міститься у вбудованому Plugin OpenAI, застосовується до ідентифікаторів моделей, таких як `gpt-5`, `gpt-5.2`, `gpt-5.4` і `gpt-5.4-mini`, і не застосовується до старіших моделей GPT-4.x. +OpenClaw додає спільний внесок у prompt GPT-5 для запусків сімейства GPT-5 у різних провайдерів. Він застосовується за ідентифікатором моделі, тому `openai/gpt-5.4`, `openai-codex/gpt-5.4`, `openrouter/openai/gpt-5.4`, `opencode/gpt-5.4` та інші сумісні посилання GPT-5 отримують однакове накладання. Старіші моделі GPT-4.x — ні. -Вбудований провайдер нативного harness Codex (`codex/*`) застосовує ту саму поведінку GPT-5 і накладення Heartbeat через інструкції розробника app-server Codex, тому сесії `codex/gpt-5.x` зберігають ту саму наполегливість у доведенні справ до кінця та проактивні вказівки Heartbeat, навіть попри те, що рештою prompt harness керує Codex. +Вбудований рідний провайдер harness Codex (`codex/*`) використовує таку саму поведінку GPT-5 і накладання Heartbeat через інструкції розробника Codex app-server, тому сесії `codex/gpt-5.x` зберігають ту саму послідовність виконання і проактивні вказівки Heartbeat, хоча рештою prompt harness керує Codex. -Внесок GPT-5 додає позначений контракт поведінки для збереження персонажу, безпеки виконання, дисципліни використання інструментів, форми виводу, перевірок завершення та верифікації. Поведінка відповіді та тихих повідомлень, специфічна для каналу, залишається у спільному системному prompt OpenClaw і політиці вихідної доставки. Вказівки GPT-5 завжди увімкнені для відповідних моделей. Рівень дружнього стилю взаємодії є окремим і налаштовуваним. +Внесок GPT-5 додає позначений контракт поведінки для збереження персони, безпеки виконання, дисципліни інструментів, форми виводу, перевірок завершення та верифікації. Поведінка відповідей і тихих повідомлень, специфічна для каналів, залишається у спільному системному prompt OpenClaw і політиці вихідної доставки. Вказівки GPT-5 завжди увімкнені для відповідних моделей. Рівень дружнього стилю взаємодії є окремим і налаштовуваним. -| Значення | Ефект | -| --------------------- | -------------------------------------------- | -| `"friendly"` (типово) | Увімкнути рівень дружнього стилю взаємодії | -| `"on"` | Псевдонім для `"friendly"` | -| `"off"` | Вимкнути лише рівень дружнього стилю | +| Значення | Ефект | +| -------------------- | ------------------------------------------ | +| `"friendly"` (типово) | Увімкнути рівень дружнього стилю взаємодії | +| `"on"` | Псевдонім для `"friendly"` | +| `"off"` | Вимкнути лише рівень дружнього стилю | ```json5 { - plugins: { - entries: { - openai: { config: { personality: "friendly" } }, + agents: { + defaults: { + promptOverlays: { + gpt5: { personality: "friendly" }, + }, }, }, } @@ -253,29 +255,33 @@ OpenClaw додає специфічний для OpenAI внесок у prompt ```bash - openclaw config set plugins.entries.openai.config.personality off + openclaw config set agents.defaults.promptOverlays.gpt5.personality off ``` -Під час виконання значення нечутливі до регістру, тож і `"Off"`, і `"off"` вимикають рівень дружнього стилю. +Під час виконання значення нечутливі до регістру, тому і `"Off"`, і `"off"` вимикають рівень дружнього стилю. + +Застаріле `plugins.entries.openai.config.personality` і далі зчитується як сумісний запасний варіант, коли спільне налаштування `agents.defaults.promptOverlays.gpt5.personality` не задано. + + ## Голос і мовлення Вбудований Plugin `openai` реєструє синтез мовлення для поверхні `messages.tts`. - | Налаштування | Шлях конфігурації | Типово | + | Налаштування | Шлях конфігурації | Значення за замовчуванням | |---------|------------|---------| | Модель | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` | | Голос | `messages.tts.providers.openai.voice` | `coral` | | Швидкість | `messages.tts.providers.openai.speed` | (не задано) | | Інструкції | `messages.tts.providers.openai.instructions` | (не задано, лише `gpt-4o-mini-tts`) | | Формат | `messages.tts.providers.openai.responseFormat` | `opus` для голосових нотаток, `mp3` для файлів | - | API key | `messages.tts.providers.openai.apiKey` | З резервним поверненням до `OPENAI_API_KEY` | + | API key | `messages.tts.providers.openai.apiKey` | Використовується `OPENAI_API_KEY` як запасний варіант | | Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | Доступні моделі: `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`. Доступні голоси: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `juniper`, `marin`, `onyx`, `nova`, `sage`, `shimmer`, `verse`. @@ -293,23 +299,23 @@ OpenClaw додає специфічний для OpenAI внесок у prompt ``` - Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити базовий URL TTS без впливу на кінцеву точку chat API. + Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити Base URL для TTS без впливу на endpoint chat API. - - Вбудований Plugin `openai` реєструє транскрипцію в реальному часі для Plugin Voice Call. + + Вбудований Plugin `openai` реєструє транскрибування в реальному часі для Plugin Voice Call. - | Налаштування | Шлях конфігурації | Типово | + | Налаштування | Шлях конфігурації | Значення за замовчуванням | |---------|------------|---------| | Модель | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` | | Тривалість тиші | `...openai.silenceDurationMs` | `800` | | Поріг VAD | `...openai.vadThreshold` | `0.5` | - | API key | `...openai.apiKey` | З резервним поверненням до `OPENAI_API_KEY` | + | API key | `...openai.apiKey` | Використовується `OPENAI_API_KEY` як запасний варіант | - Використовує WebSocket-з’єднання з `wss://api.openai.com/v1/realtime` з аудіо G.711 u-law. + Використовує з’єднання WebSocket з `wss://api.openai.com/v1/realtime` з аудіо G.711 u-law. @@ -317,17 +323,17 @@ OpenClaw додає специфічний для OpenAI внесок у prompt Вбудований Plugin `openai` реєструє голос у реальному часі для Plugin Voice Call. - | Налаштування | Шлях конфігурації | Типово | + | Налаштування | Шлях конфігурації | Значення за замовчуванням | |---------|------------|---------| | Модель | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime` | | Голос | `...openai.voice` | `alloy` | | Temperature | `...openai.temperature` | `0.8` | | Поріг VAD | `...openai.vadThreshold` | `0.5` | | Тривалість тиші | `...openai.silenceDurationMs` | `500` | - | API key | `...openai.apiKey` | З резервним поверненням до `OPENAI_API_KEY` | + | API key | `...openai.apiKey` | Використовується `OPENAI_API_KEY` як запасний варіант | - Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment`. Підтримує двобічний виклик інструментів. Використовує формат аудіо G.711 u-law. + Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment`. Підтримує двонапрямлений виклик інструментів. Використовує аудіоформат G.711 u-law. @@ -337,17 +343,17 @@ OpenClaw додає специфічний для OpenAI внесок у prompt - OpenClaw використовує WebSocket-first із резервним переходом на SSE (`"auto"`) як для `openai/*`, так і для `openai-codex/*`. + OpenClaw використовує WebSocket-first із запасним переходом на SSE (`"auto"`) і для `openai/*`, і для `openai-codex/*`. У режимі `"auto"` OpenClaw: - Повторює одну ранню помилку WebSocket перед переходом на SSE - - Після помилки позначає WebSocket як деградований приблизно на 60 секунд і використовує SSE під час охолодження - - Додає стабільні заголовки ідентичності сесії та ходу для повторних спроб і повторних підключень - - Нормалізує лічильники використання (`input_tokens` / `prompt_tokens`) між варіантами транспорту + - Після збою позначає WebSocket як деградований приблизно на 60 секунд і використовує SSE під час охолодження + - Додає стабільні заголовки ідентичності сесії та ходу для повторних спроб і перепідключень + - Нормалізує лічильники використання (`input_tokens` / `prompt_tokens`) у різних варіантах транспорту | Значення | Поведінка | |-------|----------| - | `"auto"` (типово) | WebSocket first, резервний перехід на SSE | + | `"auto"` (типово) | Спочатку WebSocket, запасний перехід на SSE | | `"sse"` | Примусово лише SSE | | `"websocket"` | Примусово лише WebSocket | @@ -371,11 +377,11 @@ OpenClaw додає специфічний для OpenAI внесок у prompt - - OpenClaw типово вмикає розігрів WebSocket для `openai/*`, щоб зменшити затримку першого ходу. + + OpenClaw типово вмикає прогрів WebSocket для `openai/*`, щоб зменшити затримку першого ходу. ```json5 - // Вимкнути розігрів + // Вимкнути прогрів { agents: { defaults: { @@ -413,7 +419,7 @@ OpenClaw додає специфічний для OpenAI внесок у prompt ``` - Перевизначення сесії мають пріоритет над конфігурацією. Очищення перевизначення сесії в UI Sessions повертає сесію до налаштованого типового значення. + Перевизначення сесії мають пріоритет над конфігурацією. Очищення перевизначення сесії в UI Sessions повертає сесію до налаштованого значення за замовчуванням. @@ -437,7 +443,7 @@ OpenClaw додає специфічний для OpenAI внесок у prompt Підтримувані значення: `auto`, `default`, `flex`, `priority`. - `serviceTier` передається лише до нативних кінцевих точок OpenAI (`api.openai.com`) і нативних кінцевих точок Codex (`chatgpt.com/backend-api`). Якщо ви маршрутизуєте будь-якого з цих провайдерів через проксі, OpenClaw залишає `service_tier` без змін. + `serviceTier` передається лише до нативних endpoint OpenAI (`api.openai.com`) і нативних endpoint Codex (`chatgpt.com/backend-api`). Якщо ви спрямовуєте будь-якого з цих провайдерів через proxy, OpenClaw залишає `service_tier` без змін. @@ -445,13 +451,13 @@ OpenClaw додає специфічний для OpenAI внесок у prompt Для прямих моделей OpenAI Responses (`openai/*` на `api.openai.com`) OpenClaw автоматично вмикає server-side Compaction: - - Примусово встановлює `store: true` (якщо лише сумісність моделі не задає `supportsStore: false`) - - Впроваджує `context_management: [{ type: "compaction", compact_threshold: ... }]` - - Типове значення `compact_threshold`: 70% від `contextWindow` (або `80000`, якщо воно недоступне) + - Примусово встановлює `store: true` (якщо тільки сумісність моделі не задає `supportsStore: false`) + - Вставляє `context_management: [{ type: "compaction", compact_threshold: ... }]` + - Типовий `compact_threshold`: 70% від `contextWindow` (або `80000`, якщо він недоступний) - - Корисно для сумісних кінцевих точок, таких як Azure OpenAI Responses: + + Корисно для сумісних endpoint, як-от Azure OpenAI Responses: ```json5 { @@ -503,7 +509,7 @@ OpenClaw додає специфічний для OpenAI внесок у prompt - `responsesServerCompaction` керує лише впровадженням `context_management`. Прямі моделі OpenAI Responses усе одно примусово встановлюють `store: true`, якщо сумісність не задає `supportsStore: false`. + `responsesServerCompaction` керує лише вставленням `context_management`. Прямі моделі OpenAI Responses однаково примусово встановлюють `store: true`, якщо сумісність не задає `supportsStore: false`. @@ -522,30 +528,30 @@ OpenClaw додає специфічний для OpenAI внесок у prompt ``` Із `strict-agentic` OpenClaw: - - Більше не вважає хід лише з планом успішним прогресом, якщо доступна дія з інструментом + - Більше не вважає хід лише з планом успішним прогресом, коли доступна дія інструмента - Повторює хід із вказівкою діяти зараз - Автоматично вмикає `update_plan` для суттєвої роботи - Показує явний заблокований стан, якщо модель продовжує планувати без дії - Обмежено лише запуском сімейства GPT-5 для OpenAI і Codex. Інші провайдери та старіші сімейства моделей зберігають типову поведінку. + Поширюється лише на запускі сімейства OpenAI та Codex GPT-5. Інші провайдери та старіші сімейства моделей зберігають типову поведінку. - - OpenClaw по-різному обробляє прямі кінцеві точки OpenAI, Codex і Azure OpenAI порівняно із загальними проксі `/v1`, сумісними з OpenAI: + + OpenClaw по-різному обробляє прямі endpoint OpenAI, Codex і Azure OpenAI порівняно із загальними OpenAI-compatible proxy `/v1`: **Нативні маршрути** (`openai/*`, `openai-codex/*`, Azure OpenAI): - - Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують OpenAI `none` effort - - Пропускають вимкнений reasoning для моделей або проксі, які відхиляють `reasoning.effort: "none"` - - Типово встановлюють суворий режим для схем інструментів + - Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують `none` effort в OpenAI + - Пропускають вимкнений reasoning для моделей або proxy, які відхиляють `reasoning.effort: "none"` + - Типово використовують строгий режим для схем інструментів - Додають приховані заголовки атрибуції лише на перевірених нативних хостах - - Зберігають формування запитів, специфічне для OpenAI (`service_tier`, `store`, сумісність reasoning, підказки prompt-cache) + - Зберігають формування запитів, специфічне для OpenAI (`service_tier`, `store`, reasoning-compat, підказки prompt-cache) - **Проксі/сумісні маршрути:** + **Маршрути proxy/compatible:** - Використовують м’якшу поведінку сумісності - - Не примусово встановлюють суворі схеми інструментів або заголовки, специфічні для нативних маршрутів + - Не примушують до строгих схем інструментів або нативних заголовків Azure OpenAI використовує нативний транспорт і поведінку сумісності, але не отримує приховані заголовки атрибуції.