OpenClaw Sandbox, Tool Policy und Elevated verstehen

Kennst du das? Du versuchst ein Skript auszuführen, aber plötzlich blockiert eine Permission-Wall deinen Workflow. Entweder ist die Umgebung so offen, dass du dir Sorgen um die Sicherheit machst, oder sie ist so restriktiv, dass kein Tool mehr funktioniert. Die Balance zwischen Sicherheit und Produktivität zu finden, ist oft frustrierend.

OpenClaw löst das mit drei verschiedenen Mechanismen. Hier erfährst du, wie du Sandbox, Tool Policy und Elevated Mode richtig einsetzt, damit deine Agenten genau das tun, was sie sollen.

Voraussetzungen

• Eine laufende OpenClaw-Instanz
• Zugriff auf die Konfigurationsdateien (agents.defaults oder agents.list)

Schnellstart

Wenn du wissen willst, was OpenClaw gerade im Hintergrund entscheidet, ist der Inspector dein bester Freund. Nutze diesen Befehl, um die aktuelle Konfiguration zu prüfen:

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

Die Ausgabe zeigt dir sofort:

• Den effektiven Sandbox-Modus und Workspace-Zugriff.
• Ob die aktuelle Session sandboxed ist.
• Welche Tools erlaubt oder abgelehnt sind.
• Den Status der Elevated-Gates.

Sandbox: Wo Tools laufen

Die Sandbox bestimmt den Ort der Ausführung. Gesteuert wird das über agents.defaults.sandbox.mode. Ich empfehle, hier genau hinzusehen, da der Modus "non-main" oft für Überraschungen in Gruppen oder Channels sorgt.

• "off": Alles läuft direkt auf dem Host.
• "non-main": Nur Sessions, die nicht “main” sind, landen in der Sandbox.
• "all": Komplette Isolation für alles.

Bind Mounts und Sicherheit

Mit docker.binds kannst du das Dateisystem der Sandbox gezielt öffnen.

• Standardmäßig ist der Zugriff read-write, wenn du den Modus weglässt. Nutze lieber :ro für Quellcode oder Secrets.
• Falls scope: "shared" aktiv ist, werden agent-spezifische Binds ignoriert.
• Vorsicht: Wenn du /var/run/docker.sock mountest, gibst du der Sandbox effektiv die Kontrolle über deinen Host.

Tool Policy: Welche Tools erlaubt sind

Hier entscheidest du, welche Tools überhaupt aufgerufen werden dürfen. Es gibt verschiedene Ebenen, von globalen Profilen bis hin zu provider-spezifischen Regeln.

Wichtige Regeln für die Konfiguration:

• deny gewinnt immer.
• Wenn allow nicht leer ist, wird alles andere automatisch blockiert.
• Tool Policies sind hart: Ein /exec kann kein Tool erzwingen, das per Policy verboten ist.

Tool Groups

Statt jedes Tool einzeln aufzulisten, kannst du Gruppen nutzen. Das spart Zeit und hält die Config sauber:

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

Verfügbare Gruppen sind zum Beispiel group:runtime (für exec, bash, process) oder group:fs (für read, write, edit, apply_patch). Mit group:openclaw erlaubst du alle eingebauten Tools auf einmal.

Elevated: Der Host-Escape für exec

Elevated ist kein Freifahrtschein für alle Tools. Es beeinflusst ausschließlich den exec-Befehl. Wenn du in einer Sandbox feststeckst, aber einen Befehl auf dem Host ausführen musst, ist dies dein Weg nach draußen.

• /elevated on: Schaltet den Host-Zugriff für exec ein (Genehmigungen können trotzdem nötig sein).
• /elevated full: Überspringt zusätzlich die Approvals für die Session.
• Elevated überschreibt keine Tool-Allowlists oder Denylists.

Damit das funktioniert, musst du die Gates in der Config öffnen:

• tools.elevated.enabled: Muss auf true stehen.
• tools.elevated.allowFrom.<provider>: Hier definierst du, wer diesen Modus nutzen darf.

Fehlerbehebung

”Tool X blocked by sandbox tool policy”

Das ist ein klassisches Konfigurationsproblem. Du hast zwei Möglichkeiten:

1. Deaktiviere die Sandbox mit agents.defaults.sandbox.mode=off.
2. Erlaube das Tool explizit innerhalb der Sandbox, indem du es zu tools.sandbox.tools.allow hinzufügst oder aus tools.sandbox.tools.deny entfernst.

”Warum ist diese Session sandboxed?”

In "non-main" Modus sind Keys für Gruppen oder Channels nicht als “main” markiert. Nutze openclaw sandbox explain, um den Session-Key zu prüfen. Wenn du dort volle Freiheit brauchst, wechsel zu mode: "off".

Du hast spezifische Fragen zu deinem Setup? Nutze den AI Setup Assistant.

Nächste Schritte

• Sandboxing Details
• Elevated Mode Guide