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 песочницы:

# Список всех сред выполнения песочниц (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

openclaw sandbox recreate --all

Усиление безопасности

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

Текущие ограничения

• Браузер песочницы не поддерживается в бэкенде 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-бэкенд.
4. В режиме mirror: синхронизация с локальной стороны на удаленную перед exec, запуск, синхронизация обратно после exec.
5. В режиме remote: однократное заполнение при создании, затем работа напрямую с удаленной рабочей областью.

Связанные материалы

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