Пісочниця, політика інструментів і підвищені привілеї

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 насправді робить:

openclaw sandbox explainopenclaw sandbox explain --session agent:main:mainopenclaw sandbox explain --agent workopenclaw sandbox explain --json

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

• чинний режим, область дії та доступ до робочого простору пісочниці
• чи працює поточний сеанс у пісочниці (основний чи неосновний)
• чинні дозволи/заборони інструментів пісочниці (і чи походять вони з налаштувань агента, глобальних налаштувань або значень за замовчуванням)
• умови підвищеного режиму та шляхи ключів для виправлення

Пісочниця: де виконуються інструменти

Роботою в пісочниці керує agents.defaults.sandbox.mode:

• "off": усе виконується на хості.
• "non-main": лише неосновні сеанси працюють у пісочниці (поширена «несподіванка» для груп/каналів).
• "all": усе працює в пісочниці.

agents.defaults.sandbox.workspaceAccess визначає, що може бачити пісочниця: "none", "ro" або "rw".

Повну матрицю (область дії, монтування робочого простору, образи) див. у розділі Робота в пісочниці.

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

• 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:*, які розгортаються в кілька інструментів:

{  tools: {    sandbox: {      tools: {        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],      },    },  },}

Доступні групи:

Для агентів із доступом лише для читання забороніть 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>)

Див. Підвищений режим.

Типові виправлення «ув’язнення в пісочниці»

«Інструмент 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".

Пов’язані матеріали

• Робота в пісочниці — повний довідник із пісочниці (режими, області дії, серверні частини, образи)
• Пісочниця та інструменти для кількох агентів — перевизначення для окремих агентів і пріоритети
• Підвищений режим