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

Изменения файлов на хосте вне OpenClaw после первоначального заполнения не видны удалённой песочнице. Выполните openclaw sandbox recreate, чтобы заполнить её заново.

​

Выбор режима

	mirror	remote
Каноническое рабочее пространство	Локальный хост	Удалённая среда OpenShell
Направление синхронизации	Двунаправленная (при каждом выполнении)	Однократное заполнение
Накладные расходы на ход	Выше (отправка + загрузка)	Ниже (прямые удалённые операции)
Видны локальные изменения?	Да, при следующем выполнении	Нет, до повторного создания
Лучше всего подходит для	Рабочих процессов разработки	Долгоживущих агентов, CI

​

Справочник по конфигурации

Вся конфигурация OpenShell находится в plugins.entries.openshell.config:

Ключ	Тип	Значение по умолчанию	Описание
mode	"mirror" или "remote"	"mirror"	Режим синхронизации рабочего пространства
command	string	"openshell"	Путь к CLI openshell или его имя
from	string	"openclaw"	Источник песочницы при первоначальном создании
gateway	string	unset	Имя шлюза OpenShell (--gateway верхнего уровня)
gatewayEndpoint	string	unset	Конечная точка шлюза OpenShell (--gateway-endpoint верхнего уровня)
policy	string	unset	Идентификатор политики OpenShell для создания песочницы
providers	string[]	[]	Имена провайдеров, добавляемые при создании песочницы (без дубликатов, по одному флагу --provider на запись)
gpu	boolean	false	Запрашивать ресурсы GPU (--gpu)
autoProviders	boolean	true	Передавать --auto-providers (или --no-auto-providers, если значение равно false) при создании
remoteWorkspaceDir	string	"/sandbox"	Основное доступное для записи рабочее пространство внутри песочницы
remoteAgentWorkspaceDir	string	"/agent"	Путь монтирования рабочего пространства агента (только для чтения, если доступ к рабочему пространству не равен rw)
timeoutSeconds	number	120	Время ожидания операций CLI openshell

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