Ізоляція

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

Що ізолюється

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

Не ізолюються:

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

Режим, область дії та бекенд

Поведінкою ізольованого середовища керують три незалежні параметри:

Режим визначає, коли застосовується ізоляція:

• off: без ізоляції.
• non-main: ізолювати кожен сеанс, крім основного сеансу агента. Ключ основного сеансу завжди має вигляд agent:<agentId>:main (або global, коли session.scope має значення "global"); його не можна налаштувати. Групові сеанси та сеанси каналів використовують власні ключі, тому завжди вважаються неосновними та ізолюються.
• all: кожен сеанс працює в ізольованому середовищі.

Область дії визначає кількість створюваних контейнерів або середовищ:

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

Бекенд визначає середовище виконання ізольованих інструментів. Конфігурація для SSH міститься в agents.defaults.sandbox.ssh, а конфігурація для OpenShell — у plugins.entries.openshell.config.

Бекенд Docker

Docker є типовим бекендом після ввімкнення ізоляції. Він локально запускає інструменти та ізольовані браузери через сокет демона Docker (/var/run/docker.sock); ізоляцію забезпечують простори імен Docker.

Типові значення: network: "none" (без вихідного доступу), readOnlyRoot: true, capDrop: ["ALL"], образ openclaw-sandbox:bookworm-slim.

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

Ізольований браузер

• Ізольований браузер запускається автоматично (що забезпечує доступність CDP), коли він потрібен інструменту браузера. Налаштовуйте це через agents.defaults.sandbox.browser.autoStart (типово true) і autoStartTimeoutMs (типово 12 с).
• Контейнери ізольованого браузера використовують окрему мережу 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 із короткочасним токеном, який віддає локальну початкову сторінку та відкриває noVNC із паролем у фрагменті URL (не в рядку запиту чи журналах заголовків).
• agents.defaults.sandbox.browser.allowHostControl (типово false) дає ізольованим сеансам змогу явно вибирати браузер хоста як ціль.
• Необов’язкові списки дозволених значень обмежують target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

Бекенд SSH

Використовуйте backend: "ssh", щоб ізолювати 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" },        },      },    },  },}

Типові значення: command: "ssh", workspaceRoot: "/tmp/openclaw-sandboxes", strictHostKeyChecking: true, updateHostKeys: true.

• Життєвий цикл: OpenClaw створює віддалений кореневий каталог для кожної області дії в sandbox.ssh.workspaceRoot. Під час першого використання після створення або повторного створення він один раз початково заповнює цей віддалений робочий простір із локального. Після цього exec, read, write, edit, apply_patch, читання медіафайлів із запиту та підготовка вхідних медіафайлів виконуються безпосередньо з віддаленим робочим простором через SSH. OpenClaw не синхронізує віддалені зміни назад до локального робочого простору автоматично.
• Матеріали автентифікації: identityFile/certificateFile/knownHostsFile посилаються на наявні локальні файли. identityData/certificateData/knownHostsData приймають вбудовані рядки або SecretRefs, які визначаються через звичайний знімок середовища виконання секретів, записуються до тимчасових файлів із режимом 0600 і видаляються після завершення сеансу SSH. Якщо для того самого елемента задано і варіант *File, і варіант *Data, у цьому сеансі перевагу має *Data.
• Наслідки віддаленого канонічного простору: після початкового заповнення віддалений робочий простір SSH стає фактичним станом ізольованого середовища. Локальні зміни на хості, внесені поза OpenClaw після етапу початкового заповнення, не відображаються віддалено, доки ви не створите ізольоване середовище повторно. openclaw sandbox recreate видаляє віддалений кореневий каталог відповідної області дії, а під час наступного використання знову початково заповнює його з локального простору. Цей бекенд не підтримує ізоляцію браузера, а параметри sandbox.docker.* до нього не застосовуються.

Бекенд OpenShell

Використовуйте backend: "openshell", щоб ізолювати інструменти у віддаленому середовищі під керуванням OpenShell. OpenShell повторно використовує той самий транспорт SSH і міст віддаленої файлової системи, що й універсальний бекенд SSH, а також додає керування життєвим циклом OpenShell (sandbox create/get/delete/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        },      },    },  },}

mode: "mirror" (типово) зберігає локальний робочий простір канонічним: OpenClaw синхронізує локальні дані до ізольованого середовища перед exec і синхронізує їх назад після виконання. mode: "remote" один раз початково заповнює віддалений робочий простір із локального, а потім виконує exec/read/write/edit/apply_patch безпосередньо з віддаленим робочим простором без зворотної синхронізації; локальні зміни після початкового заповнення не відображаються, доки ви не виконаєте openclaw sandbox recreate. За scope: "agent" або scope: "shared" цей віддалений робочий простір є спільним у межах відповідної області дії. Поточні обмеження: ізольований браузер поки не підтримується, а sandbox.docker.binds не застосовується до цього бекенду.

openclaw sandbox list/recreate/prune обробляють середовища виконання OpenShell так само, як середовища виконання Docker; логіка очищення враховує бекенд.

Повний перелік передумов, довідник із конфігурації, порівняння режимів робочого простору та подробиці життєвого циклу див. у розділі OpenShell.

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

agents.defaults.sandbox.workspaceAccess визначає, що може бачити ізольоване середовище:

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

Вхідні медіафайли копіюються до активного робочого простору пісочниці (media/inbound/*).

Власні прив’язувальні монтування

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

Глобальні прив’язки та прив’язки окремих агентів об’єднуються (а не замінюються). За scope: "shared" прив’язки окремих агентів ігноруються.

agents.defaults.sandbox.browser.binds монтує додаткові каталоги хоста лише до контейнера браузера пісочниці. Якщо значення задано (зокрема []), воно замінює docker.binds для контейнера браузера; якщо його пропущено, контейнер браузера використовує 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

Для розгортань Gateway у Docker сценарій 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, забороніть його в політиці інструментів (див. Пісочниця, політика інструментів і привілейоване виконання).

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

• openclaw sandbox list показує контейнери пісочниці, стан, відповідність образу, вік, час бездіяльності та пов’язаний сеанс або агент.
• openclaw sandbox explain [--session <key>] [--agent <id>] перевіряє фактичний режим пісочниці, робочий простір хоста, робочий каталог середовища виконання, монтування Docker, політику інструментів і ключі конфігурації для виправлення. Поле workspaceRoot залишається налаштованим коренем пісочниці; effectiveHostWorkspaceRoot показує, де фактично розташований активний робочий простір.
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] видаляє контейнери або середовища, щоб під час наступного використання вони були створені заново з поточною конфігурацією.
• Модель мислення для запитання «чому це заблоковано?» див. у розділі Пісочниця, політика інструментів і привілейоване виконання.

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

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

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

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

Пов’язане

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