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

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

# Що потрапляє до пісочниці

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

Не потрапляє до пісочниці:

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

# Режими

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

# Область

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

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

# Бекенд

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

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

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

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

# Бекенд Docker

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

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

# Бекенд SSH

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

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

OpenShell має дві моделі робочої області. Це найважливіша на практиці частина.

Виберіть mirror, якщо сприймаєте sandbox як тимчасове середовище виконання. Виберіть remote, якщо сприймаєте sandbox як справжній робочий простір.

# Життєвий цикл OpenShell

Sandbox OpenShell усе ще керуються через звичайний життєвий цикл sandbox:

• openclaw sandbox list показує runtime OpenShell, а також runtime Docker
• openclaw sandbox recreate видаляє поточний runtime і дає OpenClaw створити його заново під час наступного використання
• логіка prune також враховує бекенд

Для режиму remote повторне створення особливо важливе:

• recreate видаляє канонічний віддалений робочий простір для цієї області
• наступне використання заповнює свіжий віддалений робочий простір із локального робочого простору

Для режиму mirror повторне створення переважно скидає віддалене середовище виконання, бо локальний робочий простір однаково лишається канонічним.

# Доступ до робочого простору

agents.defaults.sandbox.workspaceAccess керує тим, що sandbox може бачити:

З бекендом OpenShell:

• режим mirror усе ще використовує локальний робочий простір як канонічне джерело між exec-кроками
• режим remote використовує віддалений робочий простір OpenShell як канонічне джерело після початкового заповнення
• workspaceAccess: "ro" і "none" усе ще обмежують поведінку запису так само

Вхідні медіа копіюються в активний робочий простір sandbox (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 монтує додаткові каталоги хоста лише в контейнер браузера sandbox.

• Коли задано (включно з []), це замінює 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-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

За замовчуванням контейнери Docker sandbox працюють без мережі. Перевизначте це через agents.defaults.sandbox.docker.network.

Встановлення Docker і контейнеризований Gateway описані тут: Docker

Для розгортань Docker gateway scripts/docker/setup.sh може початково налаштувати конфігурацію sandbox. Задайте OPENCLAW_SANDBOX=1 (або true/yes/on), щоб увімкнути цей шлях. Ви можете перевизначити розташування socket через OPENCLAW_DOCKER_SOCKET. Повне налаштування й довідка щодо env: Docker.

# setupCommand (одноразове налаштування контейнера)

setupCommand виконується один раз після створення контейнера sandbox (не під час кожного запуску). Він виконується всередині контейнера через sh -lc.

Шляхи:

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

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

Політики дозволу/заборони інструментів усе ще застосовуються перед правилами пісочниці. Якщо інструмент заборонено глобально або для окремого агента, пісочниця не повертає його.

tools.elevated — це явний аварійний обхід, який запускає exec поза пісочницею (gateway за замовчуванням або node, коли ціль exec — node). Директиви /exec застосовуються лише для авторизованих відправників і зберігаються в межах сеансу; щоб жорстко вимкнути exec, використовуйте заборону в політиці інструментів (див. Пісочниця vs Політика інструментів vs Підвищені права).

Налагодження:

• Використовуйте openclaw sandbox explain, щоб перевірити ефективний режим пісочниці, політику інструментів і ключі конфігурації для виправлення.
• Див. Пісочниця vs Політика інструментів vs Підвищені права для ментальної моделі "чому це заблоковано?".

Тримайте це максимально обмеженим.

# Перевизначення для кількох агентів

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

# Мінімальний приклад увімкнення

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

# Пов’язане

• Пісочниця та інструменти для кількох агентів — перевизначення для окремих агентів і пріоритет
• OpenShell — налаштування керованого бекенду пісочниці, режими робочого простору та довідник конфігурації
• Конфігурація пісочниці
• Пісочниця vs Політика інструментів vs Підвищені права — налагодження "чому це заблоковано?"
• Безпека