OpenShell

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

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

Передумови

• CLI openshell установлено й доступний у PATH (або задайте власний шлях через plugins.entries.openshell.config.command)
• Обліковий запис OpenShell із доступом до пісочниць
• OpenClaw Gateway, що працює на хості

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

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

{  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, як і для будь-якого бекенда. Повну матрицю див. у Sandboxing.

Приклади

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

{  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 фіксує кореневий файловий дескриптор робочого простору й повторно перевіряє identity пісочниці перед кожним читанням, тому підміна 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. Ядро записує конфігурацію SSH у тимчасовий файл і відкриває SSH-сеанс, використовуючи той самий міст віддаленої файлової системи, що й загальний SSH backend.
4. У режимі mirror: синхронізує локальний робочий простір із віддаленим перед exec, виконує команду, синхронізує назад після exec.
5. У режимі remote: ініціалізує один раз під час створення, а потім працює безпосередньо з віддаленим робочим простором.

Пов’язане

• Sandboxing -- режими, області дії та порівняння бекендів
• Sandbox vs Tool Policy vs Elevated -- налагодження заблокованих інструментів
• Multi-Agent Sandbox and Tools -- перевизначення для окремих агентів
• Sandbox CLI -- команди openclaw sandbox