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

Agent coordination

Multi-Agenten-Sandbox und Werkzeuge

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

Sandboxing

Backends und Modi — vollständige Sandbox-Referenz.
Sandbox vs. Tool-Richtlinie vs. erhöht

Fehlersuche: „Warum ist das blockiert?“
Erhöhter Modus

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

Konfigurationsbeispiele

Beispiel 1: Persönlicher + eingeschränkter Familienagent 
{
  "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"],
          "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"]
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "family",
      "match": {
        "provider": "whatsapp",
        "accountId": "*",
        "peer": {
          "kind": "group",
          "id": "[email protected]"
        }
      }
    }
  ]
}

Ergebnis:

  • Agent main: läuft auf dem Host, vollständiger Tool-Zugriff.
  • Agent family: läuft in Docker (ein Container pro Agent), nur das Tool read.
Beispiel 2: Arbeitsagent mit gemeinsam genutzter Sandbox 
{
  "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 + Nur-Messaging-Agent 
{
  "tools": { "profile": "coding" },
  "agents": {
    "list": [
      {
        "id": "support",
        "tools": { "profile": "messaging", "allow": ["slack"] }
      }
    ]
  }
}

Ergebnis:

  • Standardagenten erhalten Coding-Tools.
  • Der Agent support ist nur für Messaging konfiguriert (+ Slack-Tool).
Beispiel 3: Unterschiedliche Sandbox-Modi pro Agent 
{
  "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:

agents.list[].sandbox.mode > agents.defaults.sandbox.mode
agents.list[].sandbox.scope > agents.defaults.sandbox.scope
agents.list[].sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
agents.list[].sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
agents.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 ist:

  • 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 anwendbar.

    • Vorrangregeln
    • Jede Ebene kann Tools weiter einschränken, aber zuvor verweigerte Tools nicht wieder gewähren.
    • Wenn agents.list[].tools.sandbox.tools gesetzt ist, ersetzt es tools.sandbox.tools für diesen Agenten.
    • Wenn agents.list[].tools.profile gesetzt 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 Allowlist

    Wenn eine explizite Allowlist in dieser Kette dazu führt, dass für den Lauf keine Tools aufrufbar sind, stoppt OpenClaw, bevor der Prompt an das Modell gesendet wird. Das ist beabsichtigt: Ein Agent, der mit einem fehlenden Tool wie agents.list[].tools.allow: ["query_db"] konfiguriert ist, soll deutlich fehlschlagen, bis das Plugin, das query_db registriert, aktiviert ist, 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 erhöhte Überschreibungen (agents.list[].tools.elevated) können erhöhte Ausführung für bestimmte Agenten weiter einschränken. Details finden Sie unter Erhöhter Modus.

    Migration von einem einzelnen Agenten

    Vorher (einzelner Agent)

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

    Nachher (Multi-Agent)

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

    Beispiele für Tool-Einschränkungen

    Schreibgeschützter Agent

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

    Sichere Ausführung (keine Dateiänderungen)

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

    Nur Kommunikation

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

    sessions_history in diesem Profil gibt weiterhin eine begrenzte, bereinigte Erinnerungsansicht zurück, statt eines rohen Transcript-Dumps. Der Assistentenabruf entfernt Denk-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 gekürzter Tool-Aufrufblöcke), herabgestufte Tool-Aufrufgerüste, offengelegte ASCII-/vollbreite Modellsteuerungstoken und fehlerhaftes MiniMax-Tool-Aufruf-XML vor Redaktion/Kürzung.

    Häufige Fehlerquelle: „non-main“

    Tests

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

  • Agentenauflösung prüfen

    openclaw agents list --bindings

  • Sandbox-Container verifizieren

    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

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

    • Fehlerbehebung

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

    Verwandte Themen