Пісочниця

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).
  • Підвищений exec обходить sandboxing і використовує налаштований шлях виходу (gateway за замовчуванням або node, коли ціль exec — node).
  • Якщо sandboxing вимкнено, tools.elevated не змінює виконання (воно вже на хості). Див. Підвищений режим.

Режими

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 змогу створити його заново під час наступного використання
• логіка prune також враховує бекенд

Для режиму 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").

Глобальні й агентні binds об'єднуються (не замінюються). За scope: "shared" агентні binds ігноруються.

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