From 2515efd4d04a439890e612975e08cad798e68e91 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 14 Apr 2026 01:22:29 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/gateway/sandboxing.md | 366 ++++++++++++++++++---------------- 1 file changed, 189 insertions(+), 177 deletions(-) diff --git a/docs/uk/gateway/sandboxing.md b/docs/uk/gateway/sandboxing.md index b24eef77f..7500b7e47 100644 --- a/docs/uk/gateway/sandboxing.md +++ b/docs/uk/gateway/sandboxing.md @@ -1,93 +1,105 @@ --- 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-05T18:05:33Z" + generated_at: "2026-04-14T01:21:00Z" model: gpt-5.4 provider: openai - source_hash: 756ebd5b9806c23ba720a311df7e3b4ffef6ce41ba4315ee4b36b5ea87b26e60 + source_hash: 2573d0d7462f63a68eb1750e5432211522ff5b42989a17379d3e188468bbce52 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 (а не в журналах query/header). - - `agents.defaults.sandbox.browser.allowHostControl` дозволяє пісочницьним сесіям явно націлюватися на браузер хоста. - - Необов’язкові списки дозволених обмежують `target: "custom"`: `allowedControlUrls`, `allowedControlHosts`, `allowedControlPorts`. + - Необов’язковий параметр `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`. Не ізолюються: - Сам процес Gateway. -- Будь-який інструмент, якому явно дозволено працювати поза пісочницею (наприклад `tools.elevated`). - - **Elevated exec обходить пісочницю й використовує налаштований шлях виходу (`gateway` типово або `node`, коли ціллю exec є `node`).** - - Якщо пісочницю вимкнено, `tools.elevated` не змінює виконання (воно і так уже на хості). Див. [Elevated Mode](/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"`: ізолювати лише **не-main** сесії (типово, якщо ви хочете звичайні чати на хості). -- `"all"`: кожна сесія працює в пісочниці. - Примітка: `"non-main"` базується на `session.mainKey` (типово `"main"`), а не на id агента. - Групові/канальні сесії використовують власні ключі, тому вважаються не-main і будуть ізольовані в пісочниці. +- `"off"`: без ізоляції. +- `"non-main"`: ізолюються лише **неосновні** сеанси (типовий варіант, якщо ви хочете, щоб звичайні чати працювали на хості). +- `"all"`: кожен сеанс працює в ізоляції. + Примітка: `"non-main"` визначається за `session.mainKey` (типово `"main"`), а не за id агента. + Сеанси груп/каналів використовують власні ключі, тож вони вважаються неосновними й будуть ізольовані. -## Область +## Область дії -`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-ключ + цільовий хост | Увімкнений плагін OpenShell | -| **Модель робочого простору** | Bind mount або копіювання | Віддалений як канонічний (одноразове ініціалізування) | `mirror` або `remote` | -| **Керування мережею** | `docker.network` (типово: none) | Залежить від віддаленого хоста | Залежить від OpenShell | -| **Браузер у пісочниці** | Підтримується | Не підтримується | Поки що не підтримується | -| **Bind mount** | `docker.binds` | Н/Д | Н/Д | -| **Найкраще для** | Локальна розробка, повна ізоляція | Винесення на віддалену машину | Керовані віддалені пісочниці з необов’язковою двосторонньою синхронізацією | +| | 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 | +| **Найкраще підходить для** | Локальної розробки, повної ізоляції | Винесення на віддалену машину | Керованих віддалених середовищ ізоляції з необов’язковою двосторонньою синхронізацією | + +### Бекенд Docker + +Бекенд Docker є типовим середовищем виконання: він локально запускає інструменти та браузери в ізоляції через сокет демона Docker (`/var/run/docker.sock`). Ізоляція контейнера визначається просторами імен Docker. + +**Обмеження Docker-out-of-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`). + +Якщо ви відображаєте шляхи внутрішньо без абсолютного паритету з хостом, OpenClaw нативно викидає помилку дозволів `EACCES` при спробі записати свій heartbeat у контейнерному середовищі, оскільки повністю кваліфікований рядок шляху нативно не існує. ### Бекенд SSH -Використовуйте `backend: "ssh"`, коли хочете, щоб OpenClaw ізолював у пісочниці `exec`, файлові інструменти й читання медіа -на довільній машині, доступній через SSH. +Використовуйте `backend: "ssh"`, якщо ви хочете, щоб OpenClaw ізолював `exec`, файлові інструменти та читання медіа +на довільній машині, доступній по SSH. ```json5 { @@ -106,7 +118,7 @@ Gateway залишається на хості; виконання інстру identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // Або використовуйте SecretRef / вбудований вміст замість локальних файлів: + // Або використовуйте SecretRefs / вбудований вміст замість локальних файлів: // 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" }, @@ -119,36 +131,36 @@ Gateway залишається на хості; виконання інстру Як це працює: -- OpenClaw створює віддалений корінь для кожної області в `sandbox.ssh.workspaceRoot`. -- Під час першого використання після створення або повторного створення OpenClaw один раз ініціалізує цей віддалений робочий простір із локального. -- Після цього `exec`, `read`, `write`, `edit`, `apply_patch`, читання медіа під час prompt і staging вхідних медіа працюють безпосередньо з віддаленим робочим простором через SSH. +- OpenClaw створює віддалений кореневий каталог для кожної області дії в `sandbox.ssh.workspaceRoot`. +- При першому використанні після створення або повторного створення OpenClaw один раз заповнює цей віддалений робочий простір із локального. +- Після цього `exec`, `read`, `write`, `edit`, `apply_patch`, читання медіа в prompt і підготовка вхідних медіа виконуються безпосередньо у віддаленому робочому просторі через SSH. - OpenClaw не синхронізує віддалені зміни назад у локальний робочий простір автоматично. -Матеріал автентифікації: +Матеріали автентифікації: -- `identityFile`, `certificateFile`, `knownHostsFile`: використовують наявні локальні файли й передають їх через конфігурацію OpenSSH. -- `identityData`, `certificateData`, `knownHostsData`: використовують вбудовані рядки або SecretRef. 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`. -Це модель **віддалений як канонічний**. Після початкового seed віддалений робочий простір SSH стає реальним станом пісочниці. +Це модель, де **канонічним є віддалений стан**. Віддалений робочий простір SSH стає реальним станом ізоляції після початкового заповнення. Важливі наслідки: -- Локальні зміни на хості, зроблені поза OpenClaw після кроку seed, не будуть видимі віддалено, доки ви не відтворите пісочницю. -- `openclaw sandbox recreate` видаляє віддалений корінь для кожної області й повторно ініціалізує його з локального під час наступного використання. -- Браузер у пісочниці не підтримується в бекенді SSH. +- Локальні зміни на хості, зроблені поза OpenClaw після етапу початкового заповнення, не будуть видимі віддалено, доки ви не створите середовище ізоляції заново. +- `openclaw sandbox recreate` видаляє віддалений кореневий каталог для відповідної області дії та знову виконує початкове заповнення з локального джерела під час наступного використання. +- Ізоляція браузера не підтримується в бекенді SSH. - Налаштування `sandbox.docker.*` не застосовуються до бекенда SSH. ### Бекенд OpenShell -Використовуйте `backend: "openshell"`, коли хочете, щоб OpenClaw запускав інструменти в пісочниці -у віддаленому середовищі під керуванням OpenShell. Повний посібник із налаштування, -довідник конфігурації та порівняння режимів робочого простору див. на окремій -[сторінці OpenShell](/gateway/openshell). +Використовуйте `backend: "openshell"`, якщо ви хочете, щоб OpenClaw ізолював інструменти в +керованому OpenShell віддаленому середовищі. Повний посібник із налаштування, довідник +з конфігурації та порівняння режимів робочого простору дивіться на +окремій [сторінці 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`), а також необов’язковий режим робочого простору `mirror`. ```json5 { @@ -181,120 +193,120 @@ OpenShell повторно використовує той самий базов Режими OpenShell: - `mirror` (типово): локальний робочий простір залишається канонічним. OpenClaw синхронізує локальні файли в OpenShell перед exec і синхронізує віддалений робочий простір назад після exec. -- `remote`: після створення пісочниці робочий простір OpenShell стає канонічним. OpenClaw один раз ініціалізує віддалений робочий простір із локального, а потім файлові інструменти й exec працюють безпосередньо з віддаленою пісочницею без синхронізації змін назад. +- `remote`: робочий простір OpenShell стає канонічним після створення середовища ізоляції. OpenClaw один раз заповнює віддалений робочий простір із локального, а потім файлові інструменти та exec працюють безпосередньо з віддаленим середовищем ізоляції без синхронізації змін назад. -Докладно про віддалений транспорт: +Деталі віддаленого транспорту: -- OpenClaw запитує в OpenShell специфічну для пісочниці конфігурацію SSH через `openshell sandbox ssh-config `. -- Core записує цю конфігурацію SSH у тимчасовий файл, відкриває SSH-сесію й повторно використовує той самий міст віддаленої файлової системи, що й `backend: "ssh"`. -- У режимі `mirror` відрізняється лише життєвий цикл: синхронізація локального у віддалений простір перед exec, а потім назад після exec. +- OpenClaw запитує в OpenShell конфігурацію SSH, специфічну для середовища ізоляції, через `openshell sandbox ssh-config `. +- Core записує цю конфігурацію SSH у тимчасовий файл, відкриває SSH-сеанс і повторно використовує той самий віддалений міст файлової системи, що й для `backend: "ssh"`. +- Лише в режимі `mirror` життєвий цикл відрізняється: синхронізація з локального на віддалений простір перед exec, а потім синхронізація назад. Поточні обмеження OpenShell: -- браузер у пісочниці поки що не підтримується +- браузер в ізоляції ще не підтримується - `sandbox.docker.binds` не підтримується в бекенді OpenShell -- специфічні для Docker параметри runtime у `sandbox.docker.*` і далі застосовуються лише до бекенда Docker +- специфічні для Docker параметри середовища виконання в `sandbox.docker.*` як і раніше застосовуються лише до бекенда Docker #### Режими робочого простору -OpenShell має дві моделі робочого простору. На практиці це найважливіша частина. +OpenShell має дві моделі робочого простору. Саме ця частина найважливіша на практиці. ##### `mirror` -Використовуйте `plugins.entries.openshell.config.mode: "mirror"`, коли хочете, щоб **локальний робочий простір залишався канонічним**. +Використовуйте `plugins.entries.openshell.config.mode: "mirror"`, якщо ви хочете, щоб **локальний робочий простір залишався канонічним**. Поведінка: -- Перед `exec` OpenClaw синхронізує локальний робочий простір у пісочницю OpenShell. +- Перед `exec` OpenClaw синхронізує локальний робочий простір у середовище OpenShell. - Після `exec` OpenClaw синхронізує віддалений робочий простір назад у локальний. -- Файлові інструменти все одно працюють через міст пісочниці, але між ходами джерелом істини лишається локальний робочий простір. +- Файлові інструменти все одно працюють через міст ізоляції, але локальний робочий простір залишається джерелом істини між ходами. Використовуйте це, коли: -- ви редагуєте файли локально поза OpenClaw і хочете, щоб ці зміни автоматично з’являлися в пісочниці -- ви хочете, щоб пісочниця OpenShell поводилася якомога більше як бекенд Docker -- ви хочете, щоб робочий простір хоста відображав записи з пісочниці після кожного ходу exec +- ви редагуєте файли локально поза OpenClaw і хочете, щоб ці зміни автоматично з’являлися в ізоляції +- ви хочете, щоб середовище OpenShell поводилося максимально схоже на бекенд Docker +- ви хочете, щоб робочий простір хоста відображав записи із середовища ізоляції після кожного ходу exec Компроміс: -- додаткова вартість синхронізації до й після exec +- додаткові витрати на синхронізацію до і після exec ##### `remote` -Використовуйте `plugins.entries.openshell.config.mode: "remote"`, коли хочете, щоб **робочий простір OpenShell став канонічним**. +Використовуйте `plugins.entries.openshell.config.mode: "remote"`, якщо ви хочете, щоб **робочий простір OpenShell став канонічним**. Поведінка: -- Коли пісочницю вперше створено, OpenClaw один раз ініціалізує віддалений робочий простір із локального. +- Коли середовище ізоляції створюється вперше, OpenClaw один раз заповнює віддалений робочий простір із локального. - Після цього `exec`, `read`, `write`, `edit` і `apply_patch` працюють безпосередньо з віддаленим робочим простором OpenShell. - OpenClaw **не** синхронізує віддалені зміни назад у локальний робочий простір після exec. -- Читання медіа під час prompt і далі працюють, тому що файлові та медіаінструменти читають через міст пісочниці, а не припускають локальний шлях хоста. -- Транспорт — це SSH до пісочниці OpenShell, повернутої `openshell sandbox ssh-config`. +- Читання медіа під час prompt і далі працює, оскільки файлові та медіа-інструменти читають через міст ізоляції, а не покладаються на локальний шлях хоста. +- Транспорт — це SSH у середовище OpenShell, яке повертає `openshell sandbox ssh-config`. Важливі наслідки: -- Якщо ви редагуєте файли на хості поза OpenClaw після кроку seed, віддалена пісочниця **не** побачить ці зміни автоматично. -- Якщо пісочницю відтворити, віддалений робочий простір знову ініціалізується з локального. -- При `scope: "agent"` або `scope: "shared"` цей віддалений робочий простір спільний у межах тієї самої області. +- Якщо ви редагуєте файли на хості поза OpenClaw після етапу початкового заповнення, віддалене середовище ізоляції **не** побачить ці зміни автоматично. +- Якщо середовище ізоляції створюється заново, віддалений робочий простір знову заповнюється з локального робочого простору. +- За `scope: "agent"` або `scope: "shared"` цей віддалений робочий простір є спільним у межах тієї самої області дії. Використовуйте це, коли: -- пісочниця має переважно жити на віддаленому боці OpenShell -- ви хочете зменшити накладні витрати на синхронізацію в кожному ході -- ви не хочете, щоб локальні редагування на хості непомітно перезаписували стан віддаленої пісочниці +- середовище ізоляції має переважно існувати на віддаленому боці OpenShell +- ви хочете менші накладні витрати на синхронізацію на кожному ході +- ви не хочете, щоб локальні зміни на хості непомітно перезаписували віддалений стан середовища ізоляції -Вибирайте `mirror`, якщо сприймаєте пісочницю як тимчасове середовище виконання. -Вибирайте `remote`, якщо сприймаєте пісочницю як справжній робочий простір. +Виберіть `mirror`, якщо сприймаєте середовище ізоляції як тимчасове середовище виконання. +Виберіть `remote`, якщо сприймаєте середовище ізоляції як реальний робочий простір. #### Життєвий цикл OpenShell -Пісочниці OpenShell і далі керуються через звичайний життєвий цикл пісочниці: +Середовища ізоляції OpenShell і далі керуються через звичайний життєвий цикл ізоляції: -- `openclaw sandbox list` показує середовища OpenShell так само, як і середовища Docker -- `openclaw sandbox recreate` видаляє поточне середовище виконання і дозволяє OpenClaw відтворити його під час наступного використання +- `openclaw sandbox list` показує як середовища виконання OpenShell, так і середовища виконання Docker +- `openclaw sandbox recreate` видаляє поточне середовище виконання і дозволяє OpenClaw створити його заново під час наступного використання - логіка очищення теж враховує бекенд -Для режиму `remote` recreate особливо важливий: +Для режиму `remote` повторне створення особливо важливе: -- recreate видаляє канонічний віддалений робочий простір для цієї області -- наступне використання ініціалізує новий віддалений робочий простір із локального +- повторне створення видаляє канонічний віддалений робочий простір для цієї області дії +- наступне використання створює новий віддалений робочий простір із локального робочого простору -Для режиму `mirror` recreate головним чином скидає віддалене середовище виконання, -тому що локальний робочий простір у будь-якому разі лишається канонічним. +Для режиму `mirror` повторне створення переважно скидає віддалене середовище виконання, +оскільки локальний робочий простір однаково залишається канонічним. ## Доступ до робочого простору -`agents.defaults.sandbox.workspaceAccess` керує **що саме може бачити пісочниця**: +`agents.defaults.sandbox.workspaceAccess` керує **що може бачити середовище ізоляції**: -- `"none"` (типово): інструменти бачать робочий простір пісочниці в `~/.openclaw/sandboxes`. +- `"none"` (типово): інструменти бачать робочий простір ізоляції в `~/.openclaw/sandboxes`. - `"ro"`: монтує робочий простір агента лише для читання в `/agent` (вимикає `write`/`edit`/`apply_patch`). -- `"rw"`: монтує робочий простір агента для читання/запису в `/workspace`. +- `"rw"`: монтує робочий простір агента для читання й запису в `/workspace`. -У бекенді OpenShell: +З бекендом OpenShell: - режим `mirror` і далі використовує локальний робочий простір як канонічне джерело між ходами exec -- режим `remote` після початкового seed використовує віддалений робочий простір OpenShell як канонічне джерело -- `workspaceAccess: "ro"` і `"none"` і далі так само обмежують запис +- режим `remote` використовує віддалений робочий простір OpenShell як канонічне джерело після початкового заповнення +- `workspaceAccess: "ro"` і `"none"` і далі так само обмежують можливість запису -Вхідні медіа копіюються в активний робочий простір пісочниці (`media/inbound/*`). -Примітка щодо Skills: інструмент `read` прив’язаний до кореня пісочниці. При `workspaceAccess: "none"` -OpenClaw віддзеркалює придатні Skills у робочий простір пісочниці (`.../skills`), щоб -їх можна було читати. При `"rw"` skills робочого простору доступні для читання з +Вхідні медіафайли копіюються в активний робочий простір ізоляції (`media/inbound/*`). +Примітка щодо Skills: інструмент `read` прив’язаний до кореня ізоляції. За `workspaceAccess: "none"` +OpenClaw віддзеркалює придатні Skills у робочий простір ізоляції (`.../skills`), щоб +їх можна було читати. За `"rw"` Skills робочого простору доступні для читання з `/workspace/skills`. -## Користувацькі bind mount +## Власні bind mounts `agents.defaults.sandbox.docker.binds` монтує додаткові каталоги хоста в контейнер. -Формат: `host:container:mode` (наприклад `"/home/user/source:/source:rw"`). +Формат: `host:container:mode` (наприклад, `"/home/user/source:/source:rw"`). -Глобальні bind і bind для окремого агента **об’єднуються** (а не замінюються). За `scope: "shared"` bind для окремого агента ігноруються. +Глобальні 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 { @@ -322,19 +334,19 @@ OpenClaw віддзеркалює придатні Skills у робочий пр Примітки щодо безпеки: -- Bind обходять файлову систему пісочниці: вони відкривають шляхи хоста з тим режимом, який ви задали (`:ro` або `:rw`). -- OpenClaw блокує небезпечні джерела bind (наприклад: `docker.sock`, `/etc`, `/proc`, `/sys`, `/dev` і батьківські mount, які відкрили б до них доступ). -- OpenClaw також блокує типові корені домашніх каталогів з обліковими даними, як-от `~/.aws`, `~/.cargo`, `~/.config`, `~/.docker`, `~/.gnupg`, `~/.netrc`, `~/.npm` і `~/.ssh`. -- Перевірка bind — це не просто зіставлення рядків. OpenClaw нормалізує шлях джерела, потім знову розв’язує його через найглибшого наявного предка перед повторною перевіркою заблокованих шляхів і дозволених коренів. -- Це означає, що вихід через батьківські symlink усе одно безпечно блокується, навіть коли фінальний лист ще не існує. Приклад: `/workspace/run-link/new-file` усе одно розв’язується як `/var/run/...`, якщо `run-link` вказує туди. -- Дозволені корені джерел канонізуються так само, тому шлях, який лише виглядає таким, що входить до allowlist до розв’язання symlink, усе одно буде відхилений як `outside allowed roots`. -- Чутливі mount (секрети, SSH-ключі, сервісні облікові дані) мають бути `:ro`, якщо це не абсолютно необхідно. -- Поєднуйте з `workspaceAccess: "ro"`, якщо вам потрібен лише доступ для читання до робочого простору; режими bind залишаються незалежними. -- Див. [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) щодо того, як bind взаємодіють із політикою інструментів і elevated exec. +- 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`. +- Чутливі монтування (секрети, SSH-ключі, службові облікові дані) мають бути `:ro`, якщо тільки це не є абсолютно необхідним. +- Поєднуйте з `workspaceAccess: "ro"`, якщо вам потрібен лише доступ на читання до робочого простору; режими bind mounts залишаються незалежними. +- Див. [Ізоляція vs Політика інструментів vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated), щоб зрозуміти, як bind mounts взаємодіють із політикою інструментів і elevated exec. -## Образи та налаштування +## Зображення + налаштування -Типовий образ Docker: `openclaw-sandbox:bookworm-slim` +Типове Docker image: `openclaw-sandbox:bookworm-slim` Зберіть його один раз: @@ -342,31 +354,31 @@ OpenClaw віддзеркалює придатні Skills у робочий пр scripts/sandbox-setup.sh ``` -Примітка: типовий образ **не** містить Node. Якщо skill потребує Node (або -інших runtime), або створіть власний образ, або встановіть через -`sandbox.docker.setupCommand` (потрібні network egress + доступний для запису root + +Примітка: типове image **не** містить Node. Якщо навичці потрібен Node (або +інші середовища виконання), або зберіть власне image, або встановіть усе через +`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-пісочниці працюють **без мережі**. +За замовчуванням Docker-контейнери ізоляції працюють **без мережі**. Перевизначити це можна через `agents.defaults.sandbox.docker.network`. -Вбудований образ браузера в пісочниці також застосовує консервативні типові параметри запуску Chromium +Комплектне image браузера в ізоляції також застосовує консервативні типові параметри запуску Chromium для контейнеризованих навантажень. Поточні типові параметри контейнера включають: - `--remote-debugging-address=127.0.0.1` @@ -387,36 +399,36 @@ 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`) необов’язкові й корисні, - коли контейнери не мають підтримки GPU. Установіть `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, +- Три прапорці посиленого захисту графіки (`--disable-3d-apis`, + `--disable-software-rasterizer`, `--disable-gpu`) є необов’язковими й корисні, + коли контейнери не мають підтримки GPU. Задайте `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо вашому навантаженню потрібен WebGL або інші 3D/браузерні можливості. -- `--disable-extensions` типово ввімкнено й може бути вимкнено через - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` для потоків, що залежать від розширень. +- `--disable-extensions` увімкнено за замовчуванням і його можна вимкнути через + `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` для сценаріїв, що залежать від розширень. - `--renderer-process-limit=2` керується через - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`, де `0` зберігає типове значення Chromium. + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`, де `0` зберігає типовий режим Chromium. -Якщо вам потрібен інший профіль runtime, використовуйте власний образ браузера й надайте -власний entrypoint. Для локальних (не контейнерних) профілів Chromium використовуйте -`browser.extraArgs`, щоб додати додаткові прапори запуску. +Якщо вам потрібен інший профіль середовища виконання, використовуйте власне image браузера і надайте +власну точку входу. Для локальних (неконтейнерних) профілів Chromium використовуйте +`browser.extraArgs`, щоб додати додаткові прапорці запуску. -Типові параметри безпеки: +Типові налаштування безпеки: - `network: "host"` заблоковано. -- `network: "container:"` типово заблоковано (ризик обходу через приєднання до namespace). -- Аварійне перевизначення: `agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`. +- `network: "container:"` типово заблоковано (ризик обходу через приєднання до простору імен). +- Аварійний override: `agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`. Установлення Docker і контейнеризований gateway описані тут: -[Docker](/install/docker) +[Docker](/uk/install/docker) -Для розгортань gateway у Docker `scripts/docker/setup.sh` може ініціалізувати конфігурацію пісочниці. -Установіть `OPENCLAW_SANDBOX=1` (або `true`/`yes`/`on`), щоб увімкнути цей шлях. Ви можете +Для розгортань gateway у Docker `scripts/docker/setup.sh` може ініціалізувати конфігурацію ізоляції. +Задайте `OPENCLAW_SANDBOX=1` (або `true`/`yes`/`on`), щоб увімкнути цей шлях. Ви можете перевизначити розташування сокета через `OPENCLAW_DOCKER_SOCKET`. Повне налаштування й довідник -змінних середовища: [Docker](/install/docker#agent-sandbox). +зі змінних середовища: [Docker](/uk/install/docker#agent-sandbox). ## setupCommand (одноразове налаштування контейнера) -`setupCommand` запускається **один раз** після створення контейнера пісочниці (не під час кожного запуску). +`setupCommand` запускається **один раз** після створення контейнера ізоляції (не під час кожного запуску). Він виконується всередині контейнера через `sh -lc`. Шляхи: @@ -426,33 +438,33 @@ scripts/sandbox-browser-setup.sh Поширені пастки: -- Типове `docker.network` має значення `"none"` (без egress), тож установлення пакетів завершиться помилкою. -- `docker.network: "container:"` вимагає `dangerouslyAllowContainerNamespaceJoin: true` і призначене лише для аварійного використання. -- `readOnlyRoot: true` забороняє запис; установіть `readOnlyRoot: false` або створіть власний образ. -- Для встановлення пакетів `user` має бути root (пропустіть `user` або задайте `user: "0:0"`). +- Типове значення `docker.network` — `"none"` (без виходу в мережу), тому встановлення пакетів завершуватиметься помилкою. +- `docker.network: "container:"` потребує `dangerouslyAllowContainerNamespaceJoin: true` і призначений лише для аварійного використання. +- `readOnlyRoot: true` забороняє запис; задайте `readOnlyRoot: false` або зберіть власне image. +- Для встановлення пакетів `user` має бути root (не задавайте `user` або задайте `user: "0:0"`). - Sandbox exec **не** успадковує `process.env` хоста. Використовуйте - `agents.defaults.sandbox.docker.env` (або власний образ) для API keys skill. + `agents.defaults.sandbox.docker.env` (або власне image) для API-ключів навичок. -## Політика інструментів і шляхи обходу +## Політика інструментів + шляхи обходу -Політики allow/deny для інструментів і далі застосовуються до правил пісочниці. Якщо інструмент заборонено -глобально або для окремого агента, пісочниця його не поверне. +Політики allow/deny для інструментів усе одно застосовуються раніше за правила ізоляції. Якщо інструмент заборонено +глобально або для конкретного агента, ізоляція його не поверне. -`tools.elevated` — це явний шлях обходу, який запускає `exec` поза пісочницею (`gateway` типово або `node`, коли ціллю exec є `node`). -Директиви `/exec` застосовуються лише для авторизованих відправників і зберігаються для кожної сесії; щоб жорстко вимкнути -`exec`, використовуйте deny у політиці інструментів (див. [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated)). +`tools.elevated` — це явний шлях обходу, який запускає `exec` поза ізоляцією (`gateway` за замовчуванням або `node`, коли ціллю exec є `node`). +Директиви `/exec` застосовуються лише для авторизованих відправників і зберігаються для кожного сеансу; щоб повністю вимкнути +`exec`, використовуйте заборону в політиці інструментів (див. [Ізоляція vs Політика інструментів vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated)). Налагодження: -- Використовуйте `openclaw sandbox explain`, щоб перевірити ефективний режим пісочниці, політику інструментів і ключі конфігурації для виправлення. -- Див. [Sandbox vs Tool Policy vs Elevated](/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` для політики інструментів у пісочниці). -Див. [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) щодо пріоритетів. +Кожен агент може перевизначати ізоляцію й інструменти: +`agents.list[].sandbox` і `agents.list[].tools` (а також `agents.list[].tools.sandbox.tools` для політики інструментів ізоляції). +Див. [Ізоляція та інструменти для кількох агентів](/uk/tools/multi-agent-sandbox-tools) щодо пріоритетів. ## Мінімальний приклад увімкнення @@ -472,8 +484,8 @@ scripts/sandbox-browser-setup.sh ## Пов’язана документація -- [OpenShell](/gateway/openshell) -- налаштування керованого бекенда пісочниці, режими робочого простору та довідник конфігурації -- [Конфігурація пісочниці](/gateway/configuration-reference#agentsdefaultssandbox) -- [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) -- налагодження “чому це заблоковано?” -- [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) -- перевизначення для окремих агентів і пріоритети -- [Security](/gateway/security) +- [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) -- перевизначення для окремих агентів і пріоритети +- [Безпека](/uk/gateway/security)