---
read_when: You want a dedicated explanation of sandboxing or need to tune agents.defaults.sandbox.
sidebarTitle: Sandboxing
status: active
summary: 'Як працює ізоляція OpenClaw: режими, області дії, доступ до робочого простору та образи'
title: Ізоляція
x-i18n:
    generated_at: "2026-07-12T13:15:14Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 60d6695c5d8f4e8d3bfb80dd387a50c104dc4e140d5974a66d5a2176594782a4
    source_path: gateway/sandboxing.md
    workflow: 16
---

OpenClaw може виконувати інструменти в ізольованому середовищі, щоб зменшити масштаб потенційних наслідків. Ізоляцію типово вимкнено; нею керують параметри `agents.defaults.sandbox` (глобально) або `agents.list[].sandbox` (для окремого агента). Процес Gateway завжди залишається на хості; коли ізоляцію ввімкнено, до ізольованого середовища переноситься лише виконання інструментів.

<Note>
Це не ідеальна межа безпеки, але вона суттєво обмежує доступ до файлової системи та процесів, коли модель робить щось нерозумне.
</Note>

## Що ізолюється

- Виконання інструментів: `exec`, `read`, `write`, `edit`, `apply_patch`, `process` тощо.
- Необов’язковий ізольований браузер (`agents.defaults.sandbox.browser`).

Не ізолюються:

- Сам процес Gateway.
- Будь-який інструмент, якому через `tools.elevated` явно дозволено працювати поза ізольованим середовищем. Виконання з підвищеними привілеями оминає ізоляцію та відбувається за налаштованим шляхом виходу (`gateway` типово або `node`, коли ціль виконання — `node`). Якщо ізоляцію вимкнено, `tools.elevated` нічого не змінює, оскільки виконання й так відбувається на хості. Див. [Режим підвищених привілеїв](/uk/tools/elevated).

## Режим, область дії та бекенд

Поведінкою ізольованого середовища керують три незалежні параметри:

| Параметр      | Ключ                              | Значення                     | Типове значення |
| ------------- | --------------------------------- | ---------------------------- | --------------- |
| Режим         | `agents.defaults.sandbox.mode`    | `off`, `non-main`, `all`     | `off`           |
| Область дії   | `agents.defaults.sandbox.scope`   | `agent`, `session`, `shared` | `agent`         |
| Бекенд        | `agents.defaults.sandbox.backend` | `docker`, `ssh`, `openshell` | `docker`        |

**Режим** визначає, коли застосовується ізоляція:

- `off`: без ізоляції.
- `non-main`: ізолювати кожен сеанс, крім основного сеансу агента. Ключ основного сеансу завжди має вигляд `agent:<agentId>:main` (або `global`, коли `session.scope` має значення `"global"`); його не можна налаштувати. Групові сеанси та сеанси каналів використовують власні ключі, тому завжди вважаються неосновними та ізолюються.
- `all`: кожен сеанс працює в ізольованому середовищі.

**Область дії** визначає кількість створюваних контейнерів або середовищ:

- `agent`: один контейнер на агента.
- `session`: один контейнер на сеанс.
- `shared`: один контейнер, спільний для всіх ізольованих сеансів (перевизначення `docker`/`ssh`/`browser` для окремих агентів у цій області дії ігноруються).

**Бекенд** визначає середовище виконання ізольованих інструментів. Конфігурація для SSH міститься в `agents.defaults.sandbox.ssh`, а конфігурація для OpenShell — у `plugins.entries.openshell.config`.

|                                | Docker                              | SSH                                      | OpenShell                                                    |
| ------------------------------ | ----------------------------------- | ---------------------------------------- | ------------------------------------------------------------ |
| **Де виконується**             | Локальний контейнер                 | Будь-який хост із доступом через SSH     | Ізольоване середовище під керуванням OpenShell                |
| **Налаштування**               | `scripts/sandbox-setup.sh`          | Ключ SSH і цільовий хост                 | Увімкнений Plugin OpenShell                                   |
| **Модель робочого простору**   | Монтування або копіювання           | Віддалений канонічний простір (одноразове початкове заповнення) | `mirror` або `remote`                              |
| **Керування мережею**          | `docker.network` (типово: немає)    | Залежить від віддаленого хоста           | Залежить від OpenShell                                       |
| **Ізольований браузер**        | Підтримується                       | Не підтримується                         | Поки не підтримується                                        |
| **Монтування каталогів**       | `docker.binds`                      | Н/Д                                      | Н/Д                                                          |
| **Найкраще підходить для**     | Локальної розробки, повної ізоляції | Перенесення навантаження на віддалену машину | Керованих віддалених ізольованих середовищ із необов’язковою двосторонньою синхронізацією |

## Бекенд Docker

Docker є типовим бекендом після ввімкнення ізоляції. Він локально запускає інструменти та ізольовані браузери через сокет демона Docker (`/var/run/docker.sock`); ізоляцію забезпечують простори імен Docker.

Типові значення: `network: "none"` (без вихідного доступу), `readOnlyRoot: true`, `capDrop: ["ALL"]`, образ `openclaw-sandbox:bookworm-slim`.

Щоб надати доступ до графічних процесорів хоста, задайте для `agents.defaults.sandbox.docker.gpus` (або перевизначення для окремого агента) значення на кшталт `"all"` чи `"device=GPU-uuid"`. Воно передається прапорцю Docker `--gpus` і потребує сумісного середовища виконання на хості, наприклад NVIDIA Container Toolkit.

<Warning>
**Обмеження Docker-out-of-Docker (DooD)**

Якщо сам Gateway OpenClaw розгорнуто як контейнер Docker, він керує сусідніми ізольованими контейнерами через сокет Docker хоста (DooD). Це накладає обмеження на зіставлення шляхів:

- **У конфігурації потрібні шляхи хоста**: параметр `workspace` у `openclaw.json` має містити **абсолютний шлях хоста** (наприклад, `/home/user/.openclaw/workspaces`), а не внутрішній шлях контейнера Gateway. Демон Docker обробляє шляхи відносно простору імен ОС хоста, а не простору імен самого Gateway.
- **Потрібне відповідне зіставлення тому**: процес Gateway також записує файли Heartbeat і моста за цим шляхом `workspace`. Надайте контейнеру Gateway ідентичне зіставлення тому (`-v /home/user/.openclaw:/home/user/.openclaw`), щоб той самий шлях хоста правильно визначався і всередині контейнера Gateway. Невідповідні зіставлення проявляються як `EACCES`, коли Gateway намагається записати свій Heartbeat.
- **Режим коду Codex**: коли активне ізольоване середовище OpenClaw, OpenClaw вимикає на цей хід власний Code Mode сервера застосунку Codex, користувацькі сервери MCP і виконання плагінів на базі застосунків (вони запускаються процесом сервера застосунку на хості Gateway, а не бекендом ізольованого середовища OpenClaw), якщо політика інструментів ізольованого середовища не надає потрібні інструменти й ви не ввімкнули експериментальний шлях сервера виконання в ізольованому середовищі. Після цього доступ до оболонки спрямовується через інструменти з бекендом ізольованого середовища OpenClaw, як-от `sandbox_exec` і `sandbox_process`. Не монтуйте сокет Docker хоста в ізольовані контейнери агентів або власні ізольовані середовища Codex. Повний опис поведінки див. у розділі [Середовище Codex](/uk/plugins/codex-harness).

На хостах Ubuntu/AppArmor з увімкненим режимом ізоляції Docker для виконання команд оболонки Codex app-server із доступом `workspace-write` потрібні непривілейовані користувацькі простори імен усередині ізольованого контейнера; запуск може завершитися помилкою ще до запуску оболонки, якщо користувач служби не може їх створити. Коли вихідний мережевий доступ ізольованого середовища Docker вимкнено (`network: "none"`, типове значення), також потрібен непривілейований мережевий простір імен. Типові ознаки: `bwrap: setting up uid map: Permission denied` і `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`. Запустіть `openclaw doctor`; якщо він повідомить про помилку перевірки простору імен Codex bwrap, надайте перевагу профілю AppArmor, який дозволяє процесу служби OpenClaw створювати потрібні простори імен. `kernel.apparmor_restrict_unprivileged_userns=0` — загальносистемний резервний варіант із компромісами щодо безпеки; використовуйте його лише тоді, коли така конфігурація безпеки хоста є прийнятною.
</Warning>

### Ізольований браузер

- Ізольований браузер запускається автоматично (що забезпечує доступність CDP), коли він потрібен інструменту браузера. Налаштовуйте це через `agents.defaults.sandbox.browser.autoStart` (типово `true`) і `autoStartTimeoutMs` (типово 12 с).
- Контейнери ізольованого браузера використовують окрему мережу 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 із короткочасним токеном, який віддає локальну початкову сторінку та відкриває noVNC із паролем у фрагменті URL (не в рядку запиту чи журналах заголовків).
- `agents.defaults.sandbox.browser.allowHostControl` (типово `false`) дає ізольованим сеансам змогу явно вибирати браузер хоста як ціль.
- Необов’язкові списки дозволених значень обмежують `target: "custom"`: `allowedControlUrls`, `allowedControlHosts`, `allowedControlPorts`.

## Бекенд SSH

Використовуйте `backend: "ssh"`, щоб ізолювати `exec`, файлові інструменти та читання медіафайлів на довільній машині з доступом через SSH.

```json5
{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "ssh",
        scope: "session",
        workspaceAccess: "rw",
        ssh: {
          target: "user@gateway-host:22",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // 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" },
        },
      },
    },
  },
}
```

Типові значення: `command: "ssh"`, `workspaceRoot: "/tmp/openclaw-sandboxes"`, `strictHostKeyChecking: true`, `updateHostKeys: true`.

- **Життєвий цикл**: OpenClaw створює віддалений кореневий каталог для кожної області дії в `sandbox.ssh.workspaceRoot`. Під час першого використання після створення або повторного створення він один раз початково заповнює цей віддалений робочий простір із локального. Після цього `exec`, `read`, `write`, `edit`, `apply_patch`, читання медіафайлів із запиту та підготовка вхідних медіафайлів виконуються безпосередньо з віддаленим робочим простором через SSH. OpenClaw не синхронізує віддалені зміни назад до локального робочого простору автоматично.
- **Матеріали автентифікації**: `identityFile`/`certificateFile`/`knownHostsFile` посилаються на наявні локальні файли. `identityData`/`certificateData`/`knownHostsData` приймають вбудовані рядки або SecretRefs, які визначаються через звичайний знімок середовища виконання секретів, записуються до тимчасових файлів із режимом `0600` і видаляються після завершення сеансу SSH. Якщо для того самого елемента задано і варіант `*File`, і варіант `*Data`, у цьому сеансі перевагу має `*Data`.
- **Наслідки віддаленого канонічного простору**: після початкового заповнення віддалений робочий простір SSH стає фактичним станом ізольованого середовища. Локальні зміни на хості, внесені поза OpenClaw після етапу початкового заповнення, не відображаються віддалено, доки ви не створите ізольоване середовище повторно. `openclaw sandbox recreate` видаляє віддалений кореневий каталог відповідної області дії, а під час наступного використання знову початково заповнює його з локального простору. Цей бекенд не підтримує ізоляцію браузера, а параметри `sandbox.docker.*` до нього не застосовуються.

## Бекенд OpenShell

Використовуйте `backend: "openshell"`, щоб ізолювати інструменти у віддаленому середовищі під керуванням OpenShell. OpenShell повторно використовує той самий транспорт SSH і міст віддаленої файлової системи, що й універсальний бекенд SSH, а також додає керування життєвим циклом OpenShell (`sandbox create/get/delete/ssh-config`) і необов’язковий режим синхронізації робочого простору `mirror`.

```json5
{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote", // mirror | remote
        },
      },
    },
  },
}
```

`mode: "mirror"` (типово) зберігає локальний робочий простір канонічним: OpenClaw синхронізує локальні дані до ізольованого середовища перед `exec` і синхронізує їх назад після виконання. `mode: "remote"` один раз початково заповнює віддалений робочий простір із локального, а потім виконує `exec`/`read`/`write`/`edit`/`apply_patch` безпосередньо з віддаленим робочим простором без зворотної синхронізації; локальні зміни після початкового заповнення не відображаються, доки ви не виконаєте `openclaw sandbox recreate`. За `scope: "agent"` або `scope: "shared"` цей віддалений робочий простір є спільним у межах відповідної області дії. Поточні обмеження: ізольований браузер поки не підтримується, а `sandbox.docker.binds` не застосовується до цього бекенду.

`openclaw sandbox list`/`recreate`/prune обробляють середовища виконання OpenShell так само, як середовища виконання Docker; логіка очищення враховує бекенд.

Повний перелік передумов, довідник із конфігурації, порівняння режимів робочого простору та подробиці життєвого циклу див. у розділі [OpenShell](/uk/gateway/openshell).

## Доступ до робочого простору

`agents.defaults.sandbox.workspaceAccess` визначає, що може бачити ізольоване середовище:

| Значення         | Поведінка                                                                                       |
| ---------------- | ----------------------------------------------------------------------------------------------- |
| `none` (типово)  | Інструменти бачать ізольований робочий простір пісочниці в `~/.openclaw/sandboxes`.              |
| `ro`             | Монтує робочий простір агента лише для читання в `/agent` (вимикає `write`/`edit`/`apply_patch`). |
| `rw`             | Монтує робочий простір агента для читання й запису в `/workspace`.                               |

З бекендом OpenShell режим `mirror` і надалі використовує локальний робочий простір як канонічне джерело між викликами exec, режим `remote` після початкового заповнення використовує як канонічний віддалений робочий простір OpenShell, а `workspaceAccess: "ro"`/`"none"` так само обмежує можливість запису.

Вхідні медіафайли копіюються до активного робочого простору пісочниці (`media/inbound/*`).

<Note>
**Skills**: інструмент `read` обмежений коренем пісочниці. За `workspaceAccess: "none"` OpenClaw дзеркалює придатні Skills до робочого простору пісочниці (`.../skills`), щоб їх можна було читати. За `"rw"` Skills робочого простору доступні для читання з `/workspace/skills`, а придатні керовані, вбудовані або плагінні Skills матеріалізуються у створеному шляху лише для читання `/workspace/.openclaw/sandbox-skills/skills`.
</Note>

## Власні прив’язувальні монтування

`agents.defaults.sandbox.docker.binds` монтує додаткові каталоги хоста до контейнера. Формат: `host:container:mode` (наприклад, `"/home/user/source:/source:rw"`).

Глобальні прив’язки та прив’язки окремих агентів об’єднуються (а не замінюються). За `scope: "shared"` прив’язки окремих агентів ігноруються.

`agents.defaults.sandbox.browser.binds` монтує додаткові каталоги хоста лише до контейнера **браузера пісочниці**. Якщо значення задано (зокрема `[]`), воно замінює `docker.binds` для контейнера браузера; якщо його пропущено, контейнер браузера використовує `docker.binds` як резервний варіант.

```json5
{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          binds: ["/home/user/source:/source:ro", "/var/data/myapp:/data:ro"],
        },
      },
    },
    list: [
      {
        id: "build",
        sandbox: {
          docker: {
            binds: ["/mnt/cache:/cache:rw"],
          },
        },
      },
    ],
  },
}
```

<Warning>
**Безпека прив’язок**

- Прив’язки обходять файлову систему пісочниці: вони відкривають шляхи хоста в указаному режимі (`:ro` або `:rw`).
- OpenClaw типово блокує небезпечні джерела прив’язок: системні шляхи (`/etc`, `/proc`, `/sys`, `/dev`, `/root`, `/boot`), каталоги сокетів Docker (`/run`, `/var/run` та їхні варіанти з `docker.sock`) і поширені кореневі каталоги облікових даних у домашньому каталозі (`~/.aws`, `~/.cargo`, `~/.config`, `~/.docker`, `~/.gnupg`, `~/.netrc`, `~/.npm`, `~/.ssh`).
- Перевірка нормалізує шлях джерела, а потім знову розв’язує його через найглибшого наявного предка перед повторною перевіркою заблокованих шляхів і дозволених коренів. Тому спроби виходу через батьківський символічний зв’язок блокуються навіть тоді, коли кінцевий елемент ще не існує (наприклад, `/workspace/run-link/new-file` усе одно розв’язується як `/var/run/...`, якщо `run-link` указує туди).
- Цілі прив’язок, які перекривають зарезервовані точки монтування контейнера (`/workspace`, `/agent`), також типово блокуються; перевизначте це за допомогою `agents.defaults.sandbox.docker.dangerouslyAllowReservedContainerTargets: true`.
- Джерела прив’язок поза коренями робочого простору або робочого простору агента зі списку дозволених типово блокуються; перевизначте це за допомогою `agents.defaults.sandbox.docker.dangerouslyAllowExternalBindSources: true`. Дозволені корені канонізуються так само, тому шлях, який лише виглядає розташованим у списку дозволених до розв’язання символічних зв’язків, усе одно відхиляється як такий, що перебуває поза дозволеними коренями.
- Чутливі монтування (секрети, ключі SSH, облікові дані сервісів) мають бути `:ro`, якщо запис не є абсолютно необхідним.
- Поєднуйте з `workspaceAccess: "ro"`, якщо вам потрібен лише доступ для читання до робочого простору; режими прив’язок залишаються незалежними.
- Відомості про взаємодію прив’язок із політикою інструментів і привілейованим виконанням див. у розділі [Пісочниця, політика інструментів і привілейоване виконання](/uk/gateway/sandbox-vs-tool-policy-vs-elevated).

</Warning>

## Образи та налаштування

Типовий образ Docker: `openclaw-sandbox:bookworm-slim`

<Note>
**Робоча копія вихідного коду та встановлення через npm**

Допоміжні сценарії `scripts/sandbox-setup.sh`, `scripts/sandbox-common-setup.sh` і `scripts/sandbox-browser-setup.sh` доступні лише під час запуску з [робочої копії вихідного коду](https://github.com/openclaw/openclaw). Вони не входять до пакета npm.

Якщо ви встановили OpenClaw за допомогою `npm install -g openclaw`, натомість використовуйте наведені нижче вбудовані команди `docker build`.
</Note>

<Steps>
  <Step title="Створення типового образу">
    З робочої копії вихідного коду:

    ```bash
    scripts/sandbox-setup.sh
    ```

    Зі встановлення npm (робоча копія вихідного коду не потрібна):

    ```bash
    docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'
    FROM debian:bookworm-slim
    ENV DEBIAN_FRONTEND=noninteractive
    RUN apt-get update && apt-get install -y --no-install-recommends \
      bash ca-certificates curl git jq python3 ripgrep \
      && rm -rf /var/lib/apt/lists/*
    RUN useradd --create-home --shell /bin/bash sandbox
    USER sandbox
    WORKDIR /home/sandbox
    CMD ["sleep", "infinity"]
    DOCKERFILE
    ```

    Типовий образ **не** містить Node. Якщо для Skill потрібен Node (або інші середовища виконання), створіть власний образ або встановіть потрібне через `sandbox.docker.setupCommand` (потрібні вихідний доступ до мережі, доступний для запису корінь і користувач root).

    OpenClaw не підставляє непомітно звичайний `debian:bookworm-slim`, коли `openclaw-sandbox:bookworm-slim` відсутній. Запуски пісочниці, націлені на типовий образ, одразу завершуються помилкою з інструкцією зі створення образу, доки ви його не створите, оскільки вбудований образ містить `python3` для допоміжних засобів запису й редагування в пісочниці.

  </Step>
  <Step title="Необов’язково: створення образу із загальними інструментами">
    Щоб отримати функціональніший образ пісочниці з поширеними інструментами (наприклад, `curl`, `jq`, Node 24, pnpm, `python3` і `git`):

    З робочої копії вихідного коду:

    ```bash
    scripts/sandbox-common-setup.sh
    ```

    У разі встановлення через npm спочатку створіть типовий образ (див. вище), а потім створіть поверх нього образ із загальними інструментами, використовуючи [`scripts/docker/sandbox/Dockerfile.common`](https://github.com/openclaw/openclaw/blob/main/scripts/docker/sandbox/Dockerfile.common) з репозиторію.

    Потім установіть для `agents.defaults.sandbox.docker.image` значення `openclaw-sandbox-common:bookworm-slim`.

  </Step>
  <Step title="Необов’язково: створення образу браузера пісочниці">
    З робочої копії вихідного коду:

    ```bash
    scripts/sandbox-browser-setup.sh
    ```

    У разі встановлення через npm створіть образ за допомогою [`scripts/docker/sandbox/Dockerfile.browser`](https://github.com/openclaw/openclaw/blob/main/scripts/docker/sandbox/Dockerfile.browser) з репозиторію.

  </Step>
</Steps>

Типово контейнери пісочниці Docker запускаються **без мережі**. Перевизначте це за допомогою `agents.defaults.sandbox.docker.network`.

<AccordionGroup>
  <Accordion title="Типові параметри Chromium у браузері пісочниці">
    Вбудований образ браузера пісочниці застосовує консервативні прапорці запуску Chromium для контейнеризованих робочих навантажень:

    - `--remote-debugging-address=127.0.0.1`
    - `--remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>`
    - `--user-data-dir=${HOME}/.chrome`
    - `--no-first-run`
    - `--no-default-browser-check`
    - `--disable-dev-shm-usage`
    - `--disable-background-networking`
    - `--disable-breakpad`
    - `--disable-crash-reporter`
    - `--no-zygote`
    - `--metrics-recording-only`
    - `--password-store=basic`
    - `--use-mock-keychain`
    - `--headless=new`, коли `browser.headless` увімкнено.
    - `--no-sandbox --disable-setuid-sandbox`, коли `browser.noSandbox` увімкнено.
    - `--disable-3d-apis`, `--disable-gpu`, `--disable-software-rasterizer` типово; ці прапорці посилення графічної безпеки допомагають у контейнерах без підтримки GPU. Установіть `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо вашому робочому навантаженню потрібні WebGL або інші тривимірні можливості.
    - `--disable-extensions` типово; установіть `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` для процесів, що залежать від розширень.
    - `--renderer-process-limit=2` типово; керується за допомогою `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>`, де `0` зберігає типове значення Chromium.

    Якщо вам потрібен інший профіль середовища виконання, використайте власний образ браузера та надайте власну точку входу. Для локальних (неконтейнерних) профілів Chromium використовуйте `browser.extraArgs`, щоб додати додаткові прапорці запуску.

  </Accordion>
  <Accordion title="Типові параметри мережевої безпеки">
    - `network: "host"` заблоковано.
    - `network: "container:<id>"` типово заблоковано (ризик обходу через приєднання до простору імен).
    - Аварійне перевизначення: `agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`.

  </Accordion>
</AccordionGroup>

Встановлення Docker і контейнеризований Gateway описано тут: [Docker](/uk/install/docker)

Для розгортань Gateway у Docker сценарій `scripts/docker/setup.sh` може виконати початкове налаштування конфігурації пісочниці. Установіть `OPENCLAW_SANDBOX=1` (або `true`/`yes`/`on`), щоб увімкнути цей шлях. Перевизначте розташування сокета за допомогою `OPENCLAW_DOCKER_SOCKET`. Повне налаштування та довідка щодо змінних середовища: [Docker](/uk/install/docker#agent-sandbox).

## setupCommand (одноразове налаштування контейнера)

`setupCommand` запускається **один раз** після створення контейнера пісочниці (не під час кожного запуску). Він виконується всередині контейнера через `sh -lc`.

Шляхи:

- Глобальний: `agents.defaults.sandbox.docker.setupCommand`
- Для окремого агента: `agents.list[].sandbox.docker.setupCommand`

<AccordionGroup>
  <Accordion title="Поширені проблеми">
    - Типовим значенням `docker.network` є `"none"` (без вихідного доступу), тому встановлення пакетів завершиться помилкою.
    - `docker.network: "container:<id>"` потребує `dangerouslyAllowContainerNamespaceJoin: true` і призначений лише для аварійного використання.
    - `readOnlyRoot: true` забороняє запис; установіть `readOnlyRoot: false` або створіть власний образ.
    - Для встановлення пакетів `user` має бути root (пропустіть `user` або встановіть `user: "0:0"`).
    - Виконання в пісочниці **не** успадковує `process.env` хоста. Використовуйте `agents.defaults.sandbox.docker.env` (або власний образ) для ключів API Skills.
    - Значення з `agents.defaults.sandbox.docker.env` передаються як явні змінні середовища контейнера Docker. Будь-хто з доступом до демона Docker може переглянути їх за допомогою команд метаданих Docker, як-от `docker inspect`. Якщо таке розкриття через метадані неприйнятне, використовуйте власний образ, змонтований файл секретів або інший спосіб передавання секретів.

  </Accordion>
</AccordionGroup>

## Політика інструментів і механізми обходу

Політики дозволу й заборони інструментів застосовуються перед правилами пісочниці. Якщо інструмент заборонено глобально або для окремого агента, пісочниця не повертає його.

`tools.elevated` — це явний механізм обходу, який запускає `exec` поза пісочницею (типово в `gateway` або в `node`, коли ціллю виконання є `node`). Директиви `/exec` застосовуються лише до авторизованих відправників і зберігаються протягом сеансу; щоб повністю вимкнути `exec`, забороніть його в політиці інструментів (див. [Пісочниця, політика інструментів і привілейоване виконання](/uk/gateway/sandbox-vs-tool-policy-vs-elevated)).

Налагодження:

- `openclaw sandbox list` показує контейнери пісочниці, стан, відповідність образу, вік, час бездіяльності та пов’язаний сеанс або агент.
- `openclaw sandbox explain [--session <key>] [--agent <id>]` перевіряє фактичний режим пісочниці, робочий простір хоста, робочий каталог середовища виконання, монтування Docker, політику інструментів і ключі конфігурації для виправлення. Поле `workspaceRoot` залишається налаштованим коренем пісочниці; `effectiveHostWorkspaceRoot` показує, де фактично розташований активний робочий простір.
- `openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force]` видаляє контейнери або середовища, щоб під час наступного використання вони були створені заново з поточною конфігурацією.
- Модель мислення для запитання «чому це заблоковано?» див. у розділі [Пісочниця, політика інструментів і привілейоване виконання](/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).

## Мінімальний приклад увімкнення

```json5
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
}
```

## Пов’язане

- [Пісочниця та інструменти для кількох агентів](/uk/tools/multi-agent-sandbox-tools) -- перевизначення для окремих агентів і порядок пріоритетів
- [OpenShell](/uk/gateway/openshell) -- налаштування керованого бекенду пісочниці, режими робочого простору та довідник конфігурації
- [Конфігурація пісочниці](/uk/gateway/config-agents#agentsdefaultssandbox)
- [Пісочниця, політика інструментів і підвищені привілеї](/uk/gateway/sandbox-vs-tool-policy-vs-elevated) -- налагодження питання «чому це заблоковано?»
- [Безпека](/uk/gateway/security)
