--- read_when: You hit 'sandbox jail' or see a tool/elevated refusal and want the exact config key to change. status: active summary: 'Чому інструмент заблоковано: середовище виконання пісочниці, політика дозволу/заборони інструментів і обмеження на виконання з підвищеними привілеями' title: Пісочниця, політика інструментів і підвищені привілеї x-i18n: generated_at: "2026-07-12T13:18:42Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 2fce3dab337e89fc2b196f59e763a169d76206ce2695744e00252c158b161260 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. **Підвищений режим** (`tools.elevated.*`, `agents.list[].tools.elevated.*`) — це **аварійний механізм лише для `exec`**, який дає змогу виконувати команди поза пісочницею, коли ви працюєте в ній (`gateway` за замовчуванням або `node`, якщо ціль виконання налаштовано як `node`). ## Швидке налагодження Скористайтеся інспектором, щоб побачити, що OpenClaw _насправді_ робить: ```bash 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"`. Повну матрицю (область дії, монтування робочого простору, образи) див. у розділі [Робота в пісочниці](/uk/gateway/sandboxing). ### Прив’язувальні монтування (швидка перевірка безпеки) - `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 { 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.` (і, за потреби, `agents.list[].tools.elevated.allowFrom.`) Див. [Підвищений режим](/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`. У ньому зафіксовано режим пісочниці та те, яке правило — дозволу чи заборони — заблокувало інструмент. ### «Я думав, що це основний сеанс; чому він у пісочниці?» У режимі `"non-main"` ключі груп/каналів _не_ є основними. Використовуйте ключ основного сеансу (показаний командою `sandbox explain`) або змініть режим на `"off"`. ## Пов’язані матеріали - [Робота в пісочниці](/uk/gateway/sandboxing) — повний довідник із пісочниці (режими, області дії, серверні частини, образи) - [Пісочниця та інструменти для кількох агентів](/uk/tools/multi-agent-sandbox-tools) — перевизначення для окремих агентів і пріоритети - [Підвищений режим](/uk/tools/elevated)