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 vs. Tool-Richtlinie vs. Elevated

Fehlerdiagnose für „Warum wird dies blockiert?“
Elevated-Modus

Elevated-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:

  • main-Agent: wird auf dem Host ausgeführt und hat vollständigen Tool-Zugriff.
  • family-Agent: wird in Docker ausgeführt (ein Container pro Agent) und kann nur read sowie Nachrichten in der aktuellen Unterhaltung senden.
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 Coding-Profil und Agent ausschließlich für Nachrichten
json
{  "tools": { "profile": "coding" },  "agents": {    "list": [      {        "id": "support",        "tools": { "profile": "messaging", "allow": ["slack"] }      }    ]  }}

Ergebnis:

  • Standardagenten erhalten Coding-Tools.
  • Der support-Agent kann ausschließlich Nachrichten verarbeiten (+ Slack-Tool).
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.entries.*.*) Konfigurationen vorhanden sind:

Sandbox-Konfiguration

Agentenspezifische Einstellungen überschreiben globale Einstellungen:

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

Tool-Einschränkungen

Die Filterreihenfolge lautet:

  • Tool-Profil

    tools.profile oder agents.entries.*.tools.profile.

  • Provider-Tool-Profil

    tools.byProvider[provider].profile oder agents.entries.*.tools.byProvider[provider].profile.

  • Globale Tool-Richtlinie

    tools.allow / tools.deny.

  • Provider-Tool-Richtlinie

    tools.byProvider[provider].allow/deny.

  • Agentenspezifische Tool-Richtlinie

    agents.entries.*.tools.allow/deny.

  • Agenten-Provider-Richtlinie

    agents.entries.*.tools.byProvider[provider].allow/deny.

  • Sandbox-Tool-Richtlinie

    tools.sandbox.tools oder agents.entries.*.tools.sandbox.tools.

  • Subagenten-Tool-Richtlinie

    tools.subagents.tools, falls zutreffend.

    • Vorrangregeln
    • Jede Ebene kann Tools weiter einschränken, aber keine auf früheren Ebenen verweigerten Tools erneut gewähren.
    • Wenn agents.entries.*.tools.sandbox.tools festgelegt ist, ersetzt es tools.sandbox.tools für diesen Agenten.
    • Wenn agents.entries.*.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.entries.*.tools.allow: ["query_db"] konfiguriert ist, soll mit einem deutlichen Fehler abbrechen, bis das Plugin aktiviert wird, 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 Elevated-Überschreibungen (agents.entries.*.tools.elevated) können die Elevated-Ausführung für bestimmte Agenten weiter einschränken. Weitere Informationen finden Sie unter Elevated-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 eines Rohabzugs des Transkripts zurück. Die Assistentenerinnerung entfernt Denk-Tags, <relevant-memories>-Gerüstcode, XML-Nutzdaten von Tool-Aufrufen im Klartext (einschließlich <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls> und abgeschnittener Tool-Aufrufblöcke), herabgestuften Tool-Aufruf-Gerüstcode, offengelegte ASCII-/vollbreite Modellsteuerungstoken und fehlerhaftes MiniMax-Tool-Aufruf-XML vor der Schwärzung/Kürzung.

    Häufiger Fallstrick: „non-main“

    Testen

    Nach der Konfiguration der Multi-Agent-Sandbox und der Tools:

  • 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, die eingeschränkte Tools erfordert.
    • Überprüfen Sie, dass der Agent verweigerte Tools nicht verwenden kann.

  • Protokolle überwachen

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

    • Fehlerbehebung

    Agent wird trotz `mode: 'all'` nicht in einer Sandbox ausgeführt
    • Prüfen Sie, ob ein globales agents.defaults.sandbox.mode vorhanden ist, das diese Einstellung überschreibt.
    • Die agentenspezifische Konfiguration hat Vorrang; legen Sie daher agents.entries.*.sandbox.mode: "all" fest.
    Trotz Sperrliste weiterhin verfügbare Tools
    • Prüfen Sie die vollständige Filterreihenfolge: Profil → Provider-Profil → globale Richtlinie → Provider-Richtlinie → Agentenrichtlinie → Agenten-Provider-Richtlinie → Sandbox → Subagent.
    • Jede Ebene kann nur weitere Einschränkungen vornehmen, nicht jedoch Berechtigungen wieder gewähren.
    • Eine schrittweise Anleitung zur Fehlerbehebung finden Sie unter Sandbox vs. Tool-Richtlinie vs. erhöhter Modus.
    Container nicht pro Agent isoliert
    • Der Standardwert für scope ist "agent" (ein Container pro Agenten-ID).
    • Legen Sie scope: "session" für einen Container pro Sitzung oder scope: "shared" fest, um einen Container agentenübergreifend wiederzuverwenden.

    Verwandte Themen

    Was this useful?
    On this page

    On this page