Multi-Agenten-Sandbox und Tools

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.

Die Authentifizierung ist auf den jeweiligen Agenten beschränkt: Jeder Agent verfügt über einen eigenen agentDir-Authentifizierungsspeicher in ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. Verwenden Sie agentDir niemals agentenübergreifend. Agenten können auf die Authentifizierungsprofile des standardmäßigen/Hauptagenten zurückgreifen, wenn sie kein lokales Profil besitzen; OAuth-Aktualisierungstoken werden jedoch nicht in die Speicher sekundärer Agenten kopiert. Wenn Sie Anmeldedaten manuell kopieren, kopieren Sie nur übertragbare statische api_key- oder token-Profile.

Konfigurationsbeispiele

Beispiel 1: Persönlicher Agent und 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", "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

{
  "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

{
  "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

{
  "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:

agents.entries.*.sandbox.mode > agents.defaults.sandbox.mode
agents.entries.*.sandbox.scope > agents.defaults.sandbox.scope
agents.entries.*.sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
agents.entries.*.sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
agents.entries.*.sandbox.docker.* > agents.defaults.sandbox.docker.*
agents.entries.*.sandbox.browser.* > agents.defaults.sandbox.browser.*
agents.entries.*.sandbox.prune.* > agents.defaults.sandbox.prune.*

agents.entries.*.sandbox.{docker,browser,prune}.* überschreibt agents.defaults.sandbox.{docker,browser,prune}.* für diesen Agenten (wird ignoriert, wenn der Sandbox-Geltungsbereich zu "shared" aufgelöst wird).

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)
Nachher (mehrere Agenten)

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

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

Veraltete agents.defaults.*/agents.entries.*.*-Konfigurationsschlüssel (wie sandbox.perSession, agentRuntime, embeddedPi) werden durch openclaw doctor migriert; verwenden Sie künftig vorzugsweise agents.defaults + agents.entries.

Beispiele für Tool-Einschränkungen

Schreibgeschützter Agent
Shell-Ausführung mit deaktivierten Dateisystem-Tools
Nur Kommunikation

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

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

Diese Richtlinie deaktiviert die Dateisystem-Tools von OpenClaw, aber exec ist weiterhin eine Shell und kann überall dort Dateien schreiben, wo das Dateisystem des ausgewählten Hosts oder der Sandbox dies zulässt. Verweigern Sie für einen schreibgeschützten Agenten exec und process, oder kombinieren Sie den Shell-Zugriff mit Sandbox-Dateisystemkontrollen wie agents.defaults.sandbox.workspaceAccess: "ro" oder "none".

{
  "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“

agents.defaults.sandbox.mode: "non-main" vergleicht den Sitzungsschlüssel mit dem Hauptsitzungsschlüssel (immer "main"; session.mainKey kann nicht benutzerseitig konfiguriert werden, und OpenClaw warnt bei jedem anderen Wert und ignoriert ihn), nicht mit der Agenten-ID. Gruppen-/Kanalsitzungen erhalten stets eigene Schlüssel, werden daher als Nicht-Hauptsitzungen behandelt und in einer Sandbox ausgeführt. Wenn ein Agent niemals in einer Sandbox ausgeführt werden soll, legen Sie agents.entries.*.sandbox.mode: "off" fest.

Testen

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

Agentenauflösung prüfen

openclaw agents list --bindings

Sandbox-Container überprüfen

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

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.

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Multi-Agenten-Sandbox und Tools

Sandboxing

Sandbox vs. Tool-Richtlinie vs. Elevated

Elevated-Modus

Konfigurationsbeispiele

Konfigurationsvorrang

Sandbox-Konfiguration

Tool-Einschränkungen

Migration von einem einzelnen Agenten

Beispiele für Tool-Einschränkungen

Häufiger Fallstrick: „non-main“

Testen

Fehlerbehebung

Verwandte Themen

Sandboxing

Sandbox vs. Tool-Richtlinie vs. Elevated

Elevated-Modus

​Konfigurationsbeispiele

​Konfigurationsvorrang

​Sandbox-Konfiguration

​Tool-Einschränkungen

​Migration von einem einzelnen Agenten

​Beispiele für Tool-Einschränkungen

​Häufiger Fallstrick: „non-main“

​Testen

​Fehlerbehebung

​Verwandte Themen

Konfigurationsbeispiele

Konfigurationsvorrang

Sandbox-Konfiguration

Tool-Einschränkungen

Migration von einem einzelnen Agenten

Beispiele für Tool-Einschränkungen

Häufiger Fallstrick: „non-main“

Testen

Fehlerbehebung

Verwandte Themen