Безопасность и песочница

Песочница

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

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

  • Выполнение инструментов (exec, read, write, edit, apply_patch, process и т.д.).
  • Опциональный браузер в песочнице (agents.defaults.sandbox.browser).
    • По умолчанию браузер в песочнице автоматически запускается (гарантирует доступность CDP), когда это требуется инструменту браузера. Настраивается через agents.defaults.sandbox.browser.autoStart и agents.defaults.sandbox.browser.autoStartTimeoutMs.
    • По умолчанию контейнеры браузера в песочнице используют выделенную сеть Docker (openclaw-sandbox-browser) вместо глобальной сети bridge. Настраивается с помощью agents.defaults.sandbox.browser.network.
    • Опциональный agents.defaults.sandbox.browser.cdpSourceRange ограничивает входящий трафик CDP на границе контейнера с помощью allowlist CIDR (например, 172.21.0.1/32).
    • Доступ к наблюдателю noVNC по умолчанию защищён паролем; OpenClaw генерирует URL-адрес с короткоживущим токеном, который обслуживает локальную загрузочную страницу и открывает noVNC с паролем в фрагменте URL (не в логах запросов/заголовков).
    • agents.defaults.sandbox.browser.allowHostControl позволяет сессиям в песочнице явно нацеливаться на браузер хоста.
    • Опциональные allowlist'ы контролируют target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

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

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

Режимы

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

  • "off": песочница не используется.
  • "non-main": песочница только для неосновных сессий (по умолчанию, если вы хотите обычные чаты на хосте).
  • "all": каждая сессия выполняется в песочнице. Примечание: "non-main" основан на session.mainKey (по умолчанию "main"), а не на идентификаторе агента. Сессии группы/канала используют свои собственные ключи, поэтому считаются неосновными и будут помещены в песочницу.

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

agents.defaults.sandbox.scope управляет количеством создаваемых контейнеров:

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

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

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

  • "none" (по умолчанию): инструменты видят рабочую область песочницы в ~/.openclaw/sandboxes.
  • "ro": монтирует рабочую область агента только для чтения в /agent (отключает write/edit/apply_patch).
  • "rw": монтирует рабочую область агента для чтения и записи в /workspace.

Входящие медиафайлы копируются в активную рабочую область песочницы (media/inbound/*). Примечание для навыков: инструмент read привязан к корню песочницы. При workspaceAccess: "none" OpenClaw зеркалирует подходящие навыки в рабочую область песочницы (.../skills), чтобы их можно было прочитать. При "rw" навыки из рабочей области доступны для чтения из /workspace/skills.

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

agents.defaults.sandbox.docker.binds монтирует дополнительные каталоги хоста в контейнер. Формат: хост:контейнер:режим (например, "/home/user/source:/source:rw"). Глобальные и per-agent монтирования объединяются (не заменяются). При scope: "shared" per-agent монтирования игнорируются. 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"],
          },
        },
      },
    ],
  },
}

Замечания по безопасности:

  • Bind-монтирования обходят файловую систему песочницы: они открывают пути хоста с любым установленным режимом (:ro или :rw).
  • OpenClaw блокирует опасные источники для монтирования (например: docker.sock, /etc, /proc, /sys, /dev и родительские монтирования, которые могли бы их открыть).
  • Чувствительные монтирования (секреты, SSH-ключи, учётные данные служб) должны быть :ro, если это не абсолютно необходимо.
  • Комбинируйте с workspaceAccess: "ro", если вам нужен только доступ на чтение к рабочей области; режимы монтирования остаются независимыми.
  • См. Песочница vs Политика инструментов vs Elevated для понимания взаимодействия bind-монтирований с политикой инструментов и elevated exec.

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

Образ по умолчанию: openclaw-sandbox:bookworm-slim Соберите его один раз:

scripts/sandbox-setup.sh

Примечание: образ по умолчанию не включает Node. Если навыку нужен Node (или другие среды выполнения), либо создайте пользовательский образ, либо установите через sandbox.docker.setupCommand (требует исходящего сетевого доступа + записываемый корень + пользователь root). Если вам нужен более функциональный образ песочницы с общими утилитами (например, curl, jq, nodejs, python3, git), соберите:

scripts/sandbox-common-setup.sh

Затем установите agents.defaults.sandbox.docker.image в openclaw-sandbox-common:bookworm-slim. Образ браузера в песочнице:

scripts/sandbox-browser-setup.sh

По умолчанию контейнеры песочницы запускаются без сети. Переопределите с помощью agents.defaults.sandbox.docker.network. Встроенный образ браузера песочницы также применяет консервативные настройки запуска Chromium для контейнеризированных рабочих нагрузок. Текущие настройки контейнера по умолчанию включают:

  • --remote-debugging-address=127.0.0.1
  • --remote-debugging-port=<производный от OPENCLAW_BROWSER_CDP_PORT>
  • --user-data-dir=${HOME}/.chrome
  • --no-first-run
  • --no-default-browser-check
  • --disable-3d-apis
  • --disable-gpu
  • --disable-dev-shm-usage
  • --disable-background-networking
  • --disable-extensions
  • --disable-features=TranslateUI
  • --disable-breakpad
  • --disable-crash-reporter
  • --disable-software-rasterizer
  • --no-zygote
  • --metrics-recording-only
  • --renderer-process-limit=2
  • --no-sandbox и --disable-setuid-sandbox, когда включен noSandbox.
  • Три флага усиления графики (--disable-3d-apis, --disable-software-rasterizer, --disable-gpu) являются опциональными и полезны, когда контейнеры не поддерживают 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 для добавления дополнительных флагов запуска. Настройки безопасности по умолчанию:

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

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

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

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

  • Глобальный: agents.defaults.sandbox.docker.setupCommand
  • Per-agent: agents.list[].sandbox.docker.setupCommand

Распространённые проблемы:

  • По умолчанию 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-ключей навыков.

Политика инструментов + аварийные выходы

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

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

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

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

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

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

Связанная документация

БезопасностьПесочница vs Политика инструментов vs Elevated