Skip to Content
👋 Willkommen bei HowToUseOpenClaw Schnellstart
GatewaySandbox vs. Tool Policy vs. Elevated

Sandbox vs. Tool Policy vs. Elevated

OpenClaw hat drei zusammenhängende (aber unterschiedliche) Steuerungen:

  1. Sandbox (agents.defaults.sandbox.* / agents.list[].sandbox.*) entscheidet, wo Tools laufen (Docker vs. Host).
  2. Tool Policy (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-exec-Fluchtluke, um auf dem Host zu laufen, wenn Sie gesandboxt sind.

Schnelles Debugging

Den Inspector nutzen, um zu sehen, was OpenClaw tatsächlich tut:

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

Es gibt aus:

  • effektiver Sandbox-Modus/Geltungsbereich/Workspace-Zugriff
  • ob die Sitzung aktuell gesandboxt ist (main vs. non-main)
  • effektive Sandbox-Tool-Allow/Deny (und ob von Agent/Global/Default)
  • Elevated-Gates und Fix-it-Konfigurationsschlüssel

Sandbox: wo Tools laufen

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

  • "off": alles läuft auf dem Host.
  • "non-main": nur Nicht-Haupt-Sitzungen werden gesandboxt (häufige „Überraschung“ bei Gruppen/Kanälen).
  • "all": alles wird gesandboxt.

Vollständige Matrix (Scope, Workspace-Mounts, Images): Sandboxing.

Bind-Mounts (Sicherheits-Schnellcheck)

  • docker.binds durchbohrt das Sandbox-Dateisystem: Was Sie mounten, ist im Container mit der gesetzten Mode (:ro oder :rw) sichtbar.
  • Standard ist read-write, wenn Sie die Mode weglassen; für Source/Geheimnisse :ro bevorzugen.
  • scope: "shared" ignoriert pro-Agent-Binds (nur globale Binds gelten).
  • /var/run/docker.sock zu binden übergibt effektiv die Host-Kontrolle an die Sandbox; nur bewusst nutzen.
  • Workspace-Zugriff (workspaceAccess: "ro"/"rw") ist unabhängig von Bind-Modi.

Tool Policy: welche Tools existieren/aufrufbar sind

Zwei Ebenen zählen:

  • 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/pro-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 (nur bei Sandbox): tools.sandbox.tools.allow/tools.sandbox.tools.deny und agents.list[].tools.sandbox.tools.*

Faustregeln:

  • deny gewinnt immer.
  • Ist allow nicht leer, wird alles andere als blockiert behandelt.
  • Tool-Policy ist die harte Grenze: /exec kann ein verweigertes exec-Tool nicht überschreiben.
  • /exec ändert nur Sitzungs-Standards für autorisierte Absender; 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: nur-exec „auf dem Host laufen“

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

  • Sind Sie gesandboxt, führt /elevated on (oder exec mit elevated: true) auf dem Host aus (Genehmigungen können weiter gelten).
  • /elevated full nutzen, um Exec-Genehmigungen für die Sitzung zu überspringen.
  • Laufen Sie bereits direkt, ist Elevated effektiv ein No-Op (weiterhin abgesichert).
  • Elevated ist nicht skill-scoped und überschreibt nicht Tool-Allow/Deny.
  • /exec ist getrennt von Elevated. Es passt nur pro-Sitzungs-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.

Typische „Sandbox-Jail“-Fixes

„Tool X von Sandbox-Tool-Policy blockiert“

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

  • Sandbox deaktivieren: agents.defaults.sandbox.mode=off (oder pro Agent agents.list[].sandbox.mode=off)
  • Tool in der Sandbox erlauben:
    • aus tools.sandbox.tools.deny entfernen (oder pro-Agent agents.list[].tools.sandbox.tools.deny)
    • oder zu tools.sandbox.tools.allow hinzufügen (oder pro-Agent-Allow)

„Ich dachte, das ist main, warum ist es gesandboxt?“

Im Modus "non-main" sind Gruppen-/Kanal-Keys nicht main. Den Hauptsitzungs-Key nutzen (von sandbox explain angezeigt) oder Modus auf "off" wechseln.

Zuletzt aktualisiert am:
BetriebSandboxing