> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Песочница

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

> [!NOTE]
>
> Это не идеальная граница безопасности, но она существенно ограничивает доступ к файловой системе и процессам, когда модель совершает необдуманные действия.

## Что выполняется в изолированной среде

* Выполнение инструментов: `exec`, `read`, `write`, `edit`, `apply_patch`, `process` и т. д.
* Необязательный изолированный браузер (`agents.defaults.sandbox.browser`).

Не выполняются в изолированной среде:

* Сам процесс Gateway.
* Любой инструмент, которому явно разрешено работать вне изолированной среды через `tools.elevated`. Выполнение с повышенными привилегиями обходит изоляцию и осуществляется по настроенному пути выхода (`gateway` по умолчанию или `node`, если целью выполнения является `node`). Если изоляция отключена, `tools.elevated` ничего не меняет, поскольку выполнение уже происходит на хосте. См. раздел [Режим повышенных привилегий](https://docs2.openclaw.ai/ru/tools/elevated.md).

## Режим, область действия и бэкенд

Поведение изолированной среды определяется тремя независимыми настройками:

| Настройка | Ключ | Значения | По умолчанию |
| - | - | - | - |
| Режим | `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 и целевой хост | Включённый плагин OpenShell |
| **Модель рабочего пространства** | Подключение через bind mount или копирование | Удалённое пространство как основное (однократное начальное заполнение) | `mirror` или `remote` |
| **Управление сетью** | `docker.network` (по умолчанию: отсутствует) | Зависит от удалённого хоста | Зависит от OpenShell |
| **Изоляция браузера** | Поддерживается | Не поддерживается | Пока не поддерживается |
| **Bind mount** | `docker.binds` | Неприменимо | Неприменимо |
| **Лучше всего подходит для** | Локальной разработки и полной изоляции | Переноса выполнения на удалённую машину | Управляемых удалённых изолированных сред с необязательной двусторонней синхронизацией |

## Бэкенд Docker

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

Значения по умолчанию: `network: "none"` (без исходящего трафика), `readOnlyRoot: true`, `capDrop: ["ALL"]`, образ `openclaw-sandbox:bookworm-slim`.

Чтобы предоставить доступ к GPU хоста, задайте для `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). Это накладывает ограничение на сопоставление путей:
>
> * **В конфигурации требуются пути хоста**: `openclaw.json` `workspace` должен содержать **абсолютный путь на хосте** (например, `/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 отключает для этого хода встроенный режим кода сервера приложений Codex, пользовательские серверы MCP и выполнение плагинов на базе приложений (они выполняются процессом сервера приложений на хосте Gateway, а не бэкендом изолированной среды OpenClaw), если только политика инструментов изолированной среды не предоставляет необходимые инструменты и вы не включили экспериментальный путь сервера выполнения в изолированной среде. После этого доступ к оболочке направляется через инструменты OpenClaw на базе изолированной среды, такие как `sandbox_exec` и `sandbox_process`. Не подключайте сокет Docker хоста к изолированным контейнерам агентов или пользовательским изолированным средам Codex. Полное описание поведения см. в разделе [Среда Codex](https://docs2.openclaw.ai/ru/plugins/codex-harness.md).
>
> На хостах Ubuntu/AppArmor с включённым режимом изоляции Docker для выполнения команд оболочки `workspace-write` сервера приложений Codex требуются непривилегированные пользовательские пространства имён внутри изолированного контейнера, и запуск может завершиться ошибкой ещё до старта оболочки, если пользователь службы не может их создать. Также требуется непривилегированное сетевое пространство имён, когда исходящий трафик из изолированной среды Docker отключён (`network: "none"`, значение по умолчанию). Типичные признаки: `bwrap: setting up uid map: Permission denied` и `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`. Выполните `openclaw doctor`; если команда сообщает об ошибке проверки пространства имён bwrap в Codex, предпочтительно использовать профиль AppArmor, предоставляющий процессу службы OpenClaw необходимые пространства имён. `kernel.apparmor_restrict_unprivileged_userns=0` — общесистемный запасной вариант с компромиссами в безопасности; используйте его, только если такая конфигурация безопасности хоста приемлема.

### Изолированный браузер

* Изолированный браузер запускается автоматически (чтобы обеспечить доступность 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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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",
          // Или используйте 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" },
        },
      },
    },
  },
}
```

Значения по умолчанию: `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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "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`/очистка обрабатывают среды выполнения OpenShell так же, как среды выполнения Docker; логика очистки учитывает бэкенд.

Полные требования, справочник по конфигурации, сравнение режимов рабочего пространства и сведения о жизненном цикле см. в разделе [OpenShell](https://docs2.openclaw.ai/ru/gateway/openshell.md).

## Доступ к рабочему пространству

`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`), чтобы их можно было прочитать. При `"rw"` навыки рабочего пространства доступны для чтения из `/workspace/skills`, а подходящие управляемые, встроенные навыки или навыки плагинов материализуются в созданном пути только для чтения `/workspace/.openclaw/sandbox-skills/skills`.

## Пользовательские bind-монтирования

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

Глобальные и заданные для отдельных агентов bind-монтирования объединяются (а не заменяются). При `scope: "shared"` bind-монтирования отдельных агентов игнорируются.

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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]
>
> **Безопасность bind-монтирований**
>
> * Bind-монтирования обходят файловую систему песочницы: они открывают доступ к путям хоста в заданном вами режиме (`:ro` или `:rw`).
> * По умолчанию OpenClaw блокирует опасные источники bind-монтирований: системные пути (`/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` указывает туда).
> * Целевые пути bind-монтирования, перекрывающие зарезервированные точки монтирования контейнера (`/workspace`, `/agent`), также блокируются по умолчанию; переопределите это с помощью `agents.defaults.sandbox.docker.dangerouslyAllowReservedContainerTargets: true`.
> * Источники bind-монтирования за пределами разрешённых корней рабочего пространства и рабочего пространства агента блокируются по умолчанию; переопределите это с помощью `agents.defaults.sandbox.docker.dangerouslyAllowExternalBindSources: true`. Разрешённые корни канонизируются таким же образом, поэтому путь, который выглядит находящимся внутри списка разрешённых путей только до разрешения символических ссылок, всё равно отклоняется как находящийся за пределами разрешённых корней.
> * Конфиденциальные монтирования (секреты, ключи SSH, учётные данные сервисов) должны использовать `:ro`, если иное не является абсолютно необходимым.
> * Используйте вместе с `workspaceAccess: "ro"`, если вам нужен только доступ к рабочему пространству для чтения; режимы bind-монтирования остаются независимыми.
> * О взаимодействии bind-монтирований с политикой инструментов и привилегированным exec см. в разделе [Песочница, политика инструментов и повышенные привилегии](https://docs2.openclaw.ai/ru/gateway/sandbox-vs-tool-policy-vs-elevated.md).

## Образы и настройка

Образ 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`.

**1. Сборка образа по умолчанию**

Из исходного репозитория:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
scripts/sandbox-setup.sh
```

Из установки npm (исходный репозиторий не требуется):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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. Если навыку требуется Node (или другие среды выполнения), создайте пользовательский образ с ними или установите их через `sandbox.docker.setupCommand` (требуются исходящий сетевой доступ, доступный для записи корень и пользователь root).

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

**2. Необязательно: сборка общего образа**

Для более функционального образа песочницы с распространёнными инструментами (например, `curl`, `jq`, Node 24, pnpm, `python3` и `git`):

Из исходного репозитория:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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`.

**3. Необязательно: сборка образа браузера песочницы**

Из исходного репозитория:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
scripts/sandbox-browser-setup.sh
```

При установке через npm выполните сборку с использованием файла [`scripts/docker/sandbox/Dockerfile.browser`](https://github.com/openclaw/openclaw/blob/main/scripts/docker/sandbox/Dockerfile.browser) из репозитория.

По умолчанию контейнеры песочницы Docker запускаются **без сети**. Переопределите это с помощью `agents.defaults.sandbox.docker.network`.

> [accordion] Настройки 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 или другие функции 3D.
> * По умолчанию `--disable-extensions`; задайте `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` для сценариев, зависящих от расширений.
> * По умолчанию `--renderer-process-limit=2`; управляется параметром `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>`, где `0` сохраняет значение Chromium по умолчанию.
>
> Если вам нужен другой профиль среды выполнения, используйте пользовательский образ браузера и укажите собственную точку входа. Для локальных (вне контейнера) профилей Chromium используйте `browser.extraArgs`, чтобы добавить дополнительные флаги запуска.

> [accordion] Настройки сетевой безопасности по умолчанию
>
> * `network: "host"` заблокирован.
> * `network: "container:<id>"` заблокирован по умолчанию (риск обхода через присоединение пространства имён).
> * Аварийное переопределение: `agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`.

Установки Docker и контейнеризованный Gateway описаны здесь: [Docker](https://docs2.openclaw.ai/ru/install/docker.md)

Для развёртываний Gateway в Docker параметр `scripts/docker/setup.sh` может выполнить начальную настройку конфигурации песочницы. Задайте `OPENCLAW_SANDBOX=1` (или `true`/`yes`/`on`), чтобы включить этот путь. Переопределите расположение сокета с помощью `OPENCLAW_DOCKER_SOCKET`. Полная настройка и справочник переменных окружения: [Docker](https://docs2.openclaw.ai/ru/install/docker.md#agent-sandbox).

## setupCommand (однократная настройка контейнера)

`setupCommand` выполняется **один раз** после создания контейнера песочницы (не при каждом запуске). Команда выполняется внутри контейнера через `sh -lc`.

Пути:

* Глобальный: `agents.defaults.sandbox.docker.setupCommand`
* Для отдельного агента: `agents.list[].sandbox.docker.setupCommand`

> [accordion] Распространённые ошибки
>
> * Значение `docker.network` по умолчанию — `"none"` (без исходящего доступа), поэтому установка пакетов завершится ошибкой.
> * `docker.network: "container:<id>"` требует `dangerouslyAllowContainerNamespaceJoin: true` и предназначен только для аварийного использования.
> * `readOnlyRoot: true` запрещает запись; задайте `readOnlyRoot: false` или создайте пользовательский образ.
> * Для установки пакетов `user` должен быть пользователем root (не указывайте `user` или задайте `user: "0:0"`).
> * Exec в песочнице **не** наследует `process.env` хоста. Используйте `agents.defaults.sandbox.docker.env` (или пользовательский образ) для ключей API навыков.
> * Значения в `agents.defaults.sandbox.docker.env` передаются как явные переменные окружения контейнера Docker. Любой пользователь с доступом к демону Docker может просмотреть их с помощью команд метаданных Docker, таких как `docker inspect`. Если такое раскрытие через метаданные неприемлемо, используйте пользовательский образ, смонтированный файл с секретами или другой способ передачи секретов.

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

Политики разрешения и запрета инструментов применяются до правил песочницы. Если инструмент запрещён глобально или для отдельного агента, песочница не сделает его снова доступным.

`tools.elevated` — это явный механизм обхода, который запускает `exec` вне песочницы (по умолчанию — `gateway`, а когда целью выполнения является `node` — `node`). Директивы `/exec` применяются только для авторизованных отправителей и сохраняются в рамках сеанса; чтобы полностью отключить `exec`, запретите его в политике инструментов (см. [Песочница, политика инструментов и повышенные привилегии](https://docs2.openclaw.ai/ru/gateway/sandbox-vs-tool-policy-vs-elevated.md)).

Отладка:

* `openclaw sandbox list` показывает контейнеры песочницы, их состояние, соответствие образу, возраст, время простоя и связанный сеанс или агент.
* `openclaw sandbox explain [--session <key>] [--agent <id>]` проверяет действующий режим песочницы, рабочее пространство хоста, рабочий каталог среды выполнения, точки монтирования Docker, политику инструментов и ключи конфигурации для устранения проблем. Поле `workspaceRoot` по-прежнему содержит настроенный корневой каталог песочницы; `effectiveHostWorkspaceRoot` показывает фактическое расположение активного рабочего пространства.
* `openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force]` удаляет контейнеры и среды, чтобы при следующем использовании они были созданы заново с текущей конфигурацией.
* Ментальную модель для понимания причин блокировки см. в разделе [Песочница, политика инструментов и повышенные привилегии](https://docs2.openclaw.ai/ru/gateway/sandbox-vs-tool-policy-vs-elevated.md).

## Переопределения для нескольких агентов

Для каждого агента можно переопределить настройки песочницы и инструментов: `agents.list[].sandbox` и `agents.list[].tools` (а также `agents.list[].tools.sandbox.tools` для политики инструментов песочницы). Порядок приоритетов описан в разделе [Песочница и инструменты для нескольких агентов](https://docs2.openclaw.ai/ru/tools/multi-agent-sandbox-tools.md).

## Минимальный пример включения

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
}
```

## Связанные разделы

* [Песочница и инструменты для нескольких агентов](https://docs2.openclaw.ai/ru/tools/multi-agent-sandbox-tools.md) — переопределения для отдельных агентов и порядок приоритетов
* [OpenShell](https://docs2.openclaw.ai/ru/gateway/openshell.md) — настройка управляемого бэкенда песочницы, режимы рабочего пространства и справочник по конфигурации
* [Конфигурация песочницы](https://docs2.openclaw.ai/ru/gateway/config-agents.md#agentsdefaultssandbox)
* [Песочница, политика инструментов и повышенные привилегии](https://docs2.openclaw.ai/ru/gateway/sandbox-vs-tool-policy-vs-elevated.md) — отладка причин блокировки
* [Безопасность](https://docs2.openclaw.ai/ru/gateway/security.md)