> ## 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. **Elevated** (`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)
* ефективні дозволи/заборони інструментів пісочниці (і чи вони походять від агента/глобальних налаштувань/типових значень)
* шлюзи 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 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 (без 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)