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

OpenClaw hat drei verwandte (aber unterschiedliche) Steuerungen:

1. Sandbox (agents.defaults.sandbox.* / agents.list[].sandbox.*) entscheidet, wo Tools ausgeführt werden (Sandbox-Backend oder Host).
2. Tool-Richtlinie (tools.*, tools.sandbox.tools.*, agents.list[].tools.*) entscheidet, welche Tools verfügbar/erlaubt sind.
3. Elevated (tools.elevated.*, agents.list[].tools.elevated.*) ist eine nur für exec gedachte Ausweichmöglichkeit, um außerhalb der Sandbox auszuführen, wenn Sie in einer Sandbox sind (standardmäßig gateway, oder node, wenn das exec-Ziel auf node konfiguriert ist).

Schnelles Debugging

Verwenden Sie den Inspector, 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/-Scope und Workspace-Zugriff
• ob die Sitzung aktuell in einer Sandbox läuft (main vs. nicht-main)
• effektive Sandbox-Tool-Erlaubnis/-Ablehnung (und ob sie von Agent/global/default stammt)
• Elevated-Gates und Fix-it-Schlüsselpfade

Sandbox: wo Tools ausgeführt werden

Sandboxing wird über agents.defaults.sandbox.mode gesteuert:

• "off": Alles läuft auf dem Host.
• "non-main": Nur nicht-main-Sitzungen laufen in einer Sandbox (häufige „Überraschung“ für Gruppen/Kanäle).
• "all": Alles läuft in einer Sandbox.

Die vollständige Matrix (Scope, Workspace-Mounts, Images) finden Sie unter Sandboxing.

Bind-Mounts (schneller Sicherheitscheck)

• docker.binds durchdringt das Sandbox-Dateisystem: Alles, was Sie mounten, ist im Container mit dem von Ihnen gesetzten Modus sichtbar (:ro oder :rw).
• Standard ist Lese-/Schreibzugriff, wenn Sie den Modus weglassen; bevorzugen Sie :ro für Source/Secrets.
• scope: "shared" ignoriert agentenspezifische Binds (nur globale Binds gelten).
• OpenClaw validiert Bind-Quellen zweimal: zuerst auf dem normalisierten Quellpfad, dann erneut nach der Auflösung über den tiefsten existierenden Vorfahren. Symlink-Parent-Escapes umgehen keine Prüfungen für blockierte Pfade oder erlaubte Roots.
• Nicht vorhandene Leaf-Pfade werden weiterhin sicher geprüft. Wenn /workspace/alias-out/new-file über einen verlinkten Parent zu einem blockierten Pfad oder außerhalb der konfigurierten erlaubten Roots aufgelöst wird, wird der Bind abgelehnt.
• Das Binden von /var/run/docker.sock übergibt der Sandbox effektiv die Kontrolle über den Host; tun Sie dies nur absichtlich.
• Workspace-Zugriff (workspaceAccess: "ro"/"rw") ist unabhängig von Bind-Modi.

Tool-Richtlinie: welche Tools existieren/aufrufbar sind

Zwei Ebenen sind wichtig:

• Tool-Profil: tools.profile und agents.list[].tools.profile (Basis-Allowlist)
• 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 in einer Sandbox): tools.sandbox.tools.allow/tools.sandbox.tools.deny und agents.list[].tools.sandbox.tools.*

Faustregeln:

• deny gewinnt immer.
• Wenn allow nicht leer ist, wird alles andere als blockiert behandelt.
• Die Tool-Richtlinie ist die harte Grenze: /exec kann ein abgelehntes exec-Tool nicht überschreiben.
• Die Tool-Richtlinie filtert die Tool-Verfügbarkeit nach Name; sie prüft keine Nebenwirkungen innerhalb von exec. Wenn exec erlaubt ist, macht das Ablehnen von write, edit oder apply_patch Shell-Befehle nicht schreibgeschützt.
• /exec ändert nur Sitzungsstandards 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-Logs enthalten agents/tool-policy-Audit-Einträge, wenn ein Schritt der Tool-Richtlinie Tools entfernt oder eine Sandbox-Tool-Richtlinie einen Aufruf blockiert. Verwenden Sie openclaw logs, um das Regel-Label, den Konfigurationsschlüssel und die betroffenen Tool-Namen zu sehen.

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:

• group:runtime: exec, process, code_execution (bash wird als Alias für exec akzeptiert)
• group:fs: read, write, edit, apply_patch Für schreibgeschützte Agenten lehnen Sie group:runtime sowie mutierende Dateisystem-Tools ab, sofern die Sandbox-Dateisystemrichtlinie oder eine separate Host-Grenze die Schreibschutzbeschränkung nicht erzwingt.
• group:sessions: sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status
• group:memory: memory_search, memory_get
• group:web: web_search, x_search, web_fetch
• group:ui: browser, canvas
• group:automation: heartbeat_respond, cron, gateway
• group:messaging: message
• group:nodes: nodes
• group:agents: agents_list, update_plan
• group:media: image, image_generate, music_generate, video_generate, tts
• group:openclaw: alle integrierten OpenClaw-Tools (ohne Provider-Plugins)
• group:plugins: alle geladenen Plugin-eigenen Tools, einschließlich konfigurierter MCP-Server, die über bundle-mcp verfügbar gemacht werden

Für MCP-Server in einer Sandbox ist die Sandbox-Tool-Richtlinie ein zweites Allow-Gate. Wenn mcp.servers konfiguriert ist, aber Sandbox-Turns nur integrierte Tools anzeigen, fügen Sie bundle-mcp, group:plugins oder einen serverpräfixierten MCP-Tool-Namen/-Glob wie outlook__send_mail oder outlook__* zu tools.sandbox.tools.alsoAllow hinzu, starten/laden Sie dann den Gateway neu und erfassen Sie die Tool-Liste erneut. Server-Globs verwenden den Provider-sicheren MCP-Server-Präfix: Nicht-[A-Za-z0-9_-]-Zeichen werden zu -, Namen, die nicht mit einem Buchstaben beginnen, erhalten ein mcp--Präfix, und lange oder doppelte Präfixe können gekürzt oder mit einem Suffix versehen werden.

openclaw doctor prüft diese Form aktuell für von OpenClaw verwaltete Server in mcp.servers. MCP-Server, die aus gebündelten Plugin-Manifesten oder Claude .mcp.json geladen werden, verwenden dasselbe Sandbox-Gate, aber diese Diagnose listet diese Quellen noch nicht auf; verwenden Sie dieselben Allowlist-Einträge, wenn deren Tools in Sandbox-Turns 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 in einer Sandbox sind, führt /elevated on (oder exec mit elevated: true) außerhalb der Sandbox aus (Genehmigungen können weiterhin gelten).
• Verwenden Sie /elevated full, um exec-Genehmigungen für die Sitzung zu überspringen.
• Wenn Sie bereits direkt ausführen, ist Elevated effektiv ein No-op (weiterhin gegated).
• Elevated ist nicht Skill-scoped und überschreibt keine Tool-Erlaubnis/-Ablehnung.
• Elevated gewährt keine beliebigen hostübergreifenden Overrides von host=auto; es folgt den normalen exec-Zielregeln und bewahrt node nur, wenn das konfigurierte/Sitzungsziel bereits node ist.
• /exec ist von Elevated getrennt. Es passt nur agentenspezifische exec-Standards für autorisierte Absender an.

Gates:

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

Siehe Elevated Mode.

Häufige „Sandbox-Gefängnis“-Korrekturen

„Tool X blocked by sandbox tool policy“

Fix-it-Schlüssel (wählen Sie einen):

• Sandbox deaktivieren: agents.defaults.sandbox.mode=off (oder agentenspezifisch agents.list[].sandbox.mode=off)
• Tool innerhalb der Sandbox erlauben:
  • entfernen Sie es aus tools.sandbox.tools.deny (oder agentenspezifisch agents.list[].tools.sandbox.tools.deny)
  • oder fügen Sie es zu tools.sandbox.tools.allow hinzu (oder agentenspezifische Erlaubnis)
• Prüfen Sie openclaw logs auf den Eintrag agents/tool-policy. Er zeichnet den Sandbox-Modus auf und ob die Allow- oder Deny-Regel das Tool blockiert hat.

„Ich dachte, dies sei main, warum läuft es in einer Sandbox?“

Im Modus "non-main" sind Gruppen-/Kanalschlüssel nicht main. Verwenden Sie den main-Sitzungsschlüssel (angezeigt von sandbox explain) oder wechseln Sie den Modus zu "off".

Verwandt

• Sandboxing -- vollständige Sandbox-Referenz (Modi, Scopes, Backends, Images)
• Multi-Agent Sandbox & Tools -- agentenspezifische Overrides und Rangfolge
• Elevated Mode