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?