chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
a8843a086d
commit
ff21d0fdf8
@ -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` плюс один явний виняток для цитати/відповіді.
|
||||
|
||||
Поки цю модель посилення захисту не реалізовано узгоджено в усіх каналах, очікуйте відмінностей залежно від поверхні.
|
||||
Поки цю модель посилення захисту не буде однаково реалізовано в усіх каналах, очікуйте відмінностей залежно від поверхні.
|
||||
|
||||
|
||||
|
||||
|
||||
Якщо ви хочете...
|
||||
|
||||
| Ціль | Що налаштувати |
|
||||
| Мета | Що налаштувати |
|
||||
| -------------------------------------------- | ---------------------------------------------------------- |
|
||||
| Дозволити всі групи, але відповідати лише на @згадки | `groups: { "*": { requireMention: true } }` |
|
||||
| Вимкнути всі відповіді в групах | `groupPolicy: "disabled"` |
|
||||
| Лише певні групи | `groups: { "<group-id>": { ... } }` (без ключа `"*"`) |
|
||||
| Лише ви можете запускати в групах | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
|
||||
| Лише ви можете запускати відповіді в групах | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
|
||||
|
||||
## Ключі сесій
|
||||
|
||||
- Групові сесії використовують ключі сесій `agent:<agentId>:<channel>:group:<id>` (кімнати/канали використовують `agent:<agentId>:<channel>:channel:<id>`).
|
||||
- Теми форуму Telegram додають `:topic:<threadId>` до ідентифікатора групи, щоб кожна тема мала власну сесію.
|
||||
- Теми форуму Telegram додають `:topic:<threadId>` до ідентифікатора групи, тому кожна тема має власну сесію.
|
||||
- Прямі чати використовують основну сесію (або окрему для кожного відправника, якщо це налаштовано).
|
||||
- Heartbeats для групових сесій пропускаються.
|
||||
- Heartbeat пропускаються для групових сесій.
|
||||
|
||||
<a id="pattern-personal-dms-public-groups-single-agent"></a>
|
||||
|
||||
## Шаблон: особисті DM + публічні групи (один агент)
|
||||
|
||||
Так — це добре працює, якщо ваш «особистий» трафік — це **DM**, а ваш «публічний» трафік — це **групи**.
|
||||
Так — це добре працює, якщо ваш «особистий» трафік — це **DM**, а «публічний» трафік — це **групи**.
|
||||
|
||||
Чому: у режимі одного агента DM зазвичай потрапляють до **основного** ключа сесії (`agent:main:main`), тоді як групи завжди використовують **неосновні** ключі сесій (`agent:main:<channel>:group:<id>`). Якщо ви ввімкнете sandboxing із `mode: "non-main"`, ці групові сесії працюватимуть у Docker, а ваша основна DM-сесія залишиться на хості.
|
||||
Чому: у режимі одного агента DM зазвичай потрапляють до ключа **основної** сесії (`agent:main:main`), тоді як групи завжди використовують ключі **неосновних** сесій (`agent:main:<channel>:group:<id>`). Якщо ви ввімкнете ізоляцію через `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`, якщо він доступний, у форматі `<channel>:<token>`.
|
||||
- Мітки в UI використовують `displayName`, коли він доступний, у форматі `<channel>:<token>`.
|
||||
- `#room` зарезервовано для кімнат/каналів; групові чати використовують `g-<slug>` (нижній регістр, пробіли -> `-`, зберігати `#@+._-`).
|
||||
|
||||
## Політика груп
|
||||
|
||||
Керуйте тим, як обробляються повідомлення груп/кімнат для кожного каналу:
|
||||
Керуйте тим, як обробляються повідомлення в групах/кімнатах для кожного каналу:
|
||||
|
||||
```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.<id>.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.<id>.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.<provider>` відсутній), політика груп переходить у 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.<channel>.historyLimit` (або `channels.<channel>.accounts.*.historyLimit`) для перевизначень. Встановіть `0`, щоб вимкнути.
|
||||
- `mentionPatterns` — це безпечні regex-патерни, нечутливі до регістру; недійсні патерни та небезпечні вкладені форми повторення ігноруються.
|
||||
- Поверхні, які надають явні згадування, усе одно проходять; патерни є резервним варіантом.
|
||||
- Перевизначення для агента: `agents.list[].groupChat.mentionPatterns` (корисно, коли кілька агентів використовують одну групу).
|
||||
- Керування згадуваннями застосовується лише тоді, коли можливе виявлення згадування (вбудовані згадки або налаштовано `mentionPatterns`).
|
||||
- Значення за замовчуванням для Discord зберігаються в `channels.discord.guilds."*"` (можна перевизначити для кожної guild/channel).
|
||||
- Контекст історії групи однаково обгортається для всіх каналів і є **лише pending** (повідомлення, пропущені через керування згадуваннями); використовуйте `messages.groupChat.historyLimit` для глобального значення за замовчуванням і `channels.<channel>.historyLimit` (або `channels.<channel>.accounts.*.historyLimit`) для перевизначень. Встановіть `0`, щоб вимкнути.
|
||||
|
||||
## Обмеження інструментів для груп/каналів (необов’язково)
|
||||
|
||||
Деякі конфігурації каналів підтримують обмеження того, які інструменти доступні **всередині конкретної групи/кімнати/каналу**.
|
||||
|
||||
- `tools`: дозволити/заборонити інструменти для всієї групи.
|
||||
- `toolsBySender`: перевизначення для окремих відправників усередині групи.
|
||||
- `toolsBySender`: перевизначення для окремих відправників у межах групи.
|
||||
Використовуйте явні префікси ключів:
|
||||
`id:<senderId>`, `e164:<phone>`, `username:<handle>`, `name:<displayName>` і 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:<id>`.
|
||||
- Перегляд чатів: `imsg chats --limit 20`.
|
||||
- Для маршрутизації або allowlist віддавайте перевагу `chat_id:<id>`.
|
||||
- Список чатів: `imsg chats --limit 20`.
|
||||
- Відповіді в групах завжди повертаються до того самого `chat_id`.
|
||||
|
||||
## Особливості WhatsApp
|
||||
|
||||
Див. [Групові повідомлення](/uk/channels/group-messages) щодо поведінки, специфічної лише для WhatsApp (впровадження історії, подробиці обробки згадок).
|
||||
Див. [Групові повідомлення](/uk/channels/group-messages) щодо поведінки лише для WhatsApp (вставлення історії, деталі обробки згадувань).
|
||||
|
||||
@ -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 зчитує необов’язкову конфігурацію <Tool
|
||||
Якщо файл відсутній, OpenClaw використовує безпечні значення за замовчуванням. Поширені причини додати конфігурацію:
|
||||
|
||||
- Підключити канали та керувати тим, хто може надсилати повідомлення боту
|
||||
- Налаштувати моделі, інструменти, ізоляцію або автоматизацію (cron, hooks)
|
||||
- Тонко налаштувати сесії, медіа, мережу або UI
|
||||
- Налаштувати моделі, інструменти, ізоляцію або автоматизацію (Cron, hooks)
|
||||
- Налаштувати сесії, медіа, мережу або UI
|
||||
|
||||
Перегляньте [повний довідник](/uk/gateway/configuration-reference), щоб побачити всі доступні поля.
|
||||
|
||||
<Tip>
|
||||
**Вперше працюєте з конфігурацією?** Почніть із `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) із готовими конфігураціями для копіювання.
|
||||
**Новачок у конфігурації?** Почніть з `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) з повними конфігураціями для копіювання й вставлення.
|
||||
</Tip>
|
||||
|
||||
## Мінімальна конфігурація
|
||||
@ -45,8 +45,8 @@ OpenClaw зчитує необов’язкову конфігурацію <Tool
|
||||
<Tabs>
|
||||
<Tab title="Інтерактивний майстер">
|
||||
```bash
|
||||
openclaw onboard # повний процес початкового налаштування
|
||||
openclaw configure # майстер конфігурації
|
||||
openclaw onboard # full onboarding flow
|
||||
openclaw configure # config wizard
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="CLI (однорядкові команди)">
|
||||
@ -58,42 +58,42 @@ OpenClaw зчитує необов’язкову конфігурацію <Tool
|
||||
</Tab>
|
||||
<Tab title="Control UI">
|
||||
Відкрийте [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`, щоб
|
||||
отримати один вузол схеми для певного шляху разом із підсумками безпосередніх дочірніх елементів.
|
||||
</Tab>
|
||||
<Tab title="Пряме редагування">
|
||||
Відредагуйте `~/.openclaw/openclaw.json` безпосередньо. Gateway відстежує файл і автоматично застосовує зміни (див. [гаряче перезавантаження](#config-hot-reload)).
|
||||
Редагуйте `~/.openclaw/openclaw.json` безпосередньо. Gateway відстежує файл і автоматично застосовує зміни (див. [гаряче перезавантаження](#config-hot-reload)).
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Сувора валідація
|
||||
|
||||
<Warning>
|
||||
OpenClaw приймає лише конфігурації, що повністю відповідають схемі. Невідомі ключі, некоректні типи або недійсні значення призводять до того, що Gateway **відмовляється запускатися**. Єдиний виняток на кореневому рівні — `$schema` (рядок), щоб редактори могли підключати метадані JSON Schema.
|
||||
OpenClaw приймає лише конфігурації, що повністю відповідають схемі. Невідомі ключі, некоректні типи або недійсні значення призводять до того, що Gateway **відмовляється запускатися**. Єдиний виняток на рівні кореня — `$schema` (рядок), щоб редактори могли приєднувати метадані JSON Schema.
|
||||
</Warning>
|
||||
|
||||
Примітки щодо інструментів схеми:
|
||||
|
||||
- `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, якщо хеш збереженого файла все ще збігається з прийнятим
|
||||
записом. Просування пропускається, коли кандидат містить відредаговані заповнювачі секретів
|
||||
на кшталт `***` або скорочені значення токенів.
|
||||
|
||||
## Поширені завдання
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Налаштування каналу (WhatsApp, Telegram, Discord тощо)">
|
||||
Кожен канал має власний розділ конфігурації в `channels.<provider>`. Кроки налаштування дивіться на окремій сторінці каналу:
|
||||
<Accordion title="Налаштувати канал (WhatsApp, Telegram, Discord тощо)">
|
||||
Кожен канал має власний розділ конфігурації в `channels.<provider>`. Перегляньте окрему сторінку каналу, щоб виконати налаштування:
|
||||
|
||||
- [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 також зберігає довірену останню відому
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Вибір і налаштування моделей">
|
||||
Задайте основну модель і необов’язкові резервні варіанти:
|
||||
<Accordion title="Вибрати й налаштувати моделі">
|
||||
Вкажіть основну модель і необов’язкові резервні варіанти:
|
||||
|
||||
```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) у довіднику.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Керування тим, хто може писати боту">
|
||||
Доступ до DM контролюється для кожного каналу через `dmPolicy`:
|
||||
<Accordion title="Керувати тим, хто може надсилати повідомлення боту">
|
||||
Доступ до приватних повідомлень контролюється окремо для кожного каналу через `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).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Налаштування фільтрації згадок у групових чатах">
|
||||
Для групових повідомлень типово **потрібна згадка**. Налаштуйте шаблони для кожного агента:
|
||||
<Accordion title="Налаштувати обмеження за згадкою в груповому чаті">
|
||||
Повідомлення в групах за замовчуванням **вимагають згадки**. Налаштуйте шаблони для кожного агента:
|
||||
|
||||
```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).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Обмеження Skills для агента">
|
||||
Використовуйте `agents.defaults.skills` для спільної базової конфігурації, а потім перевизначайте конкретні
|
||||
агенти через `agents.list[].skills`:
|
||||
<Accordion title="Обмежити 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).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Налаштування моніторингу стану каналів gateway">
|
||||
Керуйте тим, наскільки агресивно gateway перезапускає канали, що виглядають неактивними:
|
||||
<Accordion title="Налаштувати моніторинг стану каналів gateway">
|
||||
Керуйте тим, наскільки агресивно gateway перезапускає канали, які виглядають застарілими:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -269,15 +269,15 @@ Gateway також зберігає довірену останню відому
|
||||
}
|
||||
```
|
||||
|
||||
- Встановіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски монітора стану.
|
||||
- Установіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски моніторингу стану.
|
||||
- `channelStaleEventThresholdMinutes` має бути більшим або дорівнювати інтервалу перевірки.
|
||||
- Використовуйте `channels.<provider>.healthMonitor.enabled` або `channels.<provider>.accounts.<id>.healthMonitor.enabled`, щоб вимкнути автоперезапуск для одного каналу або облікового запису без вимкнення глобального монітора.
|
||||
- Див. [Health Checks](/uk/gateway/health) для операційного налагодження та [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів.
|
||||
- Використовуйте `channels.<provider>.healthMonitor.enabled` або `channels.<provider>.accounts.<id>.healthMonitor.enabled`, щоб вимкнути автоперезапуски для одного каналу чи облікового запису без вимкнення глобального монітора.
|
||||
- Див. [Health Checks](/uk/gateway/health) для операційної діагностики та [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Налаштування сесій і скидання">
|
||||
Сесії керують безперервністю та ізоляцією розмов:
|
||||
<Accordion title="Налаштувати сесії та скидання">
|
||||
Сесії керують безперервністю розмови та ізоляцією:
|
||||
|
||||
```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).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Увімкнення ізоляції">
|
||||
Запускайте сесії агентів в ізольованих Docker-контейнерах:
|
||||
<Accordion title="Увімкнути ізоляцію">
|
||||
Запускайте сесії агента в ізольованих 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).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Увімкнення push на основі relay для офіційних збірок iOS">
|
||||
Push на основі relay налаштовується в `openclaw.json`.
|
||||
<Accordion title="Увімкнути push через relay для офіційних збірок iOS">
|
||||
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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Налаштування Heartbeat (періодичні check-in)">
|
||||
<Accordion title="Налаштувати Heartbeat (періодичні перевірки зв’язку)">
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
@ -399,12 +399,12 @@ Gateway також зберігає довірену останню відому
|
||||
|
||||
- `every`: рядок тривалості (`30m`, `2h`). Установіть `0m`, щоб вимкнути.
|
||||
- `target`: `last` | `none` | `<channel-id>` (наприклад, `discord`, `matrix`, `telegram` або `whatsapp`)
|
||||
- `directPolicy`: `allow` (типово) або `block` для heartbeat-цілей у стилі DM
|
||||
- Див. [Heartbeat](/uk/gateway/heartbeat) для повного посібника.
|
||||
- `directPolicy`: `allow` (типово) або `block` для цілей Heartbeat у стилі DM
|
||||
- Повний посібник див. у [Heartbeat](/uk/gateway/heartbeat).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Налаштування завдань Cron">
|
||||
<Accordion title="Налаштувати Cron-завдання">
|
||||
```json5
|
||||
{
|
||||
cron: {
|
||||
@ -419,14 +419,14 @@ Gateway також зберігає довірену останню відому
|
||||
}
|
||||
```
|
||||
|
||||
- `sessionRetention`: видаляти завершені ізольовані сесії запуску з `sessions.json` (типово `24h`; установіть `false`, щоб вимкнути).
|
||||
- `runLog`: очищати `cron/runs/<jobId>.jsonl` за розміром і кількістю збережених рядків.
|
||||
- Див. [Завдання Cron](/uk/automation/cron-jobs) для огляду можливостей і прикладів CLI.
|
||||
- `sessionRetention`: видаляти завершені ізольовані сесії виконання з `sessions.json` (типово `24h`; установіть `false`, щоб вимкнути).
|
||||
- `runLog`: обрізати `cron/runs/<jobId>.jsonl` за розміром і кількістю збережених рядків.
|
||||
- Огляд можливостей і приклади CLI див. у [Cron jobs](/uk/automation/cron-jobs).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Налаштування Webhook (hooks)">
|
||||
Увімкніть HTTP endpoint Webhook на Gateway:
|
||||
<Accordion title="Налаштувати Webhook-и (hooks)">
|
||||
Увімкніть 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).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Налаштування маршрутизації з кількома агентами">
|
||||
Запускайте кілька ізольованих агентів з окремими workspace і сесіями:
|
||||
<Accordion title="Налаштувати маршрутизацію кількох агентів">
|
||||
Запускайте кількох ізольованих агентів з окремими робочими просторами та сесіями:
|
||||
|
||||
```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).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Поділ конфігурації на кілька файлів ($include)">
|
||||
Використовуйте `$include`, щоб організувати великі конфігурації:
|
||||
<Accordion title="Розділити конфігурацію на кілька файлів ($include)">
|
||||
Використовуйте `$include`, щоб упорядковувати великі конфігурації:
|
||||
|
||||
```json5
|
||||
// ~/.openclaw/openclaw.json
|
||||
@ -498,41 +498,40 @@ Gateway також зберігає довірену останню відому
|
||||
}
|
||||
```
|
||||
|
||||
- **Один файл**: замінює об’єкт, у якому вказаний
|
||||
- **Масив файлів**: виконується глибоке злиття за порядком (пізніші мають пріоритет)
|
||||
- **Сусідні ключі**: зливаються після include (перевизначають включені значення)
|
||||
- **Вкладені include**: підтримуються до 10 рівнів вкладеності
|
||||
- **Відносні шляхи**: обчислюються відносно файла, який містить include
|
||||
- **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок парсингу та циклічних include
|
||||
- **Один файл**: замінює об’єкт-контейнер
|
||||
- **Масив файлів**: глибоко зливається по порядку (пізніший має пріоритет)
|
||||
- **Сусідні ключі**: зливаються після include-ів (перевизначають включені значення)
|
||||
- **Вкладені include-и**: підтримуються до 10 рівнів вкладеності
|
||||
- **Відносні шляхи**: обчислюються відносно файла, що включає
|
||||
- **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок парсингу та циклічних include-ів
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Гаряче перезавантаження конфігурації
|
||||
|
||||
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` | **Так** |
|
||||
|
||||
<Note>
|
||||
`gateway.reload` і `gateway.remote` є винятками — їх зміна **не** спричиняє перезапуск.
|
||||
</Note>
|
||||
|
||||
## RPC конфігурації (програмні оновлення)
|
||||
## Config RPC (програмні оновлення)
|
||||
|
||||
<Note>
|
||||
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`.
|
||||
</Note>
|
||||
|
||||
Безпечний/типовий процес:
|
||||
|
||||
- `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`.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="config.apply (повна заміна)">
|
||||
Виконує валідацію + записує всю конфігурацію та перезапускає Gateway за один крок.
|
||||
Перевіряє + записує повну конфігурацію і перезапускає Gateway за один крок.
|
||||
|
||||
<Warning>
|
||||
`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": "<hash>",
|
||||
@ -609,7 +608,7 @@ RPC control-plane для запису (`config.apply`, `config.patch`, `update.r
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="config.patch (часткове оновлення)">
|
||||
Зливає часткове оновлення з наявною конфігурацією (семантика 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 зчитує змінні середовища з батьківськ
|
||||
```
|
||||
|
||||
<Accordion title="Імпорт shell env (необов’язково)">
|
||||
Якщо цю опцію ввімкнено, а очікувані ключі не задано, OpenClaw запускає вашу login shell і імпортує лише відсутні ключі:
|
||||
Якщо це ввімкнено і очікувані ключі не задані, OpenClaw запускає вашу login shell і імпортує лише відсутні ключі:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -662,10 +661,10 @@ OpenClaw зчитує змінні середовища з батьківськ
|
||||
}
|
||||
```
|
||||
|
||||
Еквівалентна змінна середовища: `OPENCLAW_LOAD_SHELL_ENV=1`
|
||||
Еквівалент змінної середовища: `OPENCLAW_LOAD_SHELL_ENV=1`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підстановка змінних середовища у значення конфігурації">
|
||||
<Accordion title="Підстановка env var у значеннях конфігурації">
|
||||
Посилайтеся на змінні середовища в будь-якому рядковому значенні конфігурації за допомогою `${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"`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Посилання на секрети (env, file, exec)">
|
||||
Для полів, що підтримують об’єкти SecretRef, можна використовувати:
|
||||
<Accordion title="SecretRef (env, file, exec)">
|
||||
Для полів, що підтримують об’єкти 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).
|
||||
</Accordion>
|
||||
|
||||
Див. [Середовище](/uk/help/environment) для повного опису пріоритетів і джерел.
|
||||
Повний пріоритет і джерела див. у розділі [Середовище](/uk/help/environment).
|
||||
|
||||
## Повний довідник
|
||||
|
||||
Повний довідник по полях дивіться в **[Довіднику конфігурації](/uk/gateway/configuration-reference)**.
|
||||
Повний довідник по полях див. у **[Довіднику конфігурації](/uk/gateway/configuration-reference)**.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -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.<provider>` (і, за потреби, `agents.list[].tools.elevated.allowFrom.<provider>`)
|
||||
- Списки дозволених відправників: `tools.elevated.allowFrom.<provider>` (і, за потреби, `agents.list[].tools.elevated.allowFrom.<provider>`)
|
||||
|
||||
Див. [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)
|
||||
|
||||
@ -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 <name>`.
|
||||
- Core записує цю конфігурацію SSH у тимчасовий файл, відкриває SSH-сеанс і повторно використовує той самий віддалений міст файлової системи, що й для `backend: "ssh"`.
|
||||
- Лише в режимі `mirror` життєвий цикл відрізняється: синхронізація з локального на віддалений простір перед exec, а потім синхронізація назад.
|
||||
- OpenClaw запитує в OpenShell SSH-конфігурацію, специфічну для пісочниці, через `openshell sandbox ssh-config <name>`.
|
||||
- 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=<N>`, де `0` зберігає типовий режим Chromium.
|
||||
|
||||
Якщо вам потрібен інший профіль середовища виконання, використовуйте власне image браузера і надайте
|
||||
власну точку входу. Для локальних (неконтейнерних) профілів Chromium використовуйте
|
||||
Якщо вам потрібен інший профіль runtime, використовуйте власний образ браузера і надайте
|
||||
власний entrypoint. Для локальних профілів Chromium (не в контейнері) використовуйте
|
||||
`browser.extraArgs`, щоб додати додаткові прапорці запуску.
|
||||
|
||||
Типові налаштування безпеки:
|
||||
Типові параметри безпеки:
|
||||
|
||||
- `network: "host"` заблоковано.
|
||||
- `network: "container:<id>"` типово заблоковано (ризик обходу через приєднання до простору імен).
|
||||
- `network: "container:<id>"` за замовчуванням заблоковано (ризик обходу через приєднання до 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:<id>"` потребує `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:<id>"` вимагає `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)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
1870
docs/uk/help/faq.md
1870
docs/uk/help/faq.md
File diff suppressed because it is too large
Load Diff
@ -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)** — автоматизованого інсталятора з архітектурою, орієнтованою на безпеку.
|
||||
|
||||
<Info>
|
||||
Репозиторій [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) є джерелом істини для розгортання через Ansible. Ця сторінка — короткий огляд.
|
||||
Репозиторій [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) є основним джерелом правди для розгортання через Ansible. Ця сторінка — короткий огляд.
|
||||
</Info>
|
||||
|
||||
## Передумови
|
||||
|
||||
| Вимога | Докладніше |
|
||||
| Вимога | Деталі |
|
||||
| ----------- | --------------------------------------------------------- |
|
||||
| **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** — автозапуск із посиленням безпеки
|
||||
|
||||
<Note>
|
||||
Gateway запускається безпосередньо на хості (не в Docker), але sandbox агентів використовують Docker для ізоляції. Докладніше див. у [Sandboxing](/gateway/sandboxing).
|
||||
Gateway працює безпосередньо на хості (не в Docker). Sandbox-ізоляція агента є
|
||||
необов’язковою; цей playbook встановлює Docker, оскільки це стандартний sandbox-
|
||||
бекенд. Докладніше та про інші бекенди див. у [Sandboxing](/uk/gateway/sandboxing).
|
||||
</Note>
|
||||
|
||||
## Налаштування після встановлення
|
||||
@ -72,7 +74,7 @@ Gateway запускається безпосередньо на хості (н
|
||||
```
|
||||
</Step>
|
||||
<Step title="Запустіть майстер початкового налаштування">
|
||||
Скрипт після встановлення проведе вас через налаштування параметрів OpenClaw.
|
||||
Післяінсталяційний скрипт допоможе вам налаштувати параметри OpenClaw.
|
||||
</Step>
|
||||
<Step title="Підключіть провайдерів повідомлень">
|
||||
Увійдіть у WhatsApp, Telegram, Discord або Signal:
|
||||
@ -87,7 +89,7 @@ Gateway запускається безпосередньо на хості (н
|
||||
```
|
||||
</Step>
|
||||
<Step title="Підключіться до Tailscale">
|
||||
Приєднайтеся до своєї VPN mesh для безпечного віддаленого доступу.
|
||||
Приєднайтеся до вашої VPN mesh-мережі для безпечного віддаленого доступу.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
@ -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.
|
||||
|
||||
## Ручне встановлення
|
||||
|
||||
Якщо ви віддаєте перевагу ручному контролю замість автоматизації:
|
||||
Якщо ви надаєте перевагу ручному контролю над автоматизацією:
|
||||
|
||||
<Steps>
|
||||
<Step title="Установіть передумови">
|
||||
<Step title="Встановіть передумови">
|
||||
```bash
|
||||
sudo apt update && sudo apt install -y ansible git
|
||||
```
|
||||
@ -143,7 +145,7 @@ Docker установлюється для sandbox агентів (ізольо
|
||||
cd openclaw-ansible
|
||||
```
|
||||
</Step>
|
||||
<Step title="Установіть колекції Ansible">
|
||||
<Step title="Встановіть колекції 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
|
||||
```
|
||||
|
||||
Це ідемпотентно й безпечно для багаторазового запуску.
|
||||
Це ідемпотентно та безпечно для багаторазового запуску.
|
||||
|
||||
## Усунення несправностей
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Firewall блокує моє підключення">
|
||||
- Спочатку переконайтеся, що ви можете підключитися через Tailscale VPN
|
||||
- Доступ через SSH (порт 22) завжди дозволений
|
||||
<Accordion title="Брандмауер блокує моє з’єднання">
|
||||
- Спочатку переконайтеся, що ви маєте доступ через VPN Tailscale
|
||||
- Доступ SSH (порт 22) завжди дозволений
|
||||
- Gateway за задумом доступний лише через Tailscale
|
||||
</Accordion>
|
||||
<Accordion title="Сервіс не запускається">
|
||||
@ -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
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Проблеми з Docker sandbox">
|
||||
<Accordion title="Проблеми з sandbox Docker">
|
||||
```bash
|
||||
# Перевірити, чи працює Docker
|
||||
# Переконатися, що Docker запущений
|
||||
sudo systemctl status docker
|
||||
|
||||
# Перевірити образ sandbox
|
||||
@ -221,17 +223,17 @@ cd openclaw-ansible
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Розширена конфігурація
|
||||
## Розширене налаштування
|
||||
|
||||
Докладніше про архітектуру безпеки та усунення несправностей див. у репозиторії 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) — ізоляція для кожного агента
|
||||
|
||||
@ -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
|
||||
|
||||
<Steps>
|
||||
<Step title="Зберіть образ">
|
||||
У корені репозиторію виконайте скрипт налаштування:
|
||||
У корені репозиторію запустіть скрипт налаштування:
|
||||
|
||||
```bash
|
||||
./scripts/docker/setup.sh
|
||||
```
|
||||
|
||||
Це локально збирає образ gateway. Щоб натомість використати попередньо зібраний образ:
|
||||
Це локально збере образ Gateway. Щоб натомість використати попередньо зібраний образ:
|
||||
|
||||
```bash
|
||||
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
|
||||
@ -56,23 +56,22 @@ Docker **необов’язковий**. Використовуйте його
|
||||
</Step>
|
||||
|
||||
<Step title="Завершіть онбординг">
|
||||
Скрипт налаштування автоматично запускає онбординг. Він:
|
||||
Скрипт налаштування запускає онбординг автоматично. Він:
|
||||
|
||||
- запросить API-ключі провайдера
|
||||
- згенерує токен gateway і запише його в `.env`
|
||||
- запустить gateway через Docker Compose
|
||||
- згенерує токен Gateway і запише його в `.env`
|
||||
- запустить Gateway через Docker Compose
|
||||
|
||||
Під час налаштування онбординг перед запуском і запис конфігурації виконуються
|
||||
безпосередньо через `openclaw-gateway`. `openclaw-cli` призначений для команд,
|
||||
які ви запускаєте після того, як контейнер gateway уже існує.
|
||||
Під час налаштування онбординг до запуску та запис конфігурації виконуються безпосередньо через
|
||||
`openclaw-gateway`. `openclaw-cli` призначений для команд, які ви запускаєте після того,
|
||||
як контейнер Gateway уже існує.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Відкрийте Control UI">
|
||||
<Step title="Відкрийте UI керування">
|
||||
Відкрийте `http://127.0.0.1:18789/` у браузері та вставте налаштований
|
||||
спільний секрет у Settings. Скрипт налаштування типово записує токен у `.env`;
|
||||
якщо ви перемкнете конфігурацію контейнера на автентифікацію за паролем,
|
||||
використовуйте натомість цей пароль.
|
||||
спільний секрет у Settings. Скрипт налаштування типово записує токен у `.env`; якщо ви переключите конфігурацію контейнера на автентифікацію паролем, використовуйте натомість цей
|
||||
пароль.
|
||||
|
||||
Потрібна URL-адреса знову?
|
||||
|
||||
@ -101,7 +100,7 @@ Docker **необов’язковий**. Використовуйте його
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Ручний процес
|
||||
### Ручний потік
|
||||
|
||||
Якщо ви віддаєте перевагу виконанню кожного кроку вручну замість використання скрипта налаштування:
|
||||
|
||||
@ -116,14 +115,14 @@ docker compose up -d openclaw-gateway
|
||||
|
||||
<Note>
|
||||
Запускайте `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`.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Оскільки `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`.
|
||||
</Note>
|
||||
|
||||
@ -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.
|
||||
|
||||
<Note>
|
||||
Використовуйте значення режиму прив’язки в `gateway.bind` (`lan` / `loopback` / `custom` /
|
||||
`tailnet` / `auto`), а не псевдоніми хоста на кшталт `0.0.0.0` або `127.0.0.1`.
|
||||
</Note>
|
||||
|
||||
### Сховище та збереження даних
|
||||
### Сховище й збереження даних
|
||||
|
||||
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/<agentId>/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).
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Увімкнення sandbox агента для Docker gateway">
|
||||
<Accordion title="Увімкнення sandbox агента для Docker Gateway">
|
||||
```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
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Автоматизація / CI (неінтерактивно)">
|
||||
Вимкніть виділення 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
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Примітка щодо безпеки спільної мережі">
|
||||
<Accordion title="Примітка про безпеку спільної мережі">
|
||||
`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`.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Права доступу та EACCES">
|
||||
Образ працює від імені `node` (uid 1000). Якщо ви бачите помилки прав доступу до
|
||||
`/home/node/.openclaw`, переконайтеся, що ваші bind mounts хоста належать uid 1000:
|
||||
<Accordion title="Дозволи та EACCES">
|
||||
Образ працює від імені `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
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Швидші перебудови">
|
||||
Упорядкуйте 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
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Параметри контейнера для досвідчених користувачів">
|
||||
Типовий образ орієнтований на безпеку та працює від непривілейованого користувача `node`. Для більш
|
||||
<Accordion title="Просунуті параметри контейнера">
|
||||
Типовий образ орієнтований насамперед на безпеку й працює від імені непривілейованого `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
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="OpenAI Codex OAuth (headless Docker)">
|
||||
Якщо ви виберете у майстрі OpenAI Codex OAuth, відкриється URL-адреса в браузері. У
|
||||
Якщо у майстрі ви оберете OpenAI Codex OAuth, він відкриє URL-адресу в браузері. У
|
||||
Docker або headless-середовищах скопіюйте повну URL-адресу перенаправлення, на яку ви потрапите, і вставте
|
||||
її назад у майстер, щоб завершити автентифікацію.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Метадані базового образу">
|
||||
Основний образ 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).
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### Запуск на 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
|
||||
```
|
||||
|
||||
## Усунення несправностей
|
||||
## Усунення неполадок
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Образ відсутній або sandbox-контейнер не запускається">
|
||||
<Accordion title="Образ відсутній або контейнер sandbox не запускається">
|
||||
Зберіть образ 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` на ваш власний образ.
|
||||
Контейнери автоматично створюються для кожної сесії за потреби.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Помилки прав доступу в sandbox">
|
||||
Установіть `docker.user` у UID:GID, що відповідає власнику змонтованого workspace,
|
||||
<Accordion title="Помилки дозволів у sandbox">
|
||||
Встановіть `docker.user` у значення UID:GID, яке відповідає власнику змонтованого workspace,
|
||||
або змініть власника папки workspace через chown.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Користувацькі інструменти не знайдено в sandbox">
|
||||
<Accordion title="Власні інструменти не знайдені в sandbox">
|
||||
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.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Завершено через OOM під час збирання образу (exit 137)">
|
||||
VM потрібні щонайменше 2 ГБ RAM. Використайте більший клас машини та повторіть спробу.
|
||||
<Accordion title="Примусове завершення через OOM під час збірки образу (exit 137)">
|
||||
VM потребує щонайменше 2 ГБ RAM. Використайте більший клас машини й повторіть спробу.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Unauthorized або потрібне pairing у Control UI">
|
||||
Отримайте нове посилання dashboard і схваліть пристрій браузера:
|
||||
<Accordion title="Unauthorized або потрібне pairing у UI керування">
|
||||
Отримайте свіже посилання на dashboard і підтвердьте пристрій браузера:
|
||||
|
||||
```bash
|
||||
docker compose run --rm openclaw-cli dashboard --no-open
|
||||
@ -393,8 +393,8 @@ scripts/sandbox-setup.sh
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Ціль gateway показує ws://172.x.x.x або помилки pairing із Docker CLI">
|
||||
Скиньте режим і прив’язку gateway:
|
||||
<Accordion title="Ціль Gateway показує ws://172.x.x.x або помилки pairing з Docker CLI">
|
||||
Скиньте режим і 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 після встановлення
|
||||
|
||||
@ -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`,
|
||||
`<workspace>/.agents/skills` і `<workspace>/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.<skillKey>`: перевизначення для окремого skill.
|
||||
- `entries.<skillKey>`: перевизначення для окремого 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`, використовуйте натомість цей ключ.
|
||||
- Пріоритет завантаження: `<workspace>/skills` → `<workspace>/.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.<skill>.env/apiKey` застосовуються **лише** до запусків на хості.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user