OpenShell

OpenShell — це керований бекенд ізольованого середовища: замість локального запуску контейнерів Docker OpenClaw делегує життєвий цикл ізольованого середовища CLI openshell, який створює віддалені середовища та виконує команди через SSH. Plugin повторно використовує той самий транспорт SSH і міст віддаленої файлової системи, що й універсальний бекенд SSH, а також додає керування життєвим циклом OpenShell (sandbox create/get/delete/ssh-config) і необов’язковий режим синхронізації робочого простору mirror.

Передумови

Установлений Plugin OpenShell (openclaw plugins install @openclaw/openshell-sandbox)
CLI openshell у PATH (або власний шлях через plugins.entries.openshell.config.command)
Обліковий запис OpenShell із доступом до ізольованих середовищ
Запущений на хості OpenClaw Gateway

Швидкий початок

openclaw plugins install @openclaw/openshell-sandbox

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

Перезапустіть Gateway. Під час наступного ходу агента OpenClaw створить ізольоване середовище OpenShell і спрямує виконання інструментів через нього. Перевірте це за допомогою:

openclaw sandbox list
openclaw sandbox explain

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

Це найважливіше рішення щодо OpenShell.

mirror (типово)

plugins.entries.openshell.config.mode: "mirror" залишає локальний робочий простір канонічним:

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

Найкраще підходить для робочих процесів розробки: локальні зміни поза OpenClaw з’являються під час наступного виконання, а ізольоване середовище поводиться подібно до бекенда Docker. Компроміс: витрати на завантаження в обох напрямках під час кожного ходу виконання.

remote

mode: "remote" робить робочий простір OpenShell канонічним:

Під час першого створення ізольованого середовища OpenClaw одноразово ініціалізує віддалений робочий простір із локального.
Після цього exec, read, write, edit і apply_patch працюють безпосередньо з віддаленим робочим простором. OpenClaw не синхронізує віддалені зміни назад із локальним середовищем.
Зчитування медіафайлів під час формування запиту й надалі працює (інструменти для файлів і медіафайлів читають через міст ізольованого середовища).

Найкраще підходить для довготривалих агентів і CI: менші накладні витрати на кожен хід, а локальні зміни на хості не можуть непомітно перезаписати віддалений стан.

Редагування файлів на хості поза OpenClaw після початкової ініціалізації не відображається у віддаленому ізольованому середовищі. Виконайте openclaw sandbox recreate, щоб повторно ініціалізувати його.

Вибір режиму

	`mirror`	`remote`
Канонічний робочий простір	Локальний хост	Віддалений OpenShell
Напрямок синхронізації	Двобічний (під час кожного `exec`)	Одноразова ініціалізація
Накладні витрати на хід	Вищі (завантаження в обидва боки)	Нижчі (прямі віддалені операції)
Локальні зміни видимі?	Так, під час наступного `exec`	Ні, до повторного створення
Найкраще підходить для	Робочих процесів розробки	Довготривалих агентів, CI

Довідник із конфігурації

Уся конфігурація OpenShell міститься в plugins.entries.openshell.config:

Ключ	Тип	Типове значення	Опис
`mode`	`"mirror"` або `"remote"`	`"mirror"`	Режим синхронізації робочого простору
`command`	`string`	`"openshell"`	Шлях до CLI `openshell` або його назва
`from`	`string`	`"openclaw"`	Джерело ізольованого середовища під час першого створення
`gateway`	`string`	не задано	Назва Gateway OpenShell (верхньорівневий параметр `--gateway`)
`gatewayEndpoint`	`string`	не задано	Кінцева точка Gateway OpenShell (верхньорівневий параметр `--gateway-endpoint`)
`policy`	`string`	не задано	Ідентифікатор політики OpenShell для створення ізольованого середовища
`providers`	`string[]`	`[]`	Назви постачальників, що додаються під час створення ізольованого середовища (без дублікатів, по одному прапорцю `--provider` для кожного запису)
`gpu`	`boolean`	`false`	Запит ресурсів GPU (`--gpu`)
`autoProviders`	`boolean`	`true`	Передавати `--auto-providers` (або `--no-auto-providers`, якщо `false`) під час створення
`remoteWorkspaceDir`	`string`	`"/sandbox"`	Основний доступний для запису робочий простір усередині ізольованого середовища
`remoteAgentWorkspaceDir`	`string`	`"/agent"`	Шлях монтування робочого простору агента (лише для читання, якщо доступ до робочого простору не `rw`)
`timeoutSeconds`	`number`	`120`	Час очікування для операцій CLI `openshell`

remoteWorkspaceDir і remoteAgentWorkspaceDir мають бути абсолютними шляхами та залишатися в межах керованих коренів /sandbox або /agent; інші абсолютні шляхи відхиляються. Налаштування рівня ізольованого середовища (mode, scope, workspaceAccess) містяться в agents.defaults.sandbox, як і для будь-якого бекенда. Повну матрицю наведено в розділі Ізоляція.

Приклади

Мінімальне віддалене налаштування

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
        },
      },
    },
  },
}

Режим mirror із GPU

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "agent",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "mirror",
          gpu: true,
          providers: ["openai"],
          timeoutSeconds: 180,
        },
      },
    },
  },
}

Окремий OpenShell для кожного агента з власним Gateway

{
  agents: {
    defaults: {
      sandbox: { mode: "off" },
    },
    list: [
      {
        id: "researcher",
        sandbox: {
          mode: "all",
          backend: "openshell",
          scope: "agent",
          workspaceAccess: "rw",
        },
      },
    ],
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
          gateway: "lab",
          gatewayEndpoint: "https://lab.example",
          policy: "strict",
        },
      },
    },
  },
}

Керування життєвим циклом

# Перелічити всі середовища виконання ізольованих середовищ (Docker + OpenShell)
openclaw sandbox list

# Переглянути чинну політику
openclaw sandbox explain

# Повторно створити (видаляє віддалений робочий простір, повторно ініціалізує під час наступного використання)
openclaw sandbox recreate --all

Для режиму remote повторне створення особливо важливе: воно видаляє канонічний віддалений робочий простір для відповідної області, а під час наступного використання створюється новий на основі локального. У режимі mirror повторне створення переважно скидає віддалене середовище виконання, оскільки локальний робочий простір залишається канонічним. Повторно створіть ізольоване середовище після зміни будь-якого з таких параметрів:

agents.defaults.sandbox.backend
plugins.entries.openshell.config.from
plugins.entries.openshell.config.mode
plugins.entries.openshell.config.policy

Посилення захисту

Міст файлової системи в режимі mirror фіксує корінь локального робочого простору та повторно перевіряє канонічні шляхи (через realpath) перед кожним читанням, записом, створенням каталогу, видаленням і перейменуванням, відхиляючи символічні посилання всередині шляху. Підміна символічного посилання або повторне монтування робочого простору не може перенаправити доступ до файлів за межі дзеркального дерева.

Поточні обмеження

Браузер ізольованого середовища не підтримується в бекенді OpenShell.
sandbox.docker.binds не застосовується до OpenShell; якщо налаштовано прив’язки, створення ізольованого середовища завершується помилкою.
Специфічні для Docker параметри середовища виконання в sandbox.docker.* (крім env) застосовуються лише до бекенда Docker.

Принцип роботи

OpenClaw виконує sandbox get для назви ізольованого середовища (з усіма налаштованими параметрами --gateway/--gateway-endpoint); якщо команда завершується помилкою, OpenClaw створює середовище за допомогою sandbox create, передаючи --name, --from, --policy, якщо його задано, --gpu, якщо ввімкнено, --auto-providers/--no-auto-providers і по одному прапорцю --provider для кожного налаштованого постачальника.
OpenClaw виконує sandbox ssh-config для назви ізольованого середовища, щоб отримати параметри підключення SSH.
Ядро записує конфігурацію SSH у тимчасовий файл і відкриває сеанс SSH через той самий міст віддаленої файлової системи, що й універсальний бекенд SSH.
У режимі mirror: синхронізує локальний робочий простір із віддаленим перед виконанням, виконує команду, потім синхронізує зміни назад.
У режимі remote: одноразово ініціалізує робочий простір під час створення, а потім працює безпосередньо з віддаленим робочим простором.

Пов’язані матеріали

Ізоляція — режими, області та порівняння бекендів
Ізольоване середовище, політика інструментів і підвищені привілеї — діагностика заблокованих інструментів
Ізольоване середовище й інструменти для кількох агентів — перевизначення для окремих агентів
CLI ізольованого середовища — команди openclaw sandbox

Gateway

Remote access

Security

Nodes and media

Web interfaces

Передумови

Швидкий початок

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

mirror (типово)

remote

Вибір режиму

Довідник із конфігурації

Приклади

Мінімальне віддалене налаштування

Режим mirror із GPU

Окремий OpenShell для кожного агента з власним Gateway

Керування життєвим циклом

Посилення захисту

Поточні обмеження

Принцип роботи

Пов’язані матеріали

​Передумови

​Швидкий початок

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

​mirror (типово)

​remote

​Вибір режиму

​Довідник із конфігурації

​Приклади

​Мінімальне віддалене налаштування

​Режим mirror із GPU

​Окремий OpenShell для кожного агента з власним Gateway

​Керування життєвим циклом

​Посилення захисту

​Поточні обмеження

​Принцип роботи

​Пов’язані матеріали

Передумови

Швидкий початок

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

mirror (типово)

remote

Вибір режиму

Довідник із конфігурації

Приклади

Мінімальне віддалене налаштування

Режим mirror із GPU

Окремий OpenShell для кожного агента з власним Gateway

Керування життєвим циклом

Посилення захисту

Поточні обмеження

Принцип роботи

Пов’язані матеріали