OpenShell

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

Плагин повторно использует тот же транспорт SSH и мост удалённой файловой системы, что и универсальный бэкенд SSH, а также добавляет управление жизненным циклом OpenShell (sandbox create/get/delete/ssh-config) и необязательный режим синхронизации рабочего пространства mirror.

Предварительные требования

• Установленный плагин OpenShell (openclaw plugins install @openclaw/openshell-sandbox)
• CLI openshell в PATH (или пользовательский путь через plugins.entries.openshell.config.command)
• Учётная запись OpenShell с доступом к песочницам
• Gateway OpenClaw, запущенный на хосте

Быстрый старт

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 для каждого агента с пользовательским шлюзом

{  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