> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenShell

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

Плагин повторно использует тот же транспорт SSH и мост удалённой файловой системы, что и
универсальный [бэкенд SSH](https://docs2.openclaw.ai/ru/gateway/sandboxing.md#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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins install @openclaw/openshell-sandbox
```

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
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: меньше накладных расходов на каждый ход,
а локальные изменения на хосте не могут незаметно перезаписать удалённое состояние.

> [!WARNING]
>
> Изменения файлов на хосте вне 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`, как и для любого другого бэкенда. Полную матрицу см. в разделе
[Изоляция в песочнице](https://docs2.openclaw.ai/ru/gateway/sandboxing.md).

## Примеры

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
        },
      },
    },
  },
}
```

### Режим mirror с GPU

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Вывести список всех сред выполнения песочниц (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`: однократно заполняет рабочее пространство при создании, а затем работает непосредственно с удалённым
   рабочим пространством.

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

* [Изоляция в песочнице](https://docs2.openclaw.ai/ru/gateway/sandboxing.md) — режимы, области и сравнение бэкендов
* [Песочница, политика инструментов и повышенные привилегии](https://docs2.openclaw.ai/ru/gateway/sandbox-vs-tool-policy-vs-elevated.md) — отладка заблокированных инструментов
* [Песочница и инструменты для нескольких агентов](https://docs2.openclaw.ai/ru/tools/multi-agent-sandbox-tools.md) — переопределения для отдельных агентов
* [CLI песочницы](https://docs2.openclaw.ai/ru/cli/sandbox.md) — команды `openclaw sandbox`