Ізоляція

​

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

• Виконання інструментів: 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 для окремих агентів у цій області дії ігноруються).

​

Бекенд Docker

​

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

• Ізольований браузер запускається автоматично (що забезпечує доступність 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

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

• Життєвий цикл: 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

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote", // mirror | remote
        },
      },
    },
  },
}

​

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

​

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

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

​

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

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

​

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

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

​

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

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

​

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

​

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

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

​

Пов’язане

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