---
read_when: You hit 'sandbox jail' or see a tool/elevated refusal and want the exact config key to change.
status: active
summary: 'Чому інструмент заблоковано: середовище виконання sandbox, політика дозволу/заборони інструментів і шлюзи підвищеного exec'
title: Пісочниця, політика інструментів і підвищені права
x-i18n:
    generated_at: "2026-06-27T17:35:32Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: f4156cc494a6aff4fb9c44cbca8fdfde10a3343dde624c485833dd7508e4c4d6
    source_path: gateway/sandbox-vs-tool-policy-vs-elevated.md
    workflow: 16
---

OpenClaw має три пов’язані (але різні) елементи керування:

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

## Швидке налагодження

Скористайтеся інспектором, щоб побачити, що OpenClaw _насправді_ робить:

```bash
openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json
```

Він виводить:

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

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

Пісочниця керується через `agents.defaults.sandbox.mode`:

- `"off"`: усе запускається на хості.
- `"non-main"`: лише не-main сесії запускаються в пісочниці (поширений “сюрприз” для груп/каналів).
- `"all"`: усе запускається в пісочниці.

Див. [Пісочниця](/uk/gateway/sandboxing) для повної матриці (область, монтування робочого простору, образи).

### Прив’язані монтування (швидка перевірка безпеки)

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

## Політика інструментів: які інструменти існують/можуть викликатися

Важливі два рівні:

- **Профіль інструментів**: `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
{
  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 (без Plugin провайдерів)
- `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`, використовують той самий шлюз пісочниці, але ця діагностика ще не перелічує ці джерела; використовуйте ті самі записи списку дозволів, якщо їхні інструменти зникають у ходах у пісочниці.

## Elevated: “запустити на хості” лише для exec

Elevated **не** надає додаткових інструментів; він впливає лише на `exec`.

- Якщо ви в пісочниці, `/elevated on` (або `exec` з `elevated: true`) запускає поза пісочницею (схвалення все одно можуть застосовуватися).
- Використовуйте `/elevated full`, щоб пропускати схвалення exec для сесії.
- Якщо ви вже запускаєте напряму, Elevated фактично нічого не змінює (але все одно проходить через шлюз).
- Elevated **не** обмежений Skills і **не** перевизначає allow/deny для інструментів.
- Elevated не надає довільних перевизначень між хостами з `host=auto`; він дотримується звичайних правил цілі exec і зберігає `node` лише тоді, коли налаштована/сесійна ціль уже є `node`.
- `/exec` окремий від Elevated. Він лише коригує типові значення exec для кожної сесії для авторизованих відправників.

Шлюзи:

- Увімкнення: `tools.elevated.enabled` (і, за потреби, `agents.list[].tools.elevated.enabled`)
- Списки дозволених відправників: `tools.elevated.allowFrom.<provider>` (і, за потреби, `agents.list[].tools.elevated.allowFrom.<provider>`)

Див. [Режим Elevated](/uk/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` (або до дозволів окремого агента)
- Перевірте `openclaw logs` на запис `agents/tool-policy`. Він фіксує режим пісочниці та чи інструмент заблокувало правило allow або deny.

### “Я думав, що це main, чому воно в пісочниці?”

У режимі `"non-main"` ключі груп/каналів _не_ є main. Використовуйте ключ main-сесії (показаний `sandbox explain`) або перемкніть режим на `"off"`.

## Пов’язане

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