​

Пісочниця

​

Що ізолюється в пісочниці

• Виконання інструментів (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 на межі контейнера через список дозволених CIDR (наприклад 172.21.0.1/32).
  • Доступ спостерігача noVNC типово захищено паролем; OpenClaw генерує короткоживучий URL із токеном, який віддає локальну bootstrap-сторінку та відкриває noVNC із паролем у фрагменті URL (а не в журналах query/header).
  • agents.defaults.sandbox.browser.allowHostControl дозволяє пісочницьним сесіям явно націлюватися на браузер хоста.
  • Необов’язкові списки дозволених обмежують target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

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

​

Режими

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

​

Область

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

​

Бекенд

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

​

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

​

Бекенд 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",
          // Або використовуйте SecretRef / вбудований вміст замість локальних файлів:
          // 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" },
        },
      },
    },
  },
}

• OpenClaw створює віддалений корінь для кожної області в sandbox.ssh.workspaceRoot.
• Під час першого використання після створення або повторного створення OpenClaw один раз ініціалізує цей віддалений робочий простір із локального.
• Після цього exec, read, write, edit, apply_patch, читання медіа під час prompt і staging вхідних медіа працюють безпосередньо з віддаленим робочим простором через SSH.
• OpenClaw не синхронізує віддалені зміни назад у локальний робочий простір автоматично.

• identityFile, certificateFile, knownHostsFile: використовують наявні локальні файли й передають їх через конфігурацію OpenSSH.
• identityData, certificateData, knownHostsData: використовують вбудовані рядки або SecretRef. OpenClaw розв’язує їх через звичайний runtime snapshot секретів, записує їх у тимчасові файли з правами 0600 і видаляє, коли SSH-сесія завершується.
• Якщо для одного елемента задано і *File, і *Data, для цієї SSH-сесії переважає *Data.

• Локальні зміни на хості, зроблені поза OpenClaw після кроку seed, не будуть видимі віддалено, доки ви не відтворите пісочницю.
• openclaw sandbox recreate видаляє віддалений корінь для кожної області й повторно ініціалізує його з локального під час наступного використання.
• Браузер у пісочниці не підтримується в бекенді SSH.
• Налаштування sandbox.docker.* не застосовуються до бекенда SSH.

​

Бекенд OpenShell

{
  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",
        },
      },
    },
  },
}

• mirror (типово): локальний робочий простір залишається канонічним. OpenClaw синхронізує локальні файли в OpenShell перед exec і синхронізує віддалений робочий простір назад після exec.
• remote: після створення пісочниці робочий простір OpenShell стає канонічним. OpenClaw один раз ініціалізує віддалений робочий простір із локального, а потім файлові інструменти й exec працюють безпосередньо з віддаленою пісочницею без синхронізації змін назад.

• OpenClaw запитує в OpenShell специфічну для пісочниці конфігурацію SSH через openshell sandbox ssh-config <name>.
• Core записує цю конфігурацію SSH у тимчасовий файл, відкриває SSH-сесію й повторно використовує той самий міст віддаленої файлової системи, що й backend: "ssh".
• У режимі mirror відрізняється лише життєвий цикл: синхронізація локального у віддалений простір перед exec, а потім назад після exec.

• браузер у пісочниці поки що не підтримується
• sandbox.docker.binds не підтримується в бекенді OpenShell
• специфічні для Docker параметри runtime у sandbox.docker.* і далі застосовуються лише до бекенда Docker

​

Режими робочого простору

mirror

• Перед exec OpenClaw синхронізує локальний робочий простір у пісочницю OpenShell.
• Після exec OpenClaw синхронізує віддалений робочий простір назад у локальний.
• Файлові інструменти все одно працюють через міст пісочниці, але між ходами джерелом істини лишається локальний робочий простір.

• ви редагуєте файли локально поза OpenClaw і хочете, щоб ці зміни автоматично з’являлися в пісочниці
• ви хочете, щоб пісочниця OpenShell поводилася якомога більше як бекенд Docker
• ви хочете, щоб робочий простір хоста відображав записи з пісочниці після кожного ходу exec

• додаткова вартість синхронізації до й після exec

remote

• Коли пісочницю вперше створено, OpenClaw один раз ініціалізує віддалений робочий простір із локального.
• Після цього exec, read, write, edit і apply_patch працюють безпосередньо з віддаленим робочим простором OpenShell.
• OpenClaw не синхронізує віддалені зміни назад у локальний робочий простір після exec.
• Читання медіа під час prompt і далі працюють, тому що файлові та медіаінструменти читають через міст пісочниці, а не припускають локальний шлях хоста.
• Транспорт — це SSH до пісочниці OpenShell, повернутої openshell sandbox ssh-config.

• Якщо ви редагуєте файли на хості поза OpenClaw після кроку seed, віддалена пісочниця не побачить ці зміни автоматично.
• Якщо пісочницю відтворити, віддалений робочий простір знову ініціалізується з локального.
• При scope: "agent" або scope: "shared" цей віддалений робочий простір спільний у межах тієї самої області.

• пісочниця має переважно жити на віддаленому боці OpenShell
• ви хочете зменшити накладні витрати на синхронізацію в кожному ході
• ви не хочете, щоб локальні редагування на хості непомітно перезаписували стан віддаленої пісочниці

​

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

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

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

​

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

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

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

​

Користувацькі bind mount

• Якщо задано (включно з []), він замінює 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 блокує небезпечні джерела bind (наприклад: docker.sock, /etc, /proc, /sys, /dev і батьківські mount, які відкрили б до них доступ).
• OpenClaw також блокує типові корені домашніх каталогів з обліковими даними, як-от ~/.aws, ~/.cargo, ~/.config, ~/.docker, ~/.gnupg, ~/.netrc, ~/.npm і ~/.ssh.
• Перевірка bind — це не просто зіставлення рядків. OpenClaw нормалізує шлях джерела, потім знову розв’язує його через найглибшого наявного предка перед повторною перевіркою заблокованих шляхів і дозволених коренів.
• Це означає, що вихід через батьківські symlink усе одно безпечно блокується, навіть коли фінальний лист ще не існує. Приклад: /workspace/run-link/new-file усе одно розв’язується як /var/run/..., якщо run-link вказує туди.
• Дозволені корені джерел канонізуються так само, тому шлях, який лише виглядає таким, що входить до allowlist до розв’язання symlink, усе одно буде відхилений як outside allowed roots.
• Чутливі mount (секрети, SSH-ключі, сервісні облікові дані) мають бути :ro, якщо це не абсолютно необхідно.
• Поєднуйте з workspaceAccess: "ro", якщо вам потрібен лише доступ для читання до робочого простору; режими bind залишаються незалежними.
• Див. Sandbox vs Tool Policy vs Elevated щодо того, як bind взаємодіють із політикою інструментів і elevated exec.

​

Образи та налаштування

scripts/sandbox-setup.sh

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

• --remote-debugging-address=127.0.0.1
• --remote-debugging-port=<derived from 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.

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

​

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

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

• Типове docker.network має значення "none" (без egress), тож установлення пакетів завершиться помилкою.
• docker.network: "container:<id>" вимагає dangerouslyAllowContainerNamespaceJoin: true і призначене лише для аварійного використання.
• readOnlyRoot: true забороняє запис; установіть readOnlyRoot: false або створіть власний образ.
• Для встановлення пакетів user має бути root (пропустіть user або задайте user: "0:0").
• Sandbox exec не успадковує process.env хоста. Використовуйте agents.defaults.sandbox.docker.env (або власний образ) для API keys skill.

​

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

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

​

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

​

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

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

​

Пов’язана документація

• OpenShell — налаштування керованого бекенда пісочниці, режими робочого простору та довідник конфігурації
• Конфігурація пісочниці
• Sandbox vs Tool Policy vs Elevated — налагодження “чому це заблоковано?”
• Multi-Agent Sandbox & Tools — перевизначення для окремих агентів і пріоритети
• Security