OpenShell

OpenShell — це керований бекенд пісочниці для OpenClaw. Замість локального запуску Docker контейнерів OpenClaw делегує життєвий цикл пісочниці CLI openshell, який надає віддалені середовища з виконанням команд через SSH.

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

Передумови

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

Швидкий старт

1. Установіть і ввімкніть Plugin, а потім задайте бекенд пісочниці:

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

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

3. Перевірте:

openclaw sandbox listopenclaw sandbox explain

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

Це найважливіше рішення під час використання OpenShell.

mirror

Використовуйте plugins.entries.openshell.config.mode: "mirror", коли хочете, щоб локальний робочий простір залишався канонічним.

Поведінка:

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

Найкраще підходить для:

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

Компроміс: додаткова вартість синхронізації до та після кожного exec.

remote

Використовуйте plugins.entries.openshell.config.mode: "remote", коли хочете, щоб робочий простір OpenShell став канонічним.

Поведінка:

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

Найкраще підходить для:

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

Вибір режиму

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

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

Налаштування рівня пісочниці (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",        },      },    },  },}

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

Пісочниці OpenShell керуються через звичайний CLI пісочниці:

# List all sandbox runtimes (Docker + OpenShell)openclaw sandbox list # Inspect effective policyopenclaw sandbox explain # Recreate (deletes remote workspace, re-seeds on next use)openclaw sandbox recreate --all

Для режиму remote recreate особливо важливий: він видаляє канонічний віддалений робочий простір для цієї області. Наступне використання ініціалізує новий віддалений робочий простір із локального робочого простору.

Для режиму mirror recreate переважно скидає віддалене середовище виконання, бо локальний робочий простір залишається канонічним.

Коли виконувати recreate

Виконуйте recreate після зміни будь-чого з цього:

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

openclaw sandbox recreate --all

Посилення безпеки

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

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

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

Як це працює

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

Пов’язане

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