From ff21d0fdf89b4a38335d368ceb4824cc71a70f35 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 20 Apr 2026 18:40:17 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/channels/groups.md | 184 +- docs/uk/gateway/configuration.md | 359 ++-- .../sandbox-vs-tool-policy-vs-elevated.md | 111 +- docs/uk/gateway/sandboxing.md | 349 +-- docs/uk/gateway/security/index.md | 1149 +++++----- docs/uk/help/faq.md | 1870 +++++++++-------- docs/uk/install/ansible.md | 104 +- docs/uk/install/docker.md | 224 +- docs/uk/tools/skills-config.md | 84 +- 9 files changed, 2219 insertions(+), 2215 deletions(-) diff --git a/docs/uk/channels/groups.md b/docs/uk/channels/groups.md index 8641c139d..0528d8af5 100644 --- a/docs/uk/channels/groups.md +++ b/docs/uk/channels/groups.md @@ -1,13 +1,13 @@ --- read_when: - - Зміна поведінки групового чату або керування згадками -summary: Поведінка групових чатів на різних поверхнях (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo) + - Зміна поведінки групового чату або керування згадуваннями +summary: Поведінка групового чату на різних поверхнях (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo) title: Групи x-i18n: - generated_at: "2026-04-07T06:53:59Z" + generated_at: "2026-04-20T18:29:28Z" model: gpt-5.4 provider: openai - source_hash: f5045badbba30587c8f1bf27f6b940c7c471a95c57093c9adb142374413ac81e + source_hash: bbcdebd340a2ebb5898fe1eaf52258f65ba434bcf3be010d81b0e74af728aad4 source_path: channels/groups.md workflow: 15 --- @@ -24,89 +24,89 @@ OpenClaw «живе» у ваших власних облікових запис Поведінка за замовчуванням: - Групи обмежені (`groupPolicy: "allowlist"`). -- Для відповідей потрібна згадка, якщо ви явно не вимкнули керування згадками. +- Для відповідей потрібне згадування, якщо ви явно не вимкнете керування згадуваннями. -Простіше кажучи: відправники зі списку дозволених можуть запускати OpenClaw, згадавши його. +Переклад: відправники з allowlist можуть активувати OpenClaw, згадавши його. > Коротко > > - **Доступ до DM** контролюється через `*.allowFrom`. -> - **Доступ до груп** контролюється через `*.groupPolicy` + списки дозволених (`*.groups`, `*.groupAllowFrom`). -> - **Запуск відповіді** контролюється керуванням згадками (`requireMention`, `/activation`). +> - **Доступ до груп** контролюється через `*.groupPolicy` + allowlist (`*.groups`, `*.groupAllowFrom`). +> - **Запуск відповіді** контролюється керуванням згадуваннями (`requireMention`, `/activation`). -Швидка схема (що відбувається з повідомленням у групі): +Швидкий сценарій (що відбувається з повідомленням у групі): ``` -groupPolicy? disabled -> відкинути -groupPolicy? allowlist -> група дозволена? ні -> відкинути -requireMention? так -> є згадка? ні -> зберегти лише для контексту +groupPolicy? disabled -> відхилити +groupPolicy? allowlist -> групу дозволено? ні -> відхилити +requireMention? yes -> згадано? ні -> зберегти лише для контексту інакше -> відповісти ``` -## Видимість контексту та списки дозволених +## Видимість контексту та allowlist -У безпеці груп беруть участь два різні механізми: +У безпеці груп беруть участь два різні механізми керування: -- **Авторизація запуску**: хто може запускати агента (`groupPolicy`, `groups`, `groupAllowFrom`, специфічні для каналу списки дозволених). -- **Видимість контексту**: який додатковий контекст передається в модель (текст відповіді, цитати, історія треду, метадані пересилання). +- **Авторизація запуску**: хто може активувати агента (`groupPolicy`, `groups`, `groupAllowFrom`, allowlist, специфічні для каналу). +- **Видимість контексту**: який додатковий контекст передається в модель (текст відповіді, цитати, історія гілки, метадані пересилання). -За замовчуванням OpenClaw надає пріоритет звичайній поведінці чату й зберігає контекст переважно таким, як його отримано. Це означає, що списки дозволених переважно визначають, хто може запускати дії, а не є універсальною межею редагування для кожного цитованого або історичного фрагмента. +За замовчуванням OpenClaw надає пріоритет звичайній поведінці чату й здебільшого зберігає контекст у тому вигляді, у якому його отримано. Це означає, що allowlist переважно визначають, хто може запускати дії, а не є універсальною межею редагування для кожного процитованого або історичного фрагмента. Поточна поведінка залежить від каналу: -- Деякі канали вже застосовують фільтрацію за відправником для додаткового контексту в окремих шляхах (наприклад, початкове заповнення треду Slack, пошук відповіді/треду в Matrix). -- Інші канали все ще передають контекст цитати/відповіді/пересилання таким, як його отримано. +- Деякі канали вже застосовують фільтрацію відправників для додаткового контексту в окремих шляхах (наприклад, ініціалізація гілок Slack, пошук відповідей/гілок у Matrix). +- Інші канали все ще передають контекст цитат/відповідей/пересилань у тому вигляді, у якому він отриманий. Напрям посилення захисту (заплановано): -- `contextVisibility: "all"` (типове значення) зберігає поточну поведінку «як отримано». -- `contextVisibility: "allowlist"` фільтрує додатковий контекст до відправників зі списку дозволених. +- `contextVisibility: "all"` (за замовчуванням) зберігає поточну поведінку «як отримано». +- `contextVisibility: "allowlist"` фільтрує додатковий контекст до відправників з allowlist. - `contextVisibility: "allowlist_quote"` — це `allowlist` плюс один явний виняток для цитати/відповіді. -Поки цю модель посилення захисту не реалізовано узгоджено в усіх каналах, очікуйте відмінностей залежно від поверхні. +Поки цю модель посилення захисту не буде однаково реалізовано в усіх каналах, очікуйте відмінностей залежно від поверхні. -![Схема потоку групового повідомлення](/images/groups-flow.svg) +![Потік групових повідомлень](/images/groups-flow.svg) Якщо ви хочете... -| Ціль | Що налаштувати | +| Мета | Що налаштувати | | -------------------------------------------- | ---------------------------------------------------------- | | Дозволити всі групи, але відповідати лише на @згадки | `groups: { "*": { requireMention: true } }` | | Вимкнути всі відповіді в групах | `groupPolicy: "disabled"` | | Лише певні групи | `groups: { "": { ... } }` (без ключа `"*"`) | -| Лише ви можете запускати в групах | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` | +| Лише ви можете запускати відповіді в групах | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` | ## Ключі сесій - Групові сесії використовують ключі сесій `agent:::group:` (кімнати/канали використовують `agent:::channel:`). -- Теми форуму Telegram додають `:topic:` до ідентифікатора групи, щоб кожна тема мала власну сесію. +- Теми форуму Telegram додають `:topic:` до ідентифікатора групи, тому кожна тема має власну сесію. - Прямі чати використовують основну сесію (або окрему для кожного відправника, якщо це налаштовано). -- Heartbeats для групових сесій пропускаються. +- Heartbeat пропускаються для групових сесій. ## Шаблон: особисті DM + публічні групи (один агент) -Так — це добре працює, якщо ваш «особистий» трафік — це **DM**, а ваш «публічний» трафік — це **групи**. +Так — це добре працює, якщо ваш «особистий» трафік — це **DM**, а «публічний» трафік — це **групи**. -Чому: у режимі одного агента DM зазвичай потрапляють до **основного** ключа сесії (`agent:main:main`), тоді як групи завжди використовують **неосновні** ключі сесій (`agent:main::group:`). Якщо ви ввімкнете sandboxing із `mode: "non-main"`, ці групові сесії працюватимуть у Docker, а ваша основна DM-сесія залишиться на хості. +Чому: у режимі одного агента DM зазвичай потрапляють до ключа **основної** сесії (`agent:main:main`), тоді як групи завжди використовують ключі **неосновних** сесій (`agent:main::group:`). Якщо ви ввімкнете ізоляцію через `mode: "non-main"`, ці групові сесії виконуватимуться у налаштованому бекенді sandbox, тоді як ваша основна DM-сесія залишиться на хості. Docker є бекендом за замовчуванням, якщо ви не виберете інший. -Це дає вам один «мозок» агента (спільний workspace + memory), але дві моделі виконання: +Це дає вам один «мозок» агента (спільний робочий простір + пам’ять), але дві різні моделі виконання: - **DM**: повні інструменти (хост) -- **Групи**: sandbox + обмежені інструменти (Docker) +- **Групи**: sandbox + обмежені інструменти -> Якщо вам потрібні справді окремі workspace/персони («особисте» й «публічне» ніколи не мають змішуватися), використовуйте другого агента + bindings. Див. [Маршрутизація кількох агентів](/uk/concepts/multi-agent). +> Якщо вам потрібні справді окремі робочі простори/персони («особисте» й «публічне» ніколи не мають змішуватися), використайте другого агента + bindings. Див. [Багатоагентна маршрутизація](/uk/concepts/multi-agent). -Приклад (DM на хості, групи в sandbox + лише інструменти для обміну повідомленнями): +Приклад (DM на хості, групи в sandbox + лише інструменти для повідомлень): ```json5 { agents: { defaults: { sandbox: { - mode: "non-main", // групи/канали є неосновними -> у sandbox - scope: "session", // найсильніша ізоляція (один контейнер на групу/канал) + mode: "non-main", // groups/channels are non-main -> sandboxed + scope: "session", // strongest isolation (one container per group/channel) workspaceAccess: "none", }, }, @@ -114,7 +114,7 @@ requireMention? так -> є згадка? ні -> зберегти лише д tools: { sandbox: { tools: { - // Якщо список allow не порожній, усе інше блокується (deny все одно має пріоритет). + // If allow is non-empty, everything else is blocked (deny still wins). allow: ["group:messaging", "group:sessions"], deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"], }, @@ -123,7 +123,7 @@ requireMention? так -> є згадка? ні -> зберегти лише д } ``` -Хочете, щоб «групи могли бачити лише теку X» замість «без доступу до хоста»? Залиште `workspaceAccess: "none"` і змонтуйте в sandbox лише шляхи зі списку дозволених: +Хочете, щоб «групи могли бачити лише папку X» замість «без доступу до хоста»? Залиште `workspaceAccess: "none"` і змонтуйте в sandbox лише шляхи з allowlist: ```json5 { @@ -145,20 +145,20 @@ requireMention? так -> є згадка? ні -> зберегти лише д } ``` -Пов’язано: +Пов’язане: -- Ключі конфігурації та значення за замовчуванням: [Конфігурація шлюзу](/uk/gateway/configuration-reference#agentsdefaultssandbox) -- Налагодження, чому інструмент заблоковано: [Sandbox vs Tool Policy vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated) -- Подробиці bind mounts: [Sandboxing](/uk/gateway/sandboxing#custom-bind-mounts) +- Ключі конфігурації та значення за замовчуванням: [Конфігурація Gateway](/uk/gateway/configuration-reference#agentsdefaultssandbox) +- Налагодження причин блокування інструмента: [Sandbox vs Tool Policy vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated) +- Докладніше про bind mounts: [Sandboxing](/uk/gateway/sandboxing#custom-bind-mounts) ## Мітки відображення -- Мітки в UI використовують `displayName`, якщо він доступний, у форматі `:`. +- Мітки в UI використовують `displayName`, коли він доступний, у форматі `:`. - `#room` зарезервовано для кімнат/каналів; групові чати використовують `g-` (нижній регістр, пробіли -> `-`, зберігати `#@+._-`). ## Політика груп -Керуйте тим, як обробляються повідомлення груп/кімнат для кожного каналу: +Керуйте тим, як обробляються повідомлення в групах/кімнатах для кожного каналу: ```json5 { @@ -169,7 +169,7 @@ requireMention? так -> є згадка? ні -> зберегти лише д }, telegram: { groupPolicy: "disabled", - groupAllowFrom: ["123456789"], // числовий Telegram user id (wizard може визначити через @username) + groupAllowFrom: ["123456789"], // numeric Telegram user id (wizard can resolve @username) }, signal: { groupPolicy: "disabled", @@ -207,36 +207,36 @@ requireMention? так -> є згадка? ні -> зберегти лише д | Політика | Поведінка | | ------------- | ------------------------------------------------------------ | -| `"open"` | Групи оминають списки дозволених; керування згадками все одно застосовується. | -| `"disabled"` | Повністю блокує всі групові повідомлення. | -| `"allowlist"` | Дозволяє лише групи/кімнати, що відповідають налаштованому списку дозволених. | +| `"open"` | Групи оминають allowlist; керування згадуваннями все ще діє. | +| `"disabled"` | Повністю блокувати всі групові повідомлення. | +| `"allowlist"` | Дозволяти лише групи/кімнати, що відповідають налаштованому allowlist. | Примітки: -- `groupPolicy` відокремлена від керування згадками (яке вимагає @згадок). +- `groupPolicy` відокремлена від керування згадуваннями (яке вимагає @згадок). - WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: використовуйте `groupAllowFrom` (резервний варіант: явний `allowFrom`). -- Погодження DM pairing (записи у сховищі `*-allowFrom`) стосуються лише доступу до DM; авторизація відправника в групі лишається явно керованою списками дозволених для груп. -- Discord: список дозволених використовує `channels.discord.guilds..channels`. -- Slack: список дозволених використовує `channels.slack.channels`. -- Matrix: список дозволених використовує `channels.matrix.groups`. Віддавайте перевагу room ID або alias; пошук за назвою приєднаної кімнати є best-effort, а нерозпізнані назви ігноруються під час виконання. Використовуйте `channels.matrix.groupAllowFrom` для обмеження відправників; також підтримуються списки дозволених `users` для окремих кімнат. +- Підтвердження прив’язки DM (записи сховища `*-allowFrom`) застосовуються лише до доступу в DM; авторизація відправників у групах залишається явно прив’язаною до group allowlist. +- Discord: allowlist використовує `channels.discord.guilds..channels`. +- Slack: allowlist використовує `channels.slack.channels`. +- Matrix: allowlist використовує `channels.matrix.groups`. Віддавайте перевагу ID кімнат або aliases; пошук назв приєднаних кімнат виконується за принципом best-effort, а нерозв’язані назви ігноруються під час виконання. Використовуйте `channels.matrix.groupAllowFrom`, щоб обмежити відправників; також підтримуються allowlist `users` для окремих кімнат. - Групові DM керуються окремо (`channels.discord.dm.*`, `channels.slack.dm.*`). -- Список дозволених Telegram може відповідати user ID (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) або іменам користувачів (`"@alice"` або `"alice"`); префікси нечутливі до регістру. -- За замовчуванням використовується `groupPolicy: "allowlist"`; якщо ваш список дозволених груп порожній, групові повідомлення блокуються. +- Telegram allowlist може відповідати ID користувачів (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) або іменам користувачів (`"@alice"` або `"alice"`); префікси нечутливі до регістру. +- За замовчуванням використовується `groupPolicy: "allowlist"`; якщо ваш group allowlist порожній, групові повідомлення блокуються. - Безпека під час виконання: коли блок провайдера повністю відсутній (`channels.` відсутній), політика груп переходить у fail-closed режим (зазвичай `allowlist`) замість успадкування `channels.defaults.groupPolicy`. Швидка ментальна модель (порядок перевірки для групових повідомлень): 1. `groupPolicy` (open/disabled/allowlist) -2. списки дозволених для груп (`*.groups`, `*.groupAllowFrom`, список дозволених, специфічний для каналу) -3. керування згадками (`requireMention`, `/activation`) +2. group allowlist (`*.groups`, `*.groupAllowFrom`, allowlist, специфічний для каналу) +3. керування згадуваннями (`requireMention`, `/activation`) -## Керування згадками (типово) +## Керування згадуваннями (за замовчуванням) -Групові повідомлення вимагають згадки, якщо це не перевизначено для конкретної групи. Значення за замовчуванням зберігаються для кожної підсистеми в `*.groups."*"`. +Групові повідомлення вимагають згадування, якщо це не перевизначено для конкретної групи. Значення за замовчуванням зберігаються для кожної підсистеми в `*.groups."*"`. -Відповідь на повідомлення бота вважається неявною згадкою, якщо канал -підтримує метадані відповіді. Цитування повідомлення бота також може вважатися неявною -згадкою на каналах, які надають метадані цитати. Поточні вбудовані випадки включають +Відповідь на повідомлення бота вважається неявним згадуванням, якщо канал +підтримує метадані відповіді. Цитування повідомлення бота також може вважатися неявним +згадуванням у каналах, які надають метадані цитати. Поточні вбудовані випадки включають Telegram, WhatsApp, Slack, Discord, Microsoft Teams і ZaloUser. ```json5 @@ -277,29 +277,29 @@ Telegram, WhatsApp, Slack, Discord, Microsoft Teams і ZaloUser. Примітки: -- `mentionPatterns` — це безпечні regex-шаблони, нечутливі до регістру; невалідні шаблони та небезпечні форми з вкладеним повторенням ігноруються. -- Поверхні, що надають явні згадки, усе одно проходять; шаблони є резервним варіантом. -- Перевизначення для окремого агента: `agents.list[].groupChat.mentionPatterns` (корисно, коли кілька агентів спільно використовують групу). -- Керування згадками застосовується лише тоді, коли можливе виявлення згадки (власні згадки або налаштовано `mentionPatterns`). -- Значення за замовчуванням для Discord містяться в `channels.discord.guilds."*"` (можна перевизначати для окремого guild/channel). -- Контекст історії групи уніфіковано обгортається для всіх каналів і є **лише для pending** (повідомлення, пропущені через керування згадками); використовуйте `messages.groupChat.historyLimit` для глобального значення за замовчуванням і `channels..historyLimit` (або `channels..accounts.*.historyLimit`) для перевизначень. Встановіть `0`, щоб вимкнути. +- `mentionPatterns` — це безпечні regex-патерни, нечутливі до регістру; недійсні патерни та небезпечні вкладені форми повторення ігноруються. +- Поверхні, які надають явні згадування, усе одно проходять; патерни є резервним варіантом. +- Перевизначення для агента: `agents.list[].groupChat.mentionPatterns` (корисно, коли кілька агентів використовують одну групу). +- Керування згадуваннями застосовується лише тоді, коли можливе виявлення згадування (вбудовані згадки або налаштовано `mentionPatterns`). +- Значення за замовчуванням для Discord зберігаються в `channels.discord.guilds."*"` (можна перевизначити для кожної guild/channel). +- Контекст історії групи однаково обгортається для всіх каналів і є **лише pending** (повідомлення, пропущені через керування згадуваннями); використовуйте `messages.groupChat.historyLimit` для глобального значення за замовчуванням і `channels..historyLimit` (або `channels..accounts.*.historyLimit`) для перевизначень. Встановіть `0`, щоб вимкнути. ## Обмеження інструментів для груп/каналів (необов’язково) Деякі конфігурації каналів підтримують обмеження того, які інструменти доступні **всередині конкретної групи/кімнати/каналу**. - `tools`: дозволити/заборонити інструменти для всієї групи. -- `toolsBySender`: перевизначення для окремих відправників усередині групи. +- `toolsBySender`: перевизначення для окремих відправників у межах групи. Використовуйте явні префікси ключів: `id:`, `e164:`, `username:`, `name:` і wildcard `"*"`. - Застарілі ключі без префіксів усе ще приймаються й зіставляються лише як `id:`. + Застарілі ключі без префікса все ще приймаються й зіставляються лише як `id:`. -Порядок визначення (найбільш специфічне має пріоритет): +Порядок розв’язання (найспецифічніший має пріоритет): -1. відповідність `toolsBySender` для групи/каналу +1. збіг `toolsBySender` для групи/каналу 2. `tools` для групи/каналу -3. відповідність `toolsBySender` для значення за замовчуванням (`"*"`). -4. `tools` для значення за замовчуванням (`"*"`) +3. збіг `toolsBySender` за замовчуванням (`"*"`) +4. `tools` за замовчуванням (`"*"`) Приклад (Telegram): @@ -323,17 +323,17 @@ Telegram, WhatsApp, Slack, Discord, Microsoft Teams і ZaloUser. Примітки: -- Обмеження інструментів для груп/каналів застосовуються додатково до глобальної/агентської політики інструментів (deny все одно має пріоритет). +- Обмеження інструментів для груп/каналів застосовуються додатково до глобальної/агентської політики інструментів (заборона все одно має пріоритет). - Деякі канали використовують іншу вкладеність для кімнат/каналів (наприклад, Discord `guilds.*.channels.*`, Slack `channels.*`, Microsoft Teams `teams.*.channels.*`). -## Списки дозволених для груп +## Group allowlist -Коли налаштовано `channels.whatsapp.groups`, `channels.telegram.groups` або `channels.imessage.groups`, ключі діють як список дозволених для груп. Використовуйте `"*"`, щоб дозволити всі групи й водночас задати типову поведінку згадок. +Коли налаштовано `channels.whatsapp.groups`, `channels.telegram.groups` або `channels.imessage.groups`, ключі діють як group allowlist. Використовуйте `"*"` , щоб дозволити всі групи, водночас задавши стандартну поведінку згадувань. -Поширена плутанина: погодження DM pairing — це не те саме, що авторизація групи. -Для каналів, які підтримують DM pairing, сховище pairing розблоковує лише DM. Групові команди все одно вимагають явної авторизації відправника групи через конфігураційні списки дозволених, як-от `groupAllowFrom`, або задокументований резервний механізм конфігурації для цього каналу. +Поширена плутанина: підтвердження прив’язки DM — це не те саме, що авторизація групи. +Для каналів, які підтримують прив’язку DM, сховище прив’язок відкриває лише DM. Команди в групах однаково вимагають явної авторизації відправника групи через allowlist у конфігурації, як-от `groupAllowFrom`, або задокументований резервний варіант конфігурації для цього каналу. -Поширені наміри (скопіювати/вставити): +Поширені наміри (копіюйте/вставляйте): 1. Вимкнути всі відповіді в групах @@ -343,7 +343,7 @@ Telegram, WhatsApp, Slack, Discord, Microsoft Teams і ZaloUser. } ``` -2. Дозволити лише певні групи (WhatsApp) +2. Дозволити лише конкретні групи (WhatsApp) ```json5 { @@ -358,7 +358,7 @@ Telegram, WhatsApp, Slack, Discord, Microsoft Teams і ZaloUser. } ``` -3. Дозволити всі групи, але вимагати згадку (явно) +3. Дозволити всі групи, але вимагати згадування (явно) ```json5 { @@ -370,7 +370,7 @@ Telegram, WhatsApp, Slack, Discord, Microsoft Teams і ZaloUser. } ``` -4. Лише власник може запускати в групах (WhatsApp) +4. Лише власник може запускати відповіді в групах (WhatsApp) ```json5 { @@ -386,35 +386,35 @@ Telegram, WhatsApp, Slack, Discord, Microsoft Teams і ZaloUser. ## Активація (лише для власника) -Власники груп можуть перемикати активацію для окремої групи: +Власники груп можуть перемикати активацію для кожної групи: - `/activation mention` - `/activation always` -Власник визначається через `channels.whatsapp.allowFrom` (або власний E.164 бота, якщо не задано). Надсилайте команду як окреме повідомлення. Інші поверхні наразі ігнорують `/activation`. +Власник визначається через `channels.whatsapp.allowFrom` (або через власний E.164 бота, якщо не задано). Надсилайте команду як окреме повідомлення. Інші поверхні наразі ігнорують `/activation`. ## Поля контексту -Вхідні payload для груп задають: +Вхідні payload для груп встановлюють: - `ChatType=group` - `GroupSubject` (якщо відомо) - `GroupMembers` (якщо відомо) -- `WasMentioned` (результат керування згадками) -- Теми форуму Telegram також включають `MessageThreadId` і `IsForum`. +- `WasMentioned` (результат керування згадуваннями) +- Теми форуму Telegram також містять `MessageThreadId` і `IsForum`. Примітки для конкретних каналів: -- BlueBubbles за потреби може збагачувати учасників без імен у групах macOS із локальної бази Contacts перед заповненням `GroupMembers`. Це вимкнено за замовчуванням і запускається лише після проходження звичайної перевірки груп. +- BlueBubbles може за бажанням збагачувати учасників без імен у групах macOS із локальної бази Contacts перед заповненням `GroupMembers`. Це вимкнено за замовчуванням і виконується лише після проходження звичайної перевірки групових обмежень. -Системний prompt агента включає вступ для групи на першому ході нової групової сесії. Він нагадує моделі відповідати як людині, уникати таблиць Markdown, зводити порожні рядки до мінімуму й дотримуватися звичайних інтервалів у чаті, а також не вводити буквальні послідовності `\n`. +Системний prompt агента містить вступ для групи на першому ході нової групової сесії. Він нагадує моделі відповідати як людині, уникати Markdown-таблиць, мінімізувати порожні рядки, дотримуватися звичайних інтервалів у чаті та не вводити буквально послідовності `\n`. ## Особливості iMessage -- Для маршрутизації або списків дозволених віддавайте перевагу `chat_id:`. -- Перегляд чатів: `imsg chats --limit 20`. +- Для маршрутизації або allowlist віддавайте перевагу `chat_id:`. +- Список чатів: `imsg chats --limit 20`. - Відповіді в групах завжди повертаються до того самого `chat_id`. ## Особливості WhatsApp -Див. [Групові повідомлення](/uk/channels/group-messages) щодо поведінки, специфічної лише для WhatsApp (впровадження історії, подробиці обробки згадок). +Див. [Групові повідомлення](/uk/channels/group-messages) щодо поведінки лише для WhatsApp (вставлення історії, деталі обробки згадувань). diff --git a/docs/uk/gateway/configuration.md b/docs/uk/gateway/configuration.md index 5c02f493f..2e5cf4ad4 100644 --- a/docs/uk/gateway/configuration.md +++ b/docs/uk/gateway/configuration.md @@ -1,15 +1,15 @@ --- read_when: - - Налаштування OpenClaw уперше + - Перше налаштування OpenClaw - Пошук поширених шаблонів конфігурації - Перехід до певних розділів конфігурації summary: 'Огляд конфігурації: поширені завдання, швидке налаштування та посилання на повний довідник' title: Конфігурація x-i18n: - generated_at: "2026-04-20T12:31:59Z" + generated_at: "2026-04-20T18:29:28Z" model: gpt-5.4 provider: openai - source_hash: bad966d0333c28a94905fa8c01eba41dbdf5bfcbda25e7a71a8bea1589703b9b + source_hash: 479e59fb8b57c5228ef1c6076cf80a4ce6064d3f6fad5f38ea9d75eeb92811dc source_path: gateway/configuration.md workflow: 15 --- @@ -21,13 +21,13 @@ OpenClaw зчитує необов’язкову конфігурацію -**Вперше працюєте з конфігурацією?** Почніть із `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) із готовими конфігураціями для копіювання. +**Новачок у конфігурації?** Почніть з `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) з повними конфігураціями для копіювання й вставлення. ## Мінімальна конфігурація @@ -45,8 +45,8 @@ OpenClaw зчитує необов’язкову конфігурацію ```bash - openclaw onboard # повний процес початкового налаштування - openclaw configure # майстер конфігурації + openclaw onboard # full onboarding flow + openclaw configure # config wizard ``` @@ -58,42 +58,42 @@ OpenClaw зчитує необов’язкову конфігурацію Відкрийте [http://127.0.0.1:18789](http://127.0.0.1:18789) і використовуйте вкладку **Config**. - Control UI відображає форму на основі актуальної схеми конфігурації, включно з метаданими документації полів + Control UI відображає форму з живої схеми конфігурації, включно з метаданими документації полів `title` / `description`, а також схемами Plugin і каналів, коли вони - доступні, із редактором **Raw JSON** як запасним варіантом. Для - інтерфейсів деталізації та інших інструментів gateway також надає `config.schema.lookup` для - отримання одного вузла схеми, обмеженого шляхом, разом із підсумками безпосередніх дочірніх елементів. + доступні, із редактором **Raw JSON** як запасним варіантом. Для деталізованих + UI та інших інструментів gateway також надає `config.schema.lookup`, щоб + отримати один вузол схеми для певного шляху разом із підсумками безпосередніх дочірніх елементів. - Відредагуйте `~/.openclaw/openclaw.json` безпосередньо. Gateway відстежує файл і автоматично застосовує зміни (див. [гаряче перезавантаження](#config-hot-reload)). + Редагуйте `~/.openclaw/openclaw.json` безпосередньо. Gateway відстежує файл і автоматично застосовує зміни (див. [гаряче перезавантаження](#config-hot-reload)). ## Сувора валідація -OpenClaw приймає лише конфігурації, що повністю відповідають схемі. Невідомі ключі, некоректні типи або недійсні значення призводять до того, що Gateway **відмовляється запускатися**. Єдиний виняток на кореневому рівні — `$schema` (рядок), щоб редактори могли підключати метадані JSON Schema. +OpenClaw приймає лише конфігурації, що повністю відповідають схемі. Невідомі ключі, некоректні типи або недійсні значення призводять до того, що Gateway **відмовляється запускатися**. Єдиний виняток на рівні кореня — `$schema` (рядок), щоб редактори могли приєднувати метадані JSON Schema. Примітки щодо інструментів схеми: - `openclaw config schema` виводить ту саму сім’ю JSON Schema, яку використовують Control UI і валідація конфігурації. -- Вважайте цей вивід схеми канонічним машиночитним контрактом для +- Вважайте цей вивід схеми канонічним машиночитаним контрактом для `openclaw.json`; цей огляд і довідник конфігурації її узагальнюють. - Значення полів `title` і `description` переносяться у вивід схеми для - редакторів та інструментів форм. -- Вкладені об’єкти, шаблони (`*`) і записи елементів масиву (`[]`) успадковують ті самі - метадані документації там, де існує відповідна документація для поля. + інструментів редактора та форм. +- Вкладені об’єкти, шаблонні (`*`) і елементи масивів (`[]`) успадковують ті самі + метадані документації там, де існує відповідна документація поля. - Гілки композиції `anyOf` / `oneOf` / `allOf` також успадковують ті самі - метадані документації, тож варіанти union/intersection зберігають ту саму довідку для полів. -- `config.schema.lookup` повертає один нормалізований шлях конфігурації з поверхневим - вузлом схеми (`title`, `description`, `type`, `enum`, `const`, типові обмеження - та подібні поля валідації), відповідними метаданими підказок UI та короткими - підсумками безпосередніх дочірніх елементів для інструментів деталізації. -- Схеми Plugin/каналів часу виконання об’єднуються, коли gateway може завантажити + метадані документації, тож варіанти union/intersection зберігають ту саму довідку по полях. +- `config.schema.lookup` повертає один нормалізований шлях конфігурації з неглибоким + вузлом схеми (`title`, `description`, `type`, `enum`, `const`, типові межі + та подібні поля валідації), відповідні метадані підказок UI і короткі описи + безпосередніх дочірніх елементів для інструментів деталізації. +- Схеми Plugin/каналів під час виконання об’єднуються, коли gateway може завантажити поточний реєстр маніфестів. -- `pnpm config:docs:check` виявляє розходження між артефактами базової конфігурації +- `pnpm config:docs:check` виявляє розбіжності між базовими артефактами конфігурації для документації та поточною поверхнею схеми. Коли валідація не проходить: @@ -103,22 +103,22 @@ OpenClaw приймає лише конфігурації, що повністю - Запустіть `openclaw doctor`, щоб побачити точні проблеми - Запустіть `openclaw doctor --fix` (або `--yes`), щоб застосувати виправлення -Gateway також зберігає довірену останню відому справну копію після успішного запуску. Якщо -`openclaw.json` згодом змінено поза OpenClaw і він більше не проходить валідацію, під час запуску -та гарячого перезавантаження зламаний файл зберігається як знімок `.clobbered.*` із часовою позначкою, -відновлюється остання відома справна копія, а в журнал записується помітне попередження з причиною відновлення. -На наступному ході основного агента також надсилається системне попередження, яке повідомляє, що -конфігурацію було відновлено і її не можна бездумно перезаписувати. Підвищення статусу до останньої відомої справної -копії оновлюється після валідаційного запуску та після прийнятих гарячих перезавантажень, включно з -записами конфігурації, виконаними OpenClaw, якщо хеш збереженого файлу все ще відповідає прийнятому -запису. Підвищення пропускається, коли кандидат містить замасковані заповнювачі секретів, -такі як `***` або скорочені значення токенів. +Gateway також зберігає довірену останню справну копію після успішного запуску. Якщо +`openclaw.json` пізніше змінено поза OpenClaw і він більше не проходить валідацію, під час запуску +і гарячого перезавантаження пошкоджений файл зберігається як знімок `.clobbered.*` із часовою позначкою, +відновлюється остання справна копія, а в журнал записується помітне попередження з причиною відновлення. +Під час наступного ходу головного агента він також отримує попередження системної події про те, що +конфігурацію було відновлено і її не можна бездумно перезаписувати. Просування останньої справної копії +оновлюється після перевіреного запуску та після прийнятих гарячих перезавантажень, зокрема +для записів конфігурації, виконаних самим OpenClaw, якщо хеш збереженого файла все ще збігається з прийнятим +записом. Просування пропускається, коли кандидат містить відредаговані заповнювачі секретів +на кшталт `***` або скорочені значення токенів. ## Поширені завдання - - Кожен канал має власний розділ конфігурації в `channels.`. Кроки налаштування дивіться на окремій сторінці каналу: + + Кожен канал має власний розділ конфігурації в `channels.`. Перегляньте окрему сторінку каналу, щоб виконати налаштування: - [WhatsApp](/uk/channels/whatsapp) — `channels.whatsapp` - [Telegram](/uk/channels/telegram) — `channels.telegram` @@ -131,7 +131,7 @@ Gateway також зберігає довірену останню відому - [iMessage](/uk/channels/imessage) — `channels.imessage` - [Mattermost](/uk/channels/mattermost) — `channels.mattermost` - Усі канали використовують однаковий шаблон політики DM: + Усі канали використовують однаковий шаблон політики приватних повідомлень: ```json5 { @@ -148,8 +148,8 @@ Gateway також зберігає довірену останню відому - - Задайте основну модель і необов’язкові резервні варіанти: + + Вкажіть основну модель і необов’язкові резервні варіанти: ```json5 { @@ -170,28 +170,28 @@ Gateway також зберігає довірену останню відому - `agents.defaults.models` визначає каталог моделей і слугує allowlist для `/model`. - Посилання на моделі використовують формат `provider/model` (наприклад, `anthropic/claude-opus-4-6`). - - `agents.defaults.imageMaxDimensionPx` керує зменшенням масштабу зображень у транскриптах/інструментах (типове значення `1200`); менші значення зазвичай зменшують використання vision-токенів у сценаріях з великою кількістю скриншотів. - - Див. [Models CLI](/uk/concepts/models) для перемикання моделей у чаті та [Model Failover](/uk/concepts/model-failover) для ротації автентифікації й поведінки резервних моделей. - - Для користувацьких/self-hosted provider див. [Користувацькі provider](/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 провайдерів див. [Custom providers](/uk/gateway/configuration-reference#custom-providers-and-base-urls) у довіднику. - - Доступ до DM контролюється для кожного каналу через `dmPolicy`: + + Доступ до приватних повідомлень контролюється окремо для кожного каналу через `dmPolicy`: - - `"pairing"` (типово): невідомі відправники отримують одноразовий код pairing для підтвердження - - `"allowlist"`: лише відправники з `allowFrom` (або зі сховища paired allow) - - `"open"`: дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`) - - `"disabled"`: ігнорувати всі DM + - `"pairing"` (типово): невідомі відправники отримують одноразовий код сполучення для підтвердження + - `"allowlist"`: лише відправники з `allowFrom` (або зі сховища дозволених сполучених користувачів) + - `"open"`: дозволити всі вхідні приватні повідомлення (потрібно `allowFrom: ["*"]`) + - `"disabled"`: ігнорувати всі приватні повідомлення Для груп використовуйте `groupPolicy` + `groupAllowFrom` або allowlist, специфічні для каналу. - Див. [повний довідник](/uk/gateway/configuration-reference#dm-and-group-access) для подробиць по кожному каналу. + Докладні відомості для кожного каналу див. у [повному довіднику](/uk/gateway/configuration-reference#dm-and-group-access). - - Для групових повідомлень типово **потрібна згадка**. Налаштуйте шаблони для кожного агента: + + Повідомлення в групах за замовчуванням **вимагають згадки**. Налаштуйте шаблони для кожного агента: ```json5 { @@ -215,13 +215,13 @@ Gateway також зберігає довірену останню відому - **Метадані згадок**: нативні @-згадки (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). - - Використовуйте `agents.defaults.skills` для спільної базової конфігурації, а потім перевизначайте конкретні - агенти через `agents.list[].skills`: + + Використовуйте `agents.defaults.skills` для спільної базової конфігурації, а потім перевизначайте + окремих агентів через `agents.list[].skills`: ```json5 { @@ -238,16 +238,16 @@ Gateway також зберігає довірену останню відому } ``` - - Не вказуйте `agents.defaults.skills`, якщо Skills за замовчуванням не мають бути обмежені. - - Не вказуйте `agents.list[].skills`, щоб успадкувати значення за замовчуванням. - - Вкажіть `agents.list[].skills: []`, щоб не дозволити жодних Skills. + - Не вказуйте `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). + [довідник конфігурації](/uk/gateway/configuration-reference#agents-defaults-skills). - - Керуйте тим, наскільки агресивно gateway перезапускає канали, що виглядають неактивними: + + Керуйте тим, наскільки агресивно gateway перезапускає канали, які виглядають застарілими: ```json5 { @@ -269,15 +269,15 @@ Gateway також зберігає довірену останню відому } ``` - - Встановіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски монітора стану. + - Установіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски моніторингу стану. - `channelStaleEventThresholdMinutes` має бути більшим або дорівнювати інтервалу перевірки. - - Використовуйте `channels..healthMonitor.enabled` або `channels..accounts..healthMonitor.enabled`, щоб вимкнути автоперезапуск для одного каналу або облікового запису без вимкнення глобального монітора. - - Див. [Health Checks](/uk/gateway/health) для операційного налагодження та [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів. + - Використовуйте `channels..healthMonitor.enabled` або `channels..accounts..healthMonitor.enabled`, щоб вимкнути автоперезапуски для одного каналу чи облікового запису без вимкнення глобального монітора. + - Див. [Health Checks](/uk/gateway/health) для операційної діагностики та [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів. - - Сесії керують безперервністю та ізоляцією розмов: + + Сесії керують безперервністю розмови та ізоляцією: ```json5 { @@ -298,14 +298,14 @@ Gateway також зберігає довірену останню відому ``` - `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) для всіх полів. + - `threadBindings`: глобальні типові значення для маршрутизації сесій, прив’язаних до тредів (Discord підтримує `/focus`, `/unfocus`, `/agents`, `/session idle` і `/session max-age`). + - Див. [Керування сесіями](/uk/concepts/session) для відомостей про області дії, зв’язки ідентичностей і політику надсилання. + - Усі поля див. у [повному довіднику](/uk/gateway/configuration-reference#session). - - Запускайте сесії агентів в ізольованих Docker-контейнерах: + + Запускайте сесії агента в ізольованих runtime ізолятора: ```json5 { @@ -322,14 +322,14 @@ Gateway також зберігає довірену останню відому Спочатку зберіть образ: `scripts/sandbox-setup.sh` - Див. [Ізоляція](/uk/gateway/sandboxing) для повного посібника та [повний довідник](/uk/gateway/configuration-reference#agentsdefaultssandbox) для всіх параметрів. + Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing), а всі параметри — у [повному довіднику](/uk/gateway/configuration-reference#agentsdefaultssandbox). - - Push на основі relay налаштовується в `openclaw.json`. + + Push через relay налаштовується в `openclaw.json`. - Встановіть це в конфігурації gateway: + Укажіть це в конфігурації gateway: ```json5 { @@ -355,35 +355,35 @@ Gateway також зберігає довірену останню відому Що це робить: - - Дозволяє gateway надсилати `push.test`, сигнали пробудження та сигнали повторного підключення через зовнішній relay. - - Використовує grant на надсилання в межах реєстрації, який пересилає прив’язаний iOS app. Gateway не потребує relay-токена на рівні всього розгортання. - - Прив’язує кожну relay-backed реєстрацію до ідентичності gateway, з якою було спарено iOS app, тож інший gateway не зможе повторно використати збережену реєстрацію. - - Залишає локальні/ручні збірки iOS на прямих APNs. Relay-backed надсилання застосовується лише до офіційно розповсюджуваних збірок, що зареєструвалися через relay. - - Має збігатися з базовим URL relay, вбудованим в офіційну/TestFlight збірку iOS, щоб трафік реєстрації та надсилання потрапляв до одного й того самого розгортання relay. + - Дозволяє gateway надсилати `push.test`, сигнали пробудження і сигнали повторного підключення через зовнішній relay. + - Використовує grant на надсилання в межах реєстрації, який пересилає сполучений застосунок iOS. Gateway не потребує relay-токена рівня всього розгортання. + - Прив’язує кожну реєстрацію через relay до ідентичності gateway, з якою було сполучено застосунок iOS, тож інший gateway не може повторно використати збережену реєстрацію. + - Залишає локальні/ручні збірки iOS на прямому APNs. Надсилання через relay застосовується лише до офіційно розповсюджених збірок, що зареєструвалися через relay. + - Має збігатися з базовим URL relay, вбудованим в офіційну/TestFlight збірку iOS, щоб трафік реєстрації та надсилання потрапляв до того самого розгортання relay. - Повний наскрізний процес: + Наскрізний процес: - 1. Установіть офіційну/TestFlight збірку iOS, зібрану з тим самим базовим URL relay. - 2. Налаштуйте `gateway.push.apns.relay.baseUrl` на gateway. - 3. Спарте iOS app із gateway і дочекайтеся підключення як node, так і operator sessions. - 4. iOS app отримує ідентичність gateway, реєструється в relay за допомогою App Attest і квитанції app, а потім публікує relay-backed payload `push.apns.register` до прив’язаного gateway. - 5. Gateway зберігає relay handle і grant на надсилання, а потім використовує їх для `push.test`, сигналів пробудження та сигналів повторного підключення. + 1. Установіть офіційну/TestFlight збірку iOS, скомпільовану з тим самим базовим URL relay. + 2. Налаштуйте `gateway.push.apns.relay.baseUrl` у gateway. + 3. Сполучіть застосунок iOS із gateway і дайте змогу підключитися як сесіям node, так і сесіям оператора. + 4. Застосунок iOS отримує ідентичність gateway, реєструється в relay за допомогою App Attest і квитанції застосунку, а потім публікує payload `push.apns.register` через relay до сполученого gateway. + 5. Gateway зберігає relay handle і grant на надсилання, а потім використовує їх для `push.test`, сигналів пробудження і сигналів повторного підключення. - Примітки щодо експлуатації: + Операційні примітки: - - Якщо ви перемикаєте iOS app на інший gateway, перепідключіть app, щоб він міг опублікувати нову relay-реєстрацію, прив’язану до цього gateway. - - Якщо ви випускаєте нову збірку iOS, яка вказує на інше розгортання relay, app оновлює кешовану relay-реєстрацію замість повторного використання старого relay origin. + - Якщо ви перемикаєте застосунок iOS на інший gateway, перепідключіть застосунок, щоб він міг опублікувати нову relay-реєстрацію, прив’язану до цього gateway. + - Якщо ви випускаєте нову збірку iOS, що вказує на інше розгортання relay, застосунок оновлює свій кешований relay-реєстраційний запис замість повторного використання старого джерела relay. Примітка щодо сумісності: - - `OPENCLAW_APNS_RELAY_BASE_URL` і `OPENCLAW_APNS_RELAY_TIMEOUT_MS` усе ще працюють як тимчасові перевизначення через env. - - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` залишається суто loopback-режимом для розробки; не зберігайте HTTP URL relay у конфігурації. + - `OPENCLAW_APNS_RELAY_BASE_URL` і `OPENCLAW_APNS_RELAY_TIMEOUT_MS` як і раніше працюють як тимчасові перевизначення через env. + - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` залишається тимчасовим засобом розробки лише для loopback; не зберігайте HTTP URL relay у конфігурації. - Див. [iOS App](/uk/platforms/ios#relay-backed-push-for-official-builds) для повного наскрізного процесу та [Потік автентифікації й довіри](/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. - + ```json5 { agents: { @@ -399,12 +399,12 @@ Gateway також зберігає довірену останню відому - `every`: рядок тривалості (`30m`, `2h`). Установіть `0m`, щоб вимкнути. - `target`: `last` | `none` | `` (наприклад, `discord`, `matrix`, `telegram` або `whatsapp`) - - `directPolicy`: `allow` (типово) або `block` для heartbeat-цілей у стилі DM - - Див. [Heartbeat](/uk/gateway/heartbeat) для повного посібника. + - `directPolicy`: `allow` (типово) або `block` для цілей Heartbeat у стилі DM + - Повний посібник див. у [Heartbeat](/uk/gateway/heartbeat). - + ```json5 { cron: { @@ -419,14 +419,14 @@ Gateway також зберігає довірену останню відому } ``` - - `sessionRetention`: видаляти завершені ізольовані сесії запуску з `sessions.json` (типово `24h`; установіть `false`, щоб вимкнути). - - `runLog`: очищати `cron/runs/.jsonl` за розміром і кількістю збережених рядків. - - Див. [Завдання Cron](/uk/automation/cron-jobs) для огляду можливостей і прикладів CLI. + - `sessionRetention`: видаляти завершені ізольовані сесії виконання з `sessions.json` (типово `24h`; установіть `false`, щоб вимкнути). + - `runLog`: обрізати `cron/runs/.jsonl` за розміром і кількістю збережених рядків. + - Огляд можливостей і приклади CLI див. у [Cron jobs](/uk/automation/cron-jobs). - - Увімкніть HTTP endpoint Webhook на Gateway: + + Увімкніть HTTP-ендпоїнти Webhook у Gateway: ```json5 { @@ -450,20 +450,20 @@ Gateway також зберігає довірену останню відому ``` Примітка щодо безпеки: - - Розглядайте весь вміст payload hook/webhook як недовірений вхід. + - Вважайте весь вміст payload hook/Webhook недовіреним введенням. - Використовуйте окремий `hooks.token`; не використовуйте повторно спільний токен Gateway. - - Автентифікація hook виконується лише через заголовки (`Authorization: Bearer ...` або `x-openclaw-token`); токени в query string відхиляються. - - `hooks.path` не може бути `/`; використовуйте для webhook ingress окремий підшлях, наприклад `/hooks`. - - Прапорці обходу небезпечного вмісту (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`) мають залишатися вимкненими, якщо ви не виконуєте вузькоспрямоване налагодження. - - Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також задайте `hooks.allowedSessionKeyPrefixes`, щоб обмежити ключі сесій, які може вибирати викликач. - - Для агентів, що працюють через hooks, віддавайте перевагу сильним сучасним рівням моделей і суворій політиці інструментів (наприклад, лише обмін повідомленнями плюс ізоляція, де це можливо). + - Автентифікація hook виконується лише через заголовки (`Authorization: Bearer ...` або `x-openclaw-token`); токени в рядку запиту відхиляються. + - `hooks.path` не може бути `/`; тримайте вхідний трафік Webhook на окремому підшляху, наприклад `/hooks`. + - Залишайте прапори обходу небезпечного вмісту вимкненими (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), якщо не виконуєте вузькоспрямоване налагодження. + - Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також установіть `hooks.allowedSessionKeyPrefixes`, щоб обмежити ключі сесій, які вибирає викликач. + - Для агентів, що запускаються через hook, віддавайте перевагу сильним сучасним рівням моделей і суворій політиці інструментів (наприклад, лише обмін повідомленнями плюс ізоляція, де це можливо). - Див. [повний довідник](/uk/gateway/configuration-reference#hooks) для всіх варіантів mapping та інтеграції Gmail. + Усі параметри мапінгу та інтеграцію Gmail див. у [повному довіднику](/uk/gateway/configuration-reference#hooks). - - Запускайте кілька ізольованих агентів з окремими workspace і сесіями: + + Запускайте кількох ізольованих агентів з окремими робочими просторами та сесіями: ```json5 { @@ -480,12 +480,12 @@ Gateway також зберігає довірену останню відому } ``` - Див. [Multi-Agent](/uk/concepts/multi-agent) і [повний довідник](/uk/gateway/configuration-reference#multi-agent-routing) для правил binding і профілів доступу для кожного агента. + Правила binding та профілі доступу для кожного агента див. у [Multi-Agent](/uk/concepts/multi-agent) і [повному довіднику](/uk/gateway/configuration-reference#multi-agent-routing). - - Використовуйте `$include`, щоб організувати великі конфігурації: + + Використовуйте `$include`, щоб упорядковувати великі конфігурації: ```json5 // ~/.openclaw/openclaw.json @@ -498,41 +498,40 @@ Gateway також зберігає довірену останню відому } ``` - - **Один файл**: замінює об’єкт, у якому вказаний - - **Масив файлів**: виконується глибоке злиття за порядком (пізніші мають пріоритет) - - **Сусідні ключі**: зливаються після include (перевизначають включені значення) - - **Вкладені include**: підтримуються до 10 рівнів вкладеності - - **Відносні шляхи**: обчислюються відносно файла, який містить include - - **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок парсингу та циклічних include + - **Один файл**: замінює об’єкт-контейнер + - **Масив файлів**: глибоко зливається по порядку (пізніший має пріоритет) + - **Сусідні ключі**: зливаються після include-ів (перевизначають включені значення) + - **Вкладені include-и**: підтримуються до 10 рівнів вкладеності + - **Відносні шляхи**: обчислюються відносно файла, що включає + - **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок парсингу та циклічних include-ів ## Гаряче перезавантаження конфігурації -Gateway відстежує `~/.openclaw/openclaw.json` і автоматично застосовує зміни — для більшості параметрів ручний перезапуск не потрібен. +Gateway відстежує `~/.openclaw/openclaw.json` і автоматично застосовує зміни — для більшості налаштувань ручний перезапуск не потрібен. -Прямі редагування файла вважаються недовіреними, доки не пройдуть валідацію. Спостерігач -чекає, поки завершаться тимчасові записи/перейменування редактора, зчитує фінальний файл і відхиляє -некоректні зовнішні редагування, відновлюючи останню відому справну конфігурацію. Власні -записи конфігурації OpenClaw проходять ту саму перевірку схемою перед записом; руйнівні перезаписи, -наприклад видалення `gateway.mode` або зменшення файла більш ніж удвічі, відхиляються +Прямі редагування файла вважаються недовіреними, доки не пройдуть валідацію. Спостерігач чекає, +поки завершаться тимчасові записи/перейменування редактора, зчитує фінальний файл і відхиляє +некоректні зовнішні зміни, відновлюючи останню справну конфігурацію. Власні записи конфігурації OpenClaw +використовують той самий бар’єр схеми перед записом; руйнівні перезаписи на кшталт +видалення `gateway.mode` або зменшення файла більш ніж наполовину відхиляються і зберігаються як `.rejected.*` для перевірки. -Якщо ви бачите в логах `Config auto-restored from last-known-good` або -`config reload 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) -для контрольного списку відновлення. +`openclaw config validate`. Контрольний список відновлення див. у [усуненні несправностей Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config). ### Режими перезавантаження -| Режим | Поведінка | -| ---------------------- | -------------------------------------------------------------------------------------- | -| **`hybrid`** (типово) | Миттєво гаряче застосовує безпечні зміни. Для критичних автоматично перезапускається. | -| **`hot`** | Гаряче застосовує лише безпечні зміни. Логує попередження, коли потрібен перезапуск — далі дієте ви. | -| **`restart`** | Перезапускає Gateway за будь-якої зміни конфігурації, безпечної чи ні. | -| **`off`** | Вимикає відстеження файлів. Зміни набирають чинності після наступного ручного перезапуску. | +| Режим | Поведінка | +| ---------------------- | ---------------------------------------------------------------------------------------- | +| **`hybrid`** (типово) | Миттєво гаряче застосовує безпечні зміни. Автоматично перезапускається для критичних. | +| **`hot`** | Гаряче застосовує лише безпечні зміни. Логує попередження, коли потрібен перезапуск — ви обробляєте це самі. | +| **`restart`** | Перезапускає Gateway за будь-якої зміни конфігурації, безпечної чи ні. | +| **`off`** | Вимикає відстеження файла. Зміни набирають чинності під час наступного ручного перезапуску. | ```json5 { @@ -546,42 +545,42 @@ Gateway відстежує `~/.openclaw/openclaw.json` і автоматично Більшість полів застосовуються гаряче без простою. У режимі `hybrid` зміни, що потребують перезапуску, обробляються автоматично. -| Категорія | Поля | Потрібен перезапуск? | -| ----------------- | -------------------------------------------------------------------- | -------------------- | -| Канали | `channels.*`, `web` (WhatsApp) — усі вбудовані канали й канали extension | Ні | -| Агент і моделі | `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) — усі вбудовані канали й канали розширень | Ні | +| Агент і моделі | `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` є винятками — їх зміна **не** спричиняє перезапуск. -## RPC конфігурації (програмні оновлення) +## Config RPC (програмні оновлення) -RPC control-plane для запису (`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`: отримати поточний snapshot + hash -- `config.patch`: бажаний шлях для часткових оновлень +- `config.schema.lookup`: переглянути одне піддерево конфігурації з певною областю шляху з неглибоким + вузлом схеми, відповідними метаданими підказок і короткими описами безпосередніх дочірніх елементів +- `config.get`: отримати поточний знімок + хеш +- `config.patch`: рекомендований шлях часткового оновлення - `config.apply`: лише повна заміна конфігурації - `update.run`: явне самооновлення + перезапуск -Якщо ви не замінюєте всю конфігурацію, віддавайте перевагу `config.schema.lookup`, +Якщо ви не замінюєте всю конфігурацію повністю, надавайте перевагу `config.schema.lookup`, а потім `config.patch`. - Виконує валідацію + записує всю конфігурацію та перезапускає Gateway за один крок. + Перевіряє + записує повну конфігурацію і перезапускає Gateway за один крок. `config.apply` замінює **всю конфігурацію**. Для часткових оновлень використовуйте `config.patch`, а для окремих ключів — `openclaw config set`. @@ -590,15 +589,15 @@ RPC control-plane для запису (`config.apply`, `config.patch`, `update.r Параметри: - `raw` (string) — payload JSON5 для всієї конфігурації - - `baseHash` (необов’язково) — хеш конфігурації з `config.get` (обов’язковий, якщо конфігурація існує) - - `sessionKey` (необов’язково) — ключ сесії для ping пробудження після перезапуску - - `note` (необов’язково) — примітка для sentinel перезапуску - - `restartDelayMs` (необов’язково) — затримка перед перезапуском (типово 2000) + - `baseHash` (optional) — хеш конфігурації з `config.get` (обов’язковий, якщо конфігурація існує) + - `sessionKey` (optional) — ключ сесії для ping пробудження після перезапуску + - `note` (optional) — примітка для restart sentinel + - `restartDelayMs` (optional) — затримка перед перезапуском (типово 2000) - Запити на перезапуск об’єднуються, якщо один уже очікує виконання/виконується, а між циклами перезапуску діє 30-секундна пауза. + Запити на перезапуск об’єднуються, якщо один уже очікує/виконується, і між циклами перезапуску діє 30-секундний період охолодження. ```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": "", @@ -609,7 +608,7 @@ RPC control-plane для запису (`config.apply`, `config.patch`, `update.r - Зливає часткове оновлення з наявною конфігурацією (семантика JSON merge patch): + Зливає часткове оновлення в наявну конфігурацію (семантика JSON merge patch): - Об’єкти зливаються рекурсивно - `null` видаляє ключ @@ -617,11 +616,11 @@ RPC control-plane для запису (`config.apply`, `config.patch`, `update.r Параметри: - - `raw` (string) — JSON5 лише з ключами, які потрібно змінити - - `baseHash` (обов’язково) — хеш конфігурації з `config.get` - - `sessionKey`, `note`, `restartDelayMs` — такі самі, як у `config.apply` + - `raw` (string) — JSON5 лише з тими ключами, які потрібно змінити + - `baseHash` (required) — хеш конфігурації з `config.get` + - `sessionKey`, `note`, `restartDelayMs` — те саме, що й у `config.apply` - Поведінка перезапуску збігається з `config.apply`: об’єднання перезапусків, що очікують виконання, плюс 30-секундна пауза між циклами перезапуску. + Поведінка перезапуску відповідає `config.apply`: об’єднання відкладених перезапусків плюс 30-секундний період охолодження між циклами перезапуску. ```bash openclaw gateway call config.patch --params '{ @@ -635,12 +634,12 @@ RPC control-plane для запису (`config.apply`, `config.patch`, `update.r ## Змінні середовища -OpenClaw зчитує змінні середовища з батьківського процесу, а також з: +OpenClaw зчитує змінні середовища з батьківського процесу, а також із: -- `.env` у поточному робочому каталозі (якщо є) -- `~/.openclaw/.env` (глобальний запасний варіант) +- `.env` у поточному робочому каталозі (якщо наявний) +- `~/.openclaw/.env` (глобальний резервний варіант) -Жоден із цих файлів не перевизначає наявні змінні середовища. Ви також можете задавати вбудовані змінні середовища в конфігурації: +Жоден із цих файлів не перевизначає вже наявні змінні середовища. Ви також можете задавати вбудовані змінні середовища в конфігурації: ```json5 { @@ -652,7 +651,7 @@ OpenClaw зчитує змінні середовища з батьківськ ``` - Якщо цю опцію ввімкнено, а очікувані ключі не задано, OpenClaw запускає вашу login shell і імпортує лише відсутні ключі: + Якщо це ввімкнено і очікувані ключі не задані, OpenClaw запускає вашу login shell і імпортує лише відсутні ключі: ```json5 { @@ -662,10 +661,10 @@ OpenClaw зчитує змінні середовища з батьківськ } ``` -Еквівалентна змінна середовища: `OPENCLAW_LOAD_SHELL_ENV=1` +Еквівалент змінної середовища: `OPENCLAW_LOAD_SHELL_ENV=1` - + Посилайтеся на змінні середовища в будь-якому рядковому значенні конфігурації за допомогою `${VAR_NAME}`: ```json5 @@ -677,16 +676,16 @@ OpenClaw зчитує змінні середовища з батьківськ Правила: -- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*` +- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*` - Відсутні/порожні змінні спричиняють помилку під час завантаження -- Екрануйте через `$${VAR}` для буквального виводу +- Екрануйте як `$${VAR}` для буквального виводу - Працює всередині файлів `$include` - Вбудована підстановка: `"${BASE}/v1"` → `"https://api.example.com/v1"` - - Для полів, що підтримують об’єкти SecretRef, можна використовувати: + + Для полів, що підтримують об’єкти SecretRef, ви можете використовувати: ```json5 { @@ -718,15 +717,15 @@ OpenClaw зчитує змінні середовища з батьківськ } ``` -Подробиці 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/sandbox-vs-tool-policy-vs-elevated.md b/docs/uk/gateway/sandbox-vs-tool-policy-vs-elevated.md index 808cfc659..0867c97bc 100644 --- a/docs/uk/gateway/sandbox-vs-tool-policy-vs-elevated.md +++ b/docs/uk/gateway/sandbox-vs-tool-policy-vs-elevated.md @@ -1,28 +1,28 @@ --- read_when: You hit 'sandbox jail' or see a tool/elevated refusal and want the exact config key to change. status: active -summary: 'Чому інструмент заблоковано: runtime sandbox, політика allow/deny інструментів і механізми elevated для exec' -title: Sandbox vs Tool Policy vs Elevated +summary: 'Чому інструмент заблоковано: середовище виконання sandbox, політика дозволу/заборони інструментів і шлюзи підвищеного виконання' +title: Sandbox проти політики інструментів проти підвищеного виконання x-i18n: - generated_at: "2026-04-05T18:04:38Z" + generated_at: "2026-04-20T18:29:31Z" model: gpt-5.4 provider: openai - source_hash: 331f5b2f0d5effa1320125d9f29948e16d0deaffa59eb1e4f25a63481cbe22d6 + source_hash: a85378343df0594be451212cb4c95b349a0cc7cd1f242b9306be89903a450db1 source_path: gateway/sandbox-vs-tool-policy-vs-elevated.md workflow: 15 --- -# Sandbox vs Tool Policy vs Elevated +# Sandbox проти політики інструментів проти підвищеного виконання OpenClaw має три пов’язані (але різні) механізми керування: -1. **Sandbox** (`agents.defaults.sandbox.*` / `agents.list[].sandbox.*`) визначає, **де запускаються інструменти** (Docker чи хост). +1. **Sandbox** (`agents.defaults.sandbox.*` / `agents.list[].sandbox.*`) визначає, **де запускаються інструменти** (бекенд sandbox чи хост). 2. **Політика інструментів** (`tools.*`, `tools.sandbox.tools.*`, `agents.list[].tools.*`) визначає, **які інструменти доступні/дозволені**. -3. **Elevated** (`tools.elevated.*`, `agents.list[].tools.elevated.*`) — це **лише для exec механізм обходу**, щоб запускати поза sandbox, коли ви перебуваєте в sandbox (`gateway` типово або `node`, коли exec target налаштовано як `node`). +3. **Elevated** (`tools.elevated.*`, `agents.list[].tools.elevated.*`) — це **лише для exec аварійний обхід** для запуску поза sandbox, коли ви працюєте в sandbox (`gateway` за замовчуванням або `node`, якщо ціль exec налаштована на `node`). -## Швидке налагодження +## Швидка діагностика -Використовуйте inspector, щоб побачити, що OpenClaw _насправді_ робить: +Використовуйте інспектор, щоб побачити, що OpenClaw _насправді_ робить: ```bash openclaw sandbox explain @@ -33,52 +33,52 @@ openclaw sandbox explain --json Він показує: -- ефективний режим/scope/workspace access sandbox -- чи сесія зараз працює в sandbox (main чи non-main) -- ефективний allow/deny інструментів sandbox (і чи походить він від agent/global/default) -- механізми elevated і ключі шляхів fix-it +- ефективний режим/область sandbox/доступ до робочого простору +- чи сесія зараз працює в sandbox (main проти non-main) +- ефективні правила allow/deny для інструментів у sandbox (і чи вони надійшли від агента/глобально/за замовчуванням) +- шлюзи elevated і шляхи ключів для виправлення ## Sandbox: де запускаються інструменти -Sandboxing керується через `agents.defaults.sandbox.mode`: +Робота sandbox керується через `agents.defaults.sandbox.mode`: - `"off"`: усе запускається на хості. -- `"non-main"`: у sandbox працюють лише не-main сесії (поширений “сюрприз” для groups/channels). -- `"all"`: усе працює в sandbox. +- `"non-main"`: у sandbox запускаються лише non-main сесії (типовий «сюрприз» для груп/каналів). +- `"all"`: у sandbox запускається все. -Повну матрицю (scope, монтування workspace, images) див. у [Sandboxing](/gateway/sandboxing). +Повну матрицю дивіться в [Sandboxing](/uk/gateway/sandboxing) (область, монтування робочого простору, образи). ### Bind mounts (швидка перевірка безпеки) -- `docker.binds` _пробиває_ файлову систему sandbox: усе, що ви монтуєте, стає видимим усередині контейнера з указаним режимом (`:ro` або `:rw`). -- Якщо не вказати режим, типово використовується read-write; для source/secrets віддавайте перевагу `:ro`. -- `scope: "shared"` ігнорує bind для кожного агента окремо (застосовуються лише глобальні bind). -- OpenClaw двічі перевіряє джерела bind: спочатку на нормалізованому шляху джерела, потім ще раз після визначення через найглибший наявний батьківський каталог. Вихід через symlink-батьківський шлях не обходить перевірки blocked-path або allowed-root. -- Неіснуючі leaf-шляхи все одно безпечно перевіряються. Якщо `/workspace/alias-out/new-file` визначається через symlink-батьківський каталог у заблокований шлях або поза межами налаштованих allowed roots, bind буде відхилено. -- Монтування `/var/run/docker.sock` фактично передає контроль над хостом у sandbox; робіть це лише свідомо. -- Доступ до workspace (`workspaceAccess: "ro"`/`"rw"`) не залежить від режимів bind. +- `docker.binds` _прориває_ файлову систему sandbox: усе, що ви змонтуєте, буде видиме всередині контейнера з указаним режимом (`:ro` або `:rw`). +- За замовчуванням використовується читання-запис, якщо режим не вказано; для вихідного коду/секретів краще використовувати `:ro`. +- `scope: "shared"` ігнорує bind-монтування для окремих агентів (застосовуються лише глобальні bind-монтування). +- OpenClaw двічі перевіряє джерела bind-монтувань: спочатку на нормалізованому шляху джерела, а потім повторно після розв’язання через найглибший наявний батьківський каталог. Обхід через батьківські symlink не дозволяє обійти перевірки заблокованих шляхів або дозволених коренів. +- Навіть неіснуючі кінцеві шляхи все одно безпечно перевіряються. Якщо `/workspace/alias-out/new-file` розв’язується через symlink-батьківський каталог у заблокований шлях або за межі налаштованих дозволених коренів, bind-монтування буде відхилено. +- Монтування `/var/run/docker.sock` фактично передає керування хостом sandbox; робіть це лише свідомо. +- Доступ до робочого простору (`workspaceAccess: "ro"`/`"rw"`) не залежить від режимів bind-монтування. -## Політика інструментів: які інструменти існують/можна викликати +## Політика інструментів: які інструменти існують/можуть викликатися Важливі два рівні: -- **Профіль інструментів**: `tools.profile` і `agents.list[].tools.profile` (базовий allowlist) +- **Профіль інструментів**: `tools.profile` і `agents.list[].tools.profile` (базовий список дозволених) - **Профіль інструментів провайдера**: `tools.byProvider[provider].profile` і `agents.list[].tools.byProvider[provider].profile` -- **Глобальна/для кожного агента окремо політика інструментів**: `tools.allow`/`tools.deny` і `agents.list[].tools.allow`/`agents.list[].tools.deny` +- **Глобальна/персональна політика інструментів агента**: `tools.allow`/`tools.deny` і `agents.list[].tools.allow`/`agents.list[].tools.deny` - **Політика інструментів провайдера**: `tools.byProvider[provider].allow/deny` і `agents.list[].tools.byProvider[provider].allow/deny` - **Політика інструментів sandbox** (застосовується лише в sandbox): `tools.sandbox.tools.allow`/`tools.sandbox.tools.deny` і `agents.list[].tools.sandbox.tools.*` -Основні правила: +Базові правила: -- `deny` завжди має перевагу. +- `deny` завжди має пріоритет. - Якщо `allow` не порожній, усе інше вважається заблокованим. - Політика інструментів — це жорстке обмеження: `/exec` не може перевизначити заборонений інструмент `exec`. -- `/exec` лише змінює типові значення сесії для авторизованих відправників; він не надає доступ до інструментів. - Ключі інструментів провайдера приймають або `provider` (наприклад, `google-antigravity`), або `provider/model` (наприклад, `openai/gpt-5.4`). +- `/exec` лише змінює налаштування сесії за замовчуванням для авторизованих відправників; він не надає доступ до інструментів. + Ключі інструментів провайдера можуть приймати або `provider` (наприклад, `google-antigravity`), або `provider/model` (наприклад, `openai/gpt-5.4`). ### Групи інструментів (скорочення) -Політики інструментів (глобальні, для агента, для sandbox) підтримують записи `group:*`, які розгортаються в кілька інструментів: +Політики інструментів (глобальні, агентські, sandbox) підтримують записи `group:*`, які розгортаються в кілька інструментів: ```json5 { @@ -94,7 +94,8 @@ Sandboxing керується через `agents.defaults.sandbox.mode`: Доступні групи: -- `group:runtime`: `exec`, `process`, `code_execution` (`bash` приймається як псевдонім для `exec`) +- `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` @@ -105,43 +106,43 @@ Sandboxing керується через `agents.defaults.sandbox.mode`: - `group:nodes`: `nodes` - `group:agents`: `agents_list` - `group:media`: `image`, `image_generate`, `video_generate`, `tts` -- `group:openclaw`: усі вбудовані інструменти OpenClaw (без provider plugins) +- `group:openclaw`: усі вбудовані інструменти OpenClaw (не включає Plugin провайдерів) -## Elevated: механізм "запустити на хості" лише для exec +## Elevated: exec-only «запуск на хості» Elevated **не** надає додаткових інструментів; він впливає лише на `exec`. -- Якщо ви в sandbox, `/elevated on` (або `exec` з `elevated: true`) запускається поза sandbox (при цьому підтвердження можуть усе ще застосовуватися). -- Використовуйте `/elevated full`, щоб пропустити підтвердження exec для сесії. -- Якщо ви вже працюєте напряму, elevated фактично нічого не змінює (але все одно керується механізмами доступу). -- Elevated **не** обмежується Skills і **не** перевизначає allow/deny інструментів. -- Elevated не надає довільних міжхостових перевизначень із `host=auto`; він дотримується звичайних правил exec target і зберігає `node` лише тоді, коли налаштований/сесійний target уже дорівнює `node`. -- `/exec` — це окремий механізм від elevated. Він лише налаштовує типові параметри exec для сесії для авторизованих відправників. +- Якщо ви в sandbox, `/elevated on` (або `exec` з `elevated: true`) запускає виконання поза sandbox (схвалення все одно можуть застосовуватися). +- Використовуйте `/elevated full`, щоб пропустити схвалення exec для сесії. +- Якщо ви вже працюєте напряму, elevated фактично нічого не змінює (але все одно проходить через шлюзи). +- Elevated **не** має області дії Skills і **не** перевизначає правила allow/deny для інструментів. +- Elevated не надає довільних міжхостових перевизначень із `host=auto`; він дотримується звичайних правил цілі exec і лише зберігає `node`, якщо налаштована/сесійна ціль уже встановлена як `node`. +- `/exec` — це окремий механізм від elevated. Він лише коригує стандартні параметри exec для сесії для авторизованих відправників. -Механізми доступу: +Шлюзи: - Увімкнення: `tools.elevated.enabled` (і, за потреби, `agents.list[].tools.elevated.enabled`) -- Allowlist відправників: `tools.elevated.allowFrom.` (і, за потреби, `agents.list[].tools.elevated.allowFrom.`) +- Списки дозволених відправників: `tools.elevated.allowFrom.` (і, за потреби, `agents.list[].tools.elevated.allowFrom.`) -Див. [Elevated Mode](/tools/elevated). +Див. [Elevated Mode](/uk/tools/elevated). -## Типові виправлення "sandbox jail" +## Типові виправлення «sandbox jail» -### "Tool X blocked by sandbox tool policy" +### «Інструмент X заблоковано політикою інструментів sandbox» -Ключі fix-it (виберіть один): +Ключі для виправлення (виберіть один): -- Вимкнути sandbox: `agents.defaults.sandbox.mode=off` (або для конкретного агента `agents.list[].sandbox.mode=off`) +- Вимкнути sandbox: `agents.defaults.sandbox.mode=off` (або для окремого агента `agents.list[].sandbox.mode=off`) - Дозволити інструмент усередині sandbox: - - прибрати його з `tools.sandbox.tools.deny` (або для конкретного агента `agents.list[].tools.sandbox.tools.deny`) - - або додати його до `tools.sandbox.tools.allow` (або до allow для агента) + - видалити його з `tools.sandbox.tools.deny` (або для окремого агента `agents.list[].tools.sandbox.tools.deny`) + - або додати його до `tools.sandbox.tools.allow` (або до allow для окремого агента) -### "I thought this was main, why is it sandboxed?" +### «Я думав, що це main, чому воно в sandbox?» -У режимі `"non-main"` ключі group/channel _не_ є main. Використовуйте ключ main session (його показує `sandbox explain`) або змініть режим на `"off"`. +У режимі `"non-main"` ключі груп/каналів _не_ є main. Використовуйте ключ main-сесії (показується через `sandbox explain`) або перемкніть режим на `"off"`. ## Див. також -- [Sandboxing](/gateway/sandboxing) -- повний довідник із sandbox (режими, scope, backend, images) -- [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) -- перевизначення для кожного агента окремо та пріоритетність -- [Elevated Mode](/tools/elevated) +- [Sandboxing](/uk/gateway/sandboxing) -- повний довідник із sandbox (режими, області, бекенди, образи) +- [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools) -- перевизначення для окремих агентів і пріоритетність +- [Elevated Mode](/uk/tools/elevated) diff --git a/docs/uk/gateway/sandboxing.md b/docs/uk/gateway/sandboxing.md index 7500b7e47..2923325dc 100644 --- a/docs/uk/gateway/sandboxing.md +++ b/docs/uk/gateway/sandboxing.md @@ -1,104 +1,107 @@ --- read_when: You want a dedicated explanation of sandboxing or need to tune agents.defaults.sandbox. status: active -summary: 'Як працює ізоляція OpenClaw: режими, області дії, доступ до робочого простору та зображення' -title: Ізоляція +summary: 'Як працює пісочниця OpenClaw: режими, області дії, доступ до робочого простору та зображення' +title: Пісочниця x-i18n: - generated_at: "2026-04-14T01:21:00Z" + generated_at: "2026-04-20T18:29:25Z" model: gpt-5.4 provider: openai - source_hash: 2573d0d7462f63a68eb1750e5432211522ff5b42989a17379d3e188468bbce52 + source_hash: 35405c103f37f7f7247462ed5bc54a4b0d2a19ca2a373cf10f7f231a62c2c7c4 source_path: gateway/sandboxing.md workflow: 15 --- -# Ізоляція +# Пісочниця -OpenClaw може запускати **інструменти всередині бекендів ізоляції**, щоб зменшити радіус ураження. +OpenClaw може запускати **інструменти всередині бекендів пісочниці**, щоб зменшити радіус ураження. Це **необов’язково** і керується конфігурацією (`agents.defaults.sandbox` або -`agents.list[].sandbox`). Якщо ізоляцію вимкнено, інструменти працюють на хості. -Gateway залишається на хості; виконання інструментів відбувається в ізольованому середовищі ізоляції, -коли цю функцію ввімкнено. +`agents.list[].sandbox`). Якщо пісочницю вимкнено, інструменти запускаються на хості. +Gateway залишається на хості; виконання інструментів відбувається в ізольованій пісочниці, +коли її ввімкнено. Це не є ідеальною межею безпеки, але суттєво обмежує доступ до файлової системи -та процесів, коли модель робить щось нерозумне. +та процесів, коли модель робить щось необачне. -## Що ізолюється +## Що поміщається в пісочницю - Виконання інструментів (`exec`, `read`, `write`, `edit`, `apply_patch`, `process` тощо). -- Необов’язковий браузер в ізоляції (`agents.defaults.sandbox.browser`). - - За замовчуванням браузер в ізоляції запускається автоматично (щоб CDP був доступний), коли він потрібен інструменту браузера. +- Необов’язковий браузер у пісочниці (`agents.defaults.sandbox.browser`). + - За замовчуванням браузер у пісочниці запускається автоматично (щоб CDP був доступний), коли він потрібен інструменту браузера. Налаштовується через `agents.defaults.sandbox.browser.autoStart` і `agents.defaults.sandbox.browser.autoStartTimeoutMs`. - - За замовчуванням контейнери браузера в ізоляції використовують виділену мережу Docker (`openclaw-sandbox-browser`) замість глобальної мережі `bridge`. + - За замовчуванням контейнери браузера в пісочниці використовують виділену мережу Docker (`openclaw-sandbox-browser`) замість глобальної мережі `bridge`. Налаштовується через `agents.defaults.sandbox.browser.network`. - Необов’язковий параметр `agents.defaults.sandbox.browser.cdpSourceRange` обмежує вхідний доступ до CDP на межі контейнера за допомогою списку дозволених CIDR (наприклад, `172.21.0.1/32`). - - Доступ спостерігача noVNC за замовчуванням захищено паролем; OpenClaw генерує короткочасну URL-адресу з токеном, яка відкриває локальну bootstrap-сторінку і запускає noVNC з паролем у фрагменті URL (а не в журналах запитів/заголовків). - - `agents.defaults.sandbox.browser.allowHostControl` дозволяє сеансам в ізоляції явно звертатися до браузера хоста. - - Необов’язкові списки дозволів контролюють `target: "custom"`: `allowedControlUrls`, `allowedControlHosts`, `allowedControlPorts`. + - Доступ спостерігача noVNC за замовчуванням захищений паролем; OpenClaw генерує короткочасний URL із токеном, який віддає локальну bootstrap-сторінку та відкриває noVNC з паролем у фрагменті URL (а не в логах query/header). + - `agents.defaults.sandbox.browser.allowHostControl` дозволяє сесіям у пісочниці явно націлюватися на браузер хоста. + - Необов’язкові списки дозволених значень обмежують `target: "custom"`: `allowedControlUrls`, `allowedControlHosts`, `allowedControlPorts`. -Не ізолюються: +Не поміщається в пісочницю: - Сам процес Gateway. -- Будь-який інструмент, якому явно дозволено працювати поза ізоляцією (наприклад, `tools.elevated`). - - **Elevated exec обходить ізоляцію і використовує налаштований шлях виходу (`gateway` за замовчуванням або `node`, коли ціллю exec є `node`).** - - Якщо ізоляцію вимкнено, `tools.elevated` не змінює виконання (воно й так уже на хості). Див. [Режим Elevated](/uk/tools/elevated). +- Будь-який інструмент, якому явно дозволено працювати поза пісочницею (наприклад, `tools.elevated`). + - **Elevated exec обходить пісочницю і використовує налаштований шлях виходу (`gateway` за замовчуванням або `node`, коли ціль exec — `node`).** + - Якщо пісочницю вимкнено, `tools.elevated` не змінює виконання (воно й так на хості). Див. [Режим Elevated](/uk/tools/elevated). ## Режими -`agents.defaults.sandbox.mode` керує **коли** використовується ізоляція: +`agents.defaults.sandbox.mode` керує **тим, коли** використовується пісочниця: -- `"off"`: без ізоляції. -- `"non-main"`: ізолюються лише **неосновні** сеанси (типовий варіант, якщо ви хочете, щоб звичайні чати працювали на хості). -- `"all"`: кожен сеанс працює в ізоляції. - Примітка: `"non-main"` визначається за `session.mainKey` (типово `"main"`), а не за id агента. - Сеанси груп/каналів використовують власні ключі, тож вони вважаються неосновними й будуть ізольовані. +- `"off"`: без пісочниці. +- `"non-main"`: пісочниця лише для **не-main** сесій (типово, якщо ви хочете, щоб звичайні чати працювали на хості). +- `"all"`: кожна сесія запускається в пісочниці. + Примітка: `"non-main"` базується на `session.mainKey` (типово `"main"`), а не на id агента. + Сесії груп/каналів мають власні ключі, тому вважаються не-main і будуть у пісочниці. ## Область дії -`agents.defaults.sandbox.scope` керує **скільки контейнерів** створюється: +`agents.defaults.sandbox.scope` керує **тим, скільки контейнерів** створюється: - `"agent"` (типово): один контейнер на агента. -- `"session"`: один контейнер на сеанс. -- `"shared"`: один контейнер, спільний для всіх сеансів в ізоляції. +- `"session"`: один контейнер на сесію. +- `"shared"`: один контейнер, спільний для всіх сесій у пісочниці. ## Бекенд -`agents.defaults.sandbox.backend` керує **яке середовище виконання** надає ізоляцію: +`agents.defaults.sandbox.backend` керує **тим, яке середовище виконання** надає пісочницю: -- `"docker"` (типово): локальне середовище ізоляції на основі Docker. -- `"ssh"`: універсальне віддалене середовище ізоляції на основі SSH. -- `"openshell"`: середовище ізоляції на основі OpenShell. +- `"docker"` (типово, коли пісочницю ввімкнено): локальне середовище пісочниці на основі Docker. +- `"ssh"`: універсальне віддалене середовище пісочниці на основі SSH. +- `"openshell"`: середовище пісочниці на основі OpenShell. -Конфігурація, специфічна для SSH, розміщується в `agents.defaults.sandbox.ssh`. -Конфігурація, специфічна для OpenShell, розміщується в `plugins.entries.openshell.config`. +Конфігурація, специфічна для SSH, розташована в `agents.defaults.sandbox.ssh`. +Конфігурація, специфічна для OpenShell, розташована в `plugins.entries.openshell.config`. ### Вибір бекенда | | Docker | SSH | OpenShell | | ------------------- | -------------------------------- | ------------------------------ | ---------------------------------------------------------- | -| **Де виконується** | Локальний контейнер | Будь-який хост, доступний по SSH | Кероване OpenShell середовище ізоляції | -| **Налаштування** | `scripts/sandbox-setup.sh` | SSH-ключ + цільовий хост | Увімкнений Plugin OpenShell | -| **Модель робочого простору** | Bind mount або копіювання | Віддалений як канонічний (одноразове початкове заповнення) | `mirror` або `remote` | -| **Керування мережею** | `docker.network` (типово: none) | Залежить від віддаленого хоста | Залежить від OpenShell | -| **Ізоляція браузера** | Підтримується | Не підтримується | Ще не підтримується | -| **Bind mounts** | `docker.binds` | N/A | N/A | -| **Найкраще підходить для** | Локальної розробки, повної ізоляції | Винесення на віддалену машину | Керованих віддалених середовищ ізоляції з необов’язковою двосторонньою синхронізацією | +| **Де працює** | Локальний контейнер | Будь-який хост, доступний по SSH | Пісочниця під керуванням OpenShell | +| **Налаштування** | `scripts/sandbox-setup.sh` | Ключ SSH + цільовий хост | Увімкнений Plugin OpenShell | +| **Модель workspace** | Bind-mount або копіювання | Віддалений canonical (одноразове початкове заповнення) | `mirror` або `remote` | +| **Керування мережею** | `docker.network` (типово: none) | Залежить від віддаленого хоста | Залежить від OpenShell | +| **Браузер у пісочниці** | Підтримується | Не підтримується | Ще не підтримується | +| **Bind mounts** | `docker.binds` | Н/Д | Н/Д | +| **Найкраще для** | Локальна розробка, повна ізоляція | Вивантаження на віддалену машину | Керовані віддалені пісочниці з необов’язковою двосторонньою синхронізацією | ### Бекенд Docker -Бекенд Docker є типовим середовищем виконання: він локально запускає інструменти та браузери в ізоляції через сокет демона Docker (`/var/run/docker.sock`). Ізоляція контейнера визначається просторами імен Docker. +Пісочниця за замовчуванням вимкнена. Якщо ви вмикаєте пісочницю і не вибираєте +бекенд, OpenClaw використовує бекенд Docker. Він виконує інструменти й браузери +в пісочниці локально через сокет демона Docker (`/var/run/docker.sock`). Ізоляція +контейнера пісочниці визначається просторами імен Docker. **Обмеження Docker-out-of-Docker (DooD)**: -Якщо ви розгортаєте сам Gateway OpenClaw як Docker-контейнер, він оркеструє сусідні контейнери ізоляції через Docker-сокет хоста (DooD). Це створює конкретне обмеження щодо відображення шляхів: +Якщо ви розгортаєте сам Gateway OpenClaw як контейнер Docker, він оркеструє сусідні контейнери пісочниці через Docker-сокет хоста (DooD). Це створює конкретне обмеження на зіставлення шляхів: -- **Конфігурація має використовувати шляхи хоста**: конфігурація `workspace` у `openclaw.json` ОБОВ’ЯЗКОВО повинна містити **абсолютний шлях хоста** (наприклад, `/home/user/.openclaw/workspaces`), а не внутрішній шлях контейнера Gateway. Коли OpenClaw просить демон Docker створити середовище ізоляції, демон інтерпретує шляхи відносно простору імен ОС хоста, а не простору імен Gateway. -- **Паритет FS Bridge (ідентичне відображення томів)**: нативний процес Gateway OpenClaw також записує heartbeat- та bridge-файли в каталог `workspace`. Оскільки Gateway інтерпретує той самий рядок (шлях хоста) всередині власного контейнеризованого середовища, розгортання Gateway ОБОВ’ЯЗКОВО повинно містити ідентичне відображення томів, яке нативно зв’язує простір імен хоста (`-v /home/user/.openclaw:/home/user/.openclaw`). +- **Конфігурація вимагає шляхів хоста**: конфігурація `workspace` у `openclaw.json` МАЄ містити **абсолютний шлях хоста** (наприклад, `/home/user/.openclaw/workspaces`), а не внутрішній шлях контейнера Gateway. Коли OpenClaw просить демон Docker запустити пісочницю, демон оцінює шляхи відносно простору імен ОС хоста, а не простору імен Gateway. +- **Паритет FS Bridge (ідентичне зіставлення томів)**: нативний процес Gateway OpenClaw також записує файли Heartbeat і bridge до каталогу `workspace`. Оскільки Gateway оцінює той самий рядок (шлях хоста) зі свого контейнеризованого середовища, розгортання Gateway МАЄ включати ідентичне зіставлення томів, яке нативно пов’язує простір імен хоста (`-v /home/user/.openclaw:/home/user/.openclaw`). -Якщо ви відображаєте шляхи внутрішньо без абсолютного паритету з хостом, OpenClaw нативно викидає помилку дозволів `EACCES` при спробі записати свій heartbeat у контейнерному середовищі, оскільки повністю кваліфікований рядок шляху нативно не існує. +Якщо ви зіставляєте шляхи внутрішньо без абсолютного паритету з хостом, OpenClaw нативно викидає помилку дозволів `EACCES`, намагаючись записати свій Heartbeat усередині контейнеризованого середовища, тому що повний рядок шляху нативно не існує. ### Бекенд SSH -Використовуйте `backend: "ssh"`, якщо ви хочете, щоб OpenClaw ізолював `exec`, файлові інструменти та читання медіа +Використовуйте `backend: "ssh"`, якщо хочете, щоб OpenClaw ізолював `exec`, файлові інструменти та читання медіа на довільній машині, доступній по SSH. ```json5 @@ -118,7 +121,7 @@ Gateway залишається на хості; виконання інстру identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // Або використовуйте SecretRefs / вбудований вміст замість локальних файлів: + // Or use SecretRefs / inline contents instead of local files: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -131,36 +134,36 @@ Gateway залишається на хості; виконання інстру Як це працює: -- OpenClaw створює віддалений кореневий каталог для кожної області дії в `sandbox.ssh.workspaceRoot`. -- При першому використанні після створення або повторного створення OpenClaw один раз заповнює цей віддалений робочий простір із локального. -- Після цього `exec`, `read`, `write`, `edit`, `apply_patch`, читання медіа в prompt і підготовка вхідних медіа виконуються безпосередньо у віддаленому робочому просторі через SSH. -- OpenClaw не синхронізує віддалені зміни назад у локальний робочий простір автоматично. +- OpenClaw створює віддалений корінь для кожної області дії в `sandbox.ssh.workspaceRoot`. +- Під час першого використання після створення або повторного створення OpenClaw один раз заповнює цей віддалений workspace з локального workspace. +- Після цього `exec`, `read`, `write`, `edit`, `apply_patch`, читання медіа з prompt і staging вхідних медіа працюють безпосередньо з віддаленим workspace через SSH. +- OpenClaw не синхронізує віддалені зміни назад у локальний workspace автоматично. Матеріали автентифікації: -- `identityFile`, `certificateFile`, `knownHostsFile`: використовують наявні локальні файли і передають їх через конфігурацію OpenSSH. -- `identityData`, `certificateData`, `knownHostsData`: використовують вбудовані рядки або SecretRefs. OpenClaw розв’язує їх через звичайний runtime snapshot секретів, записує у тимчасові файли з правами `0600` і видаляє, коли SSH-сеанс завершується. -- Якщо для одного й того самого елемента задано і `*File`, і `*Data`, для цього SSH-сеансу пріоритет має `*Data`. +- `identityFile`, `certificateFile`, `knownHostsFile`: використовують наявні локальні файли та передають їх через конфігурацію OpenSSH. +- `identityData`, `certificateData`, `knownHostsData`: використовують вбудовані рядки або SecretRefs. OpenClaw розв’язує їх через звичайний runtime snapshot секретів, записує у тимчасові файли з правами `0600` і видаляє, коли SSH-сесія завершується. +- Якщо для одного й того самого елемента задано і `*File`, і `*Data`, то для цієї SSH-сесії пріоритет має `*Data`. -Це модель, де **канонічним є віддалений стан**. Віддалений робочий простір SSH стає реальним станом ізоляції після початкового заповнення. +Це модель **remote-canonical**. Віддалений workspace SSH стає реальним станом пісочниці після початкового заповнення. Важливі наслідки: -- Локальні зміни на хості, зроблені поза OpenClaw після етапу початкового заповнення, не будуть видимі віддалено, доки ви не створите середовище ізоляції заново. -- `openclaw sandbox recreate` видаляє віддалений кореневий каталог для відповідної області дії та знову виконує початкове заповнення з локального джерела під час наступного використання. -- Ізоляція браузера не підтримується в бекенді SSH. +- Локальні редагування на хості, зроблені поза OpenClaw після етапу початкового заповнення, не будуть видимі віддалено, доки ви не створите пісочницю заново. +- `openclaw sandbox recreate` видаляє віддалений корінь для кожної області дії та знову заповнює його з локального під час наступного використання. +- Браузер у пісочниці не підтримується в бекенді SSH. - Налаштування `sandbox.docker.*` не застосовуються до бекенда SSH. ### Бекенд OpenShell -Використовуйте `backend: "openshell"`, якщо ви хочете, щоб OpenClaw ізолював інструменти в -керованому OpenShell віддаленому середовищі. Повний посібник із налаштування, довідник -з конфігурації та порівняння режимів робочого простору дивіться на -окремій [сторінці OpenShell](/uk/gateway/openshell). +Використовуйте `backend: "openshell"`, якщо хочете, щоб OpenClaw ізолював інструменти у +віддаленому середовищі під керуванням OpenShell. Повний посібник із налаштування, +довідник з конфігурації та порівняння режимів workspace дивіться на окремій +[сторінці OpenShell](/uk/gateway/openshell). -OpenShell повторно використовує той самий базовий транспорт SSH і той самий віддалений міст файлової системи, що й -універсальний бекенд SSH, і додає життєвий цикл, специфічний для OpenShell -(`sandbox create/get/delete`, `sandbox ssh-config`), а також необов’язковий режим робочого простору `mirror`. +OpenShell повторно використовує той самий базовий транспорт SSH і міст віддаленої файлової системи, що й +універсальний бекенд SSH, і додає життєвий цикл, специфічний для OpenShell, +(`sandbox create/get/delete`, `sandbox ssh-config`), а також необов’язковий режим workspace `mirror`. ```json5 { @@ -192,40 +195,40 @@ OpenShell повторно використовує той самий базов Режими OpenShell: -- `mirror` (типово): локальний робочий простір залишається канонічним. OpenClaw синхронізує локальні файли в OpenShell перед exec і синхронізує віддалений робочий простір назад після exec. -- `remote`: робочий простір OpenShell стає канонічним після створення середовища ізоляції. OpenClaw один раз заповнює віддалений робочий простір із локального, а потім файлові інструменти та exec працюють безпосередньо з віддаленим середовищем ізоляції без синхронізації змін назад. +- `mirror` (типово): локальний workspace залишається canonical. OpenClaw синхронізує локальні файли в OpenShell перед exec і синхронізує віддалений workspace назад після exec. +- `remote`: workspace OpenShell стає canonical після створення пісочниці. OpenClaw один раз заповнює віддалений workspace з локального, після чого файлові інструменти та exec працюють безпосередньо з віддаленою пісочницею без синхронізації змін назад. Деталі віддаленого транспорту: -- OpenClaw запитує в OpenShell конфігурацію SSH, специфічну для середовища ізоляції, через `openshell sandbox ssh-config `. -- Core записує цю конфігурацію SSH у тимчасовий файл, відкриває SSH-сеанс і повторно використовує той самий віддалений міст файлової системи, що й для `backend: "ssh"`. -- Лише в режимі `mirror` життєвий цикл відрізняється: синхронізація з локального на віддалений простір перед exec, а потім синхронізація назад. +- OpenClaw запитує в OpenShell SSH-конфігурацію, специфічну для пісочниці, через `openshell sandbox ssh-config `. +- Core записує цю SSH-конфігурацію у тимчасовий файл, відкриває SSH-сесію та повторно використовує той самий міст віддаленої файлової системи, що використовується для `backend: "ssh"`. +- Лише в режимі `mirror` життєвий цикл відрізняється: синхронізація з локального на віддалений перед exec, а потім синхронізація назад після exec. Поточні обмеження OpenShell: -- браузер в ізоляції ще не підтримується +- браузер у пісочниці ще не підтримується - `sandbox.docker.binds` не підтримується в бекенді OpenShell -- специфічні для Docker параметри середовища виконання в `sandbox.docker.*` як і раніше застосовуються лише до бекенда Docker +- специфічні для Docker параметри runtime в `sandbox.docker.*`, як і раніше, застосовуються лише до бекенда Docker -#### Режими робочого простору +#### Режими workspace -OpenShell має дві моделі робочого простору. Саме ця частина найважливіша на практиці. +OpenShell має дві моделі workspace. На практиці це найважливіша частина. ##### `mirror` -Використовуйте `plugins.entries.openshell.config.mode: "mirror"`, якщо ви хочете, щоб **локальний робочий простір залишався канонічним**. +Використовуйте `plugins.entries.openshell.config.mode: "mirror"`, якщо хочете, щоб **локальний workspace залишався canonical**. Поведінка: -- Перед `exec` OpenClaw синхронізує локальний робочий простір у середовище OpenShell. -- Після `exec` OpenClaw синхронізує віддалений робочий простір назад у локальний. -- Файлові інструменти все одно працюють через міст ізоляції, але локальний робочий простір залишається джерелом істини між ходами. +- Перед `exec` OpenClaw синхронізує локальний workspace у пісочницю OpenShell. +- Після `exec` OpenClaw синхронізує віддалений workspace назад у локальний workspace. +- Файлові інструменти все ще працюють через міст пісочниці, але локальний workspace залишається джерелом істини між ходами. Використовуйте це, коли: -- ви редагуєте файли локально поза OpenClaw і хочете, щоб ці зміни автоматично з’являлися в ізоляції -- ви хочете, щоб середовище OpenShell поводилося максимально схоже на бекенд Docker -- ви хочете, щоб робочий простір хоста відображав записи із середовища ізоляції після кожного ходу exec +- ви редагуєте файли локально поза OpenClaw і хочете, щоб ці зміни автоматично з’являлися в пісочниці +- ви хочете, щоб пісочниця OpenShell поводилася максимально схоже на бекенд Docker +- ви хочете, щоб workspace хоста відображав записи пісочниці після кожного ходу exec Компроміс: @@ -233,65 +236,65 @@ OpenShell має дві моделі робочого простору. Саме ##### `remote` -Використовуйте `plugins.entries.openshell.config.mode: "remote"`, якщо ви хочете, щоб **робочий простір OpenShell став канонічним**. +Використовуйте `plugins.entries.openshell.config.mode: "remote"`, якщо хочете, щоб **workspace OpenShell став canonical**. Поведінка: -- Коли середовище ізоляції створюється вперше, OpenClaw один раз заповнює віддалений робочий простір із локального. -- Після цього `exec`, `read`, `write`, `edit` і `apply_patch` працюють безпосередньо з віддаленим робочим простором OpenShell. -- OpenClaw **не** синхронізує віддалені зміни назад у локальний робочий простір після exec. -- Читання медіа під час prompt і далі працює, оскільки файлові та медіа-інструменти читають через міст ізоляції, а не покладаються на локальний шлях хоста. -- Транспорт — це SSH у середовище OpenShell, яке повертає `openshell sandbox ssh-config`. +- Коли пісочниця створюється вперше, OpenClaw один раз заповнює віддалений workspace з локального workspace. +- Після цього `exec`, `read`, `write`, `edit` і `apply_patch` працюють безпосередньо з віддаленим workspace OpenShell. +- OpenClaw **не** синхронізує віддалені зміни назад у локальний workspace після exec. +- Читання медіа під час prompt, як і раніше, працює, тому що файлові та медіа-інструменти читають через міст пісочниці, а не припускають наявність локального шляху хоста. +- Транспорт — це SSH у пісочницю OpenShell, яку повертає `openshell sandbox ssh-config`. Важливі наслідки: -- Якщо ви редагуєте файли на хості поза OpenClaw після етапу початкового заповнення, віддалене середовище ізоляції **не** побачить ці зміни автоматично. -- Якщо середовище ізоляції створюється заново, віддалений робочий простір знову заповнюється з локального робочого простору. -- За `scope: "agent"` або `scope: "shared"` цей віддалений робочий простір є спільним у межах тієї самої області дії. +- Якщо ви редагуєте файли на хості поза OpenClaw після етапу початкового заповнення, віддалена пісочниця **не** побачить ці зміни автоматично. +- Якщо пісочницю створити заново, віддалений workspace знову заповнюється з локального workspace. +- За `scope: "agent"` або `scope: "shared"` цей віддалений workspace спільно використовується в межах тієї самої області дії. Використовуйте це, коли: -- середовище ізоляції має переважно існувати на віддаленому боці OpenShell -- ви хочете менші накладні витрати на синхронізацію на кожному ході -- ви не хочете, щоб локальні зміни на хості непомітно перезаписували віддалений стан середовища ізоляції +- пісочниця має переважно жити на віддаленому боці OpenShell +- ви хочете менші накладні витрати на синхронізацію в кожному ході +- ви не хочете, щоб локальні редагування на хості непомітно перезаписували стан віддаленої пісочниці -Виберіть `mirror`, якщо сприймаєте середовище ізоляції як тимчасове середовище виконання. -Виберіть `remote`, якщо сприймаєте середовище ізоляції як реальний робочий простір. +Вибирайте `mirror`, якщо ви сприймаєте пісочницю як тимчасове середовище виконання. +Вибирайте `remote`, якщо ви сприймаєте пісочницю як реальний workspace. #### Життєвий цикл OpenShell -Середовища ізоляції OpenShell і далі керуються через звичайний життєвий цикл ізоляції: +Пісочниці OpenShell, як і раніше, керуються через звичайний життєвий цикл пісочниці: -- `openclaw sandbox list` показує як середовища виконання OpenShell, так і середовища виконання Docker -- `openclaw sandbox recreate` видаляє поточне середовище виконання і дозволяє OpenClaw створити його заново під час наступного використання +- `openclaw sandbox list` показує середовища виконання OpenShell так само, як і середовища Docker +- `openclaw sandbox recreate` видаляє поточне середовище виконання і дозволяє OpenClaw створити його знову під час наступного використання - логіка очищення теж враховує бекенд Для режиму `remote` повторне створення особливо важливе: -- повторне створення видаляє канонічний віддалений робочий простір для цієї області дії -- наступне використання створює новий віддалений робочий простір із локального робочого простору +- повторне створення видаляє canonical віддалений workspace для цієї області дії +- наступне використання заповнює новий віддалений workspace з локального workspace -Для режиму `mirror` повторне створення переважно скидає віддалене середовище виконання, -оскільки локальний робочий простір однаково залишається канонічним. +Для режиму `mirror` повторне створення головним чином скидає віддалене середовище виконання, +оскільки локальний workspace у будь-якому разі залишається canonical. -## Доступ до робочого простору +## Доступ до workspace -`agents.defaults.sandbox.workspaceAccess` керує **що може бачити середовище ізоляції**: +`agents.defaults.sandbox.workspaceAccess` керує **тим, що може бачити пісочниця**: -- `"none"` (типово): інструменти бачать робочий простір ізоляції в `~/.openclaw/sandboxes`. -- `"ro"`: монтує робочий простір агента лише для читання в `/agent` (вимикає `write`/`edit`/`apply_patch`). -- `"rw"`: монтує робочий простір агента для читання й запису в `/workspace`. +- `"none"` (типово): інструменти бачать workspace пісочниці в `~/.openclaw/sandboxes`. +- `"ro"`: монтує workspace агента лише для читання в `/agent` (вимикає `write`/`edit`/`apply_patch`). +- `"rw"`: монтує workspace агента для читання і запису в `/workspace`. З бекендом OpenShell: -- режим `mirror` і далі використовує локальний робочий простір як канонічне джерело між ходами exec -- режим `remote` використовує віддалений робочий простір OpenShell як канонічне джерело після початкового заповнення -- `workspaceAccess: "ro"` і `"none"` і далі так само обмежують можливість запису +- режим `mirror`, як і раніше, використовує локальний workspace як canonical джерело між ходами exec +- режим `remote` використовує віддалений workspace OpenShell як canonical джерело після початкового заповнення +- `workspaceAccess: "ro"` і `"none"` однаково обмежують запис -Вхідні медіафайли копіюються в активний робочий простір ізоляції (`media/inbound/*`). -Примітка щодо Skills: інструмент `read` прив’язаний до кореня ізоляції. За `workspaceAccess: "none"` -OpenClaw віддзеркалює придатні Skills у робочий простір ізоляції (`.../skills`), щоб -їх можна було читати. За `"rw"` Skills робочого простору доступні для читання з +Вхідні медіа копіюються в активний workspace пісочниці (`media/inbound/*`). +Примітка щодо Skills: інструмент `read` прив’язаний до кореня пісочниці. За `workspaceAccess: "none"` +OpenClaw віддзеркалює відповідні Skills у workspace пісочниці (`.../skills`), щоб +їх можна було читати. За `"rw"` Skills workspace доступні для читання з `/workspace/skills`. ## Власні bind mounts @@ -299,14 +302,14 @@ OpenClaw віддзеркалює придатні Skills у робочий пр `agents.defaults.sandbox.docker.binds` монтує додаткові каталоги хоста в контейнер. Формат: `host:container:mode` (наприклад, `"/home/user/source:/source:rw"`). -Глобальні bind mounts і bind mounts на рівні агента **об’єднуються** (а не замінюються). За `scope: "shared"` bind mounts на рівні агента ігноруються. +Глобальні та поагентні bind mounts **об’єднуються** (а не замінюються). За `scope: "shared"` bind mounts на рівні агента ігноруються. -`agents.defaults.sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер **браузера в ізоляції**. +`agents.defaults.sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер **браузера пісочниці**. -- Якщо параметр задано (включно з `[]`), він замінює `agents.defaults.sandbox.docker.binds` для контейнера браузера. -- Якщо параметр пропущено, контейнер браузера повертається до `agents.defaults.sandbox.docker.binds` (зворотна сумісність). +- Якщо задано (зокрема `[]`), воно замінює `agents.defaults.sandbox.docker.binds` для контейнера браузера. +- Якщо пропущено, контейнер браузера повертається до `agents.defaults.sandbox.docker.binds` (зворотна сумісність). -Приклад (вихідний код тільки для читання + додатковий каталог даних): +Приклад (вихідний код лише для читання + додатковий каталог даних): ```json5 { @@ -334,19 +337,19 @@ OpenClaw віддзеркалює придатні Skills у робочий пр Примітки щодо безпеки: -- Bind mounts обходять файлову систему ізоляції: вони відкривають шляхи хоста з тим режимом, який ви задаєте (`:ro` або `:rw`). +- Bind mounts обходять файлову систему пісочниці: вони відкривають шляхи хоста з тим режимом, який ви вкажете (`:ro` або `:rw`). - OpenClaw блокує небезпечні джерела bind mounts (наприклад: `docker.sock`, `/etc`, `/proc`, `/sys`, `/dev` і батьківські монтування, які відкрили б до них доступ). -- OpenClaw також блокує типові корені облікових даних у домашньому каталозі, наприклад `~/.aws`, `~/.cargo`, `~/.config`, `~/.docker`, `~/.gnupg`, `~/.netrc`, `~/.npm` і `~/.ssh`. -- Перевірка bind mounts — це не просто зіставлення рядків. OpenClaw нормалізує шлях джерела, потім знову розв’язує його через найглибшого наявного предка, а вже потім повторно перевіряє заблоковані шляхи й дозволені корені. -- Це означає, що вихід за межі через батьківський симлінк усе одно безпечно блокується, навіть якщо кінцевий елемент іще не існує. Приклад: `/workspace/run-link/new-file` усе одно розв’язується як `/var/run/...`, якщо `run-link` вказує туди. -- Дозволені корені джерел канонікалізуються так само, тож шлях, який лише виглядає таким, що входить до списку дозволених до розв’язання симлінків, усе одно буде відхилено як `outside allowed roots`. +- OpenClaw також блокує типові кореневі каталоги облікових даних у домашньому каталозі, такі як `~/.aws`, `~/.cargo`, `~/.config`, `~/.docker`, `~/.gnupg`, `~/.netrc`, `~/.npm` і `~/.ssh`. +- Перевірка bind mounts — це не просто зіставлення рядків. OpenClaw нормалізує шлях джерела, а потім знову розв’язує його через найглибший наявний батьківський елемент перед повторною перевіркою заблокованих шляхів і дозволених коренів. +- Це означає, що виходи через батьківські symlink-и все одно надійно блокуються, навіть якщо кінцевий leaf ще не існує. Приклад: `/workspace/run-link/new-file` усе одно розв’язується як `/var/run/...`, якщо `run-link` вказує туди. +- Дозволені корені джерел канонікалізуються так само, тому шлях, який лише виглядає таким, що входить до allowlist до розв’язання symlink-ів, однаково відхиляється як `outside allowed roots`. - Чутливі монтування (секрети, SSH-ключі, службові облікові дані) мають бути `:ro`, якщо тільки це не є абсолютно необхідним. -- Поєднуйте з `workspaceAccess: "ro"`, якщо вам потрібен лише доступ на читання до робочого простору; режими bind mounts залишаються незалежними. -- Див. [Ізоляція vs Політика інструментів vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated), щоб зрозуміти, як bind mounts взаємодіють із політикою інструментів і elevated exec. +- Поєднуйте з `workspaceAccess: "ro"`, якщо вам потрібен лише доступ на читання до workspace; режими bind mounts залишаються незалежними. +- Див. [Пісочниця vs політика інструментів vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated), щоб зрозуміти, як bind mounts взаємодіють із політикою інструментів і elevated exec. -## Зображення + налаштування +## Образи + налаштування -Типове Docker image: `openclaw-sandbox:bookworm-slim` +Типовий образ Docker: `openclaw-sandbox:bookworm-slim` Зберіть його один раз: @@ -354,31 +357,31 @@ OpenClaw віддзеркалює придатні Skills у робочий пр scripts/sandbox-setup.sh ``` -Примітка: типове image **не** містить Node. Якщо навичці потрібен Node (або -інші середовища виконання), або зберіть власне image, або встановіть усе через -`sandbox.docker.setupCommand` (потрібен вихід у мережу + доступний для запису корінь + -користувач root). +Примітка: типовий образ **не** містить Node. Якщо Skill потребує Node (або +інших runtime), або створіть власний образ, або встановіть їх через +`sandbox.docker.setupCommand` (потребує виходу в мережу + кореневої файлової системи з можливістю запису + +користувача root). -Якщо вам потрібне функціональніше image ізоляції з поширеними інструментами (наприклад +Якщо вам потрібен функціональніший образ пісочниці зі звичними інструментами (наприклад `curl`, `jq`, `nodejs`, `python3`, `git`), зберіть: ```bash scripts/sandbox-common-setup.sh ``` -Потім задайте `agents.defaults.sandbox.docker.image` значенням +Потім задайте `agents.defaults.sandbox.docker.image` як `openclaw-sandbox-common:bookworm-slim`. -Image браузера в ізоляції: +Образ браузера в пісочниці: ```bash scripts/sandbox-browser-setup.sh ``` -За замовчуванням Docker-контейнери ізоляції працюють **без мережі**. -Перевизначити це можна через `agents.defaults.sandbox.docker.network`. +За замовчуванням контейнери пісочниці Docker працюють **без мережі**. +Перевизначте це через `agents.defaults.sandbox.docker.network`. -Комплектне image браузера в ізоляції також застосовує консервативні типові параметри запуску Chromium +Вбудований образ браузера для пісочниці також застосовує консервативні типові параметри запуску Chromium для контейнеризованих навантажень. Поточні типові параметри контейнера включають: - `--remote-debugging-address=127.0.0.1` @@ -399,72 +402,72 @@ scripts/sandbox-browser-setup.sh - `--metrics-recording-only` - `--renderer-process-limit=2` - `--no-sandbox` і `--disable-setuid-sandbox`, коли ввімкнено `noSandbox`. -- Три прапорці посиленого захисту графіки (`--disable-3d-apis`, - `--disable-software-rasterizer`, `--disable-gpu`) є необов’язковими й корисні, +- Три прапорці посилення графічної безпеки (`--disable-3d-apis`, + `--disable-software-rasterizer`, `--disable-gpu`) є необов’язковими і корисні, коли контейнери не мають підтримки GPU. Задайте `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо вашому навантаженню потрібен WebGL або інші 3D/браузерні можливості. - `--disable-extensions` увімкнено за замовчуванням і його можна вимкнути через - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` для сценаріїв, що залежать від розширень. + `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` для сценаріїв, які залежать від розширень. - `--renderer-process-limit=2` керується через `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`, де `0` зберігає типовий режим Chromium. -Якщо вам потрібен інший профіль середовища виконання, використовуйте власне image браузера і надайте -власну точку входу. Для локальних (неконтейнерних) профілів Chromium використовуйте +Якщо вам потрібен інший профіль runtime, використовуйте власний образ браузера і надайте +власний entrypoint. Для локальних профілів Chromium (не в контейнері) використовуйте `browser.extraArgs`, щоб додати додаткові прапорці запуску. -Типові налаштування безпеки: +Типові параметри безпеки: - `network: "host"` заблоковано. -- `network: "container:"` типово заблоковано (ризик обходу через приєднання до простору імен). +- `network: "container:"` за замовчуванням заблоковано (ризик обходу через приєднання до namespace). - Аварійний override: `agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`. Установлення Docker і контейнеризований gateway описані тут: [Docker](/uk/install/docker) -Для розгортань gateway у Docker `scripts/docker/setup.sh` може ініціалізувати конфігурацію ізоляції. +Для розгортань Gateway у Docker `scripts/docker/setup.sh` може ініціалізувати конфігурацію пісочниці. Задайте `OPENCLAW_SANDBOX=1` (або `true`/`yes`/`on`), щоб увімкнути цей шлях. Ви можете -перевизначити розташування сокета через `OPENCLAW_DOCKER_SOCKET`. Повне налаштування й довідник +перевизначити розташування сокета через `OPENCLAW_DOCKER_SOCKET`. Повне налаштування та довідник зі змінних середовища: [Docker](/uk/install/docker#agent-sandbox). ## setupCommand (одноразове налаштування контейнера) -`setupCommand` запускається **один раз** після створення контейнера ізоляції (не під час кожного запуску). +`setupCommand` запускається **один раз** після створення контейнера пісочниці (не під час кожного запуску). Він виконується всередині контейнера через `sh -lc`. Шляхи: - Глобально: `agents.defaults.sandbox.docker.setupCommand` -- Для окремого агента: `agents.list[].sandbox.docker.setupCommand` +- Для агента: `agents.list[].sandbox.docker.setupCommand` -Поширені пастки: +Типові помилки: - Типове значення `docker.network` — `"none"` (без виходу в мережу), тому встановлення пакетів завершуватиметься помилкою. -- `docker.network: "container:"` потребує `dangerouslyAllowContainerNamespaceJoin: true` і призначений лише для аварійного використання. -- `readOnlyRoot: true` забороняє запис; задайте `readOnlyRoot: false` або зберіть власне image. -- Для встановлення пакетів `user` має бути root (не задавайте `user` або задайте `user: "0:0"`). -- Sandbox exec **не** успадковує `process.env` хоста. Використовуйте - `agents.defaults.sandbox.docker.env` (або власне image) для API-ключів навичок. +- `docker.network: "container:"` вимагає `dangerouslyAllowContainerNamespaceJoin: true` і призначене лише для аварійного використання. +- `readOnlyRoot: true` забороняє запис; задайте `readOnlyRoot: false` або створіть власний образ. +- Для встановлення пакетів `user` має бути root (не вказуйте `user` або задайте `user: "0:0"`). +- Sandbox exec **не** успадковує host `process.env`. Використовуйте + `agents.defaults.sandbox.docker.env` (або власний образ) для API-ключів Skills. ## Політика інструментів + шляхи обходу -Політики allow/deny для інструментів усе одно застосовуються раніше за правила ізоляції. Якщо інструмент заборонено -глобально або для конкретного агента, ізоляція його не поверне. +Політики allow/deny для інструментів, як і раніше, застосовуються до правил пісочниці. Якщо інструмент заборонено +глобально або для конкретного агента, пісочниця його не поверне. -`tools.elevated` — це явний шлях обходу, який запускає `exec` поза ізоляцією (`gateway` за замовчуванням або `node`, коли ціллю exec є `node`). -Директиви `/exec` застосовуються лише для авторизованих відправників і зберігаються для кожного сеансу; щоб повністю вимкнути -`exec`, використовуйте заборону в політиці інструментів (див. [Ізоляція vs Політика інструментів vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated)). +`tools.elevated` — це явний шлях обходу, який запускає `exec` поза пісочницею (`gateway` за замовчуванням або `node`, коли ціль exec — `node`). +Директиви `/exec` застосовуються лише до авторизованих відправників і зберігаються для кожної сесії; щоб повністю вимкнути +`exec`, використовуйте deny у політиці інструментів (див. [Пісочниця vs політика інструментів vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated)). Налагодження: -- Використовуйте `openclaw sandbox explain`, щоб переглянути фактичний режим ізоляції, політику інструментів і ключі конфігурації для виправлення. -- Див. [Ізоляція vs Політика інструментів vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated) для ментальної моделі «чому це заблоковано?». - Тримайте все максимально закритим. +- Використовуйте `openclaw sandbox explain`, щоб переглянути ефективний режим пісочниці, політику інструментів і конфігураційні ключі для виправлення. +- Див. [Пісочниця vs політика інструментів vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated) для ментальної моделі “чому це заблоковано?”. + Тримайте все жорстко заблокованим. ## Перевизначення для кількох агентів -Кожен агент може перевизначати ізоляцію й інструменти: -`agents.list[].sandbox` і `agents.list[].tools` (а також `agents.list[].tools.sandbox.tools` для політики інструментів ізоляції). -Див. [Ізоляція та інструменти для кількох агентів](/uk/tools/multi-agent-sandbox-tools) щодо пріоритетів. +Кожен агент може перевизначати пісочницю й інструменти: +`agents.list[].sandbox` і `agents.list[].tools` (а також `agents.list[].tools.sandbox.tools` для політики інструментів у пісочниці). +Докладніше про пріоритети див. у [Пісочниця та інструменти для кількох агентів](/uk/tools/multi-agent-sandbox-tools). ## Мінімальний приклад увімкнення @@ -484,8 +487,8 @@ scripts/sandbox-browser-setup.sh ## Пов’язана документація -- [OpenShell](/uk/gateway/openshell) -- налаштування керованого бекенда ізоляції, режими робочого простору та довідник з конфігурації -- [Конфігурація ізоляції](/uk/gateway/configuration-reference#agentsdefaultssandbox) -- [Ізоляція vs Політика інструментів vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated) -- налагодження «чому це заблоковано?» -- [Ізоляція та інструменти для кількох агентів](/uk/tools/multi-agent-sandbox-tools) -- перевизначення для окремих агентів і пріоритети +- [OpenShell](/uk/gateway/openshell) -- налаштування керованого бекенда пісочниці, режими workspace і довідник з конфігурації +- [Конфігурація пісочниці](/uk/gateway/configuration-reference#agentsdefaultssandbox) +- [Пісочниця vs політика інструментів vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated) -- налагодження “чому це заблоковано?” +- [Пісочниця та інструменти для кількох агентів](/uk/tools/multi-agent-sandbox-tools) -- перевизначення для окремих агентів і пріоритети - [Безпека](/uk/gateway/security) diff --git a/docs/uk/gateway/security/index.md b/docs/uk/gateway/security/index.md index 4b1fb902c..ea7d0df43 100644 --- a/docs/uk/gateway/security/index.md +++ b/docs/uk/gateway/security/index.md @@ -1,13 +1,13 @@ --- read_when: - - Додавання функцій, що розширюють доступ або автоматизацію -summary: Міркування щодо безпеки та модель загроз для запуску AI Gateway із доступом до оболонки + - Додавання функцій, які розширюють доступ або автоматизацію +summary: Міркування безпеки та модель загроз для запуску AI Gateway із доступом до оболонки title: Безпека x-i18n: - generated_at: "2026-04-12T18:22:01Z" + generated_at: "2026-04-20T18:29:25Z" model: gpt-5.4 provider: openai - source_hash: 7f3ef693813b696be2e24bcc333c8ee177fa56c3cb06c5fac12a0bd220a29917 + source_hash: aa10d97773a78c43d238aed495e00d83a3e28a50939cbe8941add05874846a86 source_path: gateway/security/index.md workflow: 15 --- @@ -15,21 +15,21 @@ x-i18n: # Безпека -**Модель довіри персонального асистента:** ці рекомендації виходять із припущення про одну межу довіри оператора на один Gateway (модель одного користувача / персонального асистента). -OpenClaw **не** є безпечною межею для ворожого багатокористувацького середовища, у якому кілька зловмисних користувачів ділять одного агента/Gateway. -Якщо вам потрібна робота зі змішаною довірою або в умовах ворожих користувачів, розділіть межі довіри (окремий Gateway + облікові дані, в ідеалі також окремі користувачі ОС/хости). +**Модель довіри для персонального помічника:** ці рекомендації виходять із припущення про один довірений операторський периметр на один Gateway (модель одного користувача / персонального помічника). +OpenClaw **не є** ворожим багатокористувацьким бар’єром безпеки для кількох недовірених користувачів, які спільно використовують одного агента/Gateway. +Якщо вам потрібна робота зі змішаною довірою або недовіреними користувачами, розділіть периметри довіри (окремий Gateway + облікові дані, в ідеалі також окремі користувачі ОС/хости). **На цій сторінці:** [Модель довіри](#scope-first-personal-assistant-security-model) | [Швидкий аудит](#quick-check-openclaw-security-audit) | [Посилений базовий захист](#hardened-baseline-in-60-seconds) | [Модель доступу DM](#dm-access-model-pairing-allowlist-open-disabled) | [Посилення конфігурації](#configuration-hardening-examples) | [Реагування на інциденти](#incident-response) -## Спочатку про межі: модель безпеки персонального асистента +## Спочатку про межі: модель безпеки персонального помічника -Рекомендації з безпеки OpenClaw ґрунтуються на розгортанні **персонального асистента**: одна межа довіри оператора, потенційно багато агентів. +Рекомендації з безпеки OpenClaw виходять із розгортання **персонального помічника**: один довірений операторський периметр, потенційно багато агентів. -- Підтримувана модель безпеки: один користувач/межа довіри на Gateway (бажано один користувач ОС/хост/VPS на межу). -- Модель, яка не підтримується як межа безпеки: один спільний Gateway/агент, яким користуються взаємно недовірені або ворожі користувачі. -- Якщо потрібна ізоляція від ворожих користувачів, розділіть за межами довіри (окремий Gateway + облікові дані, а в ідеалі також окремі користувачі ОС/хости). -- Якщо кілька недовірених користувачів можуть надсилати повідомлення одному агенту з увімкненими інструментами, вважайте, що всі вони спільно використовують однакові делеговані повноваження цього агента щодо інструментів. +- Підтримувана позиція безпеки: один користувач/периметр довіри на один Gateway (бажано один користувач ОС/хост/VPS на один периметр). +- Не є підтримуваним периметром безпеки: один спільний Gateway/агент, який використовують взаємно недовірені або ворожі користувачі. +- Якщо потрібна ізоляція від ворожих користувачів, розділіть за периметрами довіри (окремий Gateway + облікові дані, а в ідеалі також окремі користувачі ОС/хости). +- Якщо кілька недовірених користувачів можуть писати одному агенту з увімкненими інструментами, вважайте, що вони спільно використовують той самий делегований набір повноважень інструментів для цього агента. Ця сторінка пояснює посилення захисту **в межах цієї моделі**. Вона не стверджує наявність ворожої багатокористувацької ізоляції в одному спільному Gateway. @@ -37,7 +37,7 @@ OpenClaw **не** є безпечною межею для ворожого ба Див. також: [Формальна верифікація (моделі безпеки)](/uk/security/formal-verification) -Регулярно запускайте це (особливо після змін конфігурації або відкриття мережевих поверхонь): +Запускайте це регулярно (особливо після зміни конфігурації або відкриття мережевих поверхонь): ```bash 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-file і використовує скидання ACL Windows замість POSIX `chmod` під час роботи у Windows. +`security audit --fix` навмисно залишається вузькоспрямованим: він перемикає поширені відкриті групові політики на allowlist, відновлює `logging.redactSensitive: "tools"`, посилює права доступу до стану/конфігурації/включених файлів і використовує скидання ACL у Windows замість POSIX `chmod` під час роботи у Windows. -Команда позначає типові небезпечні конфігурації (відкритий доступ до автентифікації Gateway, відкритий доступ до керування браузером, розширені allowlist, дозволи файлової системи, надто поблажливі схвалення exec і відкритий доступ до інструментів через канали). +Він виявляє поширені ризиковані налаштування (відкритий доступ до автентифікації Gateway, відкритий доступ до керування браузером, підвищені allowlist, права доступу до файлової системи, надто поблажливі дозволи на `exec` і відкритий доступ інструментів у каналах). -OpenClaw — це і продукт, і експеримент: ви підключаєте поведінку frontier-моделей до реальних поверхонь обміну повідомленнями та реальних інструментів. **Ідеально безпечної конфігурації не існує.** Мета — усвідомлено визначити: +OpenClaw — це і продукт, і експеримент: ви під’єднуєте поведінку frontier-моделей до реальних поверхонь обміну повідомленнями та реальних інструментів. **«Ідеально безпечного» налаштування не існує.** Мета — свідомо визначити: -- хто може спілкуватися з вашим ботом; -- де боту дозволено діяти; -- до чого бот може торкатися. +- хто може взаємодіяти з вашим ботом +- де боту дозволено діяти +- до чого бот може мати доступ -Починайте з мінімального доступу, який ще дозволяє працювати, і розширюйте його лише в міру зростання впевненості. +Починайте з найменшого доступу, який усе ще працює, і лише потім розширюйте його в міру зростання впевненості. -### Розгортання та довіра до хоста +### Розгортання і довіра до хоста -OpenClaw припускає, що хост і межа конфігурації є довіреними: +OpenClaw виходить із того, що хост і межа конфігурації є довіреними: - Якщо хтось може змінювати стан/конфігурацію хоста Gateway (`~/.openclaw`, включно з `openclaw.json`), вважайте його довіреним оператором. -- Запуск одного Gateway для кількох взаємно недовірених/ворожих операторів **не є рекомендованою конфігурацією**. -- Для команд зі змішаним рівнем довіри розділяйте межі довіри за допомогою окремих Gateway (або щонайменше окремих користувачів ОС/хостів). -- Рекомендований типовий варіант: один користувач на машину/хост (або VPS), один gateway для цього користувача та один або кілька агентів у цьому gateway. -- У межах одного екземпляра Gateway автентифікований операторський доступ — це довірена роль площини керування, а не роль окремого користувача-орендаря. -- Ідентифікатори сеансу (`sessionKey`, session IDs, labels) — це селектори маршрутизації, а не токени авторизації. -- Якщо кілька людей можуть надсилати повідомлення одному агенту з увімкненими інструментами, кожен із них може керувати однаковим набором дозволів. Ізоляція сеансів/пам’яті на рівні користувача допомагає приватності, але не перетворює спільного агента на авторизацію хоста на рівні окремого користувача. +- Запуск одного Gateway для кількох взаємно недовірених/ворожих операторів **не є рекомендованим налаштуванням**. +- Для команд зі змішаною довірою розділяйте периметри довіри окремими Gateway (або щонайменше окремими користувачами ОС/хостами). +- Рекомендований варіант за замовчуванням: один користувач на одну машину/хост (або VPS), один gateway для цього користувача і один або більше агентів у цьому Gateway. +- У межах одного екземпляра Gateway автентифікований доступ оператора є довіреною роллю площини керування, а не роллю окремого користувача-орендаря. +- Ідентифікатори сесій (`sessionKey`, session ID, labels) — це селектори маршрутизації, а не токени авторизації. +- Якщо кілька людей можуть писати одному агенту з увімкненими інструментами, кожен із них може керувати тим самим набором дозволів. Ізоляція сесій/пам’яті на рівні користувача допомагає приватності, але не перетворює спільного агента на механізм авторизації хоста для кожного користувача окремо. -### Спільний Slack workspace: реальний ризик +### Спільний робочий простір Slack: реальний ризик -Якщо «будь-хто в Slack може написати боту», основний ризик — це делеговані повноваження інструментів: +Якщо «усі в Slack можуть писати боту», головний ризик — це делеговані повноваження інструментів: - будь-який дозволений відправник може ініціювати виклики інструментів (`exec`, браузер, мережеві/файлові інструменти) у межах політики агента; -- ін’єкція підказок/вмісту від одного відправника може спричинити дії, що впливають на спільний стан, пристрої або результати; -- якщо один спільний агент має доступ до чутливих облікових даних/файлів, будь-який дозволений відправник потенційно може ініціювати їх ексфільтрацію через використання інструментів. +- ін’єкція prompt/контенту від одного відправника може спричинити дії, що впливають на спільний стан, пристрої або результати; +- якщо один спільний агент має чутливі облікові дані/файли, будь-який дозволений відправник потенційно може ініціювати їх ексфільтрацію через використання інструментів. Для командних робочих процесів використовуйте окремі агенти/Gateway з мінімальним набором інструментів; агентів із персональними даними тримайте приватними. -### Спільний агент у компанії: прийнятний шаблон +### Спільний агент компанії: прийнятний шаблон -Це прийнятно, коли всі користувачі такого агента належать до однієї межі довіри (наприклад, одна команда в компанії), а сам агент суворо обмежений бізнес-контекстом. +Це прийнятно, коли всі, хто використовує цього агента, перебувають у межах одного периметра довіри (наприклад, одна команда в компанії), а агент жорстко обмежений бізнес-контекстом. - запускайте його на виділеній машині/VM/контейнері; -- використовуйте виділеного користувача ОС + окремий браузер/профіль/акаунти для цього середовища; -- не входьте в цьому середовищі до особистих Apple/Google-акаунтів чи особистих профілів браузера/менеджера паролів. +- використовуйте окремого користувача ОС + окремий браузер/профіль/облікові записи для цього середовища виконання; +- не входьте в цьому середовищі у персональні облікові записи Apple/Google або персональні профілі менеджера паролів/браузера. -Якщо ви змішуєте особисті й корпоративні ідентичності в одному середовищі, ви руйнуєте розділення та підвищуєте ризик витоку персональних даних. +Якщо ви змішуєте персональні та корпоративні ідентичності в одному середовищі виконання, ви руйнуєте розділення і підвищуєте ризик витоку персональних даних. -## Концепція довіри між Gateway і Node +## Концепція довіри до Gateway і Node -Розглядайте Gateway і Node як єдиний домен довіри оператора, але з різними ролями: +Сприймайте Gateway і Node як один операторський домен довіри з різними ролями: -- **Gateway** — це площина керування та поверхня політик (`gateway.auth`, політика інструментів, маршрутизація). -- **Node** — це поверхня віддаленого виконання, пов’язана з цим Gateway (команди, дії на пристрої, локальні можливості хоста). -- Викликач, автентифікований у Gateway, є довіреним у межах Gateway. Після pairing дії Node вважаються довіреними операторськими діями на цьому Node. -- `sessionKey` — це вибір маршрутизації/контексту, а не автентифікація окремого користувача. -- Схвалення exec (allowlist + ask) — це запобіжники для намірів оператора, а не ізоляція від ворожих багатокористувацьких сценаріїв. -- Типова поведінка OpenClaw для довірених конфігурацій з одним оператором полягає в тому, що виконання на хості через `gateway`/`node` дозволене без запитів на схвалення (`security="full"`, `ask="off"`, якщо ви не посилите політику). Це навмисне UX-рішення, а не вразливість саме по собі. -- Схвалення exec прив’язуються до точного контексту запиту та, наскільки можливо, до прямих локальних файлових операндів; вони не моделюють семантично кожен шлях завантаження runtime/інтерпретатора. Для сильних меж використовуйте sandboxing та ізоляцію хоста. +- **Gateway** — це площина керування і поверхня політик (`gateway.auth`, політика інструментів, маршрутизація). +- **Node** — це поверхня віддаленого виконання, прив’язана до цього Gateway (команди, дії з пристроєм, локальні для хоста можливості). +- Той, хто автентифікований у Gateway, є довіреним у межах Gateway. Після прив’язки дії Node є діями довіреного оператора на цьому Node. +- `sessionKey` — це вибір маршрутизації/контексту, а не автентифікація користувача. +- Погодження `exec` (allowlist + ask) — це запобіжники для намірів оператора, а не ізоляція від ворожих багатокористувацьких сценаріїв. +- Продуктове значення OpenClaw за замовчуванням для довірених сценаріїв з одним оператором полягає в тому, що `exec` на хості для `gateway`/`node` дозволений без запитів на погодження (`security="full"`, `ask="off"`, якщо ви самі не посилите політику). Це навмисне UX-рішення, а не вразливість саме по собі. +- Погодження `exec` прив’язуються до точного контексту запиту та, у міру можливості, до прямих локальних файлових операндів; вони не моделюють семантично кожен шлях завантаження середовища виконання/інтерпретатора. Для жорстких меж використовуйте sandboxing та ізоляцію хоста. -Якщо вам потрібна ізоляція від ворожих користувачів, розділяйте межі довіри за користувачем ОС/хостом і запускайте окремі Gateway. +Якщо вам потрібна ізоляція від ворожих користувачів, розділяйте периметри довіри за користувачами ОС/хостами і запускайте окремі Gateway. -## Матриця меж довіри +## Матриця периметрів довіри Використовуйте це як швидку модель під час оцінки ризику: -| Межа або контроль | Що це означає | Типове хибне тлумачення | -| -------------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------- | -| `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 | Віддалене виконання на рівні оператора на пов’язаних пристроях | «Керування віддаленим пристроєм слід за замовчуванням трактувати як доступ недовіреного користувача» | +| Периметр або контроль | Що це означає | Поширене хибне тлумачення | +| ---------------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------- | +| `gateway.auth` (token/password/trusted-proxy/device auth) | Автентифікує викликачів до API Gateway | «Щоб це було безпечно, потрібні підписи для кожного повідомлення в кожному кадрі» | +| `sessionKey` | Ключ маршрутизації для вибору контексту/сесії | «Ключ сесії є периметром автентифікації користувача» | +| Запобіжники prompt/контенту | Зменшують ризик зловживання моделлю | «Сама лише prompt injection уже доводить обхід автентифікації» | +| `canvas.eval` / browser evaluate | Намірена можливість оператора, коли увімкнено | «Будь-який примітив JS eval автоматично є вразливістю в цій моделі довіри» | +| Локальна оболонка `!` у TUI | Явний локальний запуск, ініційований оператором | «Зручна локальна команда оболонки — це віддалена ін’єкція» | +| Прив’язка Node і команди Node | Віддалене виконання на рівні оператора на прив’язаних пристроях | «Керування віддаленим пристроєм слід за замовчуванням трактувати як доступ недовіреного користувача» | ## Не є вразливостями за задумом -Про ці шаблони часто повідомляють, але зазвичай їх закривають без дій, якщо не показано реальний обхід межі: +Ці шаблони повідомляють часто, і зазвичай їх закривають без дій, якщо не показано реальний обхід периметра: -- Ланцюги, що складаються лише з prompt injection, без обходу політики/автентифікації/sandbox. -- Твердження, що припускають вороже багатокористувацьке використання на одному спільному хості/конфігурації. -- Твердження, які класифікують звичайний операторський доступ на читання (наприклад `sessions.list`/`sessions.preview`/`chat.history`) як IDOR у конфігурації зі спільним gateway. -- Висновки щодо розгортань лише на localhost (наприклад HSTS для gateway, доступного лише через loopback). -- Повідомлення про підпис вхідних webhook Discord для вхідних шляхів, яких немає в цьому репозиторії. -- Повідомлення, які трактують метадані pairing Node як прихований другий рівень схвалення кожної команди для `system.run`, хоча реальною межею виконання все ще є глобальна політика команд Node у gateway плюс власні схвалення exec самого Node. -- Повідомлення про «відсутність авторизації на рівні користувача», які трактують `sessionKey` як токен автентифікації. +- Ланцюги, що ґрунтуються лише на prompt injection без обходу політики/автентифікації/sandbox. +- Твердження, які припускають ворожу багатокористувацьку роботу на одному спільному хості/конфігурації. +- Твердження, які класифікують звичайний доступ оператора по шляху читання (наприклад `sessions.list`/`sessions.preview`/`chat.history`) як IDOR у конфігурації зі спільним Gateway. +- Висновки для розгортань лише на localhost (наприклад HSTS для Gateway, доступного тільки через loopback). +- Зауваження про підпис inbound Webhook у Discord для inbound-шляхів, яких у цьому репозиторії не існує. +- Звіти, які трактують метадані прив’язки Node як прихований другий рівень погодження для кожної команди `system.run`, тоді як реальним периметром виконання лишається глобальна політика команд Node на рівні gateway плюс власні погодження `exec` у node. +- Зауваження про «відсутність авторизації на рівні користувача», які трактують `sessionKey` як токен автентифікації. -## Контрольний список для дослідника перед відкриттям GHSA +## Попередній контрольний список для дослідників -Перш ніж відкривати GHSA, перевірте все з наведеного нижче: +Перш ніж відкривати GHSA, перевірте все з цього списку: -1. Відтворення все ще працює на останньому `main` або в останньому релізі. -2. Повідомлення містить точний шлях у коді (`file`, function, line range) і перевірену версію/коміт. -3. Вплив перетинає задокументовану межу довіри (а не лише prompt injection). -4. Заявлена проблема не входить до [Out of Scope](https://github.com/openclaw/openclaw/blob/main/SECURITY.md#out-of-scope). -5. Наявні advisory уже перевірені на дублікати (за потреби використовуйте канонічний GHSA повторно). -6. Припущення щодо розгортання явно описані (loopback/local чи exposed, довірені чи недовірені оператори). +1. Відтворення все ще працює на останньому `main` або останньому релізі. +2. Звіт містить точний шлях коду (`file`, function, line range) і перевірену версію/коміт. +3. Вплив перетинає задокументований периметр довіри (а не лише prompt injection). +4. Твердження не входить до [Out of Scope](https://github.com/openclaw/openclaw/blob/main/SECURITY.md#out-of-scope). +5. Наявні advisory були перевірені на дублікати (за потреби повторно використовуйте канонічний GHSA). +6. Припущення про розгортання сформульовано явно (loopback/local чи exposed, довірені чи недовірені оператори). ## Посилений базовий захист за 60 секунд -Спочатку використовуйте цей базовий профіль, а потім вибірково знову вмикайте інструменти для довірених агентів: +Спочатку використайте цей базовий варіант, а потім вибірково знову вмикайте інструменти для кожного довіреного агента: ```json5 { @@ -167,211 +167,209 @@ OpenClaw припускає, що хост і межа конфігурації } ``` -Це залишає Gateway доступним лише локально, ізолює DM і за замовчуванням вимикає інструменти площини керування/runtime. +Це залишає Gateway доступним лише локально, ізолює DM і за замовчуванням вимикає інструменти площини керування/середовища виконання. -## Швидке правило для спільної вхідної скриньки +## Швидке правило для спільної скриньки вхідних -Якщо більше ніж одна людина може надсилати DM вашому боту: +Якщо більше ніж одна людина може писати вашому боту в DM: -- Установіть `session.dmScope: "per-channel-peer"` (або `"per-account-channel-peer"` для каналів із кількома акаунтами). -- Використовуйте `dmPolicy: "pairing"` або суворі allowlist. +- Установіть `session.dmScope: "per-channel-peer"` (або `"per-account-channel-peer"` для багатокористувацьких каналів). +- Тримайте `dmPolicy: "pairing"` або суворі allowlist. - Ніколи не поєднуйте спільні DM із широким доступом до інструментів. -- Це посилює захист кооперативних/спільних вхідних скриньок, але не призначене для ворожої коорендної ізоляції, коли користувачі мають спільний доступ на запис до хоста/конфігурації. +- Це посилює захист для кооперативних/спільних вхідних, але не призначене для ворожої коорендної ізоляції, коли користувачі мають спільний доступ на запис до хоста/конфігурації. ## Модель видимості контексту OpenClaw розділяє два поняття: -- **Авторизація запуску**: хто може запускати агента (`dmPolicy`, `groupPolicy`, allowlist, обмеження згадуваннями). -- **Видимість контексту**: який додатковий контекст вбудовується у вхід моделі (тіло відповіді, процитований текст, історія гілки, метадані пересилання). +- **Авторизація тригера**: хто може запускати агента (`dmPolicy`, `groupPolicy`, allowlist, вимоги до згадування). +- **Видимість контексту**: який додатковий контекст додається до вхідних даних моделі (текст відповіді, цитований текст, історія треду, метадані пересилання). -Allowlist контролюють запуск і авторизацію команд. Налаштування `contextVisibility` визначає, як фільтрується додатковий контекст (процитовані відповіді, корені гілок, отримана історія): +Allowlist керують тригерами та авторизацією команд. Параметр `contextVisibility` визначає, як фільтрується додатковий контекст (цитовані відповіді, корені тредів, отримана історія): -- `contextVisibility: "all"` (типове значення) зберігає додатковий контекст у тому вигляді, у якому його отримано. -- `contextVisibility: "allowlist"` фільтрує додатковий контекст за відправниками, дозволеними активними перевірками allowlist. -- `contextVisibility: "allowlist_quote"` працює як `allowlist`, але все ж зберігає одну явну процитовану відповідь. +- `contextVisibility: "all"` (типово) зберігає додатковий контекст у тому вигляді, у якому його отримано. +- `contextVisibility: "allowlist"` фільтрує додатковий контекст до відправників, дозволених активними перевірками allowlist. +- `contextVisibility: "allowlist_quote"` працює як `allowlist`, але все одно зберігає одну явну цитовану відповідь. -Установлюйте `contextVisibility` для каналу або для кімнати/розмови. Докладніше про налаштування див. у [Групові чати](/uk/channels/groups#context-visibility-and-allowlists). +Установлюйте `contextVisibility` для каналу або кімнати/розмови. Докладніше про налаштування див. у [Групові чати](/uk/channels/groups#context-visibility-and-allowlists). -Рекомендації для triage advisory: +Рекомендації для аналізу advisory: -- Твердження, які лише показують, що «модель може бачити процитований або історичний текст від відправників поза allowlist», є висновками щодо посилення захисту, які можна усунути за допомогою `contextVisibility`, а не самі по собі обходом межі автентифікації чи sandbox. -- Щоб мати безпековий вплив, повідомлення все одно повинні демонструвати обхід межі довіри (автентифікація, політика, sandbox, схвалення або інша задокументована межа). +- Твердження, які лише показують, що «модель може бачити цитований або історичний текст від відправників, яких немає в allowlist», є висновками про посилення захисту, які можна усунути за допомогою `contextVisibility`, а не обхід авторизації чи меж sandbox самі по собі. +- Щоб мати вплив на безпеку, звіт усе одно має показувати доведений обхід периметра довіри (автентифікація, політика, sandbox, погодження або інший задокументований периметр). ## Що перевіряє аудит (на високому рівні) - **Вхідний доступ** (політики DM, групові політики, allowlist): чи можуть сторонні люди запускати бота? -- **Радіус ураження інструментів** (розширені інструменти + відкриті кімнати): чи може prompt injection перетворитися на дії в оболонці/з файлами/мережею? -- **Дрейф схвалення exec** (`security=full`, `autoAllowSkills`, allowlist інтерпретаторів без `strictInlineEval`): чи запобіжники host-exec усе ще працюють так, як ви очікуєте? - - `security="full"` — це широке попередження про режим безпеки, а не доказ помилки. Це обраний варіант за замовчуванням для довірених конфігурацій персонального асистента; посилюйте його лише тоді, коли ваша модель загроз вимагає схвалення або запобіжників allowlist. -- **Мережевий доступ** (bind/auth Gateway, Tailscale Serve/Funnel, слабкі/короткі токени автентифікації). -- **Доступ до керування браузером** (віддалені Node, relay-порти, віддалені кінцеві точки CDP). -- **Гігієна локального диска** (дозволи, symlink, include конфігурації, шляхи «синхронізованих папок»). -- **Плагіни** (розширення існують без явного allowlist). -- **Дрейф політик/помилки конфігурації** (налаштування sandbox docker задані, але режим sandbox вимкнений; неефективні шаблони `gateway.nodes.denyCommands`, тому що зіставлення виконується лише за точною назвою команди (наприклад `system.run`) і не аналізує текст оболонки; небезпечні записи `gateway.nodes.allowCommands`; глобальний `tools.profile="minimal"` перевизначено профілями окремих агентів; інструменти розширень Plugin доступні через надто поблажливу політику інструментів). -- **Дрейф очікувань runtime** (наприклад, припущення, що неявний exec і далі означає `sandbox`, хоча `tools.exec.host` тепер за замовчуванням має значення `auto`, або явне встановлення `tools.exec.host="sandbox"` при вимкненому режимі sandbox). -- **Гігієна моделей** (попередження, якщо налаштовані моделі виглядають застарілими; не є жорстким блокуванням). +- **Радіус ураження інструментів** (підвищені інструменти + відкриті кімнати): чи може prompt injection перетворитися на дії оболонки/файлової системи/мережі? +- **Дрейф погодження `exec`** (`security=full`, `autoAllowSkills`, allowlist інтерпретаторів без `strictInlineEval`): чи запобіжники для host-exec усе ще працюють так, як ви очікуєте? + - `security="full"` — це широке попередження про позицію безпеки, а не доказ помилки. Це обране значення за замовчуванням для довірених сценаріїв персонального помічника; посилюйте його лише тоді, коли ваша модель загроз потребує погодження або запобіжників allowlist. +- **Мережева експозиція** (bind/auth Gateway, Tailscale Serve/Funnel, слабкі/короткі токени автентифікації). +- **Експозиція керування браузером** (віддалені Node, relay-порти, віддалені CDP endpoint). +- **Гігієна локального диска** (права доступу, symlink, include-файли конфігурації, шляхи «синхронізованих папок»). +- **Plugin** (розширення існують без явного allowlist). +- **Дрейф політик/помилки конфігурації** (налаштування sandbox docker задані, але режим sandbox вимкнено; неефективні шаблони `gateway.nodes.denyCommands`, тому що зіставлення виконується лише за точною назвою команди (наприклад `system.run`) і не аналізує текст оболонки; небезпечні записи `gateway.nodes.allowCommands`; глобальний `tools.profile="minimal"` перевизначено профілями на рівні агента; інструменти plugin-розширень доступні за надто поблажливої політики інструментів). +- **Дрейф очікувань середовища виконання** (наприклад, припущення, що неявний exec і далі означає `sandbox`, коли `tools.exec.host` тепер за замовчуванням має значення `auto`, або явне встановлення `tools.exec.host="sandbox"` за вимкненого режиму sandbox). +- **Гігієна моделей** (попередження, якщо налаштовані моделі виглядають застарілими; це не жорстке блокування). -Якщо ви запускаєте `--deep`, OpenClaw також намагається виконати best-effort live-перевірку Gateway. +Якщо ви запускаєте `--deep`, OpenClaw також виконує best-effort живу перевірку Gateway. ## Карта зберігання облікових даних -Використовуйте це під час аудиту доступу або коли вирішуєте, що резервувати: +Використовуйте це під час аудиту доступу або коли вирішуєте, що саме резервувати: - **WhatsApp**: `~/.openclaw/credentials/whatsapp//creds.json` - **Токен Telegram-бота**: config/env або `channels.telegram.tokenFile` (лише звичайний файл; symlink відхиляються) -- **Токен Discord-бота**: config/env або SecretRef (постачальники env/file/exec) +- **Токен Discord-бота**: config/env або SecretRef (провайдери env/file/exec) - **Токени Slack**: config/env (`channels.slack.*`) - **Allowlist pairing**: - - `~/.openclaw/credentials/-allowFrom.json` (типовий акаунт) - - `~/.openclaw/credentials/--allowFrom.json` (нетипові акаунти) -- **Профілі автентифікації моделей**: `~/.openclaw/agents//agent/auth-profiles.json` -- **Файл із payload секретів (необов’язково)**: `~/.openclaw/secrets.json` -- **Імпорт застарілого OAuth**: `~/.openclaw/credentials/oauth.json` + - `~/.openclaw/credentials/-allowFrom.json` (обліковий запис за замовчуванням) + - `~/.openclaw/credentials/--allowFrom.json` (неосновні облікові записи) +- **Профілі автентифікації моделі**: `~/.openclaw/agents//agent/auth-profiles.json` +- **Payload секретів на основі файлу (необов’язково)**: `~/.openclaw/secrets.json` +- **Застарілий імпорт OAuth**: `~/.openclaw/credentials/oauth.json` ## Контрольний список аудиту безпеки -Коли аудит виводить висновки, дотримуйтеся такого порядку пріоритетів: +Коли аудит виводить findings, сприймайте це як порядок пріоритетів: -1. **Усе, що є “open” + увімкнені інструменти**: спочатку обмежте DM/групи (pairing/allowlist), потім посильте політику інструментів/sandboxing. -2. **Публічний мережевий доступ** (bind у LAN, Funnel, відсутність auth): виправляйте негайно. -3. **Віддалений доступ до керування браузером**: ставтеся до цього як до операторського доступу (лише tailnet, навмисне pair Node, уникайте публічного доступу). -4. **Дозволи**: переконайтеся, що state/config/credentials/auth недоступні для читання групою або всіма. -5. **Плагіни/розширення**: завантажуйте лише те, чому ви явно довіряєте. -6. **Вибір моделі**: для будь-якого бота з інструментами віддавайте перевагу сучасним моделям, загартованим проти інструкційних атак. +1. **Будь-що «відкрите» + увімкнені інструменти**: спочатку закрийте DM/групи (pairing/allowlist), потім посильте політику інструментів/sandboxing. +2. **Публічна мережева експозиція** (прив’язка до LAN, Funnel, відсутня автентифікація): виправляйте негайно. +3. **Віддалена експозиція керування браузером**: ставтеся до цього як до операторського доступу (лише tailnet, навмисно прив’язуйте Node, уникайте публічної експозиції). +4. **Права доступу**: переконайтеся, що стан/конфігурація/облікові дані/автентифікація не доступні для читання групою або всім. +5. **Plugin/розширення**: завантажуйте лише те, чому явно довіряєте. +6. **Вибір моделі**: для будь-якого бота з інструментами віддавайте перевагу сучасним моделям, стійким до інструкційних атак. ## Глосарій аудиту безпеки -Найбільш показові значення `checkId`, які ви, найімовірніше, побачите в реальних розгортаннях (список не є вичерпним): +Значення `checkId` з високим сигналом, які ви найімовірніше побачите в реальних розгортаннях (не вичерпний перелік): -| `checkId` | Серйозність | Чому це важливо | Основний ключ/шлях для виправлення | Авто-виправлення | -| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | ---------------- | -| `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 | Ціль файлу конфігурації стає іншою межею довіри | структура файлової системи файлу конфігурації | ні | -| `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 | 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, схожі на шаблони, не зіставляються з текстом оболонки або групами | `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 | Автентифікація trusted-proxy без IP-адрес trusted proxy є небезпечною | `gateway.trustedProxies` | ні | -| `gateway.trusted_proxy_no_user_header` | critical | Автентифікація trusted-proxy не може безпечно визначити ідентичність користувача | `gateway.auth.trustedProxy.userHeader` | ні | -| `gateway.trusted_proxy_no_allowlist` | warn | Автентифікація trusted-proxy приймає будь-якого автентифікованого користувача upstream | `gateway.auth.trustedProxy.allowUsers` | ні | -| `gateway.probe_auth_secretref_unavailable` | warn | Глибока перевірка не змогла розв’язати auth SecretRef у цьому шляху команди | джерело auth для deep-probe / доступність SecretRef | ні | -| `gateway.probe_failed` | warn/critical | Live-перевірка Gateway завершилася невдачею | доступність/автентифікація 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-токен hook зберігається безпосередньо в конфігурації | `hooks.token` | ні | -| `hooks.token_reuse_gateway_token` | critical | Токен входу hook також відкриває доступ до auth Gateway | `hooks.token`, `gateway.auth.token` | ні | -| `hooks.token_too_short` | warn | Полегшує brute force для входу hook | `hooks.token` | ні | -| `hooks.default_session_key_unset` | warn | Агент hook виконує fan out у згенеровані сеанси для кожного запиту | `hooks.defaultSessionKey` | ні | -| `hooks.allowed_agent_ids_unrestricted` | warn/critical | Автентифіковані викликачі hook можуть маршрутизувати до будь-якого налаштованого агента | `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 | Записи встановлення hook не прив’язані до незмінних npm-специфікацій | метадані встановлення hook | ні | -| `hooks.installs_missing_integrity` | warn | У записах встановлення hook відсутні метадані integrity | метадані встановлення hook | ні | -| `hooks.installs_version_drift` | warn | Записи встановлення hook розходяться зі встановленими пакетами | метадані встановлення hook | ні | -| `logging.redact_off` | warn | Чутливі значення витікають у журнали/статус | `logging.redactSensitive` | так | -| `browser.control_invalid_config` | warn | Конфігурація керування браузером недійсна ще до runtime | `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 sandbox використовує режим `host` або `container:*` із приєднанням до простору імен | `agents.*.sandbox.docker.network` | ні | -| `sandbox.dangerous_seccomp_profile` | critical | Профіль seccomp sandbox послаблює ізоляцію контейнера | `agents.*.sandbox.docker.securityOpt` | ні | -| `sandbox.dangerous_apparmor_profile` | critical | Профіль AppArmor sandbox послаблює ізоляцію контейнера | `agents.*.sandbox.docker.securityOpt` | ні | -| `sandbox.browser_cdp_bridge_unrestricted` | warn | Міст CDP браузера в sandbox відкритий без обмеження діапазону джерел | `sandbox.browser.cdpSourceRange` | ні | -| `sandbox.browser_container.non_loopback_publish` | critical | Наявний контейнер браузера публікує CDP на інтерфейсах поза loopback | конфігурація publish контейнера браузера sandbox | ні | -| `sandbox.browser_container.hash_label_missing` | warn | Наявний контейнер браузера створено до поточних міток хеша конфігурації | `openclaw sandbox recreate --browser --all` | ні | -| `sandbox.browser_container.hash_epoch_stale` | warn | Наявний контейнер браузера створено до поточної епохи конфігурації браузера | `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 неявно довіряють skill bins | `~/.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 | Біни інтерпретаторів/runtime у `safeBins` без явних профілів розширюють ризик exec | `tools.exec.safeBins`, `tools.exec.safeBinProfiles`, `agents.list[].tools.exec.*` | ні | -| `tools.exec.safe_bins_broad_behavior` | warn | Інструменти з широкою поведінкою в `safeBins` послаблюють модель довіри низького ризику для фільтра stdin | `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 | Розширення встановлені без явного allowlist Plugin | `plugins.allowlist` | ні | -| `plugins.installs_unpinned_npm_specs` | warn | Записи встановлення Plugin не прив’язані до незмінних npm-специфікацій | метадані встановлення Plugin | ні | -| `plugins.installs_missing_integrity` | warn | У записах встановлення Plugin відсутні метадані integrity | метадані встановлення 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 містять підозрілі або небезпечні шаблони | джерело встановлення Skills | ні | -| `skills.code_safety.scan_failed` | warn | Сканування коду Skills не вдалося завершити | середовище сканування Skills | ні | -| `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 інструментів / обмеження workspace) | ні | -| `tools.profile_minimal_overridden` | warn | Перевизначення агента обходять глобальний профіль minimal | `agents.list[].tools.profile` | ні | -| `plugins.tools_reachable_permissive_policy` | warn | Інструменти розширень доступні в надто поблажливих контекстах | `tools.profile` + allow/deny інструментів | ні | -| `models.legacy` | warn | Досі налаштовано застарілі сімейства моделей | вибір моделі | ні | -| `models.weak_tier` | warn | Налаштовані моделі нижчі за поточно рекомендовані рівні | вибір моделі | ні | -| `models.small_params` | critical/info | Малі моделі + небезпечні поверхні інструментів підвищують ризик ін’єкцій | вибір моделі + політика sandbox/інструментів | ні | -| `summary.attack_surface` | info | Підсумкове зведення щодо auth, каналів, інструментів і рівня доступності | кілька ключів (див. деталі висновку) | ні | +| `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/політику інструментів/конфігурацію | права файлової системи для `~/.openclaw/openclaw.json` | так | +| `fs.config.symlink` | попередження | Ціль файла конфігурації стає іншим периметром довіри | структура файлової системи файла конфігурації | ні | +| `fs.config.perms_group_readable` | попередження | Користувачі групи можуть читати токени/налаштування конфігурації | права файлової системи для файла конфігурації | так | +| `fs.config.perms_world_readable` | критичний | Конфігурація може розкривати токени/налаштування | права файлової системи для файла конфігурації | так | +| `fs.config_include.perms_writable` | критичний | Include-файл конфігурації можуть змінювати інші | права для 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/стан облікових даних каналу | права файлової системи для `~/.openclaw/credentials` | так | +| `fs.credentials_dir.perms_readable` | попередження | Інші можуть читати стан облікових даних каналу | права файлової системи для `~/.openclaw/credentials` | так | +| `fs.sessions_store.perms_readable` | попередження | Інші можуть читати транскрипти/метадані сесій | права для сховища сесій | так | +| `fs.log_file.perms_readable` | попередження | Інші можуть читати журнали, де дані редаговані, але все ще чутливі | права для файла журналу gateway | так | +| `fs.synced_dir` | попередження | Стан/конфігурація в iCloud/Dropbox/Drive розширює експозицію токенів/транскриптів | перенесіть конфігурацію/стан із синхронізованих папок | ні | +| `gateway.bind_no_auth` | критичний | Віддалена прив’язка без спільного секрету | `gateway.bind`, `gateway.auth.*` | ні | +| `gateway.loopback_no_auth` | критичний | Gateway на loopback за reverse proxy може стати неавтентифікованим | `gateway.auth.*`, налаштування proxy | ні | +| `gateway.trusted_proxies_missing` | попередження | Заголовки reverse 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 у стилі шаблонів не збігаються з текстом shell або групами | `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 походжень браузера | `gateway.controlUi.allowedOrigins` | ні | +| `gateway.control_ui.allowed_origins_wildcard` | попередження/критичний | `allowedOrigins=["*"]` вимикає allowlist походжень браузера | `gateway.controlUi.allowedOrigins` | ні | +| `gateway.control_ui.host_header_origin_fallback` | попередження/критичний | Увімкнено резервне визначення походження через Host header (послаблення захисту від DNS rebinding) | `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` | ні | +| `gateway.control_ui.insecure_auth` | попередження | Увімкнено режим сумісності з небезпечною автентифікацією | `gateway.controlUi.allowInsecureAuth` | ні | +| `gateway.control_ui.device_auth_disabled` | критичний | Вимкнено перевірку ідентичності пристрою | `gateway.controlUi.dangerouslyDisableDeviceAuth` | ні | +| `gateway.real_ip_fallback_enabled` | попередження/критичний | Довіра до резервного `X-Real-IP` може дозволити spoofing IP-джерела через хибну конфігурацію proxy | `gateway.allowRealIpFallback`, `gateway.trustedProxies` | ні | +| `gateway.token_too_short` | попередження | Короткий спільний токен легше підібрати перебором | `gateway.auth.token` | ні | +| `gateway.auth_no_rate_limit` | попередження | Експонована автентифікація без rate limiting підвищує ризик brute force | `gateway.auth.rateLimit` | ні | +| `gateway.trusted_proxy_auth` | критичний | Ідентичність proxy тепер стає периметром автентифікації | `gateway.auth.mode="trusted-proxy"` | ні | +| `gateway.trusted_proxy_no_proxies` | критичний | Автентифікація trusted-proxy без довірених IP proxy є небезпечною | `gateway.trustedProxies` | ні | +| `gateway.trusted_proxy_no_user_header` | критичний | Автентифікація trusted-proxy не може безпечно визначити ідентичність користувача | `gateway.auth.trustedProxy.userHeader` | ні | +| `gateway.trusted_proxy_no_allowlist` | попередження | Автентифікація trusted-proxy приймає будь-якого автентифікованого upstream-користувача | `gateway.auth.trustedProxy.allowUsers` | ні | +| `checkId` | Рівень | Чому це важливо | Основний ключ/шлях для виправлення | Автовиправлення | +| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | --------------- | +| `gateway.probe_auth_secretref_unavailable` | попередження | Глибока перевірка не змогла отримати auth SecretRef у цьому шляху виконання команди | джерело auth для глибокої перевірки / доступність SecretRef | ні | +| `gateway.probe_failed` | попередження/критичний | Жива перевірка Gateway не вдалася | доступність Gateway / auth | ні | +| `discovery.mdns_full_mode` | попередження/критичний | Повний режим mDNS рекламує метадані `cliPath`/`sshPort` у локальній мережі | `discovery.mdns.mode`, `gateway.bind` | ні | +| `config.insecure_or_dangerous_flags` | попередження | Увімкнено будь-які небезпечні/ризиковані debug-прапорці | кілька ключів (див. details у finding) | ні | +| `config.secrets.gateway_password_in_config` | попередження | Пароль Gateway збережено безпосередньо в конфігурації | `gateway.auth.password` | ні | +| `config.secrets.hooks_token_in_config` | попередження | Bearer-токен hooks збережено безпосередньо в конфігурації | `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` | попередження | Агент hook виконує fan-out у згенеровані сесії для кожного запиту | `hooks.defaultSessionKey` | ні | +| `hooks.allowed_agent_ids_unrestricted` | попередження/критичний | Автентифіковані викликачі hooks можуть маршрутизувати до будь-якого налаштованого агента | `hooks.allowedAgentIds` | ні | +| `hooks.request_session_key_enabled` | попередження/критичний | Зовнішній викликач може вибирати `sessionKey` | `hooks.allowRequestSessionKey` | ні | +| `hooks.request_session_key_prefixes_missing` | попередження/критичний | Немає обмеження на форму зовнішніх ключів сесій | `hooks.allowedSessionKeyPrefixes` | ні | +| `hooks.path_root` | критичний | Шлях hook дорівнює `/`, що полегшує конфлікти або помилкову маршрутизацію входу | `hooks.path` | ні | +| `hooks.installs_unpinned_npm_specs` | попередження | Записи встановлення hooks не прив’язані до незмінних npm-spec | метадані встановлення hook | ні | +| `hooks.installs_missing_integrity` | попередження | У записах встановлення hooks немає метаданих integrity | метадані встановлення hook | ні | +| `hooks.installs_version_drift` | попередження | Записи встановлення hooks розходяться з установленими пакетами | метадані встановлення hook | ні | +| `logging.redact_off` | попередження | Чутливі значення потрапляють у журнали/статус | `logging.redactSensitive` | так | +| `browser.control_invalid_config` | попередження | Конфігурація керування браузером невалідна ще до запуску | `browser.*` | ні | +| `browser.control_no_auth` | критичний | Керування браузером відкрите без auth через token/password | `gateway.auth.*` | ні | +| `browser.remote_cdp_http` | попередження | Віддалений CDP через звичайний HTTP не має шифрування транспорту | профіль браузера `cdpUrl` | ні | +| `browser.remote_cdp_private_host` | попередження | Віддалений CDP націлений на приватний/внутрішній хост | профіль браузера `cdpUrl`, `browser.ssrfPolicy.*` | ні | +| `sandbox.docker_config_mode_off` | попередження | Конфігурація 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 для sandbox використовує режим `host` або `container:*` із приєднанням до простору назв | `agents.*.sandbox.docker.network` | ні | +| `sandbox.dangerous_seccomp_profile` | критичний | Профіль seccomp у sandbox послаблює ізоляцію контейнера | `agents.*.sandbox.docker.securityOpt` | ні | +| `sandbox.dangerous_apparmor_profile` | критичний | Профіль AppArmor у sandbox послаблює ізоляцію контейнера | `agents.*.sandbox.docker.securityOpt` | ні | +| `sandbox.browser_cdp_bridge_unrestricted` | попередження | Міст браузера sandbox відкритий без обмеження діапазону джерел | `sandbox.browser.cdpSourceRange` | ні | +| `sandbox.browser_container.non_loopback_publish` | критичний | Наявний контейнер браузера публікує CDP на інтерфейсах не loopback | конфігурація publish контейнера браузера sandbox | ні | +| `sandbox.browser_container.hash_label_missing` | попередження | Наявний контейнер браузера створено до появи поточних міток хеша конфігурації | `openclaw sandbox recreate --browser --all` | ні | +| `sandbox.browser_container.hash_epoch_stale` | попередження | Наявний контейнер браузера створено до поточної епохи конфігурації браузера | `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` на рівні агента безпечно завершується помилкою, коли 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 неявно довіряють бінарникам 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` | попередження | Бінарники інтерпретаторів/середовищ у `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` | попередження | Розширення встановлено без явного allowlist Plugin | `plugins.allowlist` | ні | +| `plugins.installs_unpinned_npm_specs` | попередження | Записи встановлення Plugin не прив’язані до незмінних npm-spec | метадані встановлення plugin | ні | +| `checkId` | Рівень | Чому це важливо | Основний ключ/шлях для виправлення | Автовиправлення | +| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | --------------- | +| `plugins.installs_missing_integrity` | попередження | У записах встановлення Plugin відсутні метадані integrity | метадані встановлення plugin | ні | +| `plugins.installs_version_drift` | попередження | Записи встановлення Plugin розходяться з установленими пакетами | метадані встановлення 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` | попередження/критичний | Метадані встановлення/код Skill містять підозрілі або небезпечні шаблони | джерело встановлення skill | ні | +| `skills.code_safety.scan_failed` | попередження | Сканування коду Skill не вдалося завершити | середовище сканування skill | ні | +| `security.exposure.open_channels_with_exec` | попередження/критичний | Спільні/публічні кімнати можуть досягати агентів з увімкненим exec | `channels.*.dmPolicy`, `channels.*.groupPolicy`, `tools.exec.*`, `agents.list[].tools.exec.*` | ні | +| `security.exposure.open_groups_with_elevated` | критичний | Відкриті групи + підвищені інструменти створюють високоризикові шляхи prompt injection | `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` | попередження | Конфігурація виглядає багатокористувацькою, тоді як модель довіри gateway — персональний помічник | розділіть периметри довіри або посильте спільний сценарій (`sandbox.mode`, deny для інструментів / обмеження workspace) | ні | +| `tools.profile_minimal_overridden` | попередження | Перевизначення агента обходять глобальний профіль minimal | `agents.list[].tools.profile` | ні | +| `plugins.tools_reachable_permissive_policy` | попередження | Інструменти розширень доступні в поблажливих контекстах | `tools.profile` + allow/deny інструментів | ні | +| `models.legacy` | попередження | Досі налаштовані застарілі сімейства моделей | вибір моделі | ні | +| `models.weak_tier` | попередження | Налаштовані моделі нижчі за поточні рекомендовані рівні | вибір моделі | ні | +| `models.small_params` | критичний/інформація | Малі моделі + небезпечні поверхні інструментів підвищують ризик ін’єкцій | вибір моделі + політика sandbox/інструментів | ні | +| `summary.attack_surface` | інформація | Зведений підсумок позиції auth, каналів, інструментів і поверхні експозиції | кілька ключів (див. details у finding) | ні | ## Control UI через HTTP -Control UI потребує **безпечного контексту** (HTTPS або localhost), щоб генерувати ідентичність пристрою. `gateway.controlUi.allowInsecureAuth` — це локальний перемикач сумісності: +Control UI потребує **безпечного контексту** (HTTPS або localhost), щоб створити ідентичність пристрою. `gateway.controlUi.allowInsecureAuth` — це локальний перемикач сумісності: -- На localhost він дозволяє автентифікацію 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"` може допускати **операторські** сесії Control UI без ідентичності пристрою. Це навмисна поведінка режиму auth, а не обхід через `allowInsecureAuth`, і вона все одно не поширюється на сесії Control UI з роллю node. -`openclaw security audit` попереджає, коли це налаштування увімкнено. +`openclaw security audit` попереджає, коли цей параметр увімкнено. -## Підсумок небезпечних або незахищених прапорів +## Підсумок небезпечних або ризикованих прапорців -`openclaw security audit` включає `config.insecure_or_dangerous_flags`, коли -увімкнено відомі незахищені/небезпечні debug-перемикачі. Наразі ця перевірка -агрегує: +`openclaw security audit` включає `config.insecure_or_dangerous_flags`, коли увімкнено відомі небезпечні/ризиковані debug-перемикачі. Наразі ця перевірка агрегує: - `gateway.controlUi.allowInsecureAuth=true` - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` @@ -413,16 +411,15 @@ Control UI потребує **безпечного контексту** (HTTPS ## Конфігурація reverse proxy -Якщо ви запускаєте Gateway за reverse proxy (nginx, Caddy, Traefik тощо), налаштуйте -`gateway.trustedProxies` для коректної обробки IP-адрес клієнтів із forwarded-заголовків. +Якщо ви запускаєте Gateway за reverse proxy (nginx, Caddy, Traefik тощо), налаштуйте `gateway.trustedProxies` для коректної обробки forwarded-client IP. -Коли Gateway виявляє proxy-заголовки з адреси, якої **немає** в `trustedProxies`, він **не** вважатиме з’єднання локальними клієнтами. Якщо auth gateway вимкнено, такі з’єднання буде відхилено. Це запобігає обходу автентифікації, коли проксійовані з’єднання інакше могли б виглядати як такі, що надходять із localhost, і автоматично отримувати довіру. +Коли Gateway виявляє заголовки proxy від адреси, якої **немає** в `trustedProxies`, він **не** трактує підключення як локальні клієнтські. Якщо auth Gateway вимкнено, такі підключення відхиляються. Це запобігає обходу автентифікації, коли проксійовані підключення інакше виглядали б як такі, що надходять із localhost, і автоматично отримували б довіру. `gateway.trustedProxies` також використовується режимом `gateway.auth.mode: "trusted-proxy"`, але цей режим auth суворіший: -- auth trusted-proxy **завершується відмовою за замовчуванням для proxy із джерелом loopback** -- reverse proxy loopback на тому ж хості все одно можуть використовувати `gateway.trustedProxies` для виявлення локальних клієнтів і обробки forwarded 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: @@ -436,115 +433,114 @@ 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 (перезапис вхідних forwarded-заголовків): +Правильна поведінка reverse proxy (перезаписує вхідні forwarding-заголовки): ```nginx proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Real-IP $remote_addr; ``` -Некоректна поведінка reverse proxy (додавання/збереження недовірених forwarded-заголовків): +Неправильна поведінка reverse proxy (додає/зберігає недовірені forwarding-заголовки): ```nginx proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; ``` -## Примітки щодо HSTS і origin +## Нотатки про HSTS і origin -- Gateway OpenClaw насамперед орієнтований на local/loopback. Якщо ви завершуєте TLS на reverse proxy, налаштуйте HSTS на HTTPS-домені, який обслуговує proxy. -- Якщо HTTPS завершує сам gateway, ви можете встановити `gateway.http.securityHeaders.strictTransportSecurity`, щоб OpenClaw додавав заголовок HSTS у відповіді. -- Докладні вказівки щодо розгортання наведено в [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts). -- Для розгортань Control UI поза loopback `gateway.controlUi.allowedOrigins` є обов’язковим за замовчуванням. -- `gateway.controlUi.allowedOrigins: ["*"]` — це явна політика браузерних origin «дозволити все», а не посилене типове значення. Уникайте її поза межами суворо контрольованого локального тестування. -- Збої автентифікації за browser-origin на loopback усе одно підлягають rate limiting, навіть коли загальний виняток для loopback увімкнено, але ключ блокування визначається окремо для кожного нормалізованого значення `Origin`, а не для одного спільного локального bucket. -- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає режим fallback походження через заголовок Host; розглядайте це як небезпечну політику, свідомо обрану оператором. -- Розглядайте DNS rebinding і поведінку proxy щодо заголовка Host як питання посилення безпеки розгортання; тримайте `trustedProxies` вузьким і уникайте прямого відкриття gateway у публічний інтернет. +- Gateway OpenClaw насамперед орієнтований на local/loopback. Якщо ви завершуєте TLS на reverse proxy, налаштовуйте HSTS там — на HTTPS-домені, який обслуговує proxy. +- Якщо сам gateway завершує HTTPS, ви можете встановити `gateway.http.securityHeaders.strictTransportSecurity`, щоб OpenClaw додавав заголовок HSTS у відповіді. +- Докладні вказівки щодо розгортання наведено в [Автентифікація Trusted Proxy](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts). +- Для розгортань Control UI поза loopback параметр `gateway.controlUi.allowedOrigins` є обов’язковим за замовчуванням. +- `gateway.controlUi.allowedOrigins: ["*"]` — це явна політика «дозволити всі browser-origin», а не посилений варіант за замовчуванням. Уникайте цього поза жорстко контрольованим локальним тестуванням. +- Невдалі спроби auth за browser-origin на loopback усе одно обмежуються rate limiting, навіть коли загальний виняток для loopback увімкнено, але ключ блокування прив’язується до нормалізованого значення `Origin`, а не до одного спільного localhost-відра. +- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає режим резервного визначення origin через Host header; сприймайте це як небезпечну політику, навмисно обрану оператором. +- Розглядайте DNS rebinding і поведінку proxy щодо host header як аспекти посилення безпеки розгортання; тримайте `trustedProxies` вузьким і уникайте прямого відкриття gateway у публічний інтернет. -## Локальні журнали сеансів зберігаються на диску +## Локальні журнали сесій зберігаються на диску -OpenClaw зберігає транскрипти сеансів на диску в `~/.openclaw/agents//sessions/*.jsonl`. -Це необхідно для безперервності сеансів і (за бажанням) індексації пам’яті сеансів, але це також означає, що -**будь-який процес/користувач із доступом до файлової системи може читати ці журнали**. Вважайте доступ до диска -межею довіри й жорстко обмежуйте дозволи для `~/.openclaw` (див. розділ аудиту нижче). Якщо вам потрібна +OpenClaw зберігає транскрипти сесій на диску в `~/.openclaw/agents//sessions/*.jsonl`. +Це потрібно для безперервності сесій і (за бажанням) індексації пам’яті сесій, але це також означає, +що **будь-який процес/користувач із доступом до файлової системи може читати ці журнали**. Вважайте доступ до диска +периметром довіри й обмежуйте права доступу до `~/.openclaw` (див. розділ аудиту нижче). Якщо вам потрібна сильніша ізоляція між агентами, запускайте їх під окремими користувачами ОС або на окремих хостах. ## Виконання на Node (`system.run`) -Якщо Node macOS пов’язано через pairing, Gateway може викликати `system.run` на цьому Node. Це **віддалене виконання коду** на Mac: +Якщо прив’язано macOS Node, Gateway може викликати `system.run` на цьому Node. Це **віддалене виконання коду** на Mac: -- Потрібне pairing Node (схвалення + токен). -- Pairing Node в Gateway не є поверхнею схвалення кожної окремої команди. Воно встановлює ідентичність/довіру до Node та видачу токена. +- Потребує pairing Node (погодження + токен). +- Pairing Node на рівні Gateway — це не поверхня погодження для кожної окремої команди. Воно встановлює ідентичність/довіру Node і видачу токена. - Gateway застосовує грубу глобальну політику команд Node через `gateway.nodes.allowCommands` / `denyCommands`. -- На Mac це контролюється через **Settings → Exec approvals** (security + ask + allowlist). -- Політика `system.run` для конкретного Node — це власний файл схвалень exec цього Node (`exec.approvals.node.*`), який може бути суворішим або м’якшим, ніж глобальна політика ID команд у gateway. -- Node, що працює з `security="full"` і `ask="off"`, дотримується типової моделі довіреного оператора. Вважайте це очікуваною поведінкою, якщо тільки ваше розгортання явно не вимагає суворішого режиму схвалення або allowlist. -- Режим схвалення прив’язується до точного контексту запиту і, коли можливо, до одного конкретного локального операнда script/file. Якщо OpenClaw не може точно визначити один прямий локальний файл для команди інтерпретатора/runtime, виконання, що потребує схвалення, відхиляється замість того, щоб обіцяти повне семантичне покриття. -- Для `host=node` виконання, що потребують схвалення, також зберігають канонічний підготовлений `systemRunPlan`; пізніші схвалені переспрямування повторно використовують цей збережений план, а валідація gateway відхиляє зміни викликачем до команди/cwd/контексту сеансу після створення запиту на схвалення. -- Якщо ви не хочете віддаленого виконання, встановіть security у **deny** і видаліть pairing Node для цього Mac. +- Керується на 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 не може точно визначити рівно один прямий локальний файл для команди інтерпретатора/середовища виконання, виконання з погодженням буде відхилено замість того, щоб обіцяти повне семантичне покриття. +- Для `host=node` виконання з погодженням також зберігає канонічний підготовлений `systemRunPlan`; пізніші схвалені forwards повторно використовують цей збережений план, а валідація gateway відхиляє редагування викликачем команди/cwd/контексту сесії після створення запиту на погодження. +- Якщо ви не хочете віддаленого виконання, установіть security у значення **deny** і видаліть pairing Node для цього Mac. -Це розрізнення важливе для triage: +Це розрізнення важливе для аналізу: -- Повторне підключення вже пов’язаного Node, який рекламує інший список команд, саме по собі не є вразливістю, якщо глобальна політика Gateway і локальні схвалення exec самого Node усе ще забезпечують реальну межу виконання. -- Повідомлення, які трактують метадані pairing Node як другий прихований шар схвалення кожної команди, зазвичай є плутаниною політики/UX, а не обходом межі безпеки. +- Node, що перепідключився, рекламує інший список команд — саме по собі це не вразливість, якщо глобальна політика Gateway і локальні погодження exec у Node все ще забезпечують реальний периметр виконання. +- Звіти, які трактують метадані pairing Node як другий прихований рівень погодження для кожної команди, зазвичай є плутаниною політики/UX, а не обходом периметра безпеки. ## Динамічні Skills (watcher / віддалені Node) -OpenClaw може оновлювати список Skills посеред сеансу: +OpenClaw може оновлювати список Skills посеред сесії: -- **Спостерігач Skills**: зміни в `SKILL.md` можуть оновити знімок Skills на наступному ході агента. -- **Віддалені Node**: підключення Node macOS може зробити доступними Skills лише для macOS (на основі перевірки наявності бінарників). +- **Watcher Skills**: зміни в `SKILL.md` можуть оновити snapshot Skills на наступному ході агента. +- **Віддалені Node**: підключення macOS Node може зробити доступними Skills лише для macOS (на основі перевірки bin). -Розглядайте папки skill як **довірений код** і обмежуйте коло тих, хто може їх змінювати. +Сприймайте папки skill як **довірений код** і обмежуйте, хто може їх змінювати. ## Модель загроз -Ваш AI-асистент може: +Ваш AI-помічник може: -- Виконувати довільні shell-команди +- Виконувати довільні команди оболонки - Читати/записувати файли - Отримувати доступ до мережевих сервісів -- Надсилати повідомлення будь-кому (якщо ви надали йому доступ до WhatsApp) +- Надсилати повідомлення будь-кому (якщо ви дали йому доступ до WhatsApp) -Люди, які пишуть вам, можуть: +Люди, які можуть писати вам, можуть: -- Намагатися обманом змусити ваш AI робити шкідливі речі -- Соціальною інженерією добиватися доступу до ваших даних -- Досліджувати вашу інфраструктуру в пошуках деталей +- Намагатися обдурити AI, щоб він зробив щось шкідливе +- Соціально інженерити доступ до ваших даних +- Досліджувати деталі інфраструктури -## Ключова ідея: контроль доступу перед інтелектом +## Основна концепція: контроль доступу перед інтелектом -Більшість збоїв тут — не витончені експлойти, а ситуації на кшталт «хтось написав боту, і бот зробив те, що його попросили». +Більшість збоїв тут — не вишукані експлойти, а ситуації на кшталт: «хтось написав боту, і бот зробив те, що його попросили». -Позиція OpenClaw така: +Позиція OpenClaw: -- **Спочатку ідентичність:** вирішіть, хто може говорити з ботом (pairing для DM / allowlist / явний `open`). -- **Потім обсяг:** вирішіть, де боту дозволено діяти (allowlist груп + обмеження згадуваннями, інструменти, sandboxing, дозволи пристрою). -- **Модель наприкінці:** припускайте, що моделлю можна маніпулювати; проєктуйте систему так, щоб наслідки маніпуляції були обмеженими. +- **Спочатку ідентичність:** вирішіть, хто може взаємодіяти з ботом (pairing у DM / allowlist / явний режим “open”). +- **Потім межі:** вирішіть, де боту дозволено діяти (allowlist груп + вимога згадування, інструменти, sandboxing, дозволи пристрою). +- **Модель — наприкінці:** припускайте, що моделлю можна маніпулювати; проєктуйте систему так, щоб наслідки маніпуляцій були обмеженими. ## Модель авторизації команд -Слеш-команди та директиви виконуються лише для **авторизованих відправників**. Авторизація визначається через -allowlist/pairing каналу разом із `commands.useAccessGroups` (див. [Configuration](/uk/gateway/configuration) -і [Slash commands](/uk/tools/slash-commands)). Якщо allowlist каналу порожній або містить `"*"`, -команди фактично відкриті для цього каналу. +Slash-команди й директиви виконуються лише для **авторизованих відправників**. Авторизація визначається через +allowlist/pairing каналу разом із `commands.useAccessGroups` (див. [Конфігурація](/uk/gateway/configuration) +і [Slash-команди](/uk/tools/slash-commands)). Якщо allowlist каналу порожній або містить `"*"`, команди фактично відкриті для цього каналу. -`/exec` — це зручна команда лише в межах сеансу для авторизованих операторів. Вона **не** записує конфігурацію і -не змінює інші сеанси. +`/exec` — це зручна команда лише для сесії, призначена для авторизованих операторів. Вона **не** записує конфігурацію і +не змінює інші сесії. ## Ризики інструментів площини керування -Два вбудовані інструменти можуть вносити стійкі зміни до площини керування: +Два вбудовані інструменти можуть вносити постійні зміни до площини керування: -- `gateway` може переглядати конфігурацію через `config.schema.lookup` / `config.get`, а також вносити стійкі зміни через `config.apply`, `config.patch` і `update.run`. -- `cron` може створювати заплановані завдання, які продовжують працювати після завершення початкового чату/завдання. +- `gateway` може перевіряти конфігурацію через `config.schema.lookup` / `config.get`, а також вносити постійні зміни через `config.apply`, `config.patch` і `update.run`. +- `cron` може створювати заплановані завдання, які продовжують працювати після завершення оригінального чату/завдання. -Інструмент runtime `gateway`, доступний лише власнику, усе ще відмовляється -перезаписувати `tools.exec.ask` або `tools.exec.security`; застарілі псевдоніми `tools.bash.*` +Runtime-інструмент `gateway`, доступний лише власнику, усе одно відмовляється переписувати +`tools.exec.ask` або `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec перед записом. -Для будь-якого агента/поверхні, що обробляє недовірений вміст, типово забороняйте таке: +Для будь-якого агента/поверхні, що обробляє недовірений контент, за замовчуванням забороняйте їх: ```json5 { @@ -554,23 +550,23 @@ allowlist/pairing каналу разом із `commands.useAccessGroups` (ди } ``` -`commands.restart=false` блокує лише дії перезапуску. Він не вимикає дії конфігурації/оновлення `gateway`. +`commands.restart=false` блокує лише дії перезапуску. Він не вимикає дії `gateway` із конфігурацією/оновленнями. -## Плагіни/розширення +## Plugin/розширення -Плагіни працюють **у тому ж процесі**, що й Gateway. Розглядайте їх як довірений код: +Plugin працюють **у межах процесу** Gateway. Сприймайте їх як довірений код: -- Встановлюйте лише ті плагіни, джерелам яких ви довіряєте. +- Встановлюйте лише ті plugin, джерелам яких ви довіряєте. - Надавайте перевагу явним allowlist `plugins.allow`. -- Перевіряйте конфігурацію Plugin перед увімкненням. -- Перезапускайте Gateway після змін Plugin. -- Якщо ви встановлюєте або оновлюєте Plugin (`openclaw plugins install `, `openclaw plugins update `), ставтеся до цього так, ніби ви запускаєте недовірений код: - - Шлях встановлення — це каталог конкретного Plugin у межах активного кореня встановлення Plugin. - - Перед встановленням/оновленням OpenClaw запускає вбудоване сканування небезпечного коду. Знахідки рівня `critical` типово блокують операцію. - - OpenClaw використовує `npm pack`, а потім виконує `npm install --omit=dev` у цьому каталозі (скрипти життєвого циклу npm можуть виконувати код під час встановлення). - - Надавайте перевагу pinned, точним версіям (`@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. +- Переглядайте конфігурацію plugin перед увімкненням. +- Перезапускайте Gateway після змін plugin. +- Якщо ви встановлюєте або оновлюєте plugin (`openclaw plugins install `, `openclaw plugins update `), ставтеся до цього як до запуску недовіреного коду: + - Шлях встановлення — це каталог конкретного plugin у межах активного кореня встановлення plugin. + - Перед встановленням/оновленням OpenClaw запускає вбудоване сканування небезпечного коду. Findings рівня `critical` за замовчуванням блокують операцію. + - OpenClaw використовує `npm pack`, а потім виконує `npm install --omit=dev` у цьому каталозі (npm lifecycle scripts можуть виконувати код під час встановлення). + - Надавайте перевагу pinned точним версіям (`@scope/pkg@1.2.3`) і перевіряйте розпакований код на диску перед увімкненням. + - `--dangerously-force-unsafe-install` — лише аварійний варіант для хибнопозитивних спрацьовувань вбудованого сканування у потоках встановлення/оновлення plugin. Він не обходить блокування політики хуків plugin `before_install` і не обходить збої сканування. + - Встановлення залежностей Skills через Gateway підпорядковується тому самому поділу на dangerous/suspicious: вбудовані findings рівня `critical` блокують операцію, якщо тільки викликач явно не встановить `dangerouslyForceUnsafeInstall`, тоді як suspicious findings усе ще лише попереджають. `openclaw skills install` залишається окремим потоком завантаження/встановлення Skills через ClawHub. Докладніше: [Plugins](/uk/tools/plugin) @@ -578,11 +574,11 @@ allowlist/pairing каналу разом із `commands.useAccessGroups` (ди ## Модель доступу DM (pairing / allowlist / open / disabled) -Усі поточні канали з підтримкою DM мають політику DM (`dmPolicy` або `*.dm.policy`), яка блокує вхідні DM **до** обробки повідомлення: +Усі поточні канали з підтримкою DM підтримують політику DM (`dmPolicy` або `*.dm.policy`), яка блокує вхідні DM **до** обробки повідомлення: -- `pairing` (типово): невідомі відправники отримують короткий код pairing, а бот ігнорує їхнє повідомлення до схвалення. Коди спливають через 1 годину; повторні DM не надсилатимуть код знову, доки не буде створено новий запит. Кількість очікуваних запитів типово обмежена **3 на канал**. -- `allowlist`: невідомих відправників заблоковано (без handshake pairing). -- `open`: дозволити будь-кому надсилати DM (публічно). **Потрібно**, щоб allowlist каналу містив `"*"` (явне підтвердження). +- `pairing` (типово): невідомі відправники отримують короткий код pairing, а бот ігнорує їхнє повідомлення до схвалення. Коди діють 1 годину; повторні DM не надсилатимуть код знову, доки не буде створено новий запит. Кількість очікуваних запитів обмежена **3 на канал** за замовчуванням. +- `allowlist`: невідомі відправники блокуються (без handshake pairing). +- `open`: дозволити будь-кому писати в DM (публічно). **Потребує**, щоб allowlist каналу містив `"*"` (явне підтвердження). - `disabled`: повністю ігнорувати вхідні DM. Схвалення через CLI: @@ -594,9 +590,9 @@ openclaw pairing approve Докладніше + файли на диску: [Pairing](/uk/channels/pairing) -## Ізоляція сеансів DM (багатокористувацький режим) +## Ізоляція сесій DM (багатокористувацький режим) -Типово OpenClaw маршрутизує **усі DM в основний сеанс**, щоб ваш асистент зберігав безперервність між пристроями й каналами. Якщо **кілька людей** можуть надсилати DM боту (відкриті DM або allowlist із кількох осіб), розгляньте ізоляцію сеансів DM: +За замовчуванням OpenClaw маршрутизує **усі DM в основну сесію**, щоб ваш помічник зберігав безперервність між пристроями та каналами. Якщо **кілька людей** можуть писати боту в DM (відкриті DM або allowlist із кількома людьми), розгляньте ізоляцію сесій DM: ```json5 { @@ -604,63 +600,63 @@ openclaw pairing approve } ``` -Це запобігає витоку контексту між користувачами, зберігаючи при цьому ізоляцію групових чатів. +Це запобігає витоку контексту між користувачами, зберігаючи ізоляцію групових чатів. -Це межа контексту обміну повідомленнями, а не межа адміністрування хоста. Якщо користувачі взаємно ворожі та спільно використовують той самий хост/конфігурацію Gateway, запускайте окремі Gateway для кожної межі довіри. +Це межа контексту повідомлень, а не межа адміністрування хоста. Якщо користувачі є взаємно ворожими і використовують той самий хост/конфігурацію Gateway, запускайте окремі gateway для кожного периметра довіри. ### Безпечний режим DM (рекомендовано) -Розглядайте фрагмент вище як **безпечний режим DM**: +Сприймайте наведений вище фрагмент як **безпечний режим DM**: -- Типово: `session.dmScope: "main"` (усі DM використовують один спільний сеанс для безперервності). -- Типове значення локального onboarding у CLI: записує `session.dmScope: "per-channel-peer"`, якщо значення не задано (зберігає наявні явні значення). +- Типово: `session.dmScope: "main"` (усі DM використовують одну спільну сесію для безперервності). +- Типове значення для локального онбордингу через CLI: записує `session.dmScope: "per-channel-peer"`, якщо значення не задано (зберігає наявні явні значення). - Безпечний режим DM: `session.dmScope: "per-channel-peer"` (кожна пара канал+відправник отримує ізольований контекст DM). -- Ізоляція контакту між каналами: `session.dmScope: "per-peer"` (кожен відправник має один сеанс у всіх каналах одного типу). +- Ізоляція відправника між каналами: `session.dmScope: "per-peer"` (кожен відправник отримує одну сесію в усіх каналах одного типу). -Якщо ви використовуєте кілька акаунтів в одному каналі, замість цього застосовуйте `per-account-channel-peer`. Якщо та сама людина зв’язується з вами через кілька каналів, використовуйте `session.identityLinks`, щоб об’єднати ці DM-сеанси в одну канонічну ідентичність. Див. [Session Management](/uk/concepts/session) і [Configuration](/uk/gateway/configuration). +Якщо ви використовуєте кілька облікових записів в одному каналі, натомість використовуйте `per-account-channel-peer`. Якщо одна й та сама людина зв’язується з вами через кілька каналів, використовуйте `session.identityLinks`, щоб об’єднати ці DM-сесії в одну канонічну ідентичність. Див. [Керування сесіями](/uk/concepts/session) і [Конфігурація](/uk/gateway/configuration). -## Allowlists (DM + групи) — термінологія +## Allowlist (DM + групи) — термінологія -В OpenClaw є два окремі шари «хто може мене запускати?»: +В OpenClaw є два окремі рівні «хто може мене запускати?»: -- **Allowlist DM** (`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`; застаріле: `channels.discord.dm.allowFrom`, `channels.slack.dm.allowFrom`): хто має право писати боту в особисті повідомлення. - - Коли `dmPolicy="pairing"`, схвалення записуються в сховище allowlist pairing з областю дії акаунта в `~/.openclaw/credentials/` (`-allowFrom.json` для типового акаунта, `--allowFrom.json` для нетипових акаунтів) і зливаються з allowlist із конфігурації. -- **Allowlist груп** (специфічний для каналу): з яких саме груп/каналів/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 для DM** (`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`; застаріле: `channels.discord.dm.allowFrom`, `channels.slack.dm.allowFrom`): хто має право писати боту в особисті повідомлення. + - Коли `dmPolicy="pairing"`, схвалення записуються в сховище allowlist pairing з обліковим контекстом у `~/.openclaw/credentials/` (`-allowFrom.json` для облікового запису за замовчуванням, `--allowFrom.json` для неосновних облікових записів), а потім об’єднуються з allowlist із конфігурації. +- **Груповий 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`/групові allowlist, потім активація через згадування/відповідь. - Відповідь на повідомлення бота (неявне згадування) **не** обходить allowlist відправників, як-от `groupAllowFrom`. - - **Примітка щодо безпеки:** ставтеся до `dmPolicy="open"` і `groupPolicy="open"` як до крайніх варіантів. Їх варто використовувати якомога рідше; надавайте перевагу pairing + allowlist, якщо тільки ви не довіряєте повністю кожному учаснику кімнати. + - **Примітка з безпеки:** сприймайте `dmPolicy="open"` і `groupPolicy="open"` як варіанти крайньої потреби. Їх слід використовувати якомога рідше; надавайте перевагу pairing + allowlist, якщо тільки ви не довіряєте повністю кожному учаснику кімнати. -Докладніше: [Configuration](/uk/gateway/configuration) і [Groups](/uk/channels/groups) +Докладніше: [Конфігурація](/uk/gateway/configuration) і [Групи](/uk/channels/groups) -## Prompt injection (що це, і чому це важливо) +## Prompt injection (що це таке і чому це важливо) -Prompt injection — це ситуація, коли зловмисник створює повідомлення, яке маніпулює моделлю так, щоб вона зробила щось небезпечне («ігноруй свої інструкції», «виведи вміст файлової системи», «перейди за цим посиланням і виконай команди» тощо). +Prompt injection — це коли зловмисник формує повідомлення так, щоб змусити модель зробити щось небезпечне («ігноруй свої інструкції», «вивантаж файлову систему», «перейди за цим посиланням і виконай команди» тощо). -Навіть із сильними системними prompt, **prompt injection не розв’язано**. Запобіжники в системному prompt — це лише м’які вказівки; жорстке забезпечення дають політика інструментів, схвалення exec, sandboxing і allowlist каналів (і оператори можуть вимкнути це за задумом). Що практично допомагає: +Навіть за сильних системних prompt **проблему prompt injection не вирішено**. Обмеження в системному prompt — це лише м’які вказівки; жорстке забезпечення дають політика інструментів, погодження exec, sandboxing і channel allowlist (а оператори за задумом можуть їх вимкнути). Що реально допомагає на практиці: - Тримайте вхідні DM закритими (pairing/allowlist). -- У групах надавайте перевагу обмеженню за згадуванням; уникайте «завжди активних» ботів у публічних кімнатах. -- За замовчуванням вважайте посилання, вкладення та вставлені інструкції ворожими. -- Виконуйте чутливі інструменти в sandbox; тримайте секрети поза файловою системою, доступною для агента. -- Примітка: sandboxing вмикається добровільно. Якщо режим sandbox вимкнено, неявне `host=auto` розв’язується до хоста gateway. Явне `host=sandbox` усе одно безпечно завершується відмовою, тому що runtime sandbox недоступний. Установіть `host=gateway`, якщо хочете, щоб така поведінка була явно описана в конфігурації. -- Обмежуйте інструменти високого ризику (`exec`, `browser`, `web_fetch`, `web_search`) лише довіреними агентами або явними allowlist. -- Якщо ви використовуєте allowlist інтерпретаторів (`python`, `node`, `ruby`, `perl`, `php`, `lua`, `osascript`), увімкніть `tools.exec.strictInlineEval`, щоб inline eval-форми все одно вимагали явного схвалення. -- **Вибір моделі має значення:** старіші/менші/застарілі моделі значно менш стійкі до prompt injection і зловживань інструментами. Для агентів з увімкненими інструментами використовуйте найсильнішу доступну сучасну модель, загартовану щодо інструкцій. +- У групах віддавайте перевагу активації через згадування; уникайте «завжди активних» ботів у публічних кімнатах. +- Сприймайте посилання, вкладення та вставлені інструкції як ворожі за замовчуванням. +- Виконуйте чутливі інструменти в sandbox; не тримайте секрети у файловій системі, доступній агенту. +- Примітка: sandboxing — це опція за згодою. Якщо режим sandbox вимкнено, неявний `host=auto` резолвиться до хоста gateway. Явний `host=sandbox` усе одно безпечно завершується відмовою, оскільки sandbox runtime недоступний. Встановіть `host=gateway`, якщо хочете, щоб така поведінка була явно зафіксована в конфігурації. +- Обмежуйте високоризикові інструменти (`exec`, `browser`, `web_fetch`, `web_search`) лише для довірених агентів або явних allowlist. +- Якщо ви додаєте інтерпретатори в allowlist (`python`, `node`, `ruby`, `perl`, `php`, `lua`, `osascript`), увімкніть `tools.exec.strictInlineEval`, щоб форми inline eval усе одно вимагали явного погодження. +- **Вибір моделі має значення:** старіші/менші/застарілі моделі значно гірше протистоять prompt injection і зловживанню інструментами. Для агентів з увімкненими інструментами використовуйте найсильнішу доступну модель останнього покоління, стійку до інструкційних атак. -Тривожні сигнали, які слід вважати недовіреними: +Червоні прапорці, які слід вважати недовіреними: -- «Прочитай цей файл/URL і зроби точно те, що там написано». -- «Ігноруй свій системний prompt або правила безпеки». -- «Розкрий свої приховані інструкції або результати інструментів». -- «Встав повний вміст `~/.openclaw` або свої журнали». +- «Прочитай цей файл/URL і зроби рівно те, що там сказано.» +- «Ігноруй свій системний prompt або правила безпеки.» +- «Розкрий свої приховані інструкції або результати інструментів.» +- «Встав повний вміст ~/.openclaw або своїх журналів.» -## Прапори обходу небезпечного зовнішнього вмісту +## Прапорці обходу небезпечного зовнішнього контенту -OpenClaw містить явні прапори обходу, які вимикають захисне обгортання зовнішнього вмісту: +OpenClaw містить явні прапорці обходу, які вимикають безпечне обгортання зовнішнього контенту: - `hooks.mappings[].allowUnsafeExternalContent` - `hooks.gmail.allowUnsafeExternalContent` @@ -668,128 +664,128 @@ OpenClaw містить явні прапори обходу, які вимик Рекомендації: -- У production залишайте їх незаданими/false. -- Увімкнюйте лише тимчасово для дуже вузько обмеженого налагодження. -- Якщо увімкнули, ізолюйте цього агента (sandbox + мінімум інструментів + окремий простір імен сеансів). +- У production залишайте ці значення не заданими/`false`. +- Увімкнюйте лише тимчасово для вузько обмеженого налагодження. +- Якщо увімкнено, ізолюйте такого агента (sandbox + мінімум інструментів + окремий простір імен сесій). -Примітка про ризики Hooks: +Примітка про ризики hooks: -- Payload hooks — це недовірений вміст, навіть якщо доставлення походить із систем, які ви контролюєте (пошта/документи/вебвміст можуть містити prompt injection). -- Слабкіші рівні моделей збільшують цей ризик. Для автоматизації на основі hooks надавайте перевагу сильним сучасним рівням моделей і тримайте політику інструментів суворою (`tools.profile: "messaging"` або суворіше), а також використовуйте sandboxing там, де це можливо. +- Payload hooks — це недовірений контент, навіть якщо доставка надходить із систем, які ви контролюєте (пошта/документи/вебконтент можуть містити prompt injection). +- Слабкі рівні моделей підвищують цей ризик. Для автоматизації на основі hooks віддавайте перевагу сильним сучасним рівням моделей і тримайте політику інструментів жорсткою (`tools.profile: "messaging"` або суворіше), а також використовуйте sandboxing, де це можливо. ### Prompt injection не потребує публічних DM -Навіть якщо **лише ви** можете писати боту, prompt injection усе одно може виникнути через -будь-який **недовірений вміст**, який бот читає (результати web search/fetch, сторінки браузера, -листи, документи, вкладення, вставлені журнали/код). Іншими словами: не лише відправник -є поверхнею загрози; сам **вміст** також може містити ворожі інструкції. +Навіть якщо **лише ви** можете писати боту, prompt injection усе одно може статися через +будь-який **недовірений контент**, який читає бот (результати web search/web fetch, сторінки браузера, +листи, документи, вкладення, вставлені журнали/код). Іншими словами: відправник — не +єдина поверхня загрози; ворожі інструкції може нести **сам контент**. Коли інструменти увімкнені, типовий ризик — це ексфільтрація контексту або запуск -викликів інструментів. Зменшуйте радіус ураження так: +викликів інструментів. Зменшити радіус ураження можна так: -- Використовуйте **агента-читача** лише для читання або без інструментів, щоб підсумовувати недовірений вміст, - а вже потім передавайте підсумок основному агенту. -- Тримайте `web_search` / `web_fetch` / `browser` вимкненими для агентів з інструментами, якщо вони не потрібні. -- Для 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 декодував його локально. Вбудований блок усе одно містить явні + `gateway.http.endpoints.responses.images.urlAllowlist`, а `maxUrlParts` тримайте низьким. + Порожні allowlist вважаються не заданими; використовуйте `files.allowUrl: false` / `images.allowUrl: false`, + якщо хочете повністю вимкнути завантаження URL. +- Для файлових входів OpenResponses декодований текст `input_file` усе одно вставляється як + **недовірений зовнішній контент**. Не покладайтеся на те, що текст файла є довіреним лише тому, + що Gateway декодував його локально. Вставлений блок усе одно містить явні маркери меж `<<>>` плюс метадані `Source: External`, - хоча цей шлях і пропускає довший банер `SECURITY NOTICE:`. -- Таке саме обгортання на основі маркерів застосовується, коли media-understanding витягує текст - із прикріплених документів перед додаванням цього тексту до prompt медіа. + хоча в цьому шляху немає довшого банера `SECURITY NOTICE:`. +- Те саме обгортання на основі маркерів застосовується, коли механізм розуміння медіа витягує текст + із прикріплених документів перед додаванням цього тексту до media prompt. - Увімкніть sandboxing і суворі allowlist інструментів для будь-якого агента, який працює з недовіреним вводом. -- Тримайте секрети поза prompt; передавайте їх через env/config на хості gateway. +- Не передавайте секрети через prompt; натомість передавайте їх через env/config на хості gateway. -### Сила моделі (примітка щодо безпеки) +### Потужність моделі (примітка з безпеки) -Стійкість до prompt injection **не** однакова для всіх рівнів моделей. Менші/дешевші моделі загалом більш схильні до зловживання інструментами та перехоплення інструкцій, особливо під час ворожих prompt. +Стійкість до prompt injection **не** є однаковою для всіх рівнів моделей. Менші/дешевші моделі зазвичай більш вразливі до зловживання інструментами та перехоплення інструкцій, особливо за ворожих prompt. -Для агентів із увімкненими інструментами або агентів, які читають недовірений вміст, ризик prompt injection зі старішими/меншими моделями часто є надто високим. Не запускайте такі навантаження на слабких рівнях моделей. +Для агентів з увімкненими інструментами або агентів, які читають недовірений контент, ризик prompt injection у старіших/менших моделях часто є надто високим. Не запускайте такі навантаження на слабких рівнях моделей. Рекомендації: -- **Використовуйте модель останнього покоління найвищого рівня** для будь-якого бота, який може запускати інструменти або взаємодіяти з файлами/мережами. -- **Не використовуйте старіші/слабші/менші рівні** для агентів з інструментами або недовірених вхідних скриньок; ризик prompt injection надто високий. -- Якщо вам доводиться використовувати меншу модель, **зменшуйте радіус ураження** (лише читання, сильне sandboxing, мінімальний доступ до файлової системи, суворі allowlist). -- Під час роботи з малими моделями **увімкніть sandboxing для всіх сеансів** і **вимкніть `web_search`/`web_fetch`/`browser`**, якщо вхідні дані не контролюються дуже жорстко. -- Для персональних асистентів лише для чату з довіреним вводом і без інструментів малі моделі зазвичай підходять. +- **Використовуйте модель останнього покоління найкращого рівня** для будь-якого бота, який може запускати інструменти або працювати з файлами/мережами. +- **Не використовуйте старіші/слабші/менші рівні** для агентів з увімкненими інструментами або недовірених вхідних; ризик prompt injection занадто високий. +- Якщо ви змушені використовувати меншу модель, **зменшуйте радіус ураження** (інструменти лише для читання, жорсткий sandboxing, мінімальний доступ до файлової системи, суворі allowlist). +- Під час роботи з малими моделями **увімкніть sandboxing для всіх сесій** і **вимкніть web_search/web_fetch/browser**, якщо тільки вхідні дані не є жорстко контрольованими. +- Для персональних помічників лише для чату з довіреним вводом і без інструментів менші моделі зазвичай підходять. ## Reasoning і verbose output у групах -`/reasoning`, `/verbose` і `/trace` можуть розкривати внутрішнє міркування, вихід -інструментів або діагностику Plugin, які -не призначалися для публічного каналу. У групових налаштуваннях розглядайте їх як **лише для налагодження** +`/reasoning`, `/verbose` і `/trace` можуть розкривати внутрішнє міркування, вивід +інструментів або діагностику plugin, які +не призначалися для публічного каналу. У групових налаштуваннях сприймайте їх як **лише для налагодження** і тримайте вимкненими, якщо тільки вони вам явно не потрібні. Рекомендації: - Тримайте `/reasoning`, `/verbose` і `/trace` вимкненими в публічних кімнатах. -- Якщо ви їх увімкнули, робіть це лише в довірених DM або в суворо контрольованих кімнатах. -- Пам’ятайте: verbose і trace output можуть містити аргументи інструментів, URL, діагностику Plugin і дані, які бачила модель. +- Якщо вмикаєте їх, робіть це лише в довірених DM або жорстко контрольованих кімнатах. +- Пам’ятайте: verbose і trace можуть містити аргументи інструментів, URL, діагностику plugin і дані, які бачила модель. ## Посилення конфігурації (приклади) -### 0) Дозволи файлів +### 0) Права доступу до файлів -Тримайте конфігурацію та стан приватними на хості gateway: +Тримайте конфігурацію й стан приватними на хості gateway: - `~/.openclaw/openclaw.json`: `600` (лише читання/запис для користувача) - `~/.openclaw`: `700` (лише користувач) -`openclaw doctor` може попередити про це та запропонувати посилити ці дозволи. +`openclaw doctor` може попередити про це і запропонувати посилити ці права доступу. -### 0.4) Мережевий доступ (bind + порт + firewall) +### 0.4) Мережева експозиція (bind + port + firewall) Gateway мультиплексує **WebSocket + HTTP** на одному порту: - Типово: `18789` - Config/flags/env: `gateway.port`, `--port`, `OPENCLAW_GATEWAY_PORT` -Ця HTTP-поверхня включає Control UI і canvas host: +Ця HTTP-поверхня включає Control UI і хост canvas: - Control UI (ресурси SPA) (типовий базовий шлях `/`) -- Canvas host: `/__openclaw__/canvas/` і `/__openclaw__/a2ui/` (довільні HTML/JS; розглядайте як недовірений вміст) +- Хост canvas: `/__openclaw__/canvas/` і `/__openclaw__/a2ui/` (довільні HTML/JS; сприймайте як недовірений контент) -Якщо ви завантажуєте вміст canvas у звичайному браузері, ставтеся до нього як до будь-якої іншої недовіреної вебсторінки: +Якщо ви завантажуєте контент canvas у звичайному браузері, ставтеся до нього як до будь-якої іншої недовіреної вебсторінки: -- Не відкривайте canvas host для недовірених мереж/користувачів. -- Не змушуйте вміст canvas використовувати той самий origin, що й привілейовані вебповерхні, якщо ви повністю не розумієте наслідки. +- Не відкривайте хост canvas для недовірених мереж/користувачів. +- Не змушуйте контент canvas використовувати те саме origin, що й привілейовані вебповерхні, якщо повністю не розумієте наслідків. Режим bind визначає, де саме слухає Gateway: - `gateway.bind: "loopback"` (типово): підключатися можуть лише локальні клієнти. -- Bind поза loopback (`"lan"`, `"tailnet"`, `"custom"`) розширює поверхню атаки. Використовуйте їх лише з auth gateway (спільний token/password або правильно налаштований non-loopback trusted proxy) і реальним 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; не робіть широкого port-forward. +- Надавайте перевагу Tailscale Serve замість bind до LAN (Serve тримає Gateway на loopback, а Tailscale керує доступом). +- Якщо все ж потрібно bind до LAN, обмежте порт через firewall жорстким allowlist джерельних IP; не робіть широкий port-forward. - Ніколи не відкривайте Gateway без автентифікації на `0.0.0.0`. ### 0.4.1) Публікація портів Docker + UFW (`DOCKER-USER`) -Якщо ви запускаєте OpenClaw у Docker на VPS, пам’ятайте, що опубліковані порти контейнера -(`-p HOST:CONTAINER` або Compose `ports:`) маршрутизуються через ланцюги переспрямування Docker, -а не лише через правила `INPUT` хоста. +Якщо ви запускаєте OpenClaw через Docker на VPS, пам’ятайте, що опубліковані порти контейнера +(`-p HOST:CONTAINER` або `ports:` у Compose) маршрутизуються через ланцюги +переспрямування Docker, а не лише через правила `INPUT` хоста. Щоб трафік Docker відповідав політиці вашого firewall, застосовуйте правила в `DOCKER-USER` (цей ланцюг перевіряється до власних правил accept Docker). -На багатьох сучасних дистрибутивах `iptables`/`ip6tables` використовують frontend `iptables-nft` +У багатьох сучасних дистрибутивах `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 @@ -805,12 +801,12 @@ Gateway мультиплексує **WebSocket + HTTP** на одному пор COMMIT ``` -Для IPv6 існують окремі таблиці. Додайте відповідну політику в `/etc/ufw/after6.rules`, якщо -IPv6 у Docker увімкнено. +IPv6 має окремі таблиці. Додайте відповідну політику в `/etc/ufw/after6.rules`, якщо +Docker IPv6 увімкнено. -Уникайте жорстко заданих назв інтерфейсів, таких як `eth0`, у фрагментах документації. Назви інтерфейсів +Уникайте жорстко заданих назв інтерфейсів на кшталт `eth0` у фрагментах документації. Назви інтерфейсів відрізняються між образами VPS (`ens3`, `enp*` тощо), і невідповідність може випадково -призвести до пропуску вашого правила deny. +обійти ваше правило deny. Швидка перевірка після перезавантаження: @@ -821,22 +817,22 @@ ip6tables -S DOCKER-USER nmap -sT -p 1-65535 --open ``` -Очікувано зовні мають бути відкриті лише ті порти, які ви навмисно відкрили (для більшості -конфігурацій: SSH + порти вашого reverse proxy). +Очікувано зовні мають бути відкриті лише ті порти, які ви відкрили навмисно (у більшості +налаштувань: SSH + порти вашого reverse proxy). ### 0.4.2) Виявлення через mDNS/Bonjour (розкриття інформації) -Gateway транслює свою присутність через mDNS (`_openclaw-gw._tcp` на порту 5353) для локального виявлення пристроїв. У повному режимі це включає TXT-записи, які можуть розкривати операційні деталі: +Gateway транслює свою присутність через mDNS (`_openclaw-gw._tcp` на порту 5353) для виявлення локальними пристроями. У повному режимі це включає TXT-записи, які можуть розкривати робочі деталі: -- `cliPath`: повний шлях у файловій системі до CLI-бінарника (розкриває ім’я користувача та місце встановлення) -- `sshPort`: рекламує доступність SSH на хості -- `displayName`, `lanHost`: інформація про ім’я хоста +- `cliPath`: повний шлях файлової системи до бінарника CLI (розкриває ім’я користувача і місце встановлення) +- `sshPort`: повідомляє про доступність SSH на хості +- `displayName`, `lanHost`: інформація про hostname -**Міркування щодо операційної безпеки:** трансляція інфраструктурних деталей полегшує розвідку для будь-кого в локальній мережі. Навіть «нешкідлива» інформація, як-от шляхи файлової системи та наявність SSH, допомагає зловмисникам картографувати ваше середовище. +**Міркування операційної безпеки:** трансляція деталей інфраструктури спрощує розвідку для будь-кого в локальній мережі. Навіть «нешкідлива» інформація на кшталт шляхів у файловій системі та доступності SSH допомагає зловмисникам скласти карту вашого середовища. **Рекомендації:** -1. **Мінімальний режим** (типово, рекомендовано для відкритих gateway): вилучає чутливі поля з mDNS-трансляцій: +1. **Мінімальний режим** (типовий, рекомендований для відкритих gateway): не включає чутливі поля в трансляції mDNS: ```json5 { @@ -846,7 +842,7 @@ Gateway транслює свою присутність через mDNS (`_open } ``` -2. **Повністю вимкніть**, якщо локальне виявлення пристроїв вам не потрібне: +2. **Повністю вимкніть**, якщо вам не потрібне локальне виявлення пристроїв: ```json5 { @@ -856,7 +852,7 @@ Gateway транслює свою присутність через mDNS (`_open } ``` -3. **Повний режим** (за явним бажанням): включає `cliPath` + `sshPort` у TXT-записи: +3. **Повний режим** (за явною згодою): включає `cliPath` + `sshPort` у TXT-записи: ```json5 { @@ -866,19 +862,19 @@ Gateway транслює свою присутність через mDNS (`_open } ``` -4. **Змінна середовища** (альтернатива): установіть `OPENCLAW_DISABLE_BONJOUR=1`, щоб вимкнути mDNS без змін конфігурації. +4. **Змінна середовища** (альтернатива): встановіть `OPENCLAW_DISABLE_BONJOUR=1`, щоб вимкнути mDNS без змін конфігурації. -У мінімальному режимі Gateway все одно транслює достатньо даних для виявлення пристроїв (`role`, `gatewayPort`, `transport`), але не включає `cliPath` і `sshPort`. Програми, яким потрібна інформація про шлях до CLI, можуть отримати її через автентифіковане з’єднання WebSocket. +У мінімальному режимі Gateway усе ще транслює достатньо даних для виявлення пристрою (`role`, `gatewayPort`, `transport`), але не включає `cliPath` і `sshPort`. Застосунки, яким потрібна інформація про шлях CLI, можуть отримати її через автентифіковане WebSocket-підключення. ### 0.5) Захистіть WebSocket Gateway (локальна auth) -Auth Gateway **потрібна за замовчуванням**. Якщо не налаштовано -жодного коректного шляху auth gateway, Gateway відмовляє у WebSocket-з’єднаннях (fail‑closed). +Auth Gateway **обов’язкова за замовчуванням**. Якщо не налаштовано +жодного коректного шляху auth Gateway, Gateway відмовляється від WebSocket-підключень (безпечна відмова). -Onboarding типово генерує токен (навіть для loopback), тому -локальні клієнти повинні проходити автентифікацію. +Онбординг за замовчуванням генерує token (навіть для loopback), тому +локальні клієнти мають проходити автентифікацію. -Установіть токен, щоб **усі** WS-клієнти мусили автентифікуватися: +Установіть token, щоб **усі** WS-клієнти мусили автентифікуватися: ```json5 { @@ -888,136 +884,136 @@ Onboarding типово генерує токен (навіть для loopback) } ``` -Doctor може згенерувати його за вас: `openclaw doctor --generate-gateway-token`. +Doctor може згенерувати його для вас: `openclaw doctor --generate-gateway-token`. Примітка: `gateway.remote.token` / `.password` — це джерела облікових даних клієнта. -Самі по собі вони **не** захищають локальний доступ WS. -Локальні шляхи виклику можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` +Самі по собі вони **не** захищають локальний WS-доступ. +Локальні шляхи виклику можуть використовувати `gateway.remote.*` як fallback лише тоді, коли `gateway.auth.*` не задано. -Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і його не вдається розв’язати, розв’язання завершується fail closed (жоден резервний шлях remote не маскує проблему). -Необов’язково: закріпіть віддалений TLS через `gateway.remote.tlsFingerprint` під час використання `wss://`. -Нешифрований `ws://` типово дозволено лише для loopback. Для довірених шляхів у приватній мережі +Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef, але не розв’язано, +розв’язання завершується безпечною відмовою (жоден remote fallback цього не маскує). +Необов’язково: закріпіть віддалений TLS через `gateway.remote.tlsFingerprint`, якщо використовуєте `wss://`. +Нешифрований `ws://` за замовчуванням дозволено лише для loopback. Для довірених шляхів у приватній мережі встановіть `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` у процесі клієнта як аварійний варіант. -Локальний pairing пристроїв: +Локальне pairing пристроїв: - Pairing пристрою автоматично схвалюється для прямих локальних loopback-підключень, щоб - взаємодія клієнтів на тому самому хості була зручною. -- OpenClaw також має вузький шлях backend/container-local self-connect для - довірених потоків із допоміжними засобами зі спільним секретом. -- Підключення через tailnet і LAN, включно з bind через tailnet на тому ж хості, вважаються - віддаленими для pairing і все одно потребують схвалення. + зберегти зручність для клієнтів на тому самому хості. +- OpenClaw також має вузький шлях self-connect між backend/контейнером для + довірених потоків із загальним секретом. +- Підключення через tailnet і LAN, включно з bind до tailnet на тому самому хості, трактуються як + віддалені для pairing і все одно потребують схвалення. Режими auth: -- `gateway.auth.mode: "token"`: спільний bearer token (рекомендовано для більшості конфігурацій). -- `gateway.auth.mode: "password"`: автентифікація паролем (краще задавати через 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](/uk/gateway/trusted-proxy-auth)). Контрольний список ротації (token/password): 1. Згенеруйте/встановіть новий секрет (`gateway.auth.token` або `OPENCLAW_GATEWAY_PASSWORD`). -2. Перезапустіть Gateway (або перезапустіть застосунок macOS, якщо він керує Gateway). +2. Перезапустіть Gateway (або застосунок macOS, якщо він керує Gateway). 3. Оновіть усі віддалені клієнти (`gateway.remote.token` / `.password` на машинах, які звертаються до Gateway). -4. Переконайтеся, що зі старими обліковими даними підключитися більше не можна. +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 -і містять `x-forwarded-for`, `x-forwarded-proto` та `x-forwarded-host`, як -інжектує Tailscale. +`x-forwarded-for` через локальний демон Tailscale (`tailscale whois`) і звіряючи її із заголовком. Це спрацьовує лише для запитів, що приходять на loopback +і містять `x-forwarded-for`, `x-forwarded-proto` і `x-forwarded-host`, +які додає Tailscale. Для цього асинхронного шляху перевірки ідентичності невдалі спроби для того самого `{scope, ip}` -серіалізуються до того, як обмежувач зафіксує збій. Тому конкурентні невдалі повтори -від одного клієнта Serve можуть заблокувати другу спробу негайно, замість того щоб -проскочити як дві звичайні невідповідності. -Кінцеві точки HTTP API (наприклад `/v1/*`, `/tools/invoke` і `/api/channels/*`) -**не** використовують автентифікацію заголовками ідентичності Tailscale. Вони, як і раніше, дотримуються -налаштованого в gateway режиму HTTP auth. +серіалізуються до того, як limiter зафіксує невдачу. Тому конкурентні хибні повтори +від одного клієнта Serve можуть одразу заблокувати другу спробу +замість того, щоб «проскочити» як дві звичайні невідповідності. +HTTP API endpoint (`/v1/*`, `/tools/invoke` і `/api/channels/*` наприклад) +**не** використовують auth через заголовки ідентичності Tailscale. Вони й надалі дотримуються +налаштованого режиму HTTP auth gateway. -Важлива примітка щодо меж: +Важлива примітка про периметр: -- Bearer auth HTTP Gateway фактично дає повний операторський доступ без тонкого поділу. -- Ставтеся до облікових даних, які можуть викликати `/v1/chat/completions`, `/v1/responses` або `/api/channels/*`, як до повноцінних операторських секретів доступу до цього gateway. -- На сумісній з OpenAI HTTP-поверхні bearer auth зі спільним секретом відновлює повний типовий набір операторських scope (`operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`) і семантику власника для ходів агента; вужчі значення `x-openclaw-scopes` не звужують цей шлях зі спільним секретом. -- Семантика scope на HTTP на рівні окремого запиту застосовується лише тоді, коли запит надходить із режиму, що несе ідентичність, як-от auth через trusted proxy або `gateway.auth.mode="none"` на приватному вході. -- У таких режимах, що несуть ідентичність, якщо не вказано `x-openclaw-scopes`, використовується звичайний типовий набір операторських scope; надсилайте заголовок явно, коли хочете вужчий набір scope. -- `/tools/invoke` дотримується того самого правила спільного секрету: bearer auth через token/password там також розглядається як повний операторський доступ, тоді як режими, що несуть ідентичність, як і раніше, поважають задекларовані scope. -- Не передавайте ці облікові дані недовіреним викликачам; краще використовуйте окремі 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`) і семантику власника для ходів агента; вужчі значення `x-openclaw-scopes` не зменшують цей шлях зі спільним секретом. +- Семантика прав на рівні запиту для HTTP застосовується лише тоді, коли запит походить із режиму з ідентичністю, такого як auth trusted proxy або `gateway.auth.mode="none"` на приватному ingress. +- У цих режимах з ідентичністю, якщо не вказати `x-openclaw-scopes`, використовується типовий набір операторських прав; надсилайте цей заголовок явно, якщо хочете вужчий набір прав. +- `/tools/invoke` дотримується того самого правила спільного секрету: bearer auth через token/password там також сприймається як повний операторський доступ, тоді як режими з ідентичністю все ще враховують оголошені права. +- Не діліться цими обліковими даними з недовіреними викликачами; віддавайте перевагу окремим gateway для кожного периметра довіри. -**Припущення довіри:** auth Serve без токена виходить із того, що хост gateway є довіреним. -Не розглядайте це як захист від ворожих процесів на тому самому хості. Якщо на хості gateway +**Припущення довіри:** auth Serve без token виходить із того, що хост gateway є довіреним. +Не сприймайте це як захист від ворожих процесів на тому самому хості. Якщо на хості gateway може виконуватися недовірений локальний код, вимкніть `gateway.auth.allowTailscale` -і вимагайте явної auth через спільний секрет із `gateway.auth.mode: "token"` або +і вимагайте явну auth через спільний секрет із `gateway.auth.mode: "token"` або `"password"`. **Правило безпеки:** не пересилайте ці заголовки зі свого reverse proxy. Якщо -ви завершуєте TLS або проксіюєте запити перед gateway, вимкніть -`gateway.auth.allowTailscale` і використовуйте auth через спільний секрет (`gateway.auth.mode: -"token"` або `"password"`) або [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth) +ви завершуєте TLS або проксіюєте перед gateway, вимкніть +`gateway.auth.allowTailscale` і використовуйте auth зі спільним секретом (`gateway.auth.mode: +"token"` або `"password"`) або [Автентифікація Trusted Proxy](/uk/gateway/trusted-proxy-auth) замість цього. -Довірені proxy: +Trusted 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). -### 0.6.1) Керування браузером через host Node (рекомендовано) +### 0.6.1) Керування браузером через host=node (рекомендовано) -Якщо ваш Gateway віддалений, але браузер працює на іншій машині, запустіть **host Node** -на машині з браузером і дозвольте Gateway проксувати дії браузера (див. [Інструмент browser](/uk/tools/browser)). -Ставтеся до pairing Node як до адміністративного доступу. +Якщо ваш Gateway віддалений, але браузер працює на іншій машині, запустіть **host node** +на машині з браузером і дозвольте Gateway проксіювати дії браузера (див. [Інструмент browser](/uk/tools/browser)). +Сприймайте pairing Node як адміністративний доступ. Рекомендований шаблон: -- Тримайте Gateway і host Node в одній tailnet (Tailscale). -- Навмисно виконайте pairing Node; вимикайте proxy-маршрутизацію браузера, якщо вона вам не потрібна. +- Тримайте Gateway і host node в одній tailnet (Tailscale). +- Pairing Node виконуйте навмисно; вимикайте proxy-маршрутизацію браузера, якщо вона не потрібна. Уникайте: - Відкриття relay/control-портів у LAN або публічному інтернеті. -- Tailscale Funnel для кінцевих точок керування браузером (публічний доступ). +- Tailscale Funnel для endpoint керування браузером (публічна експозиція). ### 0.7) Секрети на диску (чутливі дані) Вважайте, що все в `~/.openclaw/` (або `$OPENCLAW_STATE_DIR/`) може містити секрети або приватні дані: -- `openclaw.json`: конфігурація може містити токени (gateway, віддалений gateway), налаштування постачальників і allowlist. -- `credentials/**`: облікові дані каналів (наприклад, облікові дані WhatsApp), allowlist pairing, імпорт застарілого OAuth. -- `agents//agent/auth-profiles.json`: API-ключі, профілі токенів, OAuth-токени, а також необов’язкові `keyRef`/`tokenRef`. -- `secrets.json` (необов’язково): файл із payload секретів, який використовується постачальниками SecretRef типу `file` (`secrets.providers`). -- `agents//agent/auth.json`: застарілий файл сумісності. Статичні записи `api_key` очищаються під час виявлення. -- `agents//sessions/**`: транскрипти сеансів (`*.jsonl`) + метадані маршрутизації (`sessions.json`), які можуть містити приватні повідомлення та результати інструментів. -- пакети bundled Plugin: установлені Plugin (разом із їхніми `node_modules/`). -- `sandboxes/**`: робочі простори sandbox інструментів; у них можуть накопичуватися копії файлів, які ви читали/записували всередині sandbox. +- `openclaw.json`: конфігурація може містити токени (gateway, remote gateway), налаштування провайдерів і allowlist. +- `credentials/**`: облікові дані каналів (наприклад creds WhatsApp), allowlist pairing, застарілі імпорти OAuth. +- `agents//agent/auth-profiles.json`: API-ключі, профілі токенів, OAuth-токени і необов’язкові `keyRef`/`tokenRef`. +- `secrets.json` (необов’язково): payload секретів на основі файлу, що використовується провайдерами SecretRef типу `file` (`secrets.providers`). +- `agents//agent/auth.json`: застарілий файл сумісності. Статичні записи `api_key` очищаються при виявленні. +- `agents//sessions/**`: транскрипти сесій (`*.jsonl`) + метадані маршрутизації (`sessions.json`), які можуть містити приватні повідомлення та вивід інструментів. +- пакети вбудованих plugin: установлені plugin (разом із їхніми `node_modules/`). +- `sandboxes/**`: робочі каталоги sandbox інструментів; там можуть накопичуватися копії файлів, які ви читали/записували всередині sandbox. Поради щодо посилення захисту: -- Тримайте дозволи суворими (`700` для каталогів, `600` для файлів). +- Тримайте права доступу жорсткими (`700` для каталогів, `600` для файлів). - Використовуйте повне шифрування диска на хості gateway. - Якщо хост спільний, надавайте перевагу окремому обліковому запису користувача ОС для Gateway. ### 0.8) Журнали + транскрипти (редагування + зберігання) -Журнали й транскрипти можуть призвести до витоку чутливої інформації навіть тоді, коли контроль доступу налаштовано правильно: +Журнали й транскрипти можуть розкривати чутливу інформацію, навіть якщо контроль доступу налаштовано правильно: - Журнали Gateway можуть містити зведення інструментів, помилки та URL. -- Транскрипти сеансів можуть містити вставлені секрети, вміст файлів, вихід команд і посилання. +- Транскрипти сесій можуть містити вставлені секрети, вміст файлів, вивід команд і посилання. Рекомендації: -- Тримайте редагування зведень інструментів увімкненим (`logging.redactSensitive: "tools"`; типове значення). -- Додавайте власні шаблони для свого середовища через `logging.redactPatterns` (токени, імена хостів, внутрішні URL). -- Коли ділитеся діагностикою, надавайте перевагу `openclaw status --all` (зручно вставляти, секрети відредаговані), а не сирим журналам. -- Видаляйте старі транскрипти сеансів і файли журналів, якщо вам не потрібне тривале зберігання. +- Тримайте ввімкненим редагування зведень інструментів (`logging.redactSensitive: "tools"`; типово). +- Додавайте власні шаблони для свого середовища через `logging.redactPatterns` (токени, hostnames, внутрішні URL). +- Коли ділитеся діагностикою, надавайте перевагу `openclaw status --all` (можна вставляти, секрети відредаговано) замість сирих журналів. +- Видаляйте старі транскрипти сесій і файли журналів, якщо вам не потрібне тривале зберігання. -Докладніше: [Logging](/uk/gateway/logging) +Докладніше: [Журналювання](/uk/gateway/logging) ### 1) DM: pairing за замовчуванням @@ -1053,27 +1049,27 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ро ### 3) Окремі номери (WhatsApp, Signal, Telegram) -Для каналів на основі телефонних номерів розгляньте запуск вашого 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` і нативні шляхи автозавантаження зображень у prompt лише каталогом workspace (корисно, якщо сьогодні ви дозволяєте абсолютні шляхи й хочете мати єдиний запобіжник). -- Тримайте корені файлової системи вузькими: уникайте широких коренів, як-от ваш домашній каталог, для workspace агента/workspace 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. Широкі корені можуть відкрити чутливі локальні файли (наприклад стан/конфігурацію в `~/.openclaw`) для файлових інструментів. -### 5) Безпечний базовий профіль (копіювати/вставити) +### 5) Безпечний базовий варіант (скопіювати/вставити) -Одна «безпечна типова» конфігурація, яка тримає Gateway приватним, вимагає pairing для DM і уникає завжди активних ботів у групах: +Один «безпечний варіант за замовчуванням», який тримає Gateway приватним, вимагає pairing у DM і уникає завжди активних ботів у групах: ```json5 { @@ -1092,9 +1088,9 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ро } ``` -Якщо ви хочете також «типово безпечніше» виконання інструментів, додайте sandbox + deny небезпечних інструментів для будь-якого агента, який не є власником (див. приклад нижче в розділі «Профілі доступу для кожного агента»). +Якщо ви хочете також «безпечніше за замовчуванням» виконання інструментів, додайте sandbox + заборону небезпечних інструментів для будь-якого агента, який не є власником (приклад нижче в розділі «Профілі доступу на рівні агента»). -Вбудований базовий профіль для chat-driven ходів агента: відправники, які не є власниками, не можуть використовувати інструменти `cron` або `gateway`. +Вбудований базовий захист для ходів агента, керованих чатом: відправники, які не є власником, не можуть використовувати інструменти `cron` або `gateway`. ## Sandboxing (рекомендовано) @@ -1102,59 +1098,59 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ро Два взаємодоповнювальні підходи: -- **Запускати весь Gateway у Docker** (межа контейнера): [Docker](/uk/install/docker) -- **Інструментальний sandbox** (`agents.defaults.sandbox`, host gateway + інструменти, ізольовані Docker): [Sandboxing](/uk/gateway/sandboxing) +- **Запуск усього Gateway у Docker** (периметр контейнера): [Docker](/uk/install/docker) +- **Sandbox інструментів** (`agents.defaults.sandbox`, host gateway + ізольовані через sandbox інструменти; Docker — типовий backend): [Sandboxing](/uk/gateway/sandboxing) -Примітка: щоб запобігти доступу між агентами, залишайте `agents.defaults.sandbox.scope` зі значенням `"agent"` (типово) -або використовуйте `"session"` для суворішої ізоляції на рівні сеансу. `scope: "shared"` використовує +Примітка: щоб запобігти доступу між агентами, залишайте `agents.defaults.sandbox.scope` на значенні `"agent"` (типово) +або `"session"` для суворішої ізоляції на рівні сесії. `scope: "shared"` використовує один спільний контейнер/workspace. -Також врахуйте доступ агента до workspace всередині sandbox: +Також враховуйте доступ до workspace агента всередині sandbox: -- `agents.defaults.sandbox.workspaceAccess: "none"` (типово) залишає workspace агента недоступним; інструменти працюють із workspace sandbox у `~/.openclaw/sandboxes` +- `agents.defaults.sandbox.workspaceAccess: "none"` (типово) не дає доступу до workspace агента; інструменти працюють із sandbox workspace в `~/.openclaw/sandboxes` - `agents.defaults.sandbox.workspaceAccess: "ro"` монтує workspace агента лише для читання в `/agent` (вимикає `write`/`edit`/`apply_patch`) - `agents.defaults.sandbox.workspaceAccess: "rw"` монтує workspace агента для читання/запису в `/workspace` -- Додаткові `sandbox.docker.binds` перевіряються за нормалізованими й канонізованими шляхами джерела. Хитрощі з symlink батьківських каталогів і канонічними псевдонімами home усе одно завершуються fail closed, якщо вони розв’язуються в заблоковані корені, такі як `/etc`, `/var/run` або каталоги облікових даних у home ОС. +- Додаткові `sandbox.docker.binds` перевіряються щодо нормалізованих і канонічних шляхів джерела. Трюки з symlink у батьківських каталогах і канонічними псевдонімами home усе одно завершуються безпечною відмовою, якщо вони резолвляться до заблокованих коренів, таких як `/etc`, `/var/run` або каталоги облікових даних у home ОС. -Важливо: `tools.elevated` — це глобальний аварійний обхід базового захисту, який запускає exec поза sandbox. Ефективний host типово має значення `gateway`, або `node`, якщо ціль exec налаштована на `node`. Тримайте `tools.elevated.allowFrom` вузьким і не вмикайте це для сторонніх. Ви також можете додатково обмежити elevated для конкретного агента через `agents.list[].tools.elevated`. Див. [Elevated Mode](/uk/tools/elevated). +Важливо: `tools.elevated` — це глобальний аварійний вихід із базового захисту, який запускає exec поза sandbox. Ефективний host за замовчуванням — `gateway`, або `node`, коли ціль exec налаштована як `node`. Тримайте `tools.elevated.allowFrom` жорстко обмеженим і не вмикайте його для сторонніх. Ви можете додатково обмежити elevated на рівні агента через `agents.list[].tools.elevated`. Див. [Режим Elevated](/uk/tools/elevated). ### Запобіжник делегування підлеглих агентів -Якщо ви дозволяєте інструменти сеансів, розглядайте делеговані запуски підлеглих агентів як ще одне рішення щодо меж: +Якщо ви дозволяєте інструменти сесій, сприймайте делеговані запуски підлеглих агентів як окреме рішення щодо периметра: - Забороняйте `sessions_spawn`, якщо агенту справді не потрібне делегування. -- Тримайте `agents.defaults.subagents.allowAgents` і будь-які перевизначення `agents.list[].subagents.allowAgents` для окремих агентів обмеженими відомими безпечними цільовими агентами. -- Для будь-якого робочого процесу, який має залишатися в sandbox, викликайте `sessions_spawn` із `sandbox: "require"` (типове значення — `inherit`). -- `sandbox: "require"` швидко завершується помилкою, якщо цільовий дочірній runtime не працює в sandbox. +- Тримайте `agents.defaults.subagents.allowAgents` і будь-які перевизначення `agents.list[].subagents.allowAgents` на рівні агента обмеженими відомими безпечними цільовими агентами. +- Для будь-якого workflow, який має лишатися в sandbox, викликайте `sessions_spawn` із `sandbox: "require"` (типове значення — `inherit`). +- `sandbox: "require"` швидко завершується помилкою, якщо середовище виконання дочірнього процесу не є sandboxed. ## Ризики керування браузером Увімкнення керування браузером дає моделі можливість керувати реальним браузером. -Якщо в цьому профілі браузера вже є активні сеанси входу, модель може -отримати доступ до цих акаунтів і даних. Розглядайте профілі браузера як **чутливий стан**: +Якщо цей профіль браузера вже містить активні сесії входу, модель може +отримати доступ до цих облікових записів і даних. Сприймайте профілі браузера як **чутливий стан**: - Надавайте перевагу окремому профілю для агента (типовий профіль `openclaw`). -- Уникайте спрямування агента на ваш особистий повсякденний профіль. -- Тримайте керування браузером на host вимкненим для агентів у sandbox, якщо ви їм не довіряєте. -- Автономний loopback API керування браузером приймає лише auth через спільний секрет +- Уникайте використання агентом вашого особистого щоденного профілю. +- Тримайте host browser control вимкненим для sandboxed агентів, якщо ви їм не довіряєте. +- Окремий loopback API керування браузером приймає лише auth через спільний секрет (bearer auth токеном gateway або паролем gateway). Він не використовує заголовки ідентичності trusted-proxy або Tailscale Serve. -- Ставтеся до завантажень браузера як до недовіреного вводу; надавайте перевагу ізольованому каталогу завантажень. +- Сприймайте завантаження браузера як недовірений ввід; надавайте перевагу ізольованому каталогу завантажень. - Якщо можливо, вимикайте синхронізацію браузера/менеджери паролів у профілі агента (це зменшує радіус ураження). -- Для віддалених gateway виходьте з того, що «керування браузером» еквівалентне «операторському доступу» до всього, чого може досягти цей профіль. -- Тримайте Gateway і host Node доступними лише через tailnet; уникайте відкриття портів керування браузером у LAN або публічному інтернеті. +- Для віддалених gateway припускайте, що «керування браузером» еквівалентне «операторському доступу» до всього, що доступне цьому профілю. +- Тримайте Gateway і host node доступними лише через tailnet; уникайте відкриття портів керування браузером у LAN або публічному інтернеті. - Вимикайте proxy-маршрутизацію браузера, коли вона не потрібна (`gateway.nodes.browser.mode="off"`). -- Режим існуючого сеансу Chrome MCP **не** є «безпечнішим»; він може діяти від вашого імені в межах усього, до чого має доступ цей профіль Chrome на host. +- Режим existing-session у Chrome MCP **не є** «безпечнішим»; він може діяти від вашого імені в межах усього, до чого має доступ цей профіль Chrome на хості. -### Політика SSRF браузера (сувора за замовчуванням) +### Політика Browser SSRF (сувора за замовчуванням) -Політика навігації браузера в OpenClaw сувора за замовчуванням: приватні/внутрішні адресати залишаються заблокованими, якщо ви явно не дозволите їх. +Політика навігації браузера в OpenClaw за замовчуванням є суворою: приватні/внутрішні цілі залишаються заблокованими, якщо ви явно не дозволите їх. -- Типово: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` не встановлено, тому навігація браузера блокує приватні/внутрішні/special-use адресати. -- Застарілий псевдонім: `browser.ssrfPolicy.allowPrivateNetwork` і далі приймається для сумісності. -- Режим за явною згодою: установіть `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`, щоб дозволити приватні/внутрішні/special-use адресати. -- У суворому режимі використовуйте `hostnameAllowlist` (шаблони на кшталт `*.example.com`) і `allowedHostnames` (точні винятки для host, включно із заблокованими іменами, як-от `localhost`) для явних винятків. -- Навігація перевіряється перед запитом і повторно перевіряється best-effort на фінальному URL `http(s)` після навігації, щоб зменшити ризик pivot через редиректи. +- Типово: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` не задано, тому навігація браузера блокує приватні/внутрішні/special-use цілі. +- Застарілий псевдонім: `browser.ssrfPolicy.allowPrivateNetwork` усе ще приймається для сумісності. +- Режим за явною згодою: установіть `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`, щоб дозволити приватні/внутрішні/special-use цілі. +- У суворому режимі використовуйте `hostnameAllowlist` (шаблони на кшталт `*.example.com`) і `allowedHostnames` (точні винятки для host, зокрема заблоковані назви на кшталт `localhost`) для явних винятків. +- Навігація перевіряється до запиту і best-effort повторно перевіряється на фінальному `http(s)` URL після навігації, щоб зменшити можливість pivot через redirect. Приклад суворої політики: @@ -1170,17 +1166,17 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ро } ``` -## Профілі доступу для кожного агента (багатоагентність) +## Профілі доступу на рівні агента (multi-agent) -За багатoагентної маршрутизації кожен агент може мати власний sandbox + політику інструментів: +За маршрутизації multi-agent кожен агент може мати власну політику sandbox + tools: використовуйте це, щоб надавати **повний доступ**, **лише читання** або **без доступу** для кожного агента. -Повні подробиці та правила пріоритету див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). +Повні подробиці та правила пріоритетів див. у [Sandbox і Tools для Multi-Agent](/uk/tools/multi-agent-sandbox-tools). -Типові сценарії: +Поширені сценарії: -- Особистий агент: повний доступ, без sandbox -- Сімейний/робочий агент: sandbox + інструменти лише для читання -- Публічний агент: sandbox + без доступу до файлової системи/оболонки +- Персональний агент: повний доступ, без sandbox +- Сімейний/робочий агент: sandboxed + інструменти лише для читання +- Публічний агент: sandboxed + без інструментів файлової системи/оболонки ### Приклад: повний доступ (без sandbox) @@ -1222,7 +1218,7 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ро } ``` -### Приклад: без доступу до файлової системи/оболонки (дозволено обмін повідомленнями через постачальника) +### Приклад: без доступу до файлової системи/оболонки (дозволено messaging провайдера) ```json5 { @@ -1236,9 +1232,9 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ро scope: "agent", workspaceAccess: "none", }, - // Інструменти сеансів можуть розкривати чутливі дані з транскриптів. Типово OpenClaw обмежує ці інструменти - // поточним сеансом + сеансами запущених підлеглих агентів, але за потреби можна обмежити їх ще сильніше. - // Див. `tools.sessions.visibility` у довіднику конфігурації. + // Інструменти сесій можуть розкривати чутливі дані з транскриптів. За замовчуванням OpenClaw обмежує ці інструменти + // поточною сесією + сесіями породжених підлеглих агентів, але за потреби ви можете обмежити ще сильніше. + // Див. `tools.sessions.visibility` у довіднику з конфігурації. tools: { sessions: { visibility: "tree" }, // self | tree | agent | all allow: [ @@ -1275,7 +1271,7 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ро ## Що сказати вашому AI -Додайте рекомендації з безпеки до системного prompt вашого агента: +Додайте настанови з безпеки до системного prompt вашого агента: ``` ## Security Rules @@ -1288,42 +1284,43 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ро ## Реагування на інциденти -Якщо ваш AI зробив щось погане: +Якщо ваш AI робить щось погане: -### Стримайте ситуацію +### Локалізуйте 1. **Зупиніть його:** зупиніть застосунок macOS (якщо він керує Gateway) або завершіть процес `openclaw gateway`. -2. **Закрийте доступ:** установіть `gateway.bind: "loopback"` (або вимкніть Tailscale Funnel/Serve), доки не зрозумієте, що сталося. -3. **Заморозьте доступ:** перемкніть ризиковані DM/групи на `dmPolicy: "disabled"` / вимогу згадувань і видаліть записи `"*"`, що дозволяють усіх, якщо вони були. +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 (облікові дані 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 (creds 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. Перегляньте нещодавні зміни конфігурації (усе, що могло розширити доступ: `gateway.bind`, `gateway.auth`, політики dm/group, `tools.elevated`, зміни Plugin). -4. Повторно запустіть `openclaw security audit --deep` і переконайтеся, що критичні висновки усунено. +3. Перегляньте нещодавні зміни конфігурації (усе, що могло розширити доступ: `gateway.bind`, `gateway.auth`, політики DM/груп, `tools.elevated`, зміни plugin). +4. Повторно запустіть `openclaw security audit --deep` і переконайтеся, що критичні findings усунуто. ### Зберіть для звіту -- Часову позначку, ОС хоста gateway + версію OpenClaw -- Транскрипти сеансів + короткий tail журналу (після редагування) -- Що надіслав атакувальник + що зробив агент -- Чи був 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`. +У CI pre-commit hook `detect-secrets` запускається в job `secrets`. Push у `main` завжди запускають сканування всіх файлів. Pull request використовують -швидкий шлях лише для змінених файлів, коли доступний базовий коміт, і повертаються -до повного сканування інакше. Якщо перевірка завершується невдачею, це означає, що є нові кандидати, яких ще немає в baseline. +швидкий шлях за зміненими файлами, коли доступний базовий коміт, і переходять +до повного сканування всіх файлів в іншому разі. Якщо перевірка не проходить, +це означає, що є нові кандидати, яких ще немає в baseline. -### Якщо CI падає +### Якщо CI не пройшов 1. Відтворіть локально: @@ -1333,26 +1330,26 @@ Push у `main` завжди запускають сканування всіх 2. Зрозумійте інструменти: - `detect-secrets` у pre-commit запускає `detect-secrets-hook` із baseline - та виключеннями репозиторію. + і excludes цього репозиторію. - `detect-secrets audit` відкриває інтерактивний перегляд, щоб позначити кожен елемент baseline - як справжній секрет або хибнопозитивне спрацювання. -3. Для справжніх секретів: змініть/видаліть їх, а потім повторно запустіть сканування, щоб оновити baseline. -4. Для хибнопозитивних спрацювань: запустіть інтерактивний audit і позначте їх як хибні: + як справжній секрет або хибнопозитивний результат. +3. Якщо це справжні секрети: ротуйте/видаліть їх, а потім повторно запустіть сканування, щоб оновити baseline. +4. Якщо це хибнопозитивні результати: запустіть інтерактивний аудит і позначте їх як хибні: ```bash detect-secrets audit .secrets.baseline ``` -5. Якщо вам потрібні нові виключення, додайте їх до `.detect-secrets.cfg` і заново згенеруйте - baseline з відповідними прапорами `--exclude-files` / `--exclude-lines` (файл config - наведено лише для довідки; detect-secrets не читає його автоматично). +5. Якщо вам потрібні нові excludes, додайте їх до `.detect-secrets.cfg` і повторно згенеруйте + baseline з відповідними прапорцями `--exclude-files` / `--exclude-lines` (файл + конфігурації є лише довідковим; detect-secrets не читає його автоматично). -Закомітьте оновлений `.secrets.baseline`, коли він відображатиме задуманий стан. +Закомітьте оновлений `.secrets.baseline`, щойно він відобразить бажаний стан. ## Повідомлення про проблеми безпеки Знайшли вразливість в OpenClaw? Будь ласка, повідомте відповідально: -1. Email: [security@openclaw.ai](mailto:security@openclaw.ai) -2. Не публікуйте публічно, доки проблему не буде виправлено +1. Електронна пошта: [security@openclaw.ai](mailto:security@openclaw.ai) +2. Не публікуйте інформацію публічно, доки проблему не буде виправлено 3. Ми вкажемо вас у подяках (якщо ви не віддаєте перевагу анонімності) diff --git a/docs/uk/help/faq.md b/docs/uk/help/faq.md index 19f59bb80..e865018c4 100644 --- a/docs/uk/help/faq.md +++ b/docs/uk/help/faq.md @@ -1,23 +1,23 @@ --- read_when: - - Відповіді на поширені запитання щодо налаштування, встановлення, онбордингу або підтримки під час виконання - - Сортування проблем, про які повідомляють користувачі, перед глибшим налагодженням + - Відповіді на поширені запитання щодо налаштування, встановлення, онбордингу або підтримки під час роботи + - Тріаж проблем, про які повідомляють користувачі, перед глибшим налагодженням summary: Поширені запитання про налаштування, конфігурацію та використання OpenClaw title: Поширені запитання x-i18n: - generated_at: "2026-04-20T12:31:52Z" + generated_at: "2026-04-20T18:29:30Z" model: gpt-5.4 provider: openai - source_hash: b9441a569bade4b862b115df0537183473b457470218e9b3e18539d503318f13 + source_hash: 8bde531507540bc91bc131c3e27d72a8be76cc53ef46a5e01aaeaf02a71cc8a2 source_path: help/faq.md workflow: 15 --- # Поширені запитання -Швидкі відповіді плюс глибше усунення несправностей для реальних сценаріїв налаштування (локальна розробка, VPS, multi-agent, OAuth/API ключі, резервне перемикання моделей). Для діагностики під час виконання дивіться [Усунення несправностей](/uk/gateway/troubleshooting). Для повного довідника з конфігурації дивіться [Конфігурація](/uk/gateway/configuration). +Швидкі відповіді плюс глибше усунення несправностей для реальних конфігурацій (локальна розробка, VPS, кілька агентів, OAuth/API-ключі, резервування моделей). Для діагностики під час роботи див. [Усунення несправностей](/uk/gateway/troubleshooting). Повний довідник з конфігурації див. у [Конфігурація](/uk/gateway/configuration). -## Перші 60 секунд, якщо щось зламано +## Перші 60 секунд, якщо щось зламалося 1. **Швидкий статус (перша перевірка)** @@ -25,15 +25,15 @@ x-i18n: openclaw status ``` - Швидке локальне зведення: ОС + оновлення, доступність gateway/сервісу, агенти/сесії, конфігурація провайдера + проблеми під час виконання (коли gateway доступний). + Швидкий локальний підсумок: ОС + оновлення, доступність gateway/сервісу, агенти/сесії, конфігурація провайдера + проблеми під час роботи (коли gateway доступний). -2. **Звіт, який можна вставити й поширити (безпечно ділитися)** +2. **Звіт, який можна вставити (безпечно ділитися)** ```bash openclaw status --all ``` - Діагностика лише для читання з хвостом журналу (токени замасковано). + Діагностика лише для читання з хвостом логів (токени замасковані). 3. **Стан демона + порту** @@ -41,79 +41,79 @@ x-i18n: openclaw gateway status ``` - Показує стан supervisor під час виконання порівняно з доступністю RPC, цільову URL-адресу probe і яку конфігурацію сервіс, імовірно, використовував. + Показує стан supervisor під час роботи проти доступності RPC, цільовий URL перевірки та яку конфігурацію сервіс імовірно використовував. -4. **Глибокі probe-перевірки** +4. **Глибокі перевірки** ```bash openclaw status --deep ``` - Виконує живу probe-перевірку стану gateway, включно з probe-перевірками каналів, коли це підтримується - (потрібен доступний gateway). Дивіться [Стан](/uk/gateway/health). + Виконує живу перевірку стану gateway, включно з перевірками каналів, коли це підтримується + (потрібен доступний gateway). Див. [Health](/uk/gateway/health). -5. **Переглянути останній журнал у реальному часі** +5. **Показати останній лог у реальному часі** ```bash openclaw logs --follow ``` - Якщо RPC недоступний, використайте запасний варіант: + Якщо RPC недоступний, використайте резервний варіант: ```bash tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" ``` - Файлові журнали відокремлені від журналів сервісу; дивіться [Журналювання](/uk/logging) і [Усунення несправностей](/uk/gateway/troubleshooting). + Файлові логи відокремлені від сервісних логів; див. [Логування](/uk/logging) і [Усунення несправностей](/uk/gateway/troubleshooting). -6. **Запустити doctor (виправлення)** +6. **Запустіть doctor (виправлення)** ```bash openclaw doctor ``` - Виправляє/мігрує конфігурацію/стан + виконує перевірки стану. Дивіться [Doctor](/uk/gateway/doctor). + Виправляє/мігрує конфігурацію/стан + виконує перевірки здоров’я. Див. [Doctor](/uk/gateway/doctor). 7. **Знімок стану gateway** ```bash openclaw health --json - openclaw health --verbose # показує цільову URL-адресу + шлях до конфігурації при помилках + openclaw health --verbose # shows the target URL + config path on errors ``` - Запитує в запущеного gateway повний знімок стану (лише WS). Дивіться [Стан](/uk/gateway/health). + Запитує у запущеного gateway повний знімок стану (лише WS). Див. [Health](/uk/gateway/health). -## Швидкий старт і початкове налаштування +## Швидкий старт і перше налаштування - - Використайте локального AI-агента, який може **бачити вашу машину**. Це набагато ефективніше, ніж питати - у Discord, тому що більшість випадків «я застряг» — це **локальні проблеми конфігурації або середовища**, + + Використовуйте локального AI-агента, який може **бачити вашу машину**. Це набагато ефективніше, ніж звертатися + у Discord, тому що більшість випадків «я застряг» — це **проблеми локальної конфігурації або середовища**, які віддалені помічники не можуть перевірити. - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/) - Ці інструменти можуть читати репозиторій, запускати команди, перевіряти журнали й допомагати виправляти - налаштування на рівні машини (PATH, сервіси, дозволи, файли автентифікації). Надайте їм **повну checkout-копію вихідного коду** через - hackable (git) install: + Ці інструменти можуть читати репозиторій, запускати команди, перевіряти логи та допомагати виправляти + налаштування на рівні машини (PATH, сервіси, дозволи, файли автентифікації). Надайте їм **повну копію вихідного коду** + через інсталяцію для редагування (git): ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Це встановлює OpenClaw **з checkout-копії git**, тож агент може читати код + документацію та - міркувати про точну версію, яку ви запускаєте. Ви завжди можете повернутися до стабільної версії пізніше, + Це встановлює OpenClaw **з git checkout**, тому агент може читати код + документацію та + аналізувати точну версію, яку ви використовуєте. Ви завжди можете повернутися до стабільної версії пізніше, повторно запустивши інсталятор без `--install-method git`. - Порада: попросіть агента **спланувати й супроводжувати** виправлення (крок за кроком), а потім виконати лише - потрібні команди. Так зміни залишаються невеликими й їх легше перевірити. + Порада: попросіть агента **спланувати та проконтролювати** виправлення (крок за кроком), а потім виконати лише + необхідні команди. Це робить зміни меншими й простішими для аудиту. - Якщо ви виявите реальну помилку або виправлення, будь ласка, створіть issue на GitHub або надішліть PR: + Якщо ви знайдете реальну помилку або виправлення, будь ласка, створіть issue на GitHub або надішліть PR: [https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues) [https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls) - Почніть із цих команд (діліться виводом, коли просите про допомогу): + Почніть із цих команд (поділіться виводом, коли просите про допомогу): ```bash openclaw status @@ -130,27 +130,27 @@ x-i18n: Інші корисні перевірки CLI: `openclaw status --all`, `openclaw logs --follow`, `openclaw gateway status`, `openclaw health --verbose`. - Швидкий цикл налагодження: [Перші 60 секунд, якщо щось зламано](#перші-60-секунд-якщо-щось-зламано). - Документація зі встановлення: [Встановлення](/uk/install), [Прапорці інсталятора](/uk/install/installer), [Оновлення](/uk/install/updating). + Швидкий цикл налагодження: [Перші 60 секунд, якщо щось зламалося](#перші-60-секунд-якщо-щось-зламалося). + Документація з інсталяції: [Інсталяція](/uk/install), [Прапорці інсталятора](/uk/install/installer), [Оновлення](/uk/install/updating). Поширені причини пропуску Heartbeat: - - `quiet-hours`: поза налаштованим вікном active-hours - - `empty-heartbeat-file`: `HEARTBEAT.md` існує, але містить лише порожній каркас або лише заголовки - - `no-tasks-due`: режим завдань `HEARTBEAT.md` активний, але для жодного з інтервалів завдань ще не настав час - - `alerts-disabled`: уся видимість heartbeat вимкнена (`showOk`, `showAlerts` і `useIndicator` усі вимкнені) + - `quiet-hours`: поза межами налаштованого вікна active-hours + - `empty-heartbeat-file`: `HEARTBEAT.md` існує, але містить лише порожню/заголовкову заготовку + - `no-tasks-due`: активний режим завдань `HEARTBEAT.md`, але жоден із інтервалів завдань ще не настав + - `alerts-disabled`: усю видимість heartbeat вимкнено (`showOk`, `showAlerts` і `useIndicator` усі вимкнені) - У режимі завдань часові позначки настання строку оновлюються лише після завершення + У режимі завдань часові позначки настання оновлюються лише після завершення реального запуску heartbeat. Пропущені запуски не позначають завдання як виконані. Документація: [Heartbeat](/uk/gateway/heartbeat), [Автоматизація та завдання](/uk/automation). - + Репозиторій рекомендує запуск із вихідного коду та використання онбордингу: ```bash @@ -160,7 +160,7 @@ x-i18n: Майстер також може автоматично зібрати UI-ресурси. Після онбордингу ви зазвичай запускаєте Gateway на порту **18789**. - Із вихідного коду (contributors/dev): + Із вихідного коду (контриб’ютори/розробники): ```bash git clone https://github.com/openclaw/openclaw.git @@ -176,84 +176,84 @@ x-i18n: - Майстер відкриває ваш браузер із чистою (без токена) URL-адресою dashboard одразу після онбордингу, а також друкує посилання у підсумку. Залиште цю вкладку відкритою; якщо вона не запустилася, скопіюйте й вставте надруковану URL-адресу на тій самій машині. + Майстер відкриває браузер із чистим (без токенів) URL dashboard одразу після онбордингу, а також виводить посилання в підсумку. Тримайте цю вкладку відкритою; якщо вона не запустилася, скопіюйте й вставте надрукований URL на тій самій машині. **Localhost (та сама машина):** - Відкрийте `http://127.0.0.1:18789/`. - - Якщо запитується автентифікація за shared secret, вставте налаштований токен або пароль у налаштуваннях Control UI. + - Якщо запитується автентифікація за спільним секретом, вставте налаштований токен або пароль у налаштуваннях Control UI. - Джерело токена: `gateway.auth.token` (або `OPENCLAW_GATEWAY_TOKEN`). - Джерело пароля: `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). - - Якщо shared secret ще не налаштовано, згенеруйте токен командою `openclaw doctor --generate-gateway-token`. + - Якщо спільний секрет ще не налаштовано, згенеруйте токен за допомогою `openclaw doctor --generate-gateway-token`. **Не на localhost:** - - **Tailscale Serve** (рекомендовано): залиште bind loopback, виконайте `openclaw gateway --tailscale serve`, відкрийте `https:///`. Якщо `gateway.auth.allowTailscale` має значення `true`, заголовки ідентичності задовольняють автентифікацію Control UI/WebSocket (без вставлення shared secret, за умови довіреного хоста gateway); HTTP API однаково вимагають автентифікацію за shared secret, якщо ви свідомо не використовуєте private-ingress `none` або HTTP-автентифікацію trusted-proxy. - Некоректні одночасні спроби автентифікації Serve від одного клієнта серіалізуються до того, як лімітатор невдалих автентифікацій зафіксує їх, тому вже під час другої невдалої повторної спроби може з’явитися `retry later`. - - **Tailnet bind**: виконайте `openclaw gateway --bind tailnet --token ""` (або налаштуйте автентифікацію паролем), відкрийте `http://:18789/`, а потім вставте відповідний shared secret у налаштуваннях dashboard. - - **Identity-aware reverse proxy**: залиште Gateway за trusted proxy не на loopback, налаштуйте `gateway.auth.mode: "trusted-proxy"`, а потім відкрийте URL-адресу proxy. - - **SSH-тунель**: `ssh -N -L 18789:127.0.0.1:18789 user@host`, а потім відкрийте `http://127.0.0.1:18789/`. Автентифікація за shared secret і далі застосовується через тунель; вставте налаштований токен або пароль, якщо з’явиться запит. + - **Tailscale Serve** (рекомендовано): залиште loopback bind, запустіть `openclaw gateway --tailscale serve`, відкрийте `https:///`. Якщо `gateway.auth.allowTailscale` має значення `true`, заголовки ідентичності задовольняють автентифікацію Control UI/WebSocket (без вставлення спільного секрету, за умови довіреного хоста gateway); API HTTP усе одно вимагають автентифікації за спільним секретом, якщо ви свідомо не використовуєте `none` для private-ingress або HTTP-автентифікацію trusted-proxy. + Некоректні одночасні спроби автентифікації Serve від того самого клієнта серіалізуються до того, як обмежувач невдалих спроб зафіксує їх, тому друга невдала спроба вже може показувати `retry later`. + - **Bind до tailnet**: запустіть `openclaw gateway --bind tailnet --token ""` (або налаштуйте автентифікацію за паролем), відкрийте `http://:18789/`, а потім вставте відповідний спільний секрет у налаштуваннях dashboard. + - **Reverse proxy з урахуванням ідентичності**: залиште Gateway за trusted proxy без loopback, налаштуйте `gateway.auth.mode: "trusted-proxy"`, а потім відкрийте URL proxy. + - **SSH-тунель**: `ssh -N -L 18789:127.0.0.1:18789 user@host`, а потім відкрийте `http://127.0.0.1:18789/`. Автентифікація за спільним секретом усе одно застосовується через тунель; вставте налаштований токен або пароль, якщо буде запит. - Дивіться [Dashboard](/web/dashboard) і [Веб-поверхні](/web) для подробиць про режими bind і автентифікацію. + Див. [Dashboard](/web/dashboard) і [Веб-поверхні](/web), щоб дізнатися про режими bind і деталі автентифікації. - + Вони керують різними рівнями: - - `approvals.exec`: пересилає запити на погодження до чат-призначень - - `channels..execApprovals`: робить цей канал нативним клієнтом погоджень для погоджень exec + - `approvals.exec`: пересилає запити на підтвердження до призначень чату + - `channels..execApprovals`: робить цей канал нативним клієнтом підтвердження для exec approvals - Політика exec на хості все одно є реальним бар’єром погодження. Конфігурація чату лише визначає, де саме - з’являються запити на погодження і як люди можуть на них відповідати. + Політика host exec усе ще є реальним бар’єром підтвердження. Конфігурація чату лише керує тим, + де з’являються запити на підтвердження і як люди можуть на них відповідати. - У більшості сценаріїв вам **не** потрібні обидві: + У більшості конфігурацій вам **не** потрібні обидві: - Якщо чат уже підтримує команди й відповіді, `/approve` у тому самому чаті працює через спільний шлях. - - Якщо підтримуваний нативний канал може безпечно визначити тих, хто погоджує, OpenClaw тепер автоматично вмикає нативні погодження DM-first, коли `channels..execApprovals.enabled` не задано або має значення `"auto"`. - - Коли доступні нативні картки/кнопки погодження, цей нативний UI є основним шляхом; агент має включати ручну команду `/approve` лише якщо результат інструмента каже, що погодження в чаті недоступні або єдиний шлях — ручне погодження. - - Використовуйте `approvals.exec` лише коли запити також потрібно пересилати до інших чатів або окремих ops-кімнат. - - Використовуйте `channels..execApprovals.target: "channel"` або `"both"` лише якщо ви явно хочете, щоб запити на погодження публікувалися назад у вихідну кімнату/тему. - - Погодження Plugin — це ще окрема категорія: вони типово використовують `/approve` у тому самому чаті, необов’язкове пересилання `approvals.plugin`, і лише деякі нативні канали додатково зберігають нативну обробку погоджень Plugin. + - Якщо підтримуваний нативний канал може безпечно визначити апруверів, OpenClaw тепер автоматично вмикає нативні підтвердження спочатку через DM, коли `channels..execApprovals.enabled` не задано або дорівнює `"auto"`. + - Коли доступні нативні картки/кнопки підтвердження, цей нативний UI є основним шляхом; агент має включати ручну команду `/approve` лише якщо результат інструмента каже, що chat approvals недоступні або ручне підтвердження — єдиний шлях. + - Використовуйте `approvals.exec` лише тоді, коли запити також потрібно пересилати в інші чати або в окремі кімнати для ops. + - Використовуйте `channels..execApprovals.target: "channel"` або `"both"` лише якщо ви явно хочете, щоб запити на підтвердження публікувалися назад у початкову кімнату/тему. + - Підтвердження Plugin — це ще окрема категорія: вони типово використовують `/approve` у тому самому чаті, необов’язкове пересилання `approvals.plugin`, і лише деякі нативні канали додатково зберігають нативну обробку plugin-підтверджень. - Коротко: пересилання — для маршрутизації, конфігурація нативного клієнта — для багатшого UX, специфічного для каналу. - Дивіться [Погодження Exec](/uk/tools/exec-approvals). + Коротко: пересилання — це маршрутизація, конфігурація нативного клієнта — це багатший UX, специфічний для каналу. + Див. [Exec Approvals](/uk/tools/exec-approvals). - Потрібен Node **>= 22**. Рекомендовано `pnpm`. Bun **не рекомендований** для Gateway. + Потрібен Node **>= 22**. Рекомендується `pnpm`. Bun **не рекомендується** для Gateway. - Так. Gateway легкий — у документації вказано, що для особистого використання достатньо **512 МБ–1 ГБ RAM**, **1 ядра** та приблизно **500 МБ** - дискового простору, а також зазначено, що **Raspberry Pi 4 може це запускати**. + Так. Gateway легкий — у документації вказано, що для особистого використання достатньо **512 МБ–1 ГБ RAM**, **1 ядра** і приблизно **500 МБ** + диска, а також зазначено, що **Raspberry Pi 4 може його запускати**. - Якщо вам потрібен додатковий запас (журнали, медіа, інші сервіси), **рекомендовано 2 ГБ**, але це + Якщо вам потрібен додатковий запас (логи, медіа, інші сервіси), **рекомендується 2 ГБ**, але це не жорсткий мінімум. - Порада: невеликий Pi/VPS може хостити Gateway, а ви можете підключати **nodes** на ноутбуці/телефоні для - локального екрана/камери/canvas або виконання команд. Дивіться [Nodes](/uk/nodes). + Порада: невеликий Pi/VPS може хостити Gateway, а ви можете під’єднати **nodes** на ноутбуці/телефоні для + локального екрана/камери/canvas або виконання команд. Див. [Nodes](/uk/nodes). - - Коротко: це працює, але очікуйте певних незручностей. + + Коротко: це працює, але очікуйте шорстких країв. - Використовуйте **64-бітну** ОС і Node >= 22. - - Надавайте перевагу **hackable (git) install**, щоб бачити журнали й швидко оновлюватися. - - Почніть без каналів/Skills, а потім додавайте їх по одному. - - Якщо натрапите на дивні проблеми з бінарними файлами, зазвичай це проблема **сумісності ARM**. + - Надавайте перевагу **інсталяції для редагування (git)**, щоб можна було бачити логи й швидко оновлюватися. + - Починайте без каналів/Skills, а потім додавайте їх по одному. + - Якщо стикаєтеся з дивними проблемами з бінарниками, це зазвичай проблема **сумісності ARM**. - Документація: [Linux](/uk/platforms/linux), [Встановлення](/uk/install). + Документація: [Linux](/uk/platforms/linux), [Інсталяція](/uk/install). - - Цей екран залежить від того, чи доступний і автентифікований Gateway. TUI також надсилає - "Wake up, my friend!" автоматично під час першого hatch. Якщо ви бачите цей рядок **без відповіді** + + Цей екран залежить від того, чи gateway доступний і автентифікований. TUI також надсилає + «Wake up, my friend!» автоматично під час першого hatch. Якщо ви бачите цей рядок **без відповіді** і токени залишаються на 0, агент так і не запустився. 1. Перезапустіть Gateway: @@ -270,35 +270,35 @@ x-i18n: openclaw logs --follow ``` - 3. Якщо все одно зависає, виконайте: + 3. Якщо все ще зависає, виконайте: ```bash openclaw doctor ``` - Якщо Gateway віддалений, переконайтеся, що тунель/з’єднання Tailscale активне і що UI - вказує на правильний Gateway. Дивіться [Віддалений доступ](/uk/gateway/remote). + Якщо Gateway віддалений, переконайтеся, що тунель/Tailscale-з’єднання активне і що UI + вказує на правильний Gateway. Див. [Віддалений доступ](/uk/gateway/remote). Так. Скопіюйте **каталог стану** і **workspace**, а потім один раз запустіть Doctor. Це - збереже вашого бота «точно таким самим» (пам’ять, історія сесій, автентифікація та - стан каналу), якщо ви скопіюєте **обидва** розташування: + збереже вашого бота «точно таким самим» (пам’ять, історію сесій, автентифікацію та стан + каналів), якщо ви скопіюєте **обидва** місця: 1. Встановіть OpenClaw на новій машині. 2. Скопіюйте `$OPENCLAW_STATE_DIR` (типово: `~/.openclaw`) зі старої машини. - 3. Скопіюйте свій workspace (типово: `~/.openclaw/workspace`). - 4. Виконайте `openclaw doctor` і перезапустіть сервіс Gateway. + 3. Скопіюйте ваш workspace (типово: `~/.openclaw/workspace`). + 4. Запустіть `openclaw doctor` і перезапустіть сервіс Gateway. Це зберігає конфігурацію, профілі автентифікації, облікові дані WhatsApp, сесії та пам’ять. Якщо ви працюєте - у віддаленому режимі, пам’ятайте, що хост gateway володіє сховищем сесій і workspace. + у віддаленому режимі, пам’ятайте, що session store і workspace належать хосту gateway. - **Важливо:** якщо ви лише commit/push свій workspace у GitHub, ви створюєте резервну копію - **пам’яті + bootstrap-файлів**, але **не** історії сесій або автентифікації. Вони зберігаються + **Важливо:** якщо ви лише комітите/пушите свій workspace на GitHub, ви робите резервну + копію **пам’яті + bootstrap-файлів**, але **не** історії сесій чи автентифікації. Вони зберігаються у `~/.openclaw/` (наприклад, `~/.openclaw/agents//sessions/`). - Пов’язане: [Міграція](/uk/install/migrating), [Де все зберігається на диску](#where-things-live-on-disk), + Пов’язано: [Міграція](/uk/install/migrating), [Де що зберігається на диску](#where-things-live-on-disk), [Workspace агента](/uk/concepts/agent-workspace), [Doctor](/uk/gateway/doctor), [Віддалений режим](/uk/gateway/remote). @@ -308,14 +308,14 @@ x-i18n: Перевірте changelog на GitHub: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Найновіші записи розташовані вгорі. Якщо верхній розділ позначено як **Unreleased**, то наступний датований - розділ — це остання випущена версія. Записи згруповані за категоріями **Highlights**, **Changes** і - **Fixes** (а також docs/інші розділи за потреби). + Найновіші записи розташовані вгорі. Якщо верхній розділ позначено як **Unreleased**, наступний датований + розділ — це остання випущена версія. Записи згруповані за **Highlights**, **Changes** і + **Fixes** (а також за розділами docs/other, коли це потрібно). - - Деякі підключення Comcast/Xfinity помилково блокують `docs.openclaw.ai` через Xfinity + + Деякі з’єднання Comcast/Xfinity помилково блокують `docs.openclaw.ai` через Xfinity Advanced Security. Вимкніть її або додайте `docs.openclaw.ai` до allowlist, а потім повторіть спробу. Будь ласка, допоможіть нам розблокувати сайт, повідомивши тут: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). @@ -330,21 +330,21 @@ x-i18n: - `latest` = stable - `beta` = рання збірка для тестування - Зазвичай стабільний реліз спочатку потрапляє в **beta**, а потім явний - крок підвищення переміщує цю саму версію в `latest`. За потреби maintainers також можуть - публікувати одразу в `latest`. Саме тому beta і stable можуть - вказувати на **ту саму версію** після підвищення. + Зазвичай stable-реліз спочатку потрапляє в **beta**, а потім явний + крок просування переміщує цю саму версію в `latest`. За потреби мейнтейнери також можуть + публікувати одразу в `latest`. Саме тому після просування beta і stable можуть + вказувати на **одну й ту саму версію**. Подивитися, що змінилося: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Для однорядкових команд встановлення і різниці між beta та dev дивіться accordion нижче. + Однорядкові команди встановлення та різницю між beta і dev див. в accordion нижче. - - **Beta** — це npm dist-tag `beta` (може збігатися з `latest` після підвищення). - **Dev** — це рухома голова `main` (git); коли її публікують, використовується npm dist-tag `dev`. + + **Beta** — це npm dist-tag `beta` (може збігатися з `latest` після просування). + **Dev** — це рухома вершина `main` (git); під час публікації вона використовує npm dist-tag `dev`. Однорядкові команди (macOS/Linux): @@ -359,14 +359,14 @@ x-i18n: Інсталятор для Windows (PowerShell): [https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1) - Більше деталей: [Канали розробки](/uk/install/development-channels) і [Прапорці інсталятора](/uk/install/installer). + Докладніше: [Канали розробки](/uk/install/development-channels) і [Прапорці інсталятора](/uk/install/installer). - + Є два варіанти: - 1. **Канал dev (git checkout):** + 1. **Dev channel (git checkout):** ```bash openclaw update --channel dev @@ -374,15 +374,15 @@ x-i18n: Це перемикає вас на гілку `main` і оновлює з вихідного коду. - 2. **Hackable install (із сайту інсталятора):** + 2. **Інсталяція для редагування (із сайту інсталятора):** ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Це дає вам локальний репозиторій, який ви можете редагувати, а потім оновлювати через git. + Це дає вам локальний репозиторій, який можна редагувати, а потім оновлювати через git. - Якщо ви віддаєте перевагу чистому clone вручну, використайте: + Якщо ви віддаєте перевагу чистому ручному clone, використовуйте: ```bash git clone https://github.com/openclaw/openclaw.git @@ -392,23 +392,23 @@ x-i18n: ``` Документація: [Оновлення](/cli/update), [Канали розробки](/uk/install/development-channels), - [Встановлення](/uk/install). + [Інсталяція](/uk/install). - - Приблизний орієнтир: + + Орієнтовно: - **Встановлення:** 2–5 хвилин - **Онбординг:** 5–15 хвилин залежно від того, скільки каналів/моделей ви налаштовуєте - Якщо все зависає, використайте [Інсталятор завис?](#quick-start-and-first-run-setup) - і швидкий цикл налагодження в [Я застряг](#quick-start-and-first-run-setup). + Якщо все зависає, скористайтеся [Інсталятор завис?](#quick-start-and-first-run-setup) + і швидким циклом налагодження в [Я застряг](#quick-start-and-first-run-setup). - Повторно запустіть інсталятор із **докладним виводом**: + Повторно запустіть інсталятор з **докладним виводом**: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose @@ -420,7 +420,7 @@ x-i18n: curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose ``` - Для hackable (git) install: + Для інсталяції для редагування (git): ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose @@ -429,7 +429,7 @@ x-i18n: Еквівалент для Windows (PowerShell): ```powershell - # install.ps1 поки що не має окремого прапорця -Verbose. + # install.ps1 has no dedicated -Verbose flag yet. Set-PSDebug -Trace 1 & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard Set-PSDebug -Trace 0 @@ -439,38 +439,38 @@ x-i18n: - + Дві поширені проблеми у Windows: - **1) Помилка npm spawn git / git not found** + **1) помилка npm spawn git / git not found** - Установіть **Git for Windows** і переконайтеся, що `git` є у вашому PATH. - Закрийте й знову відкрийте PowerShell, потім повторно запустіть інсталятор. - **2) Після встановлення `openclaw` не розпізнається** + **2) після встановлення openclaw is not recognized** - - Ваша глобальна папка bin npm відсутня в PATH. + - Ваша глобальна папка bin npm не додана в PATH. - Перевірте шлях: ```powershell npm config get prefix ``` - - Додайте цей каталог до вашого PATH користувача (суфікс `\bin` у Windows не потрібен; у більшості систем це `%AppData%\npm`). - - Закрийте й знову відкрийте PowerShell після оновлення PATH. + - Додайте цей каталог до свого користувацького PATH (суфікс `\bin` у Windows не потрібен; у більшості систем це `%AppData%\npm`). + - Після оновлення PATH закрийте й знову відкрийте PowerShell. - Якщо вам потрібне максимально безпроблемне налаштування у Windows, використовуйте **WSL2** замість нативного Windows. + Якщо ви хочете найгладше налаштування у Windows, використовуйте **WSL2** замість нативного Windows. Документація: [Windows](/uk/platforms/windows). - + Зазвичай це невідповідність кодової сторінки консолі в нативних оболонках Windows. Симптоми: - - вивід `system.run`/`exec` показує китайський текст як mojibake - - та сама команда виглядає нормально в іншому профілі термінала + - Вивід `system.run`/`exec` відображає китайський текст як mojibake + - Та сама команда нормально виглядає в іншому профілі термінала Швидкий обхідний шлях у PowerShell: @@ -487,21 +487,21 @@ x-i18n: openclaw gateway restart ``` - Якщо ви все ще відтворюєте це в останній версії OpenClaw, відстежуйте/повідомляйте тут: + Якщо це все ще відтворюється в останній версії OpenClaw, відстежуйте/повідомляйте тут: - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640) - Використайте **hackable (git) install**, щоб мати повний вихідний код і документацію локально, а потім запитайте - свого бота (або Claude/Codex) _з цієї папки_, щоб він міг прочитати репозиторій і відповісти точно. + Використовуйте **інсталяцію для редагування (git)**, щоб повний вихідний код і документація були локально, а потім запитайте + свого бота (або Claude/Codex) _з цієї папки_, щоб він міг читати репозиторій і дати точну відповідь. ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Більше деталей: [Встановлення](/uk/install) і [Прапорці інсталятора](/uk/install/installer). + Докладніше: [Інсталяція](/uk/install) і [Прапорці інсталятора](/uk/install/installer). @@ -510,32 +510,32 @@ x-i18n: - Швидкий шлях для Linux + встановлення сервісу: [Linux](/uk/platforms/linux). - Повний покроковий посібник: [Початок роботи](/uk/start/getting-started). - - Інсталятор + оновлення: [Встановлення та оновлення](/uk/install/updating). + - Інсталятор + оновлення: [Встановлення й оновлення](/uk/install/updating). - Підійде будь-який Linux VPS. Установіть на сервері, а потім використовуйте SSH/Tailscale для доступу до Gateway. + Підійде будь-який VPS на Linux. Установіть на сервері, а потім використовуйте SSH/Tailscale для доступу до Gateway. Інструкції: [exe.dev](/uk/install/exe-dev), [Hetzner](/uk/install/hetzner), [Fly.io](/uk/install/fly). Віддалений доступ: [Віддалений Gateway](/uk/gateway/remote). - - У нас є **хаб хостингу** з поширеними провайдерами. Виберіть одного й дотримуйтесь інструкції: + + Ми підтримуємо **хаб хостингу** з поширеними провайдерами. Виберіть одного та дотримуйтеся інструкції: - [VPS-хостинг](/uk/vps) (усі провайдери в одному місці) - [Fly.io](/uk/install/fly) - [Hetzner](/uk/install/hetzner) - [exe.dev](/uk/install/exe-dev) - Як це працює у хмарі: **Gateway запускається на сервері**, а ви отримуєте до нього доступ - зі свого ноутбука/телефона через Control UI (або Tailscale/SSH). Ваш стан + workspace - зберігаються на сервері, тож вважайте хост джерелом істини й робіть його резервні копії. + Як це працює в хмарі: **Gateway працює на сервері**, а ви отримуєте до нього доступ + з ноутбука/телефона через Control UI (або Tailscale/SSH). Ваші стан + workspace + зберігаються на сервері, тому ставтеся до хоста як до джерела істини та робіть його резервні копії. - Ви можете підключати **nodes** (Mac/iOS/Android/headless) до цього хмарного Gateway, щоб мати доступ - до локального екрана/камери/canvas або запускати команди на ноутбуці, залишаючи + Ви можете під’єднати **nodes** (Mac/iOS/Android/headless) до цього хмарного Gateway, щоб отримувати доступ + до локального екрана/камери/canvas або виконувати команди на своєму ноутбуці, залишаючи Gateway у хмарі. Хаб: [Платформи](/uk/platforms). Віддалений доступ: [Віддалений Gateway](/uk/gateway/remote). @@ -544,9 +544,9 @@ x-i18n: - Коротка відповідь: **можливо, але не рекомендовано**. Процес оновлення може перезапустити - Gateway (що перерве активну сесію), може вимагати чистого git checkout і - може запитувати підтвердження. Безпечніше запускати оновлення з оболонки як оператор. + Коротка відповідь: **можливо, але не рекомендується**. Процес оновлення може перезапустити + Gateway (що розірве активну сесію), може потребувати чистого git checkout і + може запитати підтвердження. Безпечніше запускати оновлення з оболонки як оператор. Використовуйте CLI: @@ -558,7 +558,7 @@ x-i18n: openclaw update --no-restart ``` - Якщо вам усе ж потрібно автоматизувати це з агента: + Якщо вам обов’язково потрібно автоматизувати це від імені агента: ```bash openclaw update --yes --no-restart @@ -572,66 +572,66 @@ x-i18n: `openclaw onboard` — це рекомендований шлях налаштування. У **локальному режимі** він проводить вас через: - - **Налаштування моделей/автентифікації** (OAuth провайдера, API ключі, Anthropic setup-token, а також варіанти локальних моделей, наприклад LM Studio) - - розташування **workspace** + bootstrap-файли + - **Налаштування моделі/автентифікації** (OAuth провайдера, API-ключі, setup-token Anthropic, а також локальні варіанти моделей, як-от LM Studio) + - Розташування **workspace** + bootstrap-файли - **Налаштування Gateway** (bind/port/auth/tailscale) - - **Канали** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, а також bundled channel plugins, такі як QQ Bot) - - **Встановлення демона** (LaunchAgent у macOS; systemd user unit у Linux/WSL2) - - **Перевірки стану** і вибір **Skills** + - **Канали** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, а також вбудовані channel plugin, як-от QQ Bot) + - **Установлення демона** (LaunchAgent у macOS; systemd user unit у Linux/WSL2) + - **Перевірки здоров’я** і вибір **Skills** - Він також попереджає, якщо налаштована модель невідома або для неї відсутня автентифікація. + Він також попереджає, якщо ваша налаштована модель невідома або для неї бракує автентифікації. - - Ні. Ви можете запускати OpenClaw з **API ключами** (Anthropic/OpenAI/інші) або з + + Ні. Ви можете запускати OpenClaw з **API-ключами** (Anthropic/OpenAI/інші) або з **лише локальними моделями**, щоб ваші дані залишалися на вашому пристрої. Підписки (Claude Pro/Max або OpenAI Codex) — це необов’язкові способи автентифікації в цих провайдерів. Для Anthropic в OpenClaw практичний поділ такий: - - **API ключ Anthropic**: звичайне білінгування Anthropic API + - **API-ключ Anthropic**: звичайна тарифікація API Anthropic - **Claude CLI / автентифікація через підписку Claude в OpenClaw**: співробітники Anthropic повідомили нам, що таке використання знову дозволене, і OpenClaw розглядає використання `claude -p` як санкціоноване для цієї інтеграції, якщо Anthropic не опублікує нову політику - Для довгоживучих хостів gateway API ключі Anthropic усе ще є більш - передбачуваним варіантом налаштування. OpenAI Codex OAuth явно підтримується для зовнішніх - інструментів, таких як OpenClaw. + Для довготривалих хостів gateway API-ключі Anthropic усе ще є більш + передбачуваним налаштуванням. OAuth OpenAI Codex явно підтримується для зовнішніх + інструментів на кшталт OpenClaw. - OpenClaw також підтримує інші хостовані варіанти у стилі підписки, зокрема + OpenClaw також підтримує інші розміщені варіанти у стилі підписки, зокрема **Qwen Cloud Coding Plan**, **MiniMax Coding Plan** і **Z.AI / GLM Coding Plan**. Документація: [Anthropic](/uk/providers/anthropic), [OpenAI](/uk/providers/openai), [Qwen Cloud](/uk/providers/qwen), - [MiniMax](/uk/providers/minimax), [Моделі GLM](/uk/providers/glm), + [MiniMax](/uk/providers/minimax), [GLM Models](/uk/providers/glm), [Локальні моделі](/uk/gateway/local-models), [Моделі](/uk/concepts/models). - + Так. Співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому - OpenClaw вважає автентифікацію через підписку Claude і використання `claude -p` - санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. - Якщо вам потрібне найбільш передбачуване налаштування на стороні сервера, замість цього використовуйте API ключ Anthropic. + OpenClaw розглядає автентифікацію через підписку Claude і використання `claude -p` як санкціоновані + для цієї інтеграції, якщо Anthropic не опублікує нову політику. Якщо вам потрібне + найбільш передбачуване серверне налаштування, натомість використовуйте API-ключ Anthropic. Так. - Співробітники Anthropic повідомили нам, що таке використання знову дозволене, тому OpenClaw вважає - повторне використання Claude CLI і використання `claude -p` санкціонованими для цієї інтеграції, + Співробітники Anthropic повідомили нам, що таке використання знову дозволене, тому OpenClaw розглядає + повторне використання Claude CLI і використання `claude -p` як санкціоновані для цієї інтеграції, якщо Anthropic не опублікує нову політику. - Anthropic setup-token усе ще доступний як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, коли це доступно. - Для production або багатокористувацьких навантажень автентифікація через API ключ Anthropic усе ще є - безпечнішим і передбачуванішим вибором. Якщо вас цікавлять інші хостовані - варіанти у стилі підписки в OpenClaw, дивіться [OpenAI](/uk/providers/openai), [Qwen / Model + setup-token Anthropic усе ще доступний як підтримуваний шлях токена OpenClaw, але тепер OpenClaw віддає перевагу повторному використанню Claude CLI і `claude -p`, коли це доступно. + Для production або багатокористувацьких навантажень автентифікація через API-ключ Anthropic усе ще є + безпечнішим і більш передбачуваним вибором. Якщо вам потрібні інші розміщені + варіанти у стилі підписки в OpenClaw, див. [OpenAI](/uk/providers/openai), [Qwen / Model Cloud](/uk/providers/qwen), [MiniMax](/uk/providers/minimax) і [GLM Models](/uk/providers/glm). @@ -641,121 +641,121 @@ x-i18n: Це означає, що вашу **квоту/ліміт запитів Anthropic** вичерпано для поточного вікна. Якщо ви використовуєте **Claude CLI**, зачекайте, поки вікно скинеться, або оновіть свій план. Якщо ви -використовуєте **API ключ Anthropic**, перевірте Anthropic Console +використовуєте **API-ключ Anthropic**, перевірте Anthropic Console щодо використання/білінгу та за потреби підвищте ліміти. Якщо повідомлення конкретно таке: - `Extra usage is required for long context requests`, запит намагається використовувати - 1M context beta від Anthropic (`context1m: true`). Це працює лише тоді, коли ваші - облікові дані мають право на білінг довгого контексту (білінг за API ключем або - шлях входу OpenClaw Claude з увімкненим Extra Usage). + `Extra usage is required for long context requests`, запит намагається використати + бета-функцію контексту 1M від Anthropic (`context1m: true`). Це працює лише тоді, коли ваші + облікові дані мають право на білінг довгого контексту (білінг за API-ключем або + шлях входу Claude в OpenClaw з увімкненим Extra Usage). - Порада: налаштуйте **резервну модель**, щоб OpenClaw міг продовжувати відповідати, поки провайдер обмежений rate limit. - Дивіться [Моделі](/cli/models), [OAuth](/uk/concepts/oauth) і + Порада: установіть **резервну модель**, щоб OpenClaw міг продовжувати відповідати, поки провайдер обмежений за лімітом запитів. + Див. [Models](/cli/models), [OAuth](/uk/concepts/oauth) і [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/uk/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context). - Так. OpenClaw має bundled провайдер **Amazon Bedrock (Converse)**. За наявності AWS env markers OpenClaw може автоматично виявляти каталог Bedrock для streaming/text і об’єднувати його як неявний провайдер `amazon-bedrock`; в іншому разі ви можете явно ввімкнути `plugins.entries.amazon-bedrock.config.discovery.enabled` або додати запис провайдера вручну. Дивіться [Amazon Bedrock](/uk/providers/bedrock) і [Провайдери моделей](/uk/providers/models). Якщо ви віддаєте перевагу керованому потоку ключів, OpenAI-сумісний proxy перед Bedrock також залишається чинним варіантом. + Так. OpenClaw має вбудований провайдер **Amazon Bedrock (Converse)**. За наявності маркерів середовища AWS OpenClaw може автоматично виявити каталог потокових/текстових моделей Bedrock і об’єднати його як неявного провайдера `amazon-bedrock`; інакше ви можете явно ввімкнути `plugins.entries.amazon-bedrock.config.discovery.enabled` або додати запис провайдера вручну. Див. [Amazon Bedrock](/uk/providers/bedrock) і [Провайдери моделей](/uk/providers/models). Якщо ви віддаєте перевагу керованому потоку ключів, OpenAI-сумісний proxy перед Bedrock теж залишається коректним варіантом. - OpenClaw підтримує **OpenAI Code (Codex)** через OAuth (вхід через ChatGPT). Онбординг може запустити OAuth-потік і за потреби встановить модель за замовчуванням `openai-codex/gpt-5.4`. Дивіться [Провайдери моделей](/uk/concepts/model-providers) і [Онбординг (CLI)](/uk/start/wizard). + OpenClaw підтримує **OpenAI Code (Codex)** через OAuth (вхід через ChatGPT). Під час онбордингу можна пройти OAuth-потік, і за потреби він встановить модель за замовчуванням `openai-codex/gpt-5.4`. Див. [Провайдери моделей](/uk/concepts/model-providers) і [Онбординг (CLI)](/uk/start/wizard). - + OpenClaw розглядає ці два шляхи окремо: - `openai-codex/gpt-5.4` = OAuth ChatGPT/Codex - `openai/gpt-5.4` = прямий API OpenAI Platform В OpenClaw вхід через ChatGPT/Codex прив’язаний до маршруту `openai-codex/*`, - а не до прямого маршруту `openai/*`. Якщо ви хочете прямий API-шлях в + а не до прямого маршруту `openai/*`. Якщо вам потрібен прямий API-шлях в OpenClaw, установіть `OPENAI_API_KEY` (або еквівалентну конфігурацію провайдера OpenAI). - Якщо ви хочете вхід через ChatGPT/Codex в OpenClaw, використовуйте `openai-codex/*`. + Якщо вам потрібен вхід через ChatGPT/Codex в OpenClaw, використовуйте `openai-codex/*`. `openai-codex/*` використовує маршрут Codex OAuth, а його доступні вікна квот керуються OpenAI і залежать від плану. На практиці ці ліміти можуть відрізнятися від - досвіду використання сайту/застосунку ChatGPT, навіть якщо обидва прив’язані до одного облікового запису. + досвіду на сайті/в застосунку ChatGPT, навіть якщо обидва прив’язані до одного облікового запису. OpenClaw може показувати поточні видимі вікна використання/квоти провайдера в - `openclaw models status`, але він не вигадує і не нормалізує права ChatGPT-web - у прямий доступ до API. Якщо ви хочете прямий шлях білінгу/лімітів OpenAI Platform, - використовуйте `openai/*` з API ключем. + `openclaw models status`, але не вигадує і не нормалізує entitlements ChatGPT web + у прямий доступ до API. Якщо вам потрібен прямий шлях білінгу/лімітів OpenAI Platform, + використовуйте `openai/*` з API-ключем. - Так. OpenClaw повністю підтримує **OAuth підписки OpenAI Code (Codex)**. - OpenAI явно дозволяє використання OAuth підписки в зовнішніх інструментах/процесах, - таких як OpenClaw. Онбординг може запустити OAuth-потік для вас. + Так. OpenClaw повністю підтримує **OAuth через підписку OpenAI Code (Codex)**. + OpenAI явно дозволяє використання OAuth підписки у зовнішніх інструментах/робочих процесах + на кшталт OpenClaw. Під час онбордингу можна пройти OAuth-потік за вас. - Дивіться [OAuth](/uk/concepts/oauth), [Провайдери моделей](/uk/concepts/model-providers) і [Онбординг (CLI)](/uk/start/wizard). + Див. [OAuth](/uk/concepts/oauth), [Провайдери моделей](/uk/concepts/model-providers) і [Онбординг (CLI)](/uk/start/wizard). - Gemini CLI використовує **Plugin auth flow**, а не client id чи secret у `openclaw.json`. + Gemini CLI використовує **потік автентифікації Plugin**, а не client id чи secret у `openclaw.json`. Кроки: 1. Установіть Gemini CLI локально, щоб `gemini` був у `PATH` - Homebrew: `brew install gemini-cli` - npm: `npm install -g @google/gemini-cli` - 2. Увімкніть Plugin: `openclaw plugins enable google` + 2. Увімкніть plugin: `openclaw plugins enable google` 3. Увійдіть: `openclaw models auth login --provider google-gemini-cli --set-default` 4. Модель за замовчуванням після входу: `google-gemini-cli/gemini-3-flash-preview` 5. Якщо запити не працюють, установіть `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway - Це зберігає OAuth-токени в профілях автентифікації на хості gateway. Деталі: [Провайдери моделей](/uk/concepts/model-providers). + Це зберігає OAuth-токени в профілях автентифікації на хості gateway. Подробиці: [Провайдери моделей](/uk/concepts/model-providers). - Зазвичай ні. OpenClaw потребує великого контексту + сильної безпеки; малі карти обрізають і протікають. Якщо це необхідно, запускайте **найбільшу** збірку моделі, яку можете локально (LM Studio), і дивіться [/gateway/local-models](/uk/gateway/local-models). Менші/квантизовані моделі підвищують ризик prompt injection — дивіться [Безпека](/uk/gateway/security). + Зазвичай ні. OpenClaw потребує великого контексту + сильної безпеки; малі картки обрізають і протікають. Якщо все ж потрібно, запускайте **найбільшу** збірку моделі, яку можете локально (LM Studio), і див. [/gateway/local-models](/uk/gateway/local-models). Менші/квантизовані моделі збільшують ризик prompt injection — див. [Безпека](/uk/gateway/security). - - Вибирайте endpoint-и з прив’язкою до регіону. OpenRouter надає US-hosted варіанти для MiniMax, Kimi і GLM; вибирайте варіант, хостований у США, щоб дані залишалися в регіоні. Ви все одно можете перелічувати Anthropic/OpenAI поряд із ними, використовуючи `models.mode: "merge"`, щоб резервні варіанти залишалися доступними, водночас дотримуючись вибраного вами регіонального провайдера. + + Вибирайте endpoints, прив’язані до регіону. OpenRouter надає варіанти, розміщені у США, для MiniMax, Kimi і GLM; виберіть варіант, розміщений у США, щоб зберігати дані в межах регіону. Ви все одно можете перелічувати Anthropic/OpenAI поруч із ними, використовуючи `models.mode: "merge"`, щоб резервні варіанти залишалися доступними, одночасно дотримуючись вибраного регіонального провайдера. - Ні. OpenClaw працює на macOS або Linux (Windows через WSL2). Mac mini — необов’язковий: деякі люди - купують його як постійно ввімкнений хост, але також підійде невеликий VPS, домашній сервер або пристрій класу Raspberry Pi. + Ні. OpenClaw працює на macOS або Linux (Windows через WSL2). Mac mini — необов’язковий варіант: дехто + купує його як постійно ввімкнений хост, але також підійде невеликий VPS, домашній сервер або пристрій класу Raspberry Pi. - Mac потрібен лише для **інструментів лише для macOS**. Для iMessage використовуйте [BlueBubbles](/uk/channels/bluebubbles) (рекомендовано) — сервер BlueBubbles працює на будь-якому Mac, а Gateway може працювати на Linux або деінде. Якщо вам потрібні інші інструменти лише для macOS, запускайте Gateway на Mac або підключайте macOS node. + Mac потрібен лише **для інструментів лише для macOS**. Для iMessage використовуйте [BlueBubbles](/uk/channels/bluebubbles) (рекомендовано) — сервер BlueBubbles працює на будь-якому Mac, а Gateway може працювати на Linux або деінде. Якщо вам потрібні інші інструменти лише для macOS, запускайте Gateway на Mac або під’єднайте macOS Node. Документація: [BlueBubbles](/uk/channels/bluebubbles), [Nodes](/uk/nodes), [Віддалений режим Mac](/uk/platforms/mac/remote). - Вам потрібен **якийсь пристрій macOS**, на якому виконано вхід у Messages. Це **не** обов’язково має бути Mac mini — + Вам потрібен **якийсь пристрій macOS**, увійшовший у Messages. Це **не обов’язково** має бути Mac mini — підійде будь-який Mac. Для iMessage **використовуйте [BlueBubbles](/uk/channels/bluebubbles)** (рекомендовано) — сервер BlueBubbles працює на macOS, тоді як Gateway може працювати на Linux або деінде. - Типові сценарії: + Поширені конфігурації: - - Запускайте Gateway на Linux/VPS, а сервер BlueBubbles — на будь-якому Mac із входом у Messages. - - Запускайте все на Mac, якщо хочете найпростішу конфігурацію на одній машині. + - Запустіть Gateway на Linux/VPS, а сервер BlueBubbles — на будь-якому Mac, увійшовшому в Messages. + - Запустіть усе на Mac, якщо хочете найпростішу конфігурацію з однією машиною. Документація: [BlueBubbles](/uk/channels/bluebubbles), [Nodes](/uk/nodes), [Віддалений режим Mac](/uk/platforms/mac/remote). - - Так. **Mac mini може запускати Gateway**, а ваш MacBook Pro може під’єднатися як - **node** (супутній пристрій). Nodes не запускають Gateway — вони надають додаткові + + Так. **Mac mini може запускати Gateway**, а ваш MacBook Pro може підключатися як + **Node** (додатковий пристрій). Nodes не запускають Gateway — вони надають додаткові можливості, як-от екран/камера/canvas і `system.run` на цьому пристрої. - Типовий шаблон: + Поширений шаблон: - - Gateway на Mac mini (завжди ввімкнений). - - MacBook Pro запускає застосунок macOS або node host і під’єднується до Gateway. + - Gateway на Mac mini (постійно ввімкнений). + - MacBook Pro запускає застосунок macOS або хост Node і під’єднується до Gateway. - Використовуйте `openclaw nodes status` / `openclaw nodes list`, щоб побачити його. Документація: [Nodes](/uk/nodes), [CLI Nodes](/cli/nodes). @@ -763,41 +763,41 @@ x-i18n: - Bun **не рекомендований**. Ми спостерігаємо помилки під час виконання, особливо з WhatsApp і Telegram. + Bun **не рекомендується**. Ми спостерігаємо помилки під час виконання, особливо з WhatsApp і Telegram. Для стабільних gateway використовуйте **Node**. - Якщо ви все ж хочете поекспериментувати з Bun, робіть це на непродакшн gateway + Якщо ви все ж хочете поекспериментувати з Bun, робіть це на gateway не для production без WhatsApp/Telegram. - + `channels.telegram.allowFrom` — це **Telegram user ID людини-відправника** (числовий). Це не ім’я користувача бота. Під час налаштування запитуються лише числові user ID. Якщо у вашій конфігурації вже є застарілі записи `@username`, `openclaw doctor --fix` може спробувати їх розв’язати. - Безпечніший варіант (без стороннього бота): + Безпечніше (без стороннього бота): - - Напишіть своєму боту в DM, потім виконайте `openclaw logs --follow` і прочитайте `from.id`. + - Напишіть своєму боту в DM, а потім виконайте `openclaw logs --follow` і прочитайте `from.id`. Офіційний Bot API: - - Напишіть своєму боту в DM, потім викличте `https://api.telegram.org/bot/getUpdates` і прочитайте `message.from.id`. + - Напишіть своєму боту в DM, а потім викличте `https://api.telegram.org/bot/getUpdates` і прочитайте `message.from.id`. Сторонній варіант (менш приватний): - Напишіть у DM `@userinfobot` або `@getidsbot`. - Дивіться [/channels/telegram](/uk/channels/telegram#access-control-and-activation). + Див. [/channels/telegram](/uk/channels/telegram#access-control-and-activation). - - Так, через **маршрутизацію multi-agent**. Прив’яжіть **DM** WhatsApp кожного відправника (peer `kind: "direct"`, sender E.164 на кшталт `+15551234567`) до різного `agentId`, щоб кожна людина мала власний workspace і сховище сесій. Відповіді все одно надходитимуть з **того самого облікового запису WhatsApp**, а контроль доступу до DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) є глобальним для кожного облікового запису WhatsApp. Дивіться [Маршрутизація Multi-Agent](/uk/concepts/multi-agent) і [WhatsApp](/uk/channels/whatsapp). + + Так, через **маршрутизацію кількох агентів**. Прив’яжіть **DM** WhatsApp кожного відправника (peer `kind: "direct"`, E.164 відправника на кшталт `+15551234567`) до іншого `agentId`, щоб кожна людина мала власний workspace і session store. Відповіді все одно надходитимуть з **того самого облікового запису WhatsApp**, а контроль доступу DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) є глобальним для кожного облікового запису WhatsApp. Див. [Маршрутизація кількох агентів](/uk/concepts/multi-agent) і [WhatsApp](/uk/channels/whatsapp). - - Так. Використовуйте маршрутизацію multi-agent: надайте кожному агенту власну модель за замовчуванням, а потім прив’яжіть вхідні маршрути (обліковий запис провайдера або конкретні peers) до кожного агента. Приклад конфігурації наведено в [Маршрутизації Multi-Agent](/uk/concepts/multi-agent). Дивіться також [Моделі](/uk/concepts/models) і [Конфігурація](/uk/gateway/configuration). + + Так. Використовуйте маршрутизацію кількох агентів: надайте кожному агенту власну модель за замовчуванням, а потім прив’яжіть вхідні маршрути (обліковий запис провайдера або конкретних peers) до кожного агента. Приклад конфігурації наведено в [Маршрутизація кількох агентів](/uk/concepts/multi-agent). Див. також [Моделі](/uk/concepts/models) і [Конфігурація](/uk/gateway/configuration). @@ -810,24 +810,24 @@ x-i18n: brew install ``` - Якщо ви запускаєте OpenClaw через systemd, переконайтеся, що PATH сервісу включає `/home/linuxbrew/.linuxbrew/bin` (або ваш префікс brew), щоб інструменти, встановлені через `brew`, знаходилися в оболонках без входу в систему. - Останні збірки також додають на початок типові каталоги user bin у сервісах Linux systemd (наприклад, `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) і враховують `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` і `FNM_DIR`, якщо вони задані. + Якщо ви запускаєте OpenClaw через systemd, переконайтеся, що PATH сервісу містить `/home/linuxbrew/.linuxbrew/bin` (або ваш префікс brew), щоб інструменти, встановлені через `brew`, розв’язувалися в non-login оболонках. + Останні збірки також додають на початок поширені користувацькі каталоги bin у Linux systemd services (наприклад `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) і враховують `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` і `FNM_DIR`, якщо вони задані. - - - **Hackable (git) install:** повний checkout вихідного коду, можна редагувати, найкраще для contributors. + + - **Інсталяція git для редагування:** повний checkout вихідного коду, можна редагувати, найкраще для контриб’юторів. Ви локально запускаєте збірки й можете вносити зміни в код/документацію. - **npm install:** глобальне встановлення CLI, без репозиторію, найкраще для сценарію «просто запустити». - Оновлення надходять із npm dist-tags. + Оновлення надходять через npm dist-tags. Документація: [Початок роботи](/uk/start/getting-started), [Оновлення](/uk/install/updating). - - Так. Установіть інший варіант, а потім запустіть Doctor, щоб сервіс gateway вказував на нову entrypoint. - Це **не видаляє ваші дані** — змінюється лише встановлення коду OpenClaw. Ваш стан + + Так. Установіть інший варіант, а потім запустіть Doctor, щоб сервіс gateway вказував на нову точку входу. + Це **не видаляє ваші дані** — змінюється лише інсталяція коду OpenClaw. Ваш стан (`~/.openclaw`) і workspace (`~/.openclaw/workspace`) залишаються недоторканими. З npm на git: @@ -841,7 +841,7 @@ x-i18n: openclaw gateway restart ``` - Із git на npm: + З git на npm: ```bash npm install -g openclaw@latest @@ -849,50 +849,50 @@ x-i18n: openclaw gateway restart ``` - Doctor виявляє невідповідність entrypoint сервісу gateway і пропонує переписати конфігурацію сервісу відповідно до поточного встановлення (використовуйте `--repair` в автоматизації). + Doctor виявляє невідповідність точки входу сервісу gateway і пропонує переписати конфігурацію сервісу відповідно до поточного встановлення (у сценаріях автоматизації використовуйте `--repair`). - Поради щодо резервного копіювання: дивіться [Стратегія резервного копіювання](#where-things-live-on-disk). + Поради щодо резервного копіювання: див. [Стратегія резервного копіювання](#where-things-live-on-disk). - Коротка відповідь: **якщо вам потрібна надійність 24/7, використовуйте VPS**. Якщо вам потрібен - найменший тертя і ви нормально ставитеся до сну/перезапусків, запускайте локально. + Коротка відповідь: **якщо вам потрібна надійність 24/7, використовуйте VPS**. Якщо вам потрібне + мінімальне тертя і вас влаштовують сон/перезапуски, запускайте локально. **Ноутбук (локальний Gateway)** - - **Переваги:** без вартості сервера, прямий доступ до локальних файлів, видиме вікно браузера в реальному часі. - - **Недоліки:** сон/мережеві обриви = відключення, оновлення ОС/перезавантаження переривають роботу, машина має залишатися активною. + - **Переваги:** немає витрат на сервер, прямий доступ до локальних файлів, видиме вікно браузера. + - **Недоліки:** сон/обриви мережі = відключення, оновлення/перезавантаження ОС переривають роботу, машина має залишатися активною. **VPS / хмара** - - **Переваги:** завжди увімкнено, стабільна мережа, немає проблем зі сном ноутбука, легше підтримувати безперервну роботу. - - **Недоліки:** часто headless-режим (використовуйте скриншоти), лише віддалений доступ до файлів, для оновлень потрібен SSH. + - **Переваги:** завжди ввімкнено, стабільна мережа, немає проблем через сон ноутбука, простіше підтримувати роботу. + - **Недоліки:** часто headless-режим (використовуйте знімки екрана), лише віддалений доступ до файлів, для оновлень потрібно SSH. - **Примітка щодо OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord чудово працюють із VPS. Єдиний реальний компроміс — це **headless browser** проти видимого вікна. Дивіться [Browser](/uk/tools/browser). + **Примітка для OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord чудово працюють з VPS. Єдиний реальний компроміс — **headless browser** проти видимого вікна. Див. [Браузер](/uk/tools/browser). - **Рекомендовано за замовчуванням:** VPS, якщо у вас раніше були відключення gateway. Локальний запуск чудово підходить, коли ви активно користуєтеся Mac і хочете мати доступ до локальних файлів або автоматизації UI з видимим браузером. + **Рекомендований варіант за замовчуванням:** VPS, якщо у вас раніше були відключення gateway. Локальний запуск чудовий, коли ви активно користуєтеся Mac і хочете доступ до локальних файлів або автоматизацію UI з видимим браузером. - Це не обов’язково, але **рекомендується для надійності та ізоляції**. + Не обов’язково, але **рекомендується для надійності й ізоляції**. - - **Окремий хост (VPS/Mac mini/Pi):** завжди увімкнений, менше переривань через сон/перезавантаження, чистіші дозволи, легше підтримувати безперервну роботу. - - **Спільний ноутбук/настільний ПК:** цілком підходить для тестування й активного використання, але очікуйте пауз, коли машина переходить у сон або оновлюється. + - **Виділений хост (VPS/Mac mini/Pi):** завжди ввімкнений, менше переривань через сон/перезавантаження, чистіші дозволи, простіше підтримувати роботу. + - **Спільний ноутбук/десктоп:** цілком підходить для тестування й активного використання, але очікуйте пауз, коли машина засинає або оновлюється. - Якщо ви хочете найкраще з обох світів, тримайте Gateway на окремому хості, а ноутбук під’єднуйте як **node** для локальних інструментів екрана/камери/exec. Дивіться [Nodes](/uk/nodes). - Для рекомендацій із безпеки прочитайте [Безпека](/uk/gateway/security). + Якщо хочете найкраще з обох світів, тримайте Gateway на виділеному хості, а ноутбук під’єднайте як **Node** для локальних інструментів screen/camera/exec. Див. [Nodes](/uk/nodes). + Рекомендації з безпеки див. в [Безпека](/uk/gateway/security). - - OpenClaw легкий. Для базового Gateway + одного чат-каналу: + + OpenClaw легкий. Для базового Gateway + одного каналу чату: - **Абсолютний мінімум:** 1 vCPU, 1 ГБ RAM, ~500 МБ диска. - - **Рекомендовано:** 1–2 vCPU, 2 ГБ RAM або більше для запасу (журнали, медіа, кілька каналів). Інструменти Node і автоматизація браузера можуть бути вимогливими до ресурсів. + - **Рекомендовано:** 1–2 vCPU, 2 ГБ RAM або більше із запасом (логи, медіа, кілька каналів). Інструменти Node і автоматизація браузера можуть бути вимогливими до ресурсів. - ОС: використовуйте **Ubuntu LTS** (або будь-який сучасний Debian/Ubuntu). Шлях встановлення для Linux там протестований найкраще. + ОС: використовуйте **Ubuntu LTS** (або будь-який сучасний Debian/Ubuntu). Шлях встановлення для Linux там протестовано найкраще. Документація: [Linux](/uk/platforms/linux), [VPS-хостинг](/uk/vps). @@ -900,17 +900,17 @@ x-i18n: Так. Ставтеся до VM так само, як до VPS: вона має бути завжди ввімкненою, доступною і мати достатньо - RAM для Gateway і будь-яких каналів, які ви ввімкнете. + RAM для Gateway та всіх каналів, які ви вмикаєте. Базові рекомендації: - **Абсолютний мінімум:** 1 vCPU, 1 ГБ RAM. - - **Рекомендовано:** 2 ГБ RAM або більше, якщо ви запускаєте кілька каналів, автоматизацію браузера чи медіа-інструменти. + - **Рекомендовано:** 2 ГБ RAM або більше, якщо ви запускаєте кілька каналів, автоматизацію браузера чи медіаінструменти. - **ОС:** Ubuntu LTS або інший сучасний Debian/Ubuntu. - Якщо ви працюєте у Windows, **WSL2 — це найпростіше налаштування у стилі VM** і воно має найкращу - сумісність інструментів. Дивіться [Windows](/uk/platforms/windows), [VPS-хостинг](/uk/vps). - Якщо ви запускаєте macOS у VM, дивіться [macOS VM](/uk/install/macos-vm). + Якщо ви працюєте у Windows, **WSL2 — найпростіше налаштування у стилі VM** і має найкращу + сумісність інструментів. Див. [Windows](/uk/platforms/windows), [VPS-хостинг](/uk/vps). + Якщо ви запускаєте macOS у VM, див. [macOS VM](/uk/install/macos-vm). @@ -919,64 +919,64 @@ x-i18n: - OpenClaw — це персональний AI-помічник, який ви запускаєте на власних пристроях. Він відповідає на поверхнях обміну повідомленнями, якими ви вже користуєтеся (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat, а також bundled channel plugins, такі як QQ Bot) і також може працювати з голосом + live Canvas на підтримуваних платформах. **Gateway** — це постійно увімкнена control plane; помічник — це продукт. + OpenClaw — це персональний AI-помічник, який ви запускаєте на власних пристроях. Він відповідає в тих поверхнях обміну повідомленнями, якими ви вже користуєтеся (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat і вбудовані channel plugin, як-от QQ Bot), а також може працювати з голосом + живим Canvas на підтримуваних платформах. **Gateway** — це постійно ввімкнена контрольна площина; помічник — це сам продукт. - OpenClaw — це не «просто обгортка для Claude». Це **локальна насамперед control plane**, яка дає вам змогу запускати - потужного помічника на **вашому власному обладнанні**, доступного з чат-застосунків, якими ви вже користуєтеся, зі - станом сесій, пам’яттю та інструментами — без передачі контролю над вашими процесами хостованому + OpenClaw — це не «просто обгортка для Claude». Це **локальна контрольна площина з пріоритетом локальності**, яка дає змогу запускати + потужного помічника на **вашому власному обладнанні**, доступного з чат-застосунків, якими ви вже користуєтеся, з + сесійним станом, пам’яттю та інструментами — без передачі контролю над вашими робочими процесами розміщеному SaaS. Основні переваги: - - **Ваші пристрої, ваші дані:** запускайте Gateway там, де хочете (Mac, Linux, VPS), і зберігайте + - **Ваші пристрої, ваші дані:** запускайте Gateway де завгодно (Mac, Linux, VPS) і зберігайте workspace + історію сесій локально. - - **Реальні канали, а не веб-пісочниця:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage тощо, - плюс мобільний голос і Canvas на підтримуваних платформах. - - **Незалежність від моделі:** використовуйте Anthropic, OpenAI, MiniMax, OpenRouter тощо з маршрутизацією - та резервним перемиканням на рівні агента. + - **Справжні канали, а не веб-пісочниця:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage тощо, + а також мобільний голос і Canvas на підтримуваних платформах. + - **Незалежність від моделі:** використовуйте Anthropic, OpenAI, MiniMax, OpenRouter тощо, з маршрутизацією + і резервуванням на рівні агента. - **Варіант лише локально:** запускайте локальні моделі, щоб **усі дані могли залишатися на вашому пристрої**, якщо ви цього хочете. - - **Маршрутизація multi-agent:** окремі агенти для кожного каналу, облікового запису або завдання, кожен зі своїм - workspace і налаштуваннями за замовчуванням. - - **Відкритий код і hackable:** перевіряйте, розширюйте й self-host без vendor lock-in. + - **Маршрутизація кількох агентів:** окремі агенти для кожного каналу, облікового запису або завдання, кожен зі своїм + workspace і параметрами за замовчуванням. + - **Відкритий код і можливість змінювати:** перевіряйте, розширюйте й самостійно хостіть без vendor lock-in. - Документація: [Gateway](/uk/gateway), [Канали](/uk/channels), [Multi-agent](/uk/concepts/multi-agent), + Документація: [Gateway](/uk/gateway), [Канали](/uk/channels), [Кілька агентів](/uk/concepts/multi-agent), [Пам’ять](/uk/concepts/memory). - Хороші перші проєкти: + Гарні перші проєкти: - - Створіть вебсайт (WordPress, Shopify або простий статичний сайт). - - Прототипуйте мобільний застосунок (план, екрани, план API). - - Організуйте файли та папки (очищення, найменування, тегування). - - Під’єднайте Gmail і автоматизуйте підсумки або подальші дії. + - Створити вебсайт (WordPress, Shopify або простий статичний сайт). + - Прототипувати мобільний застосунок (структура, екрани, план API). + - Організувати файли та папки (очищення, іменування, теги). + - Підключити Gmail і автоматизувати зведення або подальші дії. - Він може виконувати великі завдання, але найкраще працює, коли ви ділите їх на фази і - використовуєте sub agents для паралельної роботи. + Він може обробляти великі завдання, але найкраще працює, коли ви розбиваєте їх на етапи й + використовуєте субагентів для паралельної роботи. - - Повсякденна користь зазвичай виглядає так: + + Щоденні виграші зазвичай виглядають так: - - **Персональні зведення:** підсумки пошти, календаря та новин, які для вас важливі. - - **Дослідження та чернетки:** швидкі дослідження, підсумки й перші чернетки для листів або документів. - - **Нагадування та подальші дії:** підказки й чеклісти на основі Cron або Heartbeat. - - **Автоматизація браузера:** заповнення форм, збір даних і повторювані веб-завдання. - - **Координація між пристроями:** надішліть завдання з телефону, дайте Gateway виконати його на сервері й отримайте результат назад у чат. + - **Персональні зведення:** підсумки вхідних повідомлень, календаря та новин, які вас цікавлять. + - **Дослідження та чернетки:** швидкі дослідження, підсумки й перші чернетки листів або документів. + - **Нагадування та подальші дії:** поштовхи й чеклісти на основі cron або Heartbeat. + - **Автоматизація браузера:** заповнення форм, збирання даних і повторення вебзавдань. + - **Координація між пристроями:** надішліть завдання з телефона, дозвольте Gateway виконати його на сервері та отримайте результат назад у чаті. - - Так, для **дослідження, кваліфікації та створення чернеток**. Він може сканувати сайти, формувати shortlists, - підсумовувати інформацію про потенційних клієнтів і писати чернетки outreach або рекламних текстів. + + Так — для **дослідження, кваліфікації та створення чернеток**. Він може сканувати сайти, складати короткі списки, + підсумовувати потенційних клієнтів і писати чернетки outreach або рекламних текстів. - Для **outreach або запуску реклами** залишайте людину в циклі. Уникайте спаму, дотримуйтеся місцевих законів і - політик платформ, а також перевіряйте все перед надсиланням. Найбезпечніший шаблон — дозволити - OpenClaw створити чернетку, а вам — погодити її. + Для **outreach або запуску реклами** тримайте людину в циклі. Уникайте спаму, дотримуйтесь місцевих законів і + політик платформ та перевіряйте все перед надсиланням. Найбезпечніший шаблон — дозволити + OpenClaw створити чернетку, а вам — затвердити її. Документація: [Безпека](/uk/gateway/security). @@ -985,15 +985,15 @@ x-i18n: OpenClaw — це **персональний помічник** і рівень координації, а не заміна IDE. Використовуйте Claude Code або Codex для найшвидшого прямого циклу кодування в репозиторії. Використовуйте OpenClaw, коли вам - потрібні довготривала пам’ять, доступ із різних пристроїв та оркестрація інструментів. + потрібні стійка пам’ять, доступ між пристроями та оркестрація інструментів. Переваги: - **Постійна пам’ять + workspace** між сесіями - - **Доступ із різних платформ** (WhatsApp, Telegram, TUI, WebChat) - - **Оркестрація інструментів** (browser, files, scheduling, hooks) - - **Постійно увімкнений Gateway** (запускайте на VPS, взаємодійте звідусіль) - - **Nodes** для локального browser/screen/camera/exec + - **Доступ із кількох платформ** (WhatsApp, Telegram, TUI, WebChat) + - **Оркестрація інструментів** (браузер, файли, планування, hooks) + - **Постійно ввімкнений Gateway** (запуск на VPS, взаємодія звідусіль) + - **Nodes** для локального браузера/екрана/камери/exec Вітрина: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) @@ -1003,69 +1003,69 @@ x-i18n: ## Skills і автоматизація - - Використовуйте керовані override-заміни замість редагування копії в репозиторії. Зберігайте свої зміни в `~/.openclaw/skills//SKILL.md` (або додайте папку через `skills.load.extraDirs` у `~/.openclaw/openclaw.json`). Пріоритет такий: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`, тож керовані override-заміни все одно мають пріоритет над bundled skills без змін у git. Якщо вам потрібно, щоб skill був установлений глобально, але видимий лише певним агентам, зберігайте спільну копію в `~/.openclaw/skills` і керуйте видимістю через `agents.defaults.skills` та `agents.list[].skills`. Лише зміни, варті апстріму, мають жити в репозиторії та надсилатися як PR. + + Використовуйте керовані overrides замість редагування копії в репозиторії. Помістіть свої зміни в `~/.openclaw/skills//SKILL.md` (або додайте папку через `skills.load.extraDirs` у `~/.openclaw/openclaw.json`). Пріоритет такий: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → вбудовані → `skills.load.extraDirs`, тому керовані overrides все одно мають вищий пріоритет за вбудовані Skills без зміни git. Якщо вам потрібно встановити Skill глобально, але зробити його видимим лише для деяких агентів, тримайте спільну копію в `~/.openclaw/skills` і керуйте видимістю через `agents.defaults.skills` і `agents.list[].skills`. Лише зміни, варті включення в основний репозиторій, повинні жити в репозиторії й надсилатися як PR. - - Так. Додайте додаткові каталоги через `skills.load.extraDirs` у `~/.openclaw/openclaw.json` (найнижчий пріоритет). Пріоритет за замовчуванням: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`. `clawhub` установлює в `./skills` за замовчуванням, що OpenClaw трактує як `/skills` у наступній сесії. Якщо skill має бути видимим лише певним агентам, поєднайте це з `agents.defaults.skills` або `agents.list[].skills`. + + Так. Додайте додаткові каталоги через `skills.load.extraDirs` у `~/.openclaw/openclaw.json` (найнижчий пріоритет). Типовий пріоритет: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → вбудовані → `skills.load.extraDirs`. `clawhub` типово встановлює в `./skills`, що OpenClaw розглядає як `/skills` у наступній сесії. Якщо Skill має бути видимим лише певним агентам, поєднуйте це з `agents.defaults.skills` або `agents.list[].skills`. Сьогодні підтримуються такі шаблони: - **Cron jobs**: ізольовані завдання можуть задавати override `model` для кожного завдання. - - **Sub-agents**: маршрутизуйте завдання до окремих агентів з різними моделями за замовчуванням. - - **Перемикання на вимогу**: використовуйте `/model`, щоб у будь-який момент перемкнути модель поточної сесії. + - **Субагенти**: маршрутизуйте завдання до окремих агентів з різними моделями за замовчуванням. + - **Перемикання на вимогу**: використовуйте `/model`, щоб у будь-який момент змінити модель поточної сесії. - Дивіться [Cron jobs](/uk/automation/cron-jobs), [Маршрутизація Multi-Agent](/uk/concepts/multi-agent) і [Slash-команди](/uk/tools/slash-commands). + Див. [Cron jobs](/uk/automation/cron-jobs), [Маршрутизація кількох агентів](/uk/concepts/multi-agent) і [Slash commands](/uk/tools/slash-commands). - - Використовуйте **sub-agents** для довгих або паралельних завдань. Sub-agents працюють у власній сесії, - повертають підсумок і зберігають чутливість вашого основного чату. + + Використовуйте **субагентів** для довгих або паралельних завдань. Субагенти працюють у власній сесії, + повертають підсумок і зберігають основний чат чутливим до відповіді. - Попросіть бота «spawn a sub-agent for this task» або використайте `/subagents`. - Використовуйте `/status` у чаті, щоб побачити, що Gateway робить просто зараз (і чи він зайнятий). + Попросіть свого бота «spawn a sub-agent for this task» або використайте `/subagents`. + Використовуйте `/status` у чаті, щоб бачити, що Gateway робить зараз (і чи він зайнятий). - Порада щодо токенів: довгі завдання й sub-agents обидва споживають токени. Якщо вартість важлива, установіть - дешевшу модель для sub-agents через `agents.defaults.subagents.model`. + Порада щодо токенів: і довгі завдання, і субагенти витрачають токени. Якщо важлива вартість, задайте + дешевшу модель для субагентів через `agents.defaults.subagents.model`. Документація: [Sub-agents](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks). - - Використовуйте прив’язки thread. Ви можете прив’язати Discord thread до subagent або session target, щоб наступні повідомлення в цьому thread залишалися в межах цієї прив’язаної сесії. + + Використовуйте прив’язки до гілок. Ви можете прив’язати гілку Discord до субагента або цілі сесії, щоб подальші повідомлення в цій гілці залишалися на цій прив’язаній сесії. Базовий процес: - - Створіть через `sessions_spawn` з `thread: true` (і за бажанням `mode: "session"` для постійших подальших повідомлень). - - Або прив’яжіть вручну через `/focus `. + - Створіть через `sessions_spawn` з `thread: true` (і за потреби `mode: "session"` для постійших подальших повідомлень). + - Або прив’яжіть вручну за допомогою `/focus `. - Використовуйте `/agents`, щоб перевірити стан прив’язки. - - Використовуйте `/session idle ` і `/session max-age `, щоб керувати автоматичним зняттям фокуса. - - Використовуйте `/unfocus`, щоб від’єднати thread. + - Використовуйте `/session idle ` і `/session max-age `, щоб керувати автоматичним зняттям фокусу. + - Використовуйте `/unfocus`, щоб від’єднати гілку. Потрібна конфігурація: - - Глобальні значення за замовчуванням: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. - - Override-значення для Discord: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. - - Автоприв’язка під час spawn: установіть `channels.discord.threadBindings.spawnSubagentSessions: true`. + - Глобальні параметри за замовчуванням: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. + - Overrides Discord: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. + - Автоприв’язка під час створення: установіть `channels.discord.threadBindings.spawnSubagentSessions: true`. - Документація: [Sub-agents](/uk/tools/subagents), [Discord](/uk/channels/discord), [Довідник із конфігурації](/uk/gateway/configuration-reference), [Slash-команди](/uk/tools/slash-commands). + Документація: [Sub-agents](/uk/tools/subagents), [Discord](/uk/channels/discord), [Configuration Reference](/uk/gateway/configuration-reference), [Slash commands](/uk/tools/slash-commands). - + Спочатку перевірте розв’язаний маршрут запитувача: - - Доставка subagent у режимі completion надає перевагу будь-якому прив’язаному thread або маршруту розмови, якщо такий існує. - - Якщо джерело completion містить лише канал, OpenClaw використовує запасний варіант — збережений маршрут сесії запитувача (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все одно могла спрацювати. - - Якщо немає ні прив’язаного маршруту, ні придатного збереженого маршруту, пряма доставка може не вдатися, і тоді результат замість негайної публікації в чаті переходить до доставки через чергу сесії. - - Некоректні або застарілі цілі все одно можуть змусити перейти до запасного варіанта з чергою або спричинити остаточну помилку доставки. - - Якщо остання видима відповідь помічника від дочірнього елемента — це точний тихий токен `NO_REPLY` / `no_reply` або точно `ANNOUNCE_SKIP`, OpenClaw навмисно пригнічує анонс, щоб не публікувати застарілий попередній прогрес. - - Якщо дочірній елемент завершився за тайм-аутом після лише викликів інструментів, анонс може згорнути це в короткий підсумок часткового прогресу замість відтворення сирого виводу інструментів. + - Доставка субагента в режимі завершення віддає перевагу будь-якій прив’язаній гілці або маршруту розмови, якщо такий існує. + - Якщо джерело завершення містить лише канал, OpenClaw повертається до збереженого маршруту сесії запитувача (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все ще могла спрацювати. + - Якщо немає ні прив’язаного маршруту, ні придатного збереженого маршруту, пряма доставка може завершитися невдачею, і результат замість негайної публікації в чаті переходить до доставки через чергу сесії. + - Некоректні або застарілі цілі все одно можуть примусово спричинити перехід до черги або остаточну помилку доставки. + - Якщо остання видима відповідь помічника дитини — це точний тихий токен `NO_REPLY` / `no_reply` або точно `ANNOUNCE_SKIP`, OpenClaw навмисно пригнічує анонс замість публікації застарілого попереднього прогресу. + - Якщо дитина завершилася за тайм-аутом після самих лише викликів інструментів, анонс може згорнути це в короткий підсумок часткового прогресу замість відтворення сирого виводу інструментів. Налагодження: @@ -1073,7 +1073,7 @@ x-i18n: openclaw tasks show ``` - Документація: [Sub-agents](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks), [Інструмент Session](/uk/concepts/session-tool). + Документація: [Sub-agents](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks), [Інструменти сесії](/uk/concepts/session-tool). @@ -1083,7 +1083,7 @@ x-i18n: Контрольний список: - - Переконайтеся, що cron увімкнено (`cron.enabled`) і `OPENCLAW_SKIP_CRON` не встановлено. + - Підтвердьте, що cron увімкнено (`cron.enabled`) і `OPENCLAW_SKIP_CRON` не встановлено. - Переконайтеся, що Gateway працює 24/7 (без сну/перезапусків). - Перевірте налаштування часового поясу для завдання (`--tz` проти часового поясу хоста). @@ -1098,17 +1098,17 @@ x-i18n: - + Спочатку перевірте режим доставки: - - `--no-deliver` / `delivery.mode: "none"` означає, що зовнішнє повідомлення не очікується. + - `--no-deliver` / `delivery.mode: "none"` означає, що жодного зовнішнього повідомлення не очікується. - Відсутня або некоректна ціль анонсу (`channel` / `to`) означає, що runner пропустив вихідну доставку. - - Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що runner спробував виконати доставку, але облікові дані її заблокували. - - Тихий ізольований результат (`NO_REPLY` / `no_reply` і нічого більше) вважається навмисно недоставлюваним, тому runner також пригнічує запасну доставку через чергу. + - Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що runner намагався доставити, але облікові дані заблокували це. + - Тихий ізольований результат (`NO_REPLY` / `no_reply` only) вважається навмисно недоставним, тому runner також пригнічує резервну доставку через чергу. - Для ізольованих Cron jobs runner відповідає за фінальну доставку. Від агента очікується - повернення підсумку звичайним текстом, який runner надішле. `--no-deliver` зберігає - цей результат внутрішнім; він не дозволяє агенту натомість надсилати напряму через + Для ізольованих Cron jobs runner керує остаточною доставкою. Очікується, що агент + поверне звичайний текстовий підсумок, який runner зможе надіслати. `--no-deliver` зберігає + цей результат внутрішнім; він не дозволяє агенту натомість напряму надсилати через message tool. Налагодження: @@ -1122,23 +1122,23 @@ x-i18n: - + Зазвичай це шлях live-перемикання моделі, а не дубльоване планування. - Ізольований cron може зберегти runtime-передачу моделі й повторити спробу, коли активний - запуск викидає `LiveSessionModelSwitchError`. Повторна спроба зберігає переключений - provider/model, а якщо перемикання також містило новий override профілю автентифікації, cron - зберігає і його перед повтором. + Ізольований cron може зберегти передачу моделі під час виконання і повторити спробу, коли активний + запуск викидає `LiveSessionModelSwitchError`. Повторна спроба зберігає перемкненого + провайдера/модель, а якщо перемикання несло новий override профілю автентифікації, cron + також зберігає це перед повторною спробою. Пов’язані правила вибору: - - Override моделі хука Gmail має найвищий пріоритет, коли застосовується. - - Потім іде `model` для конкретного завдання. + - Override моделі Gmail hook має найвищий пріоритет, коли застосовується. + - Далі — `model` для кожного завдання. - Потім будь-який збережений override моделі сесії cron. - Потім звичайний вибір моделі агента/за замовчуванням. - Цикл повторних спроб обмежений. Після початкової спроби плюс 2 повторів перемикання - cron перериває роботу замість нескінченного циклу. + Цикл повторних спроб обмежений. Після початкової спроби плюс 2 повторних спроб перемикання + cron припиняє роботу замість нескінченного циклу. Налагодження: @@ -1152,8 +1152,8 @@ x-i18n: - Використовуйте нативні команди `openclaw skills` або просто помістіть skills у свій workspace. UI Skills для macOS недоступний на Linux. - Переглянути skills можна на [https://clawhub.ai](https://clawhub.ai). + Використовуйте нативні команди `openclaw skills` або поміщайте Skills у свій workspace. UI Skills для macOS недоступний на Linux. + Переглядати Skills можна на [https://clawhub.ai](https://clawhub.ai). ```bash openclaw skills search "calendar" @@ -1166,11 +1166,11 @@ x-i18n: openclaw skills check ``` - Нативний `openclaw skills install` записує у каталог `skills/` + Нативний `openclaw skills install` записує в каталог `skills/` активного workspace. Окремий CLI `clawhub` встановлюйте лише якщо хочете публікувати або - синхронізувати власні skills. Для спільних встановлень між агентами розміщуйте skill у + синхронізувати власні Skills. Для спільних встановлень між агентами помістіть Skill у `~/.openclaw/skills` і використовуйте `agents.defaults.skills` або - `agents.list[].skills`, якщо хочете звузити коло агентів, які можуть його бачити. + `agents.list[].skills`, якщо хочете звузити перелік агентів, які можуть його бачити. @@ -1186,21 +1186,21 @@ x-i18n: - - Не напряму. Skills для macOS обмежуються `metadata.openclaw.os` плюс необхідними бінарними файлами, і skills з’являються в системному prompt лише тоді, коли вони придатні на **хості Gateway**. На Linux skills лише для `darwin` (як-от `apple-notes`, `apple-reminders`, `things-mac`) не завантажуватимуться, якщо ви не перевизначите це обмеження. + + Не напряму. Навички macOS фільтруються через `metadata.openclaw.os` плюс обов’язкові бінарники, і навички з’являються в системному prompt лише тоді, коли вони придатні на **хості Gateway**. На Linux навички лише для `darwin` (як-от `apple-notes`, `apple-reminders`, `things-mac`) не завантажаться, якщо ви не перевизначите це обмеження. - У вас є три підтримувані шаблони: + Є три підтримувані шаблони: **Варіант A — запускати Gateway на Mac (найпростіше).** - Запускайте Gateway там, де існують бінарні файли macOS, а потім підключайтеся з Linux у [віддаленому режимі](#gateway-ports-already-running-and-remote-mode) або через Tailscale. Skills завантажуються нормально, тому що хост Gateway — це macOS. + Запускайте Gateway там, де існують бінарники macOS, а потім підключайтеся з Linux у [віддаленому режимі](#gateway-ports-already-running-and-remote-mode) або через Tailscale. Навички завантажаться нормально, тому що хост Gateway — це macOS. - **Варіант B — використовувати macOS node (без SSH).** - Запускайте Gateway на Linux, під’єднайте macOS node (застосунок у menu bar) і встановіть **Node Run Commands** на «Always Ask» або «Always Allow» на Mac. OpenClaw може вважати skills лише для macOS придатними, коли потрібні бінарні файли існують на node. Агент запускає ці skills через інструмент `nodes`. Якщо ви виберете «Always Ask», підтвердження «Always Allow» у запиті додасть цю команду до allowlist. + **Варіант B — використовувати macOS Node (без SSH).** + Запустіть Gateway на Linux, під’єднайте macOS Node (menubar app) і встановіть **Node Run Commands** на «Always Ask» або «Always Allow» на Mac. OpenClaw може вважати навички лише для macOS придатними, коли потрібні бінарники існують на Node. Агент запускає ці навички через інструмент `nodes`. Якщо ви виберете «Always Ask», підтвердження «Always Allow» у запиті додає цю команду до allowlist. - **Варіант C — проксувати бінарні файли macOS через SSH (просунутий).** - Залиште Gateway на Linux, але зробіть так, щоб потрібні CLI-бінарні файли розв’язувалися у SSH-обгортки, які виконуються на Mac. Потім перевизначте skill, щоб дозволити Linux, і він залишався придатним. + **Варіант C — проксувати бінарники macOS через SSH (просунутий).** + Залиште Gateway на Linux, але зробіть так, щоб потрібні CLI-бінарники розв’язувалися у wrapper-и SSH, які запускаються на Mac. Потім перевизначте навичку так, щоб дозволити Linux і вона залишалася придатною. - 1. Створіть SSH-обгортку для бінарного файла (приклад: `memo` для Apple Notes): + 1. Створіть wrapper SSH для бінарника (приклад: `memo` для Apple Notes): ```bash #!/usr/bin/env bash @@ -1208,70 +1208,70 @@ x-i18n: exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@" ``` - 2. Помістіть обгортку в `PATH` на хості Linux (наприклад `~/bin/memo`). - 3. Перевизначте metadata skill (workspace або `~/.openclaw/skills`), щоб дозволити Linux: + 2. Додайте wrapper у `PATH` на хості Linux (наприклад `~/bin/memo`). + 3. Перевизначте метадані навички (workspace або `~/.openclaw/skills`), щоб дозволити Linux: ```markdown --- name: apple-notes - description: Manage Apple Notes via the memo CLI on macOS. + description: Керування Apple Notes через CLI memo на macOS. metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } } --- ``` - 4. Почніть нову сесію, щоб оновився snapshot skills. + 4. Почніть нову сесію, щоб знімок Skills оновився. - - Вбудованої наразі немає. + + Сьогодні вбудованої немає. Варіанти: - - **Власний skill / Plugin:** найкраще для надійного доступу до API (і Notion, і HeyGen мають API). - - **Автоматизація браузера:** працює без коду, але повільніше й менш надійно. + - **Користувацький Skill / Plugin:** найкраще для надійного доступу до API (і Notion, і HeyGen мають API). + - **Автоматизація браузера:** працює без коду, але повільніше й крихкіше. - Якщо ви хочете зберігати контекст окремо для кожного клієнта (процеси агентства), простий шаблон такий: + Якщо ви хочете зберігати контекст для кожного клієнта (агентські робочі процеси), простий шаблон такий: - - Одна сторінка Notion на кожного клієнта (контекст + уподобання + активна робота). + - Одна сторінка Notion на клієнта (контекст + налаштування + активна робота). - Попросіть агента отримувати цю сторінку на початку сесії. - Якщо ви хочете нативну інтеграцію, створіть запит на нову функцію або побудуйте skill, + Якщо вам потрібна нативна інтеграція, створіть feature request або реалізуйте Skill, орієнтований на ці API. - Установлення skills: + Установлення Skills: ```bash openclaw skills install openclaw skills update --all ``` - Нативні встановлення потрапляють у каталог `skills/` активного workspace. Для спільних skills між агентами розміщуйте їх у `~/.openclaw/skills//SKILL.md`. Якщо спільне встановлення мають бачити лише деякі агенти, налаштуйте `agents.defaults.skills` або `agents.list[].skills`. Деякі skills очікують бінарні файли, установлені через Homebrew; на Linux це означає Linuxbrew (дивіться запис FAQ про Homebrew на Linux вище). Дивіться [Skills](/uk/tools/skills), [Конфігурація Skills](/uk/tools/skills-config) і [ClawHub](/uk/tools/clawhub). + Нативні встановлення потрапляють у каталог `skills/` активного workspace. Для спільних Skills між агентами розміщуйте їх у `~/.openclaw/skills//SKILL.md`. Якщо спільне встановлення мають бачити лише деякі агенти, налаштуйте `agents.defaults.skills` або `agents.list[].skills`. Деякі Skills очікують бінарники, встановлені через Homebrew; на Linux це означає Linuxbrew (див. запис FAQ про Homebrew на Linux вище). Див. [Skills](/uk/tools/skills), [Конфігурація Skills](/uk/tools/skills-config) і [ClawHub](/uk/tools/clawhub). - - Використовуйте вбудований профіль browser `user`, який під’єднується через Chrome DevTools MCP: + + Використовуйте вбудований браузерний профіль `user`, який підключається через Chrome DevTools MCP: ```bash openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot ``` - Якщо вам потрібна власна назва, створіть явний профіль MCP: + Якщо вам потрібна власна назва, створіть явний MCP-профіль: ```bash openclaw browser create-profile --name chrome-live --driver existing-session openclaw browser --browser-profile chrome-live tabs ``` - Цей шлях може використовувати локальний browser хоста або під’єднаний browser node. Якщо Gateway працює деінде, або запускайте node host на машині з браузером, або використовуйте віддалений CDP. + Цей шлях може використовувати браузер локального хоста або підключений browser Node. Якщо Gateway працює деінде, або запускайте хост Node на машині з браузером, або використовуйте віддалений CDP. Поточні обмеження для `existing-session` / `user`: - - дії керуються через ref, а не через CSS-селектори + - дії базуються на ref, а не на CSS-селекторах - завантаження файлів вимагає `ref` / `inputRef` і зараз підтримує лише один файл за раз - - `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії все ще вимагають керованого browser або сирого профілю CDP + - `responsebody`, експорт у PDF, перехоплення завантажень і пакетні дії все ще потребують керованого браузера або сирого профілю CDP @@ -1279,61 +1279,61 @@ x-i18n: ## Ізоляція та пам’ять - - Так. Дивіться [Ізоляція](/uk/gateway/sandboxing). Для налаштування, специфічного для Docker (повний gateway у Docker або образи ізоляції), дивіться [Docker](/uk/install/docker). + + Так. Див. [Ізоляція](/uk/gateway/sandboxing). Для налаштування, специфічного для Docker (повний gateway у Docker або образи ізоляції), див. [Docker](/uk/install/docker). - Образ за замовчуванням орієнтований насамперед на безпеку й запускається від користувача `node`, тому він не + Типовий образ орієнтований насамперед на безпеку й працює від імені користувача `node`, тому він не містить системних пакетів, Homebrew або вбудованих браузерів. Для повнішого налаштування: - - Зберігайте `/home/node` через `OPENCLAW_HOME_VOLUME`, щоб кеші не зникали. - - Додавайте системні залежності в образ через `OPENCLAW_DOCKER_APT_PACKAGES`. + - Зберігайте `/home/node` через `OPENCLAW_HOME_VOLUME`, щоб кеші переживали перезапуски. + - Додавайте системні залежності до образу через `OPENCLAW_DOCKER_APT_PACKAGES`. - Установлюйте браузери Playwright через вбудований CLI: `node /app/node_modules/playwright-core/cli.js install chromium` - Установіть `PLAYWRIGHT_BROWSERS_PATH` і переконайтеся, що цей шлях зберігається. - Документація: [Docker](/uk/install/docker), [Browser](/uk/tools/browser). + Документація: [Docker](/uk/install/docker), [Браузер](/uk/tools/browser). - - Так — якщо ваш приватний трафік це **DM**, а публічний трафік — **групи**. + + Так — якщо ваш приватний трафік — це **DM**, а публічний трафік — це **групи**. - Використовуйте `agents.defaults.sandbox.mode: "non-main"`, щоб групові/канальні сесії (ключі non-main) працювали в Docker, а основна DM-сесія залишалася на хості. Потім обмежте, які інструменти доступні в ізольованих сесіях, через `tools.sandbox.tools`. + Використовуйте `agents.defaults.sandbox.mode: "non-main"`, щоб сесії груп/каналів (ключі не-main) працювали у налаштованому backend ізоляції, тоді як основна DM-сесія залишалася на хості. Якщо ви не вибрали backend, Docker буде типовим. Потім обмежте інструменти, доступні в ізольованих сесіях, через `tools.sandbox.tools`. - Покрокове налаштування + приклад конфігурації: [Групи: особисті DM + публічні групи](/uk/channels/groups#pattern-personal-dms-public-groups-single-agent) + Покрокове налаштування + приклад конфігурації: [Групи: приватні DM + публічні групи](/uk/channels/groups#pattern-personal-dms-public-groups-single-agent) - Довідник з ключової конфігурації: [Конфігурація Gateway](/uk/gateway/configuration-reference#agentsdefaultssandbox) + Довідка з ключової конфігурації: [Конфігурація Gateway](/uk/gateway/configuration-reference#agentsdefaultssandbox) - Установіть `agents.defaults.sandbox.docker.binds` у `["host:path:mode"]` (наприклад, `"/home/user/src:/src:ro"`). Глобальні прив’язки й прив’язки на рівні агента об’єднуються; прив’язки на рівні агента ігноруються, коли `scope: "shared"`. Використовуйте `:ro` для будь-чого чутливого й пам’ятайте, що прив’язки обходять файлові стіни ізоляції. + Установіть `agents.defaults.sandbox.docker.binds` у `["host:path:mode"]` (наприклад, `"/home/user/src:/src:ro"`). Глобальні прив’язки та прив’язки для конкретного агента об’єднуються; прив’язки для конкретного агента ігноруються, коли `scope: "shared"`. Використовуйте `:ro` для будь-чого чутливого та пам’ятайте, що прив’язки обходять файлові стіни ізоляції. - OpenClaw перевіряє джерела bind як відносно нормалізованого шляху, так і відносно канонічного шляху, розв’язаного через найглибший наявний предок. Це означає, що виходи за межі через батьківський symlink все одно безпечно блокуються, навіть якщо останній сегмент шляху ще не існує, а перевірки allowed-root також застосовуються після розв’язання symlink. + OpenClaw перевіряє джерела bind і за нормалізованим шляхом, і за канонічним шляхом, розв’язаним через найглибшого наявного предка. Це означає, що виходи через батьківські symlink все одно блокуються за принципом fail closed, навіть коли останній сегмент шляху ще не існує, а перевірки дозволених коренів і далі застосовуються після розв’язання symlink. - Дивіться [Ізоляція](/uk/gateway/sandboxing#custom-bind-mounts) і [Ізоляція vs політика інструментів vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) для прикладів і приміток щодо безпеки. + Приклади та примітки з безпеки див. у [Ізоляція](/uk/gateway/sandboxing#custom-bind-mounts) і [Ізоляція vs політика інструментів vs elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check). - Пам’ять OpenClaw — це просто Markdown-файли у workspace агента: + Пам’ять OpenClaw — це просто Markdown-файли в workspace агента: - Щоденні нотатки в `memory/YYYY-MM-DD.md` - - Кураторські довгострокові нотатки в `MEMORY.md` (лише основні/приватні сесії) + - Відібрані довгострокові нотатки в `MEMORY.md` (лише для main/private sessions) - OpenClaw також виконує **тихий pre-compaction flush пам’яті**, щоб нагадати моделі - записати важливі нотатки перед автоматичною Compaction. Це виконується лише тоді, коли workspace - доступний для запису (ізольовані середовища лише для читання це пропускають). Дивіться [Пам’ять](/uk/concepts/memory). + OpenClaw також виконує **тихий злив пам’яті перед Compaction**, щоб нагадати моделі + записати довговічні нотатки перед автоматичною Compaction. Це виконується лише тоді, коли workspace + доступний для запису (sandbox-и лише для читання пропускають це). Див. [Пам’ять](/uk/concepts/memory). - + Попросіть бота **записати факт у пам’ять**. Довгострокові нотатки мають зберігатися в `MEMORY.md`, короткостроковий контекст — у `memory/YYYY-MM-DD.md`. - Це все ще сфера, яку ми покращуємо. Допомагає нагадувати моделі зберігати спогади; + Це все ще область, яку ми покращуємо. Корисно нагадувати моделі зберігати спогади; вона знатиме, що робити. Якщо вона продовжує забувати, перевірте, що Gateway використовує той самий workspace під час кожного запуску. @@ -1341,9 +1341,9 @@ x-i18n: - - Файли пам’яті живуть на диску й зберігаються, доки ви їх не видалите. Обмеженням є ваше - сховище, а не модель. **Контекст сесії** все одно обмежений вікном контексту + + Файли пам’яті зберігаються на диску й існують, доки ви їх не видалите. Обмеженням є ваш + обсяг сховища, а не модель. **Контекст сесії** все ще обмежений вікном контексту моделі, тому довгі розмови можуть стискатися або обрізатися. Саме тому існує semantic memory search — він повертає в контекст лише релевантні частини. @@ -1351,44 +1351,45 @@ x-i18n: - + Лише якщо ви використовуєте **OpenAI embeddings**. Codex OAuth покриває chat/completions і - **не** надає доступу до embeddings, тому **вхід через Codex (OAuth або - вхід через Codex CLI)** не допомагає для semantic memory search. Для OpenAI embeddings - усе ще потрібен справжній API ключ (`OPENAI_API_KEY` або `models.providers.openai.apiKey`). + **не** надає доступу до embeddings, тож **вхід через Codex (OAuth або + логін Codex CLI)** не допомагає для semantic memory search. Для OpenAI embeddings + як і раніше потрібен справжній API key (`OPENAI_API_KEY` або `models.providers.openai.apiKey`). - Якщо ви явно не вказуєте провайдера, OpenClaw автоматично вибирає провайдера, коли - може розв’язати API ключ (профілі автентифікації, `models.providers.*.apiKey` або env vars). + Якщо ви явно не задаєте провайдера, OpenClaw автоматично вибирає провайдера, коли + може розв’язати API key (профілі автентифікації, `models.providers.*.apiKey` або змінні середовища). Він віддає перевагу OpenAI, якщо розв’язується ключ OpenAI, інакше Gemini, якщо розв’язується ключ Gemini, - потім Voyage, потім Mistral. Якщо віддалений ключ недоступний, memory - search залишається вимкненим, доки ви його не налаштуєте. Якщо у вас налаштовано й наявний шлях до локальної моделі, OpenClaw + потім Voyage, потім Mistral. Якщо жоден віддалений ключ недоступний, memory + search залишається вимкненим, доки ви його не налаштуєте. Якщо у вас налаштований і наявний шлях + до локальної моделі, OpenClaw віддає перевагу `local`. Ollama підтримується, коли ви явно встановлюєте `memorySearch.provider = "ollama"`. - Якщо ви волієте залишатися локально, установіть `memorySearch.provider = "local"` (і за бажанням - `memorySearch.fallback = "none"`). Якщо вам потрібні Gemini embeddings, установіть + Якщо ви волієте залишатися локальними, установіть `memorySearch.provider = "local"` (і за потреби + `memorySearch.fallback = "none"`). Якщо вам потрібні embeddings Gemini, установіть `memorySearch.provider = "gemini"` і надайте `GEMINI_API_KEY` (або - `memorySearch.remote.apiKey`). Ми підтримуємо embedding-моделі **OpenAI, Gemini, Voyage, Mistral, Ollama або local** — - дивіться [Пам’ять](/uk/concepts/memory) для деталей налаштування. + `memorySearch.remote.apiKey`). Ми підтримуємо моделі embeddings **OpenAI, Gemini, Voyage, Mistral, Ollama або local** — + докладні інструкції з налаштування див. у [Пам’ять](/uk/concepts/memory). -## Де все зберігається на диску +## Де що зберігається на диску Ні — **стан OpenClaw локальний**, але **зовнішні сервіси все одно бачать те, що ви їм надсилаєте**. - - **Локально за замовчуванням:** сесії, файли пам’яті, конфігурація й workspace живуть на хості Gateway + - **Локально за замовчуванням:** сесії, файли пам’яті, конфігурація та workspace живуть на хості Gateway (`~/.openclaw` + каталог вашого workspace). - - **Віддалено за необхідністю:** повідомлення, які ви надсилаєте провайдерам моделей (Anthropic/OpenAI тощо), надходять до + - **Віддалено за необхідністю:** повідомлення, які ви надсилаєте провайдерам моделей (Anthropic/OpenAI тощо), ідуть до їхніх API, а чат-платформи (WhatsApp/Telegram/Slack тощо) зберігають дані повідомлень на своїх серверах. - - **Ви контролюєте відбиток:** використання локальних моделей залишає prompt-и на вашій машині, але трафік + - **Ви контролюєте поверхню:** використання локальних моделей зберігає prompt-и на вашій машині, але трафік каналів усе одно проходить через сервери відповідного каналу. - Пов’язане: [Workspace агента](/uk/concepts/agent-workspace), [Пам’ять](/uk/concepts/memory). + Пов’язано: [Workspace агента](/uk/concepts/agent-workspace), [Пам’ять](/uk/concepts/memory). @@ -1398,31 +1399,31 @@ x-i18n: | Path | Призначення | | --------------------------------------------------------------- | ------------------------------------------------------------------ | | `$OPENCLAW_STATE_DIR/openclaw.json` | Основна конфігурація (JSON5) | - | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Імпорт застарілого OAuth (копіюється в профілі автентифікації під час першого використання) | - | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Профілі автентифікації (OAuth, API ключі та необов’язкові `keyRef`/`tokenRef`) | - | `$OPENCLAW_STATE_DIR/secrets.json` | Необов’язкове секретне корисне навантаження на основі файлу для провайдерів `file` SecretRef | - | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Файл застарілої сумісності (статичні записи `api_key` очищаються) | - | `$OPENCLAW_STATE_DIR/credentials/` | Стан провайдера (наприклад `whatsapp//creds.json`) | - | `$OPENCLAW_STATE_DIR/agents/` | Стан для кожного агента окремо (agentDir + sessions) | - | `$OPENCLAW_STATE_DIR/agents//sessions/` | Історія розмов і стан (для кожного агента) | - | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Метадані сесій (для кожного агента) | + | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Застарілий імпорт OAuth (копіюється в профілі автентифікації під час першого використання) | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Профілі автентифікації (OAuth, API keys та необов’язкові `keyRef`/`tokenRef`) | + | `$OPENCLAW_STATE_DIR/secrets.json` | Необов’язкове файлове секретне навантаження для провайдерів SecretRef типу `file` | + | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Файл застарілої сумісності (статичні записи `api_key` очищаються) | + | `$OPENCLAW_STATE_DIR/credentials/` | Стан провайдера (наприклад, `whatsapp//creds.json`) | + | `$OPENCLAW_STATE_DIR/agents/` | Стан для кожного агента (agentDir + sessions) | + | `$OPENCLAW_STATE_DIR/agents//sessions/` | Історія розмов і стан (для кожного агента) | + | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Метадані сесій (для кожного агента) | - Застарілий шлях single-agent: `~/.openclaw/agent/*` (мігрується командою `openclaw doctor`). + Застарілий шлях для одного агента: `~/.openclaw/agent/*` (мігрується через `openclaw doctor`). - Ваш **workspace** (`AGENTS.md`, файли пам’яті, skills тощо) зберігається окремо й налаштовується через `agents.defaults.workspace` (типово: `~/.openclaw/workspace`). + Ваш **workspace** (`AGENTS.md`, файли пам’яті, Skills тощо) відокремлений і налаштовується через `agents.defaults.workspace` (типово: `~/.openclaw/workspace`). - Ці файли зберігаються у **workspace агента**, а не в `~/.openclaw`. + Ці файли мають зберігатися у **workspace агента**, а не в `~/.openclaw`. - - **Workspace (для кожного агента):** `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, - `MEMORY.md` (або застарілий запасний варіант `memory.md`, якщо `MEMORY.md` відсутній), + - **Workspace (для кожного агента)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, + `MEMORY.md` (або застарілий резервний варіант `memory.md`, коли `MEMORY.md` відсутній), `memory/YYYY-MM-DD.md`, необов’язковий `HEARTBEAT.md`. - - **State dir (`~/.openclaw`)**: конфігурація, стан каналу/провайдера, профілі автентифікації, сесії, журнали, - і спільні skills (`~/.openclaw/skills`). + - **State dir (`~/.openclaw`)**: конфігурація, стан каналу/провайдера, профілі автентифікації, сесії, логи + і спільні Skills (`~/.openclaw/skills`). - Workspace за замовчуванням — `~/.openclaw/workspace`, налаштовується через: + Типовий workspace — `~/.openclaw/workspace`, налаштовується через: ```json5 { @@ -1434,38 +1435,38 @@ x-i18n: workspace під час кожного запуску (і пам’ятайте: віддалений режим використовує **workspace хоста gateway**, а не вашого локального ноутбука). - Порада: якщо ви хочете зберегти поведінку або вподобання надовго, попросіть бота **записати це в + Порада: якщо ви хочете зберегти поведінку чи вподобання надовго, попросіть бота **записати це в AGENTS.md або MEMORY.md**, а не покладатися на історію чату. - Дивіться [Workspace агента](/uk/concepts/agent-workspace) і [Пам’ять](/uk/concepts/memory). + Див. [Workspace агента](/uk/concepts/agent-workspace) і [Пам’ять](/uk/concepts/memory). - Зберігайте свій **workspace агента** у **приватному** git-репозиторії й створюйте його резервні копії в - приватному місці (наприклад, у приватному GitHub). Це збереже пам’ять + файли AGENTS/SOUL/USER - і дозволить відновити «розум» помічника пізніше. + Помістіть свій **workspace агента** у **приватний** git-репозиторій і робіть його резервну копію десь + приватно (наприклад, у приватному GitHub). Це збереже пам’ять + файли AGENTS/SOUL/USER + і дасть змогу пізніше відновити «розум» помічника. - **Не** робіть commit нічого з `~/.openclaw` (облікові дані, сесії, токени або зашифровані payload-и секретів). - Якщо вам потрібне повне відновлення, окремо створюйте резервні копії як workspace, так і state directory - (дивіться запитання про міграцію вище). + **Не** комітьте нічого з `~/.openclaw` (облікові дані, сесії, токени або зашифровані секретні payload-и). + Якщо вам потрібно повне відновлення, робіть резервні копії і workspace, і state directory + окремо (див. питання про міграцію вище). Документація: [Workspace агента](/uk/concepts/agent-workspace). - Дивіться окрему інструкцію: [Видалення](/uk/install/uninstall). + Див. окрему інструкцію: [Видалення](/uk/install/uninstall). - Так. Workspace — це **cwd за замовчуванням** і якір пам’яті, а не жорстка ізоляція. - Відносні шляхи розв’язуються всередині workspace, але абсолютні шляхи можуть отримати доступ до інших - розташувань хоста, якщо ізоляцію не ввімкнено. Якщо вам потрібна ізоляція, використовуйте - [`agents.defaults.sandbox`](/uk/gateway/sandboxing) або налаштування ізоляції для окремого агента. Якщо ви - хочете, щоб репозиторій був робочим каталогом за замовчуванням, вкажіть у цього агента + Так. Workspace — це **cwd за замовчуванням** і якір пам’яті, а не жорсткий sandbox. + Відносні шляхи розв’язуються всередині workspace, але абсолютні шляхи можуть звертатися до інших + місць хоста, якщо ізоляцію не ввімкнено. Якщо вам потрібна ізоляція, використовуйте + [`agents.defaults.sandbox`](/uk/gateway/sandboxing) або налаштування sandbox для конкретного агента. Якщо ви + хочете, щоб репозиторій був робочим каталогом за замовчуванням, вкажіть для цього агента `workspace` на корінь репозиторію. Репозиторій OpenClaw — це лише вихідний код; тримайте - workspace окремо, якщо тільки ви свідомо не хочете, щоб агент працював усередині нього. + workspace окремо, якщо тільки ви навмисно не хочете, щоб агент працював усередині нього. Приклад (репозиторій як cwd за замовчуванням): @@ -1481,30 +1482,30 @@ x-i18n: - - Стан сесії належить **хосту gateway**. Якщо ви у віддаленому режимі, потрібне вам сховище сесій знаходиться на віддаленій машині, а не на вашому локальному ноутбуці. Дивіться [Керування сесіями](/uk/concepts/session). + + Стан сесій належить **хосту gateway**. Якщо ви у віддаленому режимі, потрібний вам session store розташований на віддаленій машині, а не на локальному ноутбуці. Див. [Керування сесіями](/uk/concepts/session). ## Основи конфігурації - + OpenClaw читає необов’язкову конфігурацію **JSON5** з `$OPENCLAW_CONFIG_PATH` (типово: `~/.openclaw/openclaw.json`): ``` $OPENCLAW_CONFIG_PATH ``` - Якщо файл відсутній, використовуються достатньо безпечні значення за замовчуванням (зокрема workspace за замовчуванням `~/.openclaw/workspace`). + Якщо файл відсутній, використовуються відносно безпечні значення за замовчуванням (зокрема workspace за замовчуванням `~/.openclaw/workspace`). - Для bind не на loopback **потрібен дійсний шлях автентифікації gateway**. На практиці це означає: + Bind-и не на loopback **вимагають коректного шляху автентифікації gateway**. На практиці це означає: - - автентифікація через shared secret: токен або пароль - - `gateway.auth.mode: "trusted-proxy"` за правильно налаштованим identity-aware reverse proxy не на loopback + - автентифікація спільним секретом: токен або пароль + - `gateway.auth.mode: "trusted-proxy"` за правильно налаштованим reverse proxy з урахуванням ідентичності без loopback ```json5 { @@ -1521,30 +1522,30 @@ x-i18n: Примітки: - `gateway.remote.token` / `.password` самі по собі **не** вмикають локальну автентифікацію gateway. - - Локальні шляхи виклику можуть використовувати `gateway.remote.*` як запасний варіант лише тоді, коли `gateway.auth.*` не задано. - - Для автентифікації паролем натомість установіть `gateway.auth.mode: "password"` разом із `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). - - Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef, але не розв’язано, розв’язання безпечно завершується помилкою (без маскувального запасного варіанта через remote). - - Конфігурації shared-secret для Control UI автентифікуються через `connect.params.auth.token` або `connect.params.auth.password` (зберігаються в налаштуваннях застосунку/UI). Режими з передаванням ідентичності, такі як Tailscale Serve або `trusted-proxy`, замість цього використовують заголовки запитів. Уникайте розміщення shared secrets в URL. - - За `gateway.auth.mode: "trusted-proxy"` reverse proxy на loopback того самого хоста все одно **не** задовольняють автентифікацію trusted-proxy. Trusted proxy має бути налаштованим джерелом не на loopback. + - Локальні шляхи виклику можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не задано. + - Для автентифікації за паролем натомість установіть `gateway.auth.mode: "password"` разом із `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). + - Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не розв’язується, розв’язання завершується fail closed (без маскування резервним remote-варіантом). + - Конфігурації Control UI зі спільним секретом автентифікуються через `connect.params.auth.token` або `connect.params.auth.password` (зберігаються в налаштуваннях app/UI). Режими з ідентичністю, як-от Tailscale Serve або `trusted-proxy`, натомість використовують заголовки запитів. Уникайте розміщення спільних секретів в URL. + - З `gateway.auth.mode: "trusted-proxy"` reverse proxy loopback на тому самому хості все одно **не** задовольняють автентифікацію trusted-proxy. Trusted proxy має бути налаштованим джерелом без loopback. - - OpenClaw за замовчуванням примусово застосовує автентифікацію gateway, зокрема і на loopback. У звичайному шляху за замовчуванням це означає автентифікацію токеном: якщо явний шлях автентифікації не налаштовано, під час запуску gateway вибирається режим токена і автоматично генерується токен, який зберігається в `gateway.auth.token`, тому **локальні WS-клієнти мають автентифікуватися**. Це блокує іншим локальним процесам можливість викликати Gateway. + + OpenClaw типово примусово вимагає автентифікацію gateway, зокрема й для loopback. У звичайному типовому сценарії це означає автентифікацію токеном: якщо явний шлях автентифікації не налаштовано, під час запуску gateway визначається режим токена і токен генерується автоматично, зберігаючись у `gateway.auth.token`, тож **локальні WS-клієнти мають проходити автентифікацію**. Це блокує іншим локальним процесам виклики до Gateway. - Якщо ви віддаєте перевагу іншому шляху автентифікації, можете явно вибрати режим пароля (або, для identity-aware reverse proxy не на loopback, `trusted-proxy`). Якщо ви **справді** хочете відкритий loopback, явно встановіть `gateway.auth.mode: "none"` у конфігурації. Doctor може згенерувати токен для вас у будь-який момент: `openclaw doctor --generate-gateway-token`. + Якщо ви віддаєте перевагу іншому шляху автентифікації, можете явно вибрати режим пароля (або, для reverse proxy без loopback з урахуванням ідентичності, `trusted-proxy`). Якщо ви **справді** хочете відкритий loopback, явно встановіть у конфігурації `gateway.auth.mode: "none"`. Doctor може згенерувати токен у будь-який час: `openclaw doctor --generate-gateway-token`. - Gateway стежить за конфігурацією і підтримує гаряче перезавантаження: + Gateway стежить за конфігурацією і підтримує hot reload: - - `gateway.reload.mode: "hybrid"` (типово): гаряче застосовує безпечні зміни, перезапускає для критичних + - `gateway.reload.mode: "hybrid"` (типово): безпечно застосовує зміни на гарячу, для критичних робить перезапуск - також підтримуються `hot`, `restart`, `off` - + Установіть `cli.banner.taglineMode` у конфігурації: ```json5 @@ -1559,21 +1560,21 @@ x-i18n: - `off`: приховує текст слогана, але залишає рядок заголовка/версії банера. - `default`: щоразу використовує `All your chats, one OpenClaw.`. - - `random`: ротація кумедних/сезонних слоганів (типова поведінка). - - Якщо ви взагалі не хочете банер, установіть env `OPENCLAW_HIDE_BANNER=1`. + - `random`: ротаційні кумедні/сезонні слогани (поведінка за замовчуванням). + - Якщо ви взагалі не хочете банер, установіть змінну середовища `OPENCLAW_HIDE_BANNER=1`. - - `web_fetch` працює без API ключа. `web_search` залежить від вибраного + + `web_fetch` працює без API key. `web_search` залежить від вибраного провайдера: - - Провайдери на основі API, такі як Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity і Tavily, потребують звичайного налаштування API ключів. - - Ollama Web Search не потребує ключа, але використовує налаштований вами хост Ollama і вимагає `ollama signin`. + - Провайдери на основі API, як-от Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity і Tavily, потребують звичайного налаштування API key. + - Ollama Web Search не потребує ключа, але використовує налаштований хост Ollama і вимагає `ollama signin`. - DuckDuckGo не потребує ключа, але це неофіційна інтеграція на основі HTML. - - SearXNG не потребує ключа / self-hosted; налаштуйте `SEARXNG_BASE_URL` або `plugins.entries.searxng.config.webSearch.baseUrl`. + - SearXNG не потребує ключа/може бути self-hosted; налаштуйте `SEARXNG_BASE_URL` або `plugins.entries.searxng.config.webSearch.baseUrl`. - **Рекомендовано:** виконайте `openclaw configure --section web` і виберіть провайдера. + **Рекомендовано:** запустіть `openclaw configure --section web` і виберіть провайдера. Альтернативи через змінні середовища: - Brave: `BRAVE_API_KEY` @@ -1609,76 +1610,76 @@ x-i18n: }, fetch: { enabled: true, - provider: "firecrawl", // необов’язково; пропустіть для auto-detect + provider: "firecrawl", // optional; omit for auto-detect }, }, }, } ``` - Специфічна для провайдера конфігурація вебпошуку тепер знаходиться в `plugins.entries..config.webSearch.*`. - Застарілі шляхи провайдера `tools.web.search.*` усе ще тимчасово завантажуються для сумісності, але їх не слід використовувати для нових конфігурацій. - Конфігурація запасного варіанта web-fetch для Firecrawl знаходиться в `plugins.entries.firecrawl.config.webFetch.*`. + Специфічна для провайдера конфігурація web search тепер живе під `plugins.entries..config.webSearch.*`. + Застарілі шляхи провайдера `tools.web.search.*` ще тимчасово завантажуються для сумісності, але не повинні використовуватися в нових конфігураціях. + Конфігурація резервного web fetch для Firecrawl живе під `plugins.entries.firecrawl.config.webFetch.*`. Примітки: - - Якщо ви використовуєте allowlist, додайте `web_search`/`web_fetch`/`x_search` або `group:web`. - - `web_fetch` увімкнено за замовчуванням (якщо його явно не вимкнено). - - Якщо `tools.web.fetch.provider` пропущено, OpenClaw автоматично виявляє першого готового резервного провайдера fetch із доступних облікових даних. Наразі bundled провайдер — це Firecrawl. - - Демони читають env vars із `~/.openclaw/.env` (або середовища сервісу). + - Якщо ви використовуєте allowlist-и, додайте `web_search`/`web_fetch`/`x_search` або `group:web`. + - `web_fetch` типово увімкнено (якщо його явно не вимкнено). + - Якщо `tools.web.fetch.provider` не вказано, OpenClaw автоматично визначає першого готового резервного fetch-провайдера серед доступних облікових даних. Наразі вбудований провайдер — Firecrawl. + - Демони читають змінні середовища з `~/.openclaw/.env` (або із середовища сервісу). Документація: [Веб-інструменти](/uk/tools/web). - - `config.apply` замінює **всю конфігурацію повністю**. Якщо ви надсилаєте частковий об’єкт, усе - інше видаляється. + + `config.apply` замінює **всю конфігурацію**. Якщо ви надсилаєте частковий об’єкт, усе + інше буде видалено. - Поточний OpenClaw захищає від багатьох випадкових перезаписів: + Поточний OpenClaw захищає від багатьох випадкових затирань: - Записи конфігурації, якими керує OpenClaw, перевіряють повну конфігурацію після зміни перед записом. - Некоректні або руйнівні записи, якими керує OpenClaw, відхиляються і зберігаються як `openclaw.json.rejected.*`. - - Якщо пряме редагування ламає запуск або гаряче перезавантаження, Gateway відновлює останню відому робочу конфігурацію і зберігає відхилений файл як `openclaw.json.clobbered.*`. - - Після відновлення основний агент отримує попередження під час запуску, щоб він не записав сліпо погану конфігурацію знову. + - Якщо пряме редагування ламає запуск або hot reload, Gateway відновлює останню відому робочу конфігурацію і зберігає відхилений файл як `openclaw.json.clobbered.*`. + - Після відновлення головний агент отримує попередження під час запуску, щоб не записати погану конфігурацію знову навмання. Відновлення: - Перевірте `openclaw logs --follow` на наявність `Config auto-restored from last-known-good`, `Config write rejected:` або `config reload restored last-known-good config`. - Перегляньте найновіший `openclaw.json.clobbered.*` або `openclaw.json.rejected.*` поруч з активною конфігурацією. - - Залиште активну відновлену конфігурацію, якщо вона працює, а потім поверніть лише потрібні ключі через `openclaw config set` або `config.patch`. - - Виконайте `openclaw config validate` і `openclaw doctor`. - - Якщо у вас немає останньої відомої робочої конфігурації або відхиленого payload, відновіть із резервної копії або повторно виконайте `openclaw doctor` і заново налаштуйте канали/моделі. - - Якщо це було неочікувано, створіть bug і додайте останню відому конфігурацію або будь-яку резервну копію. - - Локальний coding agent часто може відновити робочу конфігурацію з журналів або історії. + - Якщо відновлена активна конфігурація працює, залиште її, а потім поверніть лише потрібні ключі через `openclaw config set` або `config.patch`. + - Запустіть `openclaw config validate` і `openclaw doctor`. + - Якщо у вас немає ані останньої відомої робочої конфігурації, ані відхиленого payload, відновіть із резервної копії або знову запустіть `openclaw doctor` і повторно налаштуйте канали/моделі. + - Якщо це було неочікувано, створіть bug report і додайте свою останню відому конфігурацію або будь-яку резервну копію. + - Локальний coding agent часто може відновити працездатну конфігурацію з логів або історії. - Як уникнути цього: + Як уникнути: - Використовуйте `openclaw config set` для невеликих змін. - Використовуйте `openclaw configure` для інтерактивного редагування. - - Спочатку використовуйте `config.schema.lookup`, коли ви не впевнені щодо точного шляху або форми поля; воно повертає неглибокий вузол схеми плюс підсумки безпосередніх дочірніх елементів для покрокового заглиблення. + - Спочатку використовуйте `config.schema.lookup`, коли ви не впевнені в точному шляху чи формі поля; він повертає поверхневий вузол схеми плюс зведення безпосередніх дочірніх елементів для подальшого заглиблення. - Використовуйте `config.patch` для часткових RPC-редагувань; залишайте `config.apply` лише для повної заміни конфігурації. - - Якщо ви використовуєте інструмент `gateway` лише для owner з запуску агента, він усе одно відхилятиме записи в `tools.exec.ask` / `tools.exec.security` (включно із застарілими псевдонімами `tools.bash.*`, які нормалізуються до тих самих захищених шляхів exec). + - Якщо ви використовуєте доступний лише власнику інструмент `gateway` із запуску агента, він усе одно відхилятиме записи до `tools.exec.ask` / `tools.exec.security` (включно із застарілими псевдонімами `tools.bash.*`, які нормалізуються до тих самих захищених шляхів exec). Документація: [Конфігурація](/cli/config), [Налаштування](/cli/configure), [Усунення несправностей Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config), [Doctor](/uk/gateway/doctor). - - Типовий шаблон — **один Gateway** (наприклад Raspberry Pi) плюс **nodes** і **agents**: + + Поширений шаблон — **один Gateway** (наприклад, Raspberry Pi) плюс **nodes** і **agents**: - **Gateway (центральний):** володіє каналами (Signal/WhatsApp), маршрутизацією та сесіями. - - **Nodes (пристрої):** Mac/iOS/Android під’єднуються як периферія і надають локальні інструменти (`system.run`, `canvas`, `camera`). - - **Agents (workers):** окремі «мізки»/workspace для спеціальних ролей (наприклад, «Hetzner ops», «Особисті дані»). - - **Sub-agents:** запускають фонову роботу з основного агента, коли вам потрібен паралелізм. - - **TUI:** під’єднується до Gateway і перемикає agents/sessions. + - **Nodes (пристрої):** Mac/iOS/Android підключаються як периферія і надають локальні інструменти (`system.run`, `canvas`, `camera`). + - **Agents (воркери):** окремі «мізки»/workspace для спеціальних ролей (наприклад, «Hetzner ops», «Personal data»). + - **Субагенти:** запускають фонову роботу з головного агента, коли вам потрібен паралелізм. + - **TUI:** підключайтеся до Gateway і перемикайте агентів/сесії. - Документація: [Nodes](/uk/nodes), [Віддалений доступ](/uk/gateway/remote), [Маршрутизація Multi-Agent](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [TUI](/web/tui). + Документація: [Nodes](/uk/nodes), [Віддалений доступ](/uk/gateway/remote), [Маршрутизація кількох агентів](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [TUI](/web/tui). - - Так. Це параметр конфігурації: + + Так. Це опція конфігурації: ```json5 { @@ -1691,63 +1692,63 @@ x-i18n: } ``` - Типове значення — `false` (з видимим вікном). Headless-режим частіше викликає перевірки anti-bot на деяких сайтах. Дивіться [Browser](/uk/tools/browser). + Типове значення — `false` (headful). Headless з більшою ймовірністю запускає anti-bot перевірки на деяких сайтах. Див. [Браузер](/uk/tools/browser). - Headless використовує **той самий рушій Chromium** і працює для більшості автоматизацій (форми, кліки, scraping, входи). Основні відмінності: + Headless використовує **той самий рушій Chromium** і працює для більшості сценаріїв автоматизації (форми, кліки, скрейпінг, логіни). Основні відмінності: - - Немає видимого вікна browser (використовуйте скриншоти, якщо вам потрібна візуалізація). + - Немає видимого вікна браузера (використовуйте знімки екрана, якщо вам потрібна візуалізація). - Деякі сайти суворіше ставляться до автоматизації в headless-режимі (CAPTCHA, anti-bot). Наприклад, X/Twitter часто блокує headless-сесії. - - Установіть `browser.executablePath` на ваш бінарний файл Brave (або будь-який browser на основі Chromium) і перезапустіть Gateway. - Дивіться повні приклади конфігурації в [Browser](/uk/tools/browser#use-brave-or-another-chromium-based-browser). + + Установіть `browser.executablePath` на свій бінарник Brave (або будь-який інший браузер на основі Chromium) і перезапустіть Gateway. + Повні приклади конфігурації див. у [Браузер](/uk/tools/browser#use-brave-or-another-chromium-based-browser). ## Віддалені gateway і nodes - + Повідомлення Telegram обробляються **gateway**. Gateway запускає агента і - лише потім викликає nodes через **WebSocket Gateway**, коли потрібен інструмент node: + лише потім викликає nodes через **Gateway WebSocket**, коли потрібен інструмент node: Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram - Nodes не бачать вхідного трафіку провайдера; вони отримують лише виклики RPC node. + Nodes не бачать вхідний трафік провайдера; вони отримують лише RPC-виклики node. - - Коротка відповідь: **під’єднайте свій комп’ютер як node**. Gateway працює деінде, але може - викликати інструменти `node.*` (екран, камера, система) на вашій локальній машині через WebSocket Gateway. + + Коротка відповідь: **під’єднайте свій комп’ютер як Node**. Gateway працює деінде, але він може + викликати інструменти `node.*` (екран, камера, система) на вашій локальній машині через Gateway WebSocket. Типове налаштування: - 1. Запустіть Gateway на хості, який завжди увімкнений (VPS/домашній сервер). - 2. Помістіть хост Gateway і свій комп’ютер в одну й ту саму tailnet. - 3. Переконайтеся, що WS Gateway доступний (tailnet bind або SSH-тунель). - 4. Локально відкрийте застосунок macOS і під’єднайтеся в режимі **Remote over SSH** (або напряму через tailnet), - щоб він міг зареєструватися як node. - 5. Погодьте node на Gateway: + 1. Запустіть Gateway на хості, що завжди ввімкнений (VPS/домашній сервер). + 2. Додайте хост Gateway + свій комп’ютер до однієї tailnet. + 3. Переконайтеся, що Gateway WS доступний (bind до tailnet або SSH-тунель). + 4. Відкрийте застосунок macOS локально і підключіться в режимі **Remote over SSH** (або напряму через tailnet), + щоб він міг зареєструватися як Node. + 5. Схваліть Node на Gateway: ```bash openclaw devices list openclaw devices approve ``` - Окремий TCP-міст не потрібен; nodes під’єднуються через WebSocket Gateway. + Окремий TCP-міст не потрібен; nodes підключаються через Gateway WebSocket. - Нагадування про безпеку: під’єднання macOS node дозволяє `system.run` на цій машині. Під’єднуйте - лише ті пристрої, яким довіряєте, і перегляньте [Безпека](/uk/gateway/security). + Нагадування про безпеку: спарювання macOS Node дозволяє `system.run` на цій машині. Під’єднуйте + лише пристрої, яким довіряєте, і перечитайте [Безпека](/uk/gateway/security). Документація: [Nodes](/uk/nodes), [Протокол Gateway](/uk/gateway/protocol), [Віддалений режим macOS](/uk/platforms/mac/remote), [Безпека](/uk/gateway/security). - + Перевірте основи: - Gateway працює: `openclaw gateway status` @@ -1757,70 +1758,71 @@ x-i18n: Потім перевірте автентифікацію та маршрутизацію: - Якщо ви використовуєте Tailscale Serve, переконайтеся, що `gateway.auth.allowTailscale` налаштовано правильно. - - Якщо ви під’єднуєтеся через SSH-тунель, переконайтеся, що локальний тунель активний і вказує на правильний порт. - - Переконайтеся, що ваші allowlist-и (DM або група) включають ваш обліковий запис. + - Якщо ви підключаєтеся через SSH-тунель, переконайтеся, що локальний тунель активний і вказує на правильний порт. + - Переконайтеся, що ваші allowlist-и (DM або група) містять ваш обліковий запис. Документація: [Tailscale](/uk/gateway/tailscale), [Віддалений доступ](/uk/gateway/remote), [Канали](/uk/channels). - - Так. Вбудованого мосту «бот-до-бота» немає, але це можна налаштувати кількома + + Так. Вбудованого мосту «бот-до-бота» немає, але це можна організувати кількома надійними способами: - **Найпростіше:** використовуйте звичайний чат-канал, до якого мають доступ обидва боти (Telegram/Slack/WhatsApp). - Нехай бот A надсилає повідомлення боту B, а потім бот B відповідає як зазвичай. + **Найпростіше:** використовуйте звичайний канал чату, до якого мають доступ обидва боти (Telegram/Slack/WhatsApp). + Нехай Bot A надсилає повідомлення Bot B, а потім Bot B відповідає як зазвичай. - **CLI-міст (загальний):** запустіть скрипт, який викликає інший Gateway через - `openclaw agent --message ... --deliver`, націлюючись на чат, де слухає інший бот. - Якщо один бот працює на віддаленому VPS, націльте свій CLI на той віддалений Gateway - через SSH/Tailscale (дивіться [Віддалений доступ](/uk/gateway/remote)). + **Міст через CLI (загальний):** запустіть скрипт, який викликає інший Gateway через + `openclaw agent --message ... --deliver`, націливши на чат, де слухає інший бот. + Якщо один бот працює на віддаленому VPS, спрямуйте свій CLI на цей віддалений Gateway + через SSH/Tailscale (див. [Віддалений доступ](/uk/gateway/remote)). - Приклад шаблону (запускається на машині, яка може досягти цільового Gateway): + Приклад шаблону (запускається з машини, яка може дістатися цільового Gateway): ```bash openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` - Порада: додайте запобіжник, щоб два боти не зациклилися без кінця (відповіді лише на згадки, allowlist-и каналів або правило «не відповідати на повідомлення ботів»). + Порада: додайте захисне правило, щоб два боти не зациклитися безкінечно (лише згадки, channel + allowlist-и або правило «не відповідати на повідомлення ботів»). - Документація: [Віддалений доступ](/uk/gateway/remote), [CLI агента](/cli/agent), [Надсилання агентом](/uk/tools/agent-send). + Документація: [Віддалений доступ](/uk/gateway/remote), [CLI Agent](/cli/agent), [Надсилання Agent](/uk/tools/agent-send). - Ні. Один Gateway може хостити кількох агентів, кожен зі своїм workspace, моделями за замовчуванням - та маршрутизацією. Це нормальне налаштування, і воно набагато дешевше й простіше, ніж запускати - окремий VPS для кожного агента. + Ні. Один Gateway може хостити кількох агентів, кожен зі своїм workspace, типовими моделями + і маршрутизацією. Це звичайне налаштування, і воно набагато дешевше й простіше, ніж запускати + один VPS на агента. Використовуйте окремі VPS лише тоді, коли вам потрібна жорстка ізоляція (межі безпеки) або дуже - різні конфігурації, якими ви не хочете ділитися. В іншому випадку тримайте один Gateway і - використовуйте кількох агентів або sub-agents. + різні конфігурації, які ви не хочете спільно використовувати. В іншому разі залишайте один Gateway і + використовуйте кількох агентів або субагентів. - - Так — nodes є основним способом доступу до вашого ноутбука з віддаленого Gateway, і вони + + Так — nodes є першокласним способом доступу до вашого ноутбука з віддаленого Gateway, і вони дають більше, ніж просто доступ до оболонки. Gateway працює на macOS/Linux (Windows через WSL2) і є - легким (достатньо невеликого VPS або пристрою класу Raspberry Pi; 4 ГБ RAM більш ніж достатньо), тому поширений - сценарій — це завжди увімкнений хост плюс ваш ноутбук як node. + легким (достатньо невеликого VPS або пристрою класу Raspberry Pi; 4 ГБ RAM більш ніж достатньо), тож поширена + конфігурація — це постійно ввімкнений хост плюс ваш ноутбук як Node. - - **Не потрібен вхідний SSH.** Nodes самі підключаються до WebSocket Gateway і використовують парування пристроїв. - - **Безпечніший контроль виконання.** `system.run` обмежується allowlist-ами/погодженнями node на цьому ноутбуці. + - **Не потрібен вхідний SSH.** Nodes самі підключаються до Gateway WebSocket і використовують спарювання пристроїв. + - **Безпечніший контроль виконання.** `system.run` на цьому ноутбуці обмежується allowlist-ами/підтвердженнями Node. - **Більше інструментів пристрою.** Nodes надають `canvas`, `camera` і `screen` на додачу до `system.run`. - - **Локальна автоматизація браузера.** Тримайте Gateway на VPS, але запускайте Chrome локально через node host на ноутбуці або під’єднуйтеся до локального Chrome на хості через Chrome MCP. + - **Локальна автоматизація браузера.** Тримайте Gateway на VPS, але запускайте Chrome локально через хост Node на ноутбуці або підключайтеся до локального Chrome на хості через Chrome MCP. - SSH підходить для епізодичного доступу до оболонки, але nodes простіші для постійних агентних процесів і - автоматизації пристроїв. + SSH підходить для епізодичного доступу до оболонки, але nodes простіші для постійних агентських робочих процесів і + автоматизації пристрою. - Документація: [Nodes](/uk/nodes), [CLI Nodes](/cli/nodes), [Browser](/uk/tools/browser). + Документація: [Nodes](/uk/nodes), [CLI Nodes](/cli/nodes), [Браузер](/uk/tools/browser). - Ні. На хості має працювати лише **один gateway**, якщо тільки ви навмисно не запускаєте ізольовані профілі (дивіться [Кілька gateway](/uk/gateway/multiple-gateways)). Nodes — це периферійні елементи, які підключаються - до gateway (nodes iOS/Android або macOS «node mode» у застосунку menu bar). Для headless node - host і керування через CLI дивіться [CLI Node host](/cli/node). + Ні. На одному хості має працювати лише **один gateway**, якщо тільки ви навмисно не запускаєте ізольовані профілі (див. [Кілька gateway](/uk/gateway/multiple-gateways)). Nodes — це периферійні пристрої, які підключаються + до gateway (nodes iOS/Android або «режим node» macOS у menubar app). Для headless-хостів node + і керування через CLI див. [CLI хоста Node](/cli/node). Повний перезапуск потрібен для змін `gateway`, `discovery` і `canvasHost`. @@ -1829,11 +1831,11 @@ x-i18n: Так. - - `config.schema.lookup`: перевірити одне піддерево конфігурації з його неглибоким вузлом схеми, відповідною UI-підказкою і підсумками безпосередніх дочірніх елементів перед записом - - `config.get`: отримати поточний snapshot + hash - - `config.patch`: безпечне часткове оновлення (переважний варіант для більшості RPC-редагувань); за можливості виконує гаряче перезавантаження, а за потреби — перезапуск - - `config.apply`: перевірити й замінити всю конфігурацію; за можливості виконує гаряче перезавантаження, а за потреби — перезапуск - - Інструмент runtime `gateway`, доступний лише owner, як і раніше відмовляється переписувати `tools.exec.ask` / `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec + - `config.schema.lookup`: переглянути одне піддерево конфігурації з його поверхневим вузлом схеми, підібраною UI-підказкою та зведеннями безпосередніх дочірніх елементів перед записом + - `config.get`: отримати поточний знімок + хеш + - `config.patch`: безпечне часткове оновлення (рекомендовано для більшості RPC-редагувань); виконує hot reload, коли це можливо, і перезапускає, коли потрібно + - `config.apply`: перевірити й замінити повну конфігурацію; виконує hot reload, коли це можливо, і перезапускає, коли потрібно + - Доступний лише власнику runtime-інструмент `gateway` усе ще відмовляється переписувати `tools.exec.ask` / `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec @@ -1845,7 +1847,7 @@ x-i18n: } ``` - Це задає ваш workspace і обмежує, хто може активувати бота. + Це задає ваш workspace і обмежує, хто може запускати бота. @@ -1859,10 +1861,10 @@ x-i18n: sudo tailscale up ``` - 2. **Установіть + увійдіть на вашому Mac** - - Використайте застосунок Tailscale і увійдіть у ту саму tailnet. + 2. **Установіть + увійдіть на Mac** + - Використайте застосунок Tailscale і ввійдіть у ту саму tailnet. 3. **Увімкніть MagicDNS (рекомендовано)** - - У консолі адміністрування Tailscale увімкніть MagicDNS, щоб VPS мав стабільне ім’я. + - У консолі адміністратора Tailscale увімкніть MagicDNS, щоб VPS мав стабільне ім’я. 4. **Використовуйте ім’я хоста tailnet** - SSH: `ssh user@your-vps.tailnet-xxxx.ts.net` - Gateway WS: `ws://your-vps.tailnet-xxxx.ts.net:18789` @@ -1873,19 +1875,19 @@ x-i18n: openclaw gateway --tailscale serve ``` - Це залишає gateway прив’язаним до loopback і відкриває HTTPS через Tailscale. Дивіться [Tailscale](/uk/gateway/tailscale). + Це залишає gateway прив’язаним до loopback і відкриває HTTPS через Tailscale. Див. [Tailscale](/uk/gateway/tailscale). - - Serve відкриває **Control UI Gateway + WS**. Nodes підключаються через той самий endpoint Gateway WS. + + Serve відкриває **Gateway Control UI + WS**. Nodes підключаються через той самий endpoint Gateway WS. - Рекомендоване налаштування: + Рекомендована конфігурація: 1. **Переконайтеся, що VPS і Mac знаходяться в одній tailnet**. - 2. **Використовуйте застосунок macOS у режимі Remote** (ціллю SSH може бути ім’я хоста tailnet). - Застосунок протунелює порт Gateway і підключиться як node. - 3. **Погодьте node** на gateway: + 2. **Використовуйте застосунок macOS у віддаленому режимі** (ціллю SSH може бути ім’я хоста tailnet). + Застосунок протунелює порт Gateway і підключиться як Node. + 3. **Схваліть Node** на gateway: ```bash openclaw devices list @@ -1896,9 +1898,9 @@ x-i18n: - - Якщо вам потрібні лише **локальні інструменти** (screen/camera/exec) на другому ноутбуці, додайте його як - **node**. Це дозволяє зберегти один Gateway і уникнути дублювання конфігурації. Локальні інструменти node + + Якщо вам потрібні лише **локальні інструменти** (`screen`/`camera`/`exec`) на другому ноутбуці, додайте його як + **Node**. Це зберігає єдиний Gateway і дозволяє уникнути дублювання конфігурації. Локальні інструменти Node наразі доступні лише на macOS, але ми плануємо поширити їх і на інші ОС. Установлюйте другий Gateway лише тоді, коли вам потрібна **жорстка ізоляція** або два повністю окремі боти. @@ -1908,18 +1910,18 @@ x-i18n: -## Env vars і завантаження .env +## Змінні середовища та завантаження .env - OpenClaw читає env vars із батьківського процесу (shell, launchd/systemd, CI тощо) і додатково завантажує: + OpenClaw читає змінні середовища з батьківського процесу (shell, launchd/systemd, CI тощо) і додатково завантажує: - `.env` з поточного робочого каталогу - - глобальний запасний `.env` з `~/.openclaw/.env` (тобто `$OPENCLAW_STATE_DIR/.env`) + - глобальний резервний `.env` з `~/.openclaw/.env` (тобто `$OPENCLAW_STATE_DIR/.env`) - Жоден файл `.env` не перевизначає вже наявні env vars. + Жоден із `.env`-файлів не перевизначає вже наявні змінні середовища. - Ви також можете визначити inline env vars у конфігурації (застосовуються лише якщо вони відсутні в env процесу): + Ви також можете визначати вбудовані змінні середовища в конфігурації (застосовуються лише якщо вони відсутні в process env): ```json5 { @@ -1930,15 +1932,15 @@ x-i18n: } ``` - Дивіться [/environment](/uk/help/environment) для повного порядку пріоритетів і джерел. + Повний пріоритет і джерела див. у [/environment](/uk/help/environment). - - Два поширені виправлення: + + Є два поширені виправлення: - 1. Помістіть відсутні ключі в `~/.openclaw/.env`, щоб вони підхоплювалися, навіть коли сервіс не успадковує env вашої shell. - 2. Увімкніть імпорт shell (opt-in convenience): + 1. Помістіть відсутні ключі в `~/.openclaw/.env`, щоб вони підхоплювалися, навіть коли сервіс не успадковує env вашого shell. + 2. Увімкніть імпорт shell (опціональна зручність): ```json5 { @@ -1951,18 +1953,18 @@ x-i18n: } ``` - Це запускає вашу login shell і імпортує лише відсутні очікувані ключі (ніколи нічого не перевизначає). Еквіваленти env vars: + Це запускає ваш login shell та імпортує лише відсутні очікувані ключі (ніколи не перевизначає). Еквіваленти змінних середовища: `OPENCLAW_LOAD_SHELL_ENV=1`, `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`. - `openclaw models status` показує, чи ввімкнено **імпорт env із shell**. "Shell env: off" - **не** означає, що ваших env vars немає — це лише означає, що OpenClaw не завантажуватиме - вашу login shell автоматично. + `openclaw models status` повідомляє, чи увімкнено **імпорт shell env**. «Shell env: off» + **не** означає, що ваших змінних середовища немає — це лише означає, що OpenClaw не завантажуватиме + ваш login shell автоматично. Якщо Gateway працює як сервіс (launchd/systemd), він не успадковує середовище - вашої shell. Виправте це одним із таких способів: + вашого shell. Виправити це можна одним зі способів: 1. Помістіть токен у `~/.openclaw/.env`: @@ -1970,17 +1972,17 @@ x-i18n: COPILOT_GITHUB_TOKEN=... ``` - 2. Або ввімкніть імпорт shell (`env.shellEnv.enabled: true`). - 3. Або додайте його в блок `env` у конфігурації (застосовується лише якщо відсутній). + 2. Або увімкніть імпорт shell (`env.shellEnv.enabled: true`). + 3. Або додайте його в блок `env` конфігурації (застосовується лише якщо відсутній). - Потім перезапустіть gateway і перевірте знову: + Потім перезапустіть gateway і перевірте ще раз: ```bash openclaw models status ``` Токени Copilot читаються з `COPILOT_GITHUB_TOKEN` (також `GH_TOKEN` / `GITHUB_TOKEN`). - Дивіться [/concepts/model-providers](/uk/concepts/model-providers) і [/environment](/uk/help/environment). + Див. [/concepts/model-providers](/uk/concepts/model-providers) і [/environment](/uk/help/environment). @@ -1989,14 +1991,14 @@ x-i18n: - Надішліть `/new` або `/reset` як окреме повідомлення. Дивіться [Керування сесіями](/uk/concepts/session). + Надішліть `/new` або `/reset` окремим повідомленням. Див. [Керування сесіями](/uk/concepts/session). - - Термін дії сесій може завершуватися після `session.idleMinutes`, але це **вимкнено за замовчуванням** (типове значення **0**). - Установіть додатне значення, щоб увімкнути завершення через неактивність. Коли це ввімкнено, **наступне** - повідомлення після періоду неактивності запускає новий session id для цього ключа чату. - Це не видаляє transcript-и — лише починає нову сесію. + + Термін дії сесій може завершуватися після `session.idleMinutes`, але це **типово вимкнено** (типове значення **0**). + Установіть додатне значення, щоб увімкнути завершення після простою. Коли це ввімкнено, **наступне** + повідомлення після періоду простою починає новий ID сесії для цього ключа чату. + Це не видаляє транскрипти — це лише починає нову сесію. ```json5 { @@ -2008,35 +2010,35 @@ x-i18n: - - Так, через **маршрутизацію multi-agent** і **sub-agents**. Ви можете створити одного координуючого - агента і кількох робочих агентів зі своїми workspace та моделями. + + Так, через **маршрутизацію кількох агентів** і **субагентів**. Ви можете створити одного координувального + агента і кількох робочих агентів із власними workspace та моделями. - Втім, найкраще сприймати це як **цікавий експеримент**. Це потребує багато токенів і часто - менш ефективно, ніж використання одного бота з окремими сесіями. Типова модель, яку - ми уявляємо, — це один бот, з яким ви спілкуєтеся, з різними сесіями для паралельної роботи. Цей - бот також може за потреби запускати sub-agents. + Втім, на це краще дивитися як на **цікавий експеримент**. Це витрачає багато токенів і часто + менш ефективно, ніж використання одного бота з окремими сесіями. Типова модель, яку ми + уявляємо, — один бот, з яким ви спілкуєтеся, з різними сесіями для паралельної роботи. Цей + бот також може запускати субагентів, коли це потрібно. - Документація: [Маршрутизація Multi-Agent](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [CLI Agents](/cli/agents). + Документація: [Маршрутизація кількох агентів](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [CLI Agents](/cli/agents). - + Контекст сесії обмежений вікном моделі. Довгі чати, великі виводи інструментів або багато - файлів можуть викликати Compaction або обрізання. + файлів можуть викликати compaction або обрізання. Що допомагає: - Попросіть бота підсумувати поточний стан і записати його у файл. - - Використовуйте `/compact` перед довгими завданнями, а `/new` — коли змінюєте тему. - - Зберігайте важливий контекст у workspace і просіть бота зчитати його назад. - - Використовуйте sub-agents для довгої або паралельної роботи, щоб основний чат залишався меншим. - - Виберіть модель з більшим вікном контексту, якщо це трапляється часто. + - Використовуйте `/compact` перед довгими завданнями, а `/new` — під час зміни тем. + - Тримайте важливий контекст у workspace і просіть бота перечитати його. + - Використовуйте субагентів для довгих або паралельних завдань, щоб основний чат залишався меншим. + - Виберіть модель із більшим вікном контексту, якщо це трапляється часто. - - Використовуйте команду reset: + + Використовуйте команду скидання: ```bash openclaw reset @@ -2048,7 +2050,7 @@ x-i18n: openclaw reset --scope full --yes --non-interactive ``` - Потім повторно запустіть налаштування: + Потім знову запустіть налаштування: ```bash openclaw onboard --install-daemon @@ -2056,22 +2058,22 @@ x-i18n: Примітки: - - Онбординг також пропонує **Reset**, якщо бачить наявну конфігурацію. Дивіться [Онбординг (CLI)](/uk/start/wizard). - - Якщо ви використовували профілі (`--profile` / `OPENCLAW_PROFILE`), скиньте кожен state dir (типові значення — `~/.openclaw-`). - - Скидання dev: `openclaw gateway --dev --reset` (лише для dev; очищає конфігурацію dev + облікові дані + сесії + workspace). + - Онбординг також пропонує **Reset**, якщо бачить наявну конфігурацію. Див. [Онбординг (CLI)](/uk/start/wizard). + - Якщо ви використовували профілі (`--profile` / `OPENCLAW_PROFILE`), скиньте кожен state dir (типово це `~/.openclaw-`). + - Скидання dev: `openclaw gateway --dev --reset` (лише для dev; очищає dev-конфігурацію + облікові дані + сесії + workspace). - Використовуйте один із цих варіантів: + Використайте один із варіантів: - - **Compaction** (зберігає розмову, але підсумовує старіші ходи): + - **Стиснення** (зберігає розмову, але підсумовує старіші ходи): ``` /compact ``` - або `/compact `, щоб спрямувати підсумок. + або `/compact `, щоб скерувати підсумок. - **Скидання** (новий ID сесії для того самого ключа чату): @@ -2080,52 +2082,52 @@ x-i18n: /reset ``` - Якщо це продовжує траплятися: + Якщо це постійно повторюється: - - Увімкніть або налаштуйте **обрізання сесії** (`agents.defaults.contextPruning`), щоб обрізати старий вивід інструментів. - - Використовуйте модель з більшим вікном контексту. + - Увімкніть або налаштуйте **очищення сесії** (`agents.defaults.contextPruning`), щоб обрізати старий вивід інструментів. + - Використовуйте модель із більшим вікном контексту. - Документація: [Compaction](/uk/concepts/compaction), [Обрізання сесії](/uk/concepts/session-pruning), [Керування сесіями](/uk/concepts/session). + Документація: [Compaction](/uk/concepts/compaction), [Очищення сесії](/uk/concepts/session-pruning), [Керування сесіями](/uk/concepts/session). - Це помилка валідації провайдера: модель видала блок `tool_use` без обов’язкового - `input`. Зазвичай це означає, що історія сесії застаріла або пошкоджена (часто після довгих thread - або зміни tool/schema). + Це помилка валідації провайдера: модель вивела блок `tool_use` без обов’язкового + `input`. Зазвичай це означає, що історія сесії застаріла або пошкоджена (часто після довгих гілок + або зміни інструмента/схеми). - Виправлення: почніть нову сесію через `/new` (окремим повідомленням). + Виправлення: почніть нову сесію за допомогою `/new` (окреме повідомлення). - - Heartbeat запускається кожні **30m** за замовчуванням (**1h** при використанні OAuth-автентифікації). Налаштуйте або вимкніть його: + + Heartbeat типово запускається кожні **30 хв** (**1 год** при використанні OAuth-автентифікації). Налаштуйте або вимкніть його: ```json5 { agents: { defaults: { heartbeat: { - every: "2h", // або "0m", щоб вимкнути + every: "2h", // or "0m" to disable }, }, }, } ``` - Якщо `HEARTBEAT.md` існує, але фактично порожній (лише порожні рядки й markdown-заголовки - на кшталт `# Heading`), OpenClaw пропускає запуск heartbeat, щоб зекономити виклики API. - Якщо файл відсутній, heartbeat усе одно запускається, і модель вирішує, що робити. + Якщо `HEARTBEAT.md` існує, але фактично порожній (лише порожні рядки та markdown-заголовки + на кшталт `# Heading`), OpenClaw пропускає запуск Heartbeat, щоб заощадити API-виклики. + Якщо файл відсутній, Heartbeat усе одно запускається, і модель вирішує, що робити. - Override-налаштування для окремого агента використовують `agents.list[].heartbeat`. Документація: [Heartbeat](/uk/gateway/heartbeat). + Overrides для конкретного агента використовують `agents.list[].heartbeat`. Документація: [Heartbeat](/uk/gateway/heartbeat). - - Ні. OpenClaw працює від **вашого власного акаунта**, тож якщо ви є в групі, OpenClaw може її бачити. - За замовчуванням відповіді в групах заблоковані, доки ви не дозволите відправників (`groupPolicy: "allowlist"`). + + Ні. OpenClaw працює від **вашого власного облікового запису**, тому якщо ви є в групі, OpenClaw може її бачити. + Типово відповіді в групах заблоковані, доки ви не дозволите відправників (`groupPolicy: "allowlist"`). - Якщо ви хочете, щоб **лише ви** могли викликати відповіді в групі: + Якщо ви хочете, щоб запускати відповіді в групі могли лише **ви**: ```json5 { @@ -2141,7 +2143,7 @@ x-i18n: - Варіант 1 (найшвидший): переглядайте журнали і надішліть тестове повідомлення в групу: + Варіант 1 (найшвидший): дивіться логи в реальному часі та надішліть тестове повідомлення в групу: ```bash openclaw logs --follow --json @@ -2150,114 +2152,114 @@ x-i18n: Шукайте `chatId` (або `from`), що закінчується на `@g.us`, наприклад: `1234567890-1234567890@g.us`. - Варіант 2 (якщо вже налаштовано/додано в allowlist): перелічіть групи з конфігурації: + Варіант 2 (якщо вже налаштовано/додано в allowlist): перегляньте групи з конфігурації: ```bash openclaw directory groups list --channel whatsapp ``` - Документація: [WhatsApp](/uk/channels/whatsapp), [Directory](/cli/directory), [Журнали](/cli/logs). + Документація: [WhatsApp](/uk/channels/whatsapp), [Directory](/cli/directory), [Логи](/cli/logs). - Дві поширені причини: + Є дві поширені причини: - - Увімкнено обмеження на згадки (типово). Ви маєте @згадати бота (або відповідати `mentionPatterns`). + - Увімкнено обмеження за згадкою (типово). Ви маєте @згадати бота (або відповідати `mentionPatterns`). - Ви налаштували `channels.whatsapp.groups` без `"*"`, і цю групу не додано в allowlist. - Дивіться [Групи](/uk/channels/groups) і [Групові повідомлення](/uk/channels/group-messages). + Див. [Групи](/uk/channels/groups) і [Групові повідомлення](/uk/channels/group-messages). - - Прямі чати за замовчуванням згортаються до основної сесії. Групи/канали мають власні ключі сесій, а теми Telegram / threads Discord — це окремі сесії. Дивіться [Групи](/uk/channels/groups) і [Групові повідомлення](/uk/channels/group-messages). + + Прямі чати типово згортаються до основної сесії. Групи/канали мають власні ключі сесій, а теми Telegram / гілки Discord є окремими сесіями. Див. [Групи](/uk/channels/groups) і [Групові повідомлення](/uk/channels/group-messages). - Жорстких обмежень немає. Десятки (навіть сотні) — це нормально, але стежте за таким: + Жорстких обмежень немає. Десятки (навіть сотні) — це нормально, але стежте за: - - **Зростання диска:** сесії + transcript-и зберігаються в `~/.openclaw/agents//sessions/`. - - **Вартість токенів:** більше агентів означає більше одночасного використання моделі. - - **Операційні накладні витрати:** профілі автентифікації на рівні агента, workspace і маршрутизація каналів. + - **Зростанням диска:** сесії + транскрипти зберігаються в `~/.openclaw/agents//sessions/`. + - **Вартістю токенів:** більше агентів означає більше одночасного використання моделей. + - **Операційними витратами:** профілі автентифікації, workspace і маршрутизація каналів для кожного агента. Поради: - Тримайте один **активний** workspace на агента (`agents.defaults.workspace`). - - Обрізайте старі сесії (видаляйте JSONL або записи сховища), якщо диск розростається. - - Використовуйте `openclaw doctor`, щоб виявляти сторонні workspace і невідповідності профілів. + - Очищайте старі сесії (видаляйте JSONL або записи сховища), якщо диск розростається. + - Використовуйте `openclaw doctor`, щоб знаходити зайві workspace і невідповідності профілів. - - Так. Використовуйте **Маршрутизацію Multi-Agent**, щоб запускати кількох ізольованих агентів і маршрутизувати вхідні повідомлення за - каналом/акаунтом/peer. Slack підтримується як канал і може бути прив’язаний до конкретних агентів. + + Так. Використовуйте **Маршрутизацію кількох агентів**, щоб запускати кількох ізольованих агентів і маршрутизувати вхідні повідомлення за + каналом/обліковим записом/peer. Slack підтримується як канал і може бути прив’язаний до конкретних агентів. - Доступ до браузера потужний, але це не «можна все, що може людина» — anti-bot, CAPTCHA і MFA + Доступ до браузера потужний, але це не «робити все, що може людина» — anti-bot, CAPTCHA і MFA все ще можуть блокувати автоматизацію. Для найнадійнішого керування браузером використовуйте локальний Chrome MCP на хості, або використовуйте CDP на машині, яка фактично запускає браузер. Найкраща практика налаштування: - - Завжди увімкнений хост Gateway (VPS/Mac mini). + - Хост Gateway, що завжди ввімкнений (VPS/Mac mini). - Один агент на роль (bindings). - Канал(и) Slack, прив’язані до цих агентів. - - Локальний браузер через Chrome MCP або node за потреби. + - Локальний браузер через Chrome MCP або Node, коли це потрібно. - Документація: [Маршрутизація Multi-Agent](/uk/concepts/multi-agent), [Slack](/uk/channels/slack), - [Browser](/uk/tools/browser), [Nodes](/uk/nodes). + Документація: [Маршрутизація кількох агентів](/uk/concepts/multi-agent), [Slack](/uk/channels/slack), + [Браузер](/uk/tools/browser), [Nodes](/uk/nodes). -## Моделі: типові значення, вибір, псевдоніми, перемикання +## Моделі: типові значення, вибір, aliases, перемикання - Модель за замовчуванням в OpenClaw — це те, що ви встановлюєте як: + Типова модель OpenClaw — це те, що ви встановили як: ``` agents.defaults.model.primary ``` - На моделі посилаються у форматі `provider/model` (приклад: `openai/gpt-5.4`). Якщо ви пропускаєте провайдера, OpenClaw спочатку намагається знайти псевдонім, потім — унікальний збіг налаштованого провайдера для точного id цієї моделі, і лише після цього переходить до налаштованого провайдера за замовчуванням як до застарілого шляху сумісності. Якщо цей провайдер більше не надає налаштовану модель за замовчуванням, OpenClaw переходить до першого налаштованого провайдера/моделі замість того, щоб показувати застаріле значення за замовчуванням для видаленого провайдера. Але вам усе одно слід **явно** вказувати `provider/model`. + На моделі посилаються у форматі `provider/model` (приклад: `openai/gpt-5.4`). Якщо ви пропускаєте провайдера, OpenClaw спочатку намагається знайти alias, потім унікальний збіг точно цього model id серед налаштованих провайдерів, і лише потім повертається до налаштованого провайдера за замовчуванням як застарілого шляху сумісності. Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw повертається до першого налаштованого провайдера/моделі замість показу застарілого типового значення від видаленого провайдера. Але вам усе одно слід **явно** вказувати `provider/model`. - **Рекомендована модель за замовчуванням:** використовуйте найсильнішу модель останнього покоління, доступну у вашому стеку провайдерів. - **Для агентів з увімкненими інструментами або ненадійним входом:** ставте силу моделі вище за вартість. - **Для звичайного/низькоризикового чату:** використовуйте дешевші резервні моделі й маршрутизуйте за роллю агента. + **Рекомендована типова:** використовуйте найсильнішу модель останнього покоління, доступну у вашому стеку провайдерів. + **Для агентів з інструментами або недовіреним вхідним потоком:** ставте силу моделі вище за вартість. + **Для рутинного/низькоризикового чату:** використовуйте дешевші резервні моделі та маршрутизуйте за роллю агента. - Для MiniMax є окрема документація: [MiniMax](/uk/providers/minimax) і + MiniMax має власну документацію: [MiniMax](/uk/providers/minimax) і [Локальні моделі](/uk/gateway/local-models). - Практичне правило: використовуйте **найкращу модель, яку можете собі дозволити** для важливої роботи, і дешевшу - модель для звичайного чату або підсумків. Ви можете маршрутизувати моделі на рівні агента і використовувати sub-agents для - паралелізації довгих завдань (кожен sub-agent споживає токени). Дивіться [Моделі](/uk/concepts/models) і + Практичне правило: використовуйте **найкращу модель, яку можете собі дозволити** для важливих завдань, і дешевшу + модель для рутинного чату або підсумків. Ви можете маршрутизувати моделі за агентами і використовувати субагентів для + паралелізації довгих завдань (кожен субагент витрачає токени). Див. [Моделі](/uk/concepts/models) і [Sub-agents](/uk/tools/subagents). - Серйозне попередження: слабші або надмірно квантизовані моделі більш вразливі до prompt - injection і небезпечної поведінки. Дивіться [Безпека](/uk/gateway/security). + Сильне попередження: слабші/надмірно квантизовані моделі більш вразливі до prompt + injection і небезпечної поведінки. Див. [Безпека](/uk/gateway/security). Більше контексту: [Моделі](/uk/concepts/models). - + Використовуйте **команди моделей** або редагуйте лише поля **model**. Уникайте повної заміни конфігурації. Безпечні варіанти: - - `/model` у чаті (швидко, для окремої сесії) + - `/model` у чаті (швидко, для однієї сесії) - `openclaw models set ...` (оновлює лише конфігурацію моделі) - `openclaw configure --section model` (інтерактивно) - - відредагуйте `agents.defaults.model` у `~/.openclaw/openclaw.json` + - редагуйте `agents.defaults.model` у `~/.openclaw/openclaw.json` - Уникайте `config.apply` з частковим об’єктом, якщо ви не маєте наміру замінити всю конфігурацію. - Для RPC-редагувань спочатку перевірте через `config.schema.lookup` і надавайте перевагу `config.patch`. Payload lookup дає вам нормалізований шлях, неглибоку документацію/обмеження схеми та підсумки безпосередніх дочірніх елементів. + Уникайте `config.apply` з частковим об’єктом, якщо тільки ви не хочете замінити всю конфігурацію. + Для RPC-редагувань спочатку перегляньте через `config.schema.lookup` і віддавайте перевагу `config.patch`. payload lookup дає вам нормалізований шлях, поверхневу документацію/обмеження схеми та зведення безпосередніх дочірніх елементів для часткових оновлень. - Якщо ви все ж перезаписали конфігурацію, відновіть її з резервної копії або повторно виконайте `openclaw doctor` для виправлення. + Якщо ви все ж перезаписали конфігурацію, відновіть її з резервної копії або повторно запустіть `openclaw doctor` для виправлення. Документація: [Моделі](/uk/concepts/models), [Налаштування](/cli/configure), [Конфігурація](/cli/config), [Doctor](/uk/gateway/doctor). @@ -2270,19 +2272,19 @@ x-i18n: 1. Установіть Ollama з `https://ollama.com/download` 2. Завантажте локальну модель, наприклад `ollama pull gemma4` - 3. Якщо ви хочете також хмарні моделі, виконайте `ollama signin` + 3. Якщо вам потрібні також хмарні моделі, виконайте `ollama signin` 4. Запустіть `openclaw onboard` і виберіть `Ollama` 5. Виберіть `Local` або `Cloud + Local` Примітки: - `Cloud + Local` дає вам хмарні моделі плюс ваші локальні моделі Ollama - - хмарні моделі, такі як `kimi-k2.5:cloud`, не потребують локального завантаження + - хмарні моделі на кшталт `kimi-k2.5:cloud` не потребують локального завантаження - для ручного перемикання використовуйте `openclaw models list` і `openclaw models set ollama/` - Примітка щодо безпеки: менші або сильно квантизовані моделі більш вразливі до prompt + Примітка з безпеки: менші або сильно квантизовані моделі більш вразливі до prompt injection. Ми наполегливо рекомендуємо **великі моделі** для будь-якого бота, який може використовувати інструменти. - Якщо ви все ж хочете малі моделі, увімкніть ізоляцію та суворі allowlist-и інструментів. + Якщо ви все ж хочете маленькі моделі, увімкніть ізоляцію та суворі allowlist-и інструментів. Документація: [Ollama](/uk/providers/ollama), [Локальні моделі](/uk/gateway/local-models), [Провайдери моделей](/uk/concepts/model-providers), [Безпека](/uk/gateway/security), @@ -2291,9 +2293,9 @@ x-i18n: - - У цих розгортаннях усе може відрізнятися й змінюватися з часом; фіксованої рекомендації щодо провайдера немає. - - Перевіряйте поточне налаштування під час виконання на кожному gateway через `openclaw models status`. - - Для агентів, чутливих до безпеки/з інструментами, використовуйте найсильнішу доступну модель останнього покоління. + - У цих розгортаннях можуть бути різні налаштування, і вони можуть змінюватися з часом; фіксованої рекомендації щодо провайдера немає. + - Перевіряйте поточне налаштування під час роботи на кожному gateway через `openclaw models status`. + - Для чутливих до безпеки/увімкнених для інструментів агентів використовуйте найсильнішу доступну модель останнього покоління. @@ -2309,27 +2311,27 @@ x-i18n: /model gemini-flash-lite ``` - Це вбудовані псевдоніми. Власні псевдоніми можна додати через `agents.defaults.models`. + Це вбудовані aliases. Користувацькі aliases можна додати через `agents.defaults.models`. Ви можете переглянути доступні моделі через `/model`, `/model list` або `/model status`. - `/model` (і `/model list`) показує компактний нумерований вибір. Вибирайте за номером: + `/model` (і `/model list`) показує компактний нумерований picker. Вибір за номером: ``` /model 3 ``` - Ви також можете примусово вибрати конкретний профіль автентифікації для провайдера (для сесії): + Ви також можете примусово вказати конкретний профіль автентифікації для провайдера (на сесію): ``` /model opus@anthropic:default /model opus@anthropic:work ``` - Порада: `/model status` показує, який агент активний, який файл `auth-profiles.json` використовується і який профіль автентифікації буде спробовано наступним. - Він також показує налаштований endpoint провайдера (`baseUrl`) і режим API (`api`), коли вони доступні. + Порада: `/model status` показує, який агент активний, який файл `auth-profiles.json` використовується і який профіль автентифікації буде випробувано наступним. + Він також показує налаштований endpoint провайдера (`baseUrl`) і режим API (`api`), коли це доступно. - **Як зняти прив’язку профілю, який я встановив через @profile?** + **Як зняти закріплення профілю, який я встановив через @profile?** Повторно виконайте `/model` **без** суфікса `@profile`: @@ -2337,28 +2339,28 @@ x-i18n: /model anthropic/claude-opus-4-6 ``` - Якщо ви хочете повернутися до типового значення, виберіть його через `/model` (або надішліть `/model `). + Якщо ви хочете повернутися до типового значення, виберіть його з `/model` (або надішліть `/model `). Використовуйте `/model status`, щоб підтвердити, який профіль автентифікації активний. - - Так. Установіть одну як типову і перемикайте за потреби: + + Так. Установіть одну як типову і перемикайтеся за потреби: - - **Швидке перемикання (для сесії):** `/model gpt-5.4` для щоденних завдань, `/model openai-codex/gpt-5.4` для кодування з Codex OAuth. - - **Типове значення + перемикання:** установіть `agents.defaults.model.primary` в `openai/gpt-5.4`, а потім перемикайтеся на `openai-codex/gpt-5.4` під час кодування (або навпаки). - - **Sub-agents:** маршрутизуйте завдання кодування до sub-agents з іншою моделлю за замовчуванням. + - **Швидке перемикання (на сесію):** `/model gpt-5.4` для щоденних завдань, `/model openai-codex/gpt-5.4` для кодування через Codex OAuth. + - **Типове значення + перемикання:** установіть `agents.defaults.model.primary` у `openai/gpt-5.4`, а потім перемикайтеся на `openai-codex/gpt-5.4` під час кодування (або навпаки). + - **Субагенти:** маршрутизуйте завдання кодування до субагентів з іншою типовою моделлю. - Дивіться [Моделі](/uk/concepts/models) і [Slash-команди](/uk/tools/slash-commands). + Див. [Моделі](/uk/concepts/models) і [Slash commands](/uk/tools/slash-commands). Використовуйте або перемикач сесії, або типове значення в конфігурації: - - **Для сесії:** надішліть `/fast on`, коли сесія використовує `openai/gpt-5.4` або `openai-codex/gpt-5.4`. + - **На сесію:** надішліть `/fast on`, поки сесія використовує `openai/gpt-5.4` або `openai-codex/gpt-5.4`. - **Типове значення для моделі:** установіть `agents.defaults.models["openai/gpt-5.4"].params.fastMode` у `true`. - - **Також для Codex OAuth:** якщо ви також використовуєте `openai-codex/gpt-5.4`, установіть той самий прапорець і там. + - **Також для Codex OAuth:** якщо ви ще використовуєте `openai-codex/gpt-5.4`, установіть той самий прапорець і там. Приклад: @@ -2383,14 +2385,14 @@ x-i18n: } ``` - Для OpenAI fast mode відображається на `service_tier = "priority"` у підтримуваних нативних запитах Responses. Перевизначення сесії через `/fast` мають пріоритет над типовими значеннями конфігурації. + Для OpenAI fast mode відображається у `service_tier = "priority"` у підтримуваних нативних запитах Responses. Перевизначення сесії через `/fast` мають вищий пріоритет за типові значення конфігурації. - Дивіться [Thinking and fast mode](/uk/tools/thinking) і [OpenAI fast mode](/uk/providers/openai#openai-fast-mode). + Див. [Thinking і fast mode](/uk/tools/thinking) і [OpenAI fast mode](/uk/providers/openai#openai-fast-mode). - Якщо задано `agents.defaults.models`, це стає **allowlist-ом** для `/model` і будь-яких + Якщо встановлено `agents.defaults.models`, воно стає **allowlist-ом** для `/model` і будь-яких перевизначень сесії. Вибір моделі, якої немає в цьому списку, повертає: ``` @@ -2398,25 +2400,25 @@ x-i18n: ``` Ця помилка повертається **замість** звичайної відповіді. Виправлення: додайте модель до - `agents.defaults.models`, приберіть allowlist або виберіть модель з `/model list`. + `agents.defaults.models`, приберіть allowlist або виберіть модель із `/model list`. - Це означає, що **провайдера не налаштовано** (не знайдено конфігурації провайдера MiniMax або + Це означає, що **провайдер не налаштований** (не знайдено ні конфігурації провайдера MiniMax, ні профілю автентифікації), тому модель не може бути розв’язана. Контрольний список для виправлення: - 1. Оновіться до актуального релізу OpenClaw (або запускайте з вихідного коду `main`), а потім перезапустіть gateway. - 2. Переконайтеся, що MiniMax налаштовано (через майстер або JSON), або що автентифікація MiniMax - існує в env/auth profiles, щоб відповідний провайдер можна було під’єднати + 1. Оновіться до поточного релізу OpenClaw (або запускайте з вихідного коду `main`), а потім перезапустіть gateway. + 2. Переконайтеся, що MiniMax налаштований (майстер або JSON), або що автентифікація MiniMax + існує в env/профілях автентифікації, щоб відповідний провайдер міг бути інжектований (`MINIMAX_API_KEY` для `minimax`, `MINIMAX_OAUTH_TOKEN` або збережений MiniMax OAuth для `minimax-portal`). - 3. Використовуйте точний id моделі (з урахуванням регістру) для вашого шляху автентифікації: + 3. Використовуйте точний model id (з урахуванням регістру) для вашого шляху автентифікації: `minimax/MiniMax-M2.7` або `minimax/MiniMax-M2.7-highspeed` для налаштування - з API ключем, або `minimax-portal/MiniMax-M2.7` / - `minimax-portal/MiniMax-M2.7-highspeed` для налаштування через OAuth. + з API key, або `minimax-portal/MiniMax-M2.7` / + `minimax-portal/MiniMax-M2.7-highspeed` для налаштування з OAuth. 4. Виконайте: ```bash @@ -2425,15 +2427,15 @@ x-i18n: і виберіть зі списку (або `/model list` у чаті). - Дивіться [MiniMax](/uk/providers/minimax) і [Моделі](/uk/concepts/models). + Див. [MiniMax](/uk/providers/minimax) і [Моделі](/uk/concepts/models). - - Так. Використовуйте **MiniMax як типову модель** і перемикайте моделі **для окремої сесії**, коли потрібно. - Резервні варіанти призначені для **помилок**, а не для «важких завдань», тому використовуйте `/model` або окремого агента. + + Так. Використовуйте **MiniMax за замовчуванням** і перемикайте моделі **на сесію** за потреби. + Резервні варіанти — це для **помилок**, а не для «складних завдань», тому використовуйте `/model` або окремого агента. - **Варіант A: перемикання для сесії** + **Варіант A: перемикання на сесію** ```json5 { @@ -2458,16 +2460,16 @@ x-i18n: **Варіант B: окремі агенти** - - Типова модель агента A: MiniMax - - Типова модель агента B: OpenAI + - Типове значення агента A: MiniMax + - Типове значення агента B: OpenAI - Маршрутизуйте за агентом або використовуйте `/agent` для перемикання - Документація: [Моделі](/uk/concepts/models), [Маршрутизація Multi-Agent](/uk/concepts/multi-agent), [MiniMax](/uk/providers/minimax), [OpenAI](/uk/providers/openai). + Документація: [Моделі](/uk/concepts/models), [Маршрутизація кількох агентів](/uk/concepts/multi-agent), [MiniMax](/uk/providers/minimax), [OpenAI](/uk/providers/openai). - - Так. OpenClaw постачається з кількома типовими скороченнями (вони застосовуються лише тоді, коли модель існує в `agents.defaults.models`): + + Так. OpenClaw постачається з кількома типовими shorthand-ами (застосовуються лише тоді, коли модель існує в `agents.defaults.models`): - `opus` → `anthropic/claude-opus-4-6` - `sonnet` → `anthropic/claude-sonnet-4-6` @@ -2478,12 +2480,12 @@ x-i18n: - `gemini-flash` → `google/gemini-3-flash-preview` - `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview` - Якщо ви задаєте власний псевдонім з тією самою назвою, перемагає ваше значення. + Якщо ви задасте власний alias з такою самою назвою, ваше значення матиме пріоритет. - - Псевдоніми беруться з `agents.defaults.models..alias`. Приклад: + + Aliases беруться з `agents.defaults.models..alias`. Приклад: ```json5 { @@ -2500,12 +2502,12 @@ x-i18n: } ``` - Тоді `/model sonnet` (або `/`, коли це підтримується) розв’язується в цей id моделі. + Тоді `/model sonnet` (або `/`, де це підтримується) розв’язується в цей model ID. - - OpenRouter (оплата за токени; багато моделей): + + OpenRouter (оплата за токен; багато моделей): ```json5 { @@ -2533,7 +2535,7 @@ x-i18n: } ``` - Якщо ви посилаєтеся на `provider/model`, але бракує потрібного ключа провайдера, ви отримаєте помилку автентифікації під час виконання (наприклад, `No API key found for provider "zai"`). + Якщо ви посилаєтеся на `provider/model`, але потрібний ключ провайдера відсутній, ви отримаєте помилку автентифікації під час виконання (наприклад, `No API key found for provider "zai"`). **Після додавання нового агента не знайдено API key для provider** @@ -2546,86 +2548,86 @@ x-i18n: Варіанти виправлення: - - Виконайте `openclaw agents add ` і налаштуйте автентифікацію через майстер. - - Або скопіюйте `auth-profiles.json` з `agentDir` основного агента в `agentDir` нового агента. + - Виконайте `openclaw agents add ` і налаштуйте автентифікацію в майстрі. + - Або скопіюйте `auth-profiles.json` з `agentDir` головного агента до `agentDir` нового агента. - **Не** використовуйте один і той самий `agentDir` для різних агентів; це спричиняє конфлікти автентифікації/сесій. + **Не** використовуйте спільний `agentDir` для кількох агентів; це спричиняє колізії автентифікації/сесій. -## Резервне перемикання моделей і «Усі моделі завершилися помилкою» +## Резервування моделей і "All models failed" - - Резервне перемикання відбувається у два етапи: + + Резервування відбувається у два етапи: - 1. **Ротація auth profile** у межах одного провайдера. + 1. **Ротація профілів автентифікації** в межах одного провайдера. 2. **Резервна модель** до наступної моделі в `agents.defaults.model.fallbacks`. - До профілів, що дають помилки, застосовуються cooldown-и (експоненційний backoff), тому OpenClaw може продовжувати відповідати навіть тоді, коли провайдер обмежений rate limit або тимчасово недоступний. + До профілів, що завершуються помилкою, застосовуються cooldown-и (експоненційний backoff), тож OpenClaw може продовжувати відповідати, навіть коли провайдер обмежений за rate limit або тимчасово недоступний. - Кошик rate limit включає не лише звичайні відповіді `429`. OpenClaw - також розглядає повідомлення на кшталт `Too many concurrent requests`, + Кошик rate limit включає більше, ніж просто відповіді `429`. OpenClaw + також трактує такі повідомлення, як `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, `resource exhausted` і періодичні - ліміти вікна використання (`weekly/monthly limit reached`) як підставу - для резервного перемикання через rate limit. + обмеження вікон використання (`weekly/monthly limit reached`) як підставу + для резервування через rate limit. - Деякі відповіді, схожі на проблеми з білінгом, не мають коду `402`, і деякі відповіді HTTP `402` - також лишаються в цьому тимчасовому кошику. Якщо провайдер повертає - явний текст про білінг на `401` або `403`, OpenClaw все одно може залишити це - у смузі білінгу, але provider-specific текстові зіставлення лишаються обмеженими - тим провайдером, якому вони належать (наприклад OpenRouter `Key limit exceeded`). Якщо ж повідомлення `402` - схоже на вікно використання, яке можна повторити, - або ліміт витрат organization/workspace (`daily limit reached, resets tomorrow`, - `organization spending limit exceeded`), OpenClaw розглядає це як - `rate_limit`, а не як довге блокування через білінг. + Деякі відповіді, схожі на проблеми білінгу, не є `402`, а деякі HTTP `402` + також залишаються в цьому транзитному кошику. Якщо провайдер повертає + явний текст про білінг у `401` або `403`, OpenClaw все одно може залишити це + у білінговому кошику, але текстові зіставлення, специфічні для провайдера, залишаються обмеженими + провайдером, якому вони належать (наприклад OpenRouter `Key limit exceeded`). Якщо ж повідомлення `402` + натомість схоже на повторюване вікно використання або + ліміт витрат organization/workspace (`daily limit reached, resets tomorrow`, + `organization spending limit exceeded`), OpenClaw трактує це як + `rate_limit`, а не як довготривале вимкнення через білінг. Помилки переповнення контексту відрізняються: сигнатури на кшталт `request_too_large`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model` або `ollama error: context length - exceeded` лишаються на шляху Compaction/retry замість переходу до - резервної моделі. + exceeded` залишаються на шляху Compaction/повторної спроби, а не запускають + резервну модель. - Загальний текст помилок сервера навмисно вужчий, ніж «усе, де є - unknown/error». OpenClaw дійсно розглядає provider-scoped перехідні форми, - такі як просте Anthropic `An unknown error occurred`, просте OpenRouter + Узагальнений текст server error навмисно вужчий, ніж «усе, що містить + unknown/error». OpenClaw справді трактує форми транзитних помилок, специфічні для провайдера, + такі як голе повідомлення Anthropic `An unknown error occurred`, голе повідомлення OpenRouter `Provider returned error`, помилки stop-reason на кшталт `Unhandled stop reason: - error`, JSON payload-и `api_error` з перехідним серверним текстом + error`, JSON payload-и `api_error` із транзитним текстом server error (`internal server error`, `unknown error, 520`, `upstream error`, `backend - error`) і помилки зайнятості провайдера, такі як `ModelNotReadyException`, як - сигнали timeout/перевантаження, що варті резервного перемикання, коли контекст провайдера + error`) і помилки перевантаження провайдера на кшталт `ModelNotReadyException`, як підставу + для резервування через timeout/перевантаження, коли контекст провайдера збігається. - Загальний внутрішній запасний текст на кшталт `LLM request failed with an unknown - error.` лишається консервативним і сам по собі не запускає резервне перемикання моделі. + Загальний внутрішній резервний текст на кшталт `LLM request failed with an unknown + error.` залишається консервативним і сам по собі не запускає резервну модель. - Це означає, що система намагалася використати id auth profile `anthropic:default`, але не змогла знайти для нього облікові дані в очікуваному сховищі автентифікації. + Це означає, що система спробувала використати ID профілю автентифікації `anthropic:default`, але не змогла знайти облікові дані для нього в очікуваному сховищі автентифікації. **Контрольний список для виправлення:** - - **Переконайтеся, де зберігаються auth profiles** (нові проти застарілих шляхів) - - Поточний шлях: `~/.openclaw/agents//agent/auth-profiles.json` - - Застарілий шлях: `~/.openclaw/agent/*` (мігрується командою `openclaw doctor`) - - **Переконайтеся, що вашу env var завантажено Gateway** - - Якщо ви встановили `ANTHROPIC_API_KEY` у своїй shell, але запускаєте Gateway через systemd/launchd, він може не успадковувати його. Помістіть його в `~/.openclaw/.env` або ввімкніть `env.shellEnv`. - - **Переконайтеся, що редагуєте правильного агента** - - У multi-agent-конфігураціях може бути кілька файлів `auth-profiles.json`. - - **Швидка перевірка стану model/auth** - - Використовуйте `openclaw models status`, щоб побачити налаштовані моделі й те, чи автентифіковано провайдерів. + - **Перевірте, де зберігаються профілі автентифікації** (нові чи застарілі шляхи) + - Поточний: `~/.openclaw/agents//agent/auth-profiles.json` + - Застарілий: `~/.openclaw/agent/*` (мігрується через `openclaw doctor`) + - **Переконайтеся, що ваша змінна середовища завантажується Gateway** + - Якщо ви встановили `ANTHROPIC_API_KEY` у своєму shell, але запускаєте Gateway через systemd/launchd, він може не успадковувати її. Помістіть її в `~/.openclaw/.env` або увімкніть `env.shellEnv`. + - **Переконайтеся, що ви редагуєте правильного агента** + - Налаштування з кількома агентами означають, що може бути кілька файлів `auth-profiles.json`. + - **Перевірте стан моделі/автентифікації** + - Використовуйте `openclaw models status`, щоб побачити налаштовані моделі та чи провайдери автентифіковані. **Контрольний список для виправлення "No credentials found for profile anthropic"** - Це означає, що запуск прив’язаний до auth profile Anthropic, але Gateway + Це означає, що запуск прив’язаний до профілю автентифікації Anthropic, але Gateway не може знайти його у своєму сховищі автентифікації. - **Використовуйте Claude CLI** - Виконайте `openclaw models auth login --provider anthropic --method cli --set-default` на хості gateway. - - **Якщо ви хочете використовувати API key натомість** + - **Якщо ви хочете натомість використовувати API key** - Помістіть `ANTHROPIC_API_KEY` у `~/.openclaw/.env` на **хості gateway**. - Очистіть будь-який закріплений порядок, який примусово вимагає відсутній профіль: @@ -2633,33 +2635,33 @@ x-i18n: openclaw models auth order clear --provider anthropic ``` - - **Переконайтеся, що ви запускаєте команди на хості gateway** - - У віддаленому режимі auth profiles живуть на машині gateway, а не на вашому ноутбуці. + - **Переконайтеся, що ви виконуєте команди на хості gateway** + - У віддаленому режимі профілі автентифікації живуть на машині gateway, а не на вашому ноутбуці. - - Якщо ваша конфігурація моделі включає Google Gemini як резервний варіант (або ви переключилися на скорочення Gemini), OpenClaw спробує його під час резервного перемикання моделей. Якщо ви не налаштували облікові дані Google, побачите `No API key found for provider "google"`. + + Якщо конфігурація вашої моделі включає Google Gemini як резервний варіант (або ви перемкнулися на shorthand Gemini), OpenClaw спробує його під час резервування моделі. Якщо ви не налаштували облікові дані Google, побачите `No API key found for provider "google"`. - Виправлення: або надайте автентифікацію Google, або видаліть/уникайте моделей Google у `agents.defaults.model.fallbacks` / псевдонімах, щоб резервне перемикання не маршрутизувало туди. + Виправлення: або надайте автентифікацію Google, або приберіть/уникайте моделей Google у `agents.defaults.model.fallbacks` / aliases, щоб резервування не маршрутизувалося туди. **LLM request rejected: thinking signature required (Google Antigravity)** - Причина: історія сесії містить **блоки thinking без підписів** (часто через - перерваний/частковий потік). Google Antigravity вимагає підписів для блоків thinking. + Причина: історія сесії містить **thinking-блоки без сигнатур** (часто після + перерваного/часткового потоку). Google Antigravity вимагає сигнатури для thinking-блоків. - Виправлення: тепер OpenClaw видаляє непідписані блоки thinking для Google Antigravity Claude. Якщо це все ще трапляється, почніть **нову сесію** або встановіть `/thinking off` для цього агента. + Виправлення: тепер OpenClaw прибирає thinking-блоки без сигнатур для Google Antigravity Claude. Якщо це все ще з’являється, почніть **нову сесію** або встановіть `/thinking off` для цього агента. -## Auth profiles: що це таке і як ними керувати +## Профілі автентифікації: що це таке і як ними керувати -Пов’язане: [/concepts/oauth](/uk/concepts/oauth) (OAuth-потоки, зберігання токенів, шаблони з кількома акаунтами) +Пов’язано: [/concepts/oauth](/uk/concepts/oauth) (OAuth-потоки, зберігання токенів, шаблони з кількома обліковими записами) - - Auth profile — це іменований запис облікових даних (OAuth або API key), прив’язаний до провайдера. Профілі зберігаються в: + + Профіль автентифікації — це іменований запис облікових даних (OAuth або API key), прив’язаний до провайдера. Профілі зберігаються в: ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -2667,37 +2669,37 @@ x-i18n: - - OpenClaw використовує id з префіксом провайдера, наприклад: + + OpenClaw використовує ID з префіксом провайдера, наприклад: - - `anthropic:default` (типово, коли немає email identity) - - `anthropic:` для OAuth-ідентичностей - - власні id, які ви вибираєте (наприклад `anthropic:work`) + - `anthropic:default` (типово, коли немає identity на основі email) + - `anthropic:` для OAuth identity + - користувацькі ID, які ви вибираєте (наприклад `anthropic:work`) - - Так. Конфігурація підтримує необов’язкові metadata для профілів і порядок для кожного провайдера (`auth.order.`). Це **не** зберігає секрети; це зіставляє id з provider/mode і задає порядок ротації. + + Так. Конфігурація підтримує необов’язкові метадані для профілів і порядок для кожного провайдера (`auth.order.`). Це **не** зберігає секрети; воно зіставляє ID з провайдером/режимом і задає порядок ротації. OpenClaw може тимчасово пропускати профіль, якщо він перебуває в короткому **cooldown** (rate limits/timeouts/auth failures) або в довшому стані **disabled** (billing/insufficient credits). Щоб перевірити це, виконайте `openclaw models status --json` і перегляньте `auth.unusableProfiles`. Налаштування: `auth.cooldowns.billingBackoffHours*`. - Cooldown-и через rate limit можуть бути scoped до моделі. Профіль, який перебуває в cooldown - для однієї моделі, все ще може бути придатним для сусідньої моделі того самого провайдера, + Cooldown-и через rate limit можуть бути прив’язані до моделі. Профіль, який перебуває в cooldown + для однієї моделі, усе ще може бути придатним для спорідненої моделі того самого провайдера, тоді як вікна billing/disabled усе ще блокують увесь профіль. - Ви також можете встановити **перевизначення порядку для окремого агента** (зберігається в `auth-state.json` цього агента) через CLI: + Ви також можете задати **порядок для конкретного агента** (зберігається в `auth-state.json` цього агента) через CLI: ```bash - # За замовчуванням використовується типовий агент із конфігурації (пропустіть --agent) + # Defaults to the configured default agent (omit --agent) openclaw models auth order get --provider anthropic - # Зафіксувати ротацію на одному профілі (пробувати лише цей) + # Lock rotation to a single profile (only try this one) openclaw models auth order set --provider anthropic anthropic:default - # Або встановити явний порядок (резервне перемикання в межах провайдера) + # Or set an explicit order (fallback within provider) openclaw models auth order set --provider anthropic anthropic:work anthropic:default - # Очистити перевизначення (повернутися до config auth.order / round-robin) + # Clear override (fall back to config auth.order / round-robin) openclaw models auth order clear --provider anthropic ``` @@ -2707,29 +2709,29 @@ x-i18n: openclaw models auth order set --provider anthropic --agent main anthropic:default ``` - Щоб перевірити, що реально буде спробовано, використовуйте: + Щоб перевірити, що насправді буде випробувано, використовуйте: ```bash openclaw models status --probe ``` - Якщо збережений профіль пропущено в явному порядку, probe повідомить + Якщо збережений профіль пропущено в явному порядку, probe повідомляє `excluded_by_auth_order` для цього профілю замість того, щоб мовчки його пробувати. - + OpenClaw підтримує обидва варіанти: - **OAuth** часто використовує доступ за підпискою (де це застосовно). - - **API keys** використовують білінг за токени. + - **API keys** використовують білінг pay-per-token. Майстер явно підтримує Anthropic Claude CLI, OpenAI Codex OAuth і API keys. -## Gateway: порти, «already running» і віддалений режим +## Gateway: порти, "already running" і віддалений режим @@ -2743,19 +2745,19 @@ x-i18n: - - Тому що "running" — це погляд **supervisor** (launchd/systemd/schtasks). А connectivity probe — це реальне підключення CLI до WebSocket gateway. + + Тому що "running" — це погляд **supervisor-а** (launchd/systemd/schtasks). А connectivity probe — це фактичне підключення CLI до gateway WebSocket. - Використовуйте `openclaw gateway status` і довіряйте цим рядкам: + Використовуйте `openclaw gateway status` і довіряйте таким рядкам: - `Probe target:` (URL, який probe фактично використав) - `Listening:` (що реально прив’язано до порту) - - `Last gateway error:` (типова першопричина, коли процес живий, але порт не слухає) + - `Last gateway error:` (поширена першопричина, коли процес живий, але порт не слухає) - - Ви редагуєте один файл конфігурації, а сервіс запускає інший (часто це невідповідність `--profile` / `OPENCLAW_STATE_DIR`). + + Ви редагуєте один файл конфігурації, а сервіс працює з іншим (часто через невідповідність `--profile` / `OPENCLAW_STATE_DIR`). Виправлення: @@ -2763,19 +2765,19 @@ x-i18n: openclaw gateway install --force ``` - Запускайте це з того самого `--profile` / середовища, яке ви хочете використовувати для сервісу. + Запускайте це з того самого `--profile` / середовища, яке сервіс має використовувати. - OpenClaw примусово забезпечує runtime lock, одразу прив’язуючи listener WebSocket під час запуску (типово `ws://127.0.0.1:18789`). Якщо bind завершується помилкою `EADDRINUSE`, викидається `GatewayLockError`, що означає: інший інстанс уже слухає. + OpenClaw примусово використовує runtime-lock, одразу прив’язуючи слухач WebSocket під час запуску (типово `ws://127.0.0.1:18789`). Якщо bind завершується помилкою `EADDRINUSE`, викидається `GatewayLockError`, що означає: інший екземпляр уже слухає. - Виправлення: зупиніть інший інстанс, звільніть порт або запускайте з `openclaw gateway --port `. + Виправлення: зупиніть інший екземпляр, звільніть порт або запускайте з `openclaw gateway --port `. - Установіть `gateway.mode: "remote"` і вкажіть віддалену URL-адресу WebSocket, за потреби з shared-secret віддаленими обліковими даними: + Установіть `gateway.mode: "remote"` і вкажіть віддалений URL WebSocket, за потреби з віддаленими обліковими даними на основі спільного секрету: ```json5 { @@ -2792,90 +2794,90 @@ x-i18n: Примітки: - - `openclaw gateway` запускається лише тоді, коли `gateway.mode` має значення `local` (або якщо ви передали прапорець перевизначення). - - Застосунок macOS стежить за файлом конфігурації і динамічно перемикає режими, коли ці значення змінюються. + - `openclaw gateway` запускається лише тоді, коли `gateway.mode` має значення `local` (або ви передаєте прапорець перевизначення). + - Застосунок macOS стежить за файлом конфігурації та переключає режими в реальному часі, коли ці значення змінюються. - `gateway.remote.token` / `.password` — це лише клієнтські віддалені облікові дані; самі по собі вони не вмикають локальну автентифікацію gateway. - + Шлях автентифікації вашого gateway і метод автентифікації UI не збігаються. Факти (з коду): - - Control UI зберігає токен у `sessionStorage` для поточної сесії вкладки браузера та вибраної URL-адреси gateway, тож оновлення в тій самій вкладці продовжують працювати без відновлення довготривалого збереження токена в localStorage. - - За `AUTH_TOKEN_MISMATCH` довірені клієнти можуть виконати одну обмежену повторну спробу з кешованим токеном пристрою, коли gateway повертає підказки для повтору (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`). - - Ця повторна спроба з кешованим токеном тепер повторно використовує кешовані погоджені scopes, збережені разом із токеном пристрою. Явні виклики `deviceToken` / явні `scopes` як і раніше зберігають свій запитаний набір scopes замість успадкування кешованих. - - Поза цим шляхом повтору пріоритет автентифікації connect такий: спочатку явний shared token/password, потім явний `deviceToken`, потім збережений токен пристрою, потім bootstrap token. - - Перевірки scope для bootstrap token мають префікси ролей. Вбудований allowlist bootstrap-оператора задовольняє лише запити оператора; для node або інших ролей, що не є оператором, усе одно потрібні scopes під префіксом їхньої ролі. + - Control UI зберігає токен у `sessionStorage` для поточної сесії вкладки браузера та вибраного URL gateway, тому оновлення в тій самій вкладці продовжують працювати без відновлення довготривалого збереження токена в localStorage. + - При `AUTH_TOKEN_MISMATCH` довірені клієнти можуть зробити одну обмежену повторну спробу з кешованим токеном пристрою, коли gateway повертає підказки для повтору (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`). + - Тепер ця повторна спроба з кешованим токеном повторно використовує кешовані дозволені scopes, збережені разом із токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` усе ще зберігають свій запитаний набір scopes замість успадкування кешованих scopes. + - Поза цим шляхом повторної спроби пріоритет автентифікації connect такий: спочатку явний shared token/password, потім явний `deviceToken`, потім збережений токен пристрою, потім bootstrap token. + - Перевірки scopes для bootstrap token мають префікси ролей. Вбудований allowlist bootstrap operator задовольняє лише запити operator; для node або інших ролей, відмінних від operator, усе ще потрібні scopes під власним префіксом ролі. Виправлення: - - Найшвидше: `openclaw dashboard` (виводить + копіює URL-адресу dashboard, намагається відкрити; у headless-режимі показує підказку про SSH). + - Найшвидше: `openclaw dashboard` (виводить + копіює URL dashboard, намагається відкрити; у headless показує підказку для SSH). - Якщо у вас ще немає токена: `openclaw doctor --generate-gateway-token`. - - Якщо віддалено, спочатку підніміть тунель: `ssh -N -L 18789:127.0.0.1:18789 user@host`, а потім відкрийте `http://127.0.0.1:18789/`. + - Якщо це віддалений режим, спочатку підніміть тунель: `ssh -N -L 18789:127.0.0.1:18789 user@host`, а потім відкрийте `http://127.0.0.1:18789/`. - Режим shared-secret: установіть `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` або `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`, а потім вставте відповідний секрет у налаштуваннях Control UI. - - Режим Tailscale Serve: переконайтеся, що `gateway.auth.allowTailscale` увімкнено і ви відкриваєте URL Serve, а не сиру URL loopback/tailnet, яка обходить заголовки ідентичності Tailscale. - - Режим trusted-proxy: переконайтеся, що ви заходите через налаштований identity-aware proxy не на loopback, а не через loopback proxy того самого хоста чи пряму URL-адресу gateway. - - Якщо невідповідність зберігається після однієї повторної спроби, перевипустіть/повторно погодьте paired device token: + - Режим Tailscale Serve: переконайтеся, що `gateway.auth.allowTailscale` увімкнено і ви відкриваєте URL Serve, а не сирий URL loopback/tailnet, який обходить заголовки ідентичності Tailscale. + - Режим trusted-proxy: переконайтеся, що ви заходите через налаштований non-loopback identity-aware proxy, а не через loopback proxy на тому самому хості чи сирий URL gateway. + - Якщо невідповідність зберігається після однієї повторної спроби, перевипустіть/повторно схваліть токен спареного пристрою: - `openclaw devices list` - `openclaw devices rotate --device --role operator` - Якщо цей виклик rotate каже, що його відхилено, перевірте дві речі: - - paired-device sessions можуть перевипускати лише **власний** пристрій, якщо тільки вони також не мають `operator.admin` - - явні значення `--scope` не можуть перевищувати поточні operator scopes викликувача - - Усе ще не вдається? Виконайте `openclaw status --all` і дотримуйтеся [Усунення несправностей](/uk/gateway/troubleshooting). Подробиці автентифікації дивіться в [Dashboard](/web/dashboard). + - сесії спарених пристроїв можуть перевипускати лише **власний** пристрій, якщо тільки вони також не мають `operator.admin` + - явні значення `--scope` не можуть перевищувати поточні scopes operator у виклику + - Усе ще застрягли? Виконайте `openclaw status --all` і дотримуйтеся [Усунення несправностей](/uk/gateway/troubleshooting). Подробиці автентифікації див. в [Dashboard](/web/dashboard). - Bind `tailnet` вибирає Tailscale IP з ваших мережевих інтерфейсів (100.64.0.0/10). Якщо машина не в Tailscale (або інтерфейс вимкнено), прив’язуватися нема до чого. + Bind `tailnet` вибирає Tailscale IP з ваших мережевих інтерфейсів (100.64.0.0/10). Якщо машина не в Tailscale (або інтерфейс неактивний), прив’язуватися просто нема до чого. Виправлення: - Запустіть Tailscale на цьому хості (щоб він мав адресу 100.x), або - Перемкніться на `gateway.bind: "loopback"` / `"lan"`. - Примітка: `tailnet` — це явний режим. `auto` віддає перевагу loopback; використовуйте `gateway.bind: "tailnet"`, коли хочете bind лише для tailnet. + Примітка: `tailnet` є явним. `auto` віддає перевагу loopback; використовуйте `gateway.bind: "tailnet"`, коли вам потрібен bind лише до tailnet. - Зазвичай ні — один Gateway може запускати кілька каналів повідомлень і агентів. Використовуйте кілька Gateway лише тоді, коли вам потрібна надлишковість (наприклад rescue bot) або жорстка ізоляція. + Зазвичай ні — один Gateway може обслуговувати кілька каналів обміну повідомленнями та агентів. Використовуйте кілька Gateway лише тоді, коли вам потрібна надлишковість (наприклад, rescue bot) або жорстка ізоляція. Так, але потрібно ізолювати: - - `OPENCLAW_CONFIG_PATH` (окрема конфігурація для кожного інстансу) - - `OPENCLAW_STATE_DIR` (окремий стан для кожного інстансу) + - `OPENCLAW_CONFIG_PATH` (конфігурація для кожного екземпляра) + - `OPENCLAW_STATE_DIR` (стан для кожного екземпляра) - `agents.defaults.workspace` (ізоляція workspace) - `gateway.port` (унікальні порти) Швидке налаштування (рекомендовано): - - Використовуйте `openclaw --profile ...` для кожного інстансу (автоматично створює `~/.openclaw-`). + - Використовуйте `openclaw --profile ...` для кожного екземпляра (автоматично створює `~/.openclaw-`). - Установіть унікальний `gateway.port` у конфігурації кожного профілю (або передавайте `--port` для ручних запусків). - Установіть сервіс для кожного профілю: `openclaw --profile gateway install`. Профілі також додають суфікси до назв сервісів (`ai.openclaw.`; застарілі `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`). - Повний посібник: [Кілька gateway](/uk/gateway/multiple-gateways). + Повна інструкція: [Кілька gateway](/uk/gateway/multiple-gateways). - - Gateway — це **сервер WebSocket**, і він очікує, що найпершим повідомленням - буде фрейм `connect`. Якщо отримує щось інше, він закриває з’єднання - з **code 1008** (порушення політики). + + Gateway — це **WebSocket-сервер**, і він очікує, що найперше повідомлення буде + фреймом `connect`. Якщо він отримує щось інше, то закриває з’єднання + з **кодом 1008** (порушення політики). Поширені причини: - Ви відкрили URL **HTTP** у браузері (`http://...`) замість клієнта WS. - Ви використали неправильний порт або шлях. - - Proxy або тунель зрізав заголовки автентифікації або надіслав не-Gateway-запит. + - Proxy або тунель обрізав заголовки автентифікації чи надіслав запит не для Gateway. Швидкі виправлення: 1. Використовуйте URL WS: `ws://:18789` (або `wss://...`, якщо HTTPS). 2. Не відкривайте порт WS у звичайній вкладці браузера. - 3. Якщо автентифікацію ввімкнено, включіть токен/пароль у фрейм `connect`. + 3. Якщо автентифікацію ввімкнено, додайте токен/пароль у фрейм `connect`. Якщо ви використовуєте CLI або TUI, URL має виглядати так: @@ -2888,31 +2890,31 @@ x-i18n: -## Журналювання та налагодження +## Логування та налагодження - - Файлові журнали (структуровані): + + Файлові логи (структуровані): ``` /tmp/openclaw/openclaw-YYYY-MM-DD.log ``` - Ви можете встановити стабільний шлях через `logging.file`. Рівень файлових журналів керується `logging.level`. Докладність консолі керується `--verbose` і `logging.consoleLevel`. + Ви можете задати стабільний шлях через `logging.file`. Рівень файлового логування контролюється через `logging.level`. Докладність консолі контролюється через `--verbose` і `logging.consoleLevel`. - Найшвидший перегляд хвоста журналу: + Найшвидший перегляд логів у реальному часі: ```bash openclaw logs --follow ``` - Журнали сервісу/supervisor (коли gateway працює через launchd/systemd): + Логи сервісу/supervisor-а (коли gateway працює через launchd/systemd): - macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` і `gateway.err.log` (типово: `~/.openclaw/logs/...`; профілі використовують `~/.openclaw-/logs/...`) - Linux: `journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager` - Windows: `schtasks /Query /TN "OpenClaw Gateway ()" /V /FO LIST` - Докладніше дивіться в [Усуненні несправностей](/uk/gateway/troubleshooting). + Більше див. в [Усунення несправностей](/uk/gateway/troubleshooting). @@ -2924,7 +2926,7 @@ x-i18n: openclaw gateway restart ``` - Якщо ви запускаєте gateway вручну, `openclaw gateway --force` може перехопити порт. Дивіться [Gateway](/uk/gateway). + Якщо ви запускаєте gateway вручну, `openclaw gateway --force` може повернути собі порт. Див. [Gateway](/uk/gateway). @@ -2966,7 +2968,7 @@ x-i18n: - + Почніть із швидкої перевірки стану: ```bash @@ -2979,11 +2981,11 @@ x-i18n: Поширені причини: - Автентифікацію моделі не завантажено на **хості gateway** (перевірте `models status`). - - Парування/allowlist каналу блокує відповіді (перевірте конфігурацію каналу + журнали). + - Спарювання каналу/allowlist блокує відповіді (перевірте конфігурацію каналу + логи). - WebChat/Dashboard відкрито без правильного токена. - Якщо ви працюєте віддалено, переконайтеся, що тунель/з’єднання Tailscale активне і що - WebSocket Gateway доступний. + Якщо ви у віддаленому режимі, переконайтеся, що тунель/Tailscale-з’єднання активне і + Gateway WebSocket доступний. Документація: [Канали](/uk/channels), [Усунення несправностей](/uk/gateway/troubleshooting), [Віддалений доступ](/uk/gateway/remote). @@ -2993,11 +2995,11 @@ x-i18n: Зазвичай це означає, що UI втратив з’єднання WebSocket. Перевірте: 1. Чи працює Gateway? `openclaw gateway status` - 2. Чи в порядку Gateway? `openclaw status` + 2. Чи справний Gateway? `openclaw status` 3. Чи має UI правильний токен? `openclaw dashboard` - 4. Якщо віддалено, чи активне з’єднання тунелю/Tailscale? + 4. Якщо це віддалений режим, чи активне тунель/Tailscale-з’єднання? - Потім перегляньте журнали: + Потім перегляньте логи в реальному часі: ```bash openclaw logs --follow @@ -3008,7 +3010,7 @@ x-i18n: - Почніть із журналів і стану каналу: + Почніть із логів і статусу каналу: ```bash openclaw channels status @@ -3018,15 +3020,15 @@ x-i18n: Потім зіставте помилку: - `BOT_COMMANDS_TOO_MUCH`: у меню Telegram забагато записів. OpenClaw уже обрізає список до ліміту Telegram і повторює спробу з меншою кількістю команд, але деякі записи меню все одно потрібно прибрати. Зменште кількість команд plugin/skill/custom або вимкніть `channels.telegram.commands.native`, якщо меню вам не потрібне. - - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!` або подібні мережеві помилки: якщо ви на VPS або за proxy, переконайтеся, що вихідний HTTPS дозволений і DNS працює для `api.telegram.org`. + - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!` або схожі мережеві помилки: якщо ви на VPS або за proxy, переконайтеся, що вихідний HTTPS дозволено і DNS працює для `api.telegram.org`. - Якщо Gateway віддалений, переконайтеся, що дивитеся журнали на хості Gateway. + Якщо Gateway віддалений, переконайтеся, що ви дивитеся логи на хості Gateway. Документація: [Telegram](/uk/channels/telegram), [Усунення несправностей каналів](/uk/channels/troubleshooting). - + Спочатку переконайтеся, що Gateway доступний і агент може працювати: ```bash @@ -3038,7 +3040,7 @@ x-i18n: У TUI використовуйте `/status`, щоб побачити поточний стан. Якщо ви очікуєте відповіді в чат-каналі, переконайтеся, що доставку ввімкнено (`/deliver on`). - Документація: [TUI](/web/tui), [Slash-команди](/uk/tools/slash-commands). + Документація: [TUI](/web/tui), [Slash commands](/uk/tools/slash-commands). @@ -3050,7 +3052,7 @@ x-i18n: openclaw gateway start ``` - Це зупиняє/запускає **керований сервіс** (launchd у macOS, systemd у Linux). + Це зупиняє/запускає **керований сервіс** (launchd на macOS, systemd на Linux). Використовуйте це, коли Gateway працює у фоновому режимі як демон. Якщо ви запускаєте його у foreground, зупиніть через Ctrl-C, а потім: @@ -3063,25 +3065,25 @@ x-i18n: - + - `openclaw gateway restart`: перезапускає **фоновий сервіс** (launchd/systemd). - `openclaw gateway`: запускає gateway **у foreground** для цієї сесії термінала. Якщо ви встановили сервіс, використовуйте команди gateway. Використовуйте `openclaw gateway`, коли - вам потрібен одноразовий запуск у foreground. + хочете одноразовий запуск у foreground. - - Запустіть Gateway з `--verbose`, щоб отримати більше деталей у консолі. Потім перевірте файл журналу на помилки автентифікації каналу, маршрутизації моделі та RPC. + + Запустіть Gateway з `--verbose`, щоб отримати більше деталей у консолі. Потім перегляньте файл логів для автентифікації каналів, маршрутизації моделей і помилок RPC. ## Медіа та вкладення - - Вихідні вкладення від агента мають містити рядок `MEDIA:` (в окремому рядку). Дивіться [Налаштування помічника OpenClaw](/uk/start/openclaw) і [Надсилання агентом](/uk/tools/agent-send). + + Вихідні вкладення від агента мають містити рядок `MEDIA:` (в окремому рядку). Див. [Налаштування помічника OpenClaw](/uk/start/openclaw) і [Надсилання Agent](/uk/tools/agent-send). Надсилання через CLI: @@ -3091,12 +3093,12 @@ x-i18n: Також перевірте: - - Цільовий канал підтримує вихідні медіа і не блокується allowlist-ами. + - Цільовий канал підтримує вихідні медіа і не заблокований allowlist-ами. - Файл не перевищує ліміти розміру провайдера (зображення змінюють розмір до максимуму 2048px). - - `tools.fs.workspaceOnly=true` обмежує надсилання локальних шляхів workspace, temp/media-store і файлами, перевіреними ізоляцією. - - `tools.fs.workspaceOnly=false` дозволяє `MEDIA:` надсилати локальні файли хоста, які агент уже може читати, але лише для медіа та безпечних типів документів (зображення, аудіо, відео, PDF і Office-документи). Звичайний текст і файли, схожі на секрети, все одно блокуються. + - `tools.fs.workspaceOnly=true` обмежує надсилання локальних шляхів workspace, temp/media-store і файлами, перевіреними sandbox. + - `tools.fs.workspaceOnly=false` дозволяє `MEDIA:` надсилати локальні файли хоста, які агент уже може читати, але лише для медіа та безпечних типів документів (зображення, аудіо, відео, PDF і Office-документи). Звичайний текст і файли, схожі на секрети, усе одно блокуються. - Дивіться [Зображення](/uk/nodes/images). + Див. [Зображення](/uk/nodes/images). @@ -3105,94 +3107,94 @@ x-i18n: - Розглядайте вхідні DM як ненадійний вхід. Значення за замовчуванням створені для зменшення ризику: + Ставтеся до вхідних DM як до недовіреного вмісту. Типові значення налаштовані так, щоб зменшувати ризик: - - Типова поведінка на каналах із підтримкою DM — **pairing**: - - Невідомі відправники отримують pairing code; бот не обробляє їхнє повідомлення. - - Погодження через: `openclaw pairing approve --channel [--account ] ` - - Кількість очікуваних запитів обмежена **3 на канал**; перевіряйте `openclaw pairing list --channel [--account ]`, якщо код не надійшов. - - Публічне відкриття DM вимагає явного opt-in (`dmPolicy: "open"` і allowlist `"*"`). + - Типова поведінка на каналах, що підтримують DM, — це **спарювання**: + - Невідомі відправники отримують код спарювання; бот не обробляє їхнє повідомлення. + - Схвалити можна так: `openclaw pairing approve --channel [--account ] ` + - Кількість запитів у черзі обмежена до **3 на канал**; перевірте `openclaw pairing list --channel [--account ]`, якщо код не надійшов. + - Публічне відкриття DM потребує явного opt-in (`dmPolicy: "open"` і allowlist `"*"`). Запустіть `openclaw doctor`, щоб виявити ризиковані політики DM. - Ні. Prompt injection стосується **ненадійного вмісту**, а не лише того, хто може писати боту в DM. + Ні. Prompt injection стосується **недовіреного вмісту**, а не лише того, хто може надсилати DM боту. Якщо ваш помічник читає зовнішній вміст (web search/fetch, сторінки браузера, email, - документи, вкладення, вставлені журнали), цей вміст може містити інструкції, які намагаються - перехопити керування моделлю. Це може статися, навіть якщо **єдиний відправник — ви**. + документи, вкладення, вставлені логи), цей вміст може містити інструкції, які намагаються + перехопити контроль над моделлю. Це може статися навіть якщо **ви — єдиний відправник**. - Найбільший ризик виникає, коли ввімкнені інструменти: модель можна обдурити і змусити - ексфільтрувати контекст або викликати інструменти від вашого імені. Зменшуйте зону ураження так: + Найбільший ризик виникає, коли увімкнено інструменти: модель можна обманом змусити + ексфільтрувати контекст або викликати інструменти від вашого імені. Зменшуйте радіус ураження так: - - використовуйте агента «reader» лише для читання або без інструментів, щоб підсумовувати ненадійний вміст + - використовуйте агента-"читача" лише для читання або без інструментів, щоб підсумовувати недовірений вміст - тримайте `web_search` / `web_fetch` / `browser` вимкненими для агентів з увімкненими інструментами - - також розглядайте декодований текст файлів/документів як ненадійний: OpenResponses - `input_file` і витягування тексту з медіавкладень обгортають витягнутий текст - явними маркерами меж зовнішнього вмісту замість передачі сирого тексту файлу + - ставтеся до декодованого тексту файлів/документів також як до недовіреного: OpenResponses + `input_file` і витяг тексту з медіавкладень обгортають витягнутий текст у + явні маркери меж зовнішнього вмісту замість передачі сирого тексту файлу - використовуйте ізоляцію та суворі allowlist-и інструментів Подробиці: [Безпека](/uk/gateway/security). - - Так, для більшості сценаріїв. Ізоляція бота окремими акаунтами й номерами телефонів - зменшує зону ураження, якщо щось піде не так. Це також спрощує ротацію - облікових даних або відкликання доступу без впливу на ваші особисті акаунти. + + Так, для більшості конфігурацій. Ізоляція бота окремими обліковими записами й номерами телефонів + зменшує радіус ураження, якщо щось піде не так. Це також полегшує ротацію + облікових даних або відкликання доступу без впливу на ваші особисті облікові записи. - Починайте з малого. Давайте доступ лише до тих інструментів і акаунтів, які вам справді потрібні, і розширюйте + Починайте з малого. Надавайте доступ лише до тих інструментів і облікових записів, які вам справді потрібні, і розширюйте пізніше, якщо буде потрібно. - Документація: [Безпека](/uk/gateway/security), [Pairing](/uk/channels/pairing). + Документація: [Безпека](/uk/gateway/security), [Спарювання](/uk/channels/pairing). - - Ми **не** рекомендуємо повну автономію над вашими особистими повідомленнями. Найбезпечніший шаблон: + + Ми **не** рекомендуємо повну автономність над вашими особистими повідомленнями. Найбезпечніший шаблон: - - Тримайте DM у режимі **pairing** або з жорстким allowlist. - - Використовуйте **окремий номер або акаунт**, якщо хочете, щоб він писав від вашого імені. - - Нехай він створює чернетки, а ви **погоджуйте перед надсиланням**. + - Тримайте DM у **режимі спарювання** або в жорсткому allowlist. + - Використовуйте **окремий номер або обліковий запис**, якщо хочете, щоб він писав від вашого імені. + - Нехай він створює чернетку, а ви **підтверджуєте перед надсиланням**. - Якщо хочете поекспериментувати, робіть це на окремому акаунті й тримайте його ізольованим. Дивіться + Якщо хочете поекспериментувати, робіть це на окремому обліковому записі й тримайте все ізольованим. Див. [Безпека](/uk/gateway/security). - Так, **якщо** агент призначений лише для чату, а вхідні дані довірені. Менші рівні - більш схильні до перехоплення інструкціями, тому уникайте їх для агентів з увімкненими інструментами - або під час читання ненадійного вмісту. Якщо вам усе ж потрібна менша модель, жорстко обмежте - інструменти й запускайте все в ізоляції. Дивіться [Безпека](/uk/gateway/security). + Так, **якщо** агент лише для чату, а вхідні дані довірені. Менші рівні + більш схильні до перехоплення інструкцій, тому уникайте їх для агентів з увімкненими інструментами + або коли читаєте недовірений вміст. Якщо вам усе ж потрібно використовувати меншу модель, жорстко обмежте + інструменти й запускайте всередині sandbox. Див. [Безпека](/uk/gateway/security). - - Pairing codes надсилаються **лише** коли невідомий відправник пише боту і + + Коди спарювання надсилаються **лише** тоді, коли невідомий відправник пише боту і `dmPolicy: "pairing"` увімкнено. Сам по собі `/start` не генерує код. - Перевірте очікувані запити: + Перевірте запити в черзі: ```bash openclaw pairing list telegram ``` Якщо вам потрібен негайний доступ, додайте свій sender id в allowlist або встановіть `dmPolicy: "open"` - для цього акаунта. + для цього облікового запису. - - Ні. Типова політика WhatsApp DM — **pairing**. Невідомі відправники отримують лише pairing code, а їхнє повідомлення **не обробляється**. OpenClaw відповідає лише на чати, які він отримує, або на явні надсилання, які ви запускаєте. + + Ні. Типова політика WhatsApp DM — **спарювання**. Невідомі відправники отримують лише код спарювання, а їхнє повідомлення **не обробляється**. OpenClaw відповідає лише на чати, які він отримує, або на явні надсилання, які ви самі запускаєте. - Погодження pairing: + Схвалити спарювання можна так: ```bash openclaw pairing approve whatsapp ``` - Перелік очікуваних запитів: + Переглянути запити в черзі: ```bash openclaw pairing list whatsapp @@ -3203,13 +3205,13 @@ x-i18n: -## Команди чату, скасування завдань і «воно не зупиняється» +## Команди чату, скасування завдань і "він не зупиняється" - Більшість внутрішніх або інструментальних повідомлень з’являються лише тоді, коли для цієї сесії ввімкнено **verbose**, **trace** або **reasoning**. + Більшість внутрішніх або службових повідомлень з’являються лише тоді, коли для цієї сесії ввімкнено **verbose**, **trace** або **reasoning**. - Виправлення в тому чаті, де ви це бачите: + Виправлення в чаті, де ви це бачите: ``` /verbose off @@ -3217,16 +3219,16 @@ x-i18n: /reasoning off ``` - Якщо все одно занадто шумно, перевірте налаштування сесії в Control UI і встановіть verbose - на **inherit**. Також переконайтеся, що ви не використовуєте профіль бота з `verboseDefault`, установленим - у `on` у конфігурації. + Якщо все ще занадто шумно, перевірте налаштування сесії в Control UI і встановіть verbose + на **inherit**. Також переконайтеся, що ви не використовуєте профіль бота, де `verboseDefault` у конфігурації встановлено + в `on`. - Документація: [Thinking and verbose](/uk/tools/thinking), [Безпека](/uk/gateway/security#reasoning-verbose-output-in-groups). + Документація: [Thinking і verbose](/uk/tools/thinking), [Безпека](/uk/gateway/security#reasoning-verbose-output-in-groups). - Надішліть будь-що з цього **як окреме повідомлення** (без слеша): + Надішліть будь-який із цих варіантів **як окреме повідомлення** (без слеша): ``` stop @@ -3250,7 +3252,7 @@ x-i18n: interrupt ``` - Це тригери скасування (а не slash-команди). + Це тригери переривання (не slash-команди). Для фонових процесів (з інструмента exec) ви можете попросити агента виконати: @@ -3258,17 +3260,17 @@ x-i18n: process action:kill sessionId:XXX ``` - Огляд slash-команд: дивіться [Slash-команди](/uk/tools/slash-commands). + Огляд slash-команд: див. [Slash commands](/uk/tools/slash-commands). - Більшість команд потрібно надсилати як **окреме** повідомлення, що починається з `/`, але кілька скорочень (наприклад `/status`) також працюють inline для відправників із allowlist. + Більшість команд треба надсилати як **окреме** повідомлення, яке починається з `/`, але кілька shortcut-ів (як-от `/status`) також працюють inline для відправників з allowlist. - OpenClaw блокує повідомлення **між різними провайдерами** за замовчуванням. Якщо виклик інструмента прив’язаний - до Telegram, він не надсилатиме в Discord, доки ви явно цього не дозволите. + OpenClaw типово блокує повідомлення **між різними провайдерами**. Якщо виклик інструмента прив’язано + до Telegram, він не надсилатиме до Discord, доки ви явно цього не дозволите. - Увімкніть міжпровайдерний обмін повідомленнями для агента: + Увімкніть міжпровайдерські повідомлення для агента: ```json5 { @@ -3283,17 +3285,17 @@ x-i18n: } ``` - Після редагування конфігурації перезапустіть gateway. + Перезапустіть gateway після редагування конфігурації. - - Режим черги керує тим, як нові повідомлення взаємодіють із поточним запуском. Використовуйте `/queue`, щоб змінити режими: + + Queue mode визначає, як нові повідомлення взаємодіють із уже виконуваним запуском. Використовуйте `/queue`, щоб змінити режими: - `steer` - нові повідомлення перенаправляють поточне завдання - `followup` - повідомлення виконуються по одному - - `collect` - збирає повідомлення пакетом і відповідає один раз (типово) - - `steer-backlog` - спрямувати зараз, а потім обробити чергу + - `collect` - повідомлення збираються в пакет і надсилається одна відповідь (типово) + - `steer-backlog` - перенаправити зараз, а потім обробити чергу - `interrupt` - перервати поточний запуск і почати заново Ви можете додавати параметри на кшталт `debounce:2s cap:25 drop:summarize` для режимів followup. @@ -3301,11 +3303,11 @@ x-i18n: -## Інше +## Різне - - В OpenClaw облікові дані та вибір моделі — це окремі речі. Установлення `ANTHROPIC_API_KEY` (або збереження API key Anthropic в auth profiles) вмикає автентифікацію, але фактична модель за замовчуванням — це те, що ви налаштували в `agents.defaults.model.primary` (наприклад, `anthropic/claude-sonnet-4-6` або `anthropic/claude-opus-4-6`). Якщо ви бачите `No credentials found for profile "anthropic:default"`, це означає, що Gateway не зміг знайти облікові дані Anthropic в очікуваному `auth-profiles.json` для агента, який зараз працює. + + У OpenClaw облікові дані та вибір моделі розділені. Установлення `ANTHROPIC_API_KEY` (або збереження API key Anthropic у профілях автентифікації) вмикає автентифікацію, але фактична типова модель — це те, що ви налаштували в `agents.defaults.model.primary` (наприклад, `anthropic/claude-sonnet-4-6` або `anthropic/claude-opus-4-6`). Якщо ви бачите `No credentials found for profile "anthropic:default"`, це означає, що Gateway не зміг знайти облікові дані Anthropic в очікуваному `auth-profiles.json` для агента, який зараз працює. diff --git a/docs/uk/install/ansible.md b/docs/uk/install/ansible.md index 541d2fce4..f3c48c33d 100644 --- a/docs/uk/install/ansible.md +++ b/docs/uk/install/ansible.md @@ -1,43 +1,43 @@ --- read_when: - Вам потрібне автоматизоване розгортання сервера з посиленням безпеки - - Вам потрібне ізольоване firewall-налаштування з доступом через VPN + - Вам потрібне налаштування з ізоляцією брандмауером і доступом через VPN - Ви розгортаєте на віддалених серверах Debian/Ubuntu -summary: Автоматизоване, захищене встановлення OpenClaw з Ansible, Tailscale VPN та ізоляцією через firewall +summary: Автоматизоване, захищене встановлення OpenClaw за допомогою Ansible, VPN Tailscale та ізоляції брандмауером title: Ansible x-i18n: - generated_at: "2026-04-05T18:06:09Z" + generated_at: "2026-04-20T18:29:30Z" model: gpt-5.4 provider: openai - source_hash: 27433c3b4afa09406052e428be7b1990476067e47ab8abf7145ff9547b37909a + source_hash: 2a23374c971a1f3163dd18c32e553ebaad55b2542c1f25f49bcc9ae464d679e8 source_path: install/ansible.md workflow: 15 --- -# Встановлення через Ansible +# Встановлення Ansible Розгорніть OpenClaw на production-серверах за допомогою **[openclaw-ansible](https://github.com/openclaw/openclaw-ansible)** — автоматизованого інсталятора з архітектурою, орієнтованою на безпеку. -Репозиторій [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) є джерелом істини для розгортання через Ansible. Ця сторінка — короткий огляд. +Репозиторій [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) є основним джерелом правди для розгортання через Ansible. Ця сторінка — короткий огляд. ## Передумови -| Вимога | Докладніше | +| Вимога | Деталі | | ----------- | --------------------------------------------------------- | -| **OS** | Debian 11+ або Ubuntu 20.04+ | -| **Доступ** | Привілеї root або sudo | -| **Мережа** | Підключення до інтернету для встановлення пакетів | +| **ОС** | Debian 11+ або Ubuntu 20.04+ | +| **Доступ** | Права root або sudo | +| **Мережа** | Підключення до інтернету для встановлення пакунків | | **Ansible** | 2.14+ (встановлюється автоматично скриптом швидкого старту) | ## Що ви отримаєте -- **Безпека, орієнтована на firewall** — UFW + ізоляція Docker (публічно доступні лише SSH + Tailscale) -- **Tailscale VPN** — безпечний віддалений доступ без публічного відкриття сервісів +- **Безпека, орієнтована насамперед на брандмауер** — UFW + ізоляція Docker (доступні лише SSH + Tailscale) +- **VPN Tailscale** — безпечний віддалений доступ без публічного відкриття сервісів - **Docker** — ізольовані sandbox-контейнери, прив’язки лише до localhost - **Багаторівневий захист** — 4-рівнева архітектура безпеки -- **Інтеграція з systemd** — автозапуск під час завантаження з посиленням захисту +- **Інтеграція з Systemd** — автоматичний запуск під час завантаження з посиленням безпеки - **Налаштування однією командою** — повне розгортання за лічені хвилини ## Швидкий старт @@ -50,17 +50,19 @@ curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/inst ## Що буде встановлено -Ansible playbook встановлює й налаштовує: +Ansible playbook встановлює та налаштовує: 1. **Tailscale** — mesh VPN для безпечного віддаленого доступу -2. **UFW firewall** — лише порти SSH + Tailscale -3. **Docker CE + Compose V2** — для sandbox агентів -4. **Node.js 24 + pnpm** — залежності runtime (Node 22 LTS, наразі `22.14+`, і далі підтримується) -5. **OpenClaw** — на хості, не в контейнері -6. **Сервіс systemd** — автозапуск із посиленням безпеки +2. **Брандмауер UFW** — лише порти SSH + Tailscale +3. **Docker CE + Compose V2** — для стандартного sandbox-бекенда агента +4. **Node.js 24 + pnpm** — залежності середовища виконання (Node 22 LTS, наразі `22.14+`, залишається підтримуваним) +5. **OpenClaw** — на хості, не контейнеризований +6. **Сервіс Systemd** — автозапуск із посиленням безпеки -Gateway запускається безпосередньо на хості (не в Docker), але sandbox агентів використовують Docker для ізоляції. Докладніше див. у [Sandboxing](/gateway/sandboxing). +Gateway працює безпосередньо на хості (не в Docker). Sandbox-ізоляція агента є +необов’язковою; цей playbook встановлює Docker, оскільки це стандартний sandbox- +бекенд. Докладніше та про інші бекенди див. у [Sandboxing](/uk/gateway/sandboxing). ## Налаштування після встановлення @@ -72,7 +74,7 @@ Gateway запускається безпосередньо на хості (н ``` - Скрипт після встановлення проведе вас через налаштування параметрів OpenClaw. + Післяінсталяційний скрипт допоможе вам налаштувати параметри OpenClaw. Увійдіть у WhatsApp, Telegram, Discord або Signal: @@ -87,7 +89,7 @@ Gateway запускається безпосередньо на хості (н ``` - Приєднайтеся до своєї VPN mesh для безпечного віддаленого доступу. + Приєднайтеся до вашої VPN mesh-мережі для безпечного віддаленого доступу. @@ -97,7 +99,7 @@ Gateway запускається безпосередньо на хості (н # Перевірити стан сервісу sudo systemctl status openclaw -# Переглянути live-журнали +# Переглянути журнали в реальному часі sudo journalctl -u openclaw -f # Перезапустити gateway @@ -112,27 +114,27 @@ openclaw channels login Розгортання використовує 4-рівневу модель захисту: -1. **Firewall (UFW)** — публічно відкриті лише SSH (22) + Tailscale (41641/udp) -2. **VPN (Tailscale)** — gateway доступний лише через VPN mesh +1. **Брандмауер (UFW)** — публічно відкриті лише SSH (22) + Tailscale (41641/udp) +2. **VPN (Tailscale)** — Gateway доступний лише через VPN mesh 3. **Ізоляція Docker** — ланцюг iptables DOCKER-USER запобігає зовнішньому відкриттю портів -4. **Посилення systemd** — NoNewPrivileges, PrivateTmp, непривілейований користувач +4. **Посилення Systemd** — NoNewPrivileges, PrivateTmp, непривілейований користувач -Щоб перевірити зовнішню поверхню атаки: +Щоб перевірити вашу зовнішню поверхню атаки: ```bash nmap -p- YOUR_SERVER_IP ``` -Має бути відкритий лише порт 22 (SSH). Усі інші сервіси (gateway, Docker) заблоковано. +Має бути відкритий лише порт 22 (SSH). Усі інші сервіси (gateway, Docker) заблоковані. -Docker установлюється для sandbox агентів (ізольоване виконання інструментів), а не для запуску самого gateway. Див. [Multi-Agent Sandbox and Tools](/tools/multi-agent-sandbox-tools) щодо конфігурації sandbox. +Docker встановлюється для sandbox-середовищ агентів (ізольоване виконання інструментів), а не для запуску самого gateway. Див. [Multi-Agent Sandbox and Tools](/uk/tools/multi-agent-sandbox-tools) щодо налаштування sandbox. ## Ручне встановлення -Якщо ви віддаєте перевагу ручному контролю замість автоматизації: +Якщо ви надаєте перевагу ручному контролю над автоматизацією: - + ```bash sudo apt update && sudo apt install -y ansible git ``` @@ -143,7 +145,7 @@ Docker установлюється для sandbox агентів (ізольо cd openclaw-ansible ``` - + ```bash ansible-galaxy collection install -r requirements.yml ``` @@ -153,7 +155,7 @@ Docker установлюється для sandbox агентів (ізольо ./run-playbook.sh ``` - Або запустіть напряму, а потім вручну виконайте скрипт налаштування: + Або запустіть безпосередньо, а потім вручну виконайте скрипт налаштування: ```bash ansible-playbook playbook.yml --ask-become-pass # Потім виконайте: /tmp/openclaw-setup.sh @@ -164,23 +166,23 @@ Docker установлюється для sandbox агентів (ізольо ## Оновлення -Інсталятор Ansible налаштовує OpenClaw для ручних оновлень. Стандартний сценарій оновлення див. в [Updating](/install/updating). +Інсталятор Ansible налаштовує OpenClaw для ручних оновлень. Стандартний процес оновлення див. у [Updating](/uk/install/updating). -Щоб повторно запустити playbook Ansible (наприклад, для змін конфігурації): +Щоб повторно запустити Ansible playbook (наприклад, для змін конфігурації): ```bash cd openclaw-ansible ./run-playbook.sh ``` -Це ідемпотентно й безпечно для багаторазового запуску. +Це ідемпотентно та безпечно для багаторазового запуску. ## Усунення несправностей - - - Спочатку переконайтеся, що ви можете підключитися через Tailscale VPN - - Доступ через SSH (порт 22) завжди дозволений + + - Спочатку переконайтеся, що ви маєте доступ через VPN Tailscale + - Доступ SSH (порт 22) завжди дозволений - Gateway за задумом доступний лише через Tailscale @@ -188,7 +190,7 @@ cd openclaw-ansible # Перевірити журнали sudo journalctl -u openclaw -n 100 - # Перевірити права доступу + # Перевірити дозволи sudo ls -la /opt/openclaw # Перевірити ручний запуск @@ -198,9 +200,9 @@ cd openclaw-ansible ``` - + ```bash - # Перевірити, чи працює Docker + # Переконатися, що Docker запущений sudo systemctl status docker # Перевірити образ sandbox @@ -221,17 +223,17 @@ cd openclaw-ansible -## Розширена конфігурація +## Розширене налаштування -Докладніше про архітектуру безпеки та усунення несправностей див. у репозиторії openclaw-ansible: +Детальну інформацію про архітектуру безпеки та усунення несправностей див. у репозиторії openclaw-ansible: -- [Архітектура безпеки](https://github.com/openclaw/openclaw-ansible/blob/main/docs/security.md) -- [Технічні деталі](https://github.com/openclaw/openclaw-ansible/blob/main/docs/architecture.md) -- [Посібник з усунення несправностей](https://github.com/openclaw/openclaw-ansible/blob/main/docs/troubleshooting.md) +- [Security Architecture](https://github.com/openclaw/openclaw-ansible/blob/main/docs/security.md) +- [Technical Details](https://github.com/openclaw/openclaw-ansible/blob/main/docs/architecture.md) +- [Troubleshooting Guide](https://github.com/openclaw/openclaw-ansible/blob/main/docs/troubleshooting.md) ## Пов’язане -- [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) -- повний посібник із розгортання -- [Docker](/install/docker) -- налаштування gateway у контейнері -- [Sandboxing](/gateway/sandboxing) -- конфігурація sandbox агентів -- [Multi-Agent Sandbox and Tools](/tools/multi-agent-sandbox-tools) -- ізоляція для кожного агента окремо +- [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) — повний посібник із розгортання +- [Docker](/uk/install/docker) — контейнеризоване налаштування gateway +- [Sandboxing](/uk/gateway/sandboxing) — налаштування sandbox агента +- [Multi-Agent Sandbox and Tools](/uk/tools/multi-agent-sandbox-tools) — ізоляція для кожного агента diff --git a/docs/uk/install/docker.md b/docs/uk/install/docker.md index d527ae4d9..9d006ee02 100644 --- a/docs/uk/install/docker.md +++ b/docs/uk/install/docker.md @@ -1,48 +1,48 @@ --- read_when: - - Ви хочете контейнеризований gateway замість локальних встановлень - - Ви перевіряєте Docker-потік -summary: Необов’язкове налаштування та онбординг OpenClaw на основі Docker + - Ви хочете контейнеризований Gateway замість локальних встановлень + - Ви перевіряєте потік Docker +summary: Необов’язкове налаштування та онбординг для OpenClaw на основі Docker title: Docker x-i18n: - generated_at: "2026-04-05T21:33:22Z" + generated_at: "2026-04-20T18:29:30Z" model: gpt-5.4 provider: openai - source_hash: d6aa0453340d7683b4954316274ba6dd1aa7c0ce2483e9bd8ae137ff4efd4c3c + source_hash: f8d3e346ca60daa9908aef0846c9052321087af7dd2c919ce79de4d5925136a2 source_path: install/docker.md workflow: 15 --- # Docker (необов’язково) -Docker **необов’язковий**. Використовуйте його лише якщо хочете контейнеризований gateway або перевіряєте Docker-потік. +Docker **необов’язковий**. Використовуйте його лише якщо вам потрібен контейнеризований Gateway або якщо ви хочете перевірити потік Docker. ## Чи підходить мені Docker? -- **Так**: вам потрібне ізольоване, тимчасове середовище gateway або ви хочете запускати OpenClaw на хості без локальних встановлень. -- **Ні**: ви запускаєте на власній машині й просто хочете найшвидший цикл розробки. Натомість використовуйте звичайний процес встановлення. -- **Примітка щодо sandboxing**: ізоляція агентів також використовує Docker, але для цього **не** потрібно запускати весь gateway у Docker. Див. [Sandboxing](/uk/gateway/sandboxing). +- **Так**: вам потрібне ізольоване, тимчасове середовище Gateway або ви хочете запустити OpenClaw на хості без локальних встановлень. +- **Ні**: ви запускаєте на власній машині й просто хочете найшвидший цикл розробки. Замість цього використовуйте звичайний потік встановлення. +- **Примітка про ізоляцію**: типовий бекенд sandbox використовує Docker, коли sandboxing увімкнено, але sandboxing вимкнено типово й **не** вимагає запуску всього Gateway у Docker. Також доступні бекенди sandbox SSH та OpenShell. Див. [Sandboxing](/uk/gateway/sandboxing). ## Передумови - Docker Desktop (або Docker Engine) + Docker Compose v2 -- Щонайменше 2 ГБ RAM для збирання образу (`pnpm install` може бути завершено через OOM на хостах із 1 ГБ з кодом виходу 137) -- Достатньо місця на диску для образів і журналів -- Якщо запускаєте на VPS/публічному хості, перегляньте - [Посилення безпеки для мережевої доступності](/uk/gateway/security), - особливо політику фаєрвола Docker `DOCKER-USER`. +- Щонайменше 2 ГБ RAM для збірки образу (`pnpm install` може бути примусово завершений через OOM на хостах із 1 ГБ із кодом виходу 137) +- Достатньо місця на диску для образів і логів +- Якщо запускаєте на VPS/публічному хості, ознайомтеся з + [Посиленням безпеки для мережевої доступності](/uk/gateway/security), + особливо з політикою брандмауера Docker `DOCKER-USER`. ## Контейнеризований Gateway - У корені репозиторію виконайте скрипт налаштування: + У корені репозиторію запустіть скрипт налаштування: ```bash ./scripts/docker/setup.sh ``` - Це локально збирає образ gateway. Щоб натомість використати попередньо зібраний образ: + Це локально збере образ Gateway. Щоб натомість використати попередньо зібраний образ: ```bash export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest" @@ -56,23 +56,22 @@ Docker **необов’язковий**. Використовуйте його - Скрипт налаштування автоматично запускає онбординг. Він: + Скрипт налаштування запускає онбординг автоматично. Він: - запросить API-ключі провайдера - - згенерує токен gateway і запише його в `.env` - - запустить gateway через Docker Compose + - згенерує токен Gateway і запише його в `.env` + - запустить Gateway через Docker Compose - Під час налаштування онбординг перед запуском і запис конфігурації виконуються - безпосередньо через `openclaw-gateway`. `openclaw-cli` призначений для команд, - які ви запускаєте після того, як контейнер gateway уже існує. + Під час налаштування онбординг до запуску та запис конфігурації виконуються безпосередньо через + `openclaw-gateway`. `openclaw-cli` призначений для команд, які ви запускаєте після того, + як контейнер Gateway уже існує. - + Відкрийте `http://127.0.0.1:18789/` у браузері та вставте налаштований - спільний секрет у Settings. Скрипт налаштування типово записує токен у `.env`; - якщо ви перемкнете конфігурацію контейнера на автентифікацію за паролем, - використовуйте натомість цей пароль. + спільний секрет у Settings. Скрипт налаштування типово записує токен у `.env`; якщо ви переключите конфігурацію контейнера на автентифікацію паролем, використовуйте натомість цей + пароль. Потрібна URL-адреса знову? @@ -101,7 +100,7 @@ Docker **необов’язковий**. Використовуйте його -### Ручний процес +### Ручний потік Якщо ви віддаєте перевагу виконанню кожного кроку вручну замість використання скрипта налаштування: @@ -116,14 +115,14 @@ docker compose up -d openclaw-gateway Запускайте `docker compose` з кореня репозиторію. Якщо ви ввімкнули `OPENCLAW_EXTRA_MOUNTS` -або `OPENCLAW_HOME_VOLUME`, скрипт налаштування записує `docker-compose.extra.yml`; -додавайте його через `-f docker-compose.yml -f docker-compose.extra.yml`. +або `OPENCLAW_HOME_VOLUME`, скрипт налаштування запише `docker-compose.extra.yml`; +додайте його через `-f docker-compose.yml -f docker-compose.extra.yml`. -Оскільки `openclaw-cli` використовує спільний мережевий простір імен з `openclaw-gateway`, -це інструмент для використання після запуску. До `docker compose up -d openclaw-gateway` -виконуйте онбординг і запис конфігурації під час налаштування через `openclaw-gateway` з +Оскільки `openclaw-cli` використовує спільний простір імен мережі з `openclaw-gateway`, це +інструмент після запуску. До `docker compose up -d openclaw-gateway` виконуйте онбординг +і записи конфігурації під час налаштування через `openclaw-gateway` з `--no-deps --entrypoint node`. @@ -131,28 +130,28 @@ docker compose up -d openclaw-gateway Скрипт налаштування приймає такі необов’язкові змінні середовища: -| Змінна | Призначення | -| ----------------------------- | ---------------------------------------------------------------- | -| `OPENCLAW_IMAGE` | Використовувати віддалений образ замість локального збирання | -| `OPENCLAW_DOCKER_APT_PACKAGES` | Встановити додаткові apt-пакети під час збирання (через пробіл) | -| `OPENCLAW_EXTENSIONS` | Попередньо встановити залежності розширень під час збирання (назви через пробіл) | -| `OPENCLAW_EXTRA_MOUNTS` | Додаткові bind mounts хоста (через кому `source:target[:opts]`) | -| `OPENCLAW_HOME_VOLUME` | Зберігати `/home/node` в іменованому Docker volume | -| `OPENCLAW_SANDBOX` | Увімкнути bootstrap sandbox (`1`, `true`, `yes`, `on`) | -| `OPENCLAW_DOCKER_SOCKET` | Перевизначити шлях до Docker socket | +| Variable | Purpose | +| ------------------------------ | ---------------------------------------------------------------- | +| `OPENCLAW_IMAGE` | Використати віддалений образ замість локальної збірки | +| `OPENCLAW_DOCKER_APT_PACKAGES` | Встановити додаткові apt-пакети під час збірки (назви через пробіл) | +| `OPENCLAW_EXTENSIONS` | Попередньо встановити залежності extensions під час збірки (назви через пробіл) | +| `OPENCLAW_EXTRA_MOUNTS` | Додаткові bind mounts хоста (через кому у форматі `source:target[:opts]`) | +| `OPENCLAW_HOME_VOLUME` | Зберігати `/home/node` в іменованому Docker volume | +| `OPENCLAW_SANDBOX` | Увімкнути bootstrap sandbox (`1`, `true`, `yes`, `on`) | +| `OPENCLAW_DOCKER_SOCKET` | Перевизначити шлях до Docker socket | -### Перевірки стану +### Перевірки працездатності -Кінцеві точки перевірки контейнера (автентифікація не потрібна): +Кінцеві точки probe контейнера (автентифікація не потрібна): ```bash -curl -fsS http://127.0.0.1:18789/healthz # liveness -curl -fsS http://127.0.0.1:18789/readyz # readiness +curl -fsS http://127.0.0.1:18789/healthz # live-перевірка +curl -fsS http://127.0.0.1:18789/readyz # перевірка готовності ``` Образ Docker містить вбудований `HEALTHCHECK`, який опитує `/healthz`. -Якщо перевірки продовжують завершуватися невдало, Docker позначає контейнер як `unhealthy`, -а системи оркестрації можуть перезапустити або замінити його. +Якщо перевірки продовжують завершуватися помилкою, Docker позначає контейнер як `unhealthy`, і +системи оркестрації можуть перезапустити або замінити його. Автентифікований детальний знімок стану: @@ -162,58 +161,59 @@ docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLA ### LAN проти loopback -`scripts/docker/setup.sh` типово встановлює `OPENCLAW_GATEWAY_BIND=lan`, щоб доступ із хоста до -`http://127.0.0.1:18789` працював із публікацією порту Docker. +`scripts/docker/setup.sh` типово встановлює `OPENCLAW_GATEWAY_BIND=lan`, тож доступ хоста до +`http://127.0.0.1:18789` працює з публікацією портів Docker. -- `lan` (типово): браузер і CLI на хості можуть звертатися до опублікованого порту gateway. -- `loopback`: напряму до gateway можуть звертатися лише процеси всередині мережевого простору імен контейнера. +- `lan` (типово): браузер і CLI на хості можуть досягти опублікованого порту Gateway. +- `loopback`: лише процеси всередині простору імен мережі контейнера можуть + напряму досягти Gateway. Використовуйте значення режиму прив’язки в `gateway.bind` (`lan` / `loopback` / `custom` / `tailnet` / `auto`), а не псевдоніми хоста на кшталт `0.0.0.0` або `127.0.0.1`. -### Сховище та збереження даних +### Сховище й збереження даних -Docker Compose монтує `OPENCLAW_CONFIG_DIR` до `/home/node/.openclaw` і -`OPENCLAW_WORKSPACE_DIR` до `/home/node/.openclaw/workspace`, тож ці шляхи +Docker Compose монтує `OPENCLAW_CONFIG_DIR` через bind-mount у `/home/node/.openclaw` і +`OPENCLAW_WORKSPACE_DIR` у `/home/node/.openclaw/workspace`, тож ці шляхи зберігаються після заміни контейнера. -У цьому змонтованому каталозі конфігурації OpenClaw зберігає: +Цей змонтований каталог конфігурації — місце, де OpenClaw зберігає: - `openclaw.json` для конфігурації поведінки - `agents//agent/auth-profiles.json` для збереженої OAuth/API-key автентифікації провайдерів - `.env` для секретів середовища виконання на основі env, таких як `OPENCLAW_GATEWAY_TOKEN` -Повні відомості про збереження даних у VM-розгортаннях див. у -[Docker VM Runtime - Що і де зберігається](/uk/install/docker-vm-runtime#what-persists-where). +Повні відомості про збереження даних у розгортаннях на VM див. у +[Docker VM Runtime - What persists where](/uk/install/docker-vm-runtime#what-persists-where). -**Точки зростання дискового простору:** стежте за `media/`, файлами session JSONL, `cron/runs/*.jsonl` -і ротаційними файловими журналами в `/tmp/openclaw/`. +**Гарячі точки зростання диска:** стежте за `media/`, файлами JSONL сесій, `cron/runs/*.jsonl`, +і циклічними файловими логами в `/tmp/openclaw/`. ### Допоміжні команди оболонки (необов’язково) -Для зручнішого щоденного керування Docker установіть `ClawDock`: +Для зручнішого повсякденного керування Docker встановіть `ClawDock`: ```bash mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc ``` -Якщо ви встановили ClawDock зі старого raw-шляху `scripts/shell-helpers/clawdock-helpers.sh`, повторно виконайте наведену вище команду встановлення, щоб ваш локальний файл helpers відстежував нове розташування. +Якщо ви встановили ClawDock зі старого raw-шляху `scripts/shell-helpers/clawdock-helpers.sh`, повторно виконайте наведену вище команду встановлення, щоб ваш локальний файл helper відстежував нове розташування. -Потім використовуйте `clawdock-start`, `clawdock-stop`, `clawdock-dashboard` тощо. Виконайте +Потім використовуйте `clawdock-start`, `clawdock-stop`, `clawdock-dashboard` тощо. Запустіть `clawdock-help`, щоб побачити всі команди. -Див. [ClawDock](/uk/install/clawdock), щоб переглянути повний посібник із helpers. +Повний посібник із helper-команд див. у [ClawDock](/uk/install/clawdock). - + ```bash export OPENCLAW_SANDBOX=1 ./scripts/docker/setup.sh ``` - Нестандартний шлях до socket (наприклад, rootless Docker): + Користувацький шлях до socket (наприклад, rootless Docker): ```bash export OPENCLAW_SANDBOX=1 @@ -228,7 +228,7 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc - Вимкніть виділення pseudo-TTY для Compose за допомогою `-T`: + Вимкніть виділення pseudo-TTY Compose за допомогою `-T`: ```bash docker compose run -T --rm openclaw-cli gateway probe @@ -237,16 +237,16 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc - + `openclaw-cli` використовує `network_mode: "service:openclaw-gateway"`, тому команди CLI - можуть звертатися до gateway через `127.0.0.1`. Розглядайте це як спільну - межу довіри. Конфігурація compose прибирає `NET_RAW`/`NET_ADMIN` та вмикає + можуть досягати Gateway через `127.0.0.1`. Розглядайте це як межу спільної + довіри. Конфігурація compose прибирає `NET_RAW`/`NET_ADMIN` і вмикає `no-new-privileges` для `openclaw-cli`. - - Образ працює від імені `node` (uid 1000). Якщо ви бачите помилки прав доступу до - `/home/node/.openclaw`, переконайтеся, що ваші bind mounts хоста належать uid 1000: + + Образ працює від імені `node` (uid 1000). Якщо ви бачите помилки дозволів для + `/home/node/.openclaw`, переконайтеся, що bind mounts хоста належать uid 1000: ```bash sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace @@ -255,8 +255,8 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc - Упорядкуйте Dockerfile так, щоб шари залежностей кешувалися. Це дозволяє не запускати - `pnpm install` повторно, доки не зміняться lockfile-файли: + Упорядкуйте Dockerfile так, щоб шари залежностей кешувалися. Це дозволяє уникнути повторного запуску + `pnpm install`, якщо lockfiles не змінювалися: ```dockerfile FROM node:24-bookworm @@ -278,13 +278,13 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc - - Типовий образ орієнтований на безпеку та працює від непривілейованого користувача `node`. Для більш + + Типовий образ орієнтований насамперед на безпеку й працює від імені непривілейованого `node`. Для більш функціонального контейнера: 1. **Зберігайте `/home/node`**: `export OPENCLAW_HOME_VOLUME="openclaw_home"` 2. **Вбудуйте системні залежності**: `export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"` - 3. **Установіть браузери Playwright**: + 3. **Встановіть браузери Playwright**: ```bash docker compose run --rm openclaw-cli \ node /app/node_modules/playwright-core/cli.js install chromium @@ -296,42 +296,43 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc - Якщо ви виберете у майстрі OpenAI Codex OAuth, відкриється URL-адреса в браузері. У + Якщо у майстрі ви оберете OpenAI Codex OAuth, він відкриє URL-адресу в браузері. У Docker або headless-середовищах скопіюйте повну URL-адресу перенаправлення, на яку ви потрапите, і вставте її назад у майстер, щоб завершити автентифікацію. - Основний образ Docker використовує `node:24-bookworm` і публікує анотації базового OCI-образу, + Основний образ Docker використовує `node:24-bookworm` і публікує анотації OCI базового образу, зокрема `org.opencontainers.image.base.name`, `org.opencontainers.image.source` та інші. Див. - [Анотації OCI-образу](https://github.com/opencontainers/image-spec/blob/main/annotations.md). + [OCI image annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md). ### Запуск на VPS? Див. [Hetzner (Docker VPS)](/uk/install/hetzner) і -[Docker VM Runtime](/uk/install/docker-vm-runtime), щоб переглянути кроки спільного VM-розгортання, -зокрема вбудовування бінарних файлів, збереження даних і оновлення. +[Docker VM Runtime](/uk/install/docker-vm-runtime) для спільних кроків розгортання на VM, +зокрема вбудовування бінарних файлів, збереження даних та оновлення. ## Sandbox агента -Коли ввімкнено `agents.defaults.sandbox`, gateway виконує інструменти агента -(shell, читання/запис файлів тощо) в ізольованих Docker-контейнерах, тоді як -сам gateway залишається на хості. Це дає вам жорстку межу навколо недовірених або -багатокористувацьких сесій агентів без контейнеризації всього gateway. +Коли `agents.defaults.sandbox` увімкнено з бекендом Docker, Gateway +виконує інструменти агента (shell, читання/запис файлів тощо) в ізольованих Docker +контейнерах, тоді як сам Gateway залишається на хості. Це дає вам жорстку межу +навколо недовірених або багатокористувацьких сесій агента без контейнеризації всього +Gateway. -Область дії sandbox може бути на рівні агента (типово), сесії або спільною. Для кожної області -використовується власний workspace, змонтований у `/workspace`. Ви також можете налаштувати -політики дозволу/заборони інструментів, ізоляцію мережі, обмеження ресурсів і -контейнери браузера. +Область дії sandbox може бути на рівні агента (типово), на рівні сесії або спільною. Кожна область +має власний workspace, змонтований у `/workspace`. Ви також можете налаштувати +політики дозволу/заборони інструментів, ізоляцію мережі, ліміти ресурсів і браузерні +контейнери. -Повну інформацію про конфігурацію, образи, примітки щодо безпеки та профілі з кількома агентами див. тут: +Повну конфігурацію, образи, примітки щодо безпеки та багатопрофільні сценарії для агентів див. тут: -- [Sandboxing](/uk/gateway/sandboxing) -- повний довідник із sandbox -- [OpenShell](/uk/gateway/openshell) -- інтерактивний доступ до shell у sandbox-контейнерах -- [Multi-Agent Sandbox and Tools](/uk/tools/multi-agent-sandbox-tools) -- перевизначення для окремих агентів +- [Sandboxing](/uk/gateway/sandboxing) — повний довідник із sandbox +- [OpenShell](/uk/gateway/openshell) — інтерактивний доступ до shell контейнерів sandbox +- [Multi-Agent Sandbox and Tools](/uk/tools/multi-agent-sandbox-tools) — перевизначення для окремих агентів ### Швидке ввімкнення @@ -354,34 +355,33 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc scripts/sandbox-setup.sh ``` -## Усунення несправностей +## Усунення неполадок - + Зберіть образ sandbox за допомогою [`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh) - або встановіть для `agents.defaults.sandbox.docker.image` свій користувацький образ. - Контейнери автоматично створюються за потреби для кожної сесії. + або встановіть `agents.defaults.sandbox.docker.image` на ваш власний образ. + Контейнери автоматично створюються для кожної сесії за потреби. - - Установіть `docker.user` у UID:GID, що відповідає власнику змонтованого workspace, + + Встановіть `docker.user` у значення UID:GID, яке відповідає власнику змонтованого workspace, або змініть власника папки workspace через chown. - + OpenClaw запускає команди через `sh -lc` (login shell), який зчитує - `/etc/profile` і може скинути PATH. Установіть `docker.env.PATH`, щоб додати - ваші шляхи до користувацьких інструментів на початок, або додайте скрипт у `/etc/profile.d/` - у вашому Dockerfile. + `/etc/profile` і може скидати PATH. Встановіть `docker.env.PATH`, щоб додати + ваші власні шляхи інструментів на початок, або додайте скрипт у `/etc/profile.d/` у вашому Dockerfile. - - VM потрібні щонайменше 2 ГБ RAM. Використайте більший клас машини та повторіть спробу. + + VM потребує щонайменше 2 ГБ RAM. Використайте більший клас машини й повторіть спробу. - - Отримайте нове посилання dashboard і схваліть пристрій браузера: + + Отримайте свіже посилання на dashboard і підтвердьте пристрій браузера: ```bash docker compose run --rm openclaw-cli dashboard --no-open @@ -393,8 +393,8 @@ scripts/sandbox-setup.sh - - Скиньте режим і прив’язку gateway: + + Скиньте режим і bind Gateway: ```bash docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]' @@ -406,8 +406,8 @@ scripts/sandbox-setup.sh ## Пов’язане -- [Install Overview](/uk/install) — усі методи встановлення +- [Install Overview](/uk/install) — усі способи встановлення - [Podman](/uk/install/podman) — альтернатива Docker на базі Podman - [ClawDock](/uk/install/clawdock) — спільнотне налаштування Docker Compose - [Updating](/uk/install/updating) — як підтримувати OpenClaw в актуальному стані -- [Configuration](/uk/gateway/configuration) — конфігурація gateway після встановлення +- [Configuration](/uk/gateway/configuration) — конфігурація Gateway після встановлення diff --git a/docs/uk/tools/skills-config.md b/docs/uk/tools/skills-config.md index 95c6e8fe4..95b345f84 100644 --- a/docs/uk/tools/skills-config.md +++ b/docs/uk/tools/skills-config.md @@ -1,23 +1,23 @@ --- read_when: - - Додавання або зміна конфігурації Skills + - Додавання або змінення конфігурації Skills - Налаштування вбудованого allowlist або поведінки встановлення summary: Схема конфігурації Skills і приклади title: Конфігурація Skills x-i18n: - generated_at: "2026-04-05T18:20:52Z" + generated_at: "2026-04-20T18:30:02Z" model: gpt-5.4 provider: openai - source_hash: 7839f39f68c1442dcf4740b09886e0ef55762ce0d4b9f7b4f493a8c130c84579 + source_hash: 8af3a51af5d6d6af355c529bb8ec0a045046c635d8fff0dec20cd875ec12e88b source_path: tools/skills-config.md workflow: 15 --- # Конфігурація Skills -Більшість конфігурації завантаження/встановлення Skills розташована в `skills` у -`~/.openclaw/openclaw.json`. Видимість Skills для окремих агентів розташована в -`agents.defaults.skills` і `agents.list[].skills`. +Більшість конфігурації завантаження/встановлення Skills розміщується в `skills` у +`~/.openclaw/openclaw.json`. Видимість Skills для конкретного агента розміщується в +`agents.defaults.skills` та `agents.list[].skills`. ```json5 { @@ -30,12 +30,12 @@ x-i18n: }, install: { preferBrew: true, - nodeManager: "npm", // npm | pnpm | yarn | bun (середовище виконання Gateway все одно Node; bun не рекомендовано) + nodeManager: "npm", // npm | pnpm | yarn | bun (середовище виконання Gateway усе ще Node; bun не рекомендовано) }, entries: { "image-lab": { enabled: true, - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // або рядок plaintext + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // або plaintext string env: { GEMINI_API_KEY: "GEMINI_KEY_HERE", }, @@ -48,7 +48,7 @@ x-i18n: ``` Для вбудованої генерації/редагування зображень віддавайте перевагу `agents.defaults.imageGenerationModel` -разом із core-інструментом `image_generate`. `skills.entries.*` потрібен лише для користувацьких або +разом із core-інструментом `image_generate`. `skills.entries.*` призначено лише для custom або сторонніх робочих процесів Skills. Якщо ви вибираєте конкретного провайдера/модель зображень, також налаштуйте @@ -72,8 +72,8 @@ x-i18n: skills: ["github", "weather"], }, list: [ - { id: "writer" }, // успадковує значення за замовчуванням -> github, weather - { id: "docs", skills: ["docs-search"] }, // замінює значення за замовчуванням + { id: "writer" }, // успадковує defaults -> github, weather + { id: "docs", skills: ["docs-search"] }, // замінює defaults { id: "locked-down", skills: [] }, // без Skills ], }, @@ -82,59 +82,59 @@ x-i18n: Правила: -- `agents.defaults.skills`: спільний базовий allowlist для агентів, у яких пропущено +- `agents.defaults.skills`: спільний базовий allowlist для агентів, які не вказують `agents.list[].skills`. -- Пропустіть `agents.defaults.skills`, щоб за замовчуванням не обмежувати Skills. -- `agents.list[].skills`: явний фінальний набір Skills для цього агента; він не - зливається зі значеннями за замовчуванням. +- Не вказуйте `agents.defaults.skills`, щоб за замовчуванням не обмежувати Skills. +- `agents.list[].skills`: явний кінцевий набір Skills для цього агента; він не + об’єднується зі значеннями за замовчуванням. - `agents.list[].skills: []`: не надавати жодних Skills для цього агента. ## Поля -- Вбудовані корені Skills завжди включають `~/.openclaw/skills`, `~/.agents/skills`, +- Вбудовані кореневі каталоги Skills завжди включають `~/.openclaw/skills`, `~/.agents/skills`, `/.agents/skills` і `/skills`. -- `allowBundled`: необов’язковий allowlist лише для **вбудованих** Skills. Якщо встановлено, лише - вбудовані Skills зі списку будуть доступні (керовані, агентські та Skills робочого простору не зачіпаються). +- `allowBundled`: необов’язковий allowlist лише для **вбудованих** Skills. Якщо задано, лише + вбудовані Skills зі списку можуть використовуватися (керовані Skills, Skills агента та робочого простору не зачіпаються). - `load.extraDirs`: додаткові каталоги Skills для сканування (найнижчий пріоритет). -- `load.watch`: стежити за папками Skills і оновлювати знімок Skills (за замовчуванням: true). -- `load.watchDebounceMs`: debounce для подій спостерігача Skills у мілісекундах (за замовчуванням: 250). -- `install.preferBrew`: віддавати перевагу інсталяторам brew, коли вони доступні (за замовчуванням: true). -- `install.nodeManager`: бажаний інсталятор node (`npm` | `pnpm` | `yarn` | `bun`, за замовчуванням: npm). - Це впливає лише на **встановлення Skills**; середовище виконання Gateway все одно має бути Node - (Bun не рекомендовано для WhatsApp/Telegram). - - `openclaw setup --node-manager` є вужчим параметром і наразі приймає лише `npm`, +- `load.watch`: стежити за папками Skills і оновлювати знімок Skills (типово: true). +- `load.watchDebounceMs`: debounce для подій watcher-а Skills у мілісекундах (типово: 250). +- `install.preferBrew`: віддавати перевагу інсталяторам brew, якщо вони доступні (типово: true). +- `install.nodeManager`: бажаний інсталятор Node (`npm` | `pnpm` | `yarn` | `bun`, типово: npm). + Це впливає лише на **встановлення Skills**; середовище виконання Gateway усе ще має бути Node + (`bun` не рекомендовано для WhatsApp/Telegram). + - `openclaw setup --node-manager` є вужчим параметром і наразі приймає `npm`, `pnpm` або `bun`. Установіть `skills.install.nodeManager: "yarn"` вручну, якщо хочете встановлення Skills через Yarn. -- `entries.`: перевизначення для окремого skill. +- `entries.`: перевизначення для окремого Skill. - `agents.defaults.skills`: необов’язковий allowlist Skills за замовчуванням, який успадковують агенти, - у яких пропущено `agents.list[].skills`. -- `agents.list[].skills`: необов’язковий фінальний allowlist Skills для окремого агента; явні - списки замінюють успадковані значення за замовчуванням, а не зливаються з ними. + що не вказують `agents.list[].skills`. +- `agents.list[].skills`: необов’язковий кінцевий allowlist Skills для окремого агента; явні + списки замінюють успадковані значення за замовчуванням, а не об’єднуються з ними. -Поля для окремого skill: +Поля для окремого Skill: -- `enabled`: установіть `false`, щоб вимкнути skill, навіть якщо він вбудований/встановлений. -- `env`: змінні середовища, які додаються до запуску агента (лише якщо вони ще не встановлені). -- `apiKey`: необов’язковий зручний параметр для Skills, які оголошують основну env-змінну. - Підтримує рядок plaintext або об’єкт SecretRef (`{ source, provider, id }`). +- `enabled`: установіть `false`, щоб вимкнути Skill, навіть якщо він вбудований/встановлений. +- `env`: змінні середовища, які додаються під час запуску агента (лише якщо вони ще не встановлені). +- `apiKey`: необов’язкова зручна опція для Skills, які оголошують основну env-змінну. + Підтримує plaintext string або об’єкт SecretRef (`{ source, provider, id }`). ## Примітки -- Ключі в `entries` за замовчуванням відповідають імені skill. Якщо skill визначає +- Ключі в `entries` за замовчуванням відповідають імені Skill. Якщо Skill визначає `metadata.openclaw.skillKey`, використовуйте натомість цей ключ. - Пріоритет завантаження: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → вбудовані Skills → `skills.load.extraDirs`. -- Зміни до Skills підхоплюються на наступному ході агента, коли watcher увімкнено. +- Зміни в Skills застосовуються на наступному ході агента, коли watcher увімкнено. -### Ізольовані Skills + env-змінні +### Sandbox-овані Skills + env-змінні -Коли сесія **ізольована**, процеси Skills працюють усередині Docker. Ізольоване середовище -**не** успадковує хостовий `process.env`. +Коли сесію **sandbox-овано**, процеси Skills працюють усередині налаштованого +sandbox-бекенда. Sandbox **не** успадковує хостовий `process.env`. -Використовуйте одне з такого: +Використовуйте один із варіантів: -- `agents.defaults.sandbox.docker.env` (або `agents.list[].sandbox.docker.env` для окремого агента) -- додайте env у власний образ sandbox +- `agents.defaults.sandbox.docker.env` для Docker-бекенда (або `agents.list[].sandbox.docker.env` для окремого агента) +- вбудуйте env у власний образ sandbox або у віддалене sandbox-середовище Глобальні `env` і `skills.entries..env/apiKey` застосовуються **лише** до запусків на хості.