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

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

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

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

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

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

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

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

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

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

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

{  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.

Поширені виправлення “ув’язнення в пісочниці”

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

Пов’язане

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