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

Agent coordination

Multi-Agenten-Sandbox und Tools

Status: active

Jeder Agent in einer Multi-Agent-Konfiguration kann die globale Sandbox- und Tool-Richtlinie überschreiben. Diese Seite behandelt die agentenspezifische Konfiguration, Vorrangregeln und Beispiele.

Sandboxing

Backends und Modi – vollständige Sandbox-Referenz.
Sandbox, Tool-Richtlinie und erhöhter Modus im Vergleich

Fehlersuche bei „Warum wird dies blockiert?“
Erhöhter Modus

Erhöhte Ausführung für vertrauenswürdige Absender.

Konfigurationsbeispiele

Beispiel 1: Persönlicher Agent und eingeschränkter Familienagent
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"        }      }    }  ]}

Ergebnis:

  • Agent main: wird auf dem Host mit vollständigem Tool-Zugriff ausgeführt.
  • Agent family: wird in Docker ausgeführt (ein Container pro Agent) und kann nur read sowie das Senden von Nachrichten in der aktuellen Unterhaltung verwenden.
Beispiel 2: Arbeitsagent mit gemeinsam genutzter 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"]        }      }    ]  }}
Beispiel 2b: Globales Programmierprofil und Agent ausschließlich für Nachrichten
json
{  "tools": { "profile": "coding" },  "agents": {    "list": [      {        "id": "support",        "tools": { "profile": "messaging", "allow": ["slack"] }      }    ]  }}

Ergebnis:

  • Standardagenten erhalten Programmier-Tools.
  • Der Agent support kann ausschließlich Nachrichtenfunktionen verwenden (zuzüglich des Slack-Tools).
Beispiel 3: Unterschiedliche Sandbox-Modi pro 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"]        }      }    ]  }}

Konfigurationsvorrang

Wenn sowohl globale (agents.defaults.*) als auch agentenspezifische (agents.list[].*) Konfigurationen vorhanden sind:

Sandbox-Konfiguration

Agentenspezifische Einstellungen überschreiben globale Einstellungen:

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-Einschränkungen

Die Filterreihenfolge lautet:

  • Tool-Profil

    tools.profile oder agents.list[].tools.profile.

  • Provider-Tool-Profil

    tools.byProvider[provider].profile oder agents.list[].tools.byProvider[provider].profile.

  • Globale Tool-Richtlinie

    tools.allow / tools.deny.

  • Provider-Tool-Richtlinie

    tools.byProvider[provider].allow/deny.

  • Agentenspezifische Tool-Richtlinie

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

  • Agentenbezogene Provider-Richtlinie

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

  • Sandbox-Tool-Richtlinie

    tools.sandbox.tools oder agents.list[].tools.sandbox.tools.

  • Subagenten-Tool-Richtlinie

    tools.subagents.tools, sofern zutreffend.

    • Vorrangregeln
    • Jede Ebene kann Tools weiter einschränken, aber keine auf früheren Ebenen verweigerten Tools erneut freigeben.
    • Wenn agents.list[].tools.sandbox.tools festgelegt ist, ersetzt es tools.sandbox.tools für diesen Agenten.
    • Wenn agents.list[].tools.profile festgelegt ist, überschreibt es tools.profile für diesen Agenten.
    • Provider-Tool-Schlüssel akzeptieren entweder provider (z. B. google-antigravity) oder provider/model (z. B. openai/gpt-5.4).
    Verhalten bei leerer Zulassungsliste

    Wenn eine explizite Zulassungsliste in dieser Kette dazu führt, dass für die Ausführung keine aufrufbaren Tools verbleiben, hält OpenClaw an, bevor der Prompt an das Modell übermittelt wird. Dies ist beabsichtigt: Ein Agent, der mit einem fehlenden Tool wie agents.list[].tools.allow: ["query_db"] konfiguriert ist, sollte mit einer deutlichen Fehlermeldung abbrechen, bis das Plugin aktiviert ist, das query_db registriert, statt als reiner Textagent fortzufahren.

    Tool-Richtlinien unterstützen group:*-Kurzformen, die zu mehreren Tools erweitert werden. Die vollständige Liste finden Sie unter Tool-Gruppen.

    Agentenspezifische Überschreibungen für den erhöhten Modus (agents.list[].tools.elevated) können die erhöhte Ausführung für bestimmte Agenten weiter einschränken. Weitere Informationen finden Sie unter Erhöhter Modus.

    Migration von einem einzelnen Agenten

    Vorher (einzelner Agent)

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

    Nachher (mehrere Agenten)

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

    Beispiele für Tool-Einschränkungen

    Schreibgeschützter Agent

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

    Shell-Ausführung mit deaktivierten Dateisystem-Tools

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

    Nur Kommunikation

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

    sessions_history gibt in diesem Profil weiterhin eine begrenzte, bereinigte Erinnerungsansicht statt einer Rohfassung des Transkripts zurück. Die Assistentenerinnerung entfernt Denk-Tags, das <relevant-memories>-Gerüst, Tool-Aufruf-Nutzdaten im Klartext-XML-Format (einschließlich <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls> und abgeschnittener Tool-Aufrufblöcke), herabgestufte Tool-Aufrufgerüste, offengelegte ASCII-/vollbreite Modellsteuerungstoken sowie fehlerhaftes MiniMax-Tool-Aufruf-XML, bevor Schwärzung und Kürzung erfolgen.

    Häufige Fehlerquelle: "non-main"

    Tests

    Nach der Konfiguration der Sandbox und Tools für mehrere Agenten:

  • Agentenauflösung prüfen

    bash
    openclaw agents list --bindings

  • Sandbox-Container überprüfen

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

  • Tool-Einschränkungen testen

    • Senden Sie eine Nachricht, für die eingeschränkte Tools erforderlich sind.
    • Vergewissern Sie sich, dass der Agent verweigerte Tools nicht verwenden kann.

  • Protokolle überwachen

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

    • Fehlerbehebung

    Agent trotz `mode: 'all'` nicht in einer Sandbox ausgeführt
    • Prüfen Sie, ob eine globale Einstellung agents.defaults.sandbox.mode vorhanden ist, die diese Einstellung überschreibt.
    • Die agentenspezifische Konfiguration hat Vorrang. Legen Sie daher agents.list[].sandbox.mode: "all" fest.
    Tools trotz Sperrliste weiterhin verfügbar
    Container nicht pro Agent isoliert
    • Der standardmäßige scope ist "agent" (ein Container pro Agent-ID).
    • Legen Sie scope: "session" für einen Container pro Sitzung oder scope: "shared" für die Wiederverwendung eines Containers durch mehrere Agenten fest.

    Verwandte Themen

    Was this useful?
    On this page

    On this page