English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaishiالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiruفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Agent coordination

Многоагентная песочница и инструменты

Status: active

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

Песочница

Бэкенды и режимы — полный справочник по песочнице.
Песочница, политика инструментов и повышенный режим

Отладка вопроса «почему это заблокировано?»
Повышенный режим

Повышенный exec для доверенных отправителей.

Примеры конфигурации

Пример 1: личный агент + ограниченный семейный агент
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 и отправка сообщений в текущей беседе.
Пример 2: рабочий агент с общей песочницей
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"]        }      }    ]  }}
Пример 2b: глобальный профиль программирования + агент только для сообщений
json
{  "tools": { "profile": "coding" },  "agents": {    "list": [      {        "id": "support",        "tools": { "profile": "messaging", "allow": ["slack"] }      }    ]  }}

Результат:

  • агенты по умолчанию получают инструменты для программирования.
  • агент support работает только с сообщениями (+ инструмент Slack).
Пример 3: разные режимы песочницы для разных агентов
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[].*) конфигурации:

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

Настройки конкретного агента переопределяют глобальные:

Code
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.*

Ограничения инструментов

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

  • Профиль инструментов

    tools.profile или agents.list[].tools.profile.

  • Профиль инструментов провайдера

    tools.byProvider[provider].profile или agents.list[].tools.byProvider[provider].profile.

  • Глобальная политика инструментов

    tools.allow / tools.deny.

  • Политика инструментов провайдера

    tools.byProvider[provider].allow/deny.

  • Политика инструментов конкретного агента

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

  • Политика провайдера агента

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

  • Политика инструментов песочницы

    tools.sandbox.tools или agents.list[].tools.sandbox.tools.

  • Политика инструментов субагента

    tools.subagents.tools, если применимо.

    • Правила приоритета
    • Каждый уровень может дополнительно ограничивать инструменты, но не может снова разрешить инструменты, запрещенные на предыдущих уровнях.
    • Если задано agents.list[].tools.sandbox.tools, оно заменяет tools.sandbox.tools для этого агента.
    • Если задано agents.list[].tools.profile, оно переопределяет tools.profile для этого агента.
    • Ключи инструментов провайдера принимают либо provider (например, google-antigravity), либо provider/model (например, openai/gpt-5.4).
    Поведение пустого списка разрешений

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

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

    Переопределения повышенного режима для отдельных агентов (agents.list[].tools.elevated) могут дополнительно ограничивать повышенный exec для конкретных агентов. Подробнее см. в разделе Повышенный режим.

    Миграция с одного агента

    До (один агент)

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

    После (мультиагентный режим)

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

    Примеры ограничений инструментов

    Агент только для чтения

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

    Выполнение shell с отключенными файловыми инструментами

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

    Только коммуникация

    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"

    Тестирование

    После настройки мультиагентной песочницы и инструментов:

  • Проверьте разрешение агента

    bash
    openclaw agents list --bindings

  • Проверьте контейнеры песочницы

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

  • Проверьте ограничения инструментов

    • Отправьте сообщение, требующее ограниченных инструментов.
    • Убедитесь, что агент не может использовать запрещенные инструменты.

  • Отслеживайте журналы

    bash
    tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools"

    • Устранение неполадок

    Агент не запускается в песочнице, несмотря на `mode: 'all'`
    • Проверьте, есть ли глобальный agents.defaults.sandbox.mode, который переопределяет это значение.
    • Конфигурация конкретного агента имеет приоритет, поэтому задайте agents.list[].sandbox.mode: "all".
    Инструменты все еще доступны, несмотря на список запретов
    • Проверьте порядок фильтрации инструментов: глобальный → агент → песочница → субагент.
    • Каждый уровень может только дополнительно ограничивать, а не возвращать доступ.
    • Проверьте по журналам: [tools] filtering tools for agent:${agentId}.
    Контейнер не изолирован для каждого агента
    • Задайте scope: "agent" в конфигурации песочницы конкретного агента.
    • Значение по умолчанию — "session", при котором создается один контейнер на сеанс.

    Связанные материалы

    Was this useful?
    On this page

    On this page