​

Sandbox vs Tool Policy vs Elevated

1. Sandbox (agents.defaults.sandbox.* / agents.list[].sandbox.*) визначає, де запускаються інструменти (Docker чи хост).
2. Політика інструментів (tools.*, tools.sandbox.tools.*, agents.list[].tools.*) визначає, які інструменти доступні/дозволені.
3. Elevated (tools.elevated.*, agents.list[].tools.elevated.*) — це лише для exec механізм обходу, щоб запускати поза sandbox, коли ви перебуваєте в sandbox (gateway типово або node, коли exec target налаштовано як node).

​

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

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

• ефективний режим/scope/workspace access sandbox
• чи сесія зараз працює в sandbox (main чи non-main)
• ефективний allow/deny інструментів sandbox (і чи походить він від agent/global/default)
• механізми elevated і ключі шляхів fix-it

​

Sandbox: де запускаються інструменти

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

​

Bind mounts (швидка перевірка безпеки)

• docker.binds пробиває файлову систему sandbox: усе, що ви монтуєте, стає видимим усередині контейнера з указаним режимом (:ro або :rw).
• Якщо не вказати режим, типово використовується read-write; для source/secrets віддавайте перевагу :ro.
• scope: "shared" ігнорує bind для кожного агента окремо (застосовуються лише глобальні bind).
• OpenClaw двічі перевіряє джерела bind: спочатку на нормалізованому шляху джерела, потім ще раз після визначення через найглибший наявний батьківський каталог. Вихід через symlink-батьківський шлях не обходить перевірки blocked-path або allowed-root.
• Неіснуючі leaf-шляхи все одно безпечно перевіряються. Якщо /workspace/alias-out/new-file визначається через symlink-батьківський каталог у заблокований шлях або поза межами налаштованих allowed roots, bind буде відхилено.
• Монтування /var/run/docker.sock фактично передає контроль над хостом у sandbox; робіть це лише свідомо.
• Доступ до workspace (workspaceAccess: "ro"/"rw") не залежить від режимів bind.

​

Політика інструментів: які інструменти існують/можна викликати

• Профіль інструментів: tools.profile і agents.list[].tools.profile (базовий allowlist)
• Профіль інструментів провайдера: 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
• Політика інструментів sandbox (застосовується лише в sandbox): tools.sandbox.tools.allow/tools.sandbox.tools.deny і agents.list[].tools.sandbox.tools.*

• deny завжди має перевагу.
• Якщо allow не порожній, усе інше вважається заблокованим.
• Політика інструментів — це жорстке обмеження: /exec не може перевизначити заборонений інструмент exec.
• /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: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: cron, gateway
• group:messaging: message
• group:nodes: nodes
• group:agents: agents_list
• group:media: image, image_generate, video_generate, tts
• group:openclaw: усі вбудовані інструменти OpenClaw (без provider plugins)

​

Elevated: механізм “запустити на хості” лише для exec

• Якщо ви в sandbox, /elevated on (або exec з elevated: true) запускається поза sandbox (при цьому підтвердження можуть усе ще застосовуватися).
• Використовуйте /elevated full, щоб пропустити підтвердження exec для сесії.
• Якщо ви вже працюєте напряму, elevated фактично нічого не змінює (але все одно керується механізмами доступу).
• Elevated не обмежується Skills і не перевизначає allow/deny інструментів.
• Elevated не надає довільних міжхостових перевизначень із host=auto; він дотримується звичайних правил exec target і зберігає node лише тоді, коли налаштований/сесійний target уже дорівнює node.
• /exec — це окремий механізм від elevated. Він лише налаштовує типові параметри exec для сесії для авторизованих відправників.

• Увімкнення: tools.elevated.enabled (і, за потреби, agents.list[].tools.elevated.enabled)
• Allowlist відправників: tools.elevated.allowFrom.<provider> (і, за потреби, agents.list[].tools.elevated.allowFrom.<provider>)

​

Типові виправлення “sandbox jail"

​

"Tool X blocked by sandbox tool policy”

• Вимкнути sandbox: agents.defaults.sandbox.mode=off (або для конкретного агента agents.list[].sandbox.mode=off)
• Дозволити інструмент усередині sandbox:
  • прибрати його з tools.sandbox.tools.deny (або для конкретного агента agents.list[].tools.sandbox.tools.deny)
  • або додати його до tools.sandbox.tools.allow (або до allow для агента)

​

“I thought this was main, why is it sandboxed?”

​

Див. також

• Sandboxing — повний довідник із sandbox (режими, scope, backend, images)
• Multi-Agent Sandbox & Tools — перевизначення для кожного агента окремо та пріоритетність
• Elevated Mode