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.

Принцип работы

OpenClaw выполняет sandbox get для имени песочницы (с любыми настроенными --gateway/--gateway-endpoint); если команда завершается ошибкой, OpenClaw создаёт песочницу с помощью sandbox create, передавая --name, --from, --policy, если они заданы, --gpu, если он включён, --auto-providers/--no-auto-providers, а также по одному флагу --provider для каждого настроенного провайдера.
OpenClaw выполняет sandbox ssh-config для имени песочницы, чтобы получить параметры подключения SSH.
Ядро записывает конфигурацию SSH во временный файл и открывает сеанс SSH через тот же мост удалённой файловой системы, что и универсальный бэкенд SSH.
В режиме mirror: синхронизирует локальное рабочее пространство с удалённым перед выполнением команды, выполняет её, затем синхронизирует обратно.
В режиме remote: однократно заполняет рабочее пространство при создании, а затем работает непосредственно с удалённым рабочим пространством.

Связанные разделы

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

Gateway

Remote access

Security

Nodes and media

Web interfaces

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

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

Режимы рабочего пространства

mirror (по умолчанию)

remote

Выбор режима

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

Примеры

Минимальная удалённая конфигурация

Режим mirror с GPU

Отдельная среда OpenShell для каждого агента с пользовательским шлюзом

Управление жизненным циклом

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

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

Принцип работы

Связанные разделы

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

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

​Режимы рабочего пространства

​mirror (по умолчанию)

​remote

​Выбор режима

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

​Примеры

​Минимальная удалённая конфигурация

​Режим mirror с GPU

​Отдельная среда OpenShell для каждого агента с пользовательским шлюзом

​Управление жизненным циклом

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

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

​Принцип работы

​Связанные разделы

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

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

Режимы рабочего пространства

mirror (по умолчанию)

remote

Выбор режима

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

Примеры

Минимальная удалённая конфигурация

Режим mirror с GPU

Отдельная среда OpenShell для каждого агента с пользовательским шлюзом

Управление жизненным циклом

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

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

Принцип работы

Связанные разделы