--- read_when: - Вам нужны облачные управляемые песочницы вместо локального Docker - Вы настраиваете плагин OpenShell - Вам нужно выбрать между режимами зеркального и удалённого рабочего пространства summary: Используйте OpenShell как управляемый сервер изолированной среды для агентов OpenClaw title: OpenShell x-i18n: generated_at: "2026-07-13T18:12:37Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: bf5c33912bd0db759a01cf58ea26712a8ada68c0804bf16f69f1f7cdd496828c source_path: gateway/openshell.md workflow: 16 --- OpenShell — это управляемый бэкенд песочницы: вместо локального запуска контейнеров Docker OpenClaw делегирует управление жизненным циклом песочницы CLI `openshell`, который подготавливает удалённые среды и выполняет команды через SSH. Плагин повторно использует тот же транспорт SSH и мост удалённой файловой системы, что и универсальный [бэкенд SSH](/ru/gateway/sandboxing#ssh-backend), а также добавляет управление жизненным циклом 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, запущенный на хосте ## Быстрый старт ```bash openclaw plugins install @openclaw/openshell-sandbox ``` ```json5 { agents: { defaults: { sandbox: { mode: "all", backend: "openshell", scope: "session", workspaceAccess: "rw", }, }, }, plugins: { entries: { openshell: { enabled: true, config: { from: "openclaw", mode: "remote", }, }, }, }, } ``` Перезапустите Gateway. При следующем ходе агента OpenClaw создаст песочницу OpenShell и направит через неё выполнение инструментов. Для проверки выполните: ```bash 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`, как и для любого другого бэкенда. Полную матрицу см. в разделе [Изоляция в песочнице](/ru/gateway/sandboxing). ## Примеры ### Минимальная удалённая конфигурация ```json5 { agents: { defaults: { sandbox: { mode: "all", backend: "openshell", }, }, }, plugins: { entries: { openshell: { enabled: true, config: { from: "openclaw", mode: "remote", }, }, }, }, } ``` ### Режим mirror с GPU ```json5 { 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 для каждого агента с пользовательским шлюзом ```json5 { 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", }, }, }, }, } ``` ## Управление жизненным циклом ```bash # Вывести список всех сред выполнения песочниц (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`: однократно заполняет рабочее пространство при создании, а затем работает непосредственно с удалённым рабочим пространством. ## Связанные разделы - [Изоляция в песочнице](/ru/gateway/sandboxing) — режимы, области и сравнение бэкендов - [Песочница, политика инструментов и повышенные привилегии](/ru/gateway/sandbox-vs-tool-policy-vs-elevated) — отладка заблокированных инструментов - [Песочница и инструменты для нескольких агентов](/ru/tools/multi-agent-sandbox-tools) — переопределения для отдельных агентов - [CLI песочницы](/ru/cli/sandbox) — команды `openclaw sandbox`