Песочница

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

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

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

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

• Сам процесс Gateway.
• Любой инструмент, которому явно разрешено работать вне изолированной среды через tools.elevated. Выполнение с повышенными привилегиями обходит изоляцию и осуществляется по настроенному пути выхода (gateway по умолчанию или node, если целью выполнения является node). Если изоляция отключена, tools.elevated ничего не меняет, поскольку выполнение уже происходит на хосте. См. раздел Режим повышенных привилегий.

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

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

Режим определяет, когда применяется изоляция:

• 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

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.

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

• Изолированный браузер запускается автоматически (чтобы обеспечить доступность 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.

{  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.

{  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.

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

agents.defaults.sandbox.workspaceAccess определяет, что может видеть песочница:

При использовании бэкенда OpenShell режим mirror по-прежнему использует локальное рабочее пространство как канонический источник между вызовами exec, режим remote использует удалённое рабочее пространство OpenShell как каноническое после первоначальной инициализации, а workspaceAccess: "ro"/"none" по-прежнему ограничивают запись таким же образом.

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

Пользовательские 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.

{  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"],          },        },      },    ],  },}

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

Образ Docker по умолчанию: openclaw-sandbox:bookworm-slim

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'FROM debian:bookworm-slimENV DEBIAN_FRONTEND=noninteractiveRUN 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 sandboxUSER sandboxWORKDIR /home/sandboxCMD ["sleep", "infinity"]DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

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

Установки Docker и контейнеризованный Gateway описаны здесь: Docker

Для развёртываний Gateway в Docker параметр scripts/docker/setup.sh может выполнить начальную настройку конфигурации песочницы. Задайте OPENCLAW_SANDBOX=1 (или true/yes/on), чтобы включить этот путь. Переопределите расположение сокета с помощью OPENCLAW_DOCKER_SOCKET. Полная настройка и справочник переменных окружения: Docker.

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

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

Пути:

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

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

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

tools.elevated — это явный механизм обхода, который запускает exec вне песочницы (по умолчанию — gateway, а когда целью выполнения является node — node). Директивы /exec применяются только для авторизованных отправителей и сохраняются в рамках сеанса; чтобы полностью отключить exec, запретите его в политике инструментов (см. Песочница, политика инструментов и повышенные привилегии).

Отладка:

• openclaw sandbox list показывает контейнеры песочницы, их состояние, соответствие образу, возраст, время простоя и связанный сеанс или агент.
• openclaw sandbox explain [--session <key>] [--agent <id>] проверяет действующий режим песочницы, рабочее пространство хоста, рабочий каталог среды выполнения, точки монтирования Docker, политику инструментов и ключи конфигурации для устранения проблем. Поле workspaceRoot по-прежнему содержит настроенный корневой каталог песочницы; effectiveHostWorkspaceRoot показывает фактическое расположение активного рабочего пространства.
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] удаляет контейнеры и среды, чтобы при следующем использовании они были созданы заново с текущей конфигурацией.
• Ментальную модель для понимания причин блокировки см. в разделе Песочница, политика инструментов и повышенные привилегии.

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

Для каждого агента можно переопределить настройки песочницы и инструментов: agents.list[].sandbox и agents.list[].tools (а также agents.list[].tools.sandbox.tools для политики инструментов песочницы). Порядок приоритетов описан в разделе Песочница и инструменты для нескольких агентов.

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

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

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

• Песочница и инструменты для нескольких агентов — переопределения для отдельных агентов и порядок приоритетов
• OpenShell — настройка управляемого бэкенда песочницы, режимы рабочего пространства и справочник по конфигурации
• Конфигурация песочницы
• Песочница, политика инструментов и повышенные привилегии — отладка причин блокировки
• Безопасность