Exec-Freigaben

Exec-Freigaben sind die Companion-App- / Node-Host-Schranke, damit ein sandboxed Agent Befehle auf einem echten Host (gateway oder node) ausführen kann. Wie ein Sicherheits-Interlock: Befehle sind nur erlaubt, wenn Richtlinie + Allowlist + (optional) Benutzerfreigabe übereinstimmen. Exec-Freigaben sind zusätzlich zur Tool-Richtlinie und Elevated-Gating (außer elevated ist auf full, dann werden Freigaben übersprungen). Die effektive Richtlinie ist die strengere aus tools.exec.* und den Approval-Defaults; fehlt ein Approvals-Feld, wird der tools.exec-Wert genutzt. Ist die Companion-App-UI nicht verfügbar, wird jede Anfrage, die eine Abfrage erfordert, per Ask-Fallback (Standard: deny) entschieden.

Wo es gilt

Exec-Freigaben werden lokal auf dem Ausführungshost durchgesetzt:

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

macOS-Aufteilung:

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

Einstellungen und Speicher

Freigaben liegen in einer lokalen JSON-Datei auf dem Ausführungshost: ~/.clawdbot/exec-approvals.json. Beispiel-Schema:


{
  "version": 1,
  "socket": {
    "path": "~/.clawdbot/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"\
        }\
      ]
    }
  }
}

Richtlinien-Stellschrauben

Security (`exec.security`)

deny: alle Host-Exec-Anfragen blockieren.
allowlist: nur allowlistete Befehle erlauben.
full: alles erlauben (entspricht elevated).

Ask (`exec.ask`)

off: nie abfragen.
on-miss: nur abfragen, wenn die Allowlist nicht passt.
always: bei jedem Befehl abfragen.

Ask-Fallback (`askFallback`)

Wenn eine Abfrage nötig ist, aber keine UI erreichbar ist, entscheidet der Fallback:

deny: blockieren.
allowlist: nur erlauben, wenn Allowlist passt.
full: erlauben.

Allowlist (pro Agent)

Allowlists sind pro Agent. Bei mehreren Agenten in der macOS-App den zu bearbeitenden Agenten wählen. Muster sind case-insensitive Glob-Matches. Muster sollten auf Binary-Pfade aufgelöst werden (Nur-Basename-Einträge werden ignoriert). Legacy-agents.default-Einträge werden beim Laden nach agents.main migriert. Beispiele:

~/Projects/**/bin/bird
~/.local/bin/*
/opt/homebrew/bin/rg

Jeder Allowlist-Eintrag speichert:

id stabile UUID für die UI-Identität (optional)
last used Zeitstempel
last used command
last resolved path

Auto-Allow für Skill-CLIs

Wenn Auto-allow skill CLIs aktiviert ist, werden von bekannten Skills referenzierte ausführbare Dateien auf Nodes (macOS-Node oder Headless-Node-Host) als allowlistet behandelt. Dafür wird skills.bins über Gateway-RPC abgefragt. Deaktivieren für strenge manuelle Allowlists.

Safe Bins (nur stdin)

tools.exec.safeBins definiert eine kleine Liste nur-stdin-Binaries (z. B. jq), die im Allowlist-Modus ohne explizite Allowlist-Einträge laufen dürfen. Safe Bins lehnen optionale Datei-Args und pfadähnliche Tokens ab und arbeiten nur auf dem eingehenden Stream. Shell-Verkettung und -Umleitungen sind im Allowlist-Modus nicht automatisch erlaubt. Shell-Verkettung (&&, ||, ;) ist erlaubt, wenn jedes Top-Level-Segment die Allowlist erfüllt (inkl. Safe Bins oder Skill-Auto-Allow). Umleitungen bleiben im Allowlist-Modus ununterstützt. Standard Safe Bins: jq, grep, cut, sort, uniq, head, tail, tr, wc.

Bearbeitung in der Control UI

In der Control UI → Nodes → Exec approvals-Karte Defaults, pro-Agent-Überschreibungen und Allowlists bearbeiten. Einen Scope wählen (Defaults oder ein Agent), Richtlinie anpassen, Allowlist-Muster hinzufügen/entfernen, dann Save. Die UI zeigt last used-Metadaten pro Muster. Der Ziel-Selector wählt Gateway (lokale Freigaben) oder einen Node. Nodes müssen system.execApprovals.get/set anbieten (macOS-App oder Headless-Node-Host). Bietet ein Node noch keine Exec-Freigaben an, die lokale ~/.clawdbot/exec-approvals.json direkt bearbeiten. CLI: openclaw approvals unterstützt Gateway- oder Node-Bearbeitung (siehe Approvals CLI).

Freigabe-Ablauf

Wenn eine Abfrage nötig ist, sendet das Gateway exec.approval.requested an Operator-Clients. Control UI und macOS-App lösen es per exec.approval.resolve, dann leitet das Gateway die genehmigte Anfrage an den Node-Host weiter. Bei erforderlichen Freigaben gibt das Exec-Tool sofort mit einer Approval-ID zurück. Diese ID zur späteren Zuordnung von System-Events nutzen (Exec finished / Exec denied). Kommt vor Timeout keine Entscheidung, gilt die Anfrage als Approval-Timeout und wird als Ablehnungsgrund angezeigt. Der Bestätigungsdialog enthält:

Befehl + Args
cwd
Agent-ID
aufgelöster ausführbarer Pfad
Host- + Richtlinien-Metadaten

Aktionen:

Allow once → jetzt ausführen
Always allow → zur Allowlist hinzufügen + ausführen
Deny → blockieren

Weiterleitung von Exec-Freigaben in Chat-Kanäle

Exec-Freigabe-Abfragen kannst du in beliebige Chat-Kanäle (inkl. Plugin-Kanäle) weiterleiten und mit /approve freigeben. Dafür wird die normale ausgehende Zustellung genutzt. Config:


{
  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" }\
      ]
    }
  }
}

Im Chat antworten:


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

macOS-IPC-Ablauf


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

Sicherheitshinweise:

Unix-Socket-Modus 0600, Token in exec-approvals.json gespeichert.
Same-UID-Peer-Check.
Challenge/Response (Nonce + HMAC-Token + Request-Hash) + kurzer TTL.

System-Events

Der Exec-Lebenszyklus erscheint als System-Nachrichten:

Exec running (nur wenn der Befehl den Running-Notice-Schwellwert überschreitet)
Exec finished
Exec denied

Diese werden in der Sitzung des Agenten gepostet, nachdem der Node das Event meldet. Gateway-Host-Exec-Freigaben senden dieselben Lebenszyklus-Events, wenn der Befehl endet (und optional bei Laufzeit über dem Schwellwert). Freigabe-pflichtige Execs nutzen die Approval-ID als runId in diesen Nachrichten zur einfachen Zuordnung.

Konsequenzen

full ist mächtig; Allowlists bevorzugen, wenn möglich.
ask hält dich im Loop und erlaubt trotzdem schnelle Freigaben.
Pro-Agent-Allowlists verhindern, dass Freigaben eines Agenten in andere durchsickern.
Freigaben gelten nur für Host-Exec-Anfragen von autorisierten Sendern. Unautorisierte Sender können /exec nicht ausführen.
/exec security=full ist eine Sitzungs-Convenience für autorisierte Operatoren und überspringt Freigaben by Design. Für harten Block von Host-Exec: Approvals-Security auf deny setzen oder das exec-Tool per Tool-Richtlinie verweigern.

Verwandt: