Sandbox vs. Tool-Richtlinie vs. erhöhte Berechtigungen

OpenClaw verfügt über drei miteinander zusammenhängende, aber unterschiedliche Steuerungsmöglichkeiten:

1. Sandbox (agents.defaults.sandbox.* / agents.list[].sandbox.*) legt fest, wo Tools ausgeführt werden (Sandbox-Backend oder Host).
2. Tool-Richtlinie (tools.*, tools.sandbox.tools.*, agents.list[].tools.*) legt fest, welche Tools verfügbar/zulässig sind.
3. Elevated (tools.elevated.*, agents.list[].tools.elevated.*) ist ein nur für exec vorgesehener Ausweg, um bei aktivierter Sandbox außerhalb der Sandbox auszuführen (standardmäßig gateway oder node, wenn das exec-Ziel auf node konfiguriert ist).

Schnelle Fehlerdiagnose

Verwenden Sie den Inspektor, um zu sehen, was OpenClaw tatsächlich tut:

openclaw sandbox explainopenclaw sandbox explain --session agent:main:mainopenclaw sandbox explain --agent workopenclaw sandbox explain --json

Er gibt Folgendes aus:

• effektiver Sandbox-Modus/-Geltungsbereich/-Arbeitsbereichszugriff
• ob die Sitzung derzeit in einer Sandbox ausgeführt wird (Hauptsitzung oder Nicht-Hauptsitzung)
• effektive Zulassungs-/Sperrregeln für Sandbox-Tools (und ob sie vom Agenten, global oder aus den Standardwerten stammen)
• Elevated-Schranken und Konfigurationspfade zur Behebung

Sandbox: Wo Tools ausgeführt werden

Die Sandbox-Ausführung wird durch agents.defaults.sandbox.mode gesteuert:

• "off": Alles wird auf dem Host ausgeführt.
• "non-main": Nur Nicht-Hauptsitzungen werden in einer Sandbox ausgeführt (eine häufige „Überraschung“ bei Gruppen/Kanälen).
• "all": Alles wird in einer Sandbox ausgeführt.

agents.defaults.sandbox.workspaceAccess steuert, was die Sandbox sehen kann: "none", "ro" oder "rw".

Die vollständige Matrix (Geltungsbereiche, Einbindungen von Arbeitsbereichen, Images) finden Sie unter Sandbox-Ausführung.

Bind-Mounts (kurze Sicherheitsprüfung)

• docker.binds durchbricht das Sandbox-Dateisystem: Alles, was Sie einbinden, ist innerhalb des Containers in dem von Ihnen festgelegten Modus (:ro oder :rw) sichtbar.
• Wenn Sie den Modus weglassen, gilt standardmäßig Lese- und Schreibzugriff; verwenden Sie für Quellcode/geheime Daten vorzugsweise :ro.
• scope: "shared" ignoriert agentenspezifische Bind-Mounts (es gelten nur globale Bind-Mounts).
• OpenClaw validiert Bind-Quellen zweimal: zuerst anhand des normalisierten Quellpfads und anschließend erneut nach der Auflösung über den tiefsten vorhandenen übergeordneten Pfad. Ausbrüche über symbolisch verknüpfte übergeordnete Verzeichnisse umgehen weder Prüfungen auf gesperrte Pfade noch Prüfungen auf zulässige Stammverzeichnisse.
• Nicht vorhandene Endpfade werden dennoch sicher geprüft. Wenn /workspace/alias-out/new-file über ein symbolisch verknüpftes übergeordnetes Verzeichnis zu einem gesperrten Pfad oder aus den konfigurierten zulässigen Stammverzeichnissen heraus aufgelöst wird, wird der Bind-Mount abgelehnt.
• Das Einbinden von /var/run/docker.sock überträgt der Sandbox faktisch die Kontrolle über den Host; tun Sie dies nur bewusst.
• Der Arbeitsbereichszugriff (workspaceAccess) ist von den Bind-Mount-Modi unabhängig.

Tool-Richtlinie: Welche Tools vorhanden/aufrufbar sind

Mehrere Ebenen sind relevant:

• Tool-Profil: tools.profile und agents.list[].tools.profile (grundlegende Zulassungsliste)
• Provider-Tool-Profil: tools.byProvider[provider].profile und agents.list[].tools.byProvider[provider].profile
• Globale/agentenspezifische Tool-Richtlinie: tools.allow/tools.deny und agents.list[].tools.allow/agents.list[].tools.deny
• Provider-Tool-Richtlinie: tools.byProvider[provider].allow/deny und agents.list[].tools.byProvider[provider].allow/deny
• Sandbox-Tool-Richtlinie (gilt nur bei Ausführung in einer Sandbox): tools.sandbox.tools.allow/tools.sandbox.tools.deny und agents.list[].tools.sandbox.tools.*

Faustregeln:

• deny hat immer Vorrang.
• Wenn allow nicht leer ist, gilt alles andere als gesperrt.
• Die Tool-Richtlinie ist eine harte Grenze: /exec kann ein gesperrtes exec-Tool nicht freigeben.
• Die Tool-Richtlinie filtert die Tool-Verfügbarkeit nach Namen; sie prüft keine Nebenwirkungen innerhalb von exec. Wenn exec zulässig ist, werden Shell-Befehle durch das Sperren von write, edit oder apply_patch nicht schreibgeschützt.
• /exec ändert nur die Sitzungsvorgaben für autorisierte Absender; es gewährt keinen Tool-Zugriff.
• Provider-Tool-Schlüssel akzeptieren entweder provider (z. B. google-antigravity) oder provider/model (z. B. openai/gpt-5.4).
• Gateway-Protokolle enthalten agents/tool-policy-Prüfeinträge, wenn ein Schritt der Tool-Richtlinie Tools entfernt oder eine Sandbox-Tool-Richtlinie einen Aufruf blockiert. Verwenden Sie openclaw logs, um die Regelbezeichnung, den Konfigurationsschlüssel und die betroffenen Tool-Namen anzuzeigen.

Tool-Gruppen (Kurzformen)

Tool-Richtlinien (global, Agent, Sandbox) unterstützen group:*-Einträge, die zu mehreren Tools erweitert werden:

{  tools: {    sandbox: {      tools: {        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],      },    },  },}

Verfügbare Gruppen:

Sperren Sie bei schreibgeschützten Agenten sowohl group:runtime als auch Dateisystem-Tools mit Schreibwirkung, sofern nicht die Sandbox-Dateisystemrichtlinie oder eine separate Host-Grenze die Schreibschutzbeschränkung durchsetzt.

Bei MCP-Servern in einer Sandbox stellt die Sandbox-Tool-Richtlinie eine zweite Zulassungsschranke dar. Wenn mcp.servers konfiguriert ist, aber Sandbox-Durchläufe nur integrierte Tools anzeigen, fügen Sie bundle-mcp, group:plugins oder einen MCP-Tool-Namen bzw. ein Glob-Muster mit Serverpräfix wie outlook__send_mail oder outlook__* zu tools.sandbox.tools.alsoAllow hinzu. Starten Sie anschließend den Gateway neu bzw. laden Sie ihn neu und erfassen Sie die Tool-Liste erneut. Server-Glob-Muster verwenden das Provider-sichere MCP-Serverpräfix: Zeichen außerhalb von [A-Za-z0-9_-] werden zu -, Namen, die nicht mit einem Buchstaben beginnen, erhalten das Präfix mcp-, und lange oder doppelte Präfixe können gekürzt oder mit einem Suffix versehen werden.

openclaw doctor prüft diese Struktur derzeit für von OpenClaw verwaltete Server in mcp.servers. MCP-Server, die aus gebündelten Plugin-Manifesten oder der Claude-Datei .mcp.json geladen werden, verwenden dieselbe Sandbox-Schranke, diese Diagnose führt diese Quellen jedoch noch nicht auf. Verwenden Sie dieselben Einträge in der Zulassungsliste, wenn deren Tools in Sandbox-Durchläufen verschwinden.

Elevated: Nur exec „auf dem Host ausführen“

Elevated gewährt keine zusätzlichen Tools; es wirkt sich nur auf exec aus.

• Wenn Sie sich in einer Sandbox befinden, führt /elevated on (oder exec mit elevated: true) den Vorgang außerhalb der Sandbox aus (Genehmigungen können weiterhin erforderlich sein).
• Verwenden Sie /elevated full, um exec-Genehmigungen für die Sitzung zu überspringen.
• Wenn Sie bereits direkt ausführen, hat Elevated faktisch keine Wirkung (die Schranken gelten weiterhin).
• Elevated ist nicht auf Skills beschränkt und setzt die Tool-Zulassungs-/Sperrregeln nicht außer Kraft.
• Elevated gewährt bei host=auto keine beliebigen hostübergreifenden Außerkraftsetzungen; es folgt den normalen Regeln für exec-Ziele und behält node nur bei, wenn das konfigurierte Ziel bzw. das Sitzungsziel bereits node ist.
• /exec ist von Elevated getrennt. Es passt lediglich die sitzungsspezifischen exec-Vorgaben für autorisierte Absender an.

Schranken:

• Aktivierung: tools.elevated.enabled (und optional agents.list[].tools.elevated.enabled)
• Absender-Zulassungslisten: tools.elevated.allowFrom.<provider> (und optional agents.list[].tools.elevated.allowFrom.<provider>)

Siehe Elevated-Modus.

Häufige Lösungen bei „Sandbox-Gefängnis“

„Tool X durch die Sandbox-Tool-Richtlinie gesperrt“

Konfigurationsschlüssel zur Behebung (wählen Sie eine Möglichkeit):

• Sandbox deaktivieren: agents.defaults.sandbox.mode=off (oder agentenspezifisch agents.list[].sandbox.mode=off)
• Das Tool innerhalb der Sandbox zulassen:
  • Entfernen Sie es aus tools.sandbox.tools.deny (oder agentenspezifisch aus agents.list[].tools.sandbox.tools.deny).
  • Oder fügen Sie es zu tools.sandbox.tools.allow hinzu (bzw. zur agentenspezifischen Zulassungsliste).
• Prüfen Sie openclaw logs auf den Eintrag agents/tool-policy. Er zeichnet den Sandbox-Modus auf und gibt an, ob die Zulassungs- oder Sperrregel das Tool blockiert hat.

„Ich dachte, dies sei die Hauptsitzung. Warum wird sie in einer Sandbox ausgeführt?“

Im Modus "non-main" sind Gruppen-/Kanalschlüssel keine Hauptsitzungen. Verwenden Sie den Schlüssel der Hauptsitzung (angezeigt durch sandbox explain) oder ändern Sie den Modus in "off".

Verwandte Themen

• Sandbox-Ausführung -- vollständige Sandbox-Referenz (Modi, Geltungsbereiche, Backends, Images)
• Sandbox und Tools für mehrere Agenten -- agentenspezifische Außerkraftsetzungen und Vorrangregeln
• Elevated-Modus