OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Agent coordination

Пісочниця та інструменти для кількох агентів

Status: active

Кожен агент у багатоагентній конфігурації може перевизначати глобальну політику пісочниці та інструментів. На цій сторінці описано конфігурацію для окремих агентів, правила пріоритетності та приклади.

Sandboxing

Бекенди та режими — повний довідник із пісочниці.
Sandbox vs tool policy vs elevated

Налагодження проблеми «чому це заблоковано?»
Elevated mode

Виконання з підвищеними привілеями для довірених відправників.

Приклади конфігурації

Example 1: Personal + restricted family agent
json
{  "agents": {    "list": [      {        "id": "main",        "default": true,        "name": "Personal Assistant",        "workspace": "~/.openclaw/workspace",        "sandbox": { "mode": "off" }      },      {        "id": "family",        "name": "Family Bot",        "workspace": "~/.openclaw/workspace-family",        "sandbox": {          "mode": "all",          "scope": "agent"        },        "tools": {          "allow": ["read", "message"],          "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"],          "message": {            "crossContext": {              "allowWithinProvider": false,              "allowAcrossProviders": false            }          }        }      }    ]  },  "bindings": [    {      "agentId": "family",      "match": {        "provider": "whatsapp",        "accountId": "*",        "peer": {          "kind": "group",          "id": "120363424282127706@g.us"        }      }    }  ]}

Результат:

  • Агент main: працює на хості та має повний доступ до інструментів.
  • Агент family: працює в Docker (один контейнер на агента), може лише читати за допомогою read і надсилати повідомлення в поточній розмові.
Example 2: Work agent with shared sandbox
json
{  "agents": {    "list": [      {        "id": "personal",        "workspace": "~/.openclaw/workspace-personal",        "sandbox": { "mode": "off" }      },      {        "id": "work",        "workspace": "~/.openclaw/workspace-work",        "sandbox": {          "mode": "all",          "scope": "shared",          "workspaceRoot": "/tmp/work-sandboxes"        },        "tools": {          "allow": ["read", "write", "apply_patch", "exec"],          "deny": ["browser", "gateway", "discord"]        }      }    ]  }}
Example 2b: Global coding profile + messaging-only agent
json
{  "tools": { "profile": "coding" },  "agents": {    "list": [      {        "id": "support",        "tools": { "profile": "messaging", "allow": ["slack"] }      }    ]  }}

Результат:

  • типові агенти отримують інструменти для програмування.
  • агент support може лише обмінюватися повідомленнями (+ інструмент Slack).
Example 3: Different sandbox modes per agent
json
{  "agents": {    "defaults": {      "sandbox": {        "mode": "non-main",        "scope": "session"      }    },    "list": [      {        "id": "main",        "workspace": "~/.openclaw/workspace",        "sandbox": {          "mode": "off"        }      },      {        "id": "public",        "workspace": "~/.openclaw/workspace-public",        "sandbox": {          "mode": "all",          "scope": "agent"        },        "tools": {          "allow": ["read"],          "deny": ["exec", "write", "edit", "apply_patch"]        }      }    ]  }}

Пріоритетність конфігурації

Коли одночасно існують глобальні (agents.defaults.*) і специфічні для агента (agents.list[].*) конфігурації:

Конфігурація пісочниці

Специфічні для агента налаштування перевизначають глобальні:

text
agents.list[].sandbox.mode > agents.defaults.sandbox.modeagents.list[].sandbox.scope > agents.defaults.sandbox.scopeagents.list[].sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRootagents.list[].sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccessagents.list[].sandbox.docker.* > agents.defaults.sandbox.docker.*agents.list[].sandbox.browser.* > agents.defaults.sandbox.browser.*agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*

Обмеження інструментів

Порядок фільтрації:

  • Tool profile

    tools.profile або agents.list[].tools.profile.

  • Provider tool profile

    tools.byProvider[provider].profile або agents.list[].tools.byProvider[provider].profile.

  • Global tool policy

    tools.allow / tools.deny.

  • Provider tool policy

    tools.byProvider[provider].allow/deny.

  • Agent-specific tool policy

    agents.list[].tools.allow/deny.

  • Agent provider policy

    agents.list[].tools.byProvider[provider].allow/deny.

  • Sandbox tool policy

    tools.sandbox.tools або agents.list[].tools.sandbox.tools.

  • Subagent tool policy

    tools.subagents.tools, якщо застосовно.

    • Precedence rules
    • Кожен рівень може додатково обмежувати інструменти, але не може повторно дозволяти інструменти, заборонені на попередніх рівнях.
    • Якщо задано agents.list[].tools.sandbox.tools, воно замінює tools.sandbox.tools для цього агента.
    • Якщо задано agents.list[].tools.profile, воно перевизначає tools.profile для цього агента.
    • Ключі інструментів провайдера приймають як provider (наприклад, google-antigravity), так і provider/model (наприклад, openai/gpt-5.4).
    Empty allowlist behavior

    Якщо будь-який явний список дозволених інструментів у цьому ланцюжку залишає запуск без доступних для виклику інструментів, OpenClaw зупиняється до надсилання запиту моделі. Це навмисна поведінка: агент, налаштований із відсутнім інструментом, наприклад agents.list[].tools.allow: ["query_db"], має завершуватися з явною помилкою, доки не буде ввімкнено Plugin, який реєструє query_db, а не продовжувати роботу як агент, що підтримує лише текст.

    Політики інструментів підтримують скорочення group:*, які розгортаються в кілька інструментів. Повний список наведено в розділі Групи інструментів.

    Перевизначення підвищених привілеїв для окремих агентів (agents.list[].tools.elevated) можуть додатково обмежувати виконання з підвищеними привілеями для певних агентів. Докладніше див. у розділі Режим підвищених привілеїв.

    Міграція з одного агента

    Before (single agent)

    json
    {  "agents": {    "defaults": {      "workspace": "~/.openclaw/workspace",      "sandbox": {        "mode": "non-main"      }    }  },  "tools": {    "sandbox": {      "tools": {        "allow": ["read", "write", "apply_patch", "exec"],        "deny": []      }    }  }}

    After (multi-agent)

    json
    {  "agents": {    "list": [      {        "id": "main",        "default": true,        "workspace": "~/.openclaw/workspace",        "sandbox": { "mode": "off" }      }    ]  }}

    Приклади обмеження інструментів

    Read-only agent

    json
    {  "tools": {    "allow": ["read"],    "deny": ["exec", "write", "edit", "apply_patch", "process"]  }}

    Shell execution with filesystem tools disabled

    json
    {  "tools": {    "allow": ["read", "exec", "process"],    "deny": ["write", "edit", "apply_patch", "browser", "gateway"]  }}

    Communication-only

    json
    {  "tools": {    "sessions": { "visibility": "tree" },    "allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"],    "deny": ["exec", "write", "edit", "apply_patch", "read", "browser"]  }}

    sessions_history у цьому профілі все одно повертає обмежене й очищене подання відновленого контексту, а не необроблений дамп стенограми. Під час відновлення контексту асистента видаляються теги міркувань, службова структура <relevant-memories>, XML-навантаження викликів інструментів у вигляді звичайного тексту (зокрема <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls> і обрізані блоки викликів інструментів), службова структура викликів інструментів зі зниженим рівнем, витіклі керівні токени моделі у форматі ASCII або повноширинному форматі та некоректний XML викликів інструментів MiniMax — усе це відбувається до редагування й обрізання.

    Поширена помилка: "non-main"

    Тестування

    Після налаштування багатоагентної пісочниці та інструментів:

  • Check agent resolution

    bash
    openclaw agents list --bindings

  • Verify sandbox containers

    bash
    docker ps --filter "name=openclaw-sbx-"

  • Test tool restrictions

    • Надішліть повідомлення, яке потребує обмежених інструментів.
    • Переконайтеся, що агент не може використовувати заборонені інструменти.

  • Monitor logs

    bash
    openclaw logs --follow | grep -E "routing|sandbox|tools"

    • Усунення несправностей

    Agent not sandboxed despite `mode: 'all'`
    • Перевірте, чи немає глобального agents.defaults.sandbox.mode, яке його перевизначає.
    • Конфігурація конкретного агента має вищий пріоритет, тому задайте agents.list[].sandbox.mode: "all".
    Інструменти все ще доступні попри список заборон
    Контейнер не ізольовано для кожного агента
    • Стандартне значення scope — "agent" (один контейнер на ідентифікатор агента).
    • Установіть scope: "session", щоб використовувати один контейнер на сеанс, або scope: "shared", щоб повторно використовувати один контейнер для кількох агентів.

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

    Was this useful?
    On this page

    On this page