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 getrennte 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 über Host-Befehle auf gateway oder node. Control UI, Companion-App oder eine konfigurierte Chat-Weiterleitung stellen die Entscheidung dar, sind aber nicht selbst die Host-Policy. Sitzungsspezifische /exec-Overrides können das Verhalten zusätzlich verändern und erscheinen nicht in openclaw approvals get.

Eine sichtbare /approve-Anfrage bedeutet, dass ein konkreter Vorgang noch eine Entscheidung benötigt. Prüfe die angezeigte ID, den Befehl, seine Argumente, das Arbeitsverzeichnis und den Ausführungshost. Verwende anschließend genau die Optionen, die der aktuelle Prompt anbietet:

/approve <id> allow-once
/approve <id> allow-always
/approve <id> deny

allow-once autorisiert ausschließlich die konkrete Pending-Anfrage für eine Ausführung. Eine später geänderte oder neu gestellte Anfrage benötigt eine eigene Entscheidung. Erfinde keine ID und übertrage keine ID aus einem älteren Prompt.

allow-always erzeugt eine dauerhafte Freigabe gemäß dem im Prompt ausgewiesenen Scope. Prüfe vor der Bestätigung den Ausführungshost, den betroffenen Agenten, den Match- beziehungsweise Allowlist-Umfang und die Persistenz. Leite aus der Bezeichnung keine pauschale Bindung an exakte Befehlsargumente oder das aktuelle Arbeitsverzeichnis ab; maßgeblich ist der tatsächlich angezeigte Freigabeumfang.

Für Automations-Anfragen gilt ein separater Sonderfall: allow-always kann einen Standing Grant für die jeweilige Automation erzeugen. Prüfe dessen ausgewiesene Laufzeit. Beim Auflösen über die CLI lässt sich die Grant-Laufzeit mit --expires-in-days <days> ausdrücklich festlegen, statt allein den konfigurierten Standard zu verwenden.

deny lehnt die Pending-Anfrage ab. Bleibt die Approval-Oberfläche unerreichbar, greift der konfigurierte Fallback.

Offene Anfragen über die CLI auflösen

Der CLI-Fallback benötigt Zugriff auf das Gateway und passende Operator-Berechtigungen. Für eine vollständige Auflistung sowie den zugehörigen operatorweiten Resolve-Ablauf ist operator.admin erforderlich, weil Approval-Datensätze sonst nach Requester und Reviewer gefiltert bleiben können. Das Auflösen verlangt zusätzlich den dedizierten Scope operator.approvals.

Mit einem entsprechend berechtigten Token listest du offene Anfragen auf:

openclaw approvals pending
openclaw approvals pending --json

Vergleiche den vollständigen Datensatz und kopiere die vollständige ID der richtigen Anfrage. Löse ausschließlich diesen Eintrag auf:

openclaw approvals resolve <id> allow-once
# oder, nur wenn ausdrücklich beabsichtigt und angeboten:
openclaw approvals resolve <id> allow-always
# oder zum Ablehnen:
openclaw approvals resolve <id> deny --reason "Unerwarteter Befehl"

Verifikation: openclaw approvals pending darf die aufgelöste ID nicht mehr als offen führen. Starte danach den ursprünglich blockierten Befehl in der betroffenen Session erneut. Erst dessen Ergebnis zeigt, ob du die richtige Anfrage für den richtigen Host aufgelöst hast.

Fehlt eine erwartete ID, bedeutet eine leere oder verkürzte Liste nicht zwangsläufig, dass keine Anfrage existiert. Prüfe die Rollen des verwendeten Tokens, operator.admin, die Requester-/Reviewer-Filter und den Approval-Scope. Verweigert approvals resolve die Entscheidung, kontrolliere zusätzlich operator.approvals und ob das Token den betroffenen Datensatz auflösen darf.

Sandboxing betrifft Tools, nicht den Gateway-Prozess

Sandboxing ist eine optionale Isolationsschicht. Verwende für globale Vorgaben den Pfad agents.defaults.sandbox. Einzelne Agenten können diese Vorgaben über agents.entries.*.sandbox überschreiben; die agentenspezifischen Werte haben dann Vorrang. Der Gateway-Prozess bleibt auf dem Host. Nur die Tool-Ausführung wechselt in die wirksame Sandbox.

Voraussetzung für das Docker-Beispiel

Das folgende Beispiel setzt ein installiertes, von der aktuellen OpenClaw-Version unterstütztes und laufendes Docker-Backend voraus. Prüfe vor der Konfigurationsänderung die offizielle Docker-Backend-Dokumentation und die Matrix der unterstützten Sandbox-Fähigkeiten. Dort stehen die Anforderungen und Einschränkungen der jeweiligen Plattform.

Wenn Docker nicht erreichbar ist oder die benötigten Fähigkeiten auf dem Host fehlen, erzeugt ein erfolgreicher Gateway-Neustart noch keine nutzbare Docker-Sandbox. Behebe dann die Backend-Voraussetzung, statt die Exec-Policy zu lockern.

Eine globale Konfiguration kann 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 fordert eine Docker-Sandbox für Nicht-Main-Sessions an und verwendet eine Sandbox-Umgebung pro Agent.

Starte den Gateway nach der Änderung neu:

openclaw gateway restart

Der Neustart bestätigt nur, dass der Gateway wieder läuft. Prüfe die Sandbox anschließend mit einem echten Toollauf: Öffne eine Nicht-Main-Session, etwa eine Channel- oder Gruppensession, und lasse dort einen harmlosen Exec-Befehl wie pwd ausführen. Kontrolliere im Toollauf beziehungsweise in den Gateway-Diagnosedaten, dass das Ausführungsziel als Sandbox, das Backend als Docker und eine konkrete Sandbox- oder Container-Instanz ausgewiesen werden.

Erfolgskriterium: Der Nicht-Main-Toollauf startet tatsächlich in der Docker-Sandbox. Zeigt die Diagnose gateway, meldet sie ein nicht verfügbares Backend oder entsteht keine Sandbox-Instanz, ist die Einrichtung noch nicht erfolgreich. Prüfe dann Docker-Dienst, Plattformunterstützung, Backend-Fehler und agentenspezifische Sandbox-Overrides.

Bei mode: "non-main" bleibt die kanonische Main-Session außerhalb der Sandbox. Fehlt mode, gilt off. Die verfügbaren 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 der kanonische Session-Schlüssel. OpenClaw erkennt die Main-Session an agent:<agentId>:main; bei globalem Session-Scope gilt global. Gruppen- und Channel-Sessions besitzen andere Schlüssel und zählen daher als Nicht-Main-Sessions.

Sandboxing ist keine perfekte Sicherheitsgrenze. Es reduziert jedoch den erreichbaren Dateisystem- und Prozessbereich, wenn ein Modell einen ungeeigneten Befehl erzeugt. 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. Elevated full überspringt normale Exec-Approvals nur, wenn Elevated für Session und Provider verfügbar und freigegeben ist und sowohl die angeforderte Exec-Policy als auch die Host-Policy security=full und ask=off zulassen. Das ist eine Break-Glass-Funktion und keine normale Reparatur 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 übernimmt das der Node-Runner, etwa eine Companion-App oder ein Headless-Node.

Ein lokal geänderter Wert lockert deshalb 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 kein Gateway-Dokument blind auf einen Node. Prüfe die Antwort des konkreten Ziels und bearbeite nur ein für diesen Host geeignetes, vollständiges Dokument. Einrichtung und Pairing behandelt der Beitrag 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 das benötigte Ergebnis. Ein Analysejob kann vollständig in der Sandbox bleiben. Ein Wartungsskript benötigt vielleicht nur /usr/bin/uptime auf einem Node. 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 zum vorgesehenen Betrieb passt.

2. Lokale Policy prüfen

Zeige den lokalen Policy-Snapshot:

openclaw approvals get

openclaw approvals get zeigt die angeforderte tools.exec-Policy, die Policy-Quelle des Zielhosts und das daraus ermittelte effektive Ergebnis. Sitzungsspezifische /exec-Overrides sind darin nicht enthalten.

Für eine kompakte lokale Diagnose derselben Policy-Ebenen verwendest du:

openclaw exec-policy show

openclaw exec-policy show arbeitet lokal. Der Befehl zeigt lokale Config-Policy, Host-Approvals und deren effektive Zusammenführung, aber nicht automatisch die 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.

Erscheinen weiterhin Prompts, sende /exec als eigenen Chat-Befehl in genau der betroffenen Session. Die Antwort zeigt deren aktuelle Defaults. Gleiche Host und Modus mit tools.exec.host, tools.exec.mode und dem zielbezogenen Snapshot aus approvals get ab. Eine Prüfung in einer anderen Session beschreibt den Fehlerfall nicht zuverlässig.

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.

Schlägt nur der Node-Befehl fehl, ändere nicht 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 Werten im aktuellen Runtime-Schema vorhanden. Änderst du die Gateway-Policy, während der Befehl auf einem Node läuft, bleibt der Fehler bestehen. Kontrolliere 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.

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:

• deny: Host-Exec vollständig blockieren
• allowlist: Nur Allowlist-Treffer ausführen und 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 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:

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.

War der Eintrag nur für einen Test oder eine einmalige Reparatur gedacht, entferne exakt das ergänzte Muster:

openclaw approvals allowlist remove "~/Projects/**/bin/rg"
openclaw approvals get

Für das Node-Beispiel bleiben Agent und Ziel identisch:

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

Rollback-Prüfung: Der zielbezogene Snapshot darf nur den entfernten Eintrag nicht mehr enthalten. Andere Agentenregeln und Allowlist-Muster müssen unverändert bleiben.

Normalisierten Modus statt unbelegter Presets verwenden

Verwende für nachvollziehbare Änderungen den dokumentierten Config-Pfad tools.exec.mode mit einem der Werte deny, allowlist, ask, auto oder full. Kontrolliere die lokale Wirkung mit openclaw approvals get und openclaw exec-policy show.

Ein lokaler Config-Wert ändert keine entfernte Node-Policy. Prüfe Gateway und Nodes weiterhin mit den zielbezogenen approvals get-Aufrufen.

Vollständigen Policy-Ersatz vermeiden

Das vollständige Ersetzen einer Approvals-Policy ist kein normaler Reparaturschritt für einen blockierten Befehl. Die Dokumentform kann sich zwischen Gateway, dateibasierten Nodes und hostnativen Nodes unterscheiden. Ein unvollständiger Ersatz kann vorhandene Agentenregeln oder Allowlist-Einträge verlieren.

Nutze für ein vertrauenswürdiges Programm die gezeigten Allowlist-Helfer. Eine komplette Policy-Migration gehört in ein separates Wartungsfenster mit hostgerechtem Backup, der aktuellen CLI-Dokumentation für dieses Ziel und einer anschließenden zielbezogenen Kontrolle.

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 betroffenen Session separat.
6. Prüfe bei fehlender Rückfrage askFallback und die Approval-Oberfläche.
7. Kontrolliere bei fehlenden Pending-IDs oder Resolve-Denials Token-Rollen und Approval-Scope.
8. Unterscheide einen Sandbox-Deny von einem Host-Approval-Deny.

Ein erfolgreicher Sandbox-Befehl zeigt nicht, dass Host-Exec erlaubt ist. Eine offene Host-Policy schaltet die Sandbox ebenfalls nicht aus. Ebenso bestätigt ein Gateway-Neustart nicht, dass ein konfiguriertes Docker-Backend tatsächlich einen Toollauf übernommen hat.

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 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 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 eine eigene Ebene und heben OpenClaws Host-Policy nicht auf.

Elevated-Exec bleibt davon getrennt. Es umgeht die Sandbox; Elevated full überspringt normale Exec-Approvals aber nur bei freigegebenem Elevated-Zugriff und wenn angeforderte Exec-Policy und Host-Policy bereits security=full mit ask=off zulassen. 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
• Docker-Verfügbarkeit und einen realen Nicht-Main-Sandbox-Lauf kontrollieren
• /exec-Session-Override separat prüfen
• Bei unsichtbaren Prompts askFallback und Approval-Oberfläche untersuchen
• Bei fehlenden IDs oder Resolve-Denials operator.admin, operator.approvals und Scope prüfen
• Vollständigen Policy-Ersatz nicht als Schnellreparatur verwenden
• 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 ein Befehl laufen darf. Approval-Oberflächen vermitteln die Entscheidung, und eine Session kann zusätzlich einen eigenen /exec-Override besitzen.

allow-once gilt für die konkrete Pending-Anfrage. allow-always erzeugt eine dauerhafte Freigabe gemäß dem im Prompt ausgewiesenen Scope. Prüfe dafür Host, Agent, Match- beziehungsweise Allowlist-Umfang und Persistenz. Automations-Anfragen können stattdessen einen Standing Grant mit eigener Laufzeit erzeugen.

Eine Docker-Konfiguration ist erst betriebsbereit, wenn das Backend unterstützt, erreichbar und laufend ist und ein tatsächlicher Nicht-Main-Toollauf in einer ausgewiesenen Docker-Sandbox startet. So lassen sich Approval-Schleifen und Sandbox-Fehler auf die zuständige Ebene eingrenzen.