Exec Approvals einrichten: Kontrolle für deine Agent-Befehle

Du kennst das Problem: Du gibst einem KI-Agenten Zugriff auf dein Terminal, und plötzlich führt er Befehle in einer Sandbox aus, die eigentlich auf deinem echten System landen sollen. Es ist ein ständiger Balanceakt zwischen der Geschwindigkeit von Automatisierungen und der Sorge, dass ein Agent ohne Aufsicht kritische Änderungen an deinem Host vornimmt.

Man möchte die Effizienz der Agenten nutzen, braucht aber eine verlässliche Bremse, bevor ein Befehl tatsächlich ausgeführt wird. Genau hier kommen Exec Approvals ins Spiel. Sie dienen als Schutzschaltung, damit Befehle nur dann laufen, wenn Policy, Allowlist und deine manuelle Freigabe übereinstimmen.

Voraussetzungen

• Einen laufenden Gateway oder Node Host.
• Zugriff auf das lokale Dateisystem des Hosts.
• Die macOS Companion App (für UI-Bestätigungen).

Schnellstart

In fünf Minuten setzt du die Grundkonfiguration für deine Exec Approvals auf.

1. Navigiere auf deinem Execution Host zum Verzeichnis ~/.openclaw/.
2. Erstelle oder öffne die Datei exec-approvals.json.
3. Definiere deine Sicherheitsregeln. Die Policy ist immer der striktere Wert aus den tools.exec.* Einstellungen und deinen Approvals-Defaults.
4. Nutze das folgende Schema für deine Konfiguration:

{
  "version": 1,
  "socket": {
    "path": "~/.openclaw/exec-approvals.sock",
    "token": "base64url-token"
  },
  "defaults": {
    "security": "deny",
    "ask": "on-miss",
    "askFallback": "deny",
    "autoAllowSkills": false
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "askFallback": "deny",
      "autoAllowSkills": true,
      "allowlist": [
        {
          "id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",
          "pattern": "~/Projects/**/bin/rg",
          "lastUsedAt": 1737150000000,
          "lastUsedCommand": "rg -n TODO",
          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
        }
      ]
    }
  }
}

Die Approvals werden lokal erzwungen. Auf einem Gateway übernimmt dies der openclaw Prozess, auf einem Node Host der Node Runner. Wenn du macOS nutzt, leitet der Node Host Service den Befehl system.run per lokalem IPC an die macOS App weiter, damit du ihn in der UI bestätigen kannst.

Fehlerbehebung

Hier sind Lösungen für Probleme, die bei der Verwendung von Exec Approvals auftreten können:

• Die Companion App UI erscheint nicht: Wenn die UI nicht verfügbar ist, greift automatisch der ask fallback. Standardmäßig ist dieser auf deny gesetzt, wodurch die Anfrage abgelehnt wird.
• Befehl wird trotz Freigabe blockiert: Das System prüft den Kontext. Wenn sich ein gebundenes Skript nach deiner Freigabe, aber vor der eigentlichen Ausführung ändert (Drift), wird der Run verweigert.
• Berechtigungsfehler auf dem Gateway: Stelle sicher, dass der Aufrufer korrekt authentifiziert ist. Gateway-authentifizierte Nutzer gelten als vertrauenswürdige Operatoren.
• Node Host reagiert nicht: Überprüfe die lokale IPC-Verbindung zwischen dem Node Host Service und der macOS App.

Du hast Fragen zur Einrichtung? Nutze den AI Setup Assistant.

Nächste Schritte

• Gateway Configuration
• Node Host Setup
• Security Model Overview
• Tool Policy Guide

Du kennst das sicher: Du willst einen Workflow automatisieren, aber die Sicherheitsabfragen unterbrechen ständig deinen Fluss. Entweder ist alles zu restriktiv eingestellt oder du hast Sorge, dass zu viele Berechtigungen ein Sicherheitsrisiko darstellen. Es ist oft mühsam, genau die richtige Balance zwischen Sicherheit und Geschwindigkeit zu finden.

In diesem Guide schauen wir uns an, wie du die Kontrolle über die Ausführung von Befehlen behältst, ohne deine Produktivität zu opfern.

Voraussetzungen

• Einen aktiven Agent (macOS App oder Headless Node)
• Zugriff auf die Konfiguration des Gateway

Quick Start: Die wichtigsten Regler

Du kannst das Verhalten deines Systems über drei zentrale Bereiche steuern. Hier ist der schnellste Weg, um die Sicherheitseinstellungen anzupassen.

Security (exec.security)

Dieser Parameter bestimmt das generelle Sicherheitslevel für Host-Exec-Anfragen:

• deny: Blockiert alle Anfragen sofort.
• allowlist: Erlaubt nur Befehle, die explizit auf deiner Liste stehen.
• full: Erlaubt alles (entspricht Administrator-Rechten).

Ask (exec.ask)

Hier legst du fest, wann das System dich um Erlaubnis fragen soll:

• off: Es gibt niemals einen Prompt.
• on-miss: Du wirst nur gefragt, wenn ein Befehl nicht in der Allowlist steht.
• always: Das System fragt bei jedem einzelnen Befehl nach.

Ask fallback (askFallback)

Falls ein Prompt nötig ist, aber gerade kein UI (wie die macOS App) erreichbar ist, greift diese Einstellung:

• deny: Der Befehl wird blockiert.
• allowlist: Der Befehl wird nur ausgeführt, wenn er in der Allowlist steht.
• full: Der Befehl wird erlaubt.

Allowlist Details

Allowlists gelten immer per Agent. Wenn du mehrere Agents nutzt, musst du in der macOS App auswählen, welchen Agent du gerade bearbeitest.

Wichtige Regeln für Muster:

• Die Muster sind case-insensitive glob matches.
• Einträge müssen zu binary paths auflösen. Einträge, die nur den Dateinamen (basename-only) enthalten, werden ignoriert.

Beispiele für gültige Pfade:

• ~/Projects/**/bin/peekaboo
• ~/.local/bin/*
• /opt/homebrew/bin/rg

Jeder Eintrag in der Allowlist trackt intern folgende Daten:

• id: Eine stabile UUID für die UI-Identität (optional).
• last used: Zeitstempel der letzten Nutzung.
• last used command: Der zuletzt ausgeführte Befehl.
• last resolved path: Der zuletzt aufgelöste Pfad.

Auto-allow skill CLIs

Wenn du Auto-allow skill CLIs aktivierst, werden Executables von bekannten Skills automatisch als erlaubt behandelt. Das gilt für macOS Nodes und Headless Node Hosts. Das System nutzt skills.bins über den Gateway RPC, um die Liste der Skill-Bins abzurufen.

Das ist nützlich für Umgebungen, in denen Gateway und Node innerhalb derselben Vertrauensgrenze liegen. Falls du eine strikte manuelle Kontrolle brauchst, solltest du autoAllowSkills: false setzen und nur manuelle Pfade verwenden.

Fehlerbehebung

• Verschwundene Einträge: Alte agents.default Einträge werden beim Laden automatisch zu agents.main migriert. Prüfe nach dem Update deine Konfiguration.
• Befehle werden ignoriert: Prüfe, ob du nur den Namen eines Programms statt des vollen Pfads angegeben hast. Nur vollständige Binary Paths funktionieren in der Allowlist.

Hast du Fragen zur Einrichtung oder brauchst Hilfe bei spezifischen Pfaden? Nutze den AI Setup Assistant für direkte Unterstützung.

Nächste Schritte

• Gateway Security Overview
• Agent Configuration Guide

Du kennst das Problem: Du schreibst ein Skript und willst nur kurz Daten mit jq filtern. Ständig ploppen Sicherheitsabfragen auf, die deinen Flow unterbrechen. Das nervt und hält auf, wenn du eigentlich nur einen Stream verarbeiten willst.

Es ist mühsam, jedes Tool manuell in die Allowlist aufzunehmen, besonders wenn es nur einfache Text-Transformationen durchführt. Safe Bins lösen dieses Problem, indem sie einen sicheren Pfad für Tools bieten, die ausschließlich auf stdin arbeiten.

Voraussetzungen

• Zugriff auf die Konfigurationsdatei (tools.exec.safeBins)
• Eine installierte Version von OpenClaw
• Host-lokale ~/.openclaw/exec-approvals.json Datei

Schnellstart

1. Standard-Tools nutzen: In der Standardeinstellung sind jq, cut, uniq, head, tail, tr und wc bereits als Safe Bins hinterlegt.
2. Pfade konfigurieren: Falls deine Binaries in Pfaden wie /opt/homebrew/bin oder /usr/local/bin liegen, füge diese zu tools.exec.safeBinTrustedDirs hinzu.
3. Eigene Profile erstellen: Nutze openclaw doctor --fix, um automatisch Gerüste für eigene Profile in tools.exec.safeBinProfiles.<bin> zu erstellen.
4. Sicherheit prüfen: Führe openclaw security audit aus, um sicherzustellen, dass keine kritischen Interpreter fälschlicherweise als Safe Bins markiert sind.

Funktionsweise von Safe Bins

tools.exec.safeBins definiert eine kleine Liste von stdin-only Binaries. Diese können im Allowlist-Modus ohne explizite Einträge ausgeführt werden. Safe Bins lehnen positionale Datei-Argumente sowie pfadähnliche Token ab. Sie arbeiten ausschließlich mit dem eingehenden Stream.

Betrachte dies als schmalen Fast-Path für Stream-Filter, nicht als allgemeine Vertrauensliste. Füge keine Interpreter oder Laufzeit-Binaries wie python3, node, ruby, bash, sh oder zsh hinzu. Wenn ein Befehl darauf ausgelegt ist, Code auszuwerten, Sub-Befehle auszuführen oder Dateien zu lesen, verwende explizite Allowlist-Einträge und lass die Bestätigungsaufforderungen aktiviert.

Eigene Safe Bins benötigen ein explizites Profil in tools.exec.safeBinProfiles.<bin>. Die Validierung erfolgt deterministisch nur anhand der Form von argv. Es finden keine Prüfungen auf dem Host-Dateisystem statt. Das verhindert, dass Unterschiede zwischen Erlaubnis und Ablehnung Informationen über die Existenz von Dateien verraten.

Einschränkungen für Flags

Datei-orientierte Optionen sind für Standard Safe Bins gesperrt. Beispiele hierfür sind:

• sort -o, sort --output, sort --files0-from
• wc --files0-from
• jq -f, jq --from-file
• grep -f, grep --file

Safe Bins erzwingen zudem eine strikte Flag-Policy pro Binary für Optionen, die das stdin-only Verhalten aufbrechen. Lange Optionen werden nach dem “Fail-Closed”-Prinzip validiert: Unbekannte Flags oder mehrdeutige Abkürzungen werden abgelehnt.

Hier sind die gesperrten Flags nach Profil:

• grep: --dereference-recursive, --directories, --exclude-from, --file, --recursive, -R, -d, -f, -r
• jq: --argfile, --from-file, --library-path, --rawfile, --slurpfile, -L, -f
• sort: --compress-program, --files0-from, --output, --random-source, --temporary-directory, -T, -o
• wc: --files0-from

Safe Bins erzwingen außerdem, dass argv Token zur Ausführungszeit als Literal Text behandelt werden. Es findet kein Globbing und keine $VARS Expansion für stdin-only Segmente statt. Muster wie * oder $HOME/... können also nicht genutzt werden, um Dateizugriffe zu erschleichen.

Vertrauenswürdige Verzeichnisse

Safe Bins müssen aus vertrauenswürdigen Verzeichnissen aufgelöst werden. Standardmäßig sind dies /bin und /usr/bin. Einträge in PATH werden niemals automatisch als vertrauenswürdig eingestuft. Wenn deine Binaries in anderen Pfaden liegen, musst du diese explizit in tools.exec.safeBinTrustedDirs eintragen.

Shell-Verhalten und Chaining

Shell-Chaining mit &&, || oder ; ist erlaubt, wenn jedes Segment der obersten Ebene die Allowlist erfüllt. Redirections werden im Allowlist-Modus nicht unterstützt. Command Substitution ($() oder Backticks) wird während des Parsens abgelehnt, auch innerhalb von doppelten Anführungszeichen.

Bei macOS Companion-App Freigaben wird Shell-Text mit Kontroll- oder Expansions-Syntax (&, |, $, <, >, (, )) als Allowlist-Miss gewertet, außer die Shell-Binary selbst steht auf der Allowlist.

Für Shell-Wrapper wie bash -c werden umgebungsbezogene Overrides auf eine kleine Liste reduziert: TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR. Bekannte Dispatch-Wrapper wie env, nice, nohup, stdbuf oder timeout speichern den Pfad der inneren Executable statt den des Wrappers.

Safe Bins vs. Allowlist

Thema	tools.exec.safeBins	Allowlist (exec-approvals.json)
Ziel	Stdin-Filter automatisch erlauben	Bestimmten Executables explizit vertrauen
Match-Typ	Name der Executable + Safe-Bin Policy	Pfad-Glob-Pattern der Executable
Argument-Scope	Durch Profil und Literal-Token Regeln eingeschränkt	Nur Pfad-Match; Argumente liegen in deiner Verantwortung
Beispiele	jq, head, tail, wc	python3, node, ffmpeg, custom CLIs
Beste Nutzung	Risikoarme Text-Transformationen	Tools mit komplexem Verhalten oder Side Effects

Konfiguration

Die Einstellungen befinden sich an folgenden Orten:

• safeBins und safeBinTrustedDirs kommen aus der globalen Config oder per Agent via agents.list[].tools.exec.
• Allowlist-Einträge liegen in ~/.openclaw/exec-approvals.json oder werden über die Control UI verwaltet.
• Per-Agent Profile überschreiben globale Keys in safeBinProfiles.

Beispiel für ein Custom Profile

{
  tools: {
    exec: {
      safeBins: ["jq", "myfilter"],
      safeBinProfiles: {
        myfilter: {
          minPositional: 0,
          maxPositional: 0,
          allowedValueFlags: ["-n", "--limit"],
          deniedFlags: ["-f", "--file", "-c", "--command"],
        },
      },
    },
  },
}

Fehlerbehebung

• Interpreter-Warnung: openclaw security audit gibt tools.exec.safe_bins_interpreter_unprofiled aus, wenn Interpreter ohne Profil in safeBins stehen. Entferne diese oder erstelle ein Profil.
• Fehlende Profile: Nutze openclaw doctor --fix, um leere Profil-Einträge für eigene Safe Bins zu generieren. Überprüfe und verschärfe diese danach manuell.
• Gesperrte Flags: Wenn grep oder sort im stdin-only Modus scheitern, stelle sicher, dass du keine gesperrten Flags wie -f oder -o verwendest. Für grep musst du das Pattern explizit mit -e oder --regexp angeben.

Hast du Fragen zur Einrichtung oder brauchst Hilfe bei deinen Profilen? Nutze den AI Setup Assistant.

Nächste Schritte

• Configuring Exec Allowlists
• Security Audit Guide
• Shell Wrapper Policy
• CLI Reference

Kennst du das? Du automatisierst deine Workflows, aber hast ständig ein ungutes Gefühl, wenn Scripte ohne Aufsicht auf deinen Servern laufen. Du willst die Geschwindigkeit von Agenten, aber ohne die Kontrolle über kritische Befehle zu verlieren.

Es ist nervig, ständig zwischen Sicherheit und Effizienz abwägen zu müssen. Genau hier kommen die Exec Approvals ins Spiel, mit denen du genau festlegst, was ohne Rückfrage durchgeht und wo du lieber selbst nochmal hinschaust.

Voraussetzungen

• Zugriff auf die Control UI
• Nodes, die system.execApprovals.get/set unterstützen (macOS App oder Headless Node Host)
• Zugriff auf die lokale Datei ~/.openclaw/exec-approvals.json (falls die Node noch keine Remote-Konfiguration unterstützt)
• Installiertes CLI für openclaw approvals

Schnellstart

In weniger als fünf Minuten hast du deine Sicherheitsregeln im Griff. Nutze die Karte Control UI → Nodes → Exec approvals, um Defaults und Overrides zu bearbeiten.

1. Scope wählen: Entscheide dich für die globalen Defaults oder wähle einen spezifischen Agenten aus.
2. Policy anpassen: Ändere die Regeln und füge Allowlist-Patterns hinzu oder entferne sie. Die UI zeigt dir last used Metadaten für jedes Pattern, damit du ungenutzte Einträge leicht aussortieren kannst.
3. Target Selector nutzen: Wähle das Gateway für lokale Approvals oder eine spezifische Node.
4. Speichern: Klicke auf Save, um die Änderungen zu aktivieren.

Falls eine Node Approvals noch nicht über die UI meldet, kannst du die Konfiguration direkt in der Datei ~/.openclaw/exec-approvals.json auf dem entsprechenden Host vornehmen.

Für die Arbeit im Terminal nutzt du den Befehl openclaw approvals. Dieser unterstützt sowohl das Editing für das Gateway als auch für einzelne Nodes (Details findest du im Approvals CLI).

Der Approval Flow

Wenn ein Prompt erforderlich ist, sendet das Gateway ein exec.approval.requested an die Operator Clients. Die Control UI oder die macOS App lösen diesen Request via exec.approval.resolve auf. Danach leitet das Gateway die genehmigte Anfrage an den Node Host weiter.

Bei host=node enthalten die Approval Requests einen canonical systemRunPlan. Das Gateway nutzt diesen Plan als verbindliche Quelle für den Command, das cwd (Arbeitsverzeichnis) und den Session-Kontext, wenn es die genehmigten system.run Requests weiterleitet.

Sobald ein Approval benötigt wird, gibt das Exec-Tool sofort eine approval id zurück. Diese ID nutzt du, um spätere Events wie Exec finished oder Exec denied zuzuordnen.

Der Bestätigungsdialog zeigt dir alle wichtigen Details:

• Command und Argumente
• Das Arbeitsverzeichnis (cwd)
• Die Agent ID und den aufgelösten Pfad des Executables
• Host- und Policy-Metadaten

Du hast dann folgende Optionen:

• Allow once: Einmalige Ausführung jetzt.
• Always allow: Zum Allowlist hinzufügen und ausführen.
• Deny: Die Ausführung blockieren.

Fehlerbehebung

• Node wird nicht in der UI angezeigt: Prüfe, ob die Node system.execApprovals.get/set korrekt advertised. Falls nicht, editiere die ~/.openclaw/exec-approvals.json manuell auf dem Host.
• Anfrage wird automatisch abgelehnt: Wenn keine Entscheidung vor Ablauf des Timeouts eintrifft, wird dies als Approval Timeout gewertet und führt zu einem Denial.

Hast du Fragen zur Einrichtung? Unser AI Setup Assistant hilft dir direkt weiter.

Nächste Schritte

• Approvals CLI – Verwalte Berechtigungen direkt im Terminal.
• Node Configuration – Erfahre mehr über Node-spezifische Einstellungen.

Kennst du das? Du bist gerade voll im Flow, schreibst Code oder analysierst Logs, und plötzlich musst du den Kontext komplett wechseln, nur um eine manuelle Freigabe in einem anderen Tool zu bestätigen. Dieser ständige Wechsel zwischen Terminal, Browser und Messenger unterbricht nicht nur deine Konzentration, sondern hält auch den gesamten Workflow auf.

Es wäre viel einfacher, wenn du diese Anfragen dort bearbeiten könntest, wo du dich sowieso gerade mit deinem Team austauschst. Anstatt mühsam Dashboards zu durchsuchen, erledigst du die Freigabe direkt in deinem bevorzugten Chat-Channel.

Voraussetzungen

Bevor du startest, stelle sicher, dass du folgende Komponenten bereit hast:

• Ein aktives Gateway
• Den installierten Node Service
• Die Mac App (falls du den macOS IPC Flow nutzen möchtest)
• Zugriff auf deine Chat-Channels (Slack, Telegram oder Discord)

Schnellstart

Du kannst Exec-Approval-Prompts an jeden beliebigen Chat-Channel (einschließlich Plugin-Channels) weiterleiten. Die Freigabe erfolgt dann einfach über den Befehl /approve. Das System nutzt dafür die standardmäßige Outbound-Delivery-Pipeline.

1. Konfiguration anpassen

Ergänze deine Konfiguration um den Bereich approvals. Hier definierst du, welche Agents überwacht werden und wohin die Anfragen geschickt werden sollen:

{
  approvals: {
    exec: {
      enabled: true,
      mode: "session", // "session" | "targets" | "both"
      agentFilter: ["main"],
      sessionFilter: ["discord"], // Substring oder Regex
      targets: [
        { channel: "slack", to: "U12345678" },
        { channel: "telegram", to: "123456789" },
      ],
    },
  },
}

2. Im Chat antworten

Sobald eine Anfrage in deinem Channel erscheint, kannst du mit diesen Befehlen direkt reagieren:

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

macOS IPC Flow

Wenn du auf macOS arbeitest, sieht der technische Ablauf für die Kommunikation zwischen den Diensten wie folgt aus:

Gateway -> Node Service (WS)
                 |  IPC (UDS + token + HMAC + TTL)
                 v
             Mac App (UI + approvals + system.run)

Sicherheit im Fokus

Die Sicherheit deiner Befehle ist durch mehrere Ebenen geschützt:

• Der Unix Socket Mode ist auf 0600 gesetzt, der Token liegt sicher in der exec-approvals.json.
• Es erfolgt ein Same-UID Peer Check.
• Das System nutzt Challenge/Response (Nonce + HMAC Token + Request Hash) sowie eine kurze TTL (Time-To-Live).

System Events

Der Lebenszyklus eines Exec-Befehls wird durch System-Messages transparent gemacht. Diese Nachrichten erscheinen in der Session des Agents, nachdem der Node das Event gemeldet hat:

• Exec running: Erscheint nur, wenn der Befehl den definierten Schwellenwert für die Laufzeit überschreitet.
• Exec finished: Wird nach Abschluss des Befehls gesendet.
• Exec denied: Erscheint, wenn die Anfrage abgelehnt wurde.
• Gateway-Host Exec Approvals senden dieselben Events, sobald der Befehl endet.

Damit du den Überblick behältst, nutzen genehmigungspflichtige Exec-Befehle die Approval-ID als runId in diesen Nachrichten. Das macht die Korrelation extrem einfach.

Best Practices

Beim Umgang mit Genehmigungen solltest du ein paar Punkte beachten:

• full ist sehr mächtig; verwende daher Allowlists, wann immer es möglich ist.
• Der Modus ask ist ideal, um die Kontrolle zu behalten und trotzdem schnelle Entscheidungen zu treffen.
• Nutze Per-Agent Allowlists, damit Genehmigungen eines Agents nicht fälschlicherweise bei anderen landen.
• Approvals funktionieren nur für Host-Exec-Anfragen von autorisierten Sendern. Nicht autorisierte Nutzer können /exec nicht auslösen.

Falls du Host-Exec komplett blockieren möchtest, setze die Security der Approvals auf deny oder deaktiviere das exec Tool über die Tool Policy. Der Befehl /exec security=full ist ein Komfort-Feature für autorisierte Operator und überspringt die Approvals per Design.

Fehlerbehebung

• Problem: Die /approve Befehle zeigen keine Wirkung. Lösung: Prüfe, ob der Absender der Anfrage ein autorisierter Sender ist. Unautorisierte User haben keine Berechtigung, den /exec Befehl oder die dazugehörigen Approvals zu steuern.
• Problem: Die IPC-Verbindung auf macOS schlägt fehl. Lösung: Kontrolliere, ob der Unix Socket die Berechtigung 0600 besitzt und ob der Token in der Datei exec-approvals.json mit der Konfiguration deines Node Service übereinstimmt.

Du hast Fragen zur Einrichtung oder brauchst Hilfe bei der Konfiguration? Der AI Setup Assistant hilft dir gerne weiter.

Nächste Schritte

• Exec tool
• Elevated mode
• Skills