Изоляция (Sandboxing)

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.
    • agents.defaults.sandbox.browser.allowHostControl позволяет изолированным сессиям явно ориентироваться на браузер хоста.
    • Опциональные белые списки управляют target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

Не изолируется:

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

Режимы

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

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

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

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

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

Пример (исходник только для чтения + docker socket):

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          binds: [
            "/home/user/source:/source:ro",
            "/var/run/docker.sock:/var/run/docker.sock"
          ]
        }
      }
    },
    list: [
      {
        id: "build",
        sandbox: {
          docker: {
            binds: ["/mnt/cache:/cache:rw"]
          }
        }
      }
    ]
  }
}

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

  • Привязки обходят файловую систему песочницы: они открывают пути хоста с тем режимом, который вы установили (:ro или :rw).
  • Чувствительные монтирования (например, docker.sock, секреты, SSH ключи) должны быть :ro, если это абсолютно не требуется.
  • Комбинируйте с workspaceAccess: "ro", если вам нужен только доступ для чтения к рабочей области; режимы привязок остаются независимыми.
  • Смотрите Sandbox vs Tool Policy vs Elevated для того, как привязки взаимодействуют с политикой инструментов и exec с повышенными правами.

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

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

Соберите его один раз:

scripts/sandbox-setup.sh

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

Образ изолированного браузера:

scripts/sandbox-browser-setup.sh

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

Установки Docker и контейнеризированный шлюз находятся здесь: Docker

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

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

Пути:

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

Общие ловушки:

  • docker.network по умолчанию "none" (без выхода), поэтому установка пакетов не сработает.
  • readOnlyRoot: true предотвращает запись; установите readOnlyRoot: false или создайте пользовательский образ.
  • user должен быть root для установки пакетов (опустите user или установите user: "0:0").
  • Exec в песочнице не наследует process.env хоста. Используйте agents.defaults.sandbox.docker.env (или пользовательский образ) для API ключей навыков.

Политика инструментов + эскейп-хэтчи

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

tools.elevated — это явный эскейп-хэтч, который запускает exec на хосте. Директивы /exec применяются только для авторизованных отправителей и сохраняются для сессии; для жёсткого отключения exec используйте запрет политики инструментов (смотрите Sandbox vs Tool Policy vs Elevated).

Отладка:

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

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

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

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

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

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

← Назад к документации