Sandbox vs Tool Policy vs Elevated

OpenClaw hat drei verwandte (aber unterschiedliche) Steuerungsmechanismen:

  1. Sandbox (agents.defaults.sandbox.* / agents.list[].sandbox.*) bestimmt, wo Tools laufen (Docker vs Host).
  2. Tool Policy (tools.*, tools.sandbox.tools.*, agents.list[].tools.*) bestimmt, welche Tools verfügbar/erlaubt sind.
  3. Elevated (tools.elevated.*, agents.list[].tools.elevated.*) ist ein exec-only Notausgang, um auf dem Host zu laufen, wenn du in der Sandbox bist.

Schnelles Debugging

Mit dem Inspector siehst du, was OpenClaw tatsächlich macht:

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

Die Ausgabe zeigt:

  • effektiver Sandbox-Modus/Scope/Workspace-Zugriff
  • ob die Session gerade sandboxed ist (main vs non-main)
  • effektive Sandbox-Tool-Allow/Deny-Regeln (und woher sie kommen: Agent/Global/Default)
  • Elevated-Gates und Fix-it-Key-Pfade

Sandbox: Wo Tools laufen

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

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

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

Bind Mounts (kurzer Sicherheitscheck)

  • docker.binds durchbricht das Sandbox-Dateisystem: Alles, was du mountest, ist im Container mit dem von dir gesetzten Modus (:ro oder :rw) sichtbar.
  • 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).
  • /var/run/docker.sock zu binden gibt der Sandbox effektiv Host-Kontrolle; mach das nur absichtlich.
  • Workspace-Zugriff (workspaceAccess: "ro"/"rw") ist unabhängig von Bind-Modi.

Tool Policy: Welche Tools existieren/aufrufbar sind

Zwei Ebenen sind wichtig:

  • Tool Profile: tools.profile und agents.list[].tools.profile (Basis-Allowlist)
  • Provider Tool Profile: 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 wenn sandboxed): 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.
  • Tool Policy ist der harte Stopp: /exec kann ein abgelehntes 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 laufen”

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

  • Wenn du sandboxed bist, läuft /elevated on (oder exec mit elevated: true) auf dem Host (Genehmigungen können trotzdem erforderlich sein).
  • Mit /elevated full überspringst du Exec-Genehmigungen für die Session.
  • Wenn du bereits direkt läufst, ist Elevated effektiv ein No-Op (trotzdem gated).
  • Elevated ist nicht skill-scoped und überschreibt nicht Tool-Allow/Deny.
  • /exec ist getrennt 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>)

Schau dir Elevated Mode an.

Häufige “Sandbox-Jail”-Fixes

”Tool X blocked by sandbox tool policy”

Fix-it-Keys (wähle einen):

  • Sandbox deaktivieren: agents.defaults.sandbox.mode=off (oder per-Agent agents.list[].sandbox.mode=off)
  • Das Tool in 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 ist es sandboxed?”

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