> ## 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.

# Песочница, политика инструментов и повышенные привилегии

OpenClaw имеет три связанных, но разных механизма управления:

1. **Песочница** (`agents.defaults.sandbox.*` / `agents.list[].sandbox.*`) определяет, **где запускаются инструменты** (в песочнице или на хосте).
2. **Политика инструментов** (`tools.*`, `tools.sandbox.tools.*`, `agents.list[].tools.*`) определяет, **какие инструменты доступны и разрешены**.
3. **Повышенный режим** (`tools.elevated.*`, `agents.list[].tools.elevated.*`) — это **аварийный выход только для exec**, позволяющий выполнять команды вне песочницы, когда сеанс изолирован (`gateway` по умолчанию или `node`, когда целью exec настроен `node`).

## Быстрая диагностика

Используйте инспектор, чтобы узнать, что OpenClaw делает *на самом деле*:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json
```

Он выводит:

* фактический режим и область песочницы, а также доступ к рабочему пространству
* находится ли текущий сеанс в песочнице (основной или неосновной)
* фактические разрешения и запреты инструментов песочницы (и их источник: агент, глобальная конфигурация или значение по умолчанию)
* ограничения повышенного режима и пути к ключам для исправления

## Песочница: где запускаются инструменты

Работа песочницы управляется параметром `agents.defaults.sandbox.mode`:

* `"off"`: всё запускается на хосте.
* `"non-main"`: только неосновные сеансы изолируются в песочнице (частая неожиданность для групп и каналов).
* `"all"`: всё запускается в песочнице.

`agents.defaults.sandbox.workspaceAccess` определяет, что доступно песочнице: `"none"`, `"ro"` или `"rw"`.

Полную матрицу (область, подключения рабочего пространства, образы) см. в разделе [Песочница](https://docs2.openclaw.ai/ru/gateway/sandboxing.md).

### Подключения bind (быстрая проверка безопасности)

* `docker.binds` *пробивает* файловую систему песочницы: всё подключённое становится доступно внутри контейнера в заданном режиме (`:ro` или `:rw`).
* Если режим не указан, по умолчанию используется чтение и запись; для исходного кода и секретов предпочитайте `:ro`.
* `scope: "shared"` игнорирует подключения отдельных агентов (применяются только глобальные подключения).
* OpenClaw дважды проверяет источники подключений: сначала нормализованный исходный путь, затем путь после разрешения через наиболее глубокого существующего предка. Выход через родительский символьный путь не позволяет обойти проверки запрещённых путей или разрешённых корневых каталогов.
* Несуществующие конечные пути также проверяются безопасным образом. Если `/workspace/alias-out/new-file` через родительскую символьную ссылку разрешается в запрещённый путь или за пределы настроенных разрешённых корневых каталогов, подключение отклоняется.
* Подключение `/var/run/docker.sock` фактически передаёт песочнице управление хостом; делайте это только намеренно.
* Доступ к рабочему пространству (`workspaceAccess`) не зависит от режимов подключений.

## Политика инструментов: какие инструменты существуют и могут вызываться

Важны два уровня:

* **Профиль инструментов**: `tools.profile` и `agents.list[].tools.profile` (базовый список разрешений)
* **Профиль инструментов провайдера**: `tools.byProvider[provider].profile` и `agents.list[].tools.byProvider[provider].profile`
* **Глобальная политика инструментов и политика отдельных агентов**: `tools.allow`/`tools.deny` и `agents.list[].tools.allow`/`agents.list[].tools.deny`
* **Политика инструментов провайдера**: `tools.byProvider[provider].allow/deny` и `agents.list[].tools.byProvider[provider].allow/deny`
* **Политика инструментов песочницы** (применяется только в песочнице): `tools.sandbox.tools.allow`/`tools.sandbox.tools.deny` и `agents.list[].tools.sandbox.tools.*`

Основные правила:

* `deny` всегда имеет приоритет.
* Если `allow` не пуст, всё остальное считается заблокированным.
* Политика инструментов — окончательное ограничение: `/exec` не может разрешить запрещённый инструмент `exec`.
* Политика инструментов фильтрует их доступность по имени; она не проверяет побочные эффекты внутри `exec`. Если `exec` разрешён, запрет `write`, `edit` или `apply_patch` не переводит команды оболочки в режим только для чтения.
* `/exec` изменяет только значения сеанса по умолчанию для авторизованных отправителей; доступа к инструментам он не предоставляет.
* Ключи инструментов провайдера принимают либо `provider` (например, `google-antigravity`), либо `provider/model` (например, `openai/gpt-5.4`).
* Журналы Gateway содержат записи аудита `agents/tool-policy`, когда один из этапов политики инструментов удаляет инструменты или политика инструментов песочницы блокирует вызов. Используйте `openclaw logs`, чтобы увидеть метку правила, ключ конфигурации и имена затронутых инструментов.

### Группы инструментов (сокращения)

Политики инструментов (глобальные, агентские и относящиеся к песочнице) поддерживают записи `group:*`, которые разворачиваются в несколько инструментов:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  tools: {
    sandbox: {
      tools: {
        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
      },
    },
  },
}
```

Доступные группы:

| Группа | Инструменты |
| - | - |
| `group:runtime` | `exec`, `process`, `code_execution` (`bash` принимается как псевдоним для `exec`) |
| `group:fs` | `read`, `write`, `edit`, `apply_patch` |
| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` |
| `group:memory` | `memory_search`, `memory_get` |
| `group:web` | `web_search`, `x_search`, `web_fetch` |
| `group:ui` | `browser`, `canvas` |
| `group:automation` | `heartbeat_respond`, `cron`, `gateway` |
| `group:messaging` | `message` |
| `group:nodes` | `nodes`, `computer` |
| `group:agents` | `agents_list`, `get_goal`, `create_goal`, `update_goal`, `update_plan`, `skill_workshop` |
| `group:media` | `image`, `image_generate`, `music_generate`, `video_generate`, `tts` |
| `group:openclaw` | большинство встроенных инструментов OpenClaw (кроме примитивов файловой системы и среды выполнения `read`/`write`/`edit`/`apply_patch`/`exec`/`process`, `canvas` и плагинов провайдеров) |
| `group:plugins` | все загруженные инструменты, принадлежащие плагинам, включая настроенные серверы MCP, предоставляемые через `bundle-mcp` |

Для агентов, работающих только в режиме чтения, запретите `group:runtime`, а также инструменты, изменяющие файловую систему, если ограничение только для чтения не обеспечивается политикой файловой системы песочницы или отдельной границей хоста.

Для серверов MCP в песочнице политика инструментов песочницы служит вторым разрешающим барьером. Если `mcp.servers` настроен, но при работе в песочнице отображаются только встроенные инструменты, добавьте `bundle-mcp`, `group:plugins` либо имя или шаблон инструмента MCP с префиксом сервера, например `outlook__send_mail` или `outlook__*`, в `tools.sandbox.tools.alsoAllow`, затем перезапустите или перезагрузите Gateway и снова получите список инструментов. Шаблоны серверов используют безопасный для провайдера префикс сервера MCP: символы, не относящиеся к `[A-Za-z0-9_-]`, заменяются на `-`; к именам, которые не начинаются с буквы, добавляется префикс `mcp-`; длинные или повторяющиеся префиксы могут сокращаться или получать суффикс.

`openclaw doctor` сейчас проверяет эту структуру для серверов под управлением OpenClaw в `mcp.servers`. Серверы MCP, загруженные из манифестов встроенных плагинов или Claude `.mcp.json`, используют тот же барьер песочницы, но эта диагностика пока не перечисляет такие источники; если их инструменты исчезают в сеансах песочницы, используйте те же записи списка разрешений.

## Повышенный режим: «запуск на хосте» только для exec

Повышенный режим **не** предоставляет дополнительные инструменты; он влияет только на `exec`.

* Если вы находитесь в песочнице, `/elevated on` (или `exec` с `elevated: true`) выполняется вне песочницы (при этом подтверждение всё ещё может требоваться).
* Используйте `/elevated full`, чтобы пропустить подтверждения exec для сеанса.
* Если выполнение уже происходит напрямую, повышенный режим фактически ничего не меняет (ограничения всё равно применяются).
* Повышенный режим **не** ограничен областью Skills и **не** переопределяет разрешения и запреты инструментов.
* Повышенный режим не предоставляет произвольных переопределений между хостами из `host=auto`; он следует обычным правилам выбора цели exec и сохраняет `node` только тогда, когда настроенной целью или целью сеанса уже является `node`.
* `/exec` не относится к повышенному режиму. Он лишь изменяет значения exec по умолчанию для сеанса у авторизованных отправителей.

Ограничения:

* Включение: `tools.elevated.enabled` (и при необходимости `agents.list[].tools.elevated.enabled`)
* Списки разрешённых отправителей: `tools.elevated.allowFrom.<provider>` (и при необходимости `agents.list[].tools.elevated.allowFrom.<provider>`)

См. раздел [Повышенный режим](https://docs2.openclaw.ai/ru/tools/elevated.md).

## Типичные способы выхода из «тюрьмы песочницы»

### «Инструмент X заблокирован политикой инструментов песочницы»

Ключи для исправления (выберите один вариант):

* Отключить песочницу: `agents.defaults.sandbox.mode=off` (или `agents.list[].sandbox.mode=off` для отдельного агента)
* Разрешить инструмент внутри песочницы:
  * удалите его из `tools.sandbox.tools.deny` (или `agents.list[].tools.sandbox.tools.deny` для отдельного агента)
  * либо добавьте его в `tools.sandbox.tools.allow` (или в список разрешений отдельного агента)
* Проверьте запись `agents/tool-policy` в `openclaw logs`. В ней указан режим песочницы и правило разрешения или запрета, заблокировавшее инструмент.

### «Я думал, это основной сеанс. Почему он находится в песочнице?»

В режиме `"non-main"` ключи групп и каналов *не* являются основными. Используйте ключ основного сеанса (показанный командой `sandbox explain`) или переключитесь в режим `"off"`.

## См. также

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