Sandbox vs Tool-Policy vs Elevated

OpenClaw hat drei verwandte, aber unterschiedliche Steuerungsmechanismen:

Sandbox (agents.defaults.sandbox.* / agents.list[].sandbox.*) bestimmt, wo Tools ausgeführt werden (Docker vs Host).
Tool-Policy (tools.*, tools.sandbox.tools.*, agents.list[].tools.*) bestimmt, welche Tools verfügbar/erlaubt sind.
Elevated (tools.elevated.*, agents.list[].tools.elevated.*) ist ein Exec-only-Notausgang, um bei aktiver Sandbox trotzdem auf dem Host auszuführen.

Schnelldiagnose

Nutze den Inspector, um zu sehen, was OpenClaw tatsächlich macht:

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

Er zeigt:

Effektiven Sandbox-Modus/Scope/Workspace-Zugriff
Ob die Session aktuell sandboxed ist (Main vs Nicht-Main)
Effektive Sandbox-Tool-Allow/Deny-Regeln (und ob sie von Agent/Global/Default stammen)
Elevated-Gates und Fix-it-Schlüsselpfade

Sandbox: wo Tools ausgeführt werden

Sandboxing wird durch agents.defaults.sandbox.mode gesteuert:

"off": Alles läuft auf dem Host.
"non-main": Nur Nicht-Main-Sessions werden sandboxed (häufige “Überraschung” bei Gruppen/Channels).
"all": Alles wird sandboxed.

Siehe Sandboxing für die vollständige Matrix (Scope, Workspace-Mounts, Images).

Bind-Mounts (Sicherheits-Schnellcheck)

docker.binds durchbricht das Sandbox-Dateisystem: Was du mountest, ist im Container mit dem von dir gesetzten Modus sichtbar (:ro oder :rw).
Standard ist Read-Write wenn du den Modus weglässt; bevorzuge :ro für Quellcode/Secrets.
scope: "shared" ignoriert per-Agent-Binds (nur globale Binds gelten).
Das Binden von /var/run/docker.sock gibt der Sandbox effektiv Host-Kontrolle; mache das nur bewusst.
Workspace-Zugriff (workspaceAccess: "ro"/"rw") ist unabhängig von Bind-Modi.

Tool-Policy: welche Tools existieren/aufrufbar sind

Zwei Ebenen sind relevant:

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/per-Agent-Tool-Policy: tools.allow/tools.deny und agents.list[].tools.allow/agents.list[].tools.deny
Provider-Tool-Policy: tools.byProvider[provider].allow/deny und agents.list[].tools.byProvider[provider].allow/deny
Sandbox-Tool-Policy (gilt nur bei aktiver 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-Policy ist der Hard-Stop: /exec kann ein denied exec-Tool nicht überschreiben.
/exec ändert nur Session-Defaults für autorisierte Sender; es gewährt keinen Tool-Zugriff. Provider-Tool-Keys akzeptieren entweder provider (z. B. google-antigravity) oder provider/model (z. B. openai/gpt-5.2).

Tool-Gruppen (Kurzformen)

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

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

Verfügbare Gruppen:

group:runtime: exec, bash, process
group:fs: read, write, edit, apply_patch
group:sessions: sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
group:memory: memory_search, memory_get
group:ui: browser, canvas
group:automation: cron, gateway
group:messaging: message
group:nodes: nodes
group:openclaw: alle eingebauten OpenClaw-Tools (ohne Provider-Plugins)

Elevated: Exec-only “auf dem Host ausführen”

Elevated gewährt keine zusätzlichen Tools; es betrifft nur exec.

In einer Sandbox führt /elevated on (oder exec mit elevated: true) auf dem Host aus (Genehmigungen können weiterhin gelten).
Verwende /elevated full, um Exec-Genehmigungen für die Session zu überspringen.
Wenn du bereits direkt ausführst, ist Elevated effektiv ein No-Op (trotzdem gated).
Elevated ist nicht Skill-bezogen und überschreibt nicht Tool-Allow/Deny.
/exec ist separat von Elevated. Es passt nur per-Session-Exec-Defaults für autorisierte Sender an.

Gates:

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

Siehe Elevated-Modus.

Häufige “Sandbox-Jail”-Lösungen

”Tool X durch Sandbox-Tool-Policy blockiert”

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

Sandbox deaktivieren: agents.defaults.sandbox.mode=off (oder per-Agent agents.list[].sandbox.mode=off)
Tool innerhalb der Sandbox erlauben:
- Entferne es aus tools.sandbox.tools.deny (oder per-Agent agents.list[].tools.sandbox.tools.deny)
- oder füge es zu tools.sandbox.tools.allow hinzu (oder per-Agent allow)

“Ich dachte, das wäre Main, warum wird es sandboxed?”

Im "non-main"-Modus sind Gruppen-/Channel-Keys nicht Main. Verwende den Main-Session-Key (angezeigt von sandbox explain) oder wechsle den Modus auf "off".