English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย
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

Multi-Agent-Sandbox und Werkzeuge

Status: active

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

Sandboxing

Backends und Modi — vollständige Sandbox-Referenz.
Sandbox vs. Tool-Richtlinie vs. Elevated

Debugging von „warum ist das blockiert?“
Elevated-Modus

Elevated exec für vertrauenswürdige Absender.

Konfigurationsbeispiele

Beispiel 1: Persönlicher Agent + eingeschränkter Familien-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": "[email protected]"        }      }    }  ]}

Ergebnis:

  • main-Agent: läuft auf dem Host, vollständiger Tool-Zugriff.
  • family-Agent: läuft in Docker (ein Container pro Agent), nur read und Nachrichtenversand in der aktuellen Unterhaltung.
Beispiel 2: Arbeits-Agent mit geteilter 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 + Agent nur für Messaging
json
{  "tools": { "profile": "coding" },  "agents": {    "list": [      {        "id": "support",        "tools": { "profile": "messaging", "allow": ["slack"] }      }    ]  }}

Ergebnis:

  • Standard-Agents erhalten Coding-Tools.
  • Der support-Agent ist nur für Messaging vorgesehen (+ 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.list[].*) Konfigurationen vorhanden sind:

Sandbox-Konfiguration

Agentenspezifische Einstellungen überschreiben globale Einstellungen:

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

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.

  • Agent-Provider-Richtlinie

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

  • Sandbox-Tool-Richtlinie

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

  • Subagent-Tool-Richtlinie

    tools.subagents.tools, falls zutreffend.

    • Vorrangregeln
    • Jede Ebene kann Tools weiter einschränken, aber zuvor verweigerte Tools aus früheren Ebenen nicht wieder gewähren.
    • Wenn agents.list[].tools.sandbox.tools gesetzt ist, ersetzt es tools.sandbox.tools für diesen Agent.
    • Wenn agents.list[].tools.profile gesetzt ist, überschreibt es tools.profile für diesen Agent.
    • Provider-Tool-Schlüssel akzeptieren entweder provider (z. B. google-antigravity) oder provider/model (z. B. openai/gpt-5.4).
    Verhalten bei leerer Allowlist

    Wenn eine explizite Allowlist in dieser Kette dazu führt, dass für den Lauf keine aufrufbaren Tools übrig bleiben, stoppt OpenClaw, bevor der Prompt an das Modell übermittelt wird. Das ist beabsichtigt: Ein Agent, der mit einem fehlenden Tool wie agents.list[].tools.allow: ["query_db"] konfiguriert ist, sollte deutlich fehlschlagen, bis das Plugin aktiviert ist, das query_db registriert, und nicht als reiner Text-Agent fortfahren.

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

    Elevated-Überschreibungen pro Agent (agents.list[].tools.elevated) können Elevated exec für bestimmte Agents weiter einschränken. Details finden Sie unter Elevated-Modus.

    Migration vom Einzelagenten

    Vorher (Einzelagent)

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

    Nachher (Multi-Agent)

    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 Abrufansicht zurück, statt einen rohen Transkript-Dump. Der Assistentenabruf entfernt Thinking-Tags, <relevant-memories>-Gerüste, Klartext-XML-Nutzlasten von Tool-Aufrufen (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-Aufruf-Gerüste, durchgesickerte ASCII-/Vollbreiten-Modellsteuerungstokens sowie fehlerhaftes MiniMax-Tool-Aufruf-XML vor Redaktion/Kürzung.

    Häufige Fehlerquelle: "non-main"

    Testen

    Nach dem Konfigurieren von Multi-Agent-Sandbox und Tools:

  • Agent-Auflösung prüfen

    bash
    openclaw agents list --bindings

  • Sandbox-Container verifizieren

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

  • Tool-Einschränkungen testen

    • Senden Sie eine Nachricht, die eingeschränkte Tools erfordert.
    • Verifizieren Sie, dass der Agent verweigerte Tools nicht verwenden kann.

  • Logs überwachen

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

    • Fehlerbehebung

    Agent trotz `mode: 'all'` nicht in Sandbox
    • Prüfen Sie, ob es ein globales agents.defaults.sandbox.mode gibt, das dies überschreibt.
    • Agent-spezifische Konfiguration hat Vorrang, setzen Sie daher agents.list[].sandbox.mode: "all".
    Tools trotz Deny-Liste weiterhin verfügbar
    • Prüfen Sie die Reihenfolge der Tool-Filterung: global → Agent → Sandbox → Subagent.
    • Jede Ebene kann nur weiter einschränken, nicht erneut gewähren.
    • Verifizieren Sie dies mit Logs: [tools] filtering tools for agent:${agentId}.
    Container nicht pro Agent isoliert
    • Setzen Sie scope: "agent" in der Agent-spezifischen Sandbox-Konfiguration.
    • Standard ist "session", wodurch ein Container pro Sitzung erstellt wird.

    Verwandte Themen

    Was this useful?