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

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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, коли ціль exec налаштована на node).

​

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

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

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

​

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

• "off": усе запускається на хості.
• "non-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).

​

Групи інструментів (скорочення)

{
  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 провайдерів)

​

Підвищений режим: “запуск на хості” лише для 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 (або до дозволів окремого агента)

​

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

​

Пов’язане

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