OpenClaw Approvals erklärt: /approve, Sandboxing und Host-Exec ohne Blindflug

Wenn OpenClaw plötzlich eine Freigabe verlangt, ist selten der Agent defekt. Meist treffen mehrere Sicherheits- und Ausführungsebenen aufeinander: die Sandbox für Tool-Läufe, das mit tools.exec.host gewählte Ausführungsziel, die angeforderte Exec-Policy und das Approvals-Dokument auf dem Host, der den Befehl ausführen soll.

Im Chat wirkt das schnell wie ein einzelner Schalter. Technisch sind es getrennte Entscheidungen. Sandboxing begrenzt Dateisystem- und Prozesszugriffe. Exec-Approvals schützen Host-Befehle auf gateway oder node. Die durchsetzbare Host-Policy liegt auf dem jeweiligen Ausführungshost; OpenClaw leitet daraus zusammen mit der angeforderten tools.exec-Policy das effektive Ergebnis ab.

Nach diesem Walkthrough kannst du unterscheiden, ob ein Befehl an der Sandbox, am Routing, an der Host-Policy, an einem fehlenden Approval-Resolver oder an einem sitzungsspezifischen Override scheitert.

Die grundlegende Struktur der Konfigurationsdatei erklärt Teil 1 der Serie: Gateway-Konfiguration: openclaw.json (JSON5) verständlich erklärt. Für Zugangsdaten und deren Reichweite ist außerdem der Guide zu Secrets und API-Keys mit SecretRef relevant.

Was eine Approval-Anfrage tatsächlich bedeutet

Typische Symptome sind:

• Ein Agent kann Dateien in seiner Sandbox bearbeiten, aber keinen Befehl auf dem Gateway starten.
• Ein Kommando läuft auf dem lokalen Rechner, wird auf einem Node jedoch abgelehnt.
• tools.exec.mode wurde geändert, trotzdem erscheinen weiter Prompts.
• Eine Freigabe wird angefordert, aber ohne sichtbaren Dialog sofort abgelehnt.

Dahinter stehen unterschiedliche Ebenen:

• Sandboxing isoliert Tool-Ausführung wie exec, read, write, edit, apply_patch und process.
• tools.exec.host wählt das Ziel. Bei auto verwendet OpenClaw eine verfügbare Sandbox und fällt andernfalls auf das Gateway zurück.
• Exec-Policy und Approvals entscheiden, ob ein Host-Befehl auf gateway oder node ausgeführt werden darf.
• Approval-Oberflächen stellen die Entscheidung dar. Dazu können Control UI, macOS-App oder eine konfigurierte Weiterleitung in einen Chat gehören. Sie sind nicht die Host-Policy selbst.
• Sitzungsspezifische /exec-Overrides können das Verhalten einer laufenden Session zusätzlich verändern. Diese Overrides erscheinen nicht in openclaw approvals get.

Eine sichtbare /approve-Anfrage bedeutet, dass ein konkreter Host-Befehl noch eine Entscheidung benötigt. Bleibt die Oberfläche unerreichbar, greift der konfigurierte Fallback.

Sandboxing betrifft Tools, nicht den Gateway-Prozess

Sandboxing ist eine optionale Isolationsschicht. Verwende für die hier gezeigte globale Konfiguration den vom aktuellen Runtime-Schema bestätigten Pfad agents.defaults.sandbox. Ein Konfigurationsblock unter agents.entries gehört nicht zu diesem Schema. Der Gateway-Prozess bleibt auf dem Host; nur die Tool-Ausführung wechselt in die konfigurierte Sandbox.

Eine globale Konfiguration kann beispielsweise so aussehen:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "agent",
        backend: "docker"
      }
    }
  }
}

agents.defaults.sandbox, agents.defaults.sandbox.mode, scope und backend gehören zum aktuellen Runtime-Schema. Das Beispiel aktiviert eine Docker-Sandbox für Nicht-Main-Sessions und verwendet eine Sandbox-Umgebung pro Agent.

Starte den Gateway nach einer Änderung neu:

openclaw gateway restart

Erwartetes Ergebnis: Die kanonische Main-Session läuft bei mode: "non-main" weiterhin außerhalb der Sandbox. Gruppen-, Channel- und andere Nicht-Main-Sessions verwenden die konfigurierte Sandbox. Fehlt mode, gilt der Standardwert off.

Die drei Sandbox-Modi sind:

• off: Tool-Ausführung wird nicht gesandboxt.
• non-main: Alle Sessions außer der kanonischen Main-Session des Agenten werden gesandboxt.
• all: Jede Session des Agenten wird gesandboxt.

Bei non-main zählt nicht, ob du eine Session umgangssprachlich als Haupt- oder Nebensession bezeichnest. OpenClaw erkennt die Main-Session am kanonischen Schlüssel agent:<agentId>:main; bei globalem Session-Scope gilt global. Dieser Schlüssel ist für die Sandbox-Entscheidung nicht konfigurierbar. Gruppen- und Channel-Sessions besitzen andere Schlüssel und zählen daher als Nicht-Main-Sessions.

Sandboxing ist keine perfekte Sicherheitsgrenze. Es reduziert aber den erreichbaren Dateisystem- und Prozessbereich, wenn ein Modell einen ungeeigneten Befehl erzeugt. Auch ein Browser kann separat gesandboxt werden.

Elevated-Exec ist eine ausdrückliche Ausnahme: Es führt außerhalb der Sandbox über den konfigurierten Escape-Pfad aus. Bei Elevated full können zudem die normalen Exec-Approvals übersprungen werden. Das ist eine Break-Glass-Funktion, keine Standardlösung für störende Prompts.

Exec-Approvals gelten auf dem Ausführungshost

Exec-Approvals schützen Befehle auf einem echten Host:

• Auf dem Gateway-Host setzt der dort laufende openclaw-Prozess die Policy durch.
• Auf einem Node setzt der Node-Runner die Policy durch, etwa eine Companion-App oder ein Headless-Node.

Ein lokal geänderter Wert lockert daher nicht automatisch das Gateway oder einen Node. Umgekehrt kann ein hostlokales ask: "always" weitere Prompts erzwingen, obwohl die Session oder die angeforderte Config nur ask: "on-miss" vorsieht.

Hostnative Nodes können ihre Policy in einer anderen Form bereitstellen. Übertrage deshalb kein Gateway-Dokument blind auf einen Node. Prüfe zuerst die Antwort des konkreten Ziels und bearbeite nur ein für diesen Host passendes, vollständiges Dokument. Einrichtung und Pairing behandelt der Serienbeitrag OpenClaw Remote Nodes sicher einrichten.

Exec-Approvals sind weder Mehrbenutzer-Authentifizierung noch Read-only-Isolation. Ein genehmigter Befehl kann Dateien und Dienste im Rahmen der Rechte des Zielhosts verändern.

Diagnose: Welche Policy greift?

Führe die folgenden Schritte auf einem Rechner aus, dessen OpenClaw-CLI Zugriff auf das betreffende Gateway beziehungsweise den Node hat. Für Remote-Ziele können Gateway-URL, Token oder eine bestehende Paarung erforderlich sein.

1. Gewünschtes Verhalten festlegen

Kläre vor der Änderung, welches Ergebnis du brauchst. Ein Analysejob kann vollständig in der Sandbox bleiben. Ein Wartungsskript benötigt vielleicht nur zwei festgelegte Programme auf dem Gateway. Bei neuen Befehlsformen kann eine menschliche Freigabe oder der automatische Reviewer sinnvoll sein. Voller Host-Exec gehört auf einen ausdrücklich vertrauenswürdigen Host.

Damit kannst du später prüfen, ob die effektive Policy wirklich zum vorgesehenen Betrieb passt.

2. Lokale Policy prüfen

Zeige zuerst das lokale Approvals-Dokument:

openclaw approvals get

Prüfe anschließend die lokale Zusammenführung aus angeforderter Config und lokalem Approvals-Zustand:

openclaw exec-policy show

openclaw exec-policy show ist lokal-only. Der Befehl zeigt nicht automatisch die effektive Policy eines entfernten Gateways oder Nodes.

Erwartetes Ergebnis: Die Ausgabe nennt die angeforderte tools.exec-Policy, die lokale Host-Regel und das daraus abgeleitete lokale Ergebnis.

Wenn weiterhin Prompts erscheinen: Prüfe zusätzlich einen möglichen /exec-Override der laufenden Session. Er ist nicht Bestandteil von approvals get.

3. Gateway und Nodes getrennt abfragen

Für das Gateway verwendest du:

openclaw approvals get --gateway

Für jeden betroffenen Node verwendest du:

openclaw approvals get --node <id|name|ip>

Erwartetes Ergebnis: Jede Abfrage liefert die Policy des ausdrücklich gewählten Hosts. Unterschiede zwischen lokaler Maschine, Gateway und Node sind in einem verteilten Setup möglich und nicht automatisch ein Fehler.

Schlägt nur der Node-Befehl fehl, ändere nicht zuerst die lokale Policy. Prüfe die Node-Antwort, die Paarung und den tatsächlichen Exec-Host.

4. Exec-Ziel kontrollieren

Der Approval-Modus entscheidet nicht, wo ein Befehl läuft. Das Ziel kommt aus tools.exec.host:

• sandbox: Ausführung in der Sandbox
• gateway: Ausführung auf dem Gateway
• node: Ausführung auf dem ausgewählten Node
• auto: Sandbox, wenn verfügbar, andernfalls Gateway

tools.exec.host ist mit diesen vier Werten im aktuellen Runtime-Schema vorhanden. Wenn du eine Gateway-Policy änderst, der Befehl tatsächlich auf einem Node läuft, bleibt der Fehler bestehen. Kontrolliere deshalb Ziel und Policy gemeinsam.

5. Fehlende Approval-Oberfläche erkennen

Ist eine Rückfrage nötig, aber kein Resolver erreichbar, greift askFallback. Ohne abweichende Konfiguration ist der sichere Fallback deny.

Erwartetes Verhalten: Der Befehl wird abgelehnt, statt ohne Freigabe weiterzulaufen.

Das ist häufig kein Defekt im Chat. Prüfe, ob Control UI, Companion-App oder die konfigurierte Approval-Weiterleitung erreichbar ist. Soll der Workflow ohne menschlichen Dialog laufen, verwende eine passende Allowlist oder den Modus auto, statt den Fallback pauschal zu öffnen.

Die fünf Host-Exec-Modi

tools.exec.mode ist der aktuelle normalisierte Config-Pfad für die Host-Exec-Policy. Das Runtime-Schema akzeptiert diese Werte:

• deny: Host-Exec vollständig blockieren
• allowlist: Nur Allowlist-Treffer ausführen, andere Befehle ohne Prompt ablehnen
• ask: Allowlist-Treffer ausführen und bei Misses einen Menschen fragen
• auto: Allowlist-Treffer ausführen, Misses automatisch prüfen und bei Bedarf an einen Menschen eskalieren
• full: Host-Exec ohne Approval-Prompts zulassen

Die aktuelle OpenClaw-Dokumentation empfiehlt auto für Coding-Sessions, die praktischen Host-Zugriff mit einer Prüfung neuer Befehlsformen verbinden sollen. Lokal setzt du den Modus so:

openclaw config set tools.exec.mode auto
openclaw approvals get
openclaw gateway restart
openclaw exec-policy show

Erwartetes Ergebnis: Nach dem Neustart zeigt openclaw exec-policy show die lokal angeforderte Policy und die effektive Zusammenführung. Bleibt die Host-Regel strenger, wird sie durch die Config-Änderung nicht gelockert.

Recovery ohne pauschalen YOLO-Modus

Bekannte Befehle gezielt erlauben

Wenn ein Workflow wiederholt dasselbe vertrauenswürdige Programm benötigt, ergänze die Allowlist:

openclaw approvals allowlist add "~/Projects/**/bin/rg"

Für einen bestimmten Agenten auf einem Node:

openclaw approvals allowlist add --agent main --node <id|name|ip> "/usr/bin/uptime"

Prüfe danach den betroffenen Host erneut:

openclaw approvals get --node <id|name|ip>

Erwartetes Ergebnis: Der neue Eintrag erscheint in der Allowlist des gewählten Agenten und Hosts. Befehle außerhalb dieses Musters bleiben von der bestehenden Policy abhängig.

Verwende enge Pfade. Eine breite Wildcard kann mehr ausführbare Dateien erfassen als beabsichtigt.

Lokale Presets kontrolliert einsetzen

Für die lokale Maschine stellt openclaw exec-policy synchronisierte Presets bereit:

openclaw exec-policy preset cautious
openclaw exec-policy show

Das Preset cautious setzt eine vorsichtige lokale Kombination. Wenn du auf einem vollständig vertrauenswürdigen lokalen Host bewusst alle Approval-Stopps entfernen willst, existiert außerdem:

openclaw exec-policy preset yolo
openclaw exec-policy show

Beide Presets sind lokal-only. Sie ändern weder die Approvals eines entfernten Gateways noch die eines Nodes. Für einen vollständigen Stopp von Host-Exec steht außerdem das Preset deny-all bereit.

Remote-Policy nur als vollständiges Dokument ersetzen

Für Gateway und Nodes unterstützt die CLI openclaw approvals set --gateway beziehungsweise openclaw approvals set --node. set ersetzt jedoch das vollständige Approvals-Dokument des Ziels. Ein Minimaldokument kann bestehende Agentenregeln oder Allowlist-Einträge entfernen.

Gehe deshalb so vor:

1. Lies die aktuelle Policy mit openclaw approvals get --gateway --json oder der passenden --node-Abfrage.
2. Bewahre die unveränderte Ausgabe beziehungsweise das bestehende Host-Dokument als Recovery-Referenz auf.
3. Prüfe Format, Agentenabschnitte und Allowlist-Einträge des Zielhosts.
4. Bearbeite eine vollständige Kopie und übergib sie mit openclaw approvals set --file <pfad> und der passenden Zieloption an genau diesen Host.
5. Wiederhole anschließend openclaw approvals get --gateway beziehungsweise openclaw approvals get --node <id|name|ip>.

Übertrage ein Dokument nur, wenn es zum Zielhost und dessen Policy-Format passt. Besonders bei hostnativen Nodes ist eine Gateway-Vorlage keine verlässliche Ausgangsbasis.

Wenn eine Änderung scheinbar nichts bewirkt

Arbeite diese Reihenfolge ab:

1. Prüfe mit tools.exec.host, wo der Befehl laufen soll.
2. Frage genau diesen Host mit approvals get, --gateway oder --node ab.
3. Verwende exec-policy show nur für die lokale Zusammenführung.
4. Prüfe auf dem Ausführungshost eine strengere Regel wie ask: "always".
5. Kontrolliere den /exec-Override der aktuellen Session separat.
6. Prüfe bei fehlender Rückfrage askFallback und die erreichbare Approval-Oberfläche.
7. Unterscheide einen Sandbox-Deny von einem Host-Approval-Deny.

Ein erfolgreicher Sandbox-Befehl belegt nicht, dass Host-Exec erlaubt ist. Eine offene Host-Policy schaltet die Sandbox ebenfalls nicht aus.

Sicherheitscheck vor full

Vor Host-Exec ohne Prompts muss das Ausführungsziel feststehen. Prüfe, mit welchen Betriebssystemrechten der Runner arbeitet und welche Projekt-, Secret- oder Produktionsdateien er erreichen kann. Halte außerdem eine geprüfte Kopie der bisherigen Approvals bereit, damit du die Änderung zurücknehmen kannst.

Wenn das Ausführungsziel noch unklar ist, ist full verfrüht. Nutze zunächst auto, ask oder eine enge Allowlist.

Was Approvals nicht ersetzen

Exec-Approvals ersetzen keine Host-Härtung, Dateirechte, Secret-Hygiene oder Trennung von Test- und Produktivsystemen. Zusätzliche Berechtigungen eines IDE- oder ACPX-Harness bilden ebenfalls eine eigene Ebene und heben OpenClaws Host-Policy nicht auf.

Elevated-Exec bleibt davon getrennt. Es umgeht die Sandbox, und Elevated full kann normale Exec-Approvals überspringen. Verwende es nur für einen ausdrücklich vorgesehenen Escape-Pfad.

Betriebs-Checkliste

• Lokal: openclaw approvals get
• Lokale Zusammenführung: openclaw exec-policy show
• Gateway: openclaw approvals get --gateway
• Jeder betroffene Node: openclaw approvals get --node <id|name|ip>
• Exec-Ziel mit tools.exec.host prüfen
• agents.defaults.sandbox.mode und tatsächlichen Session-Typ abgleichen
• /exec-Session-Override separat kontrollieren
• Bei unsichtbaren Prompts askFallback und Approval-Oberfläche prüfen
• Vor approvals set das vollständige Zieldokument sichern und erhalten
• Elevated-Exec nicht als normale Prompt-Reparatur verwenden

Kernpunkte

agents.defaults.sandbox konfiguriert den globalen isolierten Arbeitsraum. tools.exec.host bestimmt das Ausführungsziel. Die Host-Policy entscheidet auf Gateway oder Node, ob der Befehl laufen darf. Approval-Oberflächen vermitteln die Entscheidung, und eine Session kann zusätzlich einen eigenen /exec-Override besitzen.

Wenn du diese Ebenen einzeln prüfst, lässt sich eine /approve-Schleife auf die tatsächlich zuständige Policy eingrenzen.