Ізоляція в пісочниці

OpenClaw може запускати інструменти всередині sandbox-бекендів, щоб зменшити радіус ураження. Це необов’язково й керується конфігурацією (agents.defaults.sandbox або agents.list[].sandbox). Якщо sandboxing вимкнено, інструменти виконуються на хості. Gateway залишається на хості; виконання інструментів відбувається в ізольованому sandbox, коли це ввімкнено.

Що потрапляє в sandbox

• Виконання інструментів (exec, read, write, edit, apply_patch, process тощо).
• Необов’язковий sandbox-браузер (agents.defaults.sandbox.browser).

Не потрапляє в sandbox:

• Сам процес Gateway.
• Будь-який інструмент, якому явно дозволено виконуватися поза sandbox (наприклад, tools.elevated).
  • Elevated exec обходить sandboxing і використовує налаштований escape-шлях (gateway за замовчуванням або node, коли ціль exec — node).
  • Якщо sandboxing вимкнено, tools.elevated не змінює виконання (воно вже на хості). Див. Elevated Mode.

Режими

agents.defaults.sandbox.mode керує тим, коли використовується sandboxing:

Область

agents.defaults.sandbox.scope керує тим, скільки контейнерів створюється:

• "agent" (за замовчуванням): один контейнер на агента.
• "session": один контейнер на сеанс.
• "shared": один контейнер, спільний для всіх sandbox-сеансів.

Бекенд

agents.defaults.sandbox.backend керує тим, яке середовище виконання надає sandbox:

• "docker" (за замовчуванням, коли sandboxing увімкнено): локальне sandbox-середовище виконання на базі Docker.
• "ssh": універсальне віддалене sandbox-середовище виконання на базі SSH.
• "openshell": sandbox-середовище виконання на базі OpenShell.

SSH-специфічна конфігурація розташована в agents.defaults.sandbox.ssh. OpenShell-специфічна конфігурація розташована в plugins.entries.openshell.config.

Вибір бекенда

Бекенд Docker

Sandboxing вимкнено за замовчуванням. Якщо ви вмикаєте sandboxing і не вибираєте бекенд, OpenClaw використовує бекенд Docker. Він виконує інструменти й sandbox-браузери локально через сокет демона Docker (/var/run/docker.sock). Ізоляція sandbox-контейнера визначається просторами імен Docker.

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

Бекенд SSH

Використовуйте backend: "ssh", коли хочете, щоб OpenClaw запускав exec, файлові інструменти й читання медіа в sandbox на довільній машині з доступом 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 запускав інструменти в sandbox у віддаленому середовищі, керованому OpenShell. Повний посібник із налаштування, довідку з конфігурації та порівняння режимів робочої області див. на окремій сторінці OpenShell.

OpenShell повторно використовує той самий основний SSH-транспорт і віддалений міст файлової системи, що й універсальний бекенд SSH, і додає специфічний для OpenShell життєвий цикл (sandbox create/get/delete, sandbox ssh-config) плюс необов’язковий режим робочої області 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 (за замовчуванням): локальна робоча область залишається канонічною. OpenClaw синхронізує локальні файли в OpenShell перед exec і синхронізує віддалену робочу область назад після exec.
• remote: робоча область OpenShell є канонічною після створення sandbox. OpenClaw один раз заповнює віддалену робочу область із локальної робочої області, після чого файлові інструменти й exec виконуються безпосередньо щодо віддаленого sandbox без синхронізації змін назад.

Режими робочої області

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, коли ціль виконання — 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 — налагодження «чому це заблоковано?»
• Безпека