Песочница

​

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

• Выполнение инструментов: 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 для отдельных агентов в этой области действия игнорируются).

​

Бэкенд Docker

​

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

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

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

• Жизненный цикл: 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

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote", // зеркало | удалённый режим
        },
      },
    },
  },
}

​

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

​

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

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

​

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

scripts/sandbox-setup.sh

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

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

​

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

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

​

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

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

​

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

​

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

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

​

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

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