Ausführungsgenehmigungen

Exec-Genehmigungen sind die Schutzschiene der Companion App / des Node-Hosts, damit ein sandboxed Agent Befehle auf einem echten Host (gateway oder node) ausführen kann. Eine Sicherheitsverriegelung: Befehle sind nur erlaubt, wenn Richtlinie + Allowlist + (optionale) Benutzergenehmigung übereinstimmen. Exec-Genehmigungen liegen zusätzlich zu Tool-Richtlinie und Elevated-Gating vor (außer Elevated ist auf full gesetzt, wodurch Genehmigungen übersprungen werden).

# Wirksame Richtlinie prüfen

Wenn ein lokaler Scope host=node anfordert, meldet exec-policy show diesen Scope zur Laufzeit als nodeverwaltet, statt so zu tun, als wäre die lokale Genehmigungsdatei die Source of Truth.

Wenn die UI der Companion App nicht verfügbar ist, wird jede Anfrage, die normalerweise eine Nachfrage auslösen würde, durch den Ask-Fallback aufgelöst (Standard: deny).

# Wo es gilt

Exec-Genehmigungen werden lokal auf dem Ausführungs-Host erzwungen:

• Gateway-Host → openclaw-Prozess auf der Gateway-Maschine.
• Node-Host → Node-Runner (macOS-Companion-App oder headless Node-Host).

# Vertrauensmodell

• Gateway-authentifizierte Aufrufer sind vertrauenswürdige Operatoren für dieses Gateway.
• Gekoppelte Nodes erweitern diese vertrauenswürdige Operator-Fähigkeit auf den Node-Host.
• Exec-Genehmigungen reduzieren das Risiko versehentlicher Ausführung, sind aber keine Auth-Grenze pro Benutzer.
• Genehmigte Node-Host-Ausführungen binden den kanonischen Ausführungskontext: kanonisches cwd, exaktes argv, env-Bindung, sofern vorhanden, und gepinnter ausführbarer Pfad, sofern zutreffend.
• Für Shell-Skripte und direkte Datei-Aufrufe von Interpretern/Runtimes versucht OpenClaw außerdem, einen konkreten lokalen Dateioperanden zu binden. Wenn sich diese gebundene Datei nach der Genehmigung, aber vor der Ausführung ändert, wird die Ausführung verweigert, statt veränderten Inhalt auszuführen.
• Dateibindung ist bewusst Best Effort und kein vollständiges semantisches Modell jedes Interpreter-/Runtime-Loader-Pfads. Wenn der Genehmigungsmodus nicht genau eine konkrete lokale Datei zum Binden identifizieren kann, verweigert er die Ausstellung einer genehmigungsgestützten Ausführung, statt vollständige Abdeckung vorzutäuschen.

# macOS-Aufteilung

• Der Node-Hostdienst leitet system.run per lokalem IPC an die macOS-App weiter.
• Die macOS-App erzwingt Genehmigungen und führt den Befehl im UI-Kontext aus.

# Einstellungen und Speicherung

Genehmigungen liegen in einer lokalen JSON-Datei auf dem Ausführungs-Host:

~/.openclaw/exec-approvals.json

Beispielschema:

{
  "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",
          "source": "allow-always",
          "commandText": "rg -n TODO",
          "lastUsedAt": 1737150000000,
          "lastUsedCommand": "rg -n TODO",
          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
        }
      ]
    }
  }
}

# Richtlinienoptionen

# exec.security

# exec.ask

# askFallback

# tools.exec.strictInlineEval

Beispiele, die der Strict-Modus abfängt:

• python -c
• node -e, node --eval, node -p
• ruby -e
• perl -e, perl -E
• php -r
• lua -e
• osascript -e

Im Strict-Modus benötigen diese Befehle weiterhin eine ausdrückliche Genehmigung, und allow-always speichert für sie nicht automatisch neue Allowlist-Einträge dauerhaft.

# YOLO-Modus (keine Genehmigung)

Wenn Host-Exec ohne Genehmigungsnachfragen ausgeführt werden soll, müssen Sie beide Richtlinienebenen öffnen - die angeforderte Exec-Richtlinie in der OpenClaw-Konfiguration (tools.exec.*) und die hostlokale Genehmigungsrichtlinie in ~/.openclaw/exec-approvals.json.

YOLO ist das Standardverhalten des Hosts, sofern Sie es nicht ausdrücklich verschärfen:

CLI-gestützte Provider, die ihren eigenen nichtinteraktiven Berechtigungsmodus bereitstellen, können dieser Richtlinie folgen. Claude CLI fügt --permission-mode bypassPermissions hinzu, wenn die von OpenClaw angeforderte Exec-Richtlinie YOLO ist. Überschreiben Sie dieses Backend-Verhalten mit expliziten Claude-Argumenten unter agents.defaults.cliBackends.claude-cli.args / resumeArgs - zum Beispiel --permission-mode default, acceptEdits oder bypassPermissions.

Wenn Sie eine konservativere Einrichtung möchten, verschärfen Sie eine der beiden Ebenen wieder auf allowlist / on-miss oder deny.

# Persistente Gateway-Host-Einrichtung „nie nachfragen“

openclaw config set tools.exec.host gateway
openclaw config set tools.exec.security full
openclaw config set tools.exec.ask off
openclaw gateway restart

openclaw approvals set --stdin <<'EOF'
{
  version: 1,
  defaults: {
    security: "full",
    ask: "off",
    askFallback: "full"
  }
}
EOF

# Lokaler Shortcut

openclaw exec-policy preset yolo

Dieser lokale Shortcut aktualisiert beides:

• Lokales tools.exec.host/security/ask.
• Lokale Standardwerte in ~/.openclaw/exec-approvals.json.

Er ist bewusst nur lokal. Um Genehmigungen für den Gateway-Host oder Node-Host remote zu ändern, verwenden Sie openclaw approvals set --gateway oder openclaw approvals set --node <id|name|ip>.

# Node-Host

Für einen Node-Host wenden Sie stattdessen dieselbe Genehmigungsdatei auf diesem Node an:

openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
{
  version: 1,
  defaults: {
    security: "full",
    ask: "off",
    askFallback: "full"
  }
}
EOF

# Nur-Sitzung-Shortcut

• /exec security=full ask=off ändert nur die aktuelle Sitzung.
• /elevated full ist ein Break-Glass-Shortcut, der für diese Sitzung auch Exec-Genehmigungen überspringt.

Wenn die Host-Genehmigungsdatei strenger bleibt als die Konfiguration, gewinnt weiterhin die strengere Host-Richtlinie.

# Allowlist (pro Agent)

Allowlists gelten pro Agent. Wenn mehrere Agents vorhanden sind, wechseln Sie in der macOS-App den Agent, den Sie bearbeiten. Muster sind Glob-Abgleiche.

Muster können aufgelöste Binärpfad-Globs oder reine Befehlsnamen-Globs sein. Reine Namen passen nur auf Befehle, die über PATH aufgerufen werden; daher kann rg auf /opt/homebrew/bin/rg passen, wenn der Befehl rg ist, aber nicht auf ./rg oder /tmp/rg. Verwenden Sie einen Pfad-Glob, wenn Sie einem bestimmten Binärspeicherort vertrauen möchten.

Legacy-Einträge unter agents.default werden beim Laden nach agents.main migriert. Shell-Ketten wie echo ok && pwd benötigen weiterhin für jedes Top-Level-Segment die Erfüllung der Allowlist-Regeln.

Beispiele:

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

# Argumente mit argPattern einschränken

Fügen Sie argPattern hinzu, wenn ein Allowlist-Eintrag auf eine Binärdatei und eine bestimmte Argumentform passen soll. OpenClaw wertet den regulären Ausdruck gegen die geparsten Befehlsargumente aus, ohne das ausführbare Token (argv[0]). Bei handgeschriebenen Einträgen werden Argumente mit einem einzelnen Leerzeichen verbunden; verankern Sie das Muster daher, wenn Sie eine exakte Übereinstimmung benötigen.

{
  "version": 1,
  "agents": {
    "main": {
      "allowlist": [
        {
          "pattern": "python3",
          "argPattern": "^safe\\.py$"
        }
      ]
    }
  }
}

Dieser Eintrag erlaubt python3 safe.py; python3 other.py ist ein Allowlist-Miss. Wenn auch ein reiner Pfadeintrag für dieselbe Binärdatei vorhanden ist, können nicht passende Argumente weiterhin auf diesen reinen Pfadeintrag zurückfallen. Lassen Sie den reinen Pfadeintrag weg, wenn das Ziel darin besteht, die Binärdatei auf die deklarierten Argumente zu beschränken.

Einträge, die durch Genehmigungsabläufe gespeichert wurden, können ein internes Trennzeichenformat für exakte argv-Übereinstimmung verwenden. Verwenden Sie vorzugsweise die UI oder den Genehmigungsablauf, um diese Einträge neu zu erzeugen, statt den codierten Wert von Hand zu bearbeiten. Wenn OpenClaw argv für ein Befehlssegment nicht parsen kann, passen Einträge mit argPattern nicht.

Jeder Allowlist-Eintrag unterstützt:

# Skill-CLIs automatisch zulassen

Wenn Skill-CLIs automatisch zulassen aktiviert ist, werden ausführbare Dateien, auf die bekannte Skills verweisen, auf Nodes (macOS-Node oder headless Node-Host) als allowlisted behandelt. Dies verwendet skills.bins über das Gateway-RPC, um die Skill-Bin-Liste abzurufen. Deaktivieren Sie dies, wenn Sie strikt manuelle Allowlists verwenden möchten.

# Sichere Bins und Genehmigungsweiterleitung

Informationen zu sicheren Bins (der schnellen Nur-stdin-Pfad), Details zur Interpreter-Bindung und dazu, wie Genehmigungsaufforderungen an Slack/Discord/Telegram weitergeleitet werden (oder als native Genehmigungsclients ausgeführt werden), finden Sie unter Exec-Genehmigungen - erweitert.

# Bearbeitung in der Control UI

Verwenden Sie die Karte Control UI → Nodes → Exec approvals, um Standardwerte, agentenspezifische Überschreibungen und Allowlists zu bearbeiten. Wählen Sie einen Geltungsbereich (Standardwerte oder einen Agent), passen Sie die Richtlinie an, fügen Sie Allowlist-Muster hinzu oder entfernen Sie sie, und klicken Sie dann auf Speichern. Die UI zeigt Metadaten zur letzten Verwendung pro Muster an, damit Sie die Liste übersichtlich halten können.

Der Zielselektor wählt Gateway (lokale Genehmigungen) oder eine Node aus. Nodes müssen system.execApprovals.get/set anbieten (macOS-App oder headless Node-Host). Wenn eine Node Exec-Genehmigungen noch nicht anbietet, bearbeiten Sie direkt ihre lokale Datei ~/.openclaw/exec-approvals.json.

CLI: openclaw approvals unterstützt die Bearbeitung von Gateway oder Node - siehe Approvals-CLI.

# Genehmigungsfluss

Wenn eine Aufforderung erforderlich ist, sendet das Gateway exec.approval.requested an Operator-Clients. Die Control UI und die macOS-App lösen sie über exec.approval.resolve auf, anschließend leitet das Gateway die genehmigte Anfrage an den Node-Host weiter.

Für host=node enthalten Genehmigungsanfragen eine kanonische systemRunPlan-Payload. Das Gateway verwendet diesen Plan als maßgeblichen command/cwd/session-Kontext, wenn genehmigte system.run-Anfragen weitergeleitet werden.

Das ist für asynchrone Genehmigungslatenz wichtig:

• Der Node-Exec-Pfad bereitet vorab einen kanonischen Plan vor.
• Der Genehmigungsdatensatz speichert diesen Plan und seine Bindungsmetadaten.
• Nach der Genehmigung verwendet der endgültig weitergeleitete system.run-Aufruf den gespeicherten Plan wieder, statt späteren Änderungen des Aufrufers zu vertrauen.
• Wenn der Aufrufer command, rawCommand, cwd, agentId oder sessionKey ändert, nachdem die Genehmigungsanfrage erstellt wurde, lehnt das Gateway den weitergeleiteten Lauf als Genehmigungsabweichung ab.

# Systemereignisse

Der Exec-Lebenszyklus wird als Systemmeldungen angezeigt:

• Exec running (nur wenn der Befehl den Schwellenwert für die Laufzeitbenachrichtigung überschreitet).
• Exec finished.
• Exec denied.

Diese werden in der Sitzung des Agent gepostet, nachdem die Node das Ereignis gemeldet hat. Exec-Genehmigungen auf dem Gateway-Host geben dieselben Lebenszyklusereignisse aus, wenn der Befehl abgeschlossen ist (und optional, wenn er länger als der Schwellenwert läuft). Genehmigungspflichtige Execs verwenden die Genehmigungs-ID in diesen Meldungen als runId wieder, damit sie leicht zuzuordnen sind.

# Verhalten bei verweigerter Genehmigung

Wenn eine asynchrone Exec-Genehmigung verweigert wird, verhindert OpenClaw, dass der Agent Ausgaben aus einem früheren Lauf desselben Befehls in der Sitzung wiederverwendet. Der Ablehnungsgrund wird mit explizitem Hinweis übergeben, dass keine Befehlsausgabe verfügbar ist. Dadurch wird verhindert, dass der Agent behauptet, es gebe neue Ausgaben, oder den verweigerten Befehl mit veralteten Ergebnissen aus einem früheren erfolgreichen Lauf wiederholt.

# Auswirkungen

• full ist mächtig; bevorzugen Sie nach Möglichkeit Allowlists.
• ask hält Sie eingebunden und ermöglicht gleichzeitig schnelle Genehmigungen.
• Agentenspezifische Allowlists verhindern, dass Genehmigungen eines Agent auf andere übergreifen.
• Genehmigungen gelten nur für Host-Exec-Anfragen von autorisierten Absendern. Nicht autorisierte Absender können kein /exec ausführen.
• /exec security=full ist eine sitzungsweite Komfortfunktion für autorisierte Operatoren und überspringt Genehmigungen bewusst. Um Host-Exec hart zu blockieren, setzen Sie die Genehmigungssicherheit auf deny oder verweigern Sie das Tool exec über die Tool-Richtlinie.

# Verwandt