Песочница

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

Что помещается в песочницу

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

Не помещается в песочницу:

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

Режимы

agents.defaults.sandbox.mode управляет тем, когда используется песочница:

Область действия

agents.defaults.sandbox.scope управляет тем, сколько контейнеров создается:

• "agent" (по умолчанию): один контейнер на агента.
• "session": один контейнер на сессию.
• "shared": один контейнер, общий для всех сессий в песочнице.

Бэкенд

agents.defaults.sandbox.backend управляет тем, какая среда выполнения предоставляет песочницу:

• "docker" (по умолчанию, когда песочница включена): локальная среда выполнения песочницы на базе Docker.
• "ssh": универсальная удаленная среда выполнения песочницы на базе SSH.
• "openshell": среда выполнения песочницы на базе OpenShell.

Конфигурация, специфичная для SSH, находится в agents.defaults.sandbox.ssh. Конфигурация, специфичная для OpenShell, находится в plugins.entries.openshell.config.

Выбор бэкенда

Бэкенд Docker

Песочница по умолчанию отключена. Если вы включаете песочницу и не выбираете бэкенд, OpenClaw использует бэкенд Docker. Он выполняет инструменты и браузеры в песочнице локально через сокет демона Docker (/var/run/docker.sock). Изоляция контейнера песочницы определяется пространствами имен Docker.

Чтобы предоставить GPU хоста песочницам Docker, задайте agents.defaults.sandbox.docker.gpus или переопределение на уровне агента agents.list[].sandbox.docker.gpus. Значение передается флагу Docker --gpus как отдельный аргумент, например "all" или "device=GPU-uuid", и требует совместимой среды выполнения хоста, такой как NVIDIA Container Toolkit.

Бэкенд SSH

Используйте backend: "ssh", когда хотите, чтобы OpenClaw помещал 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",          // 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" },        },      },    },  },}

Бэкенд OpenShell

Используйте backend: "openshell", когда хотите, чтобы OpenClaw помещал инструменты в песочницу в удаленной среде, управляемой OpenShell. Полное руководство по настройке, справочник конфигурации и сравнение режимов workspace см. на отдельной странице OpenShell.

OpenShell повторно использует тот же основной SSH-транспорт и мост удаленной файловой системы, что и универсальный бэкенд SSH, и добавляет специфичный для OpenShell жизненный цикл (sandbox create/get/delete, sandbox ssh-config) плюс необязательный режим workspace mirror.

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

Режимы OpenShell:

• mirror (по умолчанию): локальный workspace остается каноническим. OpenClaw синхронизирует локальные файлы в OpenShell перед exec и синхронизирует удаленный workspace обратно после exec.
• remote: workspace OpenShell становится каноническим после создания песочницы. OpenClaw один раз заполняет удаленный workspace из локального workspace, затем файловые инструменты и exec выполняются напрямую с удаленной песочницей без синхронизации изменений обратно.

Режимы рабочей области

У OpenShell есть две модели рабочей области. На практике это самая важная часть.

Выберите mirror, если считаете песочницу временной средой выполнения. Выберите remote, если считаете песочницу настоящей рабочей областью.

Жизненный цикл OpenShell

Песочницы OpenShell по-прежнему управляются через обычный жизненный цикл песочницы:

• openclaw sandbox list показывает как среды выполнения OpenShell, так и среды выполнения Docker
• openclaw sandbox recreate удаляет текущую среду выполнения и позволяет OpenClaw создать ее заново при следующем использовании
• логика очистки также учитывает бэкенд

Для режима remote повторное создание особенно важно:

• повторное создание удаляет каноническую удаленную рабочую область для этой области действия
• следующее использование заполняет свежую удаленную рабочую область из локальной рабочей области

Для режима mirror повторное создание в основном сбрасывает удаленную среду выполнения, потому что локальная рабочая область все равно остается канонической.

Доступ к рабочей области

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

• Если задано (включая []), это заменяет agents.defaults.sandbox.docker.binds для контейнера браузера.
• Если не указано, контейнер браузера откатывается к agents.defaults.sandbox.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

Для развертываний Docker Gateway 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, когда цель exec — node). Директивы /exec применяются только для авторизованных отправителей и сохраняются на уровне сессии; чтобы жестко отключить exec, используйте запрет в политике инструментов (см. Песочница, политика инструментов и Elevated).

Отладка:

• Используйте openclaw sandbox explain, чтобы проверить эффективный режим песочницы, политику инструментов и ключи конфигурации для исправления.
• См. Песочница, политика инструментов и Elevated для ментальной модели «почему это заблокировано?».

Держите это строго ограниченным.

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

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

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

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

Связанные материалы

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