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

Он выводит:

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

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

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

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

См. [Песочница](/ru/gateway/sandboxing) для полной матрицы (область действия, монтирования рабочей области, образы).

### Bind-монтирования (быстрая проверка безопасности)

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

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

Важны два слоя:

* **Профиль инструментов**: `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` не делает команды shell доступными только для чтения.
* `/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:runtime`, а также инструменты, изменяющие файловую систему, если политика файловой системы песочницы или отдельная граница хоста не обеспечивает ограничение только для чтения.
* `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`
* `group:agents`: `agents_list`, `update_plan`
* `group:media`: `image`, `image_generate`, `music_generate`, `video_generate`, `tts`
* `group:openclaw`: все встроенные инструменты OpenClaw (исключая плагины провайдеров)
* `group:plugins`: все загруженные инструменты, принадлежащие Plugin, включая настроенные MCP-серверы, предоставленные через `bundle-mcp`

Для 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-серверы, загруженные из манифестов bundled Plugin или Claude `.mcp.json`, используют тот же шлюз песочницы, но эта диагностика пока не перечисляет такие источники; используйте те же записи списка разрешений, если их инструменты исчезают в ходах в песочнице.

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

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

* Если вы в песочнице, `/elevated on` (или `exec` с `elevated: true`) запускается вне песочницы (одобрения все еще могут применяться).
* Используйте `/elevated full`, чтобы пропустить одобрения exec для сеанса.
* Если вы уже запускаетесь напрямую, повышенный режим фактически ничего не меняет (но все равно проверяется шлюзами).
* Повышенный режим **не** ограничен Skills и **не** переопределяет allow/deny инструментов.
* Повышенный режим не предоставляет произвольных межхостовых переопределений из `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>`)

См. [Повышенный режим](/ru/tools/elevated).

## Частые исправления «тюрьмы песочницы»

### «Инструмент 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` (или в поагентный allow)
* Проверьте `openclaw logs` на запись `agents/tool-policy`. В ней фиксируется режим песочницы и то, какое правило allow или deny заблокировало инструмент.

### «Я думал, что это main, почему он в песочнице?»

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

## Связанные материалы

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