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 listopenclaw 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: менші накладні витрати на кожен хід, а локальні зміни на хості не можуть непомітно перезаписати віддалений стан.

Вибір режиму

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

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

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.

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

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

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

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