openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh de translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-21 13:44:06 +00:00
parent 5f890d47c6
commit aafcd6fcc0
16 changed files with 4042 additions and 3713 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

174
docs/de/automation/cron-jobs.md
View File

@ -1,22 +1,22 @@
---
read_when:
- Planen von Hintergrundjobs oder Aufweckvorgängen
- Hintergrundjobs oder Aufweckvorgänge planen
- Externe Trigger (Webhooks, Gmail) in OpenClaw integrieren
- Entscheiden zwischen Heartbeat und Cron für geplante Aufgaben
- Zwischen Heartbeat und Cron für geplante Aufgaben entscheiden
summary: Geplante Jobs, Webhooks und Gmail-PubSub-Trigger für den Gateway-Scheduler
title: Geplante Aufgaben
x-i18n:
generated_at: "2026-04-21T06:22:57Z"
generated_at: "2026-04-21T13:35:27Z"
model: gpt-5.4
provider: openai
source_hash: e25f4dc8ee7b8f88e22d5cbc86e4527a9f5ac0ab4921e7874f76b186054682a3
source_hash: ac08f67af43bc85a1713558899a220c935479620f1ef74aa76336259daac2828
source_path: automation/cron-jobs.md
workflow: 15
---
# Geplante Aufgaben (Cron)
Cron ist der integrierte Scheduler des Gateway. Er speichert Jobs dauerhaft, weckt den Agenten zum richtigen Zeitpunkt auf und kann Ausgaben an einen Chat-Kanal oder einen Webhook-Endpunkt zurückliefern.
Cron ist der integrierte Scheduler des Gateway. Er speichert Jobs dauerhaft, weckt den Agenten zum richtigen Zeitpunkt und kann Ausgaben zurück an einen Chat-Kanal oder einen Webhook-Endpunkt zustellen.
## Schnellstart
@ -32,6 +32,7 @@ openclaw cron add \
# Ihre Jobs prüfen
openclaw cron list
openclaw cron show <job-id>
# Ausführungsverlauf anzeigen
openclaw cron runs --id <job-id>
@ -40,97 +41,95 @@ openclaw cron runs --id <job-id>
## So funktioniert Cron
- Cron läuft **innerhalb des Gateway**-Prozesses (nicht innerhalb des Modells).
- Job-Definitionen werden unter `~/.openclaw/cron/jobs.json` dauerhaft gespeichert, damit Zeitpläne bei Neustarts nicht verloren gehen.
- Der Laufzeit-Ausführungsstatus wird daneben in `~/.openclaw/cron/jobs-state.json` gespeichert. Wenn Sie Cron-Definitionen in Git nachverfolgen, verfolgen Sie `jobs.json` und setzen Sie `jobs-state.json` in `.gitignore`.
- Nach der Aufteilung können ältere OpenClaw-Versionen `jobs.json` lesen, Jobs aber möglicherweise als neu behandeln, weil Laufzeitfelder jetzt in `jobs-state.json` liegen.
- Alle Cron-Ausführungen erstellen Einträge für [Hintergrundaufgaben](/de/automation/tasks).
- Job-Definitionen werden unter `~/.openclaw/cron/jobs.json` dauerhaft gespeichert, sodass Neustarts Zeitpläne nicht verlieren.
- Der Laufzeit-Ausführungsstatus wird daneben in `~/.openclaw/cron/jobs-state.json` gespeichert. Wenn Sie Cron-Definitionen in Git verfolgen, verfolgen Sie `jobs.json` und fügen Sie `jobs-state.json` zu `.gitignore` hinzu.
- Nach der Aufteilung können ältere OpenClaw-Versionen `jobs.json` lesen, behandeln Jobs aber möglicherweise als neu, weil Laufzeitfelder jetzt in `jobs-state.json` liegen.
- Alle Cron-Ausführungen erzeugen Einträge für [Hintergrundaufgaben](/de/automation/tasks).
- Einmalige Jobs (`--at`) werden nach erfolgreicher Ausführung standardmäßig automatisch gelöscht.
- Isolierte Cron-Ausführungen schließen nach bestem Bemühen nach Abschluss des Laufs verfolgte Browser-Tabs/Prozesse für ihre Sitzung `cron:<jobId>`, damit abgekoppelte Browser-Automatisierung keine verwaisten Prozesse hinterlässt.
- Isolierte Cron-Ausführungen schützen außerdem vor veralteten Bestätigungsantworten. Wenn das erste Ergebnis nur ein vorläufiges Status-Update ist (`on it`, `pulling everything together` und ähnliche Hinweise) und kein untergeordneter Subagent-Lauf mehr für die endgültige Antwort verantwortlich ist, fordert OpenClaw vor der Zustellung einmalig erneut das eigentliche Ergebnis an.
- Isolierte Cron-Ausführungen schließen nach bestem Bemühen verfolgte Browser-Tabs/Prozesse für ihre Sitzung `cron:<jobId>`, wenn die Ausführung abgeschlossen ist, damit abgekoppelte Browser-Automatisierung keine verwaisten Prozesse hinterlässt.
- Isolierte Cron-Ausführungen schützen auch vor veralteten Bestätigungsantworten. Wenn das erste Ergebnis nur ein vorläufiges Status-Update ist (`on it`, `pulling everything together` und ähnliche Hinweise) und keine nachgeordnete Subagent-Ausführung noch für die endgültige Antwort verantwortlich ist, fordert OpenClaw einmal erneut zum eigentlichen Ergebnis auf, bevor es zugestellt wird.
<a id="maintenance"></a>
Die Aufgabenabstimmung für Cron ist laufzeitgesteuert: Eine aktive Cron-Aufgabe bleibt aktiv, solange die Cron-Laufzeit diesen Job noch als laufend verfolgt, selbst wenn noch eine alte untergeordnete Sitzungszeile existiert.
Sobald die Laufzeit den Job nicht mehr verwaltet und das 5-Minuten-Toleranzfenster abgelaufen ist, kann die Wartung die Aufgabe als `lost` markieren.
Die Aufgabenabstimmung für Cron gehört der Laufzeit: Eine aktive Cron-Aufgabe bleibt aktiv, solange die Cron-Laufzeit diesen Job noch als laufend verfolgt, selbst wenn noch ein alter Kind-Sitzungseintrag existiert.
Sobald die Laufzeit den Job nicht mehr besitzt und das 5-Minuten-Gnadenfenster abgelaufen ist, kann die Wartung die Aufgabe als `lost` markieren.
## Zeitplantypen
| Art | CLI-Flag | Beschreibung |
| ------- | -------- | ------------------------------------------------------ |
| `at` | `--at` | Einmaliger Zeitstempel (ISO 8601 oder relativ wie `20m`) |
| `every` | `--every` | Festes Intervall |
| `cron` | `--cron` | 5-Feld- oder 6-Feld-Cron-Ausdruck mit optionalem `--tz` |
| Art | CLI-Flag | Beschreibung |
| ------- | -------- | ------------------------------------------------------------- |
| `at` | `--at` | Einmaliger Zeitstempel (ISO 8601 oder relativ wie `20m`) |
| `every` | `--every`| Fester Intervall |
| `cron` | `--cron` | Cron-Ausdruck mit 5 oder 6 Feldern mit optionalem `--tz` |
Zeitstempel ohne Zeitzone werden als UTC behandelt. Fügen Sie `--tz America/New_York` hinzu, um nach lokaler Uhrzeit zu planen.
Zeitstempel ohne Zeitzone werden als UTC behandelt. Fügen Sie `--tz America/New_York` für eine lokale Uhrzeitplanung hinzu.
Wiederkehrende Ausdrücke zur vollen Stunde werden automatisch um bis zu 5 Minuten gestaffelt, um Lastspitzen zu verringern. Verwenden Sie `--exact`, um exaktes Timing zu erzwingen, oder `--stagger 30s` für ein explizites Fenster.
Wiederkehrende Ausdrücke zur vollen Stunde werden automatisch um bis zu 5 Minuten gestaffelt, um Lastspitzen zu reduzieren. Verwenden Sie `--exact`, um exaktes Timing zu erzwingen, oder `--stagger 30s` für ein explizites Fenster.
### Tag-des-Monats und Wochentag verwenden ODER-Logik
### Tag des Monats und Wochentag verwenden ODER-Logik
Cron-Ausdrücke werden von [croner](https://github.com/Hexagon/croner) geparst. Wenn sowohl die Felder für Tag-des-Monats als auch für Wochentag keine Wildcards sind, trifft croner zu, wenn **eines** der beiden Felder passt — nicht beide. Das ist das Standardverhalten von Vixie-Cron.
Cron-Ausdrücke werden von [croner](https://github.com/Hexagon/croner) geparst. Wenn sowohl die Felder für Tag des Monats als auch Wochentag kein Wildcard sind, trifft croner zu, wenn **eines** der Felder passt — nicht beide. Dies ist das standardmäßige Vixie-Cron-Verhalten.
```
# Beabsichtigt: "9 Uhr am 15., aber nur wenn es ein Montag ist"
# Tatsächlich: "9 Uhr an jedem 15., UND 9 Uhr an jedem Montag"
# Tatsächlich: "9 Uhr an jedem 15., UND 9 Uhr an jedem Montag"
0 9 15 * 1
```
Dies wird etwa 5–6 Mal pro Monat ausgelöst statt 0–1 Mal pro Monat. OpenClaw verwendet hier das standardmäßige ODER-Verhalten von Croner. Wenn beide Bedingungen erforderlich sein sollen, verwenden Sie den `+`-Wochentagsmodifikator von Croner (`0 9 15 * +1`) oder planen Sie nach einem Feld und prüfen Sie das andere im Prompt oder Befehl Ihres Jobs.
Dies wird etwa 5–6-mal pro Monat ausgelöst statt 0–1-mal pro Monat. OpenClaw verwendet hier das standardmäßige ODER-Verhalten von Croner. Um beide Bedingungen zu verlangen, verwenden Sie den `+`-Wochentag-Modifikator von Croner (`0 9 15 * +1`) oder planen Sie nach einem Feld und prüfen Sie das andere im Prompt oder Befehl Ihres Jobs.
## Ausführungsstile
| Stil | Wert für `--session` | Läuft in | Am besten geeignet für |
| --------------- | -------------------- | ------------------------ | ------------------------------ |
| Hauptsitzung | `main` | Nächste Heartbeat-Runde | Erinnerungen, Systemereignisse |
| Isoliert | `isolated` | Dedizierte `cron:<jobId>` | Berichte, Hintergrundaufgaben |
| Aktuelle Sitzung | `current` | Beim Erstellen gebunden | Wiederkehrende kontextbezogene Arbeit |
| Stil | Wert von `--session` | Läuft in | Am besten geeignet für |
| --------------- | -------------------- | ------------------------ | -------------------------------- |
| Hauptsitzung | `main` | Nächste Heartbeat-Runde | Erinnerungen, Systemereignisse |
| Isoliert | `isolated` | Dedizierte `cron:<jobId>`| Berichte, Hintergrundaufgaben |
| Aktuelle Sitzung| `current` | Bei Erstellung gebunden | Kontextbewusste wiederkehrende Arbeit |
| Benutzerdefinierte Sitzung | `session:custom-id` | Dauerhafte benannte Sitzung | Workflows, die auf Verlauf aufbauen |
Jobs der **Hauptsitzung** reihen ein Systemereignis ein und wecken optional den Heartbeat (`--wake now` oder `--wake next-heartbeat`). **Isolierte** Jobs führen eine dedizierte Agent-Runde mit einer frischen Sitzung aus. **Benutzerdefinierte Sitzungen** (`session:xxx`) behalten Kontext über mehrere Läufe hinweg bei und ermöglichen Workflows wie tägliche Standups, die auf vorherigen Zusammenfassungen aufbauen.
Jobs in der **Hauptsitzung** stellen ein Systemereignis in die Warteschlange und wecken optional den Heartbeat (`--wake now` oder `--wake next-heartbeat`). **Isolierte** Jobs führen eine dedizierte Agent-Runde mit einer frischen Sitzung aus. **Benutzerdefinierte Sitzungen** (`session:xxx`) behalten Kontext über mehrere Ausführungen hinweg bei und ermöglichen Workflows wie tägliche Standups, die auf vorherigen Zusammenfassungen aufbauen.
Bei isolierten Jobs umfasst der Laufzeitabbau jetzt auch das nach bestem Bemühen ausgeführte Browser-Cleanup für diese Cron-Sitzung. Fehler beim Cleanup werden ignoriert, damit das eigentliche Cron-Ergebnis weiterhin Vorrang hat.
Bei isolierten Jobs umfasst der Laufzeitabbau jetzt auch die Browser-Bereinigung nach bestem Bemühen für diese Cron-Sitzung. Fehler bei der Bereinigung werden ignoriert, sodass das tatsächliche Cron-Ergebnis weiterhin Vorrang hat.
Wenn isolierte Cron-Ausführungen Subagenten orchestrieren, bevorzugt die Zustellung außerdem die endgültige Ausgabe des Nachfahren gegenüber veraltetem vorläufigem Text des Elternteils. Wenn Nachfahren noch laufen, unterdrückt OpenClaw dieses teilweise Eltern-Update, statt es anzukündigen.
Wenn isolierte Cron-Ausführungen Subagenten orchestrieren, bevorzugt die Zustellung außerdem die endgültige Ausgabe der nachgeordneten Ausführung gegenüber veraltetem vorläufigem Text der übergeordneten Ausführung. Wenn nachgeordnete Ausführungen noch laufen, unterdrückt OpenClaw dieses partielle Update der übergeordneten Ausführung, statt es anzukündigen.
### Nutzlastoptionen für isolierte Jobs
### Payload-Optionen für isolierte Jobs
- `--message`: Prompt-Text (für isolierte Jobs erforderlich)
- `--model` / `--thinking`: Überschreibungen für Modell und Denkstufe
- `--light-context`: Überspringt die Injektion der Bootstrap-Datei für den Workspace
- `--tools exec,read`: Schränkt ein, welche Tools der Job verwenden darf
- `--model` / `--thinking`: Überschreibungen für Modell und Thinking-Level
- `--light-context`: Dateiinjektion beim Workspace-Bootstrap überspringen
- `--tools exec,read`: einschränken, welche Tools der Job verwenden kann
`--model` verwendet das für diesen Job ausgewählte zulässige Modell. Wenn das angeforderte Modell nicht zulässig ist, protokolliert Cron eine Warnung und fällt stattdessen auf die Modellwahl des Agenten/Standards für den Job zurück. Konfigurierte Fallback-Ketten gelten weiterhin, aber eine einfache Modellüberschreibung ohne explizite Fallback-Liste pro Job hängt den primären Agenten nicht mehr als verstecktes zusätzliches Retry-Ziel an.
`--model` verwendet das für diesen Job ausgewählte erlaubte Modell. Wenn das angeforderte Modell nicht erlaubt ist, protokolliert Cron eine Warnung und fällt stattdessen auf die Modellauswahl des Agenten/Standardmodells für den Job zurück. Konfigurierte Fallback-Ketten gelten weiterhin, aber eine einfache Modellüberschreibung ohne explizite jobbezogene Fallback-Liste hängt das primäre Agentenmodell nicht mehr als verborgenes zusätzliches Wiederholungsziel an.
Die Reihenfolge der Modellwahl für isolierte Jobs ist:
Die Reihenfolge der Modellauswahl für isolierte Jobs ist:
1. Gmail-Hook-Modellüberschreibung (wenn der Lauf von Gmail kam und diese Überschreibung zulässig ist)
2. `model` in der Nutzlast pro Job
1. Modellüberschreibung des Gmail-Hooks (wenn die Ausführung von Gmail kam und diese Überschreibung erlaubt ist)
2. Jobbezogenes Payload-`model`
3. Gespeicherte Modellüberschreibung der Cron-Sitzung
4. Modellwahl des Agenten/Standards
4. Modellauswahl des Agenten/Standardmodells
Der Schnellmodus folgt ebenfalls der aufgelösten Live-Auswahl. Wenn die ausgewählte Modellkonfiguration `params.fastMode` hat, verwendet isoliertes Cron dies standardmäßig. Eine gespeicherte Sitzungsüberschreibung `fastMode` hat in beide Richtungen weiterhin Vorrang vor der Konfiguration.
Der Fast-Modus folgt ebenfalls der aufgelösten Live-Auswahl. Wenn die ausgewählte Modellkonfiguration `params.fastMode` hat, verwendet isoliertes Cron dies standardmäßig. Eine gespeicherte Sitzungsüberschreibung für `fastMode` hat in beide Richtungen weiterhin Vorrang vor der Konfiguration.
Wenn ein isolierter Lauf auf eine Live-Modellwechsel-Übergabe stößt, versucht Cron es mit dem umgeschalteten Provider/Modell erneut und speichert diese Live-Auswahl vor dem erneuten Versuch. Wenn der Wechsel auch ein neues Auth-Profil mitbringt, speichert Cron auch diese Auth-Profil-Überschreibung. Wiederholungen sind begrenzt: Nach dem ersten Versuch plus 2 Wechsel-Wiederholungen bricht Cron ab, statt endlos zu schleifen.
Wenn eine isolierte Ausführung auf eine Live-Modellwechsel-Übergabe trifft, versucht Cron es mit dem gewechselten Provider/Modell erneut und speichert diese Live-Auswahl vor dem erneuten Versuch. Wenn der Wechsel auch ein neues Auth-Profil enthält, speichert Cron auch diese Überschreibung des Auth-Profils. Wiederholungen sind begrenzt: Nach dem ersten Versuch plus 2 Wechsel-Wiederholungen bricht Cron ab, statt endlos zu schleifen.
## Zustellung und Ausgabe
| Modus | Was passiert |
| ---------- | ----------------------------------------------------------- |
| `announce` | Zustellung der Zusammenfassung an den Zielkanal (Standard für isolierte Jobs) |
| `webhook` | Sendet die Nutzlast des abgeschlossenen Ereignisses per POST an eine URL |
| `none` | Nur intern, keine Zustellung |
| Modus | Was passiert |
| ---------- | ---------------------------------------------------------------- |
| `announce` | Stellt den finalen Text ersatzweise an das Ziel zu, falls der Agent nichts gesendet hat |
| `webhook` | POSTet die Nutzlast des abgeschlossenen Ereignisses an eine URL |
| `none` | Keine Fallback-Zustellung durch den Runner |
Verwenden Sie `--announce --channel telegram --to "-1001234567890"` für die Zustellung an einen Kanal. Für Telegram-Forenthemen verwenden Sie `-1001234567890:topic:123`. Slack-/Discord-/Mattermost-Ziele sollten explizite Präfixe verwenden (`channel:<id>`, `user:<id>`).
Verwenden Sie `--announce --channel telegram --to "-1001234567890"` für die Zustellung an einen Kanal. Für Telegram-Forenthemen verwenden Sie `-1001234567890:topic:123`. Ziele für Slack/Discord/Mattermost sollten explizite Präfixe verwenden (`channel:<id>`, `user:<id>`).
Bei isolierten Jobs in Besitz von Cron verwaltet der Runner den endgültigen Zustellpfad. Der Agent wird aufgefordert, eine Klartext-Zusammenfassung zurückzugeben, und diese Zusammenfassung wird dann über `announce` oder `webhook` gesendet oder bei `none` intern behalten. `--no-deliver` gibt die Zustellung nicht an den Agenten zurück; der Lauf bleibt intern.
Wenn in der ursprünglichen Aufgabe ausdrücklich steht, dass ein externer Empfänger benachrichtigt werden soll, sollte der Agent in seiner Ausgabe vermerken, wer/wo benachrichtigt werden soll, statt zu versuchen, direkt zu senden.
Bei isolierten Jobs ist die Chat-Zustellung gemeinsam genutzt. Wenn eine Chat-Route verfügbar ist, kann der Agent das Tool `message` verwenden, auch wenn der Job `--no-deliver` verwendet. Wenn der Agent an das konfigurierte/aktuelle Ziel sendet, überspringt OpenClaw das Fallback-`announce`. Andernfalls steuern `announce`, `webhook` und `none` nur, was der Runner nach der Agent-Runde mit der endgültigen Antwort macht.
Fehlerbenachrichtigungen folgen einem separaten Zielpfad:
- `cron.failureDestination` setzt einen globalen Standard für Fehlerbenachrichtigungen.
- `job.delivery.failureDestination` überschreibt dies pro Job.
- Wenn keines von beiden gesetzt ist und der Job bereits über `announce` zustellt, fallen Fehlerbenachrichtigungen jetzt auf dieses primäre Ankündigungsziel zurück.
- Wenn keines von beiden gesetzt ist und der Job bereits über `announce` zustellt, fallen Fehlerbenachrichtigungen jetzt auf dieses primäre `announce`-Ziel zurück.
- `delivery.failureDestination` wird nur bei Jobs mit `sessionTarget="isolated"` unterstützt, es sei denn, der primäre Zustellmodus ist `webhook`.
## CLI-Beispiele
@ -160,7 +159,7 @@ openclaw cron add \
--to "channel:C1234567890"
```
Isolierter Job mit Überschreibung von Modell und Denkstufe:
Isolierter Job mit Modell- und Thinking-Überschreibung:
```bash
openclaw cron add \
@ -199,7 +198,7 @@ Tokens in der Query-String werden abgelehnt.
### POST /hooks/wake
Reiht ein Systemereignis für die Hauptsitzung ein:
Stellt ein Systemereignis für die Hauptsitzung in die Warteschlange:
```bash
curl -X POST http://127.0.0.1:18789/hooks/wake \
@ -226,23 +225,23 @@ Felder: `message` (erforderlich), `name`, `agentId`, `wakeMode`, `deliver`, `cha
### Zugeordnete Hooks (POST /hooks/\<name\>)
Benutzerdefinierte Hook-Namen werden über `hooks.mappings` in der Konfiguration aufgelöst. Zuordnungen können beliebige Nutzlasten mit Vorlagen oder Code-Transformationen in `wake`- oder `agent`-Aktionen umwandeln.
Benutzerdefinierte Hook-Namen werden über `hooks.mappings` in der Konfiguration aufgelöst. Zuordnungen können beliebige Payloads mit Vorlagen oder Code-Transformationen in Aktionen vom Typ `wake` oder `agent` umwandeln.
### Sicherheit
- Halten Sie Hook-Endpunkte hinter Loopback, Tailnet oder einem vertrauenswürdigen Reverse-Proxy.
- Verwenden Sie ein dediziertes Hook-Token; verwenden Sie Gateway-Auth-Tokens nicht erneut.
- Verwenden Sie ein dediziertes Hook-Token; verwenden Sie keine Gateway-Auth-Tokens erneut.
- Halten Sie `hooks.path` auf einem dedizierten Unterpfad; `/` wird abgelehnt.
- Setzen Sie `hooks.allowedAgentIds`, um explizites `agentId`-Routing einzuschränken.
- Belassen Sie `hooks.allowRequestSessionKey=false`, sofern Sie keine vom Aufrufer ausgewählten Sitzungen benötigen.
- Wenn Sie `hooks.allowRequestSessionKey` aktivieren, setzen Sie zusätzlich `hooks.allowedSessionKeyPrefixes`, um zulässige Formen von Sitzungsschlüsseln einzuschränken.
- Hook-Nutzlasten werden standardmäßig mit Sicherheitsgrenzen umschlossen.
- Setzen Sie `hooks.allowedAgentIds`, um explizites `agentId`-Routing zu begrenzen.
- Belassen Sie `hooks.allowRequestSessionKey=false`, es sei denn, Sie benötigen vom Aufrufer ausgewählte Sitzungen.
- Wenn Sie `hooks.allowRequestSessionKey` aktivieren, setzen Sie auch `hooks.allowedSessionKeyPrefixes`, um erlaubte Formen von Sitzungsschlüsseln einzuschränken.
- Hook-Payloads werden standardmäßig mit Sicherheitsgrenzen umschlossen.
## Gmail-PubSub-Integration
Verbinden Sie Gmail-Posteingangs-Trigger über Google PubSub mit OpenClaw.
**Voraussetzungen**: `gcloud` CLI, `gog` (gogcli), aktivierte OpenClaw-Hooks, Tailscale für den öffentlichen HTTPS-Endpunkt.
**Voraussetzungen**: `gcloud`-CLI, `gog` (gogcli), aktivierte OpenClaw-Hooks, Tailscale für den öffentlichen HTTPS-Endpunkt.
### Einrichtung per Assistent (empfohlen)
@ -250,11 +249,11 @@ Verbinden Sie Gmail-Posteingangs-Trigger über Google PubSub mit OpenClaw.
openclaw webhooks gmail setup --account openclaw@gmail.com
```
Dies schreibt die Konfiguration `hooks.gmail`, aktiviert die Gmail-Voreinstellung und verwendet Tailscale Funnel für den Push-Endpunkt.
Dies schreibt die Konfiguration `hooks.gmail`, aktiviert das Gmail-Preset und verwendet Tailscale Funnel für den Push-Endpunkt.
### Automatischer Gateway-Start
### Gateway-Autostart
Wenn `hooks.enabled=true` und `hooks.gmail.account` gesetzt ist, startet das Gateway beim Booten `gog gmail watch serve` und erneuert die Überwachung automatisch. Setzen Sie `OPENCLAW_SKIP_GMAIL_WATCHER=1`, um dies zu deaktivieren.
Wenn `hooks.enabled=true` und `hooks.gmail.account` gesetzt ist, startet das Gateway beim Booten `gog gmail watch serve` und erneuert die Watch automatisch. Setzen Sie `OPENCLAW_SKIP_GMAIL_WATCHER=1`, um dies zu deaktivieren.
### Manuelle einmalige Einrichtung
@ -266,7 +265,7 @@ gcloud config set project <project-id>
gcloud services enable gmail.googleapis.com pubsub.googleapis.com
```
2. Erstellen Sie ein Topic und gewähren Sie Gmail Zugriff für Push:
2. Topic erstellen und Gmail Push-Zugriff gewähren:
```bash
gcloud pubsub topics create gog-gmail-watch
@ -275,7 +274,7 @@ gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
--role=roles/pubsub.publisher
```
3. Starten Sie die Überwachung:
3. Die Watch starten:
```bash
gog gmail watch start \
@ -303,10 +302,13 @@ gog gmail watch start \
# Alle Jobs auflisten
openclaw cron list
# Einen Job anzeigen, einschließlich aufgelöster Zustellroute
openclaw cron show <jobId>
# Einen Job bearbeiten
openclaw cron edit <jobId> --message "Updated prompt" --model "opus"
# Einen Job jetzt sofort ausführen
# Einen Job jetzt erzwungen ausführen
openclaw cron run <jobId>
# Nur ausführen, wenn fällig
@ -318,17 +320,17 @@ openclaw cron runs --id <jobId> --limit 50
# Einen Job löschen
openclaw cron remove <jobId>
# Agent-Auswahl (Multi-Agent-Setups)
# Agent-Auswahl (Setups mit mehreren Agenten)
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
openclaw cron edit <jobId> --clear-agent
```
Hinweis zur Modellüberschreibung:
- `openclaw cron add|edit --model ...` ändert das ausgewählte Modell des Jobs.
- Wenn das Modell zulässig ist, erreicht genau dieser Provider/dieses Modell den isolierten Agent-Lauf.
- Wenn es nicht zulässig ist, gibt Cron eine Warnung aus und fällt auf die Modellwahl des Agenten/Standards für den Job zurück.
- Konfigurierte Fallback-Ketten gelten weiterhin, aber eine einfache `--model`-Überschreibung ohne explizite Fallback-Liste pro Job fällt nicht mehr auf den primären Agenten als stilles zusätzliches Retry-Ziel zurück.
- `openclaw cron add|edit --model ...` ändert das für den Job ausgewählte Modell.
- Wenn das Modell erlaubt ist, erreicht genau dieser Provider/dieses Modell die isolierte Agent-Ausführung.
- Wenn es nicht erlaubt ist, gibt Cron eine Warnung aus und fällt auf die Auswahl des Agenten-/Standardmodells des Jobs zurück.
- Konfigurierte Fallback-Ketten gelten weiterhin, aber eine einfache `--model`-Überschreibung ohne explizite jobbezogene Fallback-Liste fällt nicht mehr stillschweigend auf das primäre Agentenmodell als zusätzliches Wiederholungsziel zurück.
## Konfiguration
@ -350,21 +352,21 @@ Hinweis zur Modellüberschreibung:
}
```
Die Sidecar-Datei für den Laufzeitzustand wird aus `cron.store` abgeleitet: Ein `.json`-Store wie
Der Laufzeit-Zustands-Sidecar wird aus `cron.store` abgeleitet: Ein `.json`-Store wie
`~/clawd/cron/jobs.json` verwendet `~/clawd/cron/jobs-state.json`, während ein Store-Pfad
ohne Suffix `.json` `-state.json` anhängt.
ohne `.json`-Suffix `-state.json` anhängt.
Cron deaktivieren: `cron.enabled: false` oder `OPENCLAW_SKIP_CRON=1`.
**Wiederholung bei einmaligen Jobs**: Vorübergehende Fehler (Rate-Limit, Überlastung, Netzwerk, Serverfehler) werden mit exponentiellem Backoff bis zu 3-mal wiederholt. Permanente Fehler deaktivieren den Job sofort.
**Wiederholungen für Einmaljobs**: Vorübergehende Fehler (Rate-Limit, Überlastung, Netzwerk, Serverfehler) werden mit exponentiellem Backoff bis zu 3-mal wiederholt. Permanente Fehler werden sofort deaktiviert.
**Wiederholung bei wiederkehrenden Jobs**: Exponentieller Backoff (30 s bis 60 min) zwischen Wiederholungen. Der Backoff wird nach dem nächsten erfolgreichen Lauf zurückgesetzt.
**Wiederholungen für wiederkehrende Jobs**: Exponentieller Backoff (30 s bis 60 min) zwischen Wiederholungen. Der Backoff wird nach der nächsten erfolgreichen Ausführung zurückgesetzt.
**Wartung**: `cron.sessionRetention` (Standard `24h`) bereinigt Einträge isolierter Lauf-Sitzungen. `cron.runLog.maxBytes` / `cron.runLog.keepLines` kürzen Run-Log-Dateien automatisch.
**Wartung**: `cron.sessionRetention` (Standard `24h`) bereinigt isolierte Lauf-Sitzungseinträge. `cron.runLog.maxBytes` / `cron.runLog.keepLines` bereinigen Run-Log-Dateien automatisch.
## Fehlerbehebung
### Befehlsreihenfolge
### Befehlsleiter
```bash
openclaw status
@ -380,23 +382,23 @@ openclaw doctor
### Cron wird nicht ausgelöst
- Prüfen Sie `cron.enabled` und die Umgebungsvariable `OPENCLAW_SKIP_CRON`.
- Stellen Sie sicher, dass das Gateway kontinuierlich läuft.
- Verifizieren Sie bei `cron`-Zeitplänen die Zeitzone (`--tz`) im Vergleich zur Host-Zeitzone.
- `reason: not-due` in der Ausführungsausgabe bedeutet, dass der manuelle Lauf mit `openclaw cron run <jobId> --due` geprüft wurde und der Job noch nicht fällig war.
- Bestätigen Sie, dass das Gateway kontinuierlich läuft.
- Prüfen Sie bei `cron`-Zeitplänen die Zeitzone (`--tz`) im Vergleich zur Zeitzone des Hosts.
- `reason: not-due` in der Ausführungsausgabe bedeutet, dass die manuelle Ausführung mit `openclaw cron run <jobId> --due` geprüft wurde und der Job noch nicht fällig war.
### Cron wurde ausgelöst, aber keine Zustellung
- Der Zustellmodus `none` bedeutet, dass keine externe Nachricht erwartet wird.
- Zustellmodus `none` bedeutet, dass keine Fallback-Zustellung durch den Runner zu erwarten ist. Der Agent kann bei verfügbarer Chat-Route weiterhin direkt mit dem Tool `message` senden.
- Fehlendes/ungültiges Zustellziel (`channel`/`to`) bedeutet, dass ausgehende Zustellung übersprungen wurde.
- Kanal-Authentifizierungsfehler (`unauthorized`, `Forbidden`) bedeuten, dass die Zustellung durch Anmeldedaten blockiert wurde.
- Wenn der isolierte Lauf nur das stille Token (`NO_REPLY` / `no_reply`) zurückgibt, unterdrückt OpenClaw die direkte ausgehende Zustellung und auch den Fallback-Pfad mit der eingereihten Zusammenfassung, sodass nichts zurück in den Chat gepostet wird.
- Erwarten Sie bei isolierten Jobs in Besitz von Cron nicht, dass der Agent das Nachrichtentool als Fallback verwendet. Der Runner verwaltet die endgültige Zustellung; `--no-deliver` hält sie intern, statt ein direktes Senden zu erlauben.
- Wenn die isolierte Ausführung nur das stille Token (`NO_REPLY` / `no_reply`) zurückgibt, unterdrückt OpenClaw die direkte ausgehende Zustellung und auch den Fallback-Pfad der in die Warteschlange gestellten Zusammenfassung, sodass nichts zurück in den Chat gepostet wird.
- Wenn der Agent dem Nutzer selbst eine Nachricht senden soll, prüfen Sie, dass der Job eine nutzbare Route hat (`channel: "last"` mit einem vorherigen Chat oder ein expliziter Kanal/ein explizites Ziel).
### Zeitzonen-Fallstricke
- Cron ohne `--tz` verwendet die Zeitzone des Gateway-Hosts.
- `at`-Zeitpläne ohne Zeitzone werden als UTC behandelt.
- Heartbeat `activeHours` verwendet die konfigurierte Zeitzonenauflösung.
- Heartbeat-`activeHours` verwendet die konfigurierte Zeitzonenauflösung.
## Verwandt

268
docs/de/channels/bluebubbles.md
View File

@ -1,43 +1,43 @@
---
read_when:
- BlueBubbles-Kanal einrichten
- Einrichten des BlueBubbles-Kanals
- Fehlerbehebung bei der Webhook-Kopplung
- iMessage auf macOS konfigurieren
- Konfigurieren von iMessage unter macOS
summary: iMessage über den BlueBubbles-macOS-Server (REST-Senden/-Empfangen, Tippen, Reaktionen, Kopplung, erweiterte Aktionen).
title: BlueBubbles
x-i18n:
generated_at: "2026-04-21T06:22:56Z"
generated_at: "2026-04-21T13:35:27Z"
model: gpt-5.4
provider: openai
source_hash: b3d8d617fc86ca1b191ff4dd2ae26b464e4d3f456a79c67b484a3a76d75de0d2
source_hash: 30ce50ae8a17140b42fa410647c367e0eefdffb1646b1ff92d8e1af63f2e1155
source_path: channels/bluebubbles.md
workflow: 15
---
# BlueBubbles (macOS REST)
Status: Gebündeltes Plugin, das über HTTP mit dem BlueBubbles-macOS-Server kommuniziert. **Empfohlen für die iMessage-Integration** aufgrund der umfangreicheren API und der einfacheren Einrichtung im Vergleich zum Legacy-imsg-Kanal.
Status: gebündeltes Plugin, das über HTTP mit dem BlueBubbles-macOS-Server kommuniziert. **Empfohlen für die iMessage-Integration** aufgrund der umfangreicheren API und der einfacheren Einrichtung im Vergleich zum veralteten imsg-Kanal.
## Gebündeltes Plugin
Aktuelle OpenClaw-Versionen enthalten BlueBubbles gebündelt, daher benötigen normale paketierte Builds keinen separaten Schritt `openclaw plugins install`.
Aktuelle OpenClaw-Releases enthalten BlueBubbles bereits gebündelt, daher ist bei normalen paketierten Builds kein separater Schritt `openclaw plugins install` erforderlich.
## Übersicht
## Überblick
- Läuft auf macOS über die BlueBubbles-Hilfs-App ([bluebubbles.app](https://bluebubbles.app)).
- Empfohlen/getestet: macOS Sequoia (15). macOS Tahoe (26) funktioniert; Bearbeiten ist auf Tahoe derzeit defekt, und Aktualisierungen von Gruppensymbolen können Erfolg melden, ohne zu synchronisieren.
- Empfohlen/getestet: macOS Sequoia (15). macOS Tahoe (26) funktioniert; Bearbeiten ist auf Tahoe derzeit defekt, und Aktualisierungen von Gruppensymbolen können Erfolg melden, aber nicht synchronisiert werden.
- OpenClaw kommuniziert damit über die REST-API (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`).
- Eingehende Nachrichten kommen über Webhooks an; ausgehende Antworten, Tippindikatoren, Lesebestätigungen und Tapbacks sind REST-Aufrufe.
- Anhänge und Sticker werden als eingehende Medien aufgenommen (und dem Agenten nach Möglichkeit bereitgestellt).
- Kopplung/Allowlist funktioniert genauso wie bei anderen Kanälen (`/channels/pairing` usw.) mit `channels.bluebubbles.allowFrom` + Kopplungscodes.
- Reaktionen werden wie bei Slack/Telegram als Systemereignisse bereitgestellt, sodass Agenten sie vor einer Antwort „erwähnen“ können.
- Reaktionen werden genau wie bei Slack/Telegram als Systemereignisse dargestellt, sodass Agenten sie vor dem Antworten „erwähnen“ können.
- Erweiterte Funktionen: Bearbeiten, Zurückziehen, Antwort-Threading, Nachrichteneffekte, Gruppenverwaltung.
## Schnellstart
1. Installieren Sie den BlueBubbles-Server auf Ihrem Mac (folgen Sie den Anweisungen unter [bluebubbles.app/install](https://bluebubbles.app/install)).
2. Aktivieren Sie in der BlueBubbles-Konfiguration die Web-API und legen Sie ein Passwort fest.
3. Führen Sie `openclaw onboard` aus und wählen Sie BlueBubbles aus, oder konfigurieren Sie manuell:
3. Führen Sie `openclaw onboard` aus und wählen Sie BlueBubbles aus, oder konfigurieren Sie es manuell:
```json5
{
@ -53,19 +53,19 @@ Aktuelle OpenClaw-Versionen enthalten BlueBubbles gebündelt, daher benötigen n
```
4. Leiten Sie BlueBubbles-Webhooks an Ihr Gateway weiter (Beispiel: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`).
5. Starten Sie das Gateway; es registriert den Webhook-Handler und startet die Kopplung.
5. Starten Sie das Gateway; es registriert den Webhook-Handler und beginnt mit der Kopplung.
Sicherheitshinweis:
- Legen Sie immer ein Webhook-Passwort fest.
- Webhook-Authentifizierung ist immer erforderlich. OpenClaw weist BlueBubbles-Webhook-Anfragen zurück, sofern sie kein Passwort/guid enthalten, das mit `channels.bluebubbles.password` übereinstimmt (zum Beispiel `?password=<password>` oder `x-password`), unabhängig von local loopback-/Proxy-Topologie.
- Die Passwortauthentifizierung wird geprüft, bevor vollständige Webhook-Bodys gelesen/geparst werden.
- Webhook-Authentifizierung ist immer erforderlich. OpenClaw weist BlueBubbles-Webhook-Anfragen zurück, sofern sie kein Passwort/GUID enthalten, das mit `channels.bluebubbles.password` übereinstimmt (zum Beispiel `?password=<password>` oder `x-password`), unabhängig von local loopback-/Proxy-Topologie.
- Die Passwortauthentifizierung wird geprüft, bevor vollständige Webhook-Bodies gelesen/geparst werden.
## Messages.app aktiv halten (VM- / Headless-Setups)
## Messages.app aktiv halten (VM-/headless-Setups)
Einige macOS-VM- / Always-on-Setups können dazu führen, dass Messages.app „inaktiv“ wird (eingehende Ereignisse stoppen, bis die App geöffnet/in den Vordergrund gebracht wird). Eine einfache Umgehung besteht darin, **Messages alle 5 Minuten anzustoßen** – mit einem AppleScript + LaunchAgent.
Bei einigen macOS-VM-/Always-on-Setups kann Messages.app in einen „Leerlauf“-Zustand geraten (eingehende Ereignisse stoppen, bis die App geöffnet/in den Vordergrund gebracht wird). Eine einfache Behelfslösung ist, **Messages alle 5 Minuten anzustoßen** – mit einem AppleScript + LaunchAgent.
### 1) Das AppleScript speichern
### 1) AppleScript speichern
Speichern Sie dies als:
@ -125,10 +125,10 @@ Speichern Sie dies als:
Hinweise:
- Dies läuft **alle 300 Sekunden** und **bei der Anmeldung**.
- Der erste Lauf kann macOS-Eingabeaufforderungen für **Automation** auslösen (`osascript` → Messages). Bestätigen Sie diese in derselben Benutzersitzung, in der der LaunchAgent ausgeführt wird.
- Dies wird **alle 300 Sekunden** und **bei der Anmeldung** ausgeführt.
- Beim ersten Ausführen können macOS-Aufforderungen für **Automation** erscheinen (`osascript` → Messages). Bestätigen Sie diese in derselben Benutzersitzung, in der der LaunchAgent läuft.
Laden Sie es:
Laden Sie ihn:
```bash
launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
@ -145,13 +145,13 @@ openclaw onboard
Der Assistent fragt nach:
- **Server URL** (erforderlich): BlueBubbles-Serveradresse (z. B. `http://192.168.1.100:1234`)
- **Password** (erforderlich): API-Passwort aus den BlueBubbles-Servereinstellungen
- **Webhook path** (optional): Standard ist `/bluebubbles-webhook`
- **DM policy**: pairing, allowlist, open oder disabled
- **Allow list**: Telefonnummern, E-Mail-Adressen oder Chat-Ziele
- **Server-URL** (erforderlich): BlueBubbles-Serveradresse (z. B. `http://192.168.1.100:1234`)
- **Passwort** (erforderlich): API-Passwort aus den BlueBubbles-Servereinstellungen
- **Webhook-Pfad** (optional): Standard ist `/bluebubbles-webhook`
- **DM-Richtlinie**: pairing, allowlist, open oder disabled
- **Allowlist**: Telefonnummern, E-Mail-Adressen oder Chat-Ziele
Sie können BlueBubbles auch per CLI hinzufügen:
Sie können BlueBubbles auch über die CLI hinzufügen:
```
openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>
@ -163,24 +163,24 @@ DMs:
- Standard: `channels.bluebubbles.dmPolicy = "pairing"`.
- Unbekannte Absender erhalten einen Kopplungscode; Nachrichten werden ignoriert, bis sie genehmigt werden (Codes laufen nach 1 Stunde ab).
- Genehmigung über:
- Genehmigen über:
- `openclaw pairing list bluebubbles`
- `openclaw pairing approve bluebubbles <CODE>`
- Kopplung ist der standardmäßige Token-Austausch. Details: [Kopplung](/de/channels/pairing)
- Kopplung ist der Standard-Tokenaustausch. Details: [Pairing](/de/channels/pairing)
Gruppen:
- `channels.bluebubbles.groupPolicy = open | allowlist | disabled` (Standard: `allowlist`).
- `channels.bluebubbles.groupAllowFrom` steuert, wer in Gruppen Trigger auslösen kann, wenn `allowlist` gesetzt ist.
- `channels.bluebubbles.groupAllowFrom` steuert, wer in Gruppen Auslöser sein darf, wenn `allowlist` gesetzt ist.
### Anreicherung von Kontaktnamen (macOS, optional)
BlueBubbles-Gruppen-Webhooks enthalten oft nur rohe Teilnehmeradressen. Wenn der Kontext `GroupMembers` stattdessen lokale Kontaktnamen anzeigen soll, können Sie unter macOS die lokale Contacts-Anreicherung aktivieren:
- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` aktiviert die Suche. Standard: `false`.
- Suchen werden nur ausgeführt, nachdem Gruppenzugriff, Befehlsautorisierung und Mention-Gating die Nachricht zugelassen haben.
- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` aktiviert die Nachschlagefunktion. Standard: `false`.
- Nachschlagen erfolgt nur, nachdem Gruppenzugriff, Befehlsautorisierung und Mention-Gating die Nachricht durchgelassen haben.
- Nur unbenannte Telefonteilnehmer werden angereichert.
- Rohe Telefonnummern bleiben der Fallback, wenn keine lokale Übereinstimmung gefunden wird.
- Rohe Telefonnummern bleiben die Rückfalloption, wenn keine lokale Übereinstimmung gefunden wird.
```json5
{
@ -194,11 +194,11 @@ BlueBubbles-Gruppen-Webhooks enthalten oft nur rohe Teilnehmeradressen. Wenn der
### Mention-Gating (Gruppen)
BlueBubbles unterstützt Mention-Gating für Gruppenchats und entspricht damit dem Verhalten von iMessage/WhatsApp:
BlueBubbles unterstützt Mention-Gating für Gruppenchats, entsprechend dem Verhalten von iMessage/WhatsApp:
- Verwendet `agents.list[].groupChat.mentionPatterns` (oder `messages.groupChat.mentionPatterns`) zur Erkennung von Erwähnungen.
- Wenn `requireMention` für eine Gruppe aktiviert ist, antwortet der Agent nur, wenn er erwähnt wird.
- Kontrollbefehle von autorisierten Absendern umgehen das Mention-Gating.
- Steuerbefehle von autorisierten Absendern umgehen das Mention-Gating.
Konfiguration pro Gruppe:
@ -210,22 +210,22 @@ Konfiguration pro Gruppe:
groupAllowFrom: ["+15555550123"],
groups: {
"*": { requireMention: true }, // Standard für alle Gruppen
"iMessage;-;chat123": { requireMention: false }, // Überschreibung für bestimmte Gruppe
"iMessage;-;chat123": { requireMention: false }, // Überschreibung für eine bestimmte Gruppe
},
},
},
}
```
### Command-Gating
### Befehls-Gating
- Kontrollbefehle (z. B. `/config`, `/model`) erfordern eine Autorisierung.
- Steuerbefehle (z. B. `/config`, `/model`) erfordern Autorisierung.
- Verwendet `allowFrom` und `groupAllowFrom`, um die Befehlsautorisierung zu bestimmen.
- Autorisierte Absender können Kontrollbefehle auch ohne Erwähnung in Gruppen ausführen.
- Autorisierte Absender können Steuerbefehle auch ohne Erwähnung in Gruppen ausführen.
### Systemprompt pro Gruppe
### System-Prompt pro Gruppe
Jeder Eintrag unter `channels.bluebubbles.groups.*` akzeptiert einen optionalen String `systemPrompt`. Der Wert wird bei jeder Runde, die eine Nachricht in dieser Gruppe verarbeitet, in den Systemprompt des Agenten eingefügt, sodass Sie pro Gruppe Persona- oder Verhaltensregeln festlegen können, ohne Agent-Prompts zu bearbeiten:
Jeder Eintrag unter `channels.bluebubbles.groups.*` akzeptiert eine optionale Zeichenfolge `systemPrompt`. Der Wert wird bei jeder Verarbeitung einer Nachricht in dieser Gruppe in den System-Prompt des Agenten eingefügt, sodass Sie pro Gruppe Persona- oder Verhaltensregeln festlegen können, ohne Agent-Prompts zu bearbeiten:
```json5
{
@ -233,7 +233,7 @@ Jeder Eintrag unter `channels.bluebubbles.groups.*` akzeptiert einen optionalen
bluebubbles: {
groups: {
"iMessage;-;chat123": {
systemPrompt: "Halte Antworten unter 3 Sätzen. Übernimm den lockeren Ton der Gruppe.",
systemPrompt: "Halte Antworten unter 3 Sätzen. Spiegele den lockeren Ton der Gruppe.",
},
},
},
@ -241,11 +241,11 @@ Jeder Eintrag unter `channels.bluebubbles.groups.*` akzeptiert einen optionalen
}
```
Der Schlüssel entspricht allem, was BlueBubbles als `chatGuid` / `chatIdentifier` / numerische `chatId` für die Gruppe meldet, und ein Platzhalter-Eintrag `"*"` stellt einen Standard für jede Gruppe ohne exakte Übereinstimmung bereit (dasselbe Muster wird für `requireMention` und Tool-Richtlinien pro Gruppe verwendet). Exakte Übereinstimmungen haben immer Vorrang vor dem Platzhalter. DMs ignorieren dieses Feld; verwenden Sie stattdessen Anpassungen auf Agenten- oder Kontoebene.
Der Schlüssel entspricht dem, was BlueBubbles für die Gruppe als `chatGuid` / `chatIdentifier` / numerische `chatId` meldet, und ein Platzhaltereintrag `"*"` stellt einen Standard für jede Gruppe ohne exakte Übereinstimmung bereit (dasselbe Muster wird von `requireMention` und gruppenspezifischen Tool-Richtlinien verwendet). Exakte Übereinstimmungen haben immer Vorrang vor dem Platzhalter. DMs ignorieren dieses Feld; verwenden Sie stattdessen Prompt-Anpassungen auf Agenten- oder Kontoebene.
#### Durchgearbeitetes Beispiel: Thread-Antworten und Tapback-Reaktionen (Private API)
#### Ausgearbeitetes Beispiel: Thread-Antworten und Tapback-Reaktionen (Private API)
Wenn die BlueBubbles Private API aktiviert ist, kommen eingehende Nachrichten mit kurzen Nachrichten-IDs an (zum Beispiel `[[reply_to:5]]`), und der Agent kann `action=reply` aufrufen, um in eine bestimmte Nachricht zu threaden, oder `action=react`, um ein Tapback zu setzen. Ein `systemPrompt` pro Gruppe ist eine zuverlässige Möglichkeit, damit der Agent das richtige Tool auswählt:
Mit aktivierter BlueBubbles Private API kommen eingehende Nachrichten mit kurzen Nachrichten-IDs an (zum Beispiel `[[reply_to:5]]`), und der Agent kann `action=reply` aufrufen, um in eine bestimmte Nachricht zu threaden, oder `action=react`, um ein Tapback zu setzen. Ein `systemPrompt` pro Gruppe ist eine zuverlässige Möglichkeit, damit der Agent das richtige Tool auswählt:
```json5
{
@ -255,12 +255,12 @@ Wenn die BlueBubbles Private API aktiviert ist, kommen eingehende Nachrichten mi
"iMessage;+;chat-family": {
systemPrompt: [
"Wenn du in dieser Gruppe antwortest, rufe immer action=reply mit der",
"messageId `[[reply_to:N]]` aus dem Kontext auf, damit deine Antwort",
"unter der auslösenden Nachricht eingeordnet wird. Sende niemals eine neue, nicht verknüpfte Nachricht.",
"[[reply_to:N]] messageId aus dem Kontext auf, damit deine Antwort",
"unter der auslösenden Nachricht gethreadet wird. Sende niemals eine neue, nicht verknüpfte Nachricht.",
"",
"Verwende für kurze Bestätigungen ('ok', 'verstanden', 'bin dran')",
"action=react mit einem passenden Tapback-Emoji (❤️, 👍, 😂, ‼️, ❓)",
"anstatt eine Textantwort zu senden.",
"anstelle einer Textantwort.",
].join(" "),
},
},
@ -269,20 +269,20 @@ Wenn die BlueBubbles Private API aktiviert ist, kommen eingehende Nachrichten mi
}
```
Tapback-Reaktionen und Thread-Antworten erfordern beide die BlueBubbles Private API; siehe [Erweiterte Aktionen](#advanced-actions) und [Nachrichten-IDs](#message-ids-short-vs-full) für die zugrunde liegende Mechanik.
Tapback-Reaktionen und Thread-Antworten erfordern beide die BlueBubbles Private API; die zugrunde liegenden Mechanismen finden Sie unter [Erweiterte Aktionen](#advanced-actions) und [Nachrichten-IDs](#message-ids-short-vs-full).
## ACP-Gesprächsbindungen
BlueBubbles-Chats können in dauerhafte ACP-Workspaces umgewandelt werden, ohne die Transportschicht zu ändern.
BlueBubbles-Chats können in dauerhafte ACP-Arbeitsbereiche umgewandelt werden, ohne die Transportebene zu ändern.
Schneller Operator-Ablauf:
- Führen Sie `/acp spawn codex --bind here` innerhalb des DM- oder erlaubten Gruppenchats aus.
- Zukünftige Nachrichten in derselben BlueBubbles-Konversation werden an die erzeugte ACP-Sitzung weitergeleitet.
- Künftige Nachrichten in derselben BlueBubbles-Konversation werden an die erzeugte ACP-Sitzung weitergeleitet.
- `/new` und `/reset` setzen dieselbe gebundene ACP-Sitzung an Ort und Stelle zurück.
- `/acp close` schließt die ACP-Sitzung und entfernt die Bindung.
Konfigurierte persistente Bindungen werden ebenfalls über Top-Level-Einträge `bindings[]` mit `type: "acp"` und `match.channel: "bluebubbles"` unterstützt.
Konfigurierte persistente Bindungen werden auch über Top-Level-Einträge `bindings[]` mit `type: "acp"` und `match.channel: "bluebubbles"` unterstützt.
`match.peer.id` kann jede unterstützte BlueBubbles-Zielform verwenden:
@ -291,7 +291,7 @@ Konfigurierte persistente Bindungen werden ebenfalls über Top-Level-Einträge `
- `chat_guid:<guid>`
- `chat_identifier:<identifier>`
Für stabile Gruppenbindungen sollten Sie `chat_id:*` oder `chat_identifier:*` bevorzugen.
Für stabile Gruppenbindungen bevorzugen Sie `chat_id:*` oder `chat_identifier:*`.
Beispiel:
@ -323,13 +323,13 @@ Beispiel:
}
```
Siehe [ACP Agents](/de/tools/acp-agents) für gemeinsames ACP-Bindungsverhalten.
Siehe [ACP Agents](/de/tools/acp-agents) für das gemeinsame Verhalten von ACP-Bindungen.
## Tippen + Lesebestätigungen
## Tippindikatoren + Lesebestätigungen
- **Tippindikatoren**: Werden automatisch vor und während der Antwortgenerierung gesendet.
- **Lesebestätigungen**: Gesteuert durch `channels.bluebubbles.sendReadReceipts` (Standard: `true`).
- **Tippindikatoren**: OpenClaw sendet Ereignisse für den Tippbeginn; BlueBubbles beendet das Tippen beim Senden oder nach einem Timeout automatisch (manuelles Stoppen über DELETE ist unzuverlässig).
- **Tippindikatoren**: OpenClaw sendet Tippstart-Ereignisse; BlueBubbles entfernt den Tippstatus beim Senden oder per Timeout automatisch (manuelles Stoppen per DELETE ist unzuverlässig).
```json5
{
@ -351,12 +351,12 @@ BlueBubbles unterstützt erweiterte Nachrichtenaktionen, wenn sie in der Konfigu
bluebubbles: {
actions: {
reactions: true, // Tapbacks (Standard: true)
edit: true, // gesendete Nachrichten bearbeiten (macOS 13+, auf macOS 26 Tahoe defekt)
edit: true, // gesendete Nachrichten bearbeiten (macOS 13+, defekt unter macOS 26 Tahoe)
unsend: true, // Nachrichten zurückziehen (macOS 13+)
reply: true, // Antwort-Threading nach Nachrichten-GUID
reply: true, // Antwort-Threading per Nachrichten-GUID
sendWithEffect: true, // Nachrichteneffekte (slam, loud usw.)
renameGroup: true, // Gruppenchats umbenennen
setGroupIcon: true, // Gruppenchatsymbol/-foto festlegen (instabil auf macOS 26 Tahoe)
setGroupIcon: true, // Gruppenchatsymbol/-foto festlegen (unzuverlässig unter macOS 26 Tahoe)
addParticipant: true, // Teilnehmer zu Gruppen hinzufügen
removeParticipant: true, // Teilnehmer aus Gruppen entfernen
leaveGroup: true, // Gruppenchats verlassen
@ -375,29 +375,127 @@ Verfügbare Aktionen:
- **reply**: Auf eine bestimmte Nachricht antworten (`messageId`, `text`, `to`)
- **sendWithEffect**: Mit iMessage-Effekt senden (`text`, `to`, `effectId`)
- **renameGroup**: Einen Gruppenchat umbenennen (`chatGuid`, `displayName`)
- **setGroupIcon**: Das Symbol/Foto eines Gruppenchats festlegen (`chatGuid`, `media`) — instabil auf macOS 26 Tahoe (API kann Erfolg zurückgeben, aber das Symbol synchronisiert nicht).
- **setGroupIcon**: Das Symbol/Foto eines Gruppenchats festlegen (`chatGuid`, `media`) — unzuverlässig unter macOS 26 Tahoe (die API kann Erfolg zurückgeben, aber das Symbol wird nicht synchronisiert).
- **addParticipant**: Jemanden zu einer Gruppe hinzufügen (`chatGuid`, `address`)
- **removeParticipant**: Jemanden aus einer Gruppe entfernen (`chatGuid`, `address`)
- **leaveGroup**: Einen Gruppenchat verlassen (`chatGuid`)
- **upload-file**: Medien/Dateien senden (`to`, `buffer`, `filename`, `asVoice`)
- Sprachmemos: Setzen Sie `asVoice: true` mit **MP3**- oder **CAF**-Audio, um es als iMessage-Sprachnachricht zu senden. BlueBubbles konvertiert MP3 → CAF beim Senden von Sprachmemos.
- Legacy-Alias: `sendAttachment` funktioniert weiterhin, aber `upload-file` ist der kanonische Aktionsname.
- Sprachnachrichten: Setzen Sie `asVoice: true` mit **MP3**- oder **CAF**-Audio, um als iMessage-Sprachnachricht zu senden. BlueBubbles konvertiert beim Senden von Sprachnotizen MP3 → CAF.
- Veralteter Alias: `sendAttachment` funktioniert weiterhin, aber `upload-file` ist der kanonische Aktionsname.
### Nachrichten-IDs (kurz vs. vollständig)
OpenClaw kann _kurze_ Nachrichten-IDs (z. B. `1`, `2`) bereitstellen, um Tokens zu sparen.
- `MessageSid` / `ReplyToId` können kurze IDs sein.
- `MessageSidFull` / `ReplyToIdFull` enthalten die vollständigen Provider-IDs.
- Kurze IDs sind im Speicher; sie können nach einem Neustart oder einer Cache-Bereinigung ablaufen.
- Aktionen akzeptieren kurze oder vollständige `messageId`, aber kurze IDs erzeugen einen Fehler, wenn sie nicht mehr verfügbar sind.
- `MessageSidFull` / `ReplyToIdFull` enthalten die vollständigen IDs des Providers.
- Kurze IDs sind im Speicher; sie können bei einem Neustart oder bei Cache-Verdrängung verfallen.
- Aktionen akzeptieren kurze oder vollständige `messageId`, aber kurze IDs führen zu Fehlern, wenn sie nicht mehr verfügbar sind.
Verwenden Sie vollständige IDs für dauerhafte Automatisierungen und Speicherung:
- Templates: `{{MessageSidFull}}`, `{{ReplyToIdFull}}`
- Vorlagen: `{{MessageSidFull}}`, `{{ReplyToIdFull}}`
- Kontext: `MessageSidFull` / `ReplyToIdFull` in eingehenden Payloads
Siehe [Konfiguration](/de/gateway/configuration) für Template-Variablen.
Siehe [Konfiguration](/de/gateway/configuration) für Vorlagenvariablen.
## Zusammenführen von Split-Send-DMs (Befehl + URL in einer Eingabe)
Wenn ein Benutzer in iMessage einen Befehl und eine URL zusammen eingibt – z. B. `Dump https://example.com/article` – teilt Apple das Senden in **zwei separate Webhook-Zustellungen** auf:
1. Eine Textnachricht (`"Dump"`).
2. Eine URL-Vorschau-Bubble (`"https://..."`) mit OG-Vorschaubildern als Anhänge.
Die beiden Webhooks treffen bei OpenClaw auf den meisten Setups mit etwa 0,8–2,0 s Abstand ein. Ohne Zusammenführung erhält der Agent in Turn 1 nur den Befehl, antwortet (oft mit „schick mir die URL“), und sieht die URL erst in Turn 2 – zu diesem Zeitpunkt ist der Befehlskontext bereits verloren.
`channels.bluebubbles.coalesceSameSenderDms` aktiviert für DMs das Zusammenführen aufeinanderfolgender Webhooks desselben Absenders in einen einzigen Agent-Turn. Gruppenchats bleiben weiter nach Nachricht getrennt, damit die Turn-Struktur mit mehreren Benutzern erhalten bleibt.
### Wann aktivieren
Aktivieren Sie dies, wenn:
- Sie Skills bereitstellen, die `Befehl + Payload` in einer Nachricht erwarten (dump, paste, save, queue usw.).
- Ihre Benutzer URLs, Bilder oder lange Inhalte zusammen mit Befehlen einfügen.
- Sie die zusätzliche DM-Turn-Latenz akzeptieren können (siehe unten).
Lassen Sie es deaktiviert, wenn:
- Sie minimale Befehlslatenz für einwortige DM-Trigger benötigen.
- Alle Ihre Abläufe One-Shot-Befehle ohne nachfolgende Payloads sind.
### Aktivierung
```json5
{
channels: {
bluebubbles: {
coalesceSameSenderDms: true, // aktivieren (Standard: false)
},
},
}
```
Mit aktiviertem Flag und ohne explizites `messages.inbound.byChannel.bluebubbles` erweitert sich das Debounce-Fenster auf **2500 ms** (der Standard ohne Zusammenführung beträgt 500 ms). Das breitere Fenster ist erforderlich – Apples Split-Send-Takt von 0,8–2,0 s passt nicht in das engere Standardfenster.
So passen Sie das Fenster selbst an:
```json5
{
messages: {
inbound: {
byChannel: {
// 2500 ms funktionieren für die meisten Setups; erhöhen Sie auf 4000 ms,
// wenn Ihr Mac langsam ist oder unter Speicherdruck steht
// (die beobachtete Lücke kann dann über 2 s hinausgehen).
bluebubbles: 2500,
},
},
},
}
```
### Abwägungen
- **Zusätzliche Latenz für DM-Steuerbefehle.** Mit aktiviertem Flag warten DM-Steuerbefehle (wie `Dump`, `Save` usw.) nun bis zur Länge des Debounce-Fensters vor dem Versand, falls ein Payload-Webhook folgt. Befehle in Gruppenchats werden weiterhin sofort versendet.
- **Zusammengeführte Ausgabe ist begrenzt** – zusammengeführter Text ist auf 4000 Zeichen mit einem expliziten Marker `…[truncated]` begrenzt; Anhänge sind auf 20 begrenzt; Quelleneinträge sind auf 10 begrenzt (darüber hinaus bleiben erster und neuester erhalten). Jede Quell-`messageId` erreicht weiterhin die Inbound-Deduplizierung, sodass ein späteres MessagePoller-Replay eines einzelnen Ereignisses als Duplikat erkannt wird.
- **Opt-in, pro Kanal.** Andere Kanäle (Telegram, WhatsApp, Slack, …) sind nicht betroffen.
### Szenarien und was der Agent sieht
| Benutzer gibt ein | Apple liefert | Flag aus (Standard) | Flag an + 2500-ms-Fenster |
| ------------------------------------------------------------------- | ------------------------- | --------------------------------------- | ---------------------------------------------------------------------- |
| `Dump https://example.com` (einmal senden) | 2 Webhooks mit ~1 s Abstand | Zwei Agent-Turns: nur „Dump“, dann URL | Ein Turn: zusammengeführter Text `Dump https://example.com` |
| `Save this 📎image.jpg caption` (Anhang + Text) | 2 Webhooks | Zwei Turns | Ein Turn: Text + Bild |
| `/status` (eigenständiger Befehl) | 1 Webhook | Sofortiger Versand | **Wartet bis zum Fensterende, dann Versand** |
| Nur URL eingefügt | 1 Webhook | Sofortiger Versand | Sofortiger Versand (nur ein Eintrag im Bucket) |
| Text + URL als zwei bewusst getrennte Nachrichten, Minuten auseinander gesendet | 2 Webhooks außerhalb des Fensters | Zwei Turns | Zwei Turns (Fenster läuft dazwischen ab) |
| Schnelle Flut (>10 kleine DMs innerhalb des Fensters) | N Webhooks | N Turns | Ein Turn, begrenzte Ausgabe (erster + neuester, Text-/Anhang-Limits angewendet) |
### Fehlerbehebung für das Zusammenführen von Split-Sends
Wenn das Flag aktiviert ist und Split-Sends trotzdem als zwei Turns ankommen, prüfen Sie jede Ebene:
1. **Konfiguration tatsächlich geladen.**
```
grep coalesceSameSenderDms ~/.openclaw/openclaw.json
```
Dann `openclaw gateway restart` – das Flag wird bei der Erstellung der Debouncer-Registry eingelesen.
2. **Debounce-Fenster breit genug für Ihr Setup.** Sehen Sie sich das BlueBubbles-Serverlog unter `~/Library/Logs/bluebubbles-server/main.log` an:
```
grep -E "Dispatching event to webhook" main.log | tail -20
```
Messen Sie die Lücke zwischen dem Versand des Textes im Stil von `"Dump"` und dem nachfolgenden Versand `"https://..."; Attachments:`. Erhöhen Sie `messages.inbound.byChannel.bluebubbles`, sodass diese Lücke sicher abgedeckt ist.
3. **JSONL-Zeitstempel der Sitzung ≠ Webhook-Ankunft.** Zeitstempel von Sitzungsereignissen (`~/.openclaw/agents/<id>/sessions/*.jsonl`) zeigen den Zeitpunkt, zu dem das Gateway eine Nachricht an den Agenten übergibt, **nicht** den Zeitpunkt, zu dem der Webhook eingetroffen ist. Eine in die Warteschlange gestellte zweite Nachricht mit dem Tag `[Queued messages while agent was busy]` bedeutet, dass der erste Turn noch lief, als der zweite Webhook eintraf – der Coalesce-Bucket war bereits geleert. Stimmen Sie das Fenster auf das BB-Serverlog ab, nicht auf das Sitzungslog.
4. **Speicherdruck verlangsamt den Antwortversand.** Auf kleineren Maschinen (8 GB) können Agent-Turns so lange dauern, dass der Coalesce-Bucket geleert wird, bevor die Antwort fertig ist, und die URL als zweiter Turn in der Warteschlange landet. Prüfen Sie `memory_pressure` und `ps -o rss -p $(pgrep openclaw-gateway)`; wenn das Gateway über ~500 MB RSS liegt und der Compressor aktiv ist, schließen Sie andere schwere Prozesse oder wechseln Sie auf einen größeren Host.
5. **Senden mit Antwortzitat ist ein anderer Pfad.** Wenn der Benutzer `Dump` als **Antwort** auf eine vorhandene URL-Bubble getippt hat (iMessage zeigt auf der Dump-Bubble ein Abzeichen „1 Reply“), befindet sich die URL in `replyToBody`, nicht in einem zweiten Webhook. Zusammenführung greift hier nicht – das ist ein Thema für Skill/Prompt, nicht für den Debouncer.
## Block-Streaming
@ -416,8 +514,8 @@ Steuern Sie, ob Antworten als einzelne Nachricht gesendet oder in Blöcken gestr
## Medien + Limits
- Eingehende Anhänge werden heruntergeladen und im Medien-Cache gespeichert.
- Medienobergrenze über `channels.bluebubbles.mediaMaxMb` für ein- und ausgehende Medien (Standard: 8 MB).
- Ausgehender Text wird auf `channels.bluebubbles.textChunkLimit` gestückelt (Standard: 4000 Zeichen).
- Medienlimit über `channels.bluebubbles.mediaMaxMb` für eingehende und ausgehende Medien (Standard: 8 MB).
- Ausgehender Text wird auf `channels.bluebubbles.textChunkLimit` segmentiert (Standard: 4000 Zeichen).
## Konfigurationsreferenz
@ -425,29 +523,30 @@ Vollständige Konfiguration: [Konfiguration](/de/gateway/configuration)
Provider-Optionen:
- `channels.bluebubbles.enabled`: Den Kanal aktivieren/deaktivieren.
- `channels.bluebubbles.serverUrl`: BlueBubbles-REST-API-Basis-URL.
- `channels.bluebubbles.enabled`: Kanal aktivieren/deaktivieren.
- `channels.bluebubbles.serverUrl`: Basis-URL der BlueBubbles-REST-API.
- `channels.bluebubbles.password`: API-Passwort.
- `channels.bluebubbles.webhookPath`: Pfad des Webhook-Endpunkts (Standard: `/bluebubbles-webhook`).
- `channels.bluebubbles.dmPolicy`: `pairing | allowlist | open | disabled` (Standard: `pairing`).
- `channels.bluebubbles.allowFrom`: DM-Allowlist (Handles, E-Mails, E.164-Nummern, `chat_id:*`, `chat_guid:*`).
- `channels.bluebubbles.groupPolicy`: `open | allowlist | disabled` (Standard: `allowlist`).
- `channels.bluebubbles.groupAllowFrom`: Absender-Allowlist für Gruppen.
- `channels.bluebubbles.enrichGroupParticipantsFromContacts`: Unter macOS unbenannte Gruppenteilnehmer optional aus lokalen Contacts anreichern, nachdem das Gating bestanden wurde. Standard: `false`.
- `channels.bluebubbles.groupAllowFrom`: Allowlist für Gruppenabsender.
- `channels.bluebubbles.enrichGroupParticipantsFromContacts`: Unter macOS unbenannte Gruppenteilnehmer nach erfolgreichem Gating optional mit lokalen Kontakten anreichern. Standard: `false`.
- `channels.bluebubbles.groups`: Konfiguration pro Gruppe (`requireMention` usw.).
- `channels.bluebubbles.sendReadReceipts`: Lesebestätigungen senden (Standard: `true`).
- `channels.bluebubbles.blockStreaming`: Block-Streaming aktivieren (Standard: `false`; erforderlich für Streaming-Antworten).
- `channels.bluebubbles.textChunkLimit`: Größe ausgehender Blöcke in Zeichen (Standard: 4000).
- `channels.bluebubbles.sendTimeoutMs`: Timeout pro Anfrage in ms für ausgehende Textsendungen über `/api/v1/message/text` (Standard: 30000). Erhöhen Sie diesen Wert auf macOS-26-Setups, bei denen iMessage-Sendungen über die Private API im iMessage-Framework 60+ Sekunden hängen können; zum Beispiel `45000` oder `60000`. Probes, Chat-Lookups, Reaktionen, Bearbeitungen und Zustandsprüfungen behalten derzeit den kürzeren Standardwert von 10 s; eine Ausweitung auf Reaktionen und Bearbeitungen ist als Folgearbeit geplant. Überschreibung pro Konto: `channels.bluebubbles.accounts.<accountId>.sendTimeoutMs`.
- `channels.bluebubbles.chunkMode`: `length` (Standard) teilt nur, wenn `textChunkLimit` überschritten wird; `newline` teilt an Leerzeilen (Absatzgrenzen) vor der Längenteilung.
- `channels.bluebubbles.mediaMaxMb`: Medienobergrenze für ein- und ausgehende Medien in MB (Standard: 8).
- `channels.bluebubbles.sendTimeoutMs`: Timeout pro Anfrage in ms für ausgehende Textsendungen über `/api/v1/message/text` (Standard: 30000). Erhöhen Sie dies auf macOS-26-Setups, bei denen Private-API-iMessage-Sendungen im iMessage-Framework 60+ Sekunden hängen können, z. B. auf `45000` oder `60000`. Probes, Chat-Lookups, Reaktionen, Bearbeitungen und Health Checks behalten derzeit den kürzeren Standard von 10 s; eine Ausweitung auf Reaktionen und Bearbeitungen ist als Follow-up geplant. Überschreibung pro Konto: `channels.bluebubbles.accounts.<accountId>.sendTimeoutMs`.
- `channels.bluebubbles.chunkMode`: `length` (Standard) teilt nur, wenn `textChunkLimit` überschritten wird; `newline` teilt an Leerzeilen (Absatzgrenzen) vor der Längensegmentierung.
- `channels.bluebubbles.mediaMaxMb`: Medienlimit für ein- und ausgehende Medien in MB (Standard: 8).
- `channels.bluebubbles.mediaLocalRoots`: Explizite Allowlist absoluter lokaler Verzeichnisse, die für ausgehende lokale Medienpfade erlaubt sind. Das Senden lokaler Pfade wird standardmäßig verweigert, sofern dies nicht konfiguriert ist. Überschreibung pro Konto: `channels.bluebubbles.accounts.<accountId>.mediaLocalRoots`.
- `channels.bluebubbles.coalesceSameSenderDms`: Führt aufeinanderfolgende DM-Webhooks desselben Absenders zu einem Agent-Turn zusammen, sodass Apples Split-Send von Text+URL als eine einzelne Nachricht ankommt (Standard: `false`). Siehe [Zusammenführen von Split-Send-DMs](#coalescing-split-send-dms-command--url-in-one-composition) für Szenarien, Fenstertuning und Abwägungen. Erweitert das Standard-Debounce-Fenster für eingehende Nachrichten von 500 ms auf 2500 ms, wenn aktiviert, ohne ein explizites `messages.inbound.byChannel.bluebubbles`.
- `channels.bluebubbles.historyLimit`: Maximale Anzahl an Gruppennachrichten für den Kontext (0 deaktiviert).
- `channels.bluebubbles.dmHistoryLimit`: DM-Verlaufslimit.
- `channels.bluebubbles.dmHistoryLimit`: Verlaufslimit für DMs.
- `channels.bluebubbles.actions`: Bestimmte Aktionen aktivieren/deaktivieren.
- `channels.bluebubbles.accounts`: Multi-Account-Konfiguration.
Verwandte globale Optionen:
Zugehörige globale Optionen:
- `agents.list[].groupChat.mentionPatterns` (oder `messages.groupChat.mentionPatterns`).
- `messages.responsePrefix`.
@ -460,31 +559,32 @@ Bevorzugen Sie `chat_guid` für stabiles Routing:
- `chat_id:123`
- `chat_identifier:...`
- Direkte Handles: `+15555550123`, `user@example.com`
- Wenn für ein direktes Handle noch kein DM-Chat existiert, erstellt OpenClaw einen über `POST /api/v1/chat/new`. Dafür muss die BlueBubbles Private API aktiviert sein.
- Wenn ein direkter Handle keinen bestehenden DM-Chat hat, erstellt OpenClaw einen über `POST /api/v1/chat/new`. Dafür muss die BlueBubbles Private API aktiviert sein.
## Sicherheit
- Webhook-Anfragen werden authentifiziert, indem `guid`-/`password`-Query-Parameter oder Header mit `channels.bluebubbles.password` verglichen werden.
- Halten Sie das API-Passwort und den Webhook-Endpunkt geheim (behandeln Sie sie wie Zugangsdaten).
- Es gibt keinen Localhost-Bypass für die BlueBubbles-Webhook-Authentifizierung. Wenn Sie Webhook-Datenverkehr proxyen, behalten Sie das BlueBubbles-Passwort Ende-zu-Ende in der Anfrage bei. `gateway.trustedProxies` ersetzt `channels.bluebubbles.password` hier nicht. Siehe [Gateway-Sicherheit](/de/gateway/security#reverse-proxy-configuration).
- Es gibt keine localhost-Umgehung für die BlueBubbles-Webhook-Authentifizierung. Wenn Sie Webhook-Traffic per Proxy weiterleiten, behalten Sie das BlueBubbles-Passwort Ende-zu-Ende in der Anfrage bei. `gateway.trustedProxies` ersetzt `channels.bluebubbles.password` hier nicht. Siehe [Gateway-Sicherheit](/de/gateway/security#reverse-proxy-configuration).
- Aktivieren Sie HTTPS + Firewall-Regeln auf dem BlueBubbles-Server, wenn Sie ihn außerhalb Ihres LAN bereitstellen.
## Fehlerbehebung
- Wenn Tipp-/Leseereignisse nicht mehr funktionieren, prüfen Sie die BlueBubbles-Webhook-Logs und vergewissern Sie sich, dass der Gateway-Pfad mit `channels.bluebubbles.webhookPath` übereinstimmt.
- Kopplungscodes laufen nach einer Stunde ab; verwenden Sie `openclaw pairing list bluebubbles` und `openclaw pairing approve bluebubbles <code>`.
- Kopplungscodes verfallen nach einer Stunde; verwenden Sie `openclaw pairing list bluebubbles` und `openclaw pairing approve bluebubbles <code>`.
- Reaktionen erfordern die BlueBubbles Private API (`POST /api/v1/message/react`); stellen Sie sicher, dass die Serverversion sie bereitstellt.
- Bearbeiten/Zurückziehen erfordern macOS 13+ und eine kompatible BlueBubbles-Serverversion. Unter macOS 26 (Tahoe) ist Bearbeiten derzeit aufgrund von Änderungen an der Private API defekt.
- Aktualisierungen von Gruppensymbolen können unter macOS 26 (Tahoe) instabil sein: Die API kann Erfolg zurückgeben, aber das neue Symbol synchronisiert nicht.
- OpenClaw blendet bekannte defekte Aktionen basierend auf der macOS-Version des BlueBubbles-Servers automatisch aus. Wenn Bearbeiten unter macOS 26 (Tahoe) weiterhin angezeigt wird, deaktivieren Sie es manuell mit `channels.bluebubbles.actions.edit=false`.
- Aktualisierungen von Gruppensymbolen können unter macOS 26 (Tahoe) unzuverlässig sein: Die API kann Erfolg melden, aber das neue Symbol wird nicht synchronisiert.
- OpenClaw blendet bekannte defekte Aktionen anhand der macOS-Version des BlueBubbles-Servers automatisch aus. Wenn Bearbeiten unter macOS 26 (Tahoe) weiterhin angezeigt wird, deaktivieren Sie es manuell mit `channels.bluebubbles.actions.edit=false`.
- `coalesceSameSenderDms` ist aktiviert, aber Split-Sends (z. B. `Dump` + URL) kommen weiterhin als zwei Turns an: siehe die Checkliste zur [Fehlerbehebung für das Zusammenführen von Split-Sends](#split-send-coalescing-troubleshooting) — häufige Ursachen sind ein zu enges Debounce-Fenster, Sitzungslog-Zeitstempel, die fälschlich als Webhook-Ankunft interpretiert werden, oder ein Senden mit Antwortzitat (das `replyToBody` verwendet, nicht einen zweiten Webhook).
- Für Status-/Health-Informationen: `openclaw status --all` oder `openclaw status --deep`.
Für allgemeine Referenzen zum Kanalablauf siehe [Kanäle](/de/channels) und den Leitfaden [Plugins](/de/tools/plugin).
Eine allgemeine Referenz zum Kanal-Workflow finden Sie unter [Kanäle](/de/channels) und im Leitfaden [Plugins](/de/tools/plugin).
## Verwandt
- [Kanalübersicht](/de/channels) — alle unterstützten Kanäle
- [Kopplung](/de/channels/pairing) — DM-Authentifizierung und Kopplungsablauf
- [Gruppen](/de/channels/groups) — Verhalten von Gruppenchats und Mention-Gating
- [Pairing](/de/channels/pairing) — DM-Authentifizierung und Kopplungsablauf
- [Gruppen](/de/channels/groups) — Verhalten in Gruppenchats und Mention-Gating
- [Kanal-Routing](/de/channels/channel-routing) — Sitzungsrouting für Nachrichten
- [Sicherheit](/de/gateway/security) — Zugriffsmodell und Härtung

262
docs/de/channels/slack.md
View File

@ -4,10 +4,10 @@ read_when:
summary: Slack-Einrichtung und Laufzeitverhalten (Socket Mode + HTTP-Request-URLs)
title: Slack
x-i18n:
generated_at: "2026-04-12T23:27:58Z"
generated_at: "2026-04-21T13:35:27Z"
model: gpt-5.4
provider: openai
source_hash: 4b80c1a612b8815c46c675b688639c207a481f367075996dde3858a83637313b
source_hash: 2fe3c3c344e1c20c09b29773f4f68d2790751e76d8bbaa3c6157e3ff75978acf
source_path: channels/slack.md
workflow: 15
---
@ -36,10 +36,10 @@ Status: produktionsreif für DMs + Channels über Slack-App-Integrationen. Der S
<Step title="Eine neue Slack-App erstellen">
Klicken Sie in den Slack-App-Einstellungen auf die Schaltfläche **[Create New App](https://api.slack.com/apps/new)**:
- wählen Sie **from a manifest** und wählen Sie einen Workspace für Ihre App aus
- fügen Sie das [Beispielmanifest](#manifest-and-scope-checklist) von unten ein und fahren Sie mit dem Erstellen fort
- generieren Sie ein **App-Level-Token** (`xapp-...`) mit `connections:write`
- installieren Sie die App und kopieren Sie das angezeigte **Bot-Token** (`xoxb-...`)
- Wählen Sie **from a manifest** und wählen Sie einen Workspace für Ihre App aus
- Fügen Sie das [Beispiel-Manifest](#manifest-and-scope-checklist) von unten ein und fahren Sie mit der Erstellung fort
- Erzeugen Sie ein **App-Level-Token** (`xapp-...`) mit `connections:write`
- Installieren Sie die App und kopieren Sie das angezeigte **Bot Token** (`xoxb-...`)
</Step>
<Step title="OpenClaw konfigurieren">
@ -82,10 +82,10 @@ openclaw gateway
<Step title="Eine neue Slack-App erstellen">
Klicken Sie in den Slack-App-Einstellungen auf die Schaltfläche **[Create New App](https://api.slack.com/apps/new)**:
- wählen Sie **from a manifest** und wählen Sie einen Workspace für Ihre App aus
- fügen Sie das [Beispielmanifest](#manifest-and-scope-checklist) ein und aktualisieren Sie die URLs vor dem Erstellen
- speichern Sie das **Signing Secret** für die Anfrageverifizierung
- installieren Sie die App und kopieren Sie das angezeigte **Bot-Token** (`xoxb-...`)
- Wählen Sie **from a manifest** und wählen Sie einen Workspace für Ihre App aus
- Fügen Sie das [Beispiel-Manifest](#manifest-and-scope-checklist) ein und aktualisieren Sie die URLs vor der Erstellung
- Speichern Sie das **Signing Secret** für die Request-Verifizierung
- Installieren Sie die App und kopieren Sie das angezeigte **Bot Token** (`xoxb-...`)
</Step>
@ -289,16 +289,16 @@ openclaw gateway
</Tab>
</Tabs>
### Zusätzliche Manifesteinstellungen
### Zusätzliche Manifest-Einstellungen
Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellungen erweitern.
Machen Sie unterschiedliche Funktionen sichtbar, die die oben genannten Standardwerte erweitern.
<AccordionGroup>
<Accordion title="Optionale native Slash-Befehle">
Mehrere [native Slash-Befehle](#commands-and-slash-behavior) können mit Nuancen anstelle eines einzelnen konfigurierten Befehls verwendet werden:
Mehrere [native Slash-Befehle](#commands-and-slash-behavior) können statt eines einzelnen konfigurierten Befehls mit gewissen Besonderheiten verwendet werden:
- Verwenden Sie `/agentstatus` anstelle von `/status`, weil der Befehl `/status` reserviert ist.
- Verwenden Sie `/agentstatus` anstelle von `/status`, da der Befehl `/status` reserviert ist.
- Es können nicht mehr als 25 Slash-Befehle gleichzeitig verfügbar gemacht werden.
Ersetzen Sie Ihren vorhandenen Abschnitt `features.slash_commands` durch eine Teilmenge der [verfügbaren Befehle](/de/tools/slash-commands#command-list):
@ -333,8 +333,8 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge
},
{
"command": "/think",
"description": "Die Denkstufe festlegen",
"usage_hint": "<off|minimal|low|medium|high|xhigh>"
"description": "Das Denk-Level festlegen",
"usage_hint": "<level>"
},
{
"command": "/verbose",
@ -348,7 +348,7 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge
},
{
"command": "/reasoning",
"description": "Sichtbarkeit von Begründungen umschalten",
"description": "Sichtbarkeit der Begründung umschalten",
"usage_hint": "[on|off|stream]"
},
{
@ -358,7 +358,7 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge
},
{
"command": "/exec",
"description": "Exec-Standardeinstellungen anzeigen oder festlegen",
"description": "Exec-Standards anzeigen oder festlegen",
"usage_hint": "host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>"
},
{
@ -368,7 +368,7 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge
},
{
"command": "/models",
"description": "Anbieter oder Modelle für einen Anbieter auflisten",
"description": "Provider oder Modelle für einen Provider auflisten",
"usage_hint": "[provider] [page] [limit=<n>|size=<n>|all]"
},
{
@ -386,7 +386,7 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge
},
{
"command": "/agentstatus",
"description": "Laufzeitstatus anzeigen, einschließlich Anbieternutzung/Kontingent, wenn verfügbar"
"description": "Laufzeitstatus anzeigen, einschließlich Provider-Nutzung/Kontingent, falls verfügbar"
},
{
"command": "/tasks",
@ -399,11 +399,11 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge
},
{
"command": "/whoami",
"description": "Ihre Absenderidentität anzeigen"
"description": "Ihre Sender-Identität anzeigen"
},
{
"command": "/skill",
"description": "Eine Skill anhand des Namens ausführen",
"description": "Eine Skills nach Namen ausführen",
"usage_hint": "<name> [input]"
},
{
@ -413,7 +413,7 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge
},
{
"command": "/usage",
"description": "Die Nutzungsfußzeile steuern oder Kostenzusammenfassung anzeigen",
"description": "Die Nutzungsfußzeile steuern oder die Kostenzusammenfassung anzeigen",
"usage_hint": "off|tokens|full|cost"
}
]
@ -454,8 +454,8 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge
},
{
"command": "/think",
"description": "Die Denkstufe festlegen",
"usage_hint": "<off|minimal|low|medium|high|xhigh>",
"description": "Das Denk-Level festlegen",
"usage_hint": "<level>",
"url": "https://gateway-host.example.com/slack/events"
},
{
@ -472,7 +472,7 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge
},
{
"command": "/reasoning",
"description": "Sichtbarkeit von Begründungen umschalten",
"description": "Sichtbarkeit der Begründung umschalten",
"usage_hint": "[on|off|stream]",
"url": "https://gateway-host.example.com/slack/events"
},
@ -484,7 +484,7 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge
},
{
"command": "/exec",
"description": "Exec-Standardeinstellungen anzeigen oder festlegen",
"description": "Exec-Standards anzeigen oder festlegen",
"usage_hint": "host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>",
"url": "https://gateway-host.example.com/slack/events"
},
@ -496,7 +496,7 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge
},
{
"command": "/models",
"description": "Anbieter oder Modelle für einen Anbieter auflisten",
"description": "Provider oder Modelle für einen Provider auflisten",
"usage_hint": "[provider] [page] [limit=<n>|size=<n>|all]",
"url": "https://gateway-host.example.com/slack/events"
},
@ -518,7 +518,7 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge
},
{
"command": "/agentstatus",
"description": "Laufzeitstatus anzeigen, einschließlich Anbieternutzung/Kontingent, wenn verfügbar",
"description": "Laufzeitstatus anzeigen, einschließlich Provider-Nutzung/Kontingent, falls verfügbar",
"url": "https://gateway-host.example.com/slack/events"
},
{
@ -534,12 +534,12 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge
},
{
"command": "/whoami",
"description": "Ihre Absenderidentität anzeigen",
"description": "Ihre Sender-Identität anzeigen",
"url": "https://gateway-host.example.com/slack/events"
},
{
"command": "/skill",
"description": "Eine Skill anhand des Namens ausführen",
"description": "Eine Skills nach Namen ausführen",
"usage_hint": "<name> [input]",
"url": "https://gateway-host.example.com/slack/events"
},
@ -551,7 +551,7 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge
},
{
"command": "/usage",
"description": "Die Nutzungsfußzeile steuern oder Kostenzusammenfassung anzeigen",
"description": "Die Nutzungsfußzeile steuern oder die Kostenzusammenfassung anzeigen",
"usage_hint": "off|tokens|full|cost",
"url": "https://gateway-host.example.com/slack/events"
}
@ -562,14 +562,14 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge
</Tabs>
</Accordion>
<Accordion title="Optionale Scope-Berechtigungen für Verfasserschaft (Schreibvorgänge)">
Fügen Sie den Bot-Scope `chat:write.customize` hinzu, wenn ausgehende Nachrichten die aktive Agent-Identität (benutzerdefinierter Benutzername und Icon) statt der Standardidentität der Slack-App verwenden sollen.
<Accordion title="Optionale Autorschaft-Scopes (Schreibvorgänge)">
Fügen Sie den Bot-Scope `chat:write.customize` hinzu, wenn ausgehende Nachrichten die Identität des aktiven Agenten (benutzerdefinierter Benutzername und Icon) statt der Standardidentität der Slack-App verwenden sollen.
Wenn Sie ein Emoji-Icon verwenden, erwartet Slack die Syntax `:emoji_name:`.
</Accordion>
<Accordion title="Optionale User-Token-Scopes (Lesevorgänge)">
Wenn Sie `channels.slack.userToken` konfigurieren, sind typische Lesescopes:
Wenn Sie `channels.slack.userToken` konfigurieren, sind typische Lese-Scopes:
- `channels:history`, `groups:history`, `im:history`, `mpim:history`
- `channels:read`, `groups:read`, `im:read`, `mpim:read`
@ -577,7 +577,7 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge
- `reactions:read`
- `pins:read`
- `emoji:read`
- `search:read` (wenn Sie von Slack-Suchlesevorgängen abhängig sind)
- `search:read` (wenn Sie auf Slack-Suchlesevorgänge angewiesen sind)
</Accordion>
</AccordionGroup>
@ -591,20 +591,20 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge
- Der Env-Fallback `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` gilt nur für das Standardkonto.
- `userToken` (`xoxp-...`) ist nur per Konfiguration verfügbar (kein Env-Fallback) und verwendet standardmäßig schreibgeschütztes Verhalten (`userTokenReadOnly: true`).
Verhalten des Status-Snapshots:
Verhalten der Statusübersicht:
- Die Slack-Kontoinspektion verfolgt pro Zugangsdaten `*Source`- und `*Status`-Felder (`botToken`, `appToken`, `signingSecret`, `userToken`).
- Die Slack-Kontoinspektion verfolgt pro Anmeldedatenfeld `*Source`- und `*Status`-Felder (`botToken`, `appToken`, `signingSecret`, `userToken`).
- Der Status ist `available`, `configured_unavailable` oder `missing`.
- `configured_unavailable` bedeutet, dass das Konto über SecretRef oder eine andere nicht-inline Geheimnisquelle konfiguriert ist, der aktuelle Befehls-/Laufzeitpfad den tatsächlichen Wert aber nicht auflösen konnte.
- Im HTTP-Modus wird `signingSecretStatus` eingeschlossen; im Socket Mode ist das erforderliche Paar `botTokenStatus` + `appTokenStatus`.
- `configured_unavailable` bedeutet, dass das Konto über SecretRef oder eine andere nicht-inline Secret-Quelle konfiguriert ist, der aktuelle Befehls-/Laufzeitpfad den tatsächlichen Wert aber nicht auflösen konnte.
- Im HTTP-Modus wird `signingSecretStatus` einbezogen; im Socket Mode ist das erforderliche Paar `botTokenStatus` + `appTokenStatus`.
<Tip>
Für Aktions-/Verzeichnislesevorgänge kann das User-Token bevorzugt werden, wenn es konfiguriert ist. Für Schreibvorgänge bleibt das Bot-Token bevorzugt; Schreibvorgänge mit User-Token sind nur zulässig, wenn `userTokenReadOnly: false` gesetzt ist und kein Bot-Token verfügbar ist.
Für Aktionen/Verzeichnislesevorgänge kann das User-Token bevorzugt werden, wenn es konfiguriert ist. Für Schreibvorgänge bleibt das Bot-Token bevorzugt; User-Token-Schreibvorgänge sind nur zulässig, wenn `userTokenReadOnly: false` gesetzt ist und kein Bot-Token verfügbar ist.
</Tip>
## Aktionen und Gates
Slack-Aktionen werden durch `channels.slack.actions.*` gesteuert.
Slack-Aktionen werden über `channels.slack.actions.*` gesteuert.
Verfügbare Aktionsgruppen im aktuellen Slack-Tooling:
@ -622,18 +622,18 @@ Zu den aktuellen Slack-Nachrichtenaktionen gehören `send`, `upload-file`, `down
<Tabs>
<Tab title="DM-Richtlinie">
`channels.slack.dmPolicy` steuert den DM-Zugriff (Legacy: `channels.slack.dm.policy`):
`channels.slack.dmPolicy` steuert den DM-Zugriff (alt: `channels.slack.dm.policy`):
- `pairing` (Standard)
- `allowlist`
- `open` (erfordert, dass `channels.slack.allowFrom` `"*"` enthält; Legacy: `channels.slack.dm.allowFrom`)
- `open` (erfordert, dass `channels.slack.allowFrom` `"*"` enthält; alt: `channels.slack.dm.allowFrom`)
- `disabled`
DM-Flags:
- `dm.enabled` (standardmäßig true)
- `dm.enabled` (Standard true)
- `channels.slack.allowFrom` (bevorzugt)
- `dm.allowFrom` (Legacy)
- `dm.allowFrom` (alt)
- `dm.groupEnabled` (Gruppen-DMs standardmäßig false)
- `dm.groupChannels` (optionale MPIM-Allowlist)
@ -643,7 +643,7 @@ Zu den aktuellen Slack-Nachrichtenaktionen gehören `send`, `upload-file`, `down
- Benannte Konten übernehmen `channels.slack.allowFrom`, wenn ihr eigenes `allowFrom` nicht gesetzt ist.
- Benannte Konten übernehmen nicht `channels.slack.accounts.default.allowFrom`.
Das Pairing in DMs verwendet `openclaw pairing approve slack <code>`.
Die Kopplung in DMs verwendet `openclaw pairing approve slack <code>`.
</Tab>
@ -654,26 +654,26 @@ Zu den aktuellen Slack-Nachrichtenaktionen gehören `send`, `upload-file`, `down
- `allowlist`
- `disabled`
Die Channel-Allowlist liegt unter `channels.slack.channels` und sollte stabile Channel-IDs verwenden.
Die Channel-Allowlist befindet sich unter `channels.slack.channels` und sollte stabile Channel-IDs verwenden.
Laufzeithinweis: Wenn `channels.slack` vollständig fehlt (nur Env-Setup), fällt die Laufzeit auf `groupPolicy="allowlist"` zurück und protokolliert eine Warnung (selbst wenn `channels.defaults.groupPolicy` gesetzt ist).
Laufzeithinweis: Wenn `channels.slack` vollständig fehlt (nur Env-Setup), fällt die Laufzeit auf `groupPolicy="allowlist"` zurück und protokolliert eine Warnung (auch wenn `channels.defaults.groupPolicy` gesetzt ist).
Namens-/ID-Auflösung:
Auflösung von Namen/IDs:
- Channel-Allowlist-Einträge und DM-Allowlist-Einträge werden beim Start aufgelöst, wenn der Token-Zugriff dies erlaubt
- nicht aufgelöste Channel-Namenseinträge bleiben wie konfiguriert erhalten, werden für das Routing standardmäßig aber ignoriert
- eingehende Autorisierung und Channel-Routing sind standardmäßig ID-first; direktes Abgleichen von Benutzernamen/Slugs erfordert `channels.slack.dangerouslyAllowNameMatching: true`
- Einträge in der Channel-Allowlist und DM-Allowlist werden beim Start aufgelöst, wenn der Token-Zugriff dies zulässt
- nicht aufgelöste Channel-Namenseinträge bleiben wie konfiguriert erhalten, werden aber standardmäßig für das Routing ignoriert
- Eingangsautorisierung und Channel-Routing sind standardmäßig ID-first; direktes Matching von Benutzernamen/Slugs erfordert `channels.slack.dangerouslyAllowNameMatching: true`
</Tab>
<Tab title="Erwähnungen und Channel-Benutzer">
Channel-Nachrichten sind standardmäßig durch Erwähnungen gated.
Channel-Nachrichten sind standardmäßig durch Erwähnungen begrenzt.
Erwähnungsquellen:
Quellen für Erwähnungen:
- explizite App-Erwähnung (`<@botId>`)
- Erwähnungs-Regex-Muster (`agents.list[].groupChat.mentionPatterns`, Fallback `messages.groupChat.mentionPatterns`)
- implizites Reply-to-Bot-Thread-Verhalten (deaktiviert, wenn `thread.requireExplicitMention` `true` ist)
- Regex-Muster für Erwähnungen (`agents.list[].groupChat.mentionPatterns`, Fallback `messages.groupChat.mentionPatterns`)
- implizites Antwort-auf-Bot-Thread-Verhalten (deaktiviert, wenn `thread.requireExplicitMention` `true` ist)
Steuerelemente pro Channel (`channels.slack.channels.<id>`; Namen nur über Startauflösung oder `dangerouslyAllowNameMatching`):
@ -684,7 +684,7 @@ Zu den aktuellen Slack-Nachrichtenaktionen gehören `send`, `upload-file`, `down
- `systemPrompt`
- `tools`, `toolsBySender`
- Schlüsselformat für `toolsBySender`: `id:`, `e164:`, `username:`, `name:` oder Platzhalter `"*"`
(Legacy-Schlüssel ohne Präfix werden weiterhin nur `id:` zugeordnet)
(Altschlüssel ohne Präfix werden weiterhin nur `id:` zugeordnet)
</Tab>
</Tabs>
@ -692,27 +692,27 @@ Zu den aktuellen Slack-Nachrichtenaktionen gehören `send`, `upload-file`, `down
## Threads, Sitzungen und Antwort-Tags
- DMs werden als `direct` geroutet; Channels als `channel`; MPIMs als `group`.
- Mit dem Standard `session.dmScope=main` werden Slack-DMs in die Hauptsitzung des Agenten zusammengeführt.
- Mit dem Standardwert `session.dmScope=main` werden Slack-DMs zur Hauptsitzung des Agenten zusammengeführt.
- Channel-Sitzungen: `agent:<agentId>:slack:channel:<channelId>`.
- Thread-Antworten können bei Bedarf Thread-Sitzungssuffixe (`:thread:<threadTs>`) erzeugen.
- Der Standardwert von `channels.slack.thread.historyScope` ist `thread`; der Standardwert von `thread.inheritParent` ist `false`.
- `channels.slack.thread.initialHistoryLimit` steuert, wie viele vorhandene Thread-Nachrichten abgerufen werden, wenn eine neue Thread-Sitzung beginnt (Standard `20`; setzen Sie `0`, um dies zu deaktivieren).
- `channels.slack.thread.requireExplicitMention` (Standard `false`): Wenn `true`, werden implizite Thread-Erwähnungen unterdrückt, sodass der Bot in Threads nur auf explizite `@bot`-Erwähnungen antwortet, selbst wenn der Bot bereits am Thread teilgenommen hat. Ohne dies umgehen Antworten in einem Thread mit Bot-Beteiligung das `requireMention`-Gating.
- `channels.slack.thread.historyScope` ist standardmäßig `thread`; `thread.inheritParent` ist standardmäßig `false`.
- `channels.slack.thread.initialHistoryLimit` steuert, wie viele vorhandene Thread-Nachrichten abgerufen werden, wenn eine neue Thread-Sitzung startet (Standard `20`; setzen Sie `0`, um dies zu deaktivieren).
- `channels.slack.thread.requireExplicitMention` (Standard `false`): Wenn `true`, werden implizite Thread-Erwähnungen unterdrückt, sodass der Bot in Threads nur auf explizite `@bot`-Erwähnungen antwortet, selbst wenn der Bot bereits am Thread teilgenommen hat. Ohne dies umgehen Antworten in einem Thread mit Bot-Beteiligung das `requireMention`-Gate.
Steuerelemente für Antwort-Threading:
Steuerelemente für Antwort-Threads:
- `channels.slack.replyToMode`: `off|first|all|batched` (Standard `off`)
- `channels.slack.replyToModeByChatType`: pro `direct|group|channel`
- Legacy-Fallback für direkte Chats: `channels.slack.dm.replyToMode`
- Alt-Fallback für direkte Chats: `channels.slack.dm.replyToMode`
Manuelle Antwort-Tags werden unterstützt:
- `[[reply_to_current]]`
- `[[reply_to:<id>]]`
Hinweis: `replyToMode="off"` deaktiviert in Slack **jegliches** Antwort-Threading, einschließlich expliziter `[[reply_to_*]]`-Tags. Dies unterscheidet sich von Telegram, wo explizite Tags im Modus `"off"` weiterhin beachtet werden. Der Unterschied spiegelt die Threading-Modelle der Plattformen wider: Slack-Threads blenden Nachrichten aus dem Channel aus, während Telegram-Antworten im Haupt-Chatverlauf sichtbar bleiben.
Hinweis: `replyToMode="off"` deaktiviert **sämtliches** Antwort-Threading in Slack, einschließlich expliziter `[[reply_to_*]]`-Tags. Dies unterscheidet sich von Telegram, wo explizite Tags auch im Modus `"off"` weiterhin berücksichtigt werden. Der Unterschied spiegelt die Threading-Modelle der Plattformen wider: Slack-Threads verbergen Nachrichten im Channel, während Telegram-Antworten im Haupt-Chatverlauf sichtbar bleiben.
## Bestätigungsreaktionen
## Ack-Reaktionen
`ackReaction` sendet ein Bestätigungs-Emoji, während OpenClaw eine eingehende Nachricht verarbeitet.
@ -721,7 +721,7 @@ Auflösungsreihenfolge:
- `channels.slack.accounts.<accountId>.ackReaction`
- `channels.slack.ackReaction`
- `messages.ackReaction`
- Emoji-Fallback der Agent-Identität (`agents.list[].identity.emoji`, sonst `"👀"`)
- Emoji-Fallback der Agentenidentität (`agents.list[].identity.emoji`, sonst "👀")
Hinweise:
@ -733,19 +733,19 @@ Hinweise:
`channels.slack.streaming` steuert das Verhalten der Live-Vorschau:
- `off`: Live-Vorschau-Streaming deaktivieren.
- `partial` (Standard): Vorschautext durch die neueste partielle Ausgabe ersetzen.
- `partial` (Standard): Vorschautext durch die neueste Teilausgabe ersetzen.
- `block`: Vorschauaktualisierungen in Blöcken anhängen.
- `progress`: Fortschrittsstatustext während der Generierung anzeigen und dann den endgültigen Text senden.
- `progress`: Während der Generierung einen Fortschrittsstatustext anzeigen und dann den endgültigen Text senden.
`channels.slack.streaming.nativeTransport` steuert natives Slack-Text-Streaming, wenn `channels.slack.streaming.mode` auf `partial` gesetzt ist (Standard: `true`).
- Für natives Text-Streaming und die Anzeige des Slack-Assistant-Thread-Status muss ein Antwort-Thread verfügbar sein. Die Thread-Auswahl folgt weiterhin `replyToMode`.
- Für natives Text-Streaming und die Anzeige des Slack-Assistenten-Thread-Status muss ein Antwort-Thread verfügbar sein. Die Thread-Auswahl folgt weiterhin `replyToMode`.
- Channel- und Gruppenchat-Wurzeln können weiterhin die normale Entwurfsvorschau verwenden, wenn natives Streaming nicht verfügbar ist.
- Slack-DMs der obersten Ebene bleiben standardmäßig ohne Thread, daher zeigen sie keine Vorschau im Thread-Stil an; verwenden Sie Thread-Antworten oder `typingReaction`, wenn Sie dort sichtbaren Fortschritt wünschen.
- Medien und Nicht-Text-Payloads fallen auf die normale Zustellung zurück.
- Wenn das Streaming mitten in einer Antwort fehlschlägt, fällt OpenClaw für die verbleibenden Payloads auf die normale Zustellung zurück.
- Slack-DMs auf oberster Ebene bleiben standardmäßig außerhalb von Threads, daher zeigen sie keine Vorschau im Thread-Stil an; verwenden Sie Thread-Antworten oder `typingReaction`, wenn dort sichtbarer Fortschritt angezeigt werden soll.
- Medien- und Nicht-Text-Payloads fallen auf normale Zustellung zurück.
- Wenn Streaming während einer Antwort fehlschlägt, fällt OpenClaw für die verbleibenden Payloads auf normale Zustellung zurück.
Verwenden Sie die Entwurfsvorschau anstelle von nativem Slack-Text-Streaming:
Entwurfsvorschau anstelle von nativem Slack-Text-Streaming verwenden:
```json5
{
@ -760,15 +760,15 @@ Verwenden Sie die Entwurfsvorschau anstelle von nativem Slack-Text-Streaming:
}
```
Legacy-Schlüssel:
Altschlüssel:
- `channels.slack.streamMode` (`replace | status_final | append`) wird automatisch nach `channels.slack.streaming.mode` migriert.
- boolesches `channels.slack.streaming` wird automatisch nach `channels.slack.streaming.mode` und `channels.slack.streaming.nativeTransport` migriert.
- Legacy-`channels.slack.nativeStreaming` wird automatisch nach `channels.slack.streaming.nativeTransport` migriert.
- `channels.slack.streamMode` (`replace | status_final | append`) wird automatisch zu `channels.slack.streaming.mode` migriert.
- Boolesches `channels.slack.streaming` wird automatisch zu `channels.slack.streaming.mode` und `channels.slack.streaming.nativeTransport` migriert.
- Das alte `channels.slack.nativeStreaming` wird automatisch zu `channels.slack.streaming.nativeTransport` migriert.
## Typing-Reaction-Fallback
`typingReaction` fügt der eingehenden Slack-Nachricht vorübergehend eine Reaktion hinzu, während OpenClaw eine Antwort verarbeitet, und entfernt sie wieder, wenn der Lauf beendet ist. Dies ist besonders nützlich außerhalb von Thread-Antworten, die standardmäßig einen Statusindikator „is typing...“ verwenden.
`typingReaction` fügt der eingehenden Slack-Nachricht vorübergehend eine Reaktion hinzu, während OpenClaw eine Antwort verarbeitet, und entfernt sie wieder, wenn der Lauf abgeschlossen ist. Dies ist besonders nützlich außerhalb von Thread-Antworten, die standardmäßig einen Statusindikator „is typing...“ verwenden.
Auflösungsreihenfolge:
@ -778,23 +778,23 @@ Auflösungsreihenfolge:
Hinweise:
- Slack erwartet Shortcodes (zum Beispiel `"hourglass_flowing_sand"`).
- Die Reaktion erfolgt nach bestem Bemühen, und die Bereinigung wird automatisch versucht, nachdem die Antwort oder der Fehlerpfad abgeschlossen ist.
- Die Reaktion erfolgt nach bestem Aufwand und die Bereinigung wird nach Abschluss des Antwort- oder Fehlerpfads automatisch versucht.
## Medien, Chunking und Zustellung
<AccordionGroup>
<Accordion title="Eingehende Anhänge">
Slack-Dateianhänge werden von Slack-gehosteten privaten URLs heruntergeladen (token-authentifizierter Anfragefluss) und in den Medienspeicher geschrieben, wenn der Abruf erfolgreich ist und Größenlimits dies erlauben.
Slack-Dateianhänge werden von privat gehosteten Slack-URLs heruntergeladen (token-authentifizierter Request-Ablauf) und in den Medienspeicher geschrieben, wenn das Abrufen erfolgreich ist und Größenlimits dies zulassen.
Die Laufzeitobergrenze für eingehende Größen beträgt standardmäßig `20MB`, sofern sie nicht durch `channels.slack.mediaMaxMb` überschrieben wird.
Die Laufzeitgrenze für eingehende Daten beträgt standardmäßig `20MB`, sofern sie nicht durch `channels.slack.mediaMaxMb` überschrieben wird.
</Accordion>
<Accordion title="Ausgehender Text und Dateien">
- Text-Chunks verwenden `channels.slack.textChunkLimit` (Standard 4000)
- `channels.slack.chunkMode="newline"` aktiviert paragrafenorientiertes Aufteilen
- Dateisendungen verwenden Slack-Upload-APIs und können Thread-Antworten (`thread_ts`) enthalten
- Das Limit für ausgehende Medien folgt bei Konfiguration `channels.slack.mediaMaxMb`; andernfalls verwenden Channel-Sendungen die MIME-Typ-Standards aus der Medienpipeline
- `channels.slack.chunkMode="newline"` aktiviert eine absatzorientierte Aufteilung
- Dateisendungen verwenden Slack-Upload-APIs und können Thread-Antworten (`thread_ts`) einschließen
- Die Obergrenze für ausgehende Medien folgt `channels.slack.mediaMaxMb`, wenn konfiguriert; andernfalls verwenden Channel-Sendungen MIME-Art-Standards aus der Medienpipeline
</Accordion>
<Accordion title="Zustellungsziele">
@ -803,14 +803,14 @@ Hinweise:
- `user:<id>` für DMs
- `channel:<id>` für Channels
Slack-DMs werden über die Slack-Conversation-APIs geöffnet, wenn an Benutzerziele gesendet wird.
Slack-DMs werden beim Senden an Benutzerziele über Slack-Conversations-APIs geöffnet.
</Accordion>
</AccordionGroup>
## Befehle und Slash-Verhalten
Slash-Befehle erscheinen in Slack entweder als einzelner konfigurierter Befehl oder als mehrere native Befehle. Konfigurieren Sie `channels.slack.slashCommand`, um die Befehlsstandards zu ändern:
Slash-Befehle erscheinen in Slack entweder als einzelner konfigurierter Befehl oder als mehrere native Befehle. Konfigurieren Sie `channels.slack.slashCommand`, um Befehlsstandards zu ändern:
- `enabled: false`
- `name: "openclaw"`
@ -821,7 +821,7 @@ Slash-Befehle erscheinen in Slack entweder als einzelner konfigurierter Befehl o
/openclaw /help
```
Native Befehle erfordern [zusätzliche Manifesteinstellungen](#additional-manifest-settings) in Ihrer Slack-App und werden stattdessen mit `channels.slack.commands.native: true` oder `commands.native: true` in globalen Konfigurationen aktiviert.
Native Befehle erfordern [zusätzliche Manifest-Einstellungen](#additional-manifest-settings) in Ihrer Slack-App und werden stattdessen mit `channels.slack.commands.native: true` oder `commands.native: true` in globalen Konfigurationen aktiviert.
- Der automatische native Befehlsmodus ist für Slack **deaktiviert**, daher aktiviert `commands.native: "auto"` keine nativen Slack-Befehle.
@ -829,22 +829,22 @@ Native Befehle erfordern [zusätzliche Manifesteinstellungen](#additional-manife
/help
```
Native Argumentmenüs verwenden eine adaptive Renderstrategie, die vor dem Senden eines ausgewählten Optionswerts ein Bestätigungsmodal anzeigt:
Native Argumentmenüs verwenden eine adaptive Rendering-Strategie, die vor dem Absenden eines ausgewählten Optionswerts ein Bestätigungsmodal anzeigt:
- bis zu 5 Optionen: Button-Blöcke
- 6–100 Optionen: statisches Auswahlmenü
- mehr als 100 Optionen: externe Auswahl mit asynchroner Optionsfilterung, wenn Interaktivitäts-Options-Handler verfügbar sind
- überschrittene Slack-Limits: codierte Optionswerte fallen auf Buttons zurück
- 6-100 Optionen: statisches Auswahlmenü
- mehr als 100 Optionen: externe Auswahl mit asynchroner Optionsfilterung, wenn Handler für Interaktivitätsoptionen verfügbar sind
- bei Überschreitung der Slack-Limits: codierte Optionswerte fallen auf Buttons zurück
```txt
/think
```
Slash-Sitzungen verwenden isolierte Schlüssel wie `agent:<agentId>:slack:slash:<userId>` und leiten Befehlsausführungen weiterhin über `CommandTargetSessionKey` an die Ziel-Konversationssitzung weiter.
Slash-Sitzungen verwenden isolierte Schlüssel wie `agent:<agentId>:slack:slash:<userId>` und leiten Befehlsausführungen weiterhin mit `CommandTargetSessionKey` an die Ziel-Konversationssitzung weiter.
## Interaktive Antworten
Slack kann von Agenten verfasste interaktive Antwortsteuerungen rendern, aber diese Funktion ist standardmäßig deaktiviert.
Slack kann interaktive, vom Agenten verfasste Antwortsteuerelemente rendern, aber diese Funktion ist standardmäßig deaktiviert.
Global aktivieren:
@ -878,30 +878,30 @@ Oder nur für ein Slack-Konto aktivieren:
}
```
Wenn aktiviert, können Agenten nur für Slack bestimmte Antwortdirektiven ausgeben:
Wenn aktiviert, können Agenten nur für Slack gültige Antwortdirektiven ausgeben:
- `[[slack_buttons: Approve:approve, Reject:reject]]`
- `[[slack_select: Choose a target | Canary:canary, Production:production]]`
Diese Direktiven werden in Slack Block Kit kompiliert und leiten Klicks oder Auswahlen über den vorhandenen Slack-Interaktionsereignispfad zurück.
Diese Direktiven werden zu Slack Block Kit kompiliert und leiten Klicks oder Auswahlen über den bestehenden Slack-Interaktionsereignispfad zurück.
Hinweise:
- Dies ist eine Slack-spezifische UI. Andere Channels übersetzen Slack-Block-Kit-Direktiven nicht in ihre eigenen Button-Systeme.
- Die Werte interaktiver Callbacks sind von OpenClaw generierte undurchsichtige Token, keine unbearbeiteten, vom Agenten verfassten Werte.
- Wenn generierte interaktive Blöcke die Slack-Block-Kit-Limits überschreiten würden, fällt OpenClaw auf die ursprüngliche Textantwort zurück, anstatt eine ungültige Blocks-Payload zu senden.
- Die interaktiven Callback-Werte sind von OpenClaw erzeugte opake Tokens, keine rohen, vom Agenten verfassten Werte.
- Wenn erzeugte interaktive Blöcke die Slack-Block-Kit-Limits überschreiten würden, fällt OpenClaw auf die ursprüngliche Textantwort zurück, anstatt eine ungültige Blocks-Payload zu senden.
## Exec-Freigaben in Slack
## Exec-Genehmigungen in Slack
Slack kann als nativer Freigabe-Client mit interaktiven Buttons und Interaktionen dienen, anstatt auf die Web-UI oder das Terminal zurückzufallen.
Slack kann als nativer Genehmigungsclient mit interaktiven Buttons und Interaktionen fungieren, statt auf die Web-UI oder das Terminal zurückzufallen.
- Exec-Freigaben verwenden `channels.slack.execApprovals.*` für natives DM-/Channel-Routing.
- Plugin-Freigaben können weiterhin über dieselbe native Slack-Button-Oberfläche aufgelöst werden, wenn die Anfrage bereits in Slack landet und die Freigabe-ID-Art `plugin:` ist.
- Die Autorisierung der Freigebenden wird weiterhin erzwungen: Nur als Freigebende identifizierte Benutzer können Anfragen über Slack genehmigen oder ablehnen.
- Exec-Genehmigungen verwenden `channels.slack.execApprovals.*` für natives DM-/Channel-Routing.
- Plugin-Genehmigungen können weiterhin über dieselbe Slack-native Button-Oberfläche aufgelöst werden, wenn die Anfrage bereits in Slack landet und die Genehmigungs-ID-Art `plugin:` ist.
- Die Autorisierung der Genehmigenden wird weiterhin erzwungen: Nur als Genehmigende identifizierte Benutzer können Anfragen über Slack genehmigen oder ablehnen.
Dies verwendet dieselbe gemeinsame Freigabe-Button-Oberfläche wie andere Channels. Wenn `interactivity` in Ihren Slack-App-Einstellungen aktiviert ist, werden Freigabeaufforderungen direkt als Block-Kit-Buttons in der Konversation gerendert.
Wenn diese Buttons vorhanden sind, sind sie die primäre Freigabe-UX; OpenClaw
sollte einen manuellen `/approve`-Befehl nur einschließen, wenn das Tool-Ergebnis sagt, dass Chat-Freigaben nicht verfügbar sind oder manuelle Freigabe der einzige Weg ist.
Dies verwendet dieselbe gemeinsame Genehmigungs-Button-Oberfläche wie andere Channels. Wenn `interactivity` in Ihren Slack-App-Einstellungen aktiviert ist, werden Genehmigungsabfragen direkt in der Konversation als Block-Kit-Buttons gerendert.
Wenn diese Buttons vorhanden sind, sind sie die primäre Genehmigungs-UX; OpenClaw
sollte einen manuellen `/approve`-Befehl nur dann einschließen, wenn das Tool-Ergebnis sagt, dass Chat-Genehmigungen nicht verfügbar sind oder die manuelle Genehmigung der einzige Weg ist.
Konfigurationspfad:
@ -910,11 +910,11 @@ Konfigurationspfad:
- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, Standard: `dm`)
- `agentFilter`, `sessionFilter`
Slack aktiviert native Exec-Freigaben automatisch, wenn `enabled` nicht gesetzt oder `"auto"` ist und sich mindestens ein
Freigebender auflösen lässt. Setzen Sie `enabled: false`, um Slack explizit als nativen Freigabe-Client zu deaktivieren.
Setzen Sie `enabled: true`, um native Freigaben zu erzwingen, wenn sich Freigebende auflösen lassen.
Slack aktiviert native Exec-Genehmigungen automatisch, wenn `enabled` nicht gesetzt ist oder `"auto"` ist und mindestens ein
Genehmigender aufgelöst wird. Setzen Sie `enabled: false`, um Slack explizit als nativen Genehmigungsclient zu deaktivieren.
Setzen Sie `enabled: true`, um native Genehmigungen zu erzwingen, wenn Genehmigende aufgelöst werden.
Standardverhalten ohne explizite Slack-Exec-Freigabekonfiguration:
Standardverhalten ohne explizite Slack-Exec-Genehmigungskonfiguration:
```json5
{
@ -924,8 +924,8 @@ Standardverhalten ohne explizite Slack-Exec-Freigabekonfiguration:
}
```
Eine explizite Slack-native Konfiguration ist nur erforderlich, wenn Sie Freigebende überschreiben, Filter hinzufügen oder
sich für die Zustellung an den Ursprungschat entscheiden möchten:
Eine explizite Slack-native Konfiguration ist nur erforderlich, wenn Sie Genehmigende überschreiben, Filter hinzufügen oder
sich für die Zustellung an den Ursprungs-Chat entscheiden möchten:
```json5
{
@ -941,20 +941,20 @@ sich für die Zustellung an den Ursprungschat entscheiden möchten:
}
```
Gemeinsame `approvals.exec`-Weiterleitung ist getrennt. Verwenden Sie sie nur, wenn Exec-Freigabeaufforderungen zusätzlich
an andere Chats oder explizite Ziele außerhalb des Bandes weitergeleitet werden müssen. Gemeinsame `approvals.plugin`-Weiterleitung ist ebenfalls
getrennt; native Slack-Buttons können Plugin-Freigaben weiterhin auflösen, wenn diese Anfragen bereits in Slack landen.
Gemeinsame Weiterleitung über `approvals.exec` ist davon getrennt. Verwenden Sie sie nur, wenn Exec-Genehmigungsabfragen zusätzlich
an andere Chats oder explizite Out-of-Band-Ziele weitergeleitet werden müssen. Gemeinsame Weiterleitung über `approvals.plugin` ist ebenfalls
getrennt; Slack-native Buttons können Plugin-Genehmigungen weiterhin auflösen, wenn diese Anfragen bereits in Slack landen.
`/approve` im selben Chat funktioniert ebenfalls in Slack-Channels und DMs, die bereits Befehle unterstützen. Siehe [Exec approvals](/de/tools/exec-approvals) für das vollständige Modell zur Freigabeweiterleitung.
`/approve` im selben Chat funktioniert auch in Slack-Channels und DMs, die bereits Befehle unterstützen. Siehe [Exec-Genehmigungen](/de/tools/exec-approvals) für das vollständige Modell zur Genehmigungsweiterleitung.
## Ereignisse und Laufzeitverhalten
## Ereignisse und Betriebsverhalten
- Nachrichtenbearbeitungen/-löschungen/Thread-Broadcasts werden in Systemereignisse abgebildet.
- Hinzugefügte/entfernte Reaktionen werden in Systemereignisse abgebildet.
- Beitritt/Austritt von Mitgliedern, Erstellung/Umbenennung von Channels und Hinzufügen/Entfernen von Pins werden in Systemereignisse abgebildet.
- Reaktions-Hinzufügen/-Entfernen-Ereignisse werden in Systemereignisse abgebildet.
- Ereignisse zu Beitritt/Austritt von Mitgliedern, erstellten/umbenannten Channels und hinzugefügten/entfernten Pins werden in Systemereignisse abgebildet.
- `channel_id_changed` kann Channel-Konfigurationsschlüssel migrieren, wenn `configWrites` aktiviert ist.
- Channel-Topic-/Purpose-Metadaten werden als nicht vertrauenswürdiger Kontext behandelt und können in den Routing-Kontext eingefügt werden.
- Thread-Starter und das anfängliche Seedings des Thread-Verlaufs-Kontexts werden, sofern zutreffend, durch konfigurierte Absender-Allowlists gefiltert.
- Channel-Topic-/Purpose-Metadaten werden als nicht vertrauenswürdiger Kontext behandelt und können in den Routing-Kontext injiziert werden.
- Thread-Starter und anfängliches Kontext-Seeding aus dem Thread-Verlauf werden, sofern zutreffend, nach konfigurierten Sender-Allowlists gefiltert.
- Block-Aktionen und Modal-Interaktionen erzeugen strukturierte Systemereignisse `Slack interaction: ...` mit umfangreichen Payload-Feldern:
- Block-Aktionen: ausgewählte Werte, Labels, Picker-Werte und `workflow_*`-Metadaten
- Modal-Ereignisse `view_submission` und `view_closed` mit gerouteten Channel-Metadaten und Formulareingaben
@ -967,8 +967,8 @@ Primäre Referenz:
Wichtige Slack-Felder:
- Modus/Auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*`
- DM-Zugriff: `dm.enabled`, `dmPolicy`, `allowFrom` (Legacy: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
- Kompatibilitätsschalter: `dangerouslyAllowNameMatching` (Break-Glass; deaktiviert lassen, sofern nicht benötigt)
- DM-Zugriff: `dm.enabled`, `dmPolicy`, `allowFrom` (alt: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
- Kompatibilitätsumschalter: `dangerouslyAllowNameMatching` (nur im Notfall; ausgeschaltet lassen, sofern nicht benötigt)
- Channel-Zugriff: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
- Threading/Verlauf: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
- Zustellung: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`
@ -983,7 +983,7 @@ Primäre Referenz:
- `groupPolicy`
- Channel-Allowlist (`channels.slack.channels`)
- `requireMention`
- `users`-Allowlist pro Channel
- Allowlist `users` pro Channel
Nützliche Befehle:
@ -999,8 +999,8 @@ openclaw doctor
Prüfen Sie:
- `channels.slack.dm.enabled`
- `channels.slack.dmPolicy` (oder Legacy `channels.slack.dm.policy`)
- Pairing-Freigaben / Allowlist-Einträge
- `channels.slack.dmPolicy` (oder alt `channels.slack.dm.policy`)
- Kopplungsgenehmigungen / Allowlist-Einträge
```bash
openclaw pairing list slack
@ -1024,9 +1024,9 @@ openclaw pairing list slack
- Signing Secret
- Webhook-Pfad
- Slack-Request-URLs (Events + Interaktivität + Slash-Befehle)
- eindeutiger `webhookPath` pro HTTP-Konto
- eindeutigen `webhookPath` pro HTTP-Konto
Wenn `signingSecretStatus: "configured_unavailable"` in Konto-Snapshots
Wenn `signingSecretStatus: "configured_unavailable"` in Kontoübersichten
erscheint, ist das HTTP-Konto konfiguriert, aber die aktuelle Laufzeit konnte das
durch SecretRef gestützte Signing Secret nicht auflösen.
@ -1035,10 +1035,10 @@ openclaw pairing list slack
<Accordion title="Native/Slash-Befehle werden nicht ausgelöst">
Prüfen Sie, ob Sie Folgendes beabsichtigt haben:
- nativen Befehlsmodus (`channels.slack.commands.native: true`) mit passenden in Slack registrierten Slash-Befehlen
- oder Modus mit einzelnem Slash-Befehl (`channels.slack.slashCommand.enabled: true`)
- nativer Befehlsmodus (`channels.slack.commands.native: true`) mit passend in Slack registrierten Slash-Befehlen
- oder Einzel-Slash-Befehlsmodus (`channels.slack.slashCommand.enabled: true`)
Prüfen Sie außerdem `commands.useAccessGroups` und Channel-/Benutzer-Allowlists.
Prüfen Sie außerdem `commands.useAccessGroups` sowie Channel-/Benutzer-Allowlists.
</Accordion>
</AccordionGroup>

130
docs/de/concepts/messages.md
View File

@ -1,53 +1,48 @@
---
read_when:
- Erklären, wie eingehende Nachrichten zu Antworten werden
- Erläutern von Sitzungen, Warteschlangenmodi oder Streaming-Verhalten
- Dokumentieren der Sichtbarkeit des Denkprozesses und der Auswirkungen auf die Nutzung
summary: Nachrichtenfluss, Sitzungen, Warteschlangenbildung und Sichtbarkeit des Denkprozesses
- Erklärung, wie eingehende Nachrichten zu Antworten werden
- Erläuterung von Sitzungen, Warteschlangenmodi oder Streaming-Verhalten
- Dokumentation der Sichtbarkeit der Argumentation und der Auswirkungen auf die Nutzung
summary: Nachrichtenfluss, Sitzungen, Warteschlangenbildung und Sichtbarkeit der Argumentation
title: Nachrichten
x-i18n:
generated_at: "2026-04-21T06:23:59Z"
generated_at: "2026-04-21T13:35:27Z"
model: gpt-5.4
provider: openai
source_hash: ddf88b91f3489bfdfb4a84f8a287a1ec0b0d71a765dfe27c666c6f43d0145022
source_hash: 4f535d01872e7fcf0f3d99a5c5ac01feddbf7fb562ff61d9ccdf18f109f9922f
source_path: concepts/messages.md
workflow: 15
---
# Nachrichten
Diese Seite fasst zusammen, wie OpenClaw eingehende Nachrichten, Sitzungen, Warteschlangenbildung,
Streaming und die Sichtbarkeit des Denkprozesses verarbeitet.
Diese Seite führt zusammen, wie OpenClaw eingehende Nachrichten, Sitzungen, Warteschlangenbildung, Streaming und die Sichtbarkeit der Argumentation verarbeitet.
## Nachrichtenfluss (Überblick)
## Nachrichtenfluss (allgemein)
```
Eingehende Nachricht
-> Routing/Bindings -> Sitzungsschlüssel
-> Warteschlange (wenn ein Lauf aktiv ist)
-> Agent-Lauf (Streaming + Tools)
-> Ausgehende Antworten (Kanalgrenzen + Aufteilung)
Inbound message
-> routing/bindings -> session key
-> queue (if a run is active)
-> agent run (streaming + tools)
-> outbound replies (channel limits + chunking)
```
Wichtige Stellschrauben befinden sich in der Konfiguration:
- `messages.*` für Präfixe, Warteschlangenbildung und Gruppenverhalten.
- `agents.defaults.*` für Standardwerte bei Block-Streaming und Aufteilung.
- Kanalüberschreibungen (`channels.whatsapp.*`, `channels.telegram.*` usw.) für Grenzen und Streaming-Umschalter.
- `agents.defaults.*` für Standardwerte für Block-Streaming und Chunking.
- Kanalüberschreibungen (`channels.whatsapp.*`, `channels.telegram.*` usw.) für Obergrenzen und Streaming-Umschalter.
Siehe [Konfiguration](/de/gateway/configuration) für das vollständige Schema.
Siehe [Configuration](/de/gateway/configuration) für das vollständige Schema.
## Deduplizierung eingehender Nachrichten
Kanäle können nach Wiederverbindungen dieselbe Nachricht erneut zustellen. OpenClaw hält einen
kurzlebigen Cache, der nach Kanal/Konto/Peer/Sitzung/Nachrichten-ID geschlüsselt ist, damit doppelte
Zustellungen keinen weiteren Agent-Lauf auslösen.
Kanäle können nach erneuten Verbindungen dieselbe Nachricht erneut zustellen. OpenClaw führt einen kurzlebigen Cache, der nach Kanal/Konto/Peer/Sitzung/Nachrichten-ID schlüsselt, damit doppelte Zustellungen keinen weiteren Agent-Durchlauf auslösen.
## Entprellung eingehender Nachrichten
Schnell aufeinanderfolgende Nachrichten vom **gleichen Absender** können über `messages.inbound`
zu einer einzelnen Agent-Runde zusammengefasst werden. Die Entprellung ist pro Kanal + Unterhaltung
begrenzt und verwendet die zuletzt eingegangene Nachricht für Antwort-Threading/IDs.
Schnell aufeinanderfolgende Nachrichten vom **gleichen Absender** können über `messages.inbound` zu einem einzelnen Agent-Turn zusammengefasst werden. Die Entprellung ist auf Kanal + Konversation beschränkt und verwendet die zuletzt empfangene Nachricht für Antwort-Threading/IDs.
Konfiguration (globaler Standard + kanalbezogene Überschreibungen):
@ -68,88 +63,74 @@ Konfiguration (globaler Standard + kanalbezogene Überschreibungen):
Hinweise:
- Entprellung gilt für **reine Textnachrichten**; Medien/Anhänge werden sofort durchgereicht.
- Steuerbefehle umgehen die Entprellung, damit sie eigenständig bleiben.
- Entprellung gilt für **reine Textnachrichten**; Medien/Anhänge werden sofort geleert.
- Steuerbefehle umgehen die Entprellung, damit sie eigenständig bleiben — **außer**, wenn ein Kanal ausdrücklich Same-Sender-DM-Coalescing aktiviert (z. B. [BlueBubbles `coalesceSameSenderDms`](/de/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)); dann warten DM-Befehle innerhalb des Entprellungsfensters, damit eine Split-Send-Nutzlast demselben Agent-Turn beitreten kann.
## Sitzungen und Geräte
Sitzungen gehören dem Gateway, nicht den Clients.
- Direktchats werden auf den Hauptsitzungsschlüssel des Agenten zusammengeführt.
- Gruppen/Kanäle erhalten eigene Sitzungsschlüssel.
- Sitzungsspeicher und Transkripte liegen auf dem Gateway-Host.
- Direkte Chats werden auf den Haupt-Sitzungsschlüssel des Agenten reduziert.
- Gruppen/Kanäle erhalten ihre eigenen Sitzungsschlüssel.
- Der Sitzungsspeicher und die Transkripte liegen auf dem Gateway-Host.
Mehrere Geräte/Kanäle können derselben Sitzung zugeordnet sein, aber der Verlauf wird nicht vollständig
an jeden Client zurücksynchronisiert. Empfehlung: Verwenden Sie für lange Unterhaltungen ein primäres Gerät,
um auseinanderlaufenden Kontext zu vermeiden. Die Control UI und die TUI zeigen immer das vom Gateway
gestützte Sitzungsprotokoll an und sind daher die Quelle der Wahrheit.
Mehrere Geräte/Kanäle können derselben Sitzung zugeordnet sein, aber der Verlauf wird nicht vollständig an jeden Client zurücksynchronisiert. Empfehlung: Verwenden Sie für lange Unterhaltungen ein primäres Gerät, um auseinanderlaufenden Kontext zu vermeiden. Das Control UI und die TUI zeigen immer das Gateway-gestützte Sitzungsprotokoll an und sind daher die Quelle der Wahrheit.
Details: [Sitzungsverwaltung](/de/concepts/session).
Details: [Session management](/de/concepts/session).
## Eingehende Inhalte und Verlaufskontext
## Eingehende Nachrichtentexte und Verlaufskontext
OpenClaw trennt den **Prompt-Text** vom **Befehlstext**:
- `Body`: Prompt-Text, der an den Agenten gesendet wird. Er kann Kanal-Umschläge und
optionale Verlaufs-Wrapper enthalten.
- `CommandBody`: Rohtext des Nutzers für Richtlinien-/Befehls-Parsing.
- `RawBody`: veralteter Alias für `CommandBody` (aus Kompatibilitätsgründen beibehalten).
- `Body`: Prompt-Text, der an den Agenten gesendet wird. Dieser kann Kanalumschläge und optionale Verlaufs-Wrapper enthalten.
- `CommandBody`: Roher Benutzertest für die Verarbeitung von Direktiven/Befehlen.
- `RawBody`: Veralteter Alias für `CommandBody` (aus Kompatibilitätsgründen beibehalten).
Wenn ein Kanal Verlauf bereitstellt, verwendet er einen gemeinsamen Wrapper:
- `[Chat-Nachrichten seit Ihrer letzten Antwort - für Kontext]`
- `[Aktuelle Nachricht - antworten Sie darauf]`
- `[Chat messages since your last reply - for context]`
- `[Current message - respond to this]`
Bei **Nicht-Direktchats** (Gruppen/Kanäle/Räume) wird dem **Inhalt der aktuellen Nachricht** das
Absender-Label vorangestellt (im selben Stil wie bei Verlaufseinträgen). So bleiben Echtzeit- und
Warteschlangen-/Verlaufsnachrichten im Agent-Prompt konsistent.
Bei **nicht direkten Chats** (Gruppen/Kanälen/Räumen) wird dem **Text der aktuellen Nachricht** das Absenderlabel vorangestellt (im selben Stil wie bei Verlaufseinträgen). So bleiben Echtzeit- sowie in Warteschlange/Verlauf befindliche Nachrichten im Agent-Prompt konsistent.
Verlaufspuffer sind **nur ausstehend**: Sie enthalten Gruppennachrichten, die _keinen_
Lauf ausgelöst haben (zum Beispiel durch Mention-Gating blockierte Nachrichten), und **schließen**
Nachrichten aus, die bereits im Sitzungsprotokoll vorhanden sind.
Verlaufspuffer sind **nur ausstehend**: Sie enthalten Gruppennachrichten, die _keinen_ Durchlauf ausgelöst haben (zum Beispiel durch Mention-Gating gefilterte Nachrichten), und **schließen** Nachrichten aus, die bereits im Sitzungsprotokoll stehen.
Das Entfernen von Richtlinien gilt nur für den Abschnitt der **aktuellen Nachricht**, damit der Verlauf
intakt bleibt. Kanäle, die Verlauf umschließen, sollten `CommandBody` (oder
`RawBody`) auf den ursprünglichen Nachrichtentext setzen und `Body` als kombinierten Prompt beibehalten.
Verlaufspuffer sind konfigurierbar über `messages.groupChat.historyLimit` (globaler
Standard) und kanalbezogene Überschreibungen wie `channels.slack.historyLimit` oder
`channels.telegram.accounts.<id>.historyLimit` (`0` zum Deaktivieren).
Das Entfernen von Direktiven gilt nur für den Abschnitt der **aktuellen Nachricht**, damit der Verlauf intakt bleibt. Kanäle, die Verlauf umschließen, sollten `CommandBody` (oder `RawBody`) auf den ursprünglichen Nachrichtentext setzen und `Body` als kombinierten Prompt beibehalten. Verlaufspuffer sind über `messages.groupChat.historyLimit` (globaler Standard) und kanalbezogene Überschreibungen wie `channels.slack.historyLimit` oder `channels.telegram.accounts.<id>.historyLimit` konfigurierbar (`0` zum Deaktivieren).
## Warteschlangenbildung und Nachfassaktionen
## Warteschlangenbildung und Folgeanfragen
Wenn bereits ein Lauf aktiv ist, können eingehende Nachrichten in die Warteschlange gestellt, in den
aktuellen Lauf gelenkt oder für eine nachfolgende Runde gesammelt werden.
Wenn bereits ein Durchlauf aktiv ist, können eingehende Nachrichten in die Warteschlange gestellt, in den aktuellen Durchlauf gelenkt oder für einen Folge-Turn gesammelt werden.
- Konfiguration über `messages.queue` (und `messages.queue.byChannel`).
- Modi: `interrupt`, `steer`, `followup`, `collect` sowie Backlog-Varianten.
Details: [Warteschlangenbildung](/de/concepts/queue).
Details: [Queueing](/de/concepts/queue).
## Streaming, Aufteilung und Bündelung
## Streaming, Chunking und Batching
Block-Streaming sendet Teilantworten, während das Modell Textblöcke erzeugt.
Die Aufteilung beachtet Textgrenzen der Kanäle und vermeidet das Trennen von eingefasstem Code.
Chunking berücksichtigt Textlimits des Kanals und vermeidet das Aufteilen von Fenced-Code.
Wichtige Einstellungen:
- `agents.defaults.blockStreamingDefault` (`on|off`, Standard aus)
- `agents.defaults.blockStreamingDefault` (`on|off`, Standard ist off)
- `agents.defaults.blockStreamingBreak` (`text_end|message_end`)
- `agents.defaults.blockStreamingChunk` (`minChars|maxChars|breakPreference`)
- `agents.defaults.blockStreamingCoalesce` (Leerlaufbasierte Bündelung)
- `agents.defaults.blockStreamingCoalesce` (leerlaufbasiertes Batching)
- `agents.defaults.humanDelay` (menschenähnliche Pause zwischen Blockantworten)
- Kanalüberschreibungen: `*.blockStreaming` und `*.blockStreamingCoalesce` (Kanäle außer Telegram erfordern explizit `*.blockStreaming: true`)
- Kanalüberschreibungen: `*.blockStreaming` und `*.blockStreamingCoalesce` (Nicht-Telegram-Kanäle erfordern explizit `*.blockStreaming: true`)
Details: [Streaming + Aufteilung](/de/concepts/streaming).
Details: [Streaming + chunking](/de/concepts/streaming).
## Sichtbarkeit des Denkprozesses und Tokens
## Sichtbarkeit der Argumentation und Tokens
OpenClaw kann das Reasoning des Modells sichtbar machen oder verbergen:
OpenClaw kann Modellargumentation sichtbar machen oder verbergen:
- `/reasoning on|off|stream` steuert die Sichtbarkeit.
- Reasoning-Inhalte zählen weiterhin zum Token-Verbrauch, wenn sie vom Modell erzeugt werden.
- Telegram unterstützt das Streamen von Reasoning in die Entwurfsblase.
- Argumentationsinhalte zählen weiterhin zur Tokennutzung, wenn sie vom Modell erzeugt werden.
- Telegram unterstützt das Streamen der Argumentation in die Entwurfsblase.
Details: [Thinking- + Reasoning-Richtlinien](/de/tools/thinking) und [Token-Nutzung](/de/reference/token-use).
Details: [Thinking + reasoning directives](/de/tools/thinking) und [Token use](/de/reference/token-use).
## Präfixe, Threading und Antworten
@ -158,19 +139,18 @@ Die Formatierung ausgehender Nachrichten ist zentral in `messages` gebündelt:
- `messages.responsePrefix`, `channels.<channel>.responsePrefix` und `channels.<channel>.accounts.<id>.responsePrefix` (Kaskade für ausgehende Präfixe) sowie `channels.whatsapp.messagePrefix` (eingehendes WhatsApp-Präfix)
- Antwort-Threading über `replyToMode` und kanalbezogene Standards
Details: [Konfiguration](/de/gateway/configuration-reference#messages) und die Kanaldokumentation.
Details: [Configuration](/de/gateway/configuration-reference#messages) und die Kanaldokumentation.
## Stille Antworten
Das exakte stille Token `NO_REPLY` / `no_reply` bedeutet „keine für Nutzer sichtbare Antwort zustellen“.
OpenClaw löst dieses Verhalten je nach Unterhaltungstyp auf:
Das exakte Silent-Token `NO_REPLY` / `no_reply` bedeutet „keine für Benutzer sichtbare Antwort zustellen“.
OpenClaw löst dieses Verhalten je nach Konversationstyp auf:
- Direkte Unterhaltungen erlauben standardmäßig keine Stille und schreiben eine reine stille
Antwort in einen kurzen sichtbaren Fallback um.
- Gruppen/Kanäle erlauben standardmäßig Stille.
- Interne Orchestrierung erlaubt standardmäßig Stille.
- Direkte Konversationen lassen Stille standardmäßig nicht zu und schreiben eine reine stille Antwort in eine kurze sichtbare Fallback-Antwort um.
- Gruppen/Kanäle erlauben Stille standardmäßig.
- Interne Orchestrierung erlaubt Stille standardmäßig.
Standardwerte liegen unter `agents.defaults.silentReply` und
Standardwerte befinden sich unter `agents.defaults.silentReply` und
`agents.defaults.silentReplyRewrite`; `surfaces.<id>.silentReply` und
`surfaces.<id>.silentReplyRewrite` können sie pro Oberfläche überschreiben.

545
docs/de/concepts/model-providers.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Sie benötigen eine anbieterweise Referenz zur Modelleinrichtung
- Sie möchten Beispielkonfigurationen oder CLI-Onboarding-Befehle für Modellanbieter
summary: Überblick über Modellanbieter mit Beispielkonfigurationen + CLI-Abläufen
- Sie möchten Beispielkonfigurationen oder CLI-Onboarding-Befehle für Modellanbieter.
summary: Übersicht über Modellanbieter mit Beispielkonfigurationen + CLI-Abläufen
title: Modellanbieter
x-i18n:
generated_at: "2026-04-21T06:24:06Z"
generated_at: "2026-04-21T13:35:27Z"
model: gpt-5.4
provider: openai
source_hash: e433dfd51d1721832480089cb35ab1243e5c873a587f9968e14744840cb912cf
source_hash: 6732ab672757579c09395583a0f7d110348c909d4e4ab1d2accad68ad054c636
source_path: concepts/model-providers.md
workflow: 15
---
@ -16,135 +16,263 @@ x-i18n:
# Modellanbieter
Diese Seite behandelt **LLM-/Modellanbieter** (nicht Chat-Kanäle wie WhatsApp/Telegram).
Für Regeln zur Modellauswahl siehe [/concepts/models](/de/concepts/models).
Zu Regeln für die Modellauswahl siehe [/concepts/models](/de/concepts/models).
## Schnellregeln
## Schnelle Regeln
- Modell-Referenzen verwenden `provider/model` (Beispiel: `opencode/claude-opus-4-6`).
- Wenn Sie `agents.defaults.models` setzen, wird es zur Allowlist.
- CLI-Helfer: `openclaw onboard`, `openclaw models list`, `openclaw models set <provider/model>`.
- Laufzeitregeln für Fallbacks, Cooldown-Probes und die Persistenz von Sitzungs-Overrides sind in [/concepts/model-failover](/de/concepts/model-failover) dokumentiert.
- `models.providers.*.models[].contextWindow` ist native Modellmetadaten; `models.providers.*.models[].contextTokens` ist die effektive Laufzeitgrenze.
- Anbieter-Plugins können Modellkataloge über `registerProvider({ catalog })` injizieren; OpenClaw führt diese Ausgabe in `models.providers` zusammen, bevor `models.json` geschrieben wird.
- Anbietermanifeste können `providerAuthEnvVars` und `providerAuthAliases` deklarieren, damit generische env-basierte Auth-Probes und Anbietervarianten die Plugin-Laufzeit nicht laden müssen. Die verbleibende Core-Env-Var-Map ist jetzt nur noch für Nicht-Plugin-/Core-Anbieter und einige generische Vorrangfälle gedacht, etwa Anthropic-Onboarding mit API-Schlüssel zuerst.
- Anbieter-Plugins können außerdem das Laufzeitverhalten des Anbieters besitzen über `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`, `resolveDynamicModel`, `prepareDynamicModel`, `normalizeResolvedModel`, `contributeResolvedModelCompat`, `capabilities`, `normalizeToolSchemas`, `inspectToolSchemas`, `resolveReasoningOutputMode`, `prepareExtraParams`, `createStreamFn`, `wrapStreamFn`, `resolveTransportTurnState`, `resolveWebSocketSessionPolicy`, `createEmbeddingProvider`, `formatApiKey`, `refreshOAuth`, `buildAuthDoctorHint`, `matchesContextOverflowError`, `classifyFailoverReason`, `isCacheTtlEligible`, `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `isBinaryThinking`, `supportsXHighThinking`, `supportsAdaptiveThinking`, `supportsMaxThinking`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot` und `onModelSelected`.
- Hinweis: Laufzeit-`capabilities` des Anbieters sind gemeinsame Runner-Metadaten (Anbieterfamilie, Transcript-/Tooling-Eigenheiten, Transport-/Cache-Hinweise). Sie sind nicht dasselbe wie das [öffentliche Fähigkeitsmodell](/de/plugins/architecture#public-capability-model), das beschreibt, was ein Plugin registriert (Text-Inferenz, Sprache usw.).
- Der gebündelte Anbieter `codex` ist mit dem gebündelten Codex-Agent-Harness gekoppelt. Verwenden Sie `codex/gpt-*`, wenn Sie Codex-eigenen Login, Modellerkennung, native Thread-Fortsetzung und App-Server-Ausführung möchten. Einfache `openai/gpt-*`-Referenzen verwenden weiterhin den OpenAI-Anbieter und den normalen OpenClaw-Anbietertransport. Reine Codex-Deployments können den automatischen PI-Fallback mit `agents.defaults.embeddedHarness.fallback: "none"` deaktivieren; siehe [Codex Harness](/de/plugins/codex-harness).
- Modellreferenzen verwenden `provider/model` (Beispiel: `opencode/claude-opus-4-6`).
- Wenn Sie `agents.defaults.models` festlegen, wird es zur Zulassungsliste.
- CLI-Hilfen: `openclaw onboard`, `openclaw models list`, `openclaw models set <provider/model>`.
- Fallback-Laufzeitregeln, Cooldown-Sondierungen und die Persistenz von Sitzungsüberschreibungen
sind in [/concepts/model-failover](/de/concepts/model-failover) dokumentiert.
- `models.providers.*.models[].contextWindow` sind native Modellmetadaten;
`models.providers.*.models[].contextTokens` ist die effektive Laufzeitobergrenze.
- Anbieter-Plugins können Modellkataloge über `registerProvider({ catalog })` einschleusen;
OpenClaw führt diese Ausgabe vor dem Schreiben von
`models.json` in `models.providers` zusammen.
- Anbieter-Manifeste können `providerAuthEnvVars` und
`providerAuthAliases` deklarieren, sodass generische umgebungsvariablenbasierte Authentifizierungsprüfungen und Anbietervarianten
die Plugin-Laufzeit nicht laden müssen. Die verbleibende Kern-Zuordnung für Umgebungsvariablen ist jetzt
nur noch für Nicht-Plugin-/Kern-Anbieter und einige generische Präzedenzfälle gedacht, etwa
Anthropic-Onboarding mit API-Schlüssel zuerst.
- Anbieter-Plugins können auch das Laufzeitverhalten des Anbieters über
`normalizeModelId`, `normalizeTransport`, `normalizeConfig`,
`applyNativeStreamingUsageCompat`, `resolveConfigApiKey`,
`resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`,
`resolveDynamicModel`, `prepareDynamicModel`,
`normalizeResolvedModel`, `contributeResolvedModelCompat`,
`capabilities`, `normalizeToolSchemas`,
`inspectToolSchemas`, `resolveReasoningOutputMode`,
`prepareExtraParams`, `createStreamFn`, `wrapStreamFn`,
`resolveTransportTurnState`, `resolveWebSocketSessionPolicy`,
`createEmbeddingProvider`, `formatApiKey`, `refreshOAuth`,
`buildAuthDoctorHint`,
`matchesContextOverflowError`, `classifyFailoverReason`,
`isCacheTtlEligible`, `buildMissingAuthMessage`, `suppressBuiltInModel`,
`augmentModelCatalog`, `resolveThinkingProfile`, `isBinaryThinking`,
`supportsXHighThinking`, `resolveDefaultThinkingLevel`,
`applyConfigDefaults`, `isModernModelRef`,
`prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot` und
`onModelSelected` besitzen.
- Hinweis: Laufzeit-`capabilities` des Anbieters sind gemeinsame Runner-Metadaten (Anbieterfamilie,
Eigenheiten bei Transkripten/Tooling, Hinweise zu Transport/Cache). Sie sind nicht
dasselbe wie das [öffentliche Fähigkeitsmodell](/de/plugins/architecture#public-capability-model),
das beschreibt, was ein Plugin registriert (Textinferenz, Sprache usw.).
- Der gebündelte `codex`-Anbieter ist mit dem gebündelten Codex-Agent-Harness gekoppelt.
Verwenden Sie `codex/gpt-*`, wenn Sie Codex-eigenes Login, Modellerkennung, natives
Fortsetzen von Threads und Ausführung auf dem App-Server möchten. Einfache Referenzen wie `openai/gpt-*`
verwenden weiterhin den OpenAI-Anbieter und den normalen OpenClaw-Anbietertransport.
Rein auf Codex ausgerichtete Deployments können automatischen PI-Fallback mit
`agents.defaults.embeddedHarness.fallback: "none"` deaktivieren; siehe
[Codex Harness](/de/plugins/codex-harness).
## Plugin-eigenes Anbieterverhalten
Anbieter-Plugins können nun den Großteil der anbieterspezifischen Logik besitzen, während OpenClaw die generische Inferenzschleife beibehält.
Anbieter-Plugins können jetzt den Großteil der anbieterspezifischen Logik besitzen, während OpenClaw
die generische Inferenzschleife beibehält.
Typische Aufteilung:
- `auth[].run` / `auth[].runNonInteractive`: Anbieter besitzt Onboarding-/Login-Abläufe für `openclaw onboard`, `openclaw models auth` und Headless-Setup
- `wizard.setup` / `wizard.modelPicker`: Anbieter besitzt Beschriftungen für Auth-Auswahl, Legacy-Aliasse, Hinweise zur Onboarding-Allowlist und Setup-Einträge in Onboarding-/Modell-Pickern
- `catalog`: Anbieter erscheint in `models.providers`
- `normalizeModelId`: Anbieter normalisiert Legacy-/Vorschau-Modell-IDs vor Lookup oder Kanonisierung
- `normalizeTransport`: Anbieter normalisiert `api` / `baseUrl` der Transportfamilie vor dem generischen Modellaufbau; OpenClaw prüft zuerst den passenden Anbieter, dann andere hook-fähige Anbieter-Plugins, bis eines den Transport tatsächlich ändert
- `normalizeConfig`: Anbieter normalisiert die Konfiguration `models.providers.<id>`, bevor die Laufzeit sie verwendet; OpenClaw prüft zuerst den passenden Anbieter, dann andere hook-fähige Anbieter-Plugins, bis eines die Konfiguration tatsächlich ändert. Wenn kein Anbieter-Hook die Konfiguration umschreibt, normalisieren gebündelte Google-Familien-Helfer weiterhin unterstützte Google-Anbietereinträge.
- `applyNativeStreamingUsageCompat`: Anbieter wendet endpoint-gesteuerte native Kompatibilitätsumschreibungen für Streaming-Nutzung auf Konfigurationsanbieter an
- `resolveConfigApiKey`: Anbieter löst Env-Marker-Auth für Konfigurationsanbieter auf, ohne das vollständige Laden der Laufzeit-Auth zu erzwingen. `amazon-bedrock` hat hier außerdem einen eingebauten AWS-Env-Marker-Resolver, obwohl die Bedrock-Laufzeit-Auth die AWS-SDK-Standardkette verwendet.
- `resolveSyntheticAuth`: Anbieter kann lokale/self-hosted oder andere konfigurationsgestützte Auth-Verfügbarkeit verfügbar machen, ohne Klartext-Geheimnisse zu persistieren
- `shouldDeferSyntheticProfileAuth`: Anbieter kann gespeicherte synthetische Profil-Platzhalter als niedrigere Priorität als env-/konfigurationsgestützte Auth markieren
- `resolveDynamicModel`: Anbieter akzeptiert Modell-IDs, die noch nicht im lokalen statischen Katalog vorhanden sind
- `prepareDynamicModel`: Anbieter benötigt eine Aktualisierung der Metadaten, bevor die dynamische Auflösung erneut versucht wird
- `normalizeResolvedModel`: Anbieter benötigt Umschreibungen von Transport oder Basis-URL
- `contributeResolvedModelCompat`: Anbieter steuert Kompatibilitätsflags für seine Vendor-Modelle bei, selbst wenn sie über einen anderen kompatiblen Transport eintreffen
- `capabilities`: Anbieter veröffentlicht Eigenheiten von Transcript/Tooling/Anbieterfamilie
- `normalizeToolSchemas`: Anbieter bereinigt Tool-Schemas, bevor der eingebettete Runner sie sieht
- `inspectToolSchemas`: Anbieter macht transportspezifische Schemawarnungen nach der Normalisierung sichtbar
- `resolveReasoningOutputMode`: Anbieter wählt native oder getaggte Verträge für Reasoning-Ausgabe
- `prepareExtraParams`: Anbieter setzt Standardwerte oder normalisiert anfragespezifische Parameter pro Modell
- `createStreamFn`: Anbieter ersetzt den normalen Stream-Pfad durch einen vollständig benutzerdefinierten Transport
- `wrapStreamFn`: Anbieter wendet Wrapper für Anfrage-Header/Body/Modell-Kompatibilität an
- `resolveTransportTurnState`: Anbieter liefert native Header oder Metadaten des Transports pro Turn
- `resolveWebSocketSessionPolicy`: Anbieter liefert native Header für WebSocket-Sitzungen oder eine Sitzungs-Cooldown-Richtlinie
- `createEmbeddingProvider`: Anbieter besitzt das Verhalten von Memory Embeddings, wenn es zum Anbieter-Plugin statt zum Core-Embedding-Switchboard gehört
- `formatApiKey`: Anbieter formatiert gespeicherte Auth-Profile in den von dem Transport erwarteten Laufzeit-String `apiKey`
- `refreshOAuth`: Anbieter besitzt das OAuth-Refresh, wenn die gemeinsamen `pi-ai`-Refresher nicht ausreichen
- `buildAuthDoctorHint`: Anbieter ergänzt Reparaturhinweise, wenn das OAuth-Refresh fehlschlägt
- `matchesContextOverflowError`: Anbieter erkennt anbieterspezifische Fehler bei Überschreitung des Kontextfensters, die generische Heuristiken übersehen würden
- `classifyFailoverReason`: Anbieter ordnet anbieterspezifische rohe Transport-/API-Fehler Failover-Gründen wie Rate Limit oder Überlastung zu
- `isCacheTtlEligible`: Anbieter entscheidet, welche Upstream-Modell-IDs Prompt-Cache-TTL unterstützen
- `buildMissingAuthMessage`: Anbieter ersetzt den generischen Fehler des Auth-Speichers durch einen anbieterspezifischen Wiederherstellungshinweis
- `suppressBuiltInModel`: Anbieter blendet veraltete Upstream-Zeilen aus und kann für direkte Auflösungsfehler einen Vendor-eigenen Fehler zurückgeben
- `augmentModelCatalog`: Anbieter hängt nach Erkennung und Konfigurationszusammenführung synthetische/finale Katalogzeilen an
- `isBinaryThinking`: Anbieter besitzt die UX für binäres Thinking mit Ein/Aus
- `supportsXHighThinking`: Anbieter aktiviert `xhigh` für ausgewählte Modelle
- `supportsAdaptiveThinking`: Anbieter aktiviert `adaptive` für ausgewählte Modelle
- `supportsMaxThinking`: Anbieter aktiviert `max` für ausgewählte Modelle
- `resolveDefaultThinkingLevel`: Anbieter besitzt die Standardrichtlinie von `/think` für eine Modellfamilie
- `applyConfigDefaults`: Anbieter wendet anbieterspezifische globale Standardwerte während der Konfigurationsmaterialisierung an, basierend auf Auth-Modus, env oder Modellfamilie
- `isModernModelRef`: Anbieter besitzt die Zuordnung bevorzugter Modelle für Live-/Smoke-Tests
- `prepareRuntimeAuth`: Anbieter wandelt konfigurierte Zugangsdaten in ein kurzlebiges Laufzeit-Token um
- `resolveUsageAuth`: Anbieter löst Nutzungs-/Quota-Zugangsdaten für `/usage` und verwandte Status-/Reporting-Oberflächen auf
- `fetchUsageSnapshot`: Anbieter besitzt das Abrufen/Parsen des Nutzungsendpunkts, während der Core weiterhin die Zusammenfassungshülle und Formatierung besitzt
- `onModelSelected`: Anbieter führt Nebeneffekte nach der Modellauswahl aus, etwa Telemetrie oder anbieter-eigene Sitzungsbuchführung
- `auth[].run` / `auth[].runNonInteractive`: Der Anbieter besitzt Onboarding-/Login-
Abläufe für `openclaw onboard`, `openclaw models auth` und Headless-Setup
- `wizard.setup` / `wizard.modelPicker`: Der Anbieter besitzt Labels für die Authentifizierungsauswahl,
Legacy-Aliasse, Hinweise zur Zulassungsliste beim Onboarding und Setup-Einträge in Onboarding-/Modellauswahlen
- `catalog`: Der Anbieter erscheint in `models.providers`
- `normalizeModelId`: Der Anbieter normalisiert Legacy-/Vorschau-Modell-IDs vor
Nachschlagen oder Kanonisierung
- `normalizeTransport`: Der Anbieter normalisiert die Transportfamilie `api` / `baseUrl`
vor der generischen Modellzusammenstellung; OpenClaw prüft zuerst den passenden Anbieter,
dann andere Hook-fähige Anbieter-Plugins, bis eines den
Transport tatsächlich ändert
- `normalizeConfig`: Der Anbieter normalisiert die Konfiguration `models.providers.<id>` vor
der Verwendung zur Laufzeit; OpenClaw prüft zuerst den passenden Anbieter, dann andere
Hook-fähige Anbieter-Plugins, bis eines die Konfiguration tatsächlich ändert. Falls kein
Anbieter-Hook die Konfiguration umschreibt, normalisieren die gebündelten Helfer der Google-Familie weiterhin
unterstützte Google-Anbietereinträge.
- `applyNativeStreamingUsageCompat`: Der Anbieter wendet endpointgesteuerte native Streaming-/Nutzungs-Kompatibilitäts-Umschreibungen für Konfigurationsanbieter an
- `resolveConfigApiKey`: Der Anbieter löst Authentifizierung über Umgebungsvariablenmarker für Konfigurationsanbieter auf,
ohne das vollständige Laden der Laufzeit-Authentifizierung zu erzwingen. `amazon-bedrock` hat hier
ebenfalls einen eingebauten AWS-Resolver für Umgebungsvariablenmarker, obwohl die Bedrock-Laufzeit-Authentifizierung
die Standardkette des AWS SDK verwendet.
- `resolveSyntheticAuth`: Der Anbieter kann lokale/selbstgehostete oder andere
konfigurationsgestützte Authentifizierungsverfügbarkeit offenlegen, ohne Klartext-Geheimnisse zu speichern
- `shouldDeferSyntheticProfileAuth`: Der Anbieter kann gespeicherte synthetische Profil-
Platzhalter als niedrigere Priorität als umgebungs-/konfigurationsgestützte Authentifizierung markieren
- `resolveDynamicModel`: Der Anbieter akzeptiert Modell-IDs, die im lokalen
statischen Katalog noch nicht vorhanden sind
- `prepareDynamicModel`: Der Anbieter benötigt eine Metadatenaktualisierung, bevor die
dynamische Auflösung erneut versucht wird
- `normalizeResolvedModel`: Der Anbieter benötigt Umschreibungen von Transport oder Basis-URL
- `contributeResolvedModelCompat`: Der Anbieter steuert Kompatibilitäts-Flags für seine
Herstellermodelle bei, auch wenn diese über einen anderen kompatiblen Transport ankommen
- `capabilities`: Der Anbieter veröffentlicht Eigenheiten zu Transkripten/Tooling/Anbieterfamilie
- `normalizeToolSchemas`: Der Anbieter bereinigt Tool-Schemata, bevor der eingebettete
Runner sie sieht
- `inspectToolSchemas`: Der Anbieter zeigt transportspezifische Schemawarnungen
nach der Normalisierung an
- `resolveReasoningOutputMode`: Der Anbieter wählt native oder getaggte
Verträge für die Ausgabebegründung
- `prepareExtraParams`: Der Anbieter setzt Standardwerte oder normalisiert anfragebezogene Parameter pro Modell
- `createStreamFn`: Der Anbieter ersetzt den normalen Streaming-Pfad durch einen vollständig
benutzerdefinierten Transport
- `wrapStreamFn`: Der Anbieter wendet Wrapper für Anfrage-Header/Body/Modell-Kompatibilität an
- `resolveTransportTurnState`: Der Anbieter liefert native Transport-
Header oder Metadaten pro Zug
- `resolveWebSocketSessionPolicy`: Der Anbieter liefert native WebSocket-Sitzungs-
Header oder Cooldown-Richtlinien für Sitzungen
- `createEmbeddingProvider`: Der Anbieter besitzt das Verhalten für Speicher-Embeddings, wenn es
eher zum Anbieter-Plugin als zum Kern-Switchboard für Embeddings gehört
- `formatApiKey`: Der Anbieter formatiert gespeicherte Authentifizierungsprofile in den zur Laufzeit
vom Transport erwarteten `apiKey`-String
- `refreshOAuth`: Der Anbieter besitzt die OAuth-Aktualisierung, wenn die gemeinsamen
`pi-ai`-Aktualisierer nicht ausreichen
- `buildAuthDoctorHint`: Der Anbieter fügt Reparaturhinweise an, wenn die OAuth-Aktualisierung
fehlschlägt
- `matchesContextOverflowError`: Der Anbieter erkennt anbieterspezifische
Fehler bei Überschreitung des Kontextfensters, die generische Heuristiken übersehen würden
- `classifyFailoverReason`: Der Anbieter ordnet anbieterspezifische rohe Transport-/API-
Fehler Failover-Gründen wie Ratenbegrenzung oder Überlastung zu
- `isCacheTtlEligible`: Der Anbieter entscheidet, welche Upstream-Modell-IDs Prompt-Cache-TTL unterstützen
- `buildMissingAuthMessage`: Der Anbieter ersetzt den generischen Fehler des Authentifizierungsspeichers
durch einen anbieterspezifischen Wiederherstellungshinweis
- `suppressBuiltInModel`: Der Anbieter blendet veraltete Upstream-Zeilen aus und kann bei
direkten Auflösungsfehlern einen herstellereigenen Fehler zurückgeben
- `augmentModelCatalog`: Der Anbieter fügt nach Erkennung und Konfigurationszusammenführung
synthetische/finale Katalogzeilen an
- `resolveThinkingProfile`: Der Anbieter besitzt die genaue Menge an `/think`-Stufen,
optionale Anzeigelabels und die Standardstufe für ein ausgewähltes Modell
- `isBinaryThinking`: Kompatibilitäts-Hook für binäre Denk-UX mit Ein/Aus
- `supportsXHighThinking`: Kompatibilitäts-Hook für ausgewählte `xhigh`-Modelle
- `resolveDefaultThinkingLevel`: Kompatibilitäts-Hook für die Standardrichtlinie von `/think`
- `applyConfigDefaults`: Der Anbieter wendet anbieterspezifische globale Standardwerte
während der Konfigurationsmaterialisierung basierend auf Authentifizierungsmodus, Umgebung oder Modellfamilie an
- `isModernModelRef`: Der Anbieter besitzt den Abgleich bevorzugter Modelle für Live-/Smoke-Tests
- `prepareRuntimeAuth`: Der Anbieter wandelt ein konfiguriertes Zugangsmittel in ein kurzlebiges
Laufzeit-Token um
- `resolveUsageAuth`: Der Anbieter löst Zugangsdaten für Nutzung/Kontingent für `/usage`
und verwandte Status-/Berichtsoberflächen auf
- `fetchUsageSnapshot`: Der Anbieter besitzt das Abrufen/Parsen des Nutzungsendpunkts, während der
Kern weiterhin die Zusammenfassungs-Shell und Formatierung besitzt
- `onModelSelected`: Der Anbieter führt Nebeneffekte nach der Auswahl aus, etwa
Telemetrie oder anbietereigene Sitzungsbuchführung
Aktuelle gebündelte Beispiele:
- `anthropic`: Claude-4.6-Vorwärtskompatibilitäts-Fallback, Hinweise zur Auth-Reparatur, Abruf des Nutzungsendpunkts, Metadaten zu Cache-TTL/Anbieterfamilie und Auth-bewusste globale Konfigurationsstandards
- `amazon-bedrock`: Anbieter-eigenes Matching für Kontextüberlauf und Klassifizierung von Failover-Gründen für Bedrock-spezifische Drosselungs-/Nicht-bereit-Fehler sowie die gemeinsame Replay-Familie `anthropic-by-model` für Claude-exklusive Replay-Policy-Schutzmechanismen auf Anthropic-Datenverkehr
- `anthropic-vertex`: Claude-exklusive Replay-Policy-Schutzmechanismen auf Anthropic-Message-Datenverkehr
- `openrouter`: Durchreichen von Modell-IDs, Anfrage-Wrapper, Hinweise zu Anbieterfähigkeiten, Bereinigung von Gemini-Thought-Signaturen auf Proxy-Gemini-Datenverkehr, Proxy-Reasoning-Injektion über die Stream-Familie `openrouter-thinking`, Weiterleitung von Routing-Metadaten und Cache-TTL-Richtlinie
- `github-copilot`: Onboarding/Geräte-Login, Vorwärtskompatibilitäts-Fallback für Modelle, Hinweise zu Claude-Thinking-Transkripten, Austausch von Laufzeit-Token und Abruf des Nutzungsendpunkts
- `openai`: GPT-5.4-Vorwärtskompatibilitäts-Fallback, direkte Normalisierung des OpenAI-Transports, Codex-bewusste Hinweise für fehlende Auth, Unterdrückung von Spark, synthetische OpenAI-/Codex-Katalogzeilen, Thinking-/Live-Modell-Richtlinie, Alias-Normalisierung für Usage-Token (`input` / `output` und `prompt` / `completion`-Familien), die gemeinsame Stream-Familie `openai-responses-defaults` für native OpenAI-/Codex-Wrapper, Metadaten zur Anbieterfamilie, gebündelte Registrierung des Bildgenerierungsanbieters für `gpt-image-1` und gebündelte Registrierung des Videogenerierungsanbieters für `sora-2`
- `google` und `google-gemini-cli`: Gemini-3.1-Vorwärtskompatibilitäts-Fallback, native Gemini-Replay-Validierung, Bereinigung von Bootstrap-Replay, getaggter Ausgabemodus für Reasoning, modernes Modell-Matching, gebündelte Registrierung des Bildgenerierungsanbieters für Gemini-Image-Preview-Modelle und gebündelte Registrierung des Videogenerierungsanbieters für Veo-Modelle; Gemini-CLI-OAuth besitzt außerdem die Formatierung von Auth-Profil-Token, das Parsen von Usage-Token und das Abrufen von Quotenendpunkten für Usage-Oberflächen
- `moonshot`: gemeinsamer Transport, Plugin-eigene Normalisierung der Thinking-Payload
- `kilocode`: gemeinsamer Transport, Plugin-eigene Anfrage-Header, Normalisierung der Reasoning-Payload, Bereinigung von Proxy-Gemini-Thought-Signaturen und Cache-TTL-Richtlinie
- `zai`: GLM-5-Vorwärtskompatibilitäts-Fallback, Standardwerte für `tool_stream`, Cache-TTL-Richtlinie, Richtlinie für binäres Thinking/Live-Modelle und Usage-Auth + Quotenabruf; unbekannte `glm-5*`-IDs werden aus der gebündelten Vorlage `glm-4.7` synthetisiert
- `xai`: native Normalisierung des Responses-Transports, Umschreibungen von `/fast`-Aliasen für schnelle Grok-Varianten, Standard `tool_stream`, xAI-spezifische Bereinigung von Tool-Schemas / Reasoning-Payload und gebündelte Registrierung des Videogenerierungsanbieters für `grok-imagine-video`
- `mistral`: Plugin-eigene Metadaten zu Fähigkeiten
- `opencode` und `opencode-go`: Plugin-eigene Metadaten zu Fähigkeiten sowie Bereinigung von Proxy-Gemini-Thought-Signaturen
- `alibaba`: Plugin-eigener Videogenerierungskatalog für direkte Wan-Modell-Referenzen wie `alibaba/wan2.6-t2v`
- `byteplus`: Plugin-eigene Kataloge sowie gebündelte Registrierung des Videogenerierungsanbieters für Seedance-Text-zu-Video-/Bild-zu-Video-Modelle
- `fal`: gebündelte Registrierung des Videogenerierungsanbieters für gehostete Bildgenerierungsanbieter-Registrierung für FLUX-Bildmodelle sowie gebündelte Registrierung des Videogenerierungsanbieters für gehostete Drittanbieter-Videomodelle
- `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`, `stepfun`, `synthetic`, `venice`, `vercel-ai-gateway` und `volcengine`: nur Plugin-eigene Kataloge
- `qwen`: Plugin-eigene Kataloge für Textmodelle sowie gemeinsame Registrierungen von Anbietern für Medienverständnis und Videogenerierung für seine multimodalen Oberflächen; die Videogenerierung von Qwen verwendet die Standard-DashScope-Videoendpunkte mit gebündelten Wan-Modellen wie `wan2.6-t2v` und `wan2.7-r2v`
- `runway`: Plugin-eigene Registrierung des Videogenerierungsanbieters für native, auf Aufgaben basierende Runway-Modelle wie `gen4.5`
- `minimax`: Plugin-eigene Kataloge, gebündelte Registrierung des Videogenerierungsanbieters für Hailuo-Videomodelle, gebündelte Registrierung des Bildgenerierungsanbieters für `image-01`, hybride Auswahl der Anthropic-/OpenAI-Replay-Policy und Usage-Auth-/Snapshot-Logik
- `together`: Plugin-eigene Kataloge sowie gebündelte Registrierung des Videogenerierungsanbieters für Wan-Videomodelle
- `xiaomi`: Plugin-eigene Kataloge sowie Usage-Auth-/Snapshot-Logik
- `anthropic`: Claude-4.6-Vorwärtskompatibilitäts-Fallback, Hinweise zur Authentifizierungsreparatur, Abrufen des Nutzungsendpunkts,
Cache-TTL-/Anbieterfamilien-Metadaten und auth-bewusste globale
Konfigurationsstandards
- `amazon-bedrock`: anbieterseitige Erkennung von Kontextüberläufen und Failover-
Klassifizierung für Bedrock-spezifische Drosselungs-/Nicht-bereit-Fehler, plus
die gemeinsame Replay-Familie `anthropic-by-model` für Claude-spezifische Replay-Richtlinien-
Schutzmechanismen für Anthropic-Datenverkehr
- `anthropic-vertex`: Claude-spezifische Replay-Richtlinien-Schutzmechanismen für Anthropic-Message-
Datenverkehr
- `openrouter`: Durchreichen von Modell-IDs, Anfrage-Wrapper, Hinweise auf Anbieterfähigkeiten,
Bereinigung von Gemini-Thought-Signaturen bei proxied Gemini-Datenverkehr, Proxy-
Begründungsinjektion über die Stream-Familie `openrouter-thinking`, Weiterleitung von Routing-
Metadaten und Cache-TTL-Richtlinie
- `github-copilot`: Onboarding/Geräte-Login, Vorwärtskompatibilitäts-Modell-Fallback,
Hinweise zu Claude-Thinking-Transkripten, Austausch von Laufzeit-Token und Abrufen des Nutzungsendpunkts
- `openai`: GPT-5.4-Vorwärtskompatibilitäts-Fallback, direkte OpenAI-Transport-
Normalisierung, Codex-bewusste Hinweise bei fehlender Authentifizierung, Spark-Unterdrückung,
synthetische OpenAI-/Codex-Katalogzeilen, Thinking-/Live-Modell-Richtlinie, Normalisierung von
Nutzungs-Token-Aliasen (`input` / `output` und `prompt` / `completion`-Familien), die
gemeinsame Stream-Familie `openai-responses-defaults` für native OpenAI-/Codex-
Wrapper, Anbieterfamilien-Metadaten, gebündelte Registrierung des Bildgenerierungsanbieters
für `gpt-image-1` und gebündelte Registrierung des Videogenerierungsanbieters
für `sora-2`
- `google` und `google-gemini-cli`: Gemini-3.1-Vorwärtskompatibilitäts-Fallback,
native Gemini-Replay-Validierung, Bootstrap-Replay-Bereinigung, getaggter
Begründungsausgabemodus, Abgleich moderner Modelle, gebündelte Registrierung des Bildgenerierungs-
anbieter für Gemini-Image-Preview-Modelle und gebündelte
Registrierung des Videogenerierungsanbieters für Veo-Modelle; Gemini-CLI-OAuth
besitzt außerdem die Formatierung von Authentifizierungsprofil-Token, das Parsen von Nutzungs-Token
und das Abrufen des Kontingent-Endpunkts für Nutzungsoberflächen
- `moonshot`: gemeinsamer Transport, plugin-eigene Normalisierung von Thinking-Payloads
- `kilocode`: gemeinsamer Transport, plugin-eigene Anfrage-Header, Normalisierung von Reasoning-Payloads,
Bereinigung von Proxy-Gemini-Thought-Signaturen und Cache-TTL-
Richtlinie
- `zai`: GLM-5-Vorwärtskompatibilitäts-Fallback, `tool_stream`-Standards, Cache-TTL-
Richtlinie, binäre Thinking-/Live-Modell-Richtlinie und Nutzungsauthentifizierung + Abruf von Kontingenten;
unbekannte `glm-5*`-IDs werden aus der gebündelten Vorlage `glm-4.7` synthetisiert
- `xai`: native Responses-Transportnormalisierung, Umschreibungen von `/fast`-Aliasen für
schnelle Grok-Varianten, Standardwert `tool_stream`, xAI-spezifische Bereinigung von Tool-Schemata /
Reasoning-Payloads und gebündelte Registrierung des Videogenerierungsanbieters
für `grok-imagine-video`
- `mistral`: plugin-eigene Fähigkeitsmetadaten
- `opencode` und `opencode-go`: plugin-eigene Fähigkeitsmetadaten plus
Bereinigung von Proxy-Gemini-Thought-Signaturen
- `alibaba`: plugin-eigener Videogenerierungskatalog für direkte Wan-Modellreferenzen
wie `alibaba/wan2.6-t2v`
- `byteplus`: plugin-eigene Kataloge plus gebündelte Registrierung des Videogenerierungsanbieters
für Seedance-Text-zu-Video-/Bild-zu-Video-Modelle
- `fal`: gebündelte Registrierung des Videogenerierungsanbieters für gehostete Drittanbieter-
Registrierung des Bildgenerierungsanbieters für FLUX-Bildmodelle plus gebündelte
Registrierung des Videogenerierungsanbieters für gehostete Drittanbieter-Videomodelle
- `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`,
`stepfun`, `synthetic`, `venice`, `vercel-ai-gateway` und `volcengine`:
nur plugin-eigene Kataloge
- `qwen`: plugin-eigene Kataloge für Textmodelle plus gemeinsame
Registrierungen für Medienverständnis- und Videogenerierungsanbieter für seine
multimodalen Oberflächen; die Qwen-Videogenerierung verwendet die Standard-DashScope-Video-
Endpunkte mit gebündelten Wan-Modellen wie `wan2.6-t2v` und `wan2.7-r2v`
- `runway`: plugin-eigene Registrierung des Videogenerierungsanbieters für native
aufgabenbasierte Runway-Modelle wie `gen4.5`
- `minimax`: plugin-eigene Kataloge, gebündelte Registrierung des Videogenerierungsanbieters
für Hailuo-Videomodelle, gebündelte Registrierung des Bildgenerierungsanbieters
für `image-01`, hybride Auswahl von Anthropic-/OpenAI-Replay-Richtlinien
und Nutzungsauthentifizierung/Snapshot-Logik
- `together`: plugin-eigene Kataloge plus gebündelte Registrierung des Videogenerierungsanbieters
für Wan-Videomodelle
- `xiaomi`: plugin-eigene Kataloge plus Nutzungsauthentifizierung/Snapshot-Logik
Das gebündelte Plugin `openai` besitzt nun beide Anbieter-IDs: `openai` und `openai-codex`.
Das gebündelte Plugin `openai` besitzt jetzt beide Anbieter-IDs: `openai` und
`openai-codex`.
Damit sind Anbieter abgedeckt, die noch in die normalen Transporte von OpenClaw passen. Ein Anbieter, der einen vollständig benutzerdefinierten Anfrage-Executor benötigt, ist eine separate, tiefere Erweiterungsoberfläche.
Damit sind Anbieter abgedeckt, die noch in die normalen Transporte von OpenClaw passen. Ein Anbieter,
der einen vollständig benutzerdefinierten Anfrage-Executor benötigt, ist eine separate, tiefere Erweiterungsoberfläche.
## API-Schlüssel-Rotation
## API-Schlüsselrotation
- Unterstützt generische Anbieterrotation für ausgewählte Anbieter.
- Konfigurieren Sie mehrere Schlüssel über:
- `OPENCLAW_LIVE_<PROVIDER>_KEY` (einzelner Live-Override, höchste Priorität)
- `<PROVIDER>_API_KEYS` (durch Komma oder Semikolon getrennte Liste)
- `OPENCLAW_LIVE_<PROVIDER>_KEY` (einzelne Live-Überschreibung, höchste Priorität)
- `<PROVIDER>_API_KEYS` (kommagetrennte oder semikolongetrennte Liste)
- `<PROVIDER>_API_KEY` (primärer Schlüssel)
- `<PROVIDER>_API_KEY_*` (nummerierte Liste, z. B. `<PROVIDER>_API_KEY_1`)
- Für Google-Anbieter wird `GOOGLE_API_KEY` zusätzlich als Fallback einbezogen.
- Die Reihenfolge der Schlüsselauswahl bewahrt die Priorität und entfernt doppelte Werte.
- Anfragen werden nur bei Antworten mit Rate-Limit mit dem nächsten Schlüssel wiederholt (zum Beispiel `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` oder periodische Meldungen zu Usage-Limits).
- Fehler, die keine Rate-Limits sind, schlagen sofort fehl; es wird keine Schlüsselrotation versucht.
- Wenn alle Kandidatenschlüssel fehlschlagen, wird der letzte Fehler des letzten Versuchs zurückgegeben.
- Für Google-Anbieter ist `GOOGLE_API_KEY` zusätzlich als Fallback enthalten.
- Die Reihenfolge der Schlüsselauswahl bewahrt die Priorität und dedupliziert Werte.
- Anfragen werden nur bei Antworten mit Ratenbegrenzung mit dem nächsten Schlüssel wiederholt (zum
Beispiel `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many
concurrent requests`, `ThrottlingException`, `concurrency limit reached`,
`workers_ai ... quota limit exceeded` oder periodische Meldungen über Nutzungslimits).
- Fehler, die keine Ratenbegrenzung sind, schlagen sofort fehl; es wird keine Schlüsselrotation versucht.
- Wenn alle Kandidatenschlüssel fehlschlagen, wird der letzte Fehler aus dem letzten Versuch zurückgegeben.
## Eingebaute Anbieter (pi-ai-Katalog)
## Integrierte Anbieter (pi-ai-Katalog)
OpenClaw wird mit dem pi‑ai-Katalog ausgeliefert. Diese Anbieter erfordern **keine** Konfiguration in `models.providers`; setzen Sie einfach Auth und wählen Sie ein Modell.
OpenClaw wird mit dem pi-ai-Katalog ausgeliefert. Diese Anbieter benötigen **keine**
Konfiguration in `models.providers`; setzen Sie einfach die Authentifizierung und wählen Sie ein Modell.
### OpenAI
- Anbieter: `openai`
- Auth: `OPENAI_API_KEY`
- Optionale Rotation: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2` sowie `OPENCLAW_LIVE_OPENAI_KEY` (einzelner Override)
- Authentifizierung: `OPENAI_API_KEY`
- Optionale Rotation: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, plus `OPENCLAW_LIVE_OPENAI_KEY` (einzelne Überschreibung)
- Beispielmodelle: `openai/gpt-5.4`, `openai/gpt-5.4-pro`
- CLI: `openclaw onboard --auth-choice openai-api-key`
- Standardtransport ist `auto` (WebSocket zuerst, SSE als Fallback)
- Pro Modell überschreiben über `agents.defaults.models["openai/<model>"].params.transport` (`"sse"`, `"websocket"` oder `"auto"`)
- OpenAI-Responses-WebSocket-Warm-up ist standardmäßig über `params.openaiWsWarmup` aktiviert (`true`/`false`)
- OpenAI-Prioritätsverarbeitung kann über `agents.defaults.models["openai/<model>"].params.serviceTier` aktiviert werden
- `/fast` und `params.fastMode` ordnen direkte `openai/*`-Responses-Anfragen `service_tier=priority` auf `api.openai.com` zu
- Verwenden Sie `params.serviceTier`, wenn Sie eine explizite Stufe statt des gemeinsamen Schalters `/fast` möchten
- Versteckte OpenClaw-Attributions-Header (`originator`, `version`, `User-Agent`) gelten nur für nativen OpenAI-Datenverkehr zu `api.openai.com`, nicht für generische OpenAI-kompatible Proxys
- Native OpenAI-Routen behalten außerdem Responses-`store`, Prompt-Cache-Hinweise und OpenAI-Reasoning-kompatibles Payload-Shaping bei; Proxy-Routen nicht
- `openai/gpt-5.3-codex-spark` wird in OpenClaw absichtlich unterdrückt, weil die Live-OpenAI-API es ablehnt; Spark wird als Codex-exklusiv behandelt
- Der Standardtransport ist `auto` (zuerst WebSocket, SSE als Fallback)
- Überschreiben Sie pro Modell über `agents.defaults.models["openai/<model>"].params.transport` (`"sse"`, `"websocket"` oder `"auto"`)
- Das OpenAI-Responses-WebSocket-Warm-up ist standardmäßig über `params.openaiWsWarmup` aktiviert (`true`/`false`)
- Die OpenAI-Prioritätsverarbeitung kann über `agents.defaults.models["openai/<model>"].params.serviceTier` aktiviert werden
- `/fast` und `params.fastMode` ordnen direkte `openai/*`-Responses-Anfragen auf `api.openai.com` `service_tier=priority` zu
- Verwenden Sie `params.serviceTier`, wenn Sie statt des gemeinsamen `/fast`-Schalters einen expliziten Tier wünschen
- Versteckte OpenClaw-Attributions-Header (`originator`, `version`,
`User-Agent`) gelten nur für nativen OpenAI-Datenverkehr zu `api.openai.com`, nicht
für generische OpenAI-kompatible Proxys
- Native OpenAI-Routen behalten außerdem `store` für Responses, Prompt-Cache-Hinweise und
OpenAI-Reasoning-kompatible Payload-Formung bei; Proxy-Routen nicht
- `openai/gpt-5.3-codex-spark` wird in OpenClaw absichtlich unterdrückt, weil die Live-OpenAI-API es ablehnt; Spark wird als nur für Codex behandelt
```json5
{
@ -155,13 +283,13 @@ OpenClaw wird mit dem pi‑ai-Katalog ausgeliefert. Diese Anbieter erfordern **k
### Anthropic
- Anbieter: `anthropic`
- Auth: `ANTHROPIC_API_KEY`
- Optionale Rotation: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2` sowie `OPENCLAW_LIVE_ANTHROPIC_KEY` (einzelner Override)
- Authentifizierung: `ANTHROPIC_API_KEY`
- Optionale Rotation: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, plus `OPENCLAW_LIVE_ANTHROPIC_KEY` (einzelne Überschreibung)
- Beispielmodell: `anthropic/claude-opus-4-6`
- CLI: `openclaw onboard --auth-choice apiKey`
- Direkte öffentliche Anthropic-Anfragen unterstützen den gemeinsamen Schalter `/fast` und `params.fastMode`, einschließlich mit API-Schlüssel und OAuth authentifiziertem Datenverkehr an `api.anthropic.com`; OpenClaw ordnet das Anthropic-`service_tier` zu (`auto` vs `standard_only`)
- Anthropic-Hinweis: Mitarbeitende von Anthropic haben uns mitgeteilt, dass die Verwendung im Stil der Claude CLI mit OpenClaw wieder erlaubt ist, daher behandelt OpenClaw die Wiederverwendung der Claude CLI und die Nutzung von `claude -p` für diese Integration als zulässig, sofern Anthropic keine neue Richtlinie veröffentlicht.
- Anthropic-Setup-Token bleibt als unterstützter OpenClaw-Tokenpfad verfügbar, aber OpenClaw bevorzugt nun, wenn verfügbar, die Wiederverwendung der Claude CLI und `claude -p`.
- Direkte öffentliche Anthropic-Anfragen unterstützen auch den gemeinsamen `/fast`-Schalter und `params.fastMode`, einschließlich per API-Schlüssel und OAuth authentifiziertem Datenverkehr an `api.anthropic.com`; OpenClaw ordnet das Anthropic-`service_tier` zu (`auto` vs `standard_only`)
- Anthropic-Hinweis: Anthropic-Mitarbeitende haben uns mitgeteilt, dass OpenClaw-artige Claude-CLI-Nutzung wieder erlaubt ist, daher behandelt OpenClaw die Wiederverwendung der Claude CLI und die Nutzung von `claude -p` für diese Integration als zulässig, sofern Anthropic keine neue Richtlinie veröffentlicht.
- Anthropic-Setup-Token bleibt als unterstützter OpenClaw-Tokenpfad verfügbar, aber OpenClaw bevorzugt jetzt die Wiederverwendung der Claude CLI und `claude -p`, wenn verfügbar.
```json5
{
@ -172,16 +300,18 @@ OpenClaw wird mit dem pi‑ai-Katalog ausgeliefert. Diese Anbieter erfordern **k
### OpenAI Code (Codex)
- Anbieter: `openai-codex`
- Auth: OAuth (ChatGPT)
- Authentifizierung: OAuth (ChatGPT)
- Beispielmodell: `openai-codex/gpt-5.4`
- CLI: `openclaw onboard --auth-choice openai-codex` oder `openclaw models auth login --provider openai-codex`
- Standardtransport ist `auto` (WebSocket zuerst, SSE als Fallback)
- Pro Modell überschreiben über `agents.defaults.models["openai-codex/<model>"].params.transport` (`"sse"`, `"websocket"` oder `"auto"`)
- `params.serviceTier` wird ebenfalls bei nativen Codex-Responses-Anfragen weitergereicht (`chatgpt.com/backend-api`)
- Versteckte OpenClaw-Attributions-Header (`originator`, `version`, `User-Agent`) werden nur an nativen Codex-Datenverkehr zu `chatgpt.com/backend-api` angehängt, nicht an generische OpenAI-kompatible Proxys
- Teilt sich denselben Schalter `/fast` und dieselbe Konfiguration `params.fastMode` wie direktes `openai/*`; OpenClaw ordnet dies `service_tier=priority` zu
- `openai-codex/gpt-5.3-codex-spark` bleibt verfügbar, wenn der Codex-OAuth-Katalog es bereitstellt; abhängig von den Berechtigungen
- `openai-codex/gpt-5.4` behält natives `contextWindow = 1050000` und standardmäßig Laufzeit-`contextTokens = 272000`; überschreiben Sie die Laufzeitgrenze mit `models.providers.openai-codex.models[].contextTokens`
- Der Standardtransport ist `auto` (zuerst WebSocket, SSE als Fallback)
- Überschreiben Sie pro Modell über `agents.defaults.models["openai-codex/<model>"].params.transport` (`"sse"`, `"websocket"` oder `"auto"`)
- `params.serviceTier` wird ebenfalls bei nativen Codex-Responses-Anfragen weitergeleitet (`chatgpt.com/backend-api`)
- Versteckte OpenClaw-Attributions-Header (`originator`, `version`,
`User-Agent`) werden nur an nativen Codex-Datenverkehr zu
`chatgpt.com/backend-api` angehängt, nicht an generische OpenAI-kompatible Proxys
- Nutzt denselben `/fast`-Schalter und dieselbe Konfiguration `params.fastMode` wie direkte `openai/*`; OpenClaw ordnet dies `service_tier=priority` zu
- `openai-codex/gpt-5.3-codex-spark` bleibt verfügbar, wenn der Codex-OAuth-Katalog es bereitstellt; abhängig von Berechtigungen
- `openai-codex/gpt-5.4` behält natives `contextWindow = 1050000` und eine Standard-Laufzeitobergrenze von `contextTokens = 272000`; überschreiben Sie die Laufzeitobergrenze mit `models.providers.openai-codex.models[].contextTokens`
- Richtlinienhinweis: OpenAI-Codex-OAuth wird ausdrücklich für externe Tools/Workflows wie OpenClaw unterstützt.
```json5
@ -204,13 +334,13 @@ OpenClaw wird mit dem pi‑ai-Katalog ausgeliefert. Diese Anbieter erfordern **k
### Andere gehostete Optionen im Abonnementstil
- [Qwen Cloud](/de/providers/qwen): Qwen-Cloud-Anbieteroberfläche sowie Endpoint-Zuordnung für Alibaba DashScope und Coding Plan
- [MiniMax](/de/providers/minimax): Zugriff per MiniMax-Coding-Plan-OAuth oder API-Schlüssel
- [Qwen Cloud](/de/providers/qwen): Qwen-Cloud-Anbieteroberfläche plus Zuordnung der Alibaba-DashScope- und Coding-Plan-Endpunkte
- [MiniMax](/de/providers/minimax): MiniMax-Coding-Plan-OAuth- oder API-Schlüsselzugriff
- [GLM Models](/de/providers/glm): Z.AI Coding Plan oder allgemeine API-Endpunkte
### OpenCode
- Auth: `OPENCODE_API_KEY` (oder `OPENCODE_ZEN_API_KEY`)
- Authentifizierung: `OPENCODE_API_KEY` (oder `OPENCODE_ZEN_API_KEY`)
- Zen-Laufzeitanbieter: `opencode`
- Go-Laufzeitanbieter: `opencode-go`
- Beispielmodelle: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.5`
@ -225,18 +355,20 @@ OpenClaw wird mit dem pi‑ai-Katalog ausgeliefert. Diese Anbieter erfordern **k
### Google Gemini (API-Schlüssel)
- Anbieter: `google`
- Auth: `GEMINI_API_KEY`
- Optionale Rotation: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, Fallback `GOOGLE_API_KEY` und `OPENCLAW_LIVE_GEMINI_KEY` (einzelner Override)
- Authentifizierung: `GEMINI_API_KEY`
- Optionale Rotation: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, Fallback auf `GOOGLE_API_KEY` und `OPENCLAW_LIVE_GEMINI_KEY` (einzelne Überschreibung)
- Beispielmodelle: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview`
- Kompatibilität: Legacy-OpenClaw-Konfiguration mit `google/gemini-3.1-flash-preview` wird zu `google/gemini-3-flash-preview` normalisiert
- CLI: `openclaw onboard --auth-choice gemini-api-key`
- Direkte Gemini-Läufe akzeptieren außerdem `agents.defaults.models["google/<model>"].params.cachedContent` (oder das Legacy-`cached_content`), um einen anbieter-nativen Handle `cachedContents/...` weiterzureichen; Gemini-Cache-Treffer erscheinen als OpenClaw-`cacheRead`
- Direkte Gemini-Ausführungen akzeptieren außerdem `agents.defaults.models["google/<model>"].params.cachedContent`
(oder das Legacy-`cached_content`), um ein anbieternatives
Handle `cachedContents/...` weiterzuleiten; Gemini-Cache-Treffer erscheinen als OpenClaw-`cacheRead`
### Google Vertex und Gemini CLI
- Anbieter: `google-vertex`, `google-gemini-cli`
- Auth: Vertex verwendet gcloud ADC; Gemini CLI verwendet seinen OAuth-Ablauf
- Vorsicht: Gemini-CLI-OAuth in OpenClaw ist eine inoffizielle Integration. Einige Nutzer haben von Einschränkungen ihres Google-Kontos nach der Verwendung von Drittanbieter-Clients berichtet. Prüfen Sie die Google-Nutzungsbedingungen und verwenden Sie ein unkritisches Konto, wenn Sie sich dafür entscheiden.
- Authentifizierung: Vertex verwendet gcloud ADC; Gemini CLI verwendet seinen OAuth-Ablauf
- Vorsicht: Gemini-CLI-OAuth in OpenClaw ist eine inoffizielle Integration. Einige Nutzer haben nach der Verwendung von Drittanbieter-Clients Einschränkungen bei Google-Konten gemeldet. Prüfen Sie die Google-Bedingungen und verwenden Sie ein unkritisches Konto, wenn Sie fortfahren möchten.
- Gemini-CLI-OAuth wird als Teil des gebündelten `google`-Plugins ausgeliefert.
- Installieren Sie zuerst Gemini CLI:
- `brew install gemini-cli`
@ -244,14 +376,16 @@ OpenClaw wird mit dem pi‑ai-Katalog ausgeliefert. Diese Anbieter erfordern **k
- Aktivieren: `openclaw plugins enable google`
- Anmelden: `openclaw models auth login --provider google-gemini-cli --set-default`
- Standardmodell: `google-gemini-cli/gemini-3-flash-preview`
- Hinweis: Sie fügen **keine** Client-ID und kein Secret in `openclaw.json` ein. Der CLI-Login-Ablauf speichert Token in Auth-Profilen auf dem Gateway-Host.
- Wenn Anfragen nach dem Login fehlschlagen, setzen Sie `GOOGLE_CLOUD_PROJECT` oder `GOOGLE_CLOUD_PROJECT_ID` auf dem Gateway-Host.
- JSON-Antworten von Gemini CLI werden aus `response` geparst; die Nutzung greift auf `stats` zurück, wobei `stats.cached` in OpenClaw-`cacheRead` normalisiert wird.
- Hinweis: Sie fügen **keine** Client-ID und kein Secret in `openclaw.json` ein. Der CLI-Anmeldeablauf speichert
Token in Authentifizierungsprofilen auf dem Gateway-Host.
- Wenn Anfragen nach der Anmeldung fehlschlagen, setzen Sie `GOOGLE_CLOUD_PROJECT` oder `GOOGLE_CLOUD_PROJECT_ID` auf dem Gateway-Host.
- Gemini-CLI-JSON-Antworten werden aus `response` geparst; die Nutzung greift auf
`stats` zurück, wobei `stats.cached` in OpenClaw-`cacheRead` normalisiert wird.
### Z.AI (GLM)
- Anbieter: `zai`
- Auth: `ZAI_API_KEY`
- Authentifizierung: `ZAI_API_KEY`
- Beispielmodell: `zai/glm-5.1`
- CLI: `openclaw onboard --auth-choice zai-api-key`
- Aliasse: `z.ai/*` und `z-ai/*` werden zu `zai/*` normalisiert
@ -260,19 +394,22 @@ OpenClaw wird mit dem pi‑ai-Katalog ausgeliefert. Diese Anbieter erfordern **k
### Vercel AI Gateway
- Anbieter: `vercel-ai-gateway`
- Auth: `AI_GATEWAY_API_KEY`
- Authentifizierung: `AI_GATEWAY_API_KEY`
- Beispielmodell: `vercel-ai-gateway/anthropic/claude-opus-4.6`
- CLI: `openclaw onboard --auth-choice ai-gateway-api-key`
### Kilo Gateway
- Anbieter: `kilocode`
- Auth: `KILOCODE_API_KEY`
- Authentifizierung: `KILOCODE_API_KEY`
- Beispielmodell: `kilocode/kilo/auto`
- CLI: `openclaw onboard --auth-choice kilocode-api-key`
- Basis-URL: `https://api.kilo.ai/api/gateway/`
- Der statische Fallback-Katalog enthält `kilocode/kilo/auto`; die Live-Erkennung über `https://api.kilo.ai/api/gateway/models` kann den Laufzeitkatalog weiter erweitern.
- Das genaue Upstream-Routing hinter `kilocode/kilo/auto` wird von Kilo Gateway verwaltet und ist nicht fest in OpenClaw codiert.
- Der statische Fallback-Katalog liefert `kilocode/kilo/auto`; die Live-
Erkennung unter `https://api.kilo.ai/api/gateway/models` kann den Laufzeit-
Katalog weiter erweitern.
- Das genaue Upstream-Routing hinter `kilocode/kilo/auto` gehört zu Kilo Gateway
und ist nicht in OpenClaw fest kodiert.
Siehe [/providers/kilocode](/de/providers/kilocode) für Einrichtungsdetails.
@ -280,17 +417,26 @@ Siehe [/providers/kilocode](/de/providers/kilocode) für Einrichtungsdetails.
- OpenRouter: `openrouter` (`OPENROUTER_API_KEY`)
- Beispielmodell: `openrouter/auto`
- OpenClaw wendet die dokumentierten App-Attributions-Header von OpenRouter nur an, wenn die Anfrage tatsächlich an `openrouter.ai` geht
- OpenRouter-spezifische Anthropic-`cache_control`-Marker sind ebenfalls auf verifizierte OpenRouter-Routen beschränkt, nicht auf beliebige Proxy-URLs
- OpenRouter bleibt auf dem proxyartigen OpenAI-kompatiblen Pfad, daher werden natives, nur für OpenAI geltendes Anfrage-Shaping (`serviceTier`, Responses-`store`, Prompt-Cache-Hinweise, OpenAI-Reasoning-kompatible Payloads) nicht weitergereicht
- Gemini-gestützte OpenRouter-Referenzen behalten nur die Bereinigung von Proxy-Gemini-Thought-Signaturen; native Gemini-Replay-Validierung und Bootstrap-Umschreibungen bleiben deaktiviert
- OpenClaw wendet die dokumentierten App-Attributions-Header von OpenRouter nur an, wenn
die Anfrage tatsächlich an `openrouter.ai` geht
- OpenRouter-spezifische Anthropic-`cache_control`-Marker sind ebenso auf
verifizierte OpenRouter-Routen beschränkt, nicht auf beliebige Proxy-URLs
- OpenRouter bleibt auf dem Proxy-artigen OpenAI-kompatiblen Pfad, daher wird die native,
nur für OpenAI geltende Anfrageformung (`serviceTier`, Responses-`store`,
Prompt-Cache-Hinweise, OpenAI-Reasoning-kompatible Payloads) nicht weitergeleitet
- Auf Gemini basierende OpenRouter-Referenzen behalten nur die Bereinigung von Proxy-Gemini-Thought-Signaturen
bei; native Gemini-Replay-Validierung und Bootstrap-Umschreibungen bleiben deaktiviert
- Kilo Gateway: `kilocode` (`KILOCODE_API_KEY`)
- Beispielmodell: `kilocode/kilo/auto`
- Gemini-gestützte Kilo-Referenzen behalten denselben Bereinigungspfad für Proxy-Gemini-Thought-Signaturen; `kilocode/kilo/auto` und andere Hinweise ohne Unterstützung für Proxy-Reasoning überspringen die Proxy-Reasoning-Injektion
- Auf Gemini basierende Kilo-Referenzen behalten denselben Pfad zur Bereinigung von Proxy-Gemini-Thought-Signaturen;
`kilocode/kilo/auto` und andere Hinweise ohne Unterstützung für Proxy-Reasoning
überspringen die Injektion von Proxy-Reasoning
- MiniMax: `minimax` (API-Schlüssel) und `minimax-portal` (OAuth)
- Auth: `MINIMAX_API_KEY` für `minimax`; `MINIMAX_OAUTH_TOKEN` oder `MINIMAX_API_KEY` für `minimax-portal`
- Authentifizierung: `MINIMAX_API_KEY` für `minimax`; `MINIMAX_OAUTH_TOKEN` oder `MINIMAX_API_KEY` für `minimax-portal`
- Beispielmodell: `minimax/MiniMax-M2.7` oder `minimax-portal/MiniMax-M2.7`
- MiniMax-Onboarding/API-Key-Setup schreibt explizite M2.7-Modell-Definitionen mit `input: ["text", "image"]`; der gebündelte Anbieterkatalog hält die Chat-Referenzen nur für Text, bis diese Anbieter-Konfiguration materialisiert ist
- MiniMax-Onboarding/API-Schlüssel-Einrichtung schreibt explizite M2.7-Modelldefinitionen mit
`input: ["text", "image"]`; der gebündelte Anbieter-Katalog belässt die Chat-Referenzen
als nur Text, bis diese Anbieterkonfiguration materialisiert wird
- Moonshot: `moonshot` (`MOONSHOT_API_KEY`)
- Beispielmodell: `moonshot/kimi-k2.6`
- Kimi Coding: `kimi` (`KIMI_API_KEY` oder `KIMICODE_API_KEY`)
@ -317,8 +463,11 @@ Siehe [/providers/kilocode](/de/providers/kilocode) für Einrichtungsdetails.
- Beispielmodell: `byteplus-plan/ark-code-latest`
- xAI: `xai` (`XAI_API_KEY`)
- Native gebündelte xAI-Anfragen verwenden den xAI-Responses-Pfad
- `/fast` oder `params.fastMode: true` schreiben `grok-3`, `grok-3-mini`, `grok-4` und `grok-4-0709` auf ihre `*-fast`-Varianten um
- `tool_stream` ist standardmäßig aktiviert; setzen Sie `agents.defaults.models["xai/<model>"].params.tool_stream` auf `false`, um es zu deaktivieren
- `/fast` oder `params.fastMode: true` schreiben `grok-3`, `grok-3-mini`,
`grok-4` und `grok-4-0709` auf ihre `*-fast`-Varianten um
- `tool_stream` ist standardmäßig aktiviert; setzen Sie
`agents.defaults.models["xai/<model>"].params.tool_stream` auf `false`, um
dies zu deaktivieren
- Mistral: `mistral` (`MISTRAL_API_KEY`)
- Beispielmodell: `mistral/mistral-large-latest`
- CLI: `openclaw onboard --auth-choice mistral-api-key`
@ -331,16 +480,21 @@ Siehe [/providers/kilocode](/de/providers/kilocode) für Einrichtungsdetails.
## Anbieter über `models.providers` (benutzerdefiniert/Basis-URL)
Verwenden Sie `models.providers` (oder `models.json`), um **benutzerdefinierte** Anbieter oder OpenAI-/Anthropic-kompatible Proxys hinzuzufügen.
Verwenden Sie `models.providers` (oder `models.json`), um **benutzerdefinierte** Anbieter oder
OpenAI-/Anthropic-kompatible Proxys hinzuzufügen.
Viele der unten aufgeführten gebündelten Anbieter-Plugins veröffentlichen bereits einen Standardkatalog. Verwenden Sie explizite Einträge `models.providers.<id>` nur dann, wenn Sie die Standard-Basis-URL, Header oder Modellliste überschreiben möchten.
Viele der unten aufgeführten gebündelten Anbieter-Plugins veröffentlichen bereits einen Standardkatalog.
Verwenden Sie explizite Einträge in `models.providers.<id>` nur dann, wenn Sie die
Standard-Basis-URL, Header oder Modellliste überschreiben möchten.
### Moonshot AI (Kimi)
Moonshot wird als gebündeltes Anbieter-Plugin ausgeliefert. Verwenden Sie standardmäßig den eingebauten Anbieter und fügen Sie nur dann einen expliziten Eintrag `models.providers.moonshot` hinzu, wenn Sie die Basis-URL oder Modellmetadaten überschreiben müssen:
Moonshot wird als gebündeltes Anbieter-Plugin ausgeliefert. Verwenden Sie standardmäßig den integrierten Anbieter
und fügen Sie nur dann einen expliziten Eintrag `models.providers.moonshot` hinzu, wenn Sie die Basis-URL oder Modellmetadaten
überschreiben müssen:
- Anbieter: `moonshot`
- Auth: `MOONSHOT_API_KEY`
- Authentifizierung: `MOONSHOT_API_KEY`
- Beispielmodell: `moonshot/kimi-k2.6`
- CLI: `openclaw onboard --auth-choice moonshot-api-key` oder `openclaw onboard --auth-choice moonshot-api-key-cn`
@ -380,7 +534,7 @@ Kimi-K2-Modell-IDs:
Kimi Coding verwendet den Anthropic-kompatiblen Endpunkt von Moonshot AI:
- Anbieter: `kimi`
- Auth: `KIMI_API_KEY`
- Authentifizierung: `KIMI_API_KEY`
- Beispielmodell: `kimi/kimi-code`
```json5
@ -392,14 +546,14 @@ Kimi Coding verwendet den Anthropic-kompatiblen Endpunkt von Moonshot AI:
}
```
Legacy-`kimi/k2p5` wird weiterhin als kompatible Modell-ID akzeptiert.
Legacy-`kimi/k2p5` bleibt als Kompatibilitäts-Modell-ID akzeptiert.
### Volcano Engine (Doubao)
Volcano Engine (火山引擎) bietet in China Zugriff auf Doubao und andere Modelle.
Volcano Engine (火山引擎) bietet Zugriff auf Doubao und andere Modelle in China.
- Anbieter: `volcengine` (Coding: `volcengine-plan`)
- Auth: `VOLCANO_ENGINE_API_KEY`
- Authentifizierung: `VOLCANO_ENGINE_API_KEY`
- Beispielmodell: `volcengine-plan/ark-code-latest`
- CLI: `openclaw onboard --auth-choice volcengine-api-key`
@ -411,9 +565,13 @@ Volcano Engine (火山引擎) bietet in China Zugriff auf Doubao und andere Mode
}
```
Beim Onboarding wird standardmäßig die Coding-Oberfläche verwendet, aber der allgemeine Katalog `volcengine/*` wird gleichzeitig registriert.
Standardmäßig verwendet Onboarding die Coding-Oberfläche, aber der allgemeine Katalog `volcengine/*`
wird gleichzeitig registriert.
In Onboarding-/Konfigurations-Modell-Pickern bevorzugt die Volcengine-Auth-Auswahl sowohl Zeilen `volcengine/*` als auch `volcengine-plan/*`. Wenn diese Modelle noch nicht geladen sind, greift OpenClaw auf den ungefilterten Katalog zurück, anstatt einen leeren anbieterbezogenen Picker anzuzeigen.
In den Modell-Auswahlen für Onboarding/Konfiguration bevorzugt die Volcengine-Authentifizierungsoption sowohl
Zeilen `volcengine/*` als auch `volcengine-plan/*`. Wenn diese Modelle noch nicht geladen sind,
fällt OpenClaw auf den ungefilterten Katalog zurück, statt eine leere
anbieterspezifische Auswahl anzuzeigen.
Verfügbare Modelle:
@ -431,12 +589,12 @@ Coding-Modelle (`volcengine-plan`):
- `volcengine-plan/kimi-k2-thinking`
- `volcengine-plan/glm-4.7`
### BytePlus (international)
### BytePlus (International)
BytePlus ARK bietet internationalen Nutzern Zugriff auf dieselben Modelle wie Volcano Engine.
- Anbieter: `byteplus` (Coding: `byteplus-plan`)
- Auth: `BYTEPLUS_API_KEY`
- Authentifizierung: `BYTEPLUS_API_KEY`
- Beispielmodell: `byteplus-plan/ark-code-latest`
- CLI: `openclaw onboard --auth-choice byteplus-api-key`
@ -448,9 +606,13 @@ BytePlus ARK bietet internationalen Nutzern Zugriff auf dieselben Modelle wie Vo
}
```
Beim Onboarding wird standardmäßig die Coding-Oberfläche verwendet, aber der allgemeine Katalog `byteplus/*` wird gleichzeitig registriert.
Standardmäßig verwendet Onboarding die Coding-Oberfläche, aber der allgemeine Katalog `byteplus/*`
wird gleichzeitig registriert.
In Onboarding-/Konfigurations-Modell-Pickern bevorzugt die BytePlus-Auth-Auswahl sowohl Zeilen `byteplus/*` als auch `byteplus-plan/*`. Wenn diese Modelle noch nicht geladen sind, greift OpenClaw auf den ungefilterten Katalog zurück, anstatt einen leeren anbieterbezogenen Picker anzuzeigen.
In den Modell-Auswahlen für Onboarding/Konfiguration bevorzugt die BytePlus-Authentifizierungsoption sowohl
Zeilen `byteplus/*` als auch `byteplus-plan/*`. Wenn diese Modelle noch nicht geladen sind,
fällt OpenClaw auf den ungefilterten Katalog zurück, statt eine leere
anbieterspezifische Auswahl anzuzeigen.
Verfügbare Modelle:
@ -471,7 +633,7 @@ Coding-Modelle (`byteplus-plan`):
Synthetic stellt Anthropic-kompatible Modelle hinter dem Anbieter `synthetic` bereit:
- Anbieter: `synthetic`
- Auth: `SYNTHETIC_API_KEY`
- Authentifizierung: `SYNTHETIC_API_KEY`
- Beispielmodell: `synthetic/hf:MiniMaxAI/MiniMax-M2.5`
- CLI: `openclaw onboard --auth-choice synthetic-api-key`
@ -502,28 +664,31 @@ MiniMax wird über `models.providers` konfiguriert, weil es benutzerdefinierte E
- MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth`
- MiniMax API-Schlüssel (Global): `--auth-choice minimax-global-api`
- MiniMax API-Schlüssel (CN): `--auth-choice minimax-cn-api`
- Auth: `MINIMAX_API_KEY` für `minimax`; `MINIMAX_OAUTH_TOKEN` oder `MINIMAX_API_KEY` für `minimax-portal`
- Authentifizierung: `MINIMAX_API_KEY` für `minimax`; `MINIMAX_OAUTH_TOKEN` oder
`MINIMAX_API_KEY` für `minimax-portal`
Siehe [/providers/minimax](/de/providers/minimax) für Einrichtungsdetails, Modelloptionen und Konfigurationsbeispiele.
Auf dem Anthropic-kompatiblen Streaming-Pfad von MiniMax deaktiviert OpenClaw standardmäßig Thinking, sofern Sie es nicht explizit setzen, und `/fast on` schreibt `MiniMax-M2.7` auf `MiniMax-M2.7-highspeed` um.
Auf dem Anthropic-kompatiblen Streaming-Pfad von MiniMax deaktiviert OpenClaw Thinking
standardmäßig, sofern Sie es nicht explizit setzen, und `/fast on` schreibt
`MiniMax-M2.7` in `MiniMax-M2.7-highspeed` um.
Plugin-eigene Aufteilung der Fähigkeiten:
Plugin-eigene Fähigkeitsaufteilung:
- Standardwerte für Text/Chat bleiben auf `minimax/MiniMax-M2.7`
- Standards für Text/Chat bleiben auf `minimax/MiniMax-M2.7`
- Bildgenerierung ist `minimax/image-01` oder `minimax-portal/image-01`
- Bildverständnis ist das Plugin-eigene `MiniMax-VL-01` auf beiden MiniMax-Auth-Pfaden
- Die Websuche bleibt auf der Anbieter-ID `minimax`
- Bildverständnis ist plugin-eigenes `MiniMax-VL-01` auf beiden MiniMax-Authentifizierungspfaden
- Websuche bleibt auf Anbieter-ID `minimax`
### LM Studio
LM Studio wird als gebündeltes Anbieter-Plugin ausgeliefert, das die native API verwendet:
- Anbieter: `lmstudio`
- Auth: `LM_API_TOKEN`
- Authentifizierung: `LM_API_TOKEN`
- Standard-Basis-URL für Inferenz: `http://localhost:1234/v1`
Setzen Sie dann ein Modell (ersetzen Sie es durch eine der IDs, die von `http://localhost:1234/api/v1/models` zurückgegeben werden):
Legen Sie dann ein Modell fest (ersetzen Sie es durch eine der IDs, die von `http://localhost:1234/api/v1/models` zurückgegeben werden):
```json5
{
@ -533,7 +698,8 @@ Setzen Sie dann ein Modell (ersetzen Sie es durch eine der IDs, die von `http://
}
```
OpenClaw verwendet die nativen Endpunkte `/api/v1/models` und `/api/v1/models/load` von LM Studio für Erkennung + automatisches Laden und standardmäßig `/v1/chat/completions` für die Inferenz.
OpenClaw verwendet die nativen Endpunkte `/api/v1/models` und `/api/v1/models/load` von LM Studio
für Erkennung + automatisches Laden und standardmäßig `/v1/chat/completions` für Inferenz.
Siehe [/providers/lmstudio](/de/providers/lmstudio) für Einrichtung und Fehlerbehebung.
### Ollama
@ -541,12 +707,12 @@ Siehe [/providers/lmstudio](/de/providers/lmstudio) für Einrichtung und Fehlerb
Ollama wird als gebündeltes Anbieter-Plugin ausgeliefert und verwendet die native API von Ollama:
- Anbieter: `ollama`
- Auth: Nicht erforderlich (lokaler Server)
- Authentifizierung: Keine erforderlich (lokaler Server)
- Beispielmodell: `ollama/llama3.3`
- Installation: [https://ollama.com/download](https://ollama.com/download)
```bash
# Ollama installieren, dann ein Modell laden:
# Installieren Sie Ollama und laden Sie dann ein Modell:
ollama pull llama3.3
```
@ -558,23 +724,27 @@ ollama pull llama3.3
}
```
Ollama wird lokal unter `http://127.0.0.1:11434` erkannt, wenn Sie sich mit `OLLAMA_API_KEY` dafür entscheiden, und das gebündelte Anbieter-Plugin fügt Ollama direkt zu `openclaw onboard` und dem Modell-Picker hinzu. Siehe [/providers/ollama](/de/providers/ollama) für Onboarding, Cloud-/lokalen Modus und benutzerdefinierte Konfiguration.
Ollama wird lokal unter `http://127.0.0.1:11434` erkannt, wenn Sie mit
`OLLAMA_API_KEY` zustimmen, und das gebündelte Anbieter-Plugin fügt Ollama direkt zu
`openclaw onboard` und der Modellauswahl hinzu. Siehe [/providers/ollama](/de/providers/ollama)
für Onboarding, Cloud-/Lokalmodus und benutzerdefinierte Konfiguration.
### vLLM
vLLM wird als gebündeltes Anbieter-Plugin für lokale/self-hosted OpenAI-kompatible Server ausgeliefert:
vLLM wird als gebündeltes Anbieter-Plugin für lokale/selbstgehostete OpenAI-kompatible
Server ausgeliefert:
- Anbieter: `vllm`
- Auth: Optional (abhängig von Ihrem Server)
- Authentifizierung: Optional (abhängig von Ihrem Server)
- Standard-Basis-URL: `http://127.0.0.1:8000/v1`
Um sich lokal für die automatische Erkennung zu entscheiden (jeder Wert funktioniert, wenn Ihr Server keine Auth erzwingt):
So stimmen Sie der automatischen lokalen Erkennung zu (jeder Wert funktioniert, wenn Ihr Server keine Authentifizierung erzwingt):
```bash
export VLLM_API_KEY="vllm-local"
```
Setzen Sie dann ein Modell (ersetzen Sie es durch eine der IDs, die von `/v1/models` zurückgegeben werden):
Legen Sie dann ein Modell fest (ersetzen Sie es durch eine der IDs, die von `/v1/models` zurückgegeben werden):
```json5
{
@ -588,19 +758,21 @@ Siehe [/providers/vllm](/de/providers/vllm) für Details.
### SGLang
SGLang wird als gebündeltes Anbieter-Plugin für schnelle self-hosted OpenAI-kompatible Server ausgeliefert:
SGLang wird als gebündeltes Anbieter-Plugin für schnelle selbstgehostete
OpenAI-kompatible Server ausgeliefert:
- Anbieter: `sglang`
- Auth: Optional (abhängig von Ihrem Server)
- Authentifizierung: Optional (abhängig von Ihrem Server)
- Standard-Basis-URL: `http://127.0.0.1:30000/v1`
Um sich lokal für die automatische Erkennung zu entscheiden (jeder Wert funktioniert, wenn Ihr Server keine Auth erzwingt):
So stimmen Sie der automatischen lokalen Erkennung zu (jeder Wert funktioniert, wenn Ihr Server keine
Authentifizierung erzwingt):
```bash
export SGLANG_API_KEY="sglang-local"
```
Setzen Sie dann ein Modell (ersetzen Sie es durch eine der IDs, die von `/v1/models` zurückgegeben werden):
Legen Sie dann ein Modell fest (ersetzen Sie es durch eine der IDs, die von `/v1/models` zurückgegeben werden):
```json5
{
@ -657,10 +829,13 @@ Hinweise:
- `contextWindow: 200000`
- `maxTokens: 8192`
- Empfohlen: Setzen Sie explizite Werte, die zu Ihren Proxy-/Modellgrenzen passen.
- Für `api: "openai-completions"` auf nicht-nativen Endpunkten (jede nicht leere `baseUrl`, deren Host nicht `api.openai.com` ist) erzwingt OpenClaw `compat.supportsDeveloperRole: false`, um 400-Fehler des Anbieters bei nicht unterstützten `developer`-Rollen zu vermeiden.
- Proxy-artige OpenAI-kompatible Routen überspringen außerdem natives, nur für OpenAI geltendes Anfrage-Shaping: kein `service_tier`, kein Responses-`store`, keine Prompt-Cache-Hinweise, kein OpenAI-Reasoning-kompatibles Payload-Shaping und keine versteckten OpenClaw-Attributions-Header.
- Wenn `baseUrl` leer ist oder weggelassen wird, behält OpenClaw das Standardverhalten von OpenAI bei (das zu `api.openai.com` aufgelöst wird).
- Aus Sicherheitsgründen wird ein explizites `compat.supportsDeveloperRole: true` auf nicht-nativen Endpunkten `openai-completions` weiterhin überschrieben.
- Für `api: "openai-completions"` auf nicht-nativen Endpunkten (jede nicht leere `baseUrl`, deren Host nicht `api.openai.com` ist), erzwingt OpenClaw `compat.supportsDeveloperRole: false`, um 400-Fehler des Anbieters bei nicht unterstützten `developer`-Rollen zu vermeiden.
- Proxy-artige OpenAI-kompatible Routen überspringen auch die native, nur für OpenAI geltende Anfrageformung:
kein `service_tier`, kein Responses-`store`, keine Prompt-Cache-Hinweise, keine
OpenAI-Reasoning-kompatible Payload-Formung und keine versteckten OpenClaw-Attributions-
Header.
- Wenn `baseUrl` leer ist oder ausgelassen wird, behält OpenClaw das Standardverhalten von OpenAI bei (das zu `api.openai.com` aufgelöst wird).
- Zur Sicherheit wird ein explizites `compat.supportsDeveloperRole: true` auf nicht-nativen `openai-completions`-Endpunkten weiterhin überschrieben.
## CLI-Beispiele
@ -676,5 +851,5 @@ Siehe auch: [/gateway/configuration](/de/gateway/configuration) für vollständi
- [Models](/de/concepts/models) — Modellkonfiguration und Aliasse
- [Model Failover](/de/concepts/model-failover) — Fallback-Ketten und Wiederholungsverhalten
- [Konfigurationsreferenz](/de/gateway/configuration-reference#agent-defaults) — Modell-Konfigurationsschlüssel
- [Anbieter](/de/providers) — anbieterbezogene Einrichtungsanleitungen
- [Configuration Reference](/de/gateway/configuration-reference#agent-defaults) — Schlüssel der Modellkonfiguration
- [Providers](/de/providers) — Einrichtungsanleitungen pro Anbieter

304
docs/de/gateway/troubleshooting.md
View File

@ -1,21 +1,21 @@
---
read_when:
- Das Hub für die Fehlerbehebung hat Sie für eine tiefergehende Diagnose hierher verwiesen
- Sie benötigen stabile, symptombasierte Runbook-Abschnitte mit exakten Befehlen
summary: Detailliertes Runbook zur Fehlerbehebung für Gateway, Kanäle, Automatisierung, Nodes und Browser
- Der Hub zur Fehlerbehebung hat Sie für eine tiefergehende Diagnose hierher verwiesen.
- Sie benötigen stabile symptomorientierte Runbook-Abschnitte mit exakten Befehlen.
summary: Tiefer Runbook zur Fehlerbehebung für Gateway, Channels, Automatisierung, Nodes und Browser
title: Fehlerbehebung
x-i18n:
generated_at: "2026-04-21T06:25:46Z"
generated_at: "2026-04-21T13:35:28Z"
model: gpt-5.4
provider: openai
source_hash: 2afb105376bb467e5a344e6d73726908cb718fa13116b751fddb494a0b641c42
source_hash: add7625785e3b78897c750b4785b7fe84a3d91c23c4175de750c4834272967f9
source_path: gateway/troubleshooting.md
workflow: 15
---
# Fehlerbehebung beim Gateway
Diese Seite ist das ausführliche Runbook.
Diese Seite ist das tiefe Runbook.
Beginnen Sie bei [/help/troubleshooting](/de/help/troubleshooting), wenn Sie zuerst den schnellen Triage-Ablauf möchten.
## Befehlsleiter
@ -30,11 +30,11 @@ openclaw doctor
openclaw channels status --probe
```
Erwartete Signale für einen gesunden Zustand:
Erwartete Signale bei gesundem Zustand:
- `openclaw gateway status` zeigt `Runtime: running`, `Connectivity probe: ok` und eine Zeile `Capability: ...`.
- `openclaw doctor` meldet keine blockierenden Konfigurations-/Serviceprobleme.
- `openclaw channels status --probe` zeigt Live-Transportstatus pro Konto und,
- `openclaw channels status --probe` zeigt den Live-Transportstatus pro Konto und,
wo unterstützt, Probe-/Audit-Ergebnisse wie `works` oder `audit ok`.
## Anthropic 429: zusätzliche Nutzung für langen Kontext erforderlich
@ -48,17 +48,17 @@ openclaw models status
openclaw config get agents.defaults.models
```
Achten Sie auf:
Achten Sie auf Folgendes:
- Das ausgewählte Anthropic-Opus-/Sonnet-Modell hat `params.context1m: true`.
- Die aktuelle Anthropic-Anmeldedaten sind nicht für die Nutzung mit langem Kontext geeignet.
- Anfragen schlagen nur bei langen Sitzungen/Modelläufen fehl, die den 1M-Beta-Pfad benötigen.
- Die aktuelle Anthropic-Anmeldung ist nicht für die Nutzung mit langem Kontext berechtigt.
- Anfragen schlagen nur bei langen Sitzungen/Modellausführungen fehl, die den 1M-Betapfad benötigen.
Optionen zur Behebung:
1. Deaktivieren Sie `context1m` für dieses Modell, um auf das normale Kontextfenster zurückzufallen.
2. Verwenden Sie Anthropic-Anmeldedaten, die für Anfragen mit langem Kontext geeignet sind, oder wechseln Sie zu einem Anthropic-API-Schlüssel.
3. Konfigurieren Sie Fallback-Modelle, damit Läufe fortgesetzt werden, wenn Anthropic-Anfragen mit langem Kontext abgelehnt werden.
2. Verwenden Sie eine Anthropic-Anmeldung, die für Langkontext-Anfragen berechtigt ist, oder wechseln Sie zu einem Anthropic-API-Schlüssel.
3. Konfigurieren Sie Fallback-Modelle, damit Ausführungen weiterlaufen, wenn Anthropic-Langkontext-Anfragen abgelehnt werden.
Verwandt:
@ -66,13 +66,13 @@ Verwandt:
- [/reference/token-use](/de/reference/token-use)
- [/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/de/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)
## Lokales OpenAI-kompatibles Backend besteht direkte Probes, aber Agent-Läufe schlagen fehl
## Lokales OpenAI-kompatibles Backend besteht direkte Probes, aber Agent-Ausführungen schlagen fehl
Verwenden Sie dies, wenn:
- `curl ... /v1/models` funktioniert
- kleine direkte `/v1/chat/completions`-Aufrufe funktionieren
- OpenClaw-Modelläufe nur bei normalen Agent-Turns fehlschlagen
- winzige direkte `/v1/chat/completions`-Aufrufe funktionieren
- OpenClaw-Modellausführungen nur bei normalen Agent-Zügen fehlschlagen
```bash
curl http://127.0.0.1:1234/v1/models
@ -83,35 +83,33 @@ openclaw infer model run --model <provider/model> --prompt "hi" --json
openclaw logs --follow
```
Achten Sie auf:
Achten Sie auf Folgendes:
- direkte kleine Aufrufe sind erfolgreich, aber OpenClaw-Läufe schlagen nur bei größeren Prompts fehl
- Backend-Fehler darüber, dass `messages[].content` einen String erwartet
- Backend-Abstürze, die nur bei höherer Prompt-Token-Zahl oder vollständigen Agent-
Laufzeit-Prompts auftreten
- direkte winzige Aufrufe sind erfolgreich, aber OpenClaw-Ausführungen schlagen nur bei größeren Prompts fehl
- Backend-Fehler dazu, dass `messages[].content` einen String erwartet
- Backend-Abstürze, die nur bei größeren Prompt-Token-Anzahlen oder vollständigen Agent-Laufzeit-Prompts auftreten
Häufige Signaturen:
- `messages[...].content: invalid type: sequence, expected a string` → Backend
lehnt strukturierte Chat-Completions-Content-Teile ab. Behebung: setzen Sie
- `messages[...].content: invalid type: sequence, expected a string` → Das Backend
lehnt strukturierte Chat-Completions-Content-Teile ab. Behebung: Setzen Sie
`models.providers.<provider>.models[].compat.requiresStringContent: true`.
- direkte kleine Anfragen sind erfolgreich, aber OpenClaw-Agent-Turns schlagen mit Backend-/Modell-
Abstürzen fehl (zum Beispiel Gemma auf einigen `inferrs`-Builds) → OpenClaw-Transport ist
wahrscheinlich bereits korrekt; das Backend scheitert an der größeren Form des Agent-
Laufzeit-Prompts.
- Fehler gehen nach dem Deaktivieren von Tools zurück, verschwinden aber nicht → Tool-Schemas waren
Teil des Drucks, aber das verbleibende Problem liegt weiterhin in der vorgelagerten Modell-/Server-
Kapazität oder einem Backend-Fehler.
- direkte winzige Anfragen sind erfolgreich, aber OpenClaw-Agent-Ausführungen schlagen mit Backend-/Modell-Abstürzen fehl
(zum Beispiel Gemma auf einigen `inferrs`-Builds) → OpenClaw-Transport ist
wahrscheinlich bereits korrekt; das Backend scheitert an der größeren Prompt-Form der Agent-Laufzeit.
- Fehler werden geringer, nachdem Tools deaktiviert wurden, verschwinden aber nicht →
Tool-Schemas waren Teil des Drucks, aber das verbleibende Problem ist weiterhin
eine Upstream-Modell-/Server-Kapazitätsgrenze oder ein Backend-Fehler.
Optionen zur Behebung:
1. Setzen Sie `compat.requiresStringContent: true` für Chat-Completions-Backends, die nur Strings unterstützen.
2. Setzen Sie `compat.supportsTools: false` für Modelle/Backends, die die
Tool-Schema-Oberfläche von OpenClaw nicht zuverlässig verarbeiten können.
3. Verringern Sie nach Möglichkeit den Prompt-Druck: kleinerer Workspace-Bootstrap, kürzerer
3. Reduzieren Sie nach Möglichkeit den Prompt-Druck: kleinerer Workspace-Bootstrap, kürzerer
Sitzungsverlauf, leichteres lokales Modell oder ein Backend mit stärkerer Unterstützung für langen Kontext.
4. Wenn direkte kleine Anfragen weiterhin erfolgreich sind, während OpenClaw-Agent-Turns im Backend noch immer abstürzen,
behandeln Sie dies als vorgelagerte Server-/Modellbeschränkung und melden Sie dort
4. Wenn direkte winzige Anfragen weiterhin erfolgreich sind, während OpenClaw-Agent-Züge im Backend weiter abstürzen,
behandeln Sie dies als Upstream-Server-/Modell-Einschränkung und melden Sie dort
eine Reproduktion mit der akzeptierten Payload-Form.
Verwandt:
@ -122,7 +120,7 @@ Verwandt:
## Keine Antworten
Wenn Kanäle aktiv sind, aber nichts antwortet, prüfen Sie Routing und Richtlinie, bevor Sie irgendetwas neu verbinden.
Wenn Channels aktiv sind, aber nichts antwortet, prüfen Sie Routing und Richtlinien, bevor Sie irgendetwas erneut verbinden.
```bash
openclaw status
@ -132,17 +130,17 @@ openclaw config get channels
openclaw logs --follow
```
Achten Sie auf:
Achten Sie auf Folgendes:
- Pairing ausstehend für DM-Absender.
- Erwähnungs-Gating in Gruppen (`requireMention`, `mentionPatterns`).
- Nicht passende Kanal-/Gruppen-Allowlist-Konfigurationen.
- Nicht übereinstimmende Channel-/Gruppen-Allowlists.
Häufige Signaturen:
- `drop guild message (mention required` → Gruppennachricht wird ignoriert, bis eine Erwähnung erfolgt.
- `pairing request` → Absender benötigt Genehmigung.
- `blocked` / `allowlist` → Absender/Kanal wurde durch Richtlinie gefiltert.
- `pairing request` → Absender benötigt eine Freigabe.
- `blocked` / `allowlist` → Absender/Channel wurde durch Richtlinien gefiltert.
Verwandt:
@ -162,52 +160,51 @@ openclaw doctor
openclaw gateway status --json
```
Achten Sie auf:
Achten Sie auf Folgendes:
- korrekte Probe-URL und Dashboard-URL.
- Authentifizierungsmodus-/Token-Fehlanpassung zwischen Client und Gateway.
- HTTP-Nutzung, wenn Geräteidentität erforderlich ist.
- korrekte Probe-URL und Dashboard-URL
- Nichtübereinstimmung von Authentifizierungsmodus/Token zwischen Client und Gateway
- HTTP-Nutzung, wo Geräteidentität erforderlich ist
Häufige Signaturen:
- `device identity required` → unsicherer Kontext oder fehlende Geräteauthentifizierung.
- `origin not allowed` → Browser-`Origin` ist nicht in `gateway.controlUi.allowedOrigins`
(oder Sie verbinden sich von einem Nicht-Loopback-Browser-Origin ohne explizite
(oder Sie verbinden sich von einer Browser-`Origin` außerhalb von Loopback ohne eine explizite
Allowlist).
- `device nonce required` / `device nonce mismatch` → Client führt den
challenge-basierten Geräteauthentifizierungsablauf nicht vollständig aus (`connect.challenge` + `device.nonce`).
- `device nonce required` / `device nonce mismatch` → Client schließt den
challengebasierten Geräteauthentifizierungsablauf nicht ab (`connect.challenge` + `device.nonce`).
- `device signature invalid` / `device signature expired` → Client hat die falsche
Payload (oder einen veralteten Zeitstempel) für den aktuellen Handshake signiert.
- `AUTH_TOKEN_MISMATCH` mit `canRetryWithDeviceToken=true` → Client kann einen vertrauenswürdigen Wiederholungsversuch mit zwischengespeichertem Gerätetoken durchführen.
- Dieser Wiederholungsversuch mit zwischengespeichertem Token verwendet den zwischengespeicherten Scope-Satz erneut, der mit dem gekoppelten
Gerätetoken gespeichert wurde. Aufrufer mit explizitem `deviceToken` / expliziten `scopes` behalten stattdessen ihren
angeforderten Scope-Satz.
- Außerhalb dieses Wiederholungswegs ist die Priorität der Verbindungsauthentifizierung:
zuerst explizites gemeinsames Token/Passwort, dann explizites
`deviceToken`, dann gespeichertes Gerätetoken,
- Dieser Wiederholungsversuch mit zwischengespeichertem Token verwendet die mit dem gekoppelten
Gerätetoken gespeicherte Scope-Menge erneut. Aufrufer mit explizitem `deviceToken` / expliziten `scopes` behalten stattdessen ihre
angeforderte Scope-Menge bei.
- Außerhalb dieses Wiederholungswegs ist die Priorität der Verbindungsauthentifizierung zuerst explizites gemeinsames
Token/Passwort, dann explizites `deviceToken`, dann gespeichertes Gerätetoken,
dann Bootstrap-Token.
- Auf dem asynchronen Tailscale-Serve-Control-UI-Pfad werden fehlgeschlagene Versuche für denselben
`{scope, ip}` serialisiert, bevor der Limiter den Fehler aufzeichnet. Zwei fehlerhafte
gleichzeitige Wiederholungsversuche vom selben Client können daher beim zweiten Versuch
`retry later` anzeigen statt zwei einfacher Fehlanpassungen.
- Im asynchronen Tailscale-Serve-Control-UI-Pfad werden fehlgeschlagene Versuche für dieselbe
`{scope, ip}` serialisiert, bevor der Limiter den Fehler erfasst. Zwei falsche
gleichzeitige Wiederholungsversuche vom selben Client können daher beim zweiten Versuch `retry later`
ausgeben statt zwei einfacher Nichtübereinstimmungen.
- `too many failed authentication attempts (retry later)` von einem Browser-Origin-
Loopback-Client → wiederholte Fehlschläge von demselben normalisierten `Origin` werden
vorübergehend gesperrt; ein anderer localhost-Origin verwendet einen separaten Bucket.
- wiederholtes `unauthorized` danach → Drift bei gemeinsamem Token/Gerätetoken; aktualisieren Sie die Token-Konfiguration und genehmigen/rotieren Sie das Gerätetoken bei Bedarf erneut.
- `gateway connect failed:` → falsches Host-/Port-/URL-Ziel.
Loopback-Client → wiederholte Fehlschläge von derselben normalisierten `Origin` werden
vorübergehend gesperrt; eine andere localhost-Origin verwendet einen separaten Bucket.
- wiederholtes `unauthorized` nach diesem Wiederholungsversuch → Abweichung bei gemeinsamem Token/Gerätetoken; aktualisieren Sie die Token-Konfiguration und genehmigen/rotieren Sie das Gerätetoken bei Bedarf erneut.
- `gateway connect failed:` → falscher Host-/Port-/URL-Zielwert.
### Kurzübersicht der Auth-Detailcodes
### Kurzzuordnung der Authentifizierungs-Detailcodes
Verwenden Sie `error.details.code` aus der fehlgeschlagenen `connect`-Antwort, um die nächste Aktion auszuwählen:
| Detailcode | Bedeutung | Empfohlene Aktion |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_TOKEN_MISSING` | Client hat kein erforderliches gemeinsames Token gesendet. | Fügen Sie das Token im Client ein/setzen Sie es und versuchen Sie es erneut. Für Dashboard-Pfade: `openclaw config get gateway.auth.token` und dann in die Control-UI-Einstellungen einfügen. |
| `AUTH_TOKEN_MISMATCH` | Gemeinsames Token stimmte nicht mit dem Gateway-Auth-Token überein. | Wenn `canRetryWithDeviceToken=true`, erlauben Sie einen vertrauenswürdigen Wiederholungsversuch. Wiederholungen mit zwischengespeichertem Token verwenden gespeicherte genehmigte Scopes erneut; Aufrufer mit explizitem `deviceToken` / `scopes` behalten angeforderte Scopes. Wenn es weiterhin fehlschlägt, führen Sie die [Checkliste zur Token-Drift-Behebung](/cli/devices#token-drift-recovery-checklist) aus. |
| `AUTH_DEVICE_TOKEN_MISMATCH` | Zwischengespeichertes gerätespezifisches Token ist veraltet oder widerrufen. | Rotieren/genehmigen Sie das Gerätetoken mit [devices CLI](/cli/devices) erneut und verbinden Sie sich dann erneut. |
| `PAIRING_REQUIRED` | Geräteidentität benötigt Genehmigung. Prüfen Sie `error.details.reason` auf `not-paired`, `scope-upgrade`, `role-upgrade` oder `metadata-upgrade` und verwenden Sie `requestId` / `remediationHint`, falls vorhanden. | Genehmigen Sie die ausstehende Anfrage: `openclaw devices list` und dann `openclaw devices approve <requestId>`. Scope-/Rollen-Upgrades verwenden denselben Ablauf, nachdem Sie den angeforderten Zugriff geprüft haben. |
| Detailcode | Bedeutung | Empfohlene Aktion |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_TOKEN_MISSING` | Der Client hat kein erforderliches gemeinsames Token gesendet. | Fügen Sie das Token im Client ein bzw. setzen Sie es und versuchen Sie es erneut. Für Dashboard-Pfade: `openclaw config get gateway.auth.token`, dann in die Einstellungen der Control UI einfügen. |
| `AUTH_TOKEN_MISMATCH` | Das gemeinsame Token stimmte nicht mit dem Gateway-Authentifizierungstoken überein. | Wenn `canRetryWithDeviceToken=true`, lassen Sie einen vertrauenswürdigen Wiederholungsversuch zu. Wiederholungen mit zwischengespeichertem Token verwenden erneut die gespeicherten genehmigten Scopes; Aufrufer mit explizitem `deviceToken` / `scopes` behalten die angeforderte Scope-Menge. Falls es weiterhin fehlschlägt, führen Sie die [Checkliste zur Behebung von Token-Abweichungen](/cli/devices#token-drift-recovery-checklist) aus. |
| `AUTH_DEVICE_TOKEN_MISMATCH` | Das zwischengespeicherte gerätespezifische Token ist veraltet oder widerrufen. | Rotieren/genehmigen Sie das Gerätetoken mit der [devices CLI](/cli/devices) erneut und verbinden Sie sich dann erneut. |
| `PAIRING_REQUIRED` | Die Geräteidentität benötigt eine Freigabe. Prüfen Sie `error.details.reason` auf `not-paired`, `scope-upgrade`, `role-upgrade` oder `metadata-upgrade`, und verwenden Sie `requestId` / `remediationHint`, wenn vorhanden. | Genehmigen Sie die ausstehende Anfrage: `openclaw devices list` und dann `openclaw devices approve <requestId>`. Scope-/Rollen-Upgrades verwenden nach Prüfung des angeforderten Zugriffs denselben Ablauf. |
Prüfung der Migration zu Geräteauthentifizierung v2:
Prüfung der Migration zu Device Auth v2:
```bash
openclaw --version
@ -215,7 +212,7 @@ openclaw doctor
openclaw gateway status
```
Wenn Logs Nonce-/Signaturfehler zeigen, aktualisieren Sie den verbindenden Client und prüfen Sie, dass er:
Wenn die Logs Nonce-/Signaturfehler zeigen, aktualisieren Sie den verbindenden Client und prüfen Sie, dass er:
1. auf `connect.challenge` wartet
2. die an die Challenge gebundene Payload signiert
@ -223,8 +220,8 @@ Wenn Logs Nonce-/Signaturfehler zeigen, aktualisieren Sie den verbindenden Clien
Wenn `openclaw devices rotate` / `revoke` / `remove` unerwartet verweigert wird:
- Sitzungen mit Token gekoppelter Geräte können nur **ihr eigenes**
Gerät verwalten, es sei denn, der Aufrufer hat auch `operator.admin`
- Sitzungen mit gekoppeltem Gerätetoken können nur **ihr eigenes** Gerät verwalten, es sei denn, der
Aufrufer hat zusätzlich `operator.admin`
- `openclaw devices rotate --scope ...` kann nur Operator-Scopes anfordern,
die die Aufrufer-Sitzung bereits besitzt
@ -236,32 +233,32 @@ Verwandt:
- [/gateway/remote](/de/gateway/remote)
- [/cli/devices](/cli/devices)
## Gateway-Dienst läuft nicht
## Gateway-Service läuft nicht
Verwenden Sie dies, wenn der Dienst installiert ist, der Prozess aber nicht aktiv bleibt.
Verwenden Sie dies, wenn der Service installiert ist, der Prozess aber nicht dauerhaft aktiv bleibt.
```bash
openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep # scannt auch Dienste auf Systemebene
openclaw gateway status --deep # scannt auch Services auf Systemebene
```
Achten Sie auf:
Achten Sie auf Folgendes:
- `Runtime: stopped` mit Hinweisen zum Exit.
- Fehlanpassung der Dienstkonfiguration (`Config (cli)` vs `Config (service)`).
- Nichtübereinstimmung der Service-Konfiguration (`Config (cli)` vs `Config (service)`).
- Port-/Listener-Konflikte.
- Zusätzliche launchd-/systemd-/schtasks-Installationen, wenn `--deep` verwendet wird.
- Hinweise zur Bereinigung von `Other gateway-like services detected (best effort)`.
- Zusätzliche launchd-/systemd-/schtasks-Installationen bei Verwendung von `--deep`.
- Hinweise zur Bereinigung bei `Other gateway-like services detected (best effort)`.
Häufige Signaturen:
- `Gateway start blocked: set gateway.mode=local` oder `existing config is missing gateway.mode` → der lokale Gateway-Modus ist nicht aktiviert, oder die Konfigurationsdatei wurde beschädigt und hat `gateway.mode` verloren. Behebung: Setzen Sie `gateway.mode="local"` in Ihrer Konfiguration, oder führen Sie `openclaw onboard --mode local` / `openclaw setup` erneut aus, um die erwartete Konfiguration für den lokalen Modus wiederherzustellen. Wenn Sie OpenClaw über Podman ausführen, ist der Standardpfad für die Konfiguration `~/.openclaw/openclaw.json`.
- `refusing to bind gateway ... without auth` → Nicht-Loopback-Bindung ohne gültigen Gateway-Authentifizierungspfad (Token/Passwort oder, falls konfiguriert, Trusted Proxy).
- `Gateway start blocked: set gateway.mode=local` oder `existing config is missing gateway.mode` → der lokale Gateway-Modus ist nicht aktiviert, oder die Konfigurationsdatei wurde überschrieben und hat `gateway.mode` verloren. Behebung: Setzen Sie `gateway.mode="local"` in Ihrer Konfiguration oder führen Sie `openclaw onboard --mode local` / `openclaw setup` erneut aus, um die erwartete Konfiguration für den lokalen Modus wiederherzustellen. Wenn Sie OpenClaw über Podman ausführen, ist der Standardpfad für die Konfiguration `~/.openclaw/openclaw.json`.
- `refusing to bind gateway ... without auth` → Nicht-Loopback-Bind ohne gültigen Gateway-Authentifizierungspfad (Token/Passwort oder, falls konfiguriert, Trusted Proxy).
- `another gateway instance is already listening` / `EADDRINUSE` → Portkonflikt.
- `Other gateway-like services detected (best effort)` → veraltete oder parallele launchd-/systemd-/schtasks-Units sind vorhanden. Die meisten Setups sollten ein Gateway pro Maschine verwenden; wenn Sie tatsächlich mehr als eines benötigen, isolieren Sie Ports + Konfiguration/Status/Workspace. Siehe [/gateway#multiple-gateways-same-host](/de/gateway#multiple-gateways-same-host).
- `Other gateway-like services detected (best effort)` → veraltete oder parallele launchd-/systemd-/schtasks-Units sind vorhanden. Die meisten Setups sollten ein Gateway pro Maschine behalten; wenn Sie tatsächlich mehr als eines benötigen, isolieren Sie Ports sowie Konfiguration/Status/Workspace. Siehe [/gateway#multiple-gateways-same-host](/de/gateway#multiple-gateways-same-host).
Verwandt:
@ -269,9 +266,9 @@ Verwandt:
- [/gateway/configuration](/de/gateway/configuration)
- [/gateway/doctor](/de/gateway/doctor)
## Gateway hat die zuletzt als gut bekannte Konfiguration wiederhergestellt
## Gateway hat die zuletzt bekannte funktionierende Konfiguration wiederhergestellt
Verwenden Sie dies, wenn das Gateway startet, die Logs aber sagen, dass `openclaw.json` wiederhergestellt wurde.
Verwenden Sie dies, wenn das Gateway startet, die Logs aber melden, dass `openclaw.json` wiederhergestellt wurde.
```bash
openclaw logs --follow
@ -280,20 +277,20 @@ openclaw config validate
openclaw doctor
```
Achten Sie auf:
Achten Sie auf Folgendes:
- `Config auto-restored from last-known-good`
- `gateway: invalid config was restored from last-known-good backup`
- `config reload restored last-known-good config after invalid-config`
- Eine mit Zeitstempel versehene Datei `openclaw.json.clobbered.*` neben der aktiven Konfiguration
- Ein Systemereignis des Haupt-Agent, das mit `Config recovery warning` beginnt
- Ein Systemereignis des Haupt-Agenten, das mit `Config recovery warning` beginnt
Was passiert ist:
Was ist passiert:
- Die abgelehnte Konfiguration bestand die Validierung beim Start oder beim Hot Reload nicht.
- OpenClaw hat die abgelehnte Payload als `.clobbered.*` bewahrt.
- Die aktive Konfiguration wurde aus der zuletzt validierten, zuletzt als gut bekannten Kopie wiederhergestellt.
- Der nächste Turn des Haupt-Agent wird gewarnt, die abgelehnte Konfiguration nicht blind neu zu schreiben.
- Die abgelehnte Konfiguration hat die Validierung beim Start oder beim Hot-Reload nicht bestanden.
- OpenClaw hat die abgelehnte Payload als `.clobbered.*` erhalten.
- Die aktive Konfiguration wurde aus der zuletzt validierten, zuletzt bekannten funktionierenden Kopie wiederhergestellt.
- Der nächste Zug des Haupt-Agenten wird davor gewarnt, die abgelehnte Konfiguration blind neu zu schreiben.
Untersuchen und reparieren:
@ -307,16 +304,16 @@ openclaw doctor
Häufige Signaturen:
- `.clobbered.*` existiert → eine externe direkte Bearbeitung oder ein Startup-Read wurde wiederhergestellt.
- `.rejected.*` existiert → ein von OpenClaw verwalteter Konfigurationsschreibvorgang scheiterte vor dem Commit an Schema- oder Clobber-Prüfungen.
- `Config write rejected:` → der Schreibvorgang versuchte, die erforderliche Struktur zu entfernen, die Datei stark zu verkleinern oder eine ungültige Konfiguration zu speichern.
- `.clobbered.*` ist vorhanden → eine externe direkte Bearbeitung oder ein Start-Lesevorgang wurde wiederhergestellt.
- `.rejected.*` ist vorhanden → ein von OpenClaw selbst durchgeführter Konfigurationsschreibvorgang hat vor dem Commit die Schema- oder Überschreibungsprüfungen nicht bestanden.
- `Config write rejected:` → der Schreibvorgang hätte versucht, eine erforderliche Struktur zu entfernen, die Datei stark zu verkleinern oder eine ungültige Konfiguration zu persistieren.
- `Config last-known-good promotion skipped` → der Kandidat enthielt redigierte Secret-Platzhalter wie `***`.
Optionen zur Behebung:
1. Behalten Sie die wiederhergestellte aktive Konfiguration bei, wenn sie korrekt ist.
2. Kopieren Sie nur die beabsichtigten Schlüssel aus `.clobbered.*` oder `.rejected.*` und wenden Sie sie dann mit `openclaw config set` oder `config.patch` an.
3. Führen Sie `openclaw config validate` vor dem Neustart aus.
3. Führen Sie vor einem Neustart `openclaw config validate` aus.
4. Wenn Sie von Hand bearbeiten, behalten Sie die vollständige JSON5-Konfiguration bei, nicht nur das partielle Objekt, das Sie ändern wollten.
Verwandt:
@ -336,18 +333,18 @@ openclaw gateway probe --json
openclaw gateway probe --ssh user@gateway-host
```
Achten Sie auf:
Achten Sie auf Folgendes:
- `warnings[].code` und `primaryTargetId` in der JSON-Ausgabe.
- Ob sich die Warnung auf SSH-Fallback, mehrere Gateways, fehlende Scopes oder nicht aufgelöste Auth-Refs bezieht.
- Ob sich die Warnung auf SSH-Fallback, mehrere Gateways, fehlende Scopes oder nicht aufgelöste Auth-Referenzen bezieht.
Häufige Signaturen:
- `SSH tunnel failed to start; falling back to direct probes.` → das SSH-Setup ist fehlgeschlagen, aber der Befehl hat trotzdem direkte konfigurierte/Loopback-Ziele versucht.
- `multiple reachable gateways detected` → mehr als ein Ziel hat geantwortet. Das bedeutet normalerweise ein beabsichtigtes Multi-Gateway-Setup oder veraltete/duplizierte Listener.
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → Verbindung funktionierte, aber Detail-RPC ist durch Scopes eingeschränkt; koppeln Sie die Geräteidentität oder verwenden Sie Anmeldedaten mit `operator.read`.
- `Capability: pairing-pending` oder `gateway closed (1008): pairing required` → das Gateway hat geantwortet, aber dieser Client benötigt noch Pairing/Genehmigung vor normalem Operatorzugriff.
- nicht aufgelöster `gateway.auth.*` / `gateway.remote.*`-SecretRef-Warntext → Auth-Material war in diesem Befehlspfad für das fehlgeschlagene Ziel nicht verfügbar.
- `SSH tunnel failed to start; falling back to direct probes.` → Das SSH-Setup ist fehlgeschlagen, aber der Befehl hat weiterhin direkte konfigurierte/Loopback-Ziele versucht.
- `multiple reachable gateways detected` → mehr als ein Ziel hat geantwortet. Normalerweise bedeutet dies ein beabsichtigtes Multi-Gateway-Setup oder veraltete/duplizierte Listener.
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → die Verbindung hat funktioniert, aber Detail-RPC ist durch Scopes eingeschränkt; koppeln Sie die Geräteidentität oder verwenden Sie Anmeldedaten mit `operator.read`.
- `Capability: pairing-pending` oder `gateway closed (1008): pairing required` → das Gateway hat geantwortet, aber dieser Client benötigt weiterhin Pairing/Freigabe vor normalem Operator-Zugriff.
- nicht aufgelöster `gateway.auth.*` / `gateway.remote.*`-SecretRef-Warntext → Authentifizierungsmaterial war in diesem Befehlspfad für das fehlgeschlagene Ziel nicht verfügbar.
Verwandt:
@ -355,9 +352,9 @@ Verwandt:
- [/gateway#multiple-gateways-same-host](/de/gateway#multiple-gateways-same-host)
- [/gateway/remote](/de/gateway/remote)
## Kanal verbunden, aber Nachrichten fließen nicht
## Channel verbunden, aber Nachrichten fließen nicht
Wenn der Kanalstatus „verbunden“ ist, der Nachrichtenfluss aber tot ist, konzentrieren Sie sich auf Richtlinien, Berechtigungen und kanalspezifische Zustellregeln.
Wenn der Channel-Status verbunden ist, aber der Nachrichtenfluss tot ist, konzentrieren Sie sich auf Richtlinien, Berechtigungen und channelspezifische Zustellregeln.
```bash
openclaw channels status --probe
@ -367,17 +364,17 @@ openclaw logs --follow
openclaw config get channels
```
Achten Sie auf:
Achten Sie auf Folgendes:
- DM-Richtlinie (`pairing`, `allowlist`, `open`, `disabled`).
- Gruppen-Allowlist und Erwähnungsanforderungen.
- Fehlende API-Berechtigungen/Scopes des Kanals.
- Fehlende Channel-API-Berechtigungen/Scopes.
Häufige Signaturen:
- `mention required` → Nachricht wird durch die Gruppen-Erwähnungsrichtlinie ignoriert.
- `pairing` / Spuren ausstehender Genehmigung → Absender ist nicht genehmigt.
- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → Problem mit Kanal-Authentifizierung/-Berechtigungen.
- `mention required` → Nachricht wird durch die Gruppenerwähnungsrichtlinie ignoriert.
- `pairing` / Spuren ausstehender Freigaben → Absender ist nicht freigegeben.
- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → Problem mit Channel-Authentifizierung/Berechtigungen.
Verwandt:
@ -386,9 +383,9 @@ Verwandt:
- [/channels/telegram](/de/channels/telegram)
- [/channels/discord](/de/channels/discord)
## Zustellung von Cron und Heartbeat
## Cron- und Heartbeat-Zustellung
Wenn Cron oder Heartbeat nicht ausgeführt wurde oder nicht zugestellt hat, prüfen Sie zuerst den Scheduler-Status und dann das Zustellziel.
Wenn Cron oder Heartbeat nicht ausgeführt wurde oder nicht zugestellt wurde, prüfen Sie zuerst den Scheduler-Status und dann das Zustellziel.
```bash
openclaw cron status
@ -398,21 +395,21 @@ openclaw system heartbeat last
openclaw logs --follow
```
Achten Sie auf:
Achten Sie auf Folgendes:
- Cron aktiviert und nächstes Aufwachen vorhanden.
- Cron ist aktiviert und der nächste Wake ist vorhanden.
- Status der Job-Ausführungshistorie (`ok`, `skipped`, `error`).
- Gründe für das Überspringen des Heartbeat (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`).
- Gründe für übersprungene Heartbeats (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`).
Häufige Signaturen:
- `cron: scheduler disabled; jobs will not run automatically` → Cron deaktiviert.
- `cron: scheduler disabled; jobs will not run automatically` → Cron ist deaktiviert.
- `cron: timer tick failed` → Scheduler-Tick fehlgeschlagen; prüfen Sie Datei-/Log-/Laufzeitfehler.
- `heartbeat skipped` mit `reason=quiet-hours` → außerhalb des Fensters aktiver Zeiten.
- `heartbeat skipped` mit `reason=empty-heartbeat-file` → `HEARTBEAT.md` existiert, enthält aber nur Leerzeilen / Markdown-Überschriften, daher überspringt OpenClaw den Modellaufruf.
- `heartbeat skipped` mit `reason=quiet-hours` → außerhalb des aktiven Stundenfensters.
- `heartbeat skipped` mit `reason=empty-heartbeat-file` → `HEARTBEAT.md` ist vorhanden, enthält aber nur leere Zeilen / Markdown-Überschriften, daher überspringt OpenClaw den Modellaufruf.
- `heartbeat skipped` mit `reason=no-tasks-due` → `HEARTBEAT.md` enthält einen `tasks:`-Block, aber bei diesem Tick ist keine der Aufgaben fällig.
- `heartbeat: unknown accountId` → ungültige Konto-ID für das Heartbeat-Zustellziel.
- `heartbeat skipped` mit `reason=dm-blocked` → Heartbeat-Ziel wurde zu einem Ziel im DM-Stil aufgelöst, während `agents.defaults.heartbeat.directPolicy` (oder die Überschreibung pro Agent) auf `block` gesetzt ist.
- `heartbeat skipped` mit `reason=dm-blocked` → das Heartbeat-Ziel wurde zu einem Ziel im DM-Stil aufgelöst, während `agents.defaults.heartbeat.directPolicy` (oder die agentenspezifische Überschreibung) auf `block` gesetzt ist.
Verwandt:
@ -420,9 +417,9 @@ Verwandt:
- [/automation/cron-jobs](/de/automation/cron-jobs)
- [/gateway/heartbeat](/de/gateway/heartbeat)
## Tool auf gekoppeltem Node schlägt fehl
## Gepairtes Node-Tool schlägt fehl
Wenn ein Node gekoppelt ist, aber Tools fehlschlagen, isolieren Sie Vordergrund-, Berechtigungs- und Genehmigungsstatus.
Wenn ein Node gepairt ist, aber Tools fehlschlagen, isolieren Sie Vordergrund-, Berechtigungs- und Freigabestatus.
```bash
openclaw nodes status
@ -432,18 +429,18 @@ openclaw logs --follow
openclaw status
```
Achten Sie auf:
Achten Sie auf Folgendes:
- Node online mit den erwarteten Fähigkeiten.
- Vom Betriebssystem gewährte Berechtigungen für Kamera/Mikrofon/Standort/Bildschirm.
- Exec-Genehmigungen und Allowlist-Status.
- Node online mit den erwarteten Capabilities.
- OS-Berechtigungen für Kamera/Mikrofon/Standort/Bildschirm.
- Exec-Freigaben und Allowlist-Status.
Häufige Signaturen:
- `NODE_BACKGROUND_UNAVAILABLE` → Node-App muss im Vordergrund sein.
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → fehlende Betriebssystemberechtigung.
- `SYSTEM_RUN_DENIED: approval required` → Exec-Genehmigung ausstehend.
- `SYSTEM_RUN_DENIED: allowlist miss` → Befehl durch Allowlist blockiert.
- `NODE_BACKGROUND_UNAVAILABLE` → die Node-App muss im Vordergrund sein.
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → fehlende OS-Berechtigung.
- `SYSTEM_RUN_DENIED: approval required` → Exec-Freigabe ausstehend.
- `SYSTEM_RUN_DENIED: allowlist miss` → Befehl wurde durch die Allowlist blockiert.
Verwandt:
@ -463,43 +460,44 @@ openclaw logs --follow
openclaw doctor
```
Achten Sie auf:
Achten Sie auf Folgendes:
- Ob `plugins.allow` gesetzt ist und `browser` enthält.
- Gültigen Pfad zur Browser-Executable.
- Gültiger Pfad zur Browser-Executable.
- Erreichbarkeit des CDP-Profils.
- Verfügbarkeit von lokalem Chrome für Profile `existing-session` / `user`.
- Lokale Chrome-Verfügbarkeit für `existing-session`- / `user`-Profile.
Häufige Signaturen:
- `unknown command "browser"` oder `unknown command 'browser'` → das gebündelte Browser-Plugin ist durch `plugins.allow` ausgeschlossen.
- Browser-Tool fehlt / ist nicht verfügbar, obwohl `browser.enabled=true` → `plugins.allow` schließt `browser` aus, daher wurde das Plugin nie geladen.
- `Failed to start Chrome CDP on port` → Browser-Prozess konnte nicht gestartet werden.
- `browser.executablePath not found` → konfigurierter Pfad ist ungültig.
- `browser.executablePath not found` → der konfigurierte Pfad ist ungültig.
- `browser.cdpUrl must be http(s) or ws(s)` → die konfigurierte CDP-URL verwendet ein nicht unterstütztes Schema wie `file:` oder `ftp:`.
- `browser.cdpUrl has invalid port` → die konfigurierte CDP-URL hat einen ungültigen oder außerhalb des Bereichs liegenden Port.
- `Could not find DevToolsActivePort for chrome` → Chrome MCP `existing-session` konnte sich noch nicht an das ausgewählte Browser-Datenverzeichnis anhängen. Öffnen Sie die Browser-Inspect-Seite, aktivieren Sie Remote-Debugging, lassen Sie den Browser geöffnet, genehmigen Sie die erste Attach-Aufforderung und versuchen Sie es dann erneut. Wenn kein angemeldeter Zustand erforderlich ist, bevorzugen Sie das verwaltete Profil `openclaw`.
- `No Chrome tabs found for profile="user"` → das Chrome-MCP-Attach-Profil hat keine geöffneten lokalen Chrome-Tabs.
- `Remote CDP for profile "<name>" is not reachable` → der konfigurierte Remote-CDP-Endpunkt ist vom Gateway-Host aus nicht erreichbar.
- `Browser attachOnly is enabled ... not reachable` oder `Browser attachOnly is enabled and CDP websocket ... is not reachable` → das Attach-only-Profil hat kein erreichbares Ziel, oder der HTTP-Endpunkt hat geantwortet, aber das CDP-WebSocket konnte trotzdem nicht geöffnet werden.
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → der aktuellen Gateway-Installation fehlt das vollständige Playwright-Paket; ARIA-Snapshots und einfache Seitenscreenshots können weiterhin funktionieren, aber Navigation, AI-Snapshots, Element-Screenshots per CSS-Selektor und PDF-Export bleiben nicht verfügbar.
- `fullPage is not supported for element screenshots` → Screenshot-Anfrage hat `--full-page` mit `--ref` oder `--element` kombiniert.
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Screenshot-Aufrufe für Chrome MCP / `existing-session` müssen Seitenerfassung oder ein Snapshot-`--ref` verwenden, nicht CSS-`--element`.
- `Browser attachOnly is enabled ... not reachable` oder `Browser attachOnly is enabled and CDP websocket ... is not reachable` → das Attach-only-Profil hat kein erreichbares Ziel, oder der HTTP-Endpunkt hat geantwortet, aber das CDP-WebSocket konnte dennoch nicht geöffnet werden.
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → in der aktuellen Gateway-Installation fehlt das vollständige Playwright-Paket; ARIA-Snapshots und einfache Seitenscreenshots können weiterhin funktionieren, aber Navigation, KI-Snapshots, Element-Screenshots per CSS-Selektor und PDF-Export bleiben nicht verfügbar.
- `fullPage is not supported for element screenshots` → die Screenshot-Anfrage hat `--full-page` mit `--ref` oder `--element` kombiniert.
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Screenshot-Aufrufe für Chrome MCP / `existing-session` müssen Seitenerfassung oder eine Snapshot-`--ref` verwenden, nicht CSS-`--element`.
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → Upload-Hooks für Chrome MCP benötigen Snapshot-Refs, keine CSS-Selektoren.
- `existing-session file uploads currently support one file at a time.` → senden Sie pro Aufruf einen Upload auf Chrome-MCP-Profilen.
- `existing-session dialog handling does not support timeoutMs.` → Dialog-Hooks auf Chrome-MCP-Profilen unterstützen keine Timeout-Überschreibungen.
- `existing-session file uploads currently support one file at a time.` → senden Sie bei Chrome-MCP-Profilen einen Upload pro Aufruf.
- `existing-session dialog handling does not support timeoutMs.` → Dialog-Hooks bei Chrome-MCP-Profilen unterstützen keine Timeout-Überschreibungen.
- `response body is not supported for existing-session profiles yet.` → `responsebody` erfordert weiterhin einen verwalteten Browser oder ein Raw-CDP-Profil.
- veraltete Überschreibungen für Viewport / Dark Mode / Locale / Offline auf Attach-only- oder Remote-CDP-Profilen → führen Sie `openclaw browser stop --browser-profile <name>` aus, um die aktive Steuerungssitzung zu schließen und den Playwright-/CDP-Emulationsstatus freizugeben, ohne das gesamte Gateway neu zu starten.
- veraltete Überschreibungen für Viewport / Dark Mode / Locale / Offline auf Attach-only- oder Remote-CDP-Profilen → führen Sie `openclaw browser stop --browser-profile <name>` aus, um die aktive Kontrollsitzung zu schließen und den Playwright-/CDP-Emulationsstatus freizugeben, ohne das gesamte Gateway neu zu starten.
Verwandt:
- [/tools/browser-linux-troubleshooting](/de/tools/browser-linux-troubleshooting)
- [/tools/browser](/de/tools/browser)
## Wenn nach einem Upgrade plötzlich etwas kaputtging
## Wenn Sie ein Upgrade durchgeführt haben und plötzlich etwas nicht mehr funktioniert
Die meisten Probleme nach Upgrades sind Konfigurationsdrift oder jetzt erzwungene strengere Standardwerte.
Die meisten Probleme nach einem Upgrade sind Konfigurationsabweichungen oder striktere Standards, die jetzt erzwungen werden.
### 1) Verhalten von Auth und URL-Überschreibungen hat sich geändert
### 1) Verhalten bei Authentifizierung und URL-Überschreibung hat sich geändert
```bash
openclaw gateway status
@ -508,17 +506,17 @@ openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode
```
Was Sie prüfen sollten:
Was zu prüfen ist:
- Wenn `gateway.mode=remote`, können CLI-Aufrufe auf remote zielen, während Ihr lokaler Dienst in Ordnung ist.
- Explizite `--url`-Aufrufe greifen nicht auf gespeicherte Anmeldedaten zurück.
- Wenn `gateway.mode=remote`, können CLI-Aufrufe das Remote-Ziel ansprechen, während Ihr lokaler Service in Ordnung ist.
- Explizite Aufrufe mit `--url` fallen nicht auf gespeicherte Anmeldedaten zurück.
Häufige Signaturen:
- `gateway connect failed:` → falsches URL-Ziel.
- `unauthorized` → Endpunkt erreichbar, aber falsche Authentifizierung.
### 2) Bindungs- und Auth-Guardrails sind strenger
### 2) Bind- und Authentifizierungs-Schutzmechanismen sind strenger
```bash
openclaw config get gateway.bind
@ -528,15 +526,15 @@ openclaw gateway status
openclaw logs --follow
```
Was Sie prüfen sollten:
Was zu prüfen ist:
- Nicht-Loopback-Bindungen (`lan`, `tailnet`, `custom`) benötigen einen gültigen Gateway-Authentifizierungspfad: gemeinsame Token-/Passwort-Authentifizierung oder eine korrekt konfigurierte Nicht-Loopback-`trusted-proxy`-Bereitstellung.
- Nicht-Loopback-Binds (`lan`, `tailnet`, `custom`) benötigen einen gültigen Gateway-Authentifizierungspfad: gemeinsame Token-/Passwort-Authentifizierung oder eine korrekt konfigurierte `trusted-proxy`-Bereitstellung ohne Loopback.
- Alte Schlüssel wie `gateway.token` ersetzen `gateway.auth.token` nicht.
Häufige Signaturen:
- `refusing to bind gateway ... without auth` → Nicht-Loopback-Bindung ohne gültigen Gateway-Authentifizierungspfad.
- `Connectivity probe: failed`, während die Laufzeit läuft → Gateway ist aktiv, aber mit aktueller Authentifizierung/URL nicht erreichbar.
- `refusing to bind gateway ... without auth` → Nicht-Loopback-Bind ohne gültigen Gateway-Authentifizierungspfad.
- `Connectivity probe: failed` während die Runtime läuft → Gateway aktiv, aber mit aktueller Authentifizierung/URL nicht erreichbar.
### 3) Pairing- und Geräteidentitätsstatus haben sich geändert
@ -547,17 +545,17 @@ openclaw logs --follow
openclaw doctor
```
Was Sie prüfen sollten:
Was zu prüfen ist:
- Ausstehende Gerätegenehmigungen für Dashboard/Nodes.
- Ausstehende DM-Pairing-Genehmigungen nach Änderungen an Richtlinie oder Identität.
- Ausstehende Gerätefreigaben für Dashboard/Nodes.
- Ausstehende DM-Pairing-Freigaben nach Richtlinien- oder Identitätsänderungen.
Häufige Signaturen:
- `device identity required` → Geräteauthentifizierung nicht erfüllt.
- `pairing required` → Absender/Gerät muss genehmigt werden.
- `pairing required` → Absender/Gerät muss freigegeben werden.
Wenn Dienstkonfiguration und Laufzeit nach den Prüfungen weiterhin nicht übereinstimmen, installieren Sie die Dienstmetadaten aus demselben Profil-/Statusverzeichnis neu:
Wenn Service-Konfiguration und Runtime nach den Prüfungen weiterhin nicht übereinstimmen, installieren Sie die Service-Metadaten aus demselben Profil-/Statusverzeichnis erneut:
```bash
openclaw gateway install --force

1781
docs/de/help/faq.md
View File

File diff suppressed because it is too large Load Diff

875
docs/de/help/testing.md
View File

File diff suppressed because it is too large Load Diff

1300
docs/de/plugins/architecture.md
View File

File diff suppressed because it is too large Load Diff

378
docs/de/plugins/sdk-provider-plugins.md
View File

@ -1,35 +1,40 @@
---
read_when:
- Sie erstellen ein neues Modellanbieter-Plugin
- Sie erstellen ein neues Modell-Provider-Plugin
- Sie möchten einen OpenAI-kompatiblen Proxy oder ein benutzerdefiniertes LLM zu OpenClaw hinzufügen
- Sie müssen Auth, Kataloge und Laufzeit-Hooks von Anbietern verstehen
- Sie müssen Provider-Authentifizierung, Kataloge und Laufzeit-Hooks verstehen
sidebarTitle: Provider Plugins
summary: Schritt-für-Schritt-Anleitung zum Erstellen eines Modellanbieter-Plugins für OpenClaw
title: Anbieter-Plugins erstellen
summary: Schritt-für-Schritt-Anleitung zum Erstellen eines Modell-Provider-Plugins für OpenClaw
title: Provider-Plugins erstellen
x-i18n:
generated_at: "2026-04-21T06:29:58Z"
generated_at: "2026-04-21T13:36:28Z"
model: gpt-5.4
provider: openai
source_hash: 459761118c7394c1643c170edfec97c87e1c6323b436183b53ad7a2fed783b04
source_hash: 08494658def4a003a1e5752f68d9232bfbbbf76348cf6f319ea1a6855c2ae439
source_path: plugins/sdk-provider-plugins.md
workflow: 15
---
# Anbieter-Plugins erstellen
# Provider-Plugins erstellen
Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das OpenClaw einen Modellanbieter (LLM) hinzufügt. Am Ende haben Sie einen Anbieter mit Modellkatalog, API-Schlüssel-Auth und dynamischer Modellauflösung.
Diese Anleitung führt Sie durch das Erstellen eines Provider-Plugins, das OpenClaw einen Modell-Provider
(LLM) hinzufügt. Am Ende haben Sie einen Provider mit einem Modellkatalog,
API-Key-Authentifizierung und dynamischer Modellauflösung.
<Info>
Wenn Sie noch nie ein OpenClaw-Plugin erstellt haben, lesen Sie zuerst
Wenn Sie zuvor noch kein OpenClaw-Plugin erstellt haben, lesen Sie zuerst
[Erste Schritte](/de/plugins/building-plugins) für die grundlegende Paketstruktur
und die Manifest-Einrichtung.
</Info>
<Tip>
Anbieter-Plugins fügen Modelle zur normalen Inferenzschleife von OpenClaw hinzu. Wenn das Modell über einen nativen Agent-Daemon laufen muss, der Threads, Compaction oder Tool-Ereignisse besitzt, koppeln Sie den Anbieter mit einem [agent harness](/de/plugins/sdk-agent-harness), statt Daemon-Protokolldetails in den Core zu legen.
Provider-Plugins fügen Modelle zum normalen Inferenz-Loop von OpenClaw hinzu. Wenn das Modell
über einen nativen Agent-Daemon laufen muss, der Threads, Compaction oder Tool-
Ereignisse verwaltet, kombinieren Sie den Provider stattdessen mit einem [Agent-Harness](/de/plugins/sdk-agent-harness),
anstatt Details des Daemon-Protokolls im Core unterzubringen.
</Tip>
## Schritt-für-Schritt
## Schritt-für-Schritt-Anleitung
<Steps>
<a id="step-1-package-and-manifest"></a>
@ -59,7 +64,7 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
{
"id": "acme-ai",
"name": "Acme AI",
"description": "Acme-AI-Modellanbieter",
"description": "Acme AI model provider",
"providers": ["acme-ai"],
"modelSupport": {
"modelPrefixes": ["acme-"]
@ -75,12 +80,12 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
"provider": "acme-ai",
"method": "api-key",
"choiceId": "acme-ai-api-key",
"choiceLabel": "Acme-AI-API-Schlüssel",
"choiceLabel": "Acme AI API key",
"groupId": "acme-ai",
"groupLabel": "Acme AI",
"cliFlag": "--acme-ai-api-key",
"cliOption": "--acme-ai-api-key <key>",
"cliDescription": "Acme-AI-API-Schlüssel"
"cliDescription": "Acme AI API key"
}
],
"configSchema": {
@ -91,12 +96,18 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
```
</CodeGroup>
Das Manifest deklariert `providerAuthEnvVars`, damit OpenClaw Zugangsdaten erkennen kann, ohne Ihre Plugin-Laufzeit zu laden. Fügen Sie `providerAuthAliases` hinzu, wenn eine Anbietervariante die Auth einer anderen Anbieter-ID wiederverwenden soll. `modelSupport` ist optional und erlaubt OpenClaw, Ihr Anbieter-Plugin automatisch aus Kurzform-Modell-IDs wie `acme-large` zu laden, bevor Laufzeit-Hooks existieren. Wenn Sie den Anbieter auf ClawHub veröffentlichen, sind diese Felder `openclaw.compat` und `openclaw.build` in `package.json` erforderlich.
Das Manifest deklariert `providerAuthEnvVars`, damit OpenClaw
Anmeldedaten erkennen kann, ohne die Laufzeit Ihres Plugins zu laden. Fügen Sie `providerAuthAliases`
hinzu, wenn eine Provider-Variante die Authentifizierung einer anderen Provider-ID wiederverwenden soll. `modelSupport`
ist optional und erlaubt OpenClaw, Ihr Provider-Plugin automatisch aus Kurzform-
Modell-IDs wie `acme-large` zu laden, bevor Laufzeit-Hooks existieren. Wenn Sie den
Provider auf ClawHub veröffentlichen, sind diese Felder `openclaw.compat` und `openclaw.build`
in `package.json` erforderlich.
</Step>
<Step title="Den Anbieter registrieren">
Ein minimaler Anbieter benötigt `id`, `label`, `auth` und `catalog`:
<Step title="Den Provider registrieren">
Ein minimaler Provider benötigt `id`, `label`, `auth` und `catalog`:
```typescript index.ts
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
@ -117,12 +128,12 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
createProviderApiKeyAuthMethod({
providerId: "acme-ai",
methodId: "api-key",
label: "Acme-AI-API-Schlüssel",
hint: "API-Schlüssel aus Ihrem Acme-AI-Dashboard",
label: "Acme AI API key",
hint: "API key from your Acme AI dashboard",
optionKey: "acmeAiApiKey",
flagName: "--acme-ai-api-key",
envVar: "ACME_AI_API_KEY",
promptMessage: "Geben Sie Ihren Acme-AI-API-Schlüssel ein",
promptMessage: "Enter your Acme AI API key",
defaultModel: "acme-ai/acme-large",
}),
],
@ -167,11 +178,12 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
});
```
Das ist ein funktionierender Anbieter. Benutzer können jetzt
Das ist ein funktionierender Provider. Nutzer können jetzt
`openclaw onboard --acme-ai-api-key <key>` ausführen und
`acme-ai/acme-large` als Modell auswählen.
`acme-ai/acme-large` als ihr Modell auswählen.
Wenn der Upstream-Anbieter andere Steuer-Token als OpenClaw verwendet, fügen Sie eine kleine bidirektionale Texttransformation hinzu, statt den Stream-Pfad zu ersetzen:
Wenn der Upstream-Provider andere Steuer-Tokens als OpenClaw verwendet, fügen Sie eine
kleine bidirektionale Texttransformation hinzu, anstatt den Stream-Pfad zu ersetzen:
```typescript
api.registerTextTransforms({
@ -188,9 +200,13 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
});
```
`input` schreibt den finalen System-Prompt und den Inhalt von Textnachrichten vor dem Transport um. `output` schreibt Assistant-Text-Deltas und finalen Text um, bevor OpenClaw seine eigenen Kontrollmarker oder die Kanalzustellung parst.
`input` schreibt den finalen System-Prompt und den Inhalt von Textnachrichten vor
dem Transport um. `output` schreibt Assistant-Text-Deltas und finalen Text um, bevor
OpenClaw seine eigenen Steuer-Markierungen oder die Kanalzustellung parst.
Für gebündelte Anbieter, die nur einen Textanbieter mit API-Schlüssel-Auth plus eine einzelne kataloggestützte Laufzeit registrieren, bevorzugen Sie den schmaleren Helper `defineSingleProviderPluginEntry(...)`:
Für gebündelte Provider, die nur einen Text-Provider mit API-Key-
Authentifizierung plus eine einzelne kataloggestützte Laufzeit registrieren, bevorzugen Sie den engeren
Helper `defineSingleProviderPluginEntry(...)`:
```typescript
import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry";
@ -205,12 +221,12 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
auth: [
{
methodId: "api-key",
label: "Acme-AI-API-Schlüssel",
hint: "API-Schlüssel aus Ihrem Acme-AI-Dashboard",
label: "Acme AI API key",
hint: "API key from your Acme AI dashboard",
optionKey: "acmeAiApiKey",
flagName: "--acme-ai-api-key",
envVar: "ACME_AI_API_KEY",
promptMessage: "Geben Sie Ihren Acme-AI-API-Schlüssel ein",
promptMessage: "Enter your Acme AI API key",
defaultModel: "acme-ai/acme-large",
},
],
@ -225,21 +241,30 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
});
```
Wenn Ihr Auth-Ablauf zusätzlich `models.providers.*`, Aliasse und das Standard-Agentenmodell beim Onboarding patchen muss, verwenden Sie die Preset-Helper aus `openclaw/plugin-sdk/provider-onboard`. Die schmalsten Helper sind
Wenn Ihr Auth-Flow während des Onboardings außerdem `models.providers.*`, Aliase und
das Standardmodell des Agenten patchen muss, verwenden Sie die Preset-Helper aus
`openclaw/plugin-sdk/provider-onboard`. Die engsten Helper sind
`createDefaultModelPresetAppliers(...)`,
`createDefaultModelsPresetAppliers(...)` und
`createModelCatalogPresetAppliers(...)`.
Wenn ein nativer Endpunkt des Anbieters gestreamte Usage-Blöcke auf dem normalen Transport `openai-completions` unterstützt, bevorzugen Sie die gemeinsamen Katalog-Helper in `openclaw/plugin-sdk/provider-catalog-shared`, statt Anbieter-ID-Prüfungen fest zu codieren. `supportsNativeStreamingUsageCompat(...)` und `applyProviderNativeStreamingUsageCompat(...)` erkennen die Unterstützung aus der Endpunkt-Fähigkeits-Map, sodass native Endpunkte im Stil von Moonshot/DashScope weiterhin opt-in sind, selbst wenn ein Plugin eine benutzerdefinierte Anbieter-ID verwendet.
Wenn der native Endpunkt eines Providers gestreamte Nutzungsblöcke auf dem
normalen Transport `openai-completions` unterstützt, bevorzugen Sie die gemeinsamen Katalog-Helper in
`openclaw/plugin-sdk/provider-catalog-shared`, anstatt Prüfungen auf Provider-IDs fest zu codieren.
`supportsNativeStreamingUsageCompat(...)` und
`applyProviderNativeStreamingUsageCompat(...)` erkennen die Unterstützung anhand der Capability-Map des
Endpunkts, sodass native Endpunkte im Stil von Moonshot/DashScope weiterhin
optieren können, selbst wenn ein Plugin eine benutzerdefinierte Provider-ID verwendet.
</Step>
<Step title="Dynamische Modellauflösung hinzufügen">
Wenn Ihr Anbieter beliebige Modell-IDs akzeptiert (wie ein Proxy oder Router), fügen Sie `resolveDynamicModel` hinzu:
Wenn Ihr Provider beliebige Modell-IDs akzeptiert (wie ein Proxy oder Router),
fügen Sie `resolveDynamicModel` hinzu:
```typescript
api.registerProvider({
// ... id, label, auth, catalog von oben
// ... id, label, auth, catalog from above
resolveDynamicModel: (ctx) => ({
id: ctx.modelId,
@ -256,14 +281,17 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
});
```
Wenn die Auflösung einen Netzwerkaufruf erfordert, verwenden Sie `prepareDynamicModel` für asynchrones Warm-up — `resolveDynamicModel` wird erneut ausgeführt, nachdem es abgeschlossen ist.
Wenn die Auflösung einen Netzwerkaufruf erfordert, verwenden Sie `prepareDynamicModel` für asynchrones
Aufwärmen — `resolveDynamicModel` läuft danach erneut.
</Step>
<Step title="Laufzeit-Hooks hinzufügen (nach Bedarf)">
Die meisten Anbieter benötigen nur `catalog` + `resolveDynamicModel`. Fügen Sie Hooks schrittweise hinzu, wenn Ihr Anbieter sie benötigt.
Die meisten Provider benötigen nur `catalog` + `resolveDynamicModel`. Fügen Sie Hooks
schrittweise hinzu, wenn Ihr Provider sie benötigt.
Gemeinsame Helper-Builder decken jetzt die häufigsten Familien für Replay-/Tool-Kompatibilität ab, sodass Plugins normalerweise nicht jeden Hook einzeln verdrahten müssen:
Gemeinsame Helper-Builder decken jetzt die häufigsten Replay-/Tool-Kompatibilitäts-
Familien ab, sodass Plugins in der Regel nicht jeden Hook einzeln von Hand verdrahten müssen:
```typescript
import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared";
@ -283,17 +311,17 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
});
```
Heute verfügbare Replay-Familien:
Verfügbare Replay-Familien heute:
| Family | Was damit verdrahtet wird |
| Familie | Was sie verdrahtet |
| --- | --- |
| `openai-compatible` | Gemeinsame Replay-Richtlinie im OpenAI-Stil für OpenAI-kompatible Transporte, einschließlich Tool-Call-ID-Bereinigung, Korrekturen für Assistant-first-Reihenfolge und generischer Gemini-Turn-Validierung, wo der Transport sie benötigt |
| `anthropic-by-model` | Claude-bewusste Replay-Richtlinie, ausgewählt nach `modelId`, sodass Anthropic-Message-Transporte nur dann Claude-spezifische Bereinigung von Thinking-Blöcken erhalten, wenn das aufgelöste Modell tatsächlich eine Claude-ID ist |
| `google-gemini` | Native Gemini-Replay-Richtlinie plus Bereinigung von Bootstrap-Replay und getaggter Ausgabemodus für Reasoning |
| `passthrough-gemini` | Bereinigung von Gemini-Thought-Signaturen für Gemini-Modelle, die über OpenAI-kompatible Proxy-Transporte laufen; aktiviert weder native Gemini-Replay-Validierung noch Bootstrap-Umschreibungen |
| `hybrid-anthropic-openai` | Hybride Richtlinie für Anbieter, die Anthropic-Message- und OpenAI-kompatible Modelloberflächen in einem Plugin mischen; optionales Entfernen Claude-spezifischer Thinking-Blöcke bleibt auf die Anthropic-Seite beschränkt |
| `openai-compatible` | Gemeinsame Replay-Richtlinie im OpenAI-Stil für OpenAI-kompatible Transporte, einschließlich Bereinigung von Tool-Call-IDs, Korrekturen für Assistant-first-Reihenfolge und generischer Gemini-Turn-Validierung, wo der Transport sie benötigt |
| `anthropic-by-model` | Claude-bewusste Replay-Richtlinie, ausgewählt nach `modelId`, sodass Transports auf Basis von Anthropic-Messages nur dann Claude-spezifische Bereinigung von Thinking-Blöcken erhalten, wenn das aufgelöste Modell tatsächlich eine Claude-ID ist |
| `google-gemini` | Native Gemini-Replay-Richtlinie plus Bereinigung des Bootstrap-Replays und markierter Modus für Reasoning-Ausgabe |
| `passthrough-gemini` | Bereinigung der Gemini-Thought-Signature für Gemini-Modelle, die über OpenAI-kompatible Proxy-Transporte laufen; aktiviert weder native Gemini-Replay-Validierung noch Bootstrap-Umschreibungen |
| `hybrid-anthropic-openai` | Hybride Richtlinie für Provider, die in einem Plugin Anthropic-Message- und OpenAI-kompatible Modelloberflächen mischen; optionales Entfernen von Claude-spezifischen Thinking-Blöcken bleibt auf die Anthropic-Seite beschränkt |
Echte gebündelte Beispiele:
Reale gebündelte Beispiele:
- `google` und `google-gemini-cli`: `google-gemini`
- `openrouter`, `kilocode`, `opencode` und `opencode-go`: `passthrough-gemini`
@ -303,17 +331,17 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
Heute verfügbare Stream-Familien:
| Family | Was damit verdrahtet wird |
| Familie | Was sie verdrahtet |
| --- | --- |
| `google-thinking` | Normalisierung der Gemini-Thinking-Payload auf dem gemeinsamen Stream-Pfad |
| `kilocode-thinking` | Kilo-Reasoning-Wrapper auf dem gemeinsamen Proxy-Stream-Pfad, wobei `kilo/auto` und nicht unterstützte Proxy-Reasoning-IDs injiziertes Thinking überspringen |
| `moonshot-thinking` | Moonshot-Mapping für binäre native Thinking-Payload aus Konfiguration + `/think`-Level |
| `minimax-fast-mode` | Umschreiben von MiniMax-Modellen im Fast-Mode auf dem gemeinsamen Stream-Pfad |
| `openai-responses-defaults` | Gemeinsame native OpenAI-/Codex-Responses-Wrapper: Attributions-Header, `/fast`/`serviceTier`, Textausführlichkeit, native Codex-Websuche, OpenAI-Reasoning-kompatibles Payload-Shaping und Responses-Kontextverwaltung |
| `openrouter-thinking` | OpenRouter-Reasoning-Wrapper für Proxy-Routen, wobei Sprünge für nicht unterstützte Modelle/`auto` zentral behandelt werden |
| `tool-stream-default-on` | Standardmäßig aktivierter `tool_stream`-Wrapper für Anbieter wie Z.AI, die Tool-Streaming wünschen, sofern es nicht explizit deaktiviert wird |
| `google-thinking` | Gemini-Thinking-Payload-Normalisierung auf dem gemeinsamen Stream-Pfad |
| `kilocode-thinking` | Kilo-Reasoning-Wrapper auf dem gemeinsamen Proxy-Stream-Pfad, wobei `kilo/auto` und nicht unterstützte Proxy-Reasoning-IDs eingefügtes Thinking überspringen |
| `moonshot-thinking` | Moonshot-Binär-Mapping für native Thinking-Payloads aus Konfiguration + `/think`-Level |
| `minimax-fast-mode` | MiniMax-Fast-Mode-Modellumschreibung auf dem gemeinsamen Stream-Pfad |
| `openai-responses-defaults` | Gemeinsame native OpenAI/Codex-Responses-Wrapper: Attributions-Header, `/fast`/`serviceTier`, Text-Verbosity, native Codex-Websuche, Reasoning-kompatible Payload-Formung und Responses-Kontextverwaltung |
| `openrouter-thinking` | OpenRouter-Reasoning-Wrapper für Proxy-Routen, wobei Überspringen bei nicht unterstützten Modellen/`auto` zentral behandelt wird |
| `tool-stream-default-on` | Standardmäßig aktivierter `tool_stream`-Wrapper für Provider wie Z.AI, die Tool-Streaming wünschen, sofern es nicht ausdrücklich deaktiviert wird |
Echte gebündelte Beispiele:
Reale gebündelte Beispiele:
- `google` und `google-gemini-cli`: `google-thinking`
- `kilocode`: `kilocode-thinking`
@ -323,7 +351,9 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
- `openrouter`: `openrouter-thinking`
- `zai`: `tool-stream-default-on`
`openclaw/plugin-sdk/provider-model-shared` exportiert außerdem das Enum für Replay-Familien sowie die gemeinsamen Helper, aus denen diese Familien aufgebaut werden. Häufige öffentliche Exporte umfassen:
`openclaw/plugin-sdk/provider-model-shared` exportiert auch das Replay-Familien-
Enum sowie die gemeinsamen Helper, aus denen diese Familien aufgebaut sind. Häufige öffentliche
Exporte sind unter anderem:
- `ProviderReplayFamily`
- `buildProviderReplayFamilyHooks(...)`
@ -337,49 +367,65 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
`normalizeProviderId(...)`, `normalizeGooglePreviewModelId(...)` und
`normalizeNativeXaiModelId(...)`
`openclaw/plugin-sdk/provider-stream` stellt sowohl den Familien-Builder als
auch die öffentlichen Wrapper-Helper bereit, die diese Familien wiederverwenden. Häufige öffentliche Exporte umfassen:
`openclaw/plugin-sdk/provider-stream` stellt sowohl den Familien-Builder als auch
die öffentlichen Wrapper-Helper bereit, die diese Familien wiederverwenden. Häufige öffentliche Exporte
sind unter anderem:
- `ProviderStreamFamily`
- `buildProviderStreamFamilyHooks(...)`
- `composeProviderStreamWrappers(...)`
- gemeinsame OpenAI-/Codex-Wrapper wie
- gemeinsame OpenAI/Codex-Wrapper wie
`createOpenAIAttributionHeadersWrapper(...)`,
`createOpenAIFastModeWrapper(...)`,
`createOpenAIServiceTierWrapper(...)`,
`createOpenAIResponsesContextManagementWrapper(...)` und
`createCodexNativeWebSearchWrapper(...)`
- gemeinsame Proxy-/Anbieter-Wrapper wie `createOpenRouterWrapper(...)`,
- gemeinsame Proxy-/Provider-Wrapper wie `createOpenRouterWrapper(...)`,
`createToolStreamWrapper(...)` und `createMinimaxFastModeWrapper(...)`
Einige Stream-Helper bleiben absichtlich anbieterlokal. Aktuelles gebündeltes Beispiel: `@openclaw/anthropic-provider` exportiert
Einige Stream-Helper bleiben absichtlich Provider-lokal. Aktuelles gebündeltes
Beispiel: `@openclaw/anthropic-provider` exportiert
`wrapAnthropicProviderStream`, `resolveAnthropicBetas`,
`resolveAnthropicFastMode`, `resolveAnthropicServiceTier` und die
Anthropic-Wrapper-Builder auf niedriger Ebene aus seiner öffentlichen Nahtstelle `api.ts` / `contract-api.ts`. Diese Helper bleiben Anthropic-spezifisch, weil sie auch die Behandlung von Claude-OAuth-Betas und `context1m`-Gating kodieren.
Wrapper-Builder auf niedrigerer Ebene für Anthropic aus seiner öffentlichen Nahtstelle `api.ts` /
`contract-api.ts`. Diese Helper bleiben Anthropic-spezifisch, weil
sie außerdem Claude-OAuth-Beta-Behandlung und `context1m`-Gating kodieren.
Andere gebündelte Anbieter behalten transportspezifische Wrapper ebenfalls lokal, wenn das Verhalten sich nicht sauber über Familien hinweg teilen lässt. Aktuelles Beispiel: Das gebündelte xAI-Plugin hält das native Shaping der xAI-Responses in seinem eigenen `wrapStreamFn`, einschließlich Umschreibungen von `/fast`-Aliasen, Standard-`tool_stream`, Bereinigung nicht unterstützter strikter Tools und Entfernung xAI-spezifischer Reasoning-Payload.
Andere gebündelte Provider behalten ebenfalls transport-spezifische Wrapper lokal, wenn
das Verhalten sich nicht sauber über Familien hinweg teilen lässt. Aktuelles Beispiel: Das
gebündelte xAI-Plugin behält die native xAI-Responses-Formung in seinem eigenen
`wrapStreamFn`, einschließlich Umschreibungen von `/fast`-Aliasen, standardmäßigem `tool_stream`,
Bereinigung nicht unterstützter Strict-Tool-Fälle und xAI-spezifischer Entfernung von
Reasoning-Payloads.
`openclaw/plugin-sdk/provider-tools` stellt derzeit eine gemeinsame Tool-Schema-Familie plus gemeinsame Schema-/Kompatibilitäts-Helper bereit:
`openclaw/plugin-sdk/provider-tools` stellt derzeit eine gemeinsame
Tool-Schema-Familie sowie gemeinsame Schema-/Kompatibilitäts-Helper bereit:
- `ProviderToolCompatFamily` dokumentiert das aktuelle Inventar der gemeinsamen Familien.
- `buildProviderToolCompatFamilyHooks("gemini")` verdrahtet Gemini-Schemabereinigung + Diagnose für Anbieter, die Gemini-sichere Tool-Schemas benötigen.
- `normalizeGeminiToolSchemas(...)` und `inspectGeminiToolSchemas(...)` sind die zugrunde liegenden öffentlichen Gemini-Schema-Helper.
- `resolveXaiModelCompatPatch()` gibt den gebündelten xAI-Kompatibilitätspatch zurück:
`toolSchemaProfile: "xai"`, nicht unterstützte Schema-Schlüsselwörter, native Unterstützung für `web_search` und das Dekodieren HTML-entity-kodierter Tool-Call-Argumente.
- `applyXaiModelCompat(model)` wendet denselben xAI-Kompatibilitätspatch auf ein aufgelöstes Modell an, bevor es den Runner erreicht.
- `ProviderToolCompatFamily` dokumentiert heute das gemeinsame Familieninventar.
- `buildProviderToolCompatFamilyHooks("gemini")` verdrahtet Gemini-Schema-
Bereinigung + Diagnostik für Provider, die Gemini-sichere Tool-Schemas benötigen.
- `normalizeGeminiToolSchemas(...)` und `inspectGeminiToolSchemas(...)`
sind die zugrunde liegenden öffentlichen Gemini-Schema-Helper.
- `resolveXaiModelCompatPatch()` gibt den gebündelten xAI-Kompatibilitäts-Patch zurück:
`toolSchemaProfile: "xai"`, nicht unterstützte Schema-Schlüsselwörter, native
Unterstützung für `web_search` und HTML-Entity-Dekodierung von Tool-Call-Argumenten.
- `applyXaiModelCompat(model)` wendet denselben xAI-Kompatibilitäts-Patch auf ein
aufgelöstes Modell an, bevor es den Runner erreicht.
Echtes gebündeltes Beispiel: Das xAI-Plugin verwendet `normalizeResolvedModel` plus `contributeResolvedModelCompat`, um diese Kompatibilitätsmetadaten beim Anbieter zu halten, statt xAI-Regeln im Core fest zu codieren.
Reales gebündeltes Beispiel: Das xAI-Plugin verwendet `normalizeResolvedModel` plus
`contributeResolvedModelCompat`, damit diese Kompatibilitätsmetadaten dem
Provider gehören, anstatt xAI-Regeln im Core fest zu codieren.
Dasselbe Muster mit Paket-Root wird auch von anderen gebündelten Anbietern verwendet:
Dasselbe Paket-Root-Muster stützt auch andere gebündelte Provider:
- `@openclaw/openai-provider`: `api.ts` exportiert Anbieter-Builder,
Helper für Standardmodelle und Builder für Realtime-Anbieter
- `@openclaw/openrouter-provider`: `api.ts` exportiert den Anbieter-Builder
- `@openclaw/openai-provider`: `api.ts` exportiert Provider-Builder,
Default-Modell-Helper und Realtime-Provider-Builder
- `@openclaw/openrouter-provider`: `api.ts` exportiert den Provider-Builder
plus Onboarding-/Konfigurations-Helper
<Tabs>
<Tab title="Token-Austausch">
Für Anbieter, die vor jedem Inferenzaufruf einen Token-Austausch benötigen:
Für Provider, die vor jedem Inferenzaufruf einen Token-Austausch benötigen:
```typescript
prepareRuntimeAuth: async (ctx) => {
@ -393,7 +439,7 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
```
</Tab>
<Tab title="Benutzerdefinierte Header">
Für Anbieter, die benutzerdefinierte Anfrage-Header oder Änderungen am Body benötigen:
Für Provider, die benutzerdefinierte Request-Header oder Änderungen am Body benötigen:
```typescript
// wrapStreamFn gibt eine von ctx.streamFn abgeleitete StreamFn zurück
@ -410,8 +456,8 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
},
```
</Tab>
<Tab title="Native Transportidentität">
Für Anbieter, die native Anfrage-/Sitzungs-Header oder Metadaten auf
<Tab title="Native Transport-Identität">
Für Provider, die native Request-/Sitzungs-Header oder Metadaten auf
generischen HTTP- oder WebSocket-Transporten benötigen:
```typescript
@ -432,8 +478,8 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
}),
```
</Tab>
<Tab title="Usage und Abrechnung">
Für Anbieter, die Usage-/Abrechnungsdaten verfügbar machen:
<Tab title="Nutzung und Abrechnung">
Für Provider, die Nutzungs-/Abrechnungsdaten bereitstellen:
```typescript
resolveUsageAuth: async (ctx) => {
@ -447,80 +493,85 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
</Tab>
</Tabs>
<Accordion title="Alle verfügbaren Anbieter-Hooks">
OpenClaw ruft Hooks in dieser Reihenfolge auf. Die meisten Anbieter verwenden nur 2–3:
<Accordion title="Alle verfügbaren Provider-Hooks">
OpenClaw ruft Hooks in dieser Reihenfolge auf. Die meisten Provider verwenden nur 2–3:
| # | Hook | Wann verwenden |
| --- | --- | --- |
| 1 | `catalog` | Modellkatalog oder Defaults für Basis-URL |
| 2 | `applyConfigDefaults` | Anbieter-eigene globale Defaults während der Konfigurationsmaterialisierung |
| 3 | `normalizeModelId` | Bereinigung von Legacy-/Vorschau-Modell-ID-Aliasen vor dem Lookup |
| 4 | `normalizeTransport` | Bereinigung von `api` / `baseUrl` der Anbieterfamilie vor der generischen Modellzusammensetzung |
| 5 | `normalizeConfig` | `models.providers.<id>`-Konfiguration normalisieren |
| 6 | `applyNativeStreamingUsageCompat` | Native Streaming-Usage-Kompatibilitätsumschreibungen für Konfigurationsanbieter |
| 7 | `resolveConfigApiKey` | Anbieter-eigene Auflösung von Env-Marker-Auth |
| 8 | `resolveSyntheticAuth` | Synthetische Auth für lokal/self-hosted oder konfigurationsgestützte Fälle |
| 9 | `shouldDeferSyntheticProfileAuth` | Gespeicherte synthetische Profil-Platzhalter hinter Env-/Konfigurations-Auth zurückstufen |
| 1 | `catalog` | Modellkatalog oder Defaultwerte für `baseUrl` |
| 2 | `applyConfigDefaults` | Provider-eigene globale Standardwerte während der Materialisierung der Konfiguration |
| 3 | `normalizeModelId` | Bereinigung von Legacy-/Preview-Modell-ID-Aliasen vor dem Lookup |
| 4 | `normalizeTransport` | Bereinigung von `api` / `baseUrl` der Provider-Familie vor der generischen Modellzusammenstellung |
| 5 | `normalizeConfig` | Konfiguration `models.providers.<id>` normalisieren |
| 6 | `applyNativeStreamingUsageCompat` | Native Streaming-Usage-Kompatibilitäts-Umschreibungen für Konfigurations-Provider |
| 7 | `resolveConfigApiKey` | Provider-eigene Auflösung von Env-Marker-Authentifizierung |
| 8 | `resolveSyntheticAuth` | Synthetische lokale/self-hosted oder konfigurationsgestützte Authentifizierung |
| 9 | `shouldDeferSyntheticProfileAuth` | Platzhalter für synthetische gespeicherte Profile hinter Env-/Konfigurations-Authentifizierung zurückstufen |
| 10 | `resolveDynamicModel` | Beliebige Upstream-Modell-IDs akzeptieren |
| 11 | `prepareDynamicModel` | Asynchroner Metadatenabruf vor der Auflösung |
| 11 | `prepareDynamicModel` | Asynchrones Abrufen von Metadaten vor der Auflösung |
| 12 | `normalizeResolvedModel` | Transport-Umschreibungen vor dem Runner |
Hinweise zum Laufzeit-Fallback:
- `normalizeConfig` prüft zuerst den passenden Anbieter und dann andere
hook-fähige Anbieter-Plugins, bis eines die Konfiguration tatsächlich ändert.
Wenn kein Anbieter-Hook einen unterstützten Konfigurationseintrag der Google-Familie umschreibt, greift weiterhin der gebündelte Google-Konfigurationsnormalisierer.
- `resolveConfigApiKey` verwendet den Anbieter-Hook, wenn er bereitgestellt wird. Der gebündelte Pfad `amazon-bedrock` hat hier außerdem einen eingebauten AWS-Env-Marker-Resolver, obwohl Bedrock-Laufzeit-Auth selbst weiterhin die AWS-SDK-Standardkette verwendet.
| 13 | `contributeResolvedModelCompat` | Kompatibilitätsflags für Vendor-Modelle hinter einem anderen kompatiblen Transport |
| 14 | `capabilities` | Legacy-statischer Capability-Bag; nur zur Kompatibilität |
| 15 | `normalizeToolSchemas` | Anbieter-eigene Bereinigung von Tool-Schemas vor der Registrierung |
| 16 | `inspectToolSchemas` | Anbieter-eigene Tool-Schema-Diagnose |
| 17 | `resolveReasoningOutputMode` | Getaggter vs. nativer Vertrag für Reasoning-Ausgabe |
| 18 | `prepareExtraParams` | Standard-Anfrageparameter |
- `normalizeConfig` prüft zuerst den passenden Provider, dann andere
Hook-fähige Provider-Plugins, bis eines die Konfiguration tatsächlich ändert.
Wenn kein Provider-Hook einen unterstützten Google-Familien-Konfigurationseintrag umschreibt, wird
weiterhin der gebündelte Google-Konfigurations-Normalisierer angewendet.
- `resolveConfigApiKey` verwendet den Provider-Hook, wenn er verfügbar ist. Der gebündelte
Pfad `amazon-bedrock` hat hier außerdem einen eingebauten AWS-Env-Marker-Resolver,
auch wenn Bedrock-Laufzeit-Auth selbst weiterhin die AWS-SDK-Default-
Chain verwendet.
| 13 | `contributeResolvedModelCompat` | Kompatibilitäts-Flags für Vendor-Modelle hinter einem anderen kompatiblen Transport |
| 14 | `capabilities` | Legacy-Bag statischer Capabilities; nur aus Kompatibilitätsgründen |
| 15 | `normalizeToolSchemas` | Provider-eigene Tool-Schema-Bereinigung vor der Registrierung |
| 16 | `inspectToolSchemas` | Provider-eigene Tool-Schema-Diagnostik |
| 17 | `resolveReasoningOutputMode` | Markierter vs. nativer Vertrag für Reasoning-Ausgabe |
| 18 | `prepareExtraParams` | Standard-Request-Parameter |
| 19 | `createStreamFn` | Vollständig benutzerdefinierter StreamFn-Transport |
| 20 | `wrapStreamFn` | Benutzerdefinierte Header-/Body-Wrapper auf dem normalen Stream-Pfad |
| 21 | `resolveTransportTurnState` | Native Header/Metadaten pro Turn |
| 22 | `resolveWebSocketSessionPolicy` | Native WS-Sitzungs-Header/Cooldown |
| 23 | `formatApiKey` | Benutzerdefinierte Form des Laufzeit-Tokens |
| 24 | `refreshOAuth` | Benutzerdefiniertes OAuth-Refresh |
| 25 | `buildAuthDoctorHint` | Hinweise zur Auth-Reparatur |
| 26 | `matchesContextOverflowError` | Anbieter-eigene Erkennung von Überläufen |
| 27 | `classifyFailoverReason` | Anbieter-eigene Klassifizierung von Rate-Limit/Überlastung |
| 28 | `isCacheTtlEligible` | Gating für Prompt-Cache-TTL |
| 29 | `buildMissingAuthMessage` | Benutzerdefinierter Hinweis für fehlende Auth |
| 22 | `resolveWebSocketSessionPolicy` | Native WS-Sitzungs-Header/Cool-down |
| 23 | `formatApiKey` | Benutzerdefinierte Laufzeit-Token-Form |
| 24 | `refreshOAuth` | Benutzerdefinierte OAuth-Aktualisierung |
| 25 | `buildAuthDoctorHint` | Hinweise zur Reparatur der Authentifizierung |
| 26 | `matchesContextOverflowError` | Provider-eigene Overflow-Erkennung |
| 27 | `classifyFailoverReason` | Provider-eigene Klassifizierung von Rate-Limit/Überlastung |
| 28 | `isCacheTtlEligible` | TTL-Gating für Prompt-Cache |
| 29 | `buildMissingAuthMessage` | Benutzerdefinierter Hinweis bei fehlender Authentifizierung |
| 30 | `suppressBuiltInModel` | Veraltete Upstream-Zeilen ausblenden |
| 31 | `augmentModelCatalog` | Synthetische Vorwärtskompatibilitäts-Zeilen |
| 32 | `isBinaryThinking` | Binäres Thinking ein/aus |
| 33 | `supportsXHighThinking` | Unterstützung für `xhigh`-Reasoning |
| 34 | `supportsAdaptiveThinking` | Unterstützung für adaptives Thinking |
| 35 | `supportsMaxThinking` | Unterstützung für `max`-Reasoning |
| 36 | `resolveDefaultThinkingLevel` | Standardrichtlinie für `/think` |
| 37 | `isModernModelRef` | Abgleich von Live-/Smoke-Modellen |
| 38 | `prepareRuntimeAuth` | Token-Austausch vor der Inferenz |
| 39 | `resolveUsageAuth` | Benutzerdefiniertes Parsing von Usage-Zugangsdaten |
| 40 | `fetchUsageSnapshot` | Benutzerdefinierter Usage-Endpunkt |
| 41 | `createEmbeddingProvider` | Anbieter-eigener Embedding-Adapter für Memory/Suche |
| 42 | `buildReplayPolicy` | Benutzerdefinierte Richtlinie für Transcript-Replay/Compaction |
| 43 | `sanitizeReplayHistory` | Anbieter-spezifische Replay-Umschreibungen nach generischer Bereinigung |
| 44 | `validateReplayTurns` | Strikte Validierung von Replay-Turns vor dem eingebetteten Runner |
| 45 | `onModelSelected` | Callback nach der Auswahl (z. B. Telemetrie) |
| 31 | `augmentModelCatalog` | Synthetische Zeilen für Vorwärtskompatibilität |
| 32 | `resolveThinkingProfile` | Modellspezifischer Optionssatz für `/think` |
| 33 | `isBinaryThinking` | Kompatibilität für binäres Thinking an/aus |
| 34 | `supportsXHighThinking` | Kompatibilität für `xhigh`-Reasoning-Unterstützung |
| 35 | `resolveDefaultThinkingLevel` | Kompatibilität der Standardrichtlinie für `/think` |
| 36 | `isModernModelRef` | Abgleich von Live-/Smoke-Modellen |
| 37 | `prepareRuntimeAuth` | Token-Austausch vor Inferenz |
| 38 | `resolveUsageAuth` | Benutzerdefiniertes Parsen von Nutzungs-Anmeldedaten |
| 39 | `fetchUsageSnapshot` | Benutzerdefinierter Usage-Endpunkt |
| 40 | `createEmbeddingProvider` | Provider-eigener Embedding-Adapter für Speicher/Suche |
| 41 | `buildReplayPolicy` | Benutzerdefinierte Richtlinie für Transcript-Replay/Compaction |
| 42 | `sanitizeReplayHistory` | Provider-spezifische Replay-Umschreibungen nach generischer Bereinigung |
| 43 | `validateReplayTurns` | Strikte Validierung von Replay-Turns vor dem eingebetteten Runner |
| 44 | `onModelSelected` | Callback nach Auswahl (z. B. Telemetrie) |
Hinweis zur Prompt-Abstimmung:
- `resolveSystemPromptContribution` erlaubt einem Anbieter, cache-bewusste
Hinweise für den System-Prompt in einer Modellfamilie zu injizieren. Bevorzugen Sie es gegenüber `before_prompt_build`, wenn das Verhalten zu einer Anbieter-/Modellfamilie gehört und die stabile/dynamische Cache-Aufteilung erhalten bleiben soll.
- `resolveSystemPromptContribution` erlaubt einem Provider das Einfügen Cache-bewusster
System-Prompt-Hinweise für eine Modellfamilie. Bevorzugen Sie dies gegenüber
`before_prompt_build`, wenn das Verhalten zu einer Provider-/Modellfamilie gehört
und die stabile/dynamische Cache-Aufteilung erhalten bleiben soll.
Ausführliche Beschreibungen und Beispiele aus der Praxis finden Sie unter
[Internals: Provider Runtime Hooks](/de/plugins/architecture#provider-runtime-hooks).
[Internals: Provider-Laufzeit-Hooks](/de/plugins/architecture#provider-runtime-hooks).
</Accordion>
</Step>
<Step title="Zusätzliche Fähigkeiten hinzufügen (optional)">
<Step title="Zusätzliche Capabilities hinzufügen (optional)">
<a id="step-5-add-extra-capabilities"></a>
Ein Anbieter-Plugin kann Sprache, Realtime-Transkription, Realtime-Stimme,
Medienverständnis, Bildgenerierung, Videogenerierung, Web-Fetch
und Websuche neben der Textinferenz registrieren:
Ein Provider-Plugin kann zusätzlich zur Textinferenz Speech, Realtime-Transkription, Realtime-
Voice, Medienverständnis, Bildgenerierung, Videogenerierung, Web-Fetch
und Websuche registrieren:
```typescript
register(api) {
@ -531,7 +582,7 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
label: "Acme Speech",
isConfigured: ({ config }) => Boolean(config.messages?.tts),
synthesize: async (req) => ({
audioBuffer: Buffer.from(/* PCM-Daten */),
audioBuffer: Buffer.from(/* PCM data */),
outputFormat: "mp3",
fileExtension: ".mp3",
voiceCompatible: false,
@ -568,14 +619,14 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
api.registerMediaUnderstandingProvider({
id: "acme-ai",
capabilities: ["image", "audio"],
describeImage: async (req) => ({ text: "Ein Foto von ..." }),
transcribeAudio: async (req) => ({ text: "Transkript ..." }),
describeImage: async (req) => ({ text: "A photo of..." }),
transcribeAudio: async (req) => ({ text: "Transcript..." }),
});
api.registerImageGenerationProvider({
id: "acme-ai",
label: "Acme Images",
generate: async (req) => ({ /* Bildergebnis */ }),
generate: async (req) => ({ /* image result */ }),
});
api.registerVideoGenerationProvider({
@ -603,7 +654,7 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
api.registerWebFetchProvider({
id: "acme-ai-fetch",
label: "Acme Fetch",
hint: "Seiten über Acmes Rendering-Backend abrufen.",
hint: "Fetch pages through Acme's rendering backend.",
envVars: ["ACME_FETCH_API_KEY"],
placeholder: "acme-...",
signupUrl: "https://acme.example.com/fetch",
@ -614,7 +665,7 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
acme.apiKey = value;
},
createTool: () => ({
description: "Eine Seite über Acme Fetch abrufen.",
description: "Fetch a page through Acme Fetch.",
parameters: {},
execute: async (args) => ({ content: [] }),
}),
@ -628,15 +679,20 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
}
```
OpenClaw klassifiziert dies als Plugin mit **hybrider Fähigkeit**. Das ist das empfohlene Muster für Firmen-Plugins (ein Plugin pro Anbieter). Siehe [Internals: Capability Ownership](/de/plugins/architecture#capability-ownership-model).
OpenClaw klassifiziert dies als Plugin mit **hybrid-capability**. Dies ist das
empfohlene Muster für Unternehmens-Plugins (ein Plugin pro Anbieter). Siehe
[Internals: Capability Ownership](/de/plugins/architecture#capability-ownership-model).
Für die Videogenerierung bevorzugen Sie die oben gezeigte, modusbewusste Form der Fähigkeiten:
Bevorzugen Sie bei der Videogenerierung die oben gezeigte fähigkeitsform mit Modusbezug:
`generate`, `imageToVideo` und `videoToVideo`. Flache aggregierte Felder wie
`maxInputImages`, `maxInputVideos` und `maxDurationSeconds` reichen nicht aus, um Unterstützung oder deaktivierte Modi für Transformationsmodi sauber zu bewerben.
`maxInputImages`, `maxInputVideos` und `maxDurationSeconds` reichen nicht
aus, um Unterstützung für Transformationsmodi oder deaktivierte Modi sauber zu bewerben.
Anbieter für Musikgenerierung sollten demselben Muster folgen:
`generate` für promptbasierte Generierung und `edit` für referenzbildbasierte Generierung. Flache aggregierte Felder wie `maxInputImages`,
`supportsLyrics` und `supportsFormat` reichen nicht aus, um Unterstützung für Bearbeitung zu bewerben; explizite Blöcke `generate` / `edit` sind der erwartete Vertrag.
Provider für Musikgenerierung sollten demselben Muster folgen:
`generate` für reine Prompt-basierte Generierung und `edit` für referenzbildbasierte
Generierung. Flache aggregierte Felder wie `maxInputImages`,
`supportsLyrics` und `supportsFormat` reichen nicht aus, um Bearbeitungs-
unterstützung zu bewerben; explizite Blöcke `generate` / `edit` sind der erwartete Vertrag.
</Step>
@ -644,11 +700,11 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
<a id="step-6-test"></a>
```typescript src/provider.test.ts
import { describe, it, expect } from "vitest";
// Exportieren Sie Ihr Anbieter-Konfigurationsobjekt aus index.ts oder einer dedizierten Datei
// Export your provider config object from index.ts or a dedicated file
import { acmeProvider } from "./provider.js";
describe("acme-ai provider", () => {
it("löst dynamische Modelle auf", () => {
it("resolves dynamic models", () => {
const model = acmeProvider.resolveDynamicModel!({
modelId: "acme-beta-v3",
} as any);
@ -656,14 +712,14 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
expect(model.provider).toBe("acme-ai");
});
it("gibt den Katalog zurück, wenn ein Schlüssel verfügbar ist", async () => {
it("returns catalog when key is available", async () => {
const result = await acmeProvider.catalog!.run({
resolveProviderApiKey: () => ({ apiKey: "test-key" }),
} as any);
expect(result?.provider?.models).toHaveLength(2);
});
it("gibt null für den Katalog zurück, wenn kein Schlüssel vorhanden ist", async () => {
it("returns null catalog when no key", async () => {
const result = await acmeProvider.catalog!.run({
resolveProviderApiKey: () => ({ apiKey: undefined }),
} as any);
@ -675,23 +731,24 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open
</Step>
</Steps>
## In ClawHub veröffentlichen
## Auf ClawHub veröffentlichen
Anbieter-Plugins werden wie jeder andere externe Code-Plugin veröffentlicht:
Provider-Plugins werden auf die gleiche Weise veröffentlicht wie jedes andere externe Code-Plugin:
```bash
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
```
Verwenden Sie hier nicht den veralteten Publish-Alias nur für Skills; Plugin-Pakete sollten `clawhub package publish` verwenden.
Verwenden Sie hier nicht den veralteten Nur-Skills-Veröffentlichungsalias; Plugin-Pakete sollten
`clawhub package publish` verwenden.
## Dateistruktur
```
<bundled-plugin-root>/acme-ai/
├── package.json # openclaw.providers-Metadaten
├── openclaw.plugin.json # Manifest mit Anbieter-Auth-Metadaten
├── openclaw.plugin.json # Manifest mit Provider-Authentifizierungsmetadaten
├── index.ts # definePluginEntry + registerProvider
└── src/
├── provider.test.ts # Tests
@ -700,18 +757,19 @@ Verwenden Sie hier nicht den veralteten Publish-Alias nur für Skills; Plugin-Pa
## Referenz zur Katalogreihenfolge
`catalog.order` steuert, wann Ihr Katalog relativ zu eingebauten Anbietern zusammengeführt wird:
`catalog.order` steuert, wann Ihr Katalog relativ zu integrierten
Providern zusammengeführt wird:
| Order | Wann | Anwendungsfall |
| --------- | ------------- | ----------------------------------------------- |
| `simple` | Erster Durchlauf | Einfache Anbieter mit API-Schlüssel |
| `profile` | Nach simple | Anbieter, die von Auth-Profilen abhängen |
| `paired` | Nach profile | Mehrere verwandte Einträge synthetisieren |
| `late` | Letzter Durchlauf | Vorhandene Anbieter überschreiben (gewinnt bei Kollision) |
| Reihenfolge | Wann | Anwendungsfall |
| ----------- | ------------ | -------------------------------------------- |
| `simple` | Erster Durchlauf | Einfache Provider mit API-Key |
| `profile` | Nach simple | Provider, die von Auth-Profilen abhängen |
| `paired` | Nach profile | Mehrere zusammengehörige Einträge synthetisieren |
| `late` | Letzter Durchlauf | Vorhandene Provider überschreiben (gewinnt bei Kollision) |
## Nächste Schritte
- [Kanal-Plugins](/de/plugins/sdk-channel-plugins) — wenn Ihr Plugin auch einen Kanal bereitstellt
- [SDK Runtime](/de/plugins/sdk-runtime) — `api.runtime`-Helper (TTS, Suche, Subagent)
- [SDK-Überblick](/de/plugins/sdk-overview) — vollständige Referenz für Subpfad-Importe
- [Plugin-Internals](/de/plugins/architecture#provider-runtime-hooks) — Hook-Details und gebündelte Beispiele
- [SDK-Laufzeit](/de/plugins/sdk-runtime) — Helper für `api.runtime` (TTS, Suche, Subagent)
- [SDK-Überblick](/de/plugins/sdk-overview) — vollständige Referenz für Subpath-Importe
- [Plugin-Interna](/de/plugins/architecture#provider-runtime-hooks) — Hook-Details und gebündelte Beispiele

513
docs/de/tools/acp-agents.md
View File

@ -1,78 +1,78 @@
---
read_when:
- Coding-Harnesses über ACP ausführen
- Konversationsgebundene ACP-Sitzungen auf Messaging-Channels einrichten
- Eine Konversation in einem Message-Channel an eine persistente ACP-Sitzung binden
- Ausführen von Coding-Harnesses über ACP
- Einrichten von gesprächsgebundenen ACP-Sitzungen auf Messaging-Kanälen
- Binden einer Nachrichtenkanal-Konversation an eine persistente ACP-Sitzung
- Fehlerbehebung bei ACP-Backend- und Plugin-Verdrahtung
- '`/acp`-Befehle aus dem Chat bedienen'
summary: ACP-Laufzeitsitzungen für Codex, Claude Code, Cursor, Gemini CLI, OpenClaw ACP und andere Harness-Agenten verwenden
- Bedienen von `/acp`-Befehlen aus dem Chat
summary: Verwenden Sie ACP-Laufzeitsitzungen für Codex, Claude Code, Cursor, Gemini CLI, OpenClaw ACP und andere Harness-Agenten.
title: ACP Agents
x-i18n:
generated_at: "2026-04-08T02:20:33Z"
generated_at: "2026-04-21T13:37:25Z"
model: gpt-5.4
provider: openai
source_hash: 71c7c0cdae5247aefef17a0029360950a1c2987ddcee21a1bb7d78c67da52950
source_hash: e458ff21d63e52ed0eed4ed65ba2c45aecae20563a3ef10bf4b64e948284b51a
source_path: tools/acp-agents.md
workflow: 15
---
# ACP Agents
# ACP-Agents
Sitzungen mit dem [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) ermöglichen es OpenClaw, externe Coding-Harnesses (zum Beispiel Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI und andere unterstützte ACPX-Harnesses) über ein ACP-Backend-Plugin auszuführen.
Sitzungen des [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) ermöglichen es OpenClaw, externe Coding-Harnesses (zum Beispiel Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI und andere unterstützte ACPX-Harnesses) über ein ACP-Backend-Plugin auszuführen.
Wenn Sie OpenClaw in natürlicher Sprache bitten, „das in Codex auszuführen“ oder „Claude Code in einem Thread zu starten“, sollte OpenClaw diese Anfrage an die ACP-Laufzeit weiterleiten (nicht an die native Subagent-Laufzeit). Jeder ACP-Sitzungsstart wird als [Hintergrundaufgabe](/de/automation/tasks) erfasst.
Wenn Sie OpenClaw in natürlicher Sprache bitten, „das in Codex auszuführen“ oder „Claude Code in einem Thread zu starten“, sollte OpenClaw diese Anfrage an die ACP-Laufzeit weiterleiten (nicht an die native Sub-Agent-Laufzeit). Jeder ACP-Sitzungsstart wird als [Hintergrundaufgabe](/de/automation/tasks) nachverfolgt.
Wenn Sie möchten, dass Codex oder Claude Code sich stattdessen direkt als externer MCP-Client
mit bestehenden OpenClaw-Channel-Konversationen verbinden, verwenden Sie
[`openclaw mcp serve`](/cli/mcp) anstelle von ACP.
Wenn Sie möchten, dass Codex oder Claude Code direkt als externer MCP-Client
mit bestehenden OpenClaw-Kanal-Konversationen verbunden werden, verwenden Sie
anstelle von ACP [`openclaw mcp serve`](/cli/mcp).
## Welche Seite brauche ich?
Es gibt drei benachbarte Oberflächen, die leicht verwechselt werden können:
Es gibt drei nahe verwandte Oberflächen, die leicht verwechselt werden:
| Sie möchten... | Verwenden Sie dies | Hinweise |
| ----------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Codex, Claude Code, Gemini CLI oder ein anderes externes Harness _durch_ OpenClaw ausführen | Diese Seite: ACP Agents | Chat-gebundene Sitzungen, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, Hintergrundaufgaben, Laufzeitsteuerung |
| Eine OpenClaw-Gateway-Sitzung _als_ ACP-Server für einen Editor oder Client bereitstellen | [`openclaw acp`](/cli/acp) | Bridge-Modus. IDE/Client spricht ACP über stdio/WebSocket mit OpenClaw |
| Eine lokale AI-CLI als reines Text-Fallback-Modell wiederverwenden | [CLI Backends](/de/gateway/cli-backends) | Nicht ACP. Keine OpenClaw-Tools, keine ACP-Steuerung, keine Harness-Laufzeit |
| Sie möchten... | Verwenden Sie dies | Hinweise |
| ----------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Codex, Claude Code, Gemini CLI oder ein anderes externes Harness _über_ OpenClaw ausführen | Diese Seite: ACP-Agents | Chat-gebundene Sitzungen, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, Hintergrundaufgaben, Laufzeitsteuerung |
| Eine OpenClaw-Gateway-Sitzung _als_ ACP-Server für einen Editor oder Client bereitstellen | [`openclaw acp`](/cli/acp) | Bridge-Modus. IDE/Client spricht ACP mit OpenClaw über stdio/WebSocket |
| Eine lokale AI-CLI als reines Text-Fallback-Modell wiederverwenden | [CLI-Backends](/de/gateway/cli-backends) | Nicht ACP. Keine OpenClaw-Tools, keine ACP-Steuerung, keine Harness-Laufzeit |
## Funktioniert das sofort?
Normalerweise ja.
- Frische Installationen werden jetzt standardmäßig mit aktiviertem gebündeltem `acpx`-Laufzeit-Plugin ausgeliefert.
- Frische Installationen werden jetzt standardmäßig mit aktiviertem gebündelten `acpx`-Laufzeit-Plugin ausgeliefert.
- Das gebündelte `acpx`-Plugin bevorzugt seine pluginlokal angeheftete `acpx`-Binärdatei.
- Beim Start prüft OpenClaw diese Binärdatei und repariert sie bei Bedarf selbst.
- Beginnen Sie mit `/acp doctor`, wenn Sie eine schnelle Bereitschaftsprüfung möchten.
Was bei der ersten Verwendung trotzdem passieren kann:
Was bei der ersten Nutzung trotzdem passieren kann:
- Ein Ziel-Harness-Adapter kann bei der ersten Verwendung dieses Harnesses bei Bedarf mit `npx` abgerufen werden.
- Die Vendor-Authentifizierung muss für dieses Harness weiterhin auf dem Host vorhanden sein.
- Wenn der Host keinen npm-/Netzwerkzugriff hat, können Adapter-Abrufe beim ersten Start fehlschlagen, bis Caches vorgewärmt sind oder der Adapter auf andere Weise installiert wurde.
- Ein Ziel-Harness-Adapter kann bei der ersten Verwendung dieses Harnesses bedarfsabhängig mit `npx` abgerufen werden.
- Vendor-Authentifizierung muss auf dem Host für dieses Harness weiterhin vorhanden sein.
- Wenn der Host keinen npm-/Netzwerkzugang hat, kann das erstmalige Abrufen von Adaptern fehlschlagen, bis die Caches vorgewärmt sind oder der Adapter auf andere Weise installiert wird.
Beispiele:
- `/acp spawn codex`: OpenClaw sollte bereit sein, `acpx` zu bootstrappen, aber der Codex-ACP-Adapter benötigt möglicherweise trotzdem noch einen Abruf beim ersten Lauf.
- `/acp spawn claude`: dieselbe Situation für den Claude-ACP-Adapter, plus Claude-seitige Authentifizierung auf diesem Host.
- `/acp spawn codex`: OpenClaw sollte bereit sein, `acpx` zu bootstrappen, aber der Codex-ACP-Adapter muss möglicherweise beim ersten Lauf noch abgerufen werden.
- `/acp spawn claude`: dasselbe gilt für den Claude-ACP-Adapter sowie für die Claude-seitige Authentifizierung auf diesem Host.
## Schneller Operator-Ablauf
Verwenden Sie dies, wenn Sie ein praktisches `/acp`-Runbook möchten:
1. Starten Sie eine Sitzung:
1. Eine Sitzung starten:
- `/acp spawn codex --bind here`
- `/acp spawn codex --mode persistent --thread auto`
2. Arbeiten Sie in der gebundenen Konversation oder im Thread (oder adressieren Sie diesen Sitzungsschlüssel explizit).
3. Prüfen Sie den Laufzeitstatus:
2. In der gebundenen Konversation oder im Thread arbeiten (oder diesen Sitzungsschlüssel explizit ansprechen).
3. Laufzeitstatus prüfen:
- `/acp status`
4. Passen Sie Laufzeitoptionen bei Bedarf an:
4. Laufzeitoptionen nach Bedarf anpassen:
- `/acp model <provider/model>`
- `/acp permissions <profile>`
- `/acp timeout <seconds>`
5. Geben Sie einer aktiven Sitzung einen Schubs, ohne den Kontext zu ersetzen:
5. Eine aktive Sitzung anstoßen, ohne den Kontext zu ersetzen:
- `/acp steer tighten logging and continue`
6. Beenden Sie die Arbeit:
6. Arbeit beenden:
- `/acp cancel` (aktuellen Turn stoppen), oder
- `/acp close` (Sitzung schließen + Bindungen entfernen)
@ -80,152 +80,152 @@ Verwenden Sie dies, wenn Sie ein praktisches `/acp`-Runbook möchten:
Beispiele für natürliche Anfragen:
- „Binde diesen Discord-Channel an Codex.“
- „Starte hier in einem Thread eine persistente Codex-Sitzung und halte sie fokussiert.“
- „Führe das als einmalige Claude Code ACP-Sitzung aus und fasse das Ergebnis zusammen.“
- „Binde diesen iMessage-Chat an Codex und halte Folgeanfragen im selben Workspace.“
- „Verwende für diese Aufgabe Gemini CLI in einem Thread und halte Folgeanfragen dann in demselben Thread.“
- „Diesen Discord-Kanal an Codex binden.“
- „Hier eine persistente Codex-Sitzung in einem Thread starten und fokussiert halten.“
- „Das als One-Shot-Claude-Code-ACP-Sitzung ausführen und das Ergebnis zusammenfassen.“
- „Diesen iMessage-Chat an Codex binden und Folgeanfragen im selben Arbeitsbereich behalten.“
- „Für diese Aufgabe Gemini CLI in einem Thread verwenden und Folgeanfragen dann in demselben Thread behalten.“
Was OpenClaw tun sollte:
1. `runtime: "acp"` auswählen.
1. `runtime: "acp"` wählen.
2. Das angeforderte Harness-Ziel auflösen (`agentId`, zum Beispiel `codex`).
3. Wenn eine Bindung an die aktuelle Konversation angefordert wird und der aktive Channel dies unterstützt, die ACP-Sitzung an diese Konversation binden.
4. Andernfalls, wenn eine Thread-Bindung angefordert wird und der aktuelle Channel dies unterstützt, die ACP-Sitzung an den Thread binden.
5. Folgeanfragen in dieser Bindung an dieselbe ACP-Sitzung weiterleiten, bis sie entfokussiert/geschlossen/abgelaufen ist.
3. Wenn eine Bindung an die aktuelle Konversation angefordert wird und der aktive Kanal dies unterstützt, die ACP-Sitzung an diese Konversation binden.
4. Andernfalls, wenn eine Thread-Bindung angefordert wird und der aktuelle Kanal dies unterstützt, die ACP-Sitzung an den Thread binden.
5. Gebundene Folgenachrichten an dieselbe ACP-Sitzung weiterleiten, bis der Fokus aufgehoben, sie geschlossen oder sie abgelaufen ist.
## ACP im Vergleich zu Subagenten
## ACP versus Sub-Agents
Verwenden Sie ACP, wenn Sie eine externe Harness-Laufzeit möchten. Verwenden Sie Subagenten, wenn Sie delegierte Ausführungen nativ in OpenClaw möchten.
Verwenden Sie ACP, wenn Sie eine externe Harness-Laufzeit möchten. Verwenden Sie Sub-Agents, wenn Sie OpenClaw-native delegierte Ausführungen möchten.
| Bereich | ACP-Sitzung | Subagent-Ausführung |
| Bereich | ACP-Sitzung | Sub-Agent-Ausführung |
| ------------- | ------------------------------------- | ----------------------------------- |
| Laufzeit | ACP-Backend-Plugin (zum Beispiel acpx) | Native OpenClaw-Subagent-Laufzeit |
| Laufzeit | ACP-Backend-Plugin (zum Beispiel acpx) | OpenClaw-native Sub-Agent-Laufzeit |
| Sitzungsschlüssel | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
| Hauptbefehle | `/acp ...` | `/subagents ...` |
| Spawn-Tool | `sessions_spawn` mit `runtime:"acp"` | `sessions_spawn` (Standardlaufzeit) |
Siehe auch [Sub-agents](/de/tools/subagents).
Siehe auch [Sub-Agents](/de/tools/subagents).
## Wie ACP Claude Code ausführt
Für Claude Code über ACP ist der Stack:
Für Claude Code über ACP sieht der Stack so aus:
1. OpenClaw-ACP-Sitzungs-Kontrollplane
1. OpenClaw-ACP-Sitzungs-Steuerungsebene
2. gebündeltes `acpx`-Laufzeit-Plugin
3. Claude-ACP-Adapter
4. Claude-seitige Laufzeit-/Sitzungsmechanik
Wichtige Unterscheidung:
- ACP Claude ist eine Harness-Sitzung mit ACP-Steuerung, Sitzungsfortsetzung, Hintergrundaufgaben-Tracking und optionaler Konversations-/Thread-Bindung.
- CLI-Backends sind separate lokale Text-Fallback-Laufzeiten. Siehe [CLI Backends](/de/gateway/cli-backends).
- ACP Claude ist eine Harness-Sitzung mit ACP-Steuerung, Sitzungsfortsetzung, Nachverfolgung von Hintergrundaufgaben und optionaler Konversations-/Thread-Bindung.
- CLI-Backends sind separate reine Text-Local-Fallback-Laufzeiten. Siehe [CLI-Backends](/de/gateway/cli-backends).
Für Operatoren gilt praktisch:
Für Operatoren lautet die praktische Regel:
- Wenn Sie `/acp spawn`, bindbare Sitzungen, Laufzeitsteuerung oder persistente Harness-Arbeit möchten: ACP verwenden
- Wenn Sie ein einfaches lokales Text-Fallback über die rohe CLI möchten: CLI-Backends verwenden
- wenn Sie `/acp spawn`, bindbare Sitzungen, Laufzeitsteuerung oder persistente Harness-Arbeit möchten: ACP verwenden
- wenn Sie einfaches lokales Text-Fallback über die rohe CLI möchten: CLI-Backends verwenden
## Gebundene Sitzungen
### Bindungen an die aktuelle Konversation
Verwenden Sie `/acp spawn <harness> --bind here`, wenn Sie möchten, dass die aktuelle Konversation zu einem dauerhaften ACP-Workspace wird, ohne einen untergeordneten Thread zu erstellen.
Verwenden Sie `/acp spawn <harness> --bind here`, wenn die aktuelle Konversation zu einem dauerhaften ACP-Arbeitsbereich werden soll, ohne einen untergeordneten Thread zu erstellen.
Verhalten:
- OpenClaw bleibt Eigentümer von Channel-Transport, Authentifizierung, Sicherheit und Zustellung.
- OpenClaw bleibt Eigentümer von Kanaltransport, Authentifizierung, Sicherheit und Zustellung.
- Die aktuelle Konversation wird an den gestarteten ACP-Sitzungsschlüssel angeheftet.
- Folge-Nachrichten in dieser Konversation werden an dieselbe ACP-Sitzung weitergeleitet.
- Folgenachrichten in dieser Konversation werden an dieselbe ACP-Sitzung weitergeleitet.
- `/new` und `/reset` setzen dieselbe gebundene ACP-Sitzung an Ort und Stelle zurück.
- `/acp close` schließt die Sitzung und entfernt die Bindung an die aktuelle Konversation.
Was das in der Praxis bedeutet:
- `--bind here` behält dieselbe Chat-Oberfläche bei. Auf Discord bleibt der aktuelle Channel der aktuelle Channel.
- `--bind here` kann trotzdem eine neue ACP-Sitzung erstellen, wenn Sie neue Arbeit starten. Die Bindung verknüpft diese Sitzung mit der aktuellen Konversation.
- `--bind here` erstellt nicht von selbst einen untergeordneten Discord-Thread oder ein Telegram-Thema.
- Die ACP-Laufzeit kann trotzdem ihr eigenes Arbeitsverzeichnis (`cwd`) oder einen backendverwalteten Workspace auf der Festplatte haben. Dieser Laufzeit-Workspace ist von der Chat-Oberfläche getrennt und impliziert keinen neuen Messaging-Thread.
- Wenn Sie zu einem anderen ACP-Agenten spawnen und kein `--cwd` übergeben, übernimmt OpenClaw standardmäßig den Workspace des **Ziel-Agenten**, nicht den des Anforderers.
- Wenn dieser übernommene Workspace-Pfad fehlt (`ENOENT`/`ENOTDIR`), fällt OpenClaw auf das Standard-`cwd` des Backends zurück, statt stillschweigend den falschen Baum wiederzuverwenden.
- Wenn der übernommene Workspace existiert, aber nicht zugänglich ist (zum Beispiel `EACCES`), gibt der Spawn den echten Zugriffsfehler zurück, statt `cwd` zu verwerfen.
- `--bind here` behält dieselbe Chat-Oberfläche. Auf Discord bleibt der aktuelle Kanal der aktuelle Kanal.
- `--bind here` kann trotzdem eine neue ACP-Sitzung erstellen, wenn Sie frische Arbeit starten. Die Bindung verknüpft diese Sitzung mit der aktuellen Konversation.
- `--bind here` erstellt nicht selbstständig einen untergeordneten Discord-Thread oder ein Telegram-Thema.
- Die ACP-Laufzeit kann weiterhin ihr eigenes Arbeitsverzeichnis (`cwd`) oder einen backendverwalteten Arbeitsbereich auf der Festplatte haben. Dieser Laufzeit-Arbeitsbereich ist von der Chat-Oberfläche getrennt und impliziert keinen neuen Messaging-Thread.
- Wenn Sie zu einem anderen ACP-Agenten starten und `--cwd` nicht übergeben, übernimmt OpenClaw standardmäßig den Arbeitsbereich des **Ziel-Agenten**, nicht den des Anforderers.
- Wenn dieser übernommene Arbeitsbereichspfad fehlt (`ENOENT`/`ENOTDIR`), fällt OpenClaw auf das Standard-`cwd` des Backends zurück, anstatt stillschweigend den falschen Baum wiederzuverwenden.
- Wenn der übernommene Arbeitsbereich existiert, aber nicht zugänglich ist (zum Beispiel `EACCES`), gibt Spawn den tatsächlichen Zugriffsfehler zurück, anstatt `cwd` zu verwerfen.
Mentales Modell:
- Chat-Oberfläche: wo Menschen weiter sprechen (`Discord channel`, `Telegram topic`, `iMessage chat`)
- Chat-Oberfläche: wo Menschen weiter reden (`Discord-Kanal`, `Telegram-Thema`, `iMessage-Chat`)
- ACP-Sitzung: der dauerhafte Codex-/Claude-/Gemini-Laufzeitzustand, an den OpenClaw weiterleitet
- untergeordneter Thread/Thema: eine optionale zusätzliche Messaging-Oberfläche, die nur durch `--thread ...` erstellt wird
- Laufzeit-Workspace: der Dateisystemort, an dem das Harness ausgeführt wird (`cwd`, Repo-Checkout, Backend-Workspace)
- Laufzeit-Arbeitsbereich: der Dateisystemort, an dem das Harness läuft (`cwd`, Repository-Checkout, Backend-Arbeitsbereich)
Beispiele:
- `/acp spawn codex --bind here`: diesen Chat beibehalten, eine Codex-ACP-Sitzung starten oder anhängen und zukünftige Nachrichten hierhin weiterleiten
- `/acp spawn codex --thread auto`: OpenClaw kann einen untergeordneten Thread/ein Thema erstellen und die ACP-Sitzung dort binden
- `/acp spawn codex --bind here`: diesen Chat beibehalten, eine Codex-ACP-Sitzung starten oder anhängen und künftige Nachrichten hierhin an sie weiterleiten
- `/acp spawn codex --thread auto`: OpenClaw kann einen untergeordneten Thread/ein Thema erstellen und dort die ACP-Sitzung binden
- `/acp spawn codex --bind here --cwd /workspace/repo`: dieselbe Chat-Bindung wie oben, aber Codex läuft in `/workspace/repo`
Unterstützung für die Bindung an die aktuelle Konversation:
Unterstützung für Bindung an die aktuelle Konversation:
- Chat-/Message-Channels, die Unterstützung für die Bindung an die aktuelle Konversation ausweisen, können `--bind here` über den gemeinsamen Konversations-Bindungspfad verwenden.
- Channels mit eigener Thread-/Themen-Semantik können hinter derselben gemeinsamen Schnittstelle weiterhin channelspezifische Kanonisierung bereitstellen.
- Chat-/Nachrichtenkanäle, die die Bindung an die aktuelle Konversation unterstützen, können `--bind here` über den gemeinsamen Konversations-Bindungspfad verwenden.
- Kanäle mit benutzerdefinierter Thread-/Thema-Semantik können hinter derselben gemeinsamen Schnittstelle weiterhin kanalspezifische Kanonisierung bereitstellen.
- `--bind here` bedeutet immer „die aktuelle Konversation an Ort und Stelle binden“.
- Generische Bindungen an die aktuelle Konversation verwenden den gemeinsamen OpenClaw-Binding-Store und überstehen normale Gateway-Neustarts.
Hinweise:
- `--bind here` und `--thread ...` schließen sich bei `/acp spawn` gegenseitig aus.
- Auf Discord bindet `--bind here` den aktuellen Channel oder Thread an Ort und Stelle. `spawnAcpSessions` ist nur erforderlich, wenn OpenClaw für `--thread auto|here` einen untergeordneten Thread erstellen muss.
- Wenn der aktive Channel keine ACP-Bindungen an die aktuelle Konversation bereitstellt, gibt OpenClaw eine klare Meldung zurück, dass dies nicht unterstützt wird.
- `resume` und Fragen nach einer „neuen Sitzung“ sind ACP-Sitzungsfragen, keine Channel-Fragen. Sie können den Laufzeitzustand wiederverwenden oder ersetzen, ohne die aktuelle Chat-Oberfläche zu ändern.
- Auf Discord bindet `--bind here` den aktuellen Kanal oder Thread an Ort und Stelle. `spawnAcpSessions` ist nur erforderlich, wenn OpenClaw für `--thread auto|here` einen untergeordneten Thread erstellen muss.
- Wenn der aktive Kanal keine ACP-Bindungen an die aktuelle Konversation bereitstellt, gibt OpenClaw eine klare Meldung zurück, dass dies nicht unterstützt wird.
- `resume` und Fragen zu „neuer Sitzung“ sind Fragen zur ACP-Sitzung, nicht zum Kanal. Sie können den Laufzeitzustand wiederverwenden oder ersetzen, ohne die aktuelle Chat-Oberfläche zu ändern.
### Thread-gebundene Sitzungen
Wenn Thread-Bindungen für einen Channel-Adapter aktiviert sind, können ACP-Sitzungen an Threads gebunden werden:
Wenn Thread-Bindungen für einen Kanaladapter aktiviert sind, können ACP-Sitzungen an Threads gebunden werden:
- OpenClaw bindet einen Thread an eine Ziel-ACP-Sitzung.
- Folge-Nachrichten in diesem Thread werden an die gebundene ACP-Sitzung weitergeleitet.
- ACP-Ausgaben werden an denselben Thread zurückgeliefert.
- Entfokussieren/Schließen/Archivieren/Ablauf durch Leerlauf-Timeout oder Maximalalter entfernt die Bindung.
- Folgenachrichten in diesem Thread werden an die gebundene ACP-Sitzung weitergeleitet.
- ACP-Ausgaben werden in denselben Thread zurückgeliefert.
- Fokus aufheben/Schließen/Archivieren/Leerlauf-Timeout oder Ablauf des maximalen Alters entfernt die Bindung.
Die Unterstützung für Thread-Bindungen ist adapterspezifisch. Wenn der aktive Channel-Adapter keine Thread-Bindungen unterstützt, gibt OpenClaw eine klare Meldung zurück, dass dies nicht unterstützt/verfügbar ist.
Die Unterstützung für Thread-Bindungen ist adapterspezifisch. Wenn der aktive Kanaladapter keine Thread-Bindungen unterstützt, gibt OpenClaw eine klare Meldung zurück, dass dies nicht unterstützt/verfügbar ist.
Erforderliche Feature-Flags für threadgebundenes ACP:
Erforderliche Feature-Flags für threadgebundene ACP:
- `acp.enabled=true`
- `acp.dispatch.enabled` ist standardmäßig aktiviert (auf `false` setzen, um ACP-Dispatch zu pausieren)
- ACP-Thread-Spawn-Flag des Channel-Adapters aktiviert (adapterspezifisch)
- ACP-Thread-Spawn-Flag des Kanaladapters aktiviert (adapterspezifisch)
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
- Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true`
### Channels mit Thread-Unterstützung
### Kanäle mit Thread-Unterstützung
- Jeder Channel-Adapter, der die Fähigkeit zur Sitzungs-/Thread-Bindung bereitstellt.
- Aktuelle eingebaute Unterstützung:
- Discord-Threads/-Channels
- Telegram-Themen (Forum-Themen in Gruppen/Supergroups und DM-Themen)
- Plugin-Channels können Unterstützung über dieselbe Binding-Schnittstelle hinzufügen.
- Jeder Kanaladapter, der Sitzungs-/Thread-Bindungsfähigkeit bereitstellt.
- Aktuelle integrierte Unterstützung:
- Discord-Threads/-Kanäle
- Telegram-Themen (Forenthemen in Gruppen/Supergruppen und DM-Themen)
- Plugin-Kanäle können Unterstützung über dieselbe Bindungsschnittstelle hinzufügen.
## Channelspezifische Einstellungen
## Kanalspezifische Einstellungen
Für nicht-ephemere Workflows konfigurieren Sie persistente ACP-Bindungen in Top-Level-Einträgen `bindings[]`.
### Binding-Modell
### Bindungsmodell
- `bindings[].type="acp"` kennzeichnet eine persistente ACP-Konversationsbindung.
- `bindings[].match` identifiziert die Zielkonversation:
- Discord-Channel oder -Thread: `match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
- Telegram-Forum-Thema: `match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
- BlueBubbles-DM-/Gruppenchat: `match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
Bevorzugen Sie `chat_id:*` oder `chat_identifier:*` für stabile Gruppenbindungen.
- iMessage-DM-/Gruppenchat: `match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
Bevorzugen Sie `chat_id:*` für stabile Gruppenbindungen.
- `bindings[].agentId` ist die zugehörige OpenClaw-Agent-ID.
- Discord-Kanal oder -Thread: `match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
- Telegram-Forenthema: `match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
- BlueBubbles-DM/Gruppenchat: `match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
Für stabile Gruppenbindungen `chat_id:*` oder `chat_identifier:*` bevorzugen.
- iMessage-DM/Gruppenchat: `match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
Für stabile Gruppenbindungen `chat_id:*` bevorzugen.
- `bindings[].agentId` ist die ID des besitzenden OpenClaw-Agenten.
- Optionale ACP-Überschreibungen befinden sich unter `bindings[].acp`:
- `mode` (`persistent` oder `oneshot`)
- `label`
- `cwd`
- `backend`
### Laufzeit-Standards pro Agent
### Laufzeitstandards pro Agent
Verwenden Sie `agents.list[].runtime`, um ACP-Standards einmal pro Agent zu definieren:
@ -235,7 +235,7 @@ Verwenden Sie `agents.list[].runtime`, um ACP-Standards einmal pro Agent zu defi
- `agents.list[].runtime.acp.mode`
- `agents.list[].runtime.acp.cwd`
Priorität von Überschreibungen für gebundene ACP-Sitzungen:
Reihenfolge der Überschreibung für ACP-gebundene Sitzungen:
1. `bindings[].acp.*`
2. `agents.list[].runtime.acp.*`
@ -323,16 +323,16 @@ Beispiel:
Verhalten:
- OpenClaw stellt vor der Verwendung sicher, dass die konfigurierte ACP-Sitzung existiert.
- Nachrichten in diesem Channel oder Thema werden an die konfigurierte ACP-Sitzung weitergeleitet.
- OpenClaw stellt sicher, dass die konfigurierte ACP-Sitzung vor der Verwendung existiert.
- Nachrichten in diesem Kanal oder Thema werden an die konfigurierte ACP-Sitzung weitergeleitet.
- In gebundenen Konversationen setzen `/new` und `/reset` denselben ACP-Sitzungsschlüssel an Ort und Stelle zurück.
- Temporäre Laufzeit-Bindungen (zum Beispiel erstellt durch Thread-Focus-Abläufe) gelten weiterhin, sofern vorhanden.
- Bei agentübergreifenden ACP-Spawns ohne explizites `cwd` übernimmt OpenClaw den Workspace des Ziel-Agenten aus der Agent-Konfiguration.
- Fehlende übernommene Workspace-Pfade fallen auf das Standard-`cwd` des Backends zurück; echte Zugriffsfehler bei vorhandenen Pfaden werden als Spawn-Fehler ausgegeben.
- Temporäre Laufzeitbindungen (zum Beispiel durch Thread-Focus-Abläufe erstellt) gelten weiterhin, sofern vorhanden.
- Bei agentenübergreifenden ACP-Starts ohne explizites `cwd` übernimmt OpenClaw den Arbeitsbereich des Ziel-Agenten aus der Agentenkonfiguration.
- Fehlende übernommene Arbeitsbereichspfade fallen auf das Standard-`cwd` des Backends zurück; Zugriffsfehler bei vorhandenen Pfaden werden als Spawn-Fehler ausgegeben.
## ACP-Sitzungen starten (Schnittstellen)
### Über `sessions_spawn`
### Aus `sessions_spawn`
Verwenden Sie `runtime: "acp"`, um eine ACP-Sitzung aus einem Agent-Turn oder Tool-Aufruf zu starten.
@ -348,29 +348,29 @@ Verwenden Sie `runtime: "acp"`, um eine ACP-Sitzung aus einem Agent-Turn oder To
Hinweise:
- `runtime` hat standardmäßig den Wert `subagent`, setzen Sie also für ACP-Sitzungen explizit `runtime: "acp"`.
- Wenn `agentId` weggelassen wird, verwendet OpenClaw `acp.defaultAgent`, sofern konfiguriert.
- `runtime` ist standardmäßig `subagent`, setzen Sie also `runtime: "acp"` explizit für ACP-Sitzungen.
- Wenn `agentId` ausgelassen wird, verwendet OpenClaw `acp.defaultAgent`, falls konfiguriert.
- `mode: "session"` erfordert `thread: true`, um eine persistente gebundene Konversation beizubehalten.
Schnittstellendetails:
Details zur Schnittstelle:
- `task` (erforderlich): initialer Prompt, der an die ACP-Sitzung gesendet wird.
- `runtime` (erforderlich für ACP): muss `"acp"` sein.
- `agentId` (optional): ACP-Ziel-Harness-ID. Fällt auf `acp.defaultAgent` zurück, wenn gesetzt.
- `thread` (optional, Standard `false`): Thread-Binding-Ablauf anfordern, wo unterstützt.
- `mode` (optional): `run` (einmalig) oder `session` (persistent).
- `task` (erforderlich): anfänglicher Prompt, der an die ACP-Sitzung gesendet wird.
- `runtime` (für ACP erforderlich): muss `"acp"` sein.
- `agentId` (optional): ACP-Ziel-Harness-ID. Fällt auf `acp.defaultAgent` zurück, falls gesetzt.
- `thread` (optional, Standard `false`): fordert einen Thread-Bindungsablauf an, sofern unterstützt.
- `mode` (optional): `run` (One-Shot) oder `session` (persistent).
- Standard ist `run`
- wenn `thread: true` und `mode` weggelassen wird, kann OpenClaw je nach Laufzeitpfad standardmäßig persistentes Verhalten wählen
- wenn `thread: true` und `mode` ausgelassen werden, kann OpenClaw je nach Laufzeitpfad standardmäßig persistentes Verhalten wählen
- `mode: "session"` erfordert `thread: true`
- `cwd` (optional): angefordertes Laufzeit-Arbeitsverzeichnis (validiert durch Backend-/Laufzeitrichtlinie). Wenn weggelassen, übernimmt ACP-Spawn bei entsprechender Konfiguration den Workspace des Ziel-Agenten; fehlende übernommene Pfade fallen auf Backend-Standards zurück, während echte Zugriffsfehler zurückgegeben werden.
- `label` (optional): für Operatoren sichtbares Label, das im Sitzungs-/Bannertext verwendet wird.
- `resumeSessionId` (optional): eine vorhandene ACP-Sitzung fortsetzen, statt eine neue zu erstellen. Der Agent spielt den Konversationsverlauf über `session/load` erneut ab. Erfordert `runtime: "acp"`.
- `streamTo` (optional): `"parent"` streamt Zusammenfassungen des Fortschritts des initialen ACP-Laufs als Systemereignisse zurück an die anfordernde Sitzung.
- Wenn verfügbar, enthalten akzeptierte Antworten `streamLogPath`, das auf ein JSONL-Log pro Sitzung verweist (`<sessionId>.acp-stream.jsonl`), das Sie für den vollständigen Relay-Verlauf mitlesen können.
- `cwd` (optional): angefordertes Laufzeit-Arbeitsverzeichnis (validiert durch Backend-/Laufzeitrichtlinie). Wenn ausgelassen, übernimmt ACP-Spawn den Arbeitsbereich des Ziel-Agenten, sofern konfiguriert; fehlende übernommene Pfade fallen auf Backend-Standards zurück, während echte Zugriffsfehler zurückgegeben werden.
- `label` (optional): für Operatoren sichtbares Label, das in Sitzungs-/Banner-Text verwendet wird.
- `resumeSessionId` (optional): setzt eine bestehende ACP-Sitzung fort, anstatt eine neue zu erstellen. Der Agent spielt seinen Gesprächsverlauf über `session/load` erneut ein. Erfordert `runtime: "acp"`.
- `streamTo` (optional): `"parent"` streamt Fortschrittszusammenfassungen des anfänglichen ACP-Laufs als Systemereignisse zurück an die anfordernde Sitzung.
- Wenn verfügbar, enthalten akzeptierte Antworten `streamLogPath`, das auf ein sitzungsbezogenes JSONL-Log (`<sessionId>.acp-stream.jsonl`) zeigt, das Sie für den vollständigen Relay-Verlauf beobachten können.
### Eine vorhandene Sitzung fortsetzen
### Eine bestehende Sitzung fortsetzen
Verwenden Sie `resumeSessionId`, um eine frühere ACP-Sitzung fortzusetzen, statt neu zu starten. Der Agent spielt den Konversationsverlauf über `session/load` erneut ab, sodass er mit dem vollständigen Kontext des Vorherigen fortsetzt.
Verwenden Sie `resumeSessionId`, um eine frühere ACP-Sitzung fortzusetzen, statt neu zu starten. Der Agent spielt seinen Gesprächsverlauf über `session/load` erneut ein, sodass er mit dem vollständigen Kontext dessen fortfährt, was zuvor geschehen ist.
```json
{
@ -384,34 +384,34 @@ Verwenden Sie `resumeSessionId`, um eine frühere ACP-Sitzung fortzusetzen, stat
Häufige Anwendungsfälle:
- Eine Codex-Sitzung vom Laptop auf das Telefon übergeben — weisen Sie Ihren Agenten an, dort weiterzumachen, wo Sie aufgehört haben
- Eine Coding-Sitzung fortsetzen, die Sie interaktiv in der CLI begonnen haben, jetzt headless über Ihren Agenten
- Arbeit fortsetzen, die durch einen Gateway-Neustart oder ein Idle-Timeout unterbrochen wurde
- Eine Coding-Sitzung fortsetzen, die Sie interaktiv in der CLI begonnen haben und jetzt headless über Ihren Agenten weiterführen
- Arbeit wieder aufnehmen, die durch einen Gateway-Neustart oder ein Leerlauf-Timeout unterbrochen wurde
Hinweise:
- `resumeSessionId` erfordert `runtime: "acp"` — gibt einen Fehler zurück, wenn es mit der Subagent-Laufzeit verwendet wird.
- `resumeSessionId` stellt den vorgelagerten ACP-Konversationsverlauf wieder her; `thread` und `mode` gelten weiterhin normal für die neue OpenClaw-Sitzung, die Sie erstellen, daher erfordert `mode: "session"` weiterhin `thread: true`.
- `resumeSessionId` erfordert `runtime: "acp"` — gibt einen Fehler zurück, wenn es mit der Sub-Agent-Laufzeit verwendet wird.
- `resumeSessionId` stellt den vorgelagerten ACP-Gesprächsverlauf wieder her; `thread` und `mode` gelten weiterhin normal für die neue OpenClaw-Sitzung, die Sie erstellen, daher erfordert `mode: "session"` weiterhin `thread: true`.
- Der Ziel-Agent muss `session/load` unterstützen (Codex und Claude Code tun das).
- Wenn die Sitzungs-ID nicht gefunden wird, schlägt der Spawn mit einem klaren Fehler fehl — kein stiller Fallback auf eine neue Sitzung.
- Wenn die Sitzungs-ID nicht gefunden wird, schlägt der Spawn mit einem klaren Fehler fehl — kein stilles Zurückfallen auf eine neue Sitzung.
### Operator-Smoketest
### Operator-Smoke-Test
Verwenden Sie dies nach einem Gateway-Deploy, wenn Sie schnell live prüfen möchten, dass ACP-Spawn
wirklich Ende-zu-Ende funktioniert und nicht nur Unit-Tests besteht.
Verwenden Sie dies nach einem Gateway-Deployment, wenn Sie eine schnelle Live-Prüfung möchten, dass ACP-Spawn
tatsächlich Ende-zu-Ende funktioniert und nicht nur Unit-Tests besteht.
Empfohlenes Gate:
1. Prüfen Sie die bereitgestellte Gateway-Version/den Commit auf dem Ziel-Host.
2. Bestätigen Sie, dass der bereitgestellte Quellcode die ACP-Lineage-Akzeptanz in
1. Überprüfen Sie die deployte Gateway-Version/den Commit auf dem Ziel-Host.
2. Bestätigen Sie, dass der deployte Quellcode die ACP-Lineage-Akzeptanz in
`src/gateway/sessions-patch.ts` enthält (`subagent:* or acp:* sessions`).
3. Öffnen Sie eine temporäre ACPX-Bridge-Sitzung zu einem Live-Agenten (zum Beispiel
`razor(main)` auf `jpclawhq`).
4. Bitten Sie diesen Agenten, `sessions_spawn` mit Folgendem aufzurufen:
4. Bitten Sie diesen Agenten, `sessions_spawn` aufzurufen mit:
- `runtime: "acp"`
- `agentId: "codex"`
- `mode: "run"`
- Aufgabe: `Reply with exactly LIVE-ACP-SPAWN-OK`
5. Verifizieren Sie, dass der Agent Folgendes meldet:
- task: `Reply with exactly LIVE-ACP-SPAWN-OK`
5. Verifizieren Sie, dass der Agent meldet:
- `accepted=yes`
- einen echten `childSessionKey`
- keinen Validator-Fehler
@ -427,11 +427,11 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
Hinweise:
- Halten Sie diesen Smoketest bei `mode: "run"`, es sei denn, Sie testen absichtlich
persistente threadgebundene ACP-Sitzungen.
- Halten Sie diesen Smoke-Test bei `mode: "run"`, sofern Sie nicht absichtlich
persistente threadgebundene ACP-Sitzungen testen.
- Verlangen Sie für das grundlegende Gate nicht `streamTo: "parent"`. Dieser Pfad hängt von
den Fähigkeiten des Anforderers/der Sitzung ab und ist eine separate Integrationsprüfung.
- Behandeln Sie Tests mit threadgebundenem `mode: "session"` als zweiten, umfangreicheren Integrationsdurchlauf
den Fähigkeiten der anfordernden Sitzung/des Requesters ab und ist eine separate Integrationsprüfung.
- Behandeln Sie threadgebundenes Testen mit `mode: "session"` als zweiten, umfassenderen Integrationsdurchlauf
aus einem echten Discord-Thread oder Telegram-Thema.
## Sandbox-Kompatibilität
@ -440,16 +440,16 @@ ACP-Sitzungen laufen derzeit auf der Host-Laufzeit, nicht innerhalb der OpenClaw
Aktuelle Einschränkungen:
- Wenn die anfordernde Sitzung sandboxed ist, werden ACP-Spawns sowohl für `sessions_spawn({ runtime: "acp" })` als auch für `/acp spawn` blockiert.
- Wenn die anfordernde Sitzung in einer Sandbox läuft, werden ACP-Spawns sowohl für `sessions_spawn({ runtime: "acp" })` als auch für `/acp spawn` blockiert.
- Fehler: `Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.`
- `sessions_spawn` mit `runtime: "acp"` unterstützt `sandbox: "require"` nicht.
- Fehler: `sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".`
Verwenden Sie `runtime: "subagent"`, wenn Sie eine durch die Sandbox erzwungene Ausführung benötigen.
### Über den Befehl `/acp`
### Aus dem Befehl `/acp`
Verwenden Sie `/acp spawn` bei Bedarf für explizite Operator-Steuerung aus dem Chat.
Verwenden Sie `/acp spawn` für explizite Operator-Steuerung aus dem Chat, wenn nötig.
```text
/acp spawn codex --mode persistent --thread auto
@ -470,35 +470,35 @@ Siehe [Slash Commands](/de/tools/slash-commands).
## Auflösung von Sitzungszielen
Die meisten `/acp`-Aktionen akzeptieren optional ein Sitzungsziel (`session-key`, `session-id` oder `session-label`).
Die meisten `/acp`-Aktionen akzeptieren ein optionales Sitzungsziel (`session-key`, `session-id` oder `session-label`).
Auflösungsreihenfolge:
Reihenfolge der Auflösung:
1. Explizites Zielargument (oder `--session` für `/acp steer`)
- versucht zuerst den Schlüssel
- dann die UUID-förmige Sitzungs-ID
- dann eine UUID-förmige Sitzungs-ID
- dann das Label
2. Aktuelle Thread-Bindung (wenn diese Konversation/dieser Thread an eine ACP-Sitzung gebunden ist)
3. Fallback auf die aktuelle Anforderer-Sitzung
3. Fallback auf die aktuelle anfordernde Sitzung
Bindungen an die aktuelle Konversation und Thread-Bindungen nehmen beide an Schritt 2 teil.
Wenn kein Ziel aufgelöst werden kann, gibt OpenClaw einen klaren Fehler zurück (`Unable to resolve session target: ...`).
## Spawn-Bind-Modi
## Spawn-Bindungsmodi
`/acp spawn` unterstützt `--bind here|off`.
| Modus | Verhalten |
| ------ | ------------------------------------------------------------------------ |
| `here` | Die aktuelle aktive Konversation an Ort und Stelle binden; fehlschlagen, wenn keine aktiv ist. |
| `off` | Keine Bindung an die aktuelle Konversation erstellen. |
| Modus | Verhalten |
| ------ | ---------------------------------------------------------------------- |
| `here` | Bindet die aktuell aktive Konversation an Ort und Stelle; schlägt fehl, wenn keine aktiv ist. |
| `off` | Erstellt keine Bindung an die aktuelle Konversation. |
Hinweise:
- `--bind here` ist der einfachste Operator-Pfad für „diesen Channel oder Chat mit Codex hinterlegen“.
- `--bind here` ist der einfachste Operator-Pfad für „diesen Kanal oder Chat mit Codex hinterlegen“.
- `--bind here` erstellt keinen untergeordneten Thread.
- `--bind here` ist nur auf Channels verfügbar, die Unterstützung für die Bindung an die aktuelle Konversation bereitstellen.
- `--bind here` ist nur auf Kanälen verfügbar, die die Bindung an die aktuelle Konversation unterstützen.
- `--bind` und `--thread` können nicht im selben `/acp spawn`-Aufruf kombiniert werden.
## Spawn-Thread-Modi
@ -507,14 +507,14 @@ Hinweise:
| Modus | Verhalten |
| ------ | ---------------------------------------------------------------------------------------------------- |
| `auto` | In einem aktiven Thread: diesen Thread binden. Außerhalb eines Threads: einen untergeordneten Thread erstellen/binden, wenn unterstützt. |
| `here` | Aktiven aktuellen Thread verlangen; fehlschlagen, wenn Sie sich nicht in einem Thread befinden. |
| `auto` | In einem aktiven Thread: bindet diesen Thread. Außerhalb eines Threads: erstellt/bindet einen untergeordneten Thread, wenn unterstützt. |
| `here` | Erfordert einen aktuell aktiven Thread; schlägt fehl, wenn keiner aktiv ist. |
| `off` | Keine Bindung. Die Sitzung startet ungebunden. |
Hinweise:
- Auf Oberflächen ohne Thread-Binding ist das Standardverhalten effektiv `off`.
- Thread-gebundener Spawn erfordert Unterstützung durch die Channel-Richtlinie:
- Auf Oberflächen ohne Thread-Bindung ist das Standardverhalten effektiv `off`.
- Thread-gebundener Spawn erfordert Unterstützung durch die Kanalrichtlinie:
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
- Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true`
- Verwenden Sie `--bind here`, wenn Sie die aktuelle Konversation anheften möchten, ohne einen untergeordneten Thread zu erstellen.
@ -539,49 +539,49 @@ Verfügbare Befehlsfamilie:
- `/acp doctor`
- `/acp install`
`/acp status` zeigt die effektiven Laufzeitoptionen und, wenn verfügbar, sowohl Sitzungskennungen auf Laufzeit- als auch auf Backend-Ebene.
`/acp status` zeigt die effektiven Laufzeitoptionen und, sofern verfügbar, sowohl Kennungen auf Laufzeitebene als auch auf Backend-Ebene an.
Einige Steuerungen hängen von den Fähigkeiten des Backends ab. Wenn ein Backend eine Steuerung nicht unterstützt, gibt OpenClaw einen klaren Fehler für nicht unterstützte Steuerung zurück.
## ACP-Befehls-Kochbuch
| Command | What it does | Example |
| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- |
| `/acp spawn` | ACP-Sitzung erstellen; optionale Bindung an aktuelle Konversation oder Thread. | `/acp spawn codex --bind here --cwd /repo` |
| `/acp cancel` | Laufenden Turn für die Zielsitzung abbrechen. | `/acp cancel agent:codex:acp:<uuid>` |
| `/acp steer` | Steueranweisung an laufende Sitzung senden. | `/acp steer --session support inbox prioritize failing tests` |
| `/acp close` | Sitzung schließen und Thread-Ziele entbinden. | `/acp close` |
| `/acp status` | Backend, Modus, Status, Laufzeitoptionen, Fähigkeiten anzeigen. | `/acp status` |
| `/acp set-mode` | Laufzeitmodus für die Zielsitzung setzen. | `/acp set-mode plan` |
| `/acp set` | Generisches Schreiben einer Laufzeit-Konfigurationsoption. | `/acp set model openai/gpt-5.4` |
| `/acp cwd` | Überschreibung für das Laufzeit-Arbeitsverzeichnis setzen. | `/acp cwd /Users/user/Projects/repo` |
| `/acp permissions` | Profil der Genehmigungsrichtlinie setzen. | `/acp permissions strict` |
| `/acp timeout` | Laufzeit-Timeout (Sekunden) setzen. | `/acp timeout 120` |
| `/acp model` | Überschreibung des Laufzeitmodells setzen. | `/acp model anthropic/claude-opus-4-6` |
| `/acp reset-options` | Überschreibungen der Sitzungs-Laufzeitoptionen entfernen. | `/acp reset-options` |
| `/acp sessions` | Aktuelle ACP-Sitzungen aus dem Store auflisten. | `/acp sessions` |
| `/acp doctor` | Backend-Zustand, Fähigkeiten, umsetzbare Behebungen. | `/acp doctor` |
| `/acp install` | Deterministische Installations- und Aktivierungsschritte ausgeben. | `/acp install` |
| Befehl | Funktion | Beispiel |
| ------------------- | ---------------------------------------------------------- | ------------------------------------------------------------- |
| `/acp spawn` | ACP-Sitzung erstellen; optionale aktuelle Bindung oder Thread-Bindung. | `/acp spawn codex --bind here --cwd /repo` |
| `/acp cancel` | Laufenden Turn für die Zielsitzung abbrechen. | `/acp cancel agent:codex:acp:<uuid>` |
| `/acp steer` | Steueranweisung an eine laufende Sitzung senden. | `/acp steer --session support inbox prioritize failing tests` |
| `/acp close` | Sitzung schließen und Thread-Ziele entbinden. | `/acp close` |
| `/acp status` | Backend, Modus, Zustand, Laufzeitoptionen und Fähigkeiten anzeigen. | `/acp status` |
| `/acp set-mode` | Laufzeitmodus für die Zielsitzung festlegen. | `/acp set-mode plan` |
| `/acp set` | Generischen Laufzeit-Konfigurationswert schreiben. | `/acp set model openai/gpt-5.4` |
| `/acp cwd` | Überschreibung des Laufzeit-Arbeitsverzeichnisses setzen. | `/acp cwd /Users/user/Projects/repo` |
| `/acp permissions` | Profil für die Genehmigungsrichtlinie festlegen. | `/acp permissions strict` |
| `/acp timeout` | Laufzeit-Timeout (Sekunden) festlegen. | `/acp timeout 120` |
| `/acp model` | Überschreibung des Laufzeitmodells festlegen. | `/acp model anthropic/claude-opus-4-6` |
| `/acp reset-options`| Überschreibungen der Sitzungs-Laufzeitoptionen entfernen. | `/acp reset-options` |
| `/acp sessions` | Kürzlich verwendete ACP-Sitzungen aus dem Store auflisten. | `/acp sessions` |
| `/acp doctor` | Backend-Gesundheit, Fähigkeiten, umsetzbare Korrekturen. | `/acp doctor` |
| `/acp install` | Deterministische Installations- und Aktivierungsschritte ausgeben. | `/acp install` |
`/acp sessions` liest den Store für die aktuell gebundene Sitzung oder die Sitzung des Anforderers. Befehle, die `session-key`-, `session-id`- oder `session-label`-Token akzeptieren, lösen Ziele über die Gateway-Sitzungserkennung auf, einschließlich benutzerdefinierter `session.store`-Wurzeln pro Agent.
`/acp sessions` liest den Store für die aktuelle gebundene oder anfordernde Sitzung. Befehle, die Tokens vom Typ `session-key`, `session-id` oder `session-label` akzeptieren, lösen Ziele über die Gateway-Sitzungserkennung auf, einschließlich benutzerdefinierter `session.store`-Wurzeln pro Agent.
## Zuordnung von Laufzeitoptionen
## Abbildung von Laufzeitoptionen
`/acp` hat Komfortbefehle und einen generischen Setter.
Äquivalente Operationen:
- `/acp model <id>` wird dem Laufzeit-Konfigurationsschlüssel `model` zugeordnet.
- `/acp permissions <profile>` wird dem Laufzeit-Konfigurationsschlüssel `approval_policy` zugeordnet.
- `/acp timeout <seconds>` wird dem Laufzeit-Konfigurationsschlüssel `timeout` zugeordnet.
- `/acp cwd <path>` aktualisiert die Überschreibung des Laufzeit-`cwd` direkt.
- `/acp model <id>` wird auf den Laufzeit-Konfigurationsschlüssel `model` abgebildet.
- `/acp permissions <profile>` wird auf den Laufzeit-Konfigurationsschlüssel `approval_policy` abgebildet.
- `/acp timeout <seconds>` wird auf den Laufzeit-Konfigurationsschlüssel `timeout` abgebildet.
- `/acp cwd <path>` aktualisiert direkt die Überschreibung des Laufzeit-`cwd`.
- `/acp set <key> <value>` ist der generische Pfad.
- Spezialfall: `key=cwd` verwendet den Pfad für die `cwd`-Überschreibung.
- `/acp reset-options` löscht alle Laufzeit-Überschreibungen für die Zielsitzung.
- Sonderfall: `key=cwd` verwendet den Pfad für die `cwd`-Überschreibung.
- `/acp reset-options` löscht alle Laufzeitüberschreibungen für die Zielsitzung.
## Unterstützung für acpx-Harnesses (aktuell)
## acpx-Harness-Unterstützung (aktuell)
Aktuelle eingebaute acpx-Harness-Aliasse:
Aktuelle integrierte acpx-Harness-Aliasse:
- `claude`
- `codex`
@ -599,19 +599,19 @@ Aktuelle eingebaute acpx-Harness-Aliasse:
- `qwen`
Wenn OpenClaw das acpx-Backend verwendet, bevorzugen Sie diese Werte für `agentId`, sofern Ihre acpx-Konfiguration keine benutzerdefinierten Agent-Aliasse definiert.
Wenn Ihre lokale Cursor-Installation ACP weiterhin als `agent acp` bereitstellt, überschreiben Sie den Befehl des `cursor`-Agenten in Ihrer acpx-Konfiguration, statt den eingebauten Standard zu ändern.
Wenn Ihre lokale Cursor-Installation ACP weiterhin als `agent acp` bereitstellt, überschreiben Sie stattdessen den Agent-Befehl `cursor` in Ihrer acpx-Konfiguration, anstatt den integrierten Standard zu ändern.
Die direkte Verwendung der acpx-CLI kann auch beliebige Adapter über `--agent <command>` ansteuern, aber dieser rohe Escape Hatch ist eine Funktion der acpx-CLI (nicht der normale OpenClaw-`agentId`-Pfad).
Die direkte Verwendung der acpx-CLI kann über `--agent <command>` auch beliebige Adapter ansprechen, aber dieser rohe Escape-Hatch ist eine acpx-CLI-Funktion (nicht der normale OpenClaw-`agentId`-Pfad).
## Erforderliche Konfiguration
Core-ACP-Baseline:
ACP-Basis in Core:
```json5
{
acp: {
enabled: true,
// Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls.
// Optional. Standard ist true; auf false setzen, um ACP-Dispatch zu pausieren und /acp-Steuerungen beizubehalten.
dispatch: { enabled: true },
backend: "acpx",
defaultAgent: "codex",
@ -643,7 +643,7 @@ Core-ACP-Baseline:
}
```
Die Konfiguration von Thread-Bindings ist channelspezifisch. Beispiel für Discord:
Die Thread-Bindungskonfiguration ist kanadapter-spezifisch. Beispiel für Discord:
```json5
{
@ -669,14 +669,14 @@ Wenn threadgebundener ACP-Spawn nicht funktioniert, prüfen Sie zuerst das Featu
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
Bindungen an die aktuelle Konversation erfordern keine Erstellung eines untergeordneten Threads. Sie erfordern einen aktiven Konversationskontext und einen Channel-Adapter, der ACP-Konversationsbindungen bereitstellt.
Bindungen an die aktuelle Konversation erfordern keine Erstellung eines untergeordneten Threads. Sie erfordern einen aktiven Konversationskontext und einen Kanaladapter, der ACP-Konversationsbindungen bereitstellt.
Siehe [Configuration Reference](/de/gateway/configuration-reference).
Siehe [Konfigurationsreferenz](/de/gateway/configuration-reference).
## Plugin-Setup für das acpx-Backend
## Plugin-Einrichtung für das acpx-Backend
Frische Installationen werden standardmäßig mit aktiviertem gebündeltem `acpx`-Laufzeit-Plugin ausgeliefert, daher funktioniert ACP
normalerweise ohne einen manuellen Schritt zur Plugin-Installation.
Frische Installationen werden standardmäßig mit aktiviertem gebündelten `acpx`-Laufzeit-Plugin ausgeliefert, daher
funktioniert ACP normalerweise ohne einen manuellen Plugin-Installationsschritt.
Beginnen Sie mit:
@ -684,7 +684,7 @@ Beginnen Sie mit:
/acp doctor
```
Wenn Sie `acpx` deaktiviert haben, es über `plugins.allow` / `plugins.deny` verweigert haben oder
Wenn Sie `acpx` deaktiviert, es über `plugins.allow` / `plugins.deny` verweigert oder
zu einem lokalen Entwicklungs-Checkout wechseln möchten, verwenden Sie den expliziten Plugin-Pfad:
```bash
@ -698,20 +698,20 @@ Lokale Workspace-Installation während der Entwicklung:
openclaw plugins install ./path/to/local/acpx-plugin
```
Prüfen Sie dann den Zustand des Backends:
Prüfen Sie dann die Backend-Gesundheit:
```text
/acp doctor
```
### Konfiguration von acpx-Befehl und -Version
### Konfiguration von acpx-Befehl und Version
Standardmäßig verwendet das gebündelte acpx-Backend-Plugin (`acpx`) die pluginlokal angeheftete Binärdatei:
1. Der Befehl ist standardmäßig die pluginlokale `node_modules/.bin/acpx` innerhalb des ACPX-Plugin-Pakets.
2. Die erwartete Version ist standardmäßig an die Extension-Pin gebunden.
2. Die erwartete Version ist standardmäßig die Anheftung der Extension.
3. Beim Start wird das ACP-Backend sofort als nicht bereit registriert.
4. Ein Hintergrund-Ensure-Job prüft `acpx --version`.
4. Ein Ensure-Job im Hintergrund prüft `acpx --version`.
5. Wenn die pluginlokale Binärdatei fehlt oder nicht übereinstimmt, wird Folgendes ausgeführt:
`npm install --omit=dev --no-save acpx@<pinned>` und anschließend erneut geprüft.
@ -736,120 +736,133 @@ Sie können Befehl/Version in der Plugin-Konfiguration überschreiben:
Hinweise:
- `command` akzeptiert einen absoluten Pfad, relativen Pfad oder Befehlsnamen (`acpx`).
- Relative Pfade werden ausgehend vom OpenClaw-Workspace-Verzeichnis aufgelöst.
- `expectedVersion: "any"` deaktiviert die strikte Versionsprüfung.
- Relative Pfade werden vom OpenClaw-Workspace-Verzeichnis aus aufgelöst.
- `expectedVersion: "any"` deaktiviert strikte Versionsprüfung.
- Wenn `command` auf eine benutzerdefinierte Binärdatei/einen benutzerdefinierten Pfad zeigt, wird die pluginlokale Auto-Installation deaktiviert.
- Der OpenClaw-Start bleibt nicht blockierend, während die Zustandsprüfung des Backends läuft.
- Der OpenClaw-Start bleibt nicht blockierend, während die Backend-Gesundheitsprüfung läuft.
Siehe [Plugins](/de/tools/plugin).
### Automatische Abhängigkeitsinstallation
Wenn Sie OpenClaw global mit `npm install -g openclaw` installieren, werden die acpx-
Laufzeitabhängigkeiten (plattformspezifische Binärdateien) automatisch über einen Postinstall-Hook installiert. Wenn die automatische Installation fehlschlägt, startet das Gateway trotzdem
Laufzeitabhängigkeiten (plattformspezifische Binärdateien) automatisch
über einen Postinstall-Hook installiert. Falls die automatische Installation fehlschlägt, startet das Gateway dennoch
normal und meldet die fehlende Abhängigkeit über `openclaw acp doctor`.
### Plugin-Tools-MCP-Bridge
### MCP-Bridge für Plugin-Tools
Standardmäßig stellen ACPX-Sitzungen **keine** von OpenClaw-Plugins registrierten Tools für
das ACP-Harness bereit.
Wenn Sie möchten, dass ACP-Agenten wie Codex oder Claude Code installierte
OpenClaw-Plugin-Tools wie Memory recall/store aufrufen können, aktivieren Sie die dedizierte Bridge:
OpenClaw-Plugin-Tools wie Memory Recall/Store aufrufen können, aktivieren Sie die dedizierte Bridge:
```bash
openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
```
Das bewirkt Folgendes:
Was dies bewirkt:
- Es injiziert einen eingebauten MCP-Server namens `openclaw-plugin-tools` in den ACPX-Sitzungs-
- Injiziert einen integrierten MCP-Server namens `openclaw-plugin-tools` in den ACPX-Sitzungs-
Bootstrap.
- Es stellt Plugin-Tools bereit, die bereits von installierten und aktivierten OpenClaw-
- Stellt Plugin-Tools bereit, die bereits von installierten und aktivierten OpenClaw-
Plugins registriert wurden.
- Das Feature bleibt explizit und standardmäßig deaktiviert.
- Hält die Funktion explizit und standardmäßig deaktiviert.
Sicherheits- und Vertrauenshinweise:
- Dadurch wird die Tool-Oberfläche des ACP-Harnesses erweitert.
- ACP-Agenten erhalten nur Zugriff auf Plugin-Tools, die bereits im Gateway aktiv sind.
- Behandeln Sie dies als dieselbe Vertrauensgrenze, wie diesen Plugins die Ausführung in
OpenClaw selbst zu erlauben.
- Prüfen Sie installierte Plugins, bevor Sie es aktivieren.
- Dies erweitert die Tool-Oberfläche des ACP-Harnesses.
- ACP-Agenten erhalten nur Zugriff auf Plugin-Tools, die im Gateway bereits aktiv sind.
- Betrachten Sie dies als dieselbe Vertrauensgrenze wie das Ausführen dieser Plugins
in OpenClaw selbst.
- Prüfen Sie installierte Plugins, bevor Sie dies aktivieren.
Benutzerdefinierte `mcpServers` funktionieren weiterhin wie bisher. Die eingebaute
Plugin-Tools-Bridge ist eine zusätzliche optionale Bequemlichkeit und kein Ersatz für generische MCP-Server-Konfiguration.
Benutzerdefinierte `mcpServers` funktionieren weiterhin wie bisher. Die integrierte Plugin-Tools-Bridge ist
eine zusätzliche optionale Komfortfunktion, kein Ersatz für generische MCP-Server-Konfiguration.
### Konfiguration des Laufzeit-Timeouts
Das gebündelte `acpx`-Plugin setzt standardmäßig für eingebettete Laufzeit-Turns ein
Timeout von 120 Sekunden. Das gibt langsameren Harnesses wie Gemini CLI genug Zeit, den
ACP-Start und die Initialisierung abzuschließen. Überschreiben Sie dies, wenn Ihr Host ein anderes
Das gebündelte `acpx`-Plugin setzt für eingebettete Laufzeit-Turns standardmäßig ein
Timeout von 120 Sekunden. Das gibt langsameren Harnesses wie Gemini CLI genügend Zeit, um
ACP-Start und Initialisierung abzuschließen. Überschreiben Sie dies, wenn Ihr Host ein anderes
Laufzeitlimit benötigt:
```bash
openclaw config set plugins.entries.acpx.config.timeoutSeconds 180
```
Starten Sie das Gateway nach dem Ändern dieses Werts neu.
Starten Sie das Gateway neu, nachdem Sie diesen Wert geändert haben.
## Konfiguration von Berechtigungen
### Konfiguration des Agents für Health-Probes
ACP-Sitzungen laufen nicht interaktiv — es gibt kein TTY, um Berechtigungsabfragen für Dateischreib- und Shell-Exec-Vorgänge zu bestätigen oder abzulehnen. Das acpx-Plugin stellt zwei Konfigurationsschlüssel bereit, die steuern, wie Berechtigungen behandelt werden:
Das gebündelte `acpx`-Plugin prüft ein Harness-Agent, während es entscheidet, ob das
eingebettete Laufzeit-Backend bereit ist. Standard ist `codex`. Wenn Ihr Deployment
einen anderen Standard-ACP-Agenten verwendet, setzen Sie den Probe-Agenten auf dieselbe ID:
Diese ACPX-Harness-Berechtigungen sind getrennt von OpenClaw-Exec-Genehmigungen und getrennt von CLI-Backend-Vendor-Bypass-Flags wie Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` ist der Break-Glass-Schalter auf Harness-Ebene für ACP-Sitzungen.
```bash
openclaw config set plugins.entries.acpx.config.probeAgent claude
```
Starten Sie das Gateway neu, nachdem Sie diesen Wert geändert haben.
## Berechtigungskonfiguration
ACP-Sitzungen laufen nicht interaktiv — es gibt kein TTY, um Aufforderungen zur Genehmigung oder Ablehnung von Schreibzugriffen auf Dateien und Shell-Ausführung zu bestätigen. Das acpx-Plugin stellt zwei Konfigurationsschlüssel bereit, die steuern, wie Berechtigungen behandelt werden:
Diese ACPX-Harness-Berechtigungen sind getrennt von OpenClaw-Exec-Genehmigungen und getrennt von Vendor-Bypass-Flags der CLI-Backends wie Claude-CLI `--permission-mode bypassPermissions`. ACPX `approve-all` ist der Harness-seitige Break-Glass-Schalter für ACP-Sitzungen.
### `permissionMode`
Steuert, welche Operationen der Harness-Agent ohne Rückfrage ausführen kann.
Steuert, welche Operationen der Harness-Agent ohne Aufforderung ausführen kann.
| Wert | Verhalten |
| Wert | Verhalten |
| ---------------- | -------------------------------------------------------- |
| `approve-all` | Alle Dateischreib- und Shell-Befehle automatisch genehmigen. |
| `approve-reads` | Nur Lesevorgänge automatisch genehmigen; Schreibvorgänge und Exec erfordern Prompts. |
| `deny-all` | Alle Berechtigungsabfragen ablehnen. |
| `approve-all` | Alle Dateischreibvorgänge und Shell-Befehle automatisch genehmigen. |
| `approve-reads` | Nur Lesevorgänge automatisch genehmigen; Schreibvorgänge und Ausführung erfordern Aufforderungen. |
| `deny-all` | Alle Berechtigungsaufforderungen ablehnen. |
### `nonInteractivePermissions`
Steuert, was passiert, wenn eine Berechtigungsabfrage angezeigt würde, aber kein interaktives TTY verfügbar ist (was bei ACP-Sitzungen immer der Fall ist).
Steuert, was passiert, wenn eine Berechtigungsaufforderung angezeigt würde, aber kein interaktives TTY verfügbar ist (was bei ACP-Sitzungen immer der Fall ist).
| Wert | Verhalten |
| ------ | ---------------------------------------------------------------- |
| `fail` | Sitzung mit `AcpRuntimeError` abbrechen. **(Standard)** |
| `deny` | Die Berechtigung stillschweigend verweigern und fortfahren (Graceful Degradation). |
| `deny` | Berechtigung stillschweigend verweigern und fortfahren (Graceful Degradation). |
### Konfiguration
Über Plugin-Konfiguration setzen:
Über die Plugin-Konfiguration setzen:
```bash
openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail
```
Starten Sie das Gateway nach dem Ändern dieser Werte neu.
Starten Sie das Gateway neu, nachdem Sie diese Werte geändert haben.
> **Wichtig:** OpenClaw verwendet derzeit standardmäßig `permissionMode=approve-reads` und `nonInteractivePermissions=fail`. In nicht interaktiven ACP-Sitzungen kann jeder Schreib- oder Exec-Vorgang, der eine Berechtigungsabfrage auslöst, mit `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` fehlschlagen.
> **Wichtig:** OpenClaw verwendet derzeit standardmäßig `permissionMode=approve-reads` und `nonInteractivePermissions=fail`. In nicht interaktiven ACP-Sitzungen kann jeder Schreib- oder Ausführungsvorgang, der eine Berechtigungsaufforderung auslöst, mit `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` fehlschlagen.
>
> Wenn Sie Berechtigungen einschränken müssen, setzen Sie `nonInteractivePermissions` auf `deny`, damit Sitzungen sich kontrolliert verschlechtern, statt abzustürzen.
> Wenn Sie Berechtigungen einschränken müssen, setzen Sie `nonInteractivePermissions` auf `deny`, damit Sitzungen sich kontrolliert verschlechtern, anstatt abzustürzen.
## Fehlerbehebung
| Symptom | Wahrscheinliche Ursache | Behebung |
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ACP runtime backend is not configured` | Backend-Plugin fehlt oder ist deaktiviert. | Backend-Plugin installieren und aktivieren, dann `/acp doctor` ausführen. |
| `ACP is disabled by policy (acp.enabled=false)` | ACP ist global deaktiviert. | `acp.enabled=true` setzen. |
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Dispatch aus normalen Thread-Nachrichten ist deaktiviert. | `acp.dispatch.enabled=true` setzen. |
| `ACP agent "<id>" is not allowed by policy` | Agent ist nicht in der Allowlist. | Erlaubte `agentId` verwenden oder `acp.allowedAgents` aktualisieren. |
| `Unable to resolve session target: ...` | Ungültiges Schlüssel-/ID-/Label-Token. | `/acp sessions` ausführen, exakten Schlüssel/Label kopieren, erneut versuchen. |
| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` wurde ohne aktive bindbare Konversation verwendet. | Zum Ziel-Chat/-Channel wechseln und erneut versuchen oder ungebundenen Spawn verwenden. |
| `Conversation bindings are unavailable for <channel>.` | Adapter besitzt keine ACP-Bindungsfähigkeit für aktuelle Konversationen. | `/acp spawn ... --thread ...` verwenden, wo unterstützt, Top-Level-`bindings[]` konfigurieren oder zu einem unterstützten Channel wechseln. |
| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` wurde außerhalb eines Thread-Kontexts verwendet. | Zum Ziel-Thread wechseln oder `--thread auto`/`off` verwenden. |
| `Only <user-id> can rebind this channel/conversation/thread.` | Ein anderer Benutzer besitzt das aktive Binding-Ziel. | Als Eigentümer neu binden oder eine andere Konversation bzw. einen anderen Thread verwenden. |
| `Thread bindings are unavailable for <channel>.` | Adapter besitzt keine Thread-Bindungsfähigkeit. | `--thread off` verwenden oder zu einem unterstützten Adapter/Channel wechseln. |
| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP-Laufzeit läuft auf dem Host; die anfordernde Sitzung ist sandboxed. | `runtime="subagent"` aus sandboxed Sitzungen verwenden oder ACP-Spawn aus einer nicht sandboxed Sitzung ausführen. |
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | `sandbox="require"` wurde für die ACP-Laufzeit angefordert. | `runtime="subagent"` für obligatorische Sandbox-Ausführung verwenden oder ACP mit `sandbox="inherit"` aus einer nicht sandboxed Sitzung verwenden. |
| Missing ACP metadata for bound session | Veraltete/gelöschte ACP-Sitzungsmetadaten. | Mit `/acp spawn` neu erstellen und dann Thread erneut binden/fokussieren. |
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` blockiert Schreib-/Exec-Vorgänge in nicht interaktiver ACP-Sitzung. | `plugins.entries.acpx.config.permissionMode` auf `approve-all` setzen und Gateway neu starten. Siehe [Konfiguration von Berechtigungen](#konfiguration-von-berechtigungen). |
| ACP-Sitzung schlägt früh mit wenig Ausgabe fehl | Berechtigungsabfragen werden durch `permissionMode`/`nonInteractivePermissions` blockiert. | Gateway-Logs auf `AcpRuntimeError` prüfen. Für vollständige Berechtigungen `permissionMode=approve-all` setzen; für Graceful Degradation `nonInteractivePermissions=deny` setzen. |
| ACP-Sitzung hängt nach Abschluss der Arbeit unbegrenzt | Harness-Prozess ist beendet, aber die ACP-Sitzung hat den Abschluss nicht gemeldet. | Mit `ps aux \| grep acpx` überwachen; veraltete Prozesse manuell beenden. |
| Symptom | Wahrscheinliche Ursache | Behebung |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ACP runtime backend is not configured` | Backend-Plugin fehlt oder ist deaktiviert. | Backend-Plugin installieren und aktivieren, dann `/acp doctor` ausführen. |
| `ACP is disabled by policy (acp.enabled=false)` | ACP ist global deaktiviert. | `acp.enabled=true` setzen. |
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Dispatch aus normalen Thread-Nachrichten ist deaktiviert. | `acp.dispatch.enabled=true` setzen. |
| `ACP agent "<id>" is not allowed by policy` | Agent ist nicht in der Allowlist. | Erlaubte `agentId` verwenden oder `acp.allowedAgents` aktualisieren. |
| `Unable to resolve session target: ...` | Ungültiges Schlüssel-/ID-/Label-Token. | `/acp sessions` ausführen, exakten Schlüssel/das exakte Label kopieren und erneut versuchen. |
| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` wurde ohne aktive bindbare Konversation verwendet. | In den Ziel-Chat/-Kanal wechseln und erneut versuchen oder ungebundenen Spawn verwenden. |
| `Conversation bindings are unavailable for <channel>.` | Adapter hat keine ACP-Bindungsfähigkeit für die aktuelle Konversation. | Unterstützt, `/acp spawn ... --thread ...` verwenden, Top-Level-`bindings[]` konfigurieren oder zu einem unterstützten Kanal wechseln. |
| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` wurde außerhalb eines Thread-Kontexts verwendet. | In den Ziel-Thread wechseln oder `--thread auto`/`off` verwenden. |
| `Only <user-id> can rebind this channel/conversation/thread.` | Ein anderer Benutzer besitzt das aktive Bindungsziel. | Als Eigentümer neu binden oder eine andere Konversation bzw. einen anderen Thread verwenden. |
| `Thread bindings are unavailable for <channel>.` | Adapter hat keine Thread-Bindungsfähigkeit. | `--thread off` verwenden oder zu einem unterstützten Adapter/Kanal wechseln. |
| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP-Laufzeit ist hostseitig; die anfordernde Sitzung läuft in einer Sandbox. | In Sandbox-Sitzungen `runtime="subagent"` verwenden oder ACP-Spawn aus einer nicht sandboxierten Sitzung ausführen. |
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | `sandbox="require"` wurde für die ACP-Laufzeit angefordert. | Für erforderliche Sandbox-Verwendung `runtime="subagent"` nutzen oder ACP mit `sandbox="inherit"` aus einer nicht sandboxierten Sitzung verwenden. |
| Missing ACP metadata for bound session | Veraltete/gelöschte ACP-Sitzungsmetadaten. | Mit `/acp spawn` neu erstellen, dann Thread neu binden/fokussieren. |
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` blockiert Schreiben/Ausführen in einer nicht interaktiven ACP-Sitzung. | `plugins.entries.acpx.config.permissionMode` auf `approve-all` setzen und das Gateway neu starten. Siehe [Berechtigungskonfiguration](#permission-configuration). |
| ACP session fails early with little output | Berechtigungsaufforderungen werden durch `permissionMode`/`nonInteractivePermissions` blockiert. | Gateway-Logs auf `AcpRuntimeError` prüfen. Für volle Berechtigungen `permissionMode=approve-all` setzen; für Graceful Degradation `nonInteractivePermissions=deny`. |
| ACP session stalls indefinitely after completing work | Harness-Prozess ist beendet, aber die ACP-Sitzung hat den Abschluss nicht gemeldet. | Mit `ps aux \| grep acpx` überwachen; veraltete Prozesse manuell beenden. |

68
docs/de/tools/agent-send.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Sie möchten Agent-Läufe aus Skripten oder über die Befehlszeile auslösen
- Sie müssen Agent-Antworten programmgesteuert an einen Chat-Kanal zustellen
summary: Agent-Züge über die CLI ausführen und Antworten optional an Kanäle zustellen
- Sie möchten Agent-Ausführungen über Skripte oder die Befehlszeile auslösen.
- Sie müssen Agent-Antworten programmgesteuert an einen Chat-Channel zustellen.
summary: Führen Sie Agent-Züge über die CLI aus und stellen Sie Antworten optional an Channels zu.
title: Agent Send
x-i18n:
generated_at: "2026-04-05T12:56:22Z"
generated_at: "2026-04-21T13:37:13Z"
model: gpt-5.4
provider: openai
source_hash: 42ea2977e89fb28d2afd07e5f6b1560ad627aea8b72fde36d8e324215c710afc
source_hash: 0550ad38efb2711f267a62b905fd150987a98801247de780ed3df97f27245704
source_path: tools/agent-send.md
workflow: 15
---
@ -16,7 +16,7 @@ x-i18n:
# Agent Send
`openclaw agent` führt einen einzelnen Agent-Zug über die Befehlszeile aus, ohne dass
eine eingehende Chat-Nachricht erforderlich ist. Verwenden Sie es für skriptgesteuerte Workflows, Tests und
eine eingehende Chat-Nachricht erforderlich ist. Verwenden Sie ihn für skriptgesteuerte Workflows, Tests und
programmgesteuerte Zustellung.
## Schnellstart
@ -31,7 +31,7 @@ programmgesteuerte Zustellung.
</Step>
<Step title="Einen bestimmten Agenten oder eine Sitzung ansprechen">
<Step title="Einen bestimmten Agenten oder eine bestimmte Sitzung ansprechen">
```bash
# Einen bestimmten Agenten ansprechen
openclaw agent --agent ops --message "Summarize logs"
@ -45,9 +45,9 @@ programmgesteuerte Zustellung.
</Step>
<Step title="Die Antwort an einen Kanal zustellen">
<Step title="Die Antwort an einen Channel zustellen">
```bash
# An WhatsApp zustellen (Standardkanal)
# An WhatsApp zustellen (Standard-Channel)
openclaw agent --to +15555550123 --message "Report ready" --deliver
# An Slack zustellen
@ -60,32 +60,32 @@ programmgesteuerte Zustellung.
## Flags
| Flag | Beschreibung |
| ----------------------------- | ---------------------------------------------------------- |
| `--message \<text\>` | Zu sendende Nachricht (erforderlich) |
| `--to \<dest\>` | Sitzungsschlüssel aus einem Ziel ableiten (Telefon, Chat-ID) |
| `--agent \<id\>` | Einen konfigurierten Agenten ansprechen (verwendet seine `main`-Sitzung) |
| `--session-id \<id\>` | Eine vorhandene Sitzung anhand der ID wiederverwenden |
| `--local` | Lokale eingebettete Laufzeit erzwingen (Gateway überspringen) |
| `--deliver` | Die Antwort an einen Chat-Kanal senden |
| `--channel \<name\>` | Zustellkanal (whatsapp, telegram, discord, slack usw.) |
| `--reply-to \<target\>` | Überschreibung des Zustellziels |
| `--reply-channel \<name\>` | Überschreibung des Zustellkanals |
| `--reply-account \<id\>` | Überschreibung der Zustellkonto-ID |
| `--thinking \<level\>` | Thinking-Level setzen (off, minimal, low, medium, high, xhigh) |
| `--verbose \<on\|full\|off\>` | Verbose-Level setzen |
| `--timeout \<seconds\>` | Agent-Timeout überschreiben |
| `--json` | Strukturiertes JSON ausgeben |
| Flag | Beschreibung |
| ----------------------------- | ----------------------------------------------------------- |
| `--message \<text\>` | Zu sendende Nachricht (erforderlich) |
| `--to \<dest\>` | Leitet den Sitzungsschlüssel aus einem Ziel ab (Telefon, Chat-ID) |
| `--agent \<id\>` | Spricht einen konfigurierten Agenten an (verwendet dessen `main`-Sitzung) |
| `--session-id \<id\>` | Verwendet eine vorhandene Sitzung anhand ihrer ID wieder |
| `--local` | Erzwingt die lokal eingebettete Runtime (Gateway überspringen) |
| `--deliver` | Sendet die Antwort an einen Chat-Channel |
| `--channel \<name\>` | Zustell-Channel (whatsapp, telegram, discord, slack usw.) |
| `--reply-to \<target\>` | Überschreibung des Zustellziels |
| `--reply-channel \<name\>` | Überschreibung des Zustell-Channels |
| `--reply-account \<id\>` | Überschreibung der Zustell-Konto-ID |
| `--thinking \<level\>` | Setzt die Thinking-Stufe für das ausgewählte Modellprofil |
| `--verbose \<on\|full\|off\>` | Setzt die Verbose-Stufe |
| `--timeout \<seconds\>` | Überschreibt das Agent-Timeout |
| `--json` | Gibt strukturiertes JSON aus |
## Verhalten
- Standardmäßig läuft die CLI **über das Gateway**. Fügen Sie `--local` hinzu, um die
eingebettete Laufzeit auf der aktuellen Maschine zu erzwingen.
- Wenn das Gateway nicht erreichbar ist, fällt die CLI **auf den lokalen eingebetteten Lauf** zurück.
- Sitzungsauswahl: `--to` leitet den Sitzungsschlüssel ab (Gruppen-/Kanalziele
eingebettete Runtime auf dem aktuellen Rechner zu erzwingen.
- Wenn das Gateway nicht erreichbar ist, fällt die CLI **auf die lokale eingebettete Ausführung** zurück.
- Sitzungsauswahl: `--to` leitet den Sitzungsschlüssel ab (Gruppen-/Channel-Ziele
behalten die Isolation bei; direkte Chats werden zu `main` zusammengeführt).
- Thinking- und Verbose-Flags werden im Sitzungsspeicher persistiert.
- Ausgabe: standardmäßig Klartext oder mit `--json` als strukturierte Payload + Metadaten.
- Ausgabe: standardmäßig Klartext oder mit `--json` strukturierte Payload + Metadaten.
## Beispiele
@ -93,15 +93,15 @@ programmgesteuerte Zustellung.
# Einfacher Zug mit JSON-Ausgabe
openclaw agent --to +15555550123 --message "Trace logs" --verbose on --json
# Zug mit Thinking-Level
# Zug mit Thinking-Stufe
openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium
# An einen anderen Kanal als die Sitzung zustellen
# An einen anderen Channel als die Sitzung zustellen
openclaw agent --agent ops --message "Alert" --deliver --reply-channel telegram --reply-to "@admin"
```
## Verwandte Themen
## Verwandt
- [Referenz zur Agent-CLI](/cli/agent)
- [Sub-Agents](/tools/subagents) — Erzeugen von Sub-Agenten im Hintergrund
- [Agent-CLI-Referenz](/cli/agent)
- [Unter-Agenten](/de/tools/subagents) — Spawn von Hintergrund-Unter-Agenten
- [Sitzungen](/de/concepts/session) — wie Sitzungsschlüssel funktionieren

533
docs/de/tools/exec-approvals.md
View File

@ -1,74 +1,74 @@
---
read_when:
- Konfigurieren von Ausführungsfreigaben oder Zulassungslisten
- Implementierung der UX für Ausführungsfreigaben in der macOS-App
- Überprüfung von Sandbox-Escape-Aufforderungen und ihren Auswirkungen
summary: Ausführungsfreigaben, Zulassungslisten und Sandbox-Escape-Aufforderungen
title: Ausführungsfreigaben
- Exec-Genehmigungen oder Allowlists konfigurieren
- Exec-Genehmigungs-UX in der macOS-App implementieren
- Aufforderungen zum Verlassen der Sandbox und deren Auswirkungen prüfen
summary: Exec-Genehmigungen, Allowlists und Aufforderungen zum Verlassen der Sandbox
title: Exec-Genehmigungen
x-i18n:
generated_at: "2026-04-10T06:21:34Z"
generated_at: "2026-04-21T13:37:25Z"
model: gpt-5.4
provider: openai
source_hash: 5f4a2e2f1f3c13a1d1926c9de0720513ea8a74d1ca571dbe74b188d8c560c14c
source_hash: 0738108dd21e24eb6317d437b7ac693312743eddc3ec295ba62c4e60356cb33e
source_path: tools/exec-approvals.md
workflow: 15
---
# Ausführungsfreigaben
# Exec-Genehmigungen
Ausführungsfreigaben sind die **Sicherheitsleitplanke der Companion-App bzw. des Node-Hosts**, damit ein in einer Sandbox ausgeführter Agent Befehle auf einem echten Host (`gateway` oder `node`) ausführen kann. Sie funktionieren wie eine Sicherheitsverriegelung:
Befehle sind nur erlaubt, wenn Richtlinie + Zulassungsliste + (optionale) Benutzerfreigabe alle zustimmen.
Ausführungsfreigaben gelten **zusätzlich** zur Tool-Richtlinie und zu Elevated-Gating (außer wenn Elevated auf `full` gesetzt ist; dann werden Freigaben übersprungen).
Die effektive Richtlinie ist die **strengere** von `tools.exec.*` und den Standardwerten für Freigaben; wenn ein Feld bei den Freigaben weggelassen wird, wird stattdessen der Wert aus `tools.exec` verwendet.
Die Host-Ausführung verwendet außerdem den lokalen Freigabestatus auf diesem Rechner. Ein hostlokales
`ask: "always"` in `~/.openclaw/exec-approvals.json` sorgt weiterhin für Eingabeaufforderungen, auch wenn
Sitzungs- oder Konfigurationsstandardwerte `ask: "on-miss"` anfordern.
Exec-Genehmigungen sind die **Schutzmaßnahme der Companion-App / des Node-Hosts**, damit ein in einer Sandbox ausgeführter Agent
Befehle auf einem echten Host (`gateway` oder `node`) ausführen darf. Verstehen Sie das wie eine Sicherheitsverriegelung:
Befehle sind nur erlaubt, wenn Richtlinie + Allowlist + (optionale) Benutzerfreigabe alle übereinstimmen.
Exec-Genehmigungen gelten **zusätzlich** zur Tool-Richtlinie und zum Elevated-Gating (außer wenn elevated auf `full` gesetzt ist; dann werden Genehmigungen übersprungen).
Die wirksame Richtlinie ist die **strengere** von `tools.exec.*` und den Standardwerten der Genehmigungen; wenn ein Genehmigungsfeld fehlt, wird der Wert aus `tools.exec` verwendet.
Host-Exec verwendet auch den lokalen Genehmigungsstatus auf diesem Rechner. Ein hostlokales
`ask: "always"` in `~/.openclaw/exec-approvals.json` sorgt weiterhin für Rückfragen, selbst wenn
Sitzungs- oder Konfigurationsstandards `ask: "on-miss"` anfordern.
Verwenden Sie `openclaw approvals get`, `openclaw approvals get --gateway` oder
`openclaw approvals get --node <id|name|ip>`, um die angeforderte Richtlinie,
die Quellen der Host-Richtlinie und das effektive Ergebnis zu prüfen.
die Quellen der Host-Richtlinie und das wirksame Ergebnis zu prüfen.
Für den lokalen Rechner zeigt `openclaw exec-policy show` dieselbe zusammengeführte Ansicht an, und
`openclaw exec-policy set|preset` kann die lokal angeforderte Richtlinie in einem Schritt mit der
lokalen Host-Freigabedatei synchronisieren. Wenn ein lokaler Geltungsbereich `host=node` anfordert,
meldet `openclaw exec-policy show` diesen Geltungsbereich zur Laufzeit als von einem Node verwaltet, statt
so zu tun, als wäre die lokale Freigabedatei die tatsächlich maßgebliche Quelle.
lokalen Host-Genehmigungsdatei synchronisieren. Wenn ein lokaler Geltungsbereich `host=node` anfordert,
meldet `openclaw exec-policy show` diesen Geltungsbereich zur Laufzeit als Node-verwaltet, statt
vorzutäuschen, dass die lokale Genehmigungsdatei die tatsächlich maßgebliche Quelle ist.
Wenn die UI der Companion-App **nicht verfügbar** ist, wird jede Anforderung, die eine Eingabeaufforderung benötigt,
über das **ask-Fallback** aufgelöst (Standard: deny).
Wenn die UI der Companion-App **nicht verfügbar** ist, wird jede Anfrage, die eine Rückfrage erfordert,
durch den **Ask-Fallback** aufgelöst (Standard: deny).
Native Chat-Freigabe-Clients können außerdem kanalspezifische Bedienelemente in der ausstehenden
Freigabenachricht anzeigen. Matrix kann zum Beispiel Reaktionskürzel in der
Freigabeaufforderung vorbelegen (`✅` einmal erlauben, `❌` verweigern und `♾️` immer erlauben, sofern verfügbar),
während die `/approve ...`-Befehle in der Nachricht weiterhin als Fallback bleiben.
Native Chat-Genehmigungsclients können auf der ausstehenden Genehmigungsnachricht auch kanalspezifische Bedienmöglichkeiten anbieten. Matrix kann zum Beispiel Reaktionskürzel auf der
Genehmigungsabfrage vorbereiten (`✅` einmal erlauben, `❌` ablehnen und `♾️` immer erlauben, wenn verfügbar)
und trotzdem die `/approve ...`-Befehle als Fallback in der Nachricht belassen.
## Wo dies gilt
Ausführungsfreigaben werden lokal auf dem Ausführungshost durchgesetzt:
Exec-Genehmigungen werden lokal auf dem Ausführungshost erzwungen:
- **gateway-Host** → `openclaw`-Prozess auf dem Gateway-Rechner
- **node-Host** → Node-Runner (macOS-Companion-App oder kopfloser Node-Host)
- **Gateway-Host** → `openclaw`-Prozess auf dem Gateway-Rechner
- **Node-Host** → Node-Runner (macOS-Companion-App oder Headless-Node-Host)
Hinweis zum Vertrauensmodell:
- Über das Gateway authentifizierte Aufrufer sind vertrauenswürdige Operatoren für dieses Gateway.
- Gekoppelte Nodes erweitern diese vertrauenswürdige Operatorfähigkeit auf den Node-Host.
- Ausführungsfreigaben verringern das Risiko versehentlicher Ausführung, sind aber keine Authentifizierungsgrenze pro Benutzer.
- Für das Gateway authentifizierte Aufrufer sind vertrauenswürdige Operatoren für dieses Gateway.
- Gekoppelte Nodes erweitern diese Fähigkeit als vertrauenswürdiger Operator auf den Node-Host.
- Exec-Genehmigungen verringern das Risiko versehentlicher Ausführung, sind aber keine Authentifizierungsgrenze pro Benutzer.
- Genehmigte Ausführungen auf dem Node-Host binden den kanonischen Ausführungskontext: kanonisches cwd, exaktes argv, env-Bindung
sofern vorhanden und angehefteter Pfad zur ausführbaren Datei, falls zutreffend.
falls vorhanden und angehefteten ausführbaren Pfad, sofern zutreffend.
- Für Shell-Skripte und direkte Interpreter-/Runtime-Dateiaufrufe versucht OpenClaw außerdem,
genau einen konkreten lokalen Dateiopeanden zu binden. Wenn sich diese gebundene Datei nach der
Freigabe, aber vor der Ausführung ändert, wird die Ausführung verweigert, statt Inhalte mit Abweichungen auszuführen.
- Diese Dateibindung ist absichtlich nur nach bestem Bemühen implementiert, nicht als vollständiges semantisches Modell jedes
Interpreter-/Runtime-Ladepfads. Wenn der Freigabemodus nicht genau eine konkrete lokale Datei zur Bindung identifizieren kann,
wird die Erzeugung einer freigabegestützten Ausführung verweigert, statt eine vollständige Abdeckung vorzutäuschen.
genau einen konkreten lokalen Dateiopeanden zu binden. Wenn sich diese gebundene Datei nach der Genehmigung, aber vor der Ausführung ändert,
wird die Ausführung verweigert, statt abgewichenen Inhalt auszuführen.
- Diese Dateibindung ist absichtlich Best-Effort und kein vollständiges semantisches Modell jedes
Interpreter-/Runtime-Ladepfads. Wenn der Genehmigungsmodus nicht genau eine konkrete lokale
Datei zur Bindung identifizieren kann, verweigert er die Erstellung einer genehmigungsgestützten Ausführung, statt vollständige Abdeckung vorzutäuschen.
macOS-Aufteilung:
- Der **node host service** leitet `system.run` über lokale IPC an die **macOS-App** weiter.
- Die **macOS-App** erzwingt Freigaben und führt den Befehl im UI-Kontext aus.
- **Node-Host-Service** leitet `system.run` über lokales IPC an die **macOS-App** weiter.
- **macOS-App** erzwingt Genehmigungen und führt den Befehl im UI-Kontext aus.
## Einstellungen und Speicherung
Freigaben werden in einer lokalen JSON-Datei auf dem Ausführungshost gespeichert:
Genehmigungen liegen in einer lokalen JSON-Datei auf dem Ausführungshost:
`~/.openclaw/exec-approvals.json`
@ -107,14 +107,14 @@ Beispielschema:
}
```
## Modus „YOLO“ ohne Freigaben
## „YOLO“-Modus ohne Genehmigungen
Wenn Sie möchten, dass die Host-Ausführung ohne Freigabeaufforderungen ausgeführt wird, müssen Sie **beide** Richtlinienebenen öffnen:
Wenn Host-Exec ohne Genehmigungsabfragen ausgeführt werden soll, müssen Sie **beide** Richtlinienebenen öffnen:
- angeforderte Ausführungsrichtlinie in der OpenClaw-Konfiguration (`tools.exec.*`)
- hostlokale Freigaberichtlinie in `~/.openclaw/exec-approvals.json`
- angeforderte Exec-Richtlinie in der OpenClaw-Konfiguration (`tools.exec.*`)
- hostlokale Genehmigungsrichtlinie in `~/.openclaw/exec-approvals.json`
Dies ist jetzt das Standardverhalten für den Host, sofern Sie es nicht explizit verschärfen:
Dies ist jetzt das Standardverhalten für Hosts, sofern Sie es nicht explizit verschärfen:
- `tools.exec.security`: `full` auf `gateway`/`node`
- `tools.exec.ask`: `off`
@ -122,15 +122,15 @@ Dies ist jetzt das Standardverhalten für den Host, sofern Sie es nicht explizit
Wichtige Unterscheidung:
- `tools.exec.host=auto` wählt aus, wo die Ausführung stattfindet: in der Sandbox, wenn verfügbar, andernfalls auf dem Gateway.
- YOLO wählt aus, wie die Host-Ausführung freigegeben wird: `security=full` plus `ask=off`.
- Im YOLO-Modus legt OpenClaw keine zusätzliche heuristische Freigabeschranke für Befehlsverschleierung über die konfigurierte Host-Ausführungsrichtlinie.
- `auto` macht Gateway-Routing nicht zu einer freien Umgehung aus einer Sandbox-Sitzung heraus. Eine Anforderung pro Aufruf mit `host=node` ist aus `auto` heraus erlaubt, und `host=gateway` ist aus `auto` nur dann erlaubt, wenn keine Sandbox-Runtime aktiv ist. Wenn Sie einen stabilen Standardwert ohne `auto` möchten, setzen Sie `tools.exec.host` oder verwenden Sie `/exec host=...` explizit.
- `tools.exec.host=auto` wählt aus, wo Exec ausgeführt wird: in der Sandbox, wenn verfügbar, andernfalls auf dem Gateway.
- YOLO wählt aus, wie Host-Exec genehmigt wird: `security=full` plus `ask=off`.
- Im YOLO-Modus fügt OpenClaw keine zusätzliche heuristische Genehmigungsschranke für Befehlsverschleierung und keine Skript-Preflight-Ablehnungsebene zusätzlich zur konfigurierten Host-Exec-Richtlinie hinzu.
- `auto` macht Gateway-Routing nicht zu einer freien Umgehung aus einer Sandbox-Sitzung heraus. Eine Anfrage pro Aufruf mit `host=node` ist von `auto` aus erlaubt, und `host=gateway` ist von `auto` aus nur erlaubt, wenn keine Sandbox-Runtime aktiv ist. Wenn Sie einen stabilen Nicht-`auto`-Standard wollen, setzen Sie `tools.exec.host` oder verwenden Sie `/exec host=...` explizit.
Wenn Sie eine konservativere Einrichtung möchten, verschärfen Sie eine der Ebenen wieder auf `allowlist` / `on-miss`
Wenn Sie ein konservativeres Setup möchten, verschärfen Sie eine der beiden Ebenen wieder auf `allowlist` / `on-miss`
oder `deny`.
Dauerhafte Einrichtung „nie nachfragen“ für den Gateway-Host:
Dauerhafte Einrichtung „nie nachfragen“ für Gateway-Hosts:
```bash
openclaw config set tools.exec.host gateway
@ -139,7 +139,7 @@ openclaw config set tools.exec.ask off
openclaw gateway restart
```
Setzen Sie dann die Host-Freigabedatei passend dazu:
Setzen Sie dann die Host-Genehmigungsdatei entsprechend:
```bash
openclaw approvals set --stdin <<'EOF'
@ -154,22 +154,22 @@ openclaw approvals set --stdin <<'EOF'
EOF
```
Lokale Abkürzung für dieselbe Gateway-Host-Richtlinie auf dem aktuellen Rechner:
Lokale Kurzform für dieselbe Gateway-Host-Richtlinie auf dem aktuellen Rechner:
```bash
openclaw exec-policy preset yolo
```
Diese lokale Abkürzung aktualisiert beides:
Diese lokale Kurzform aktualisiert beides:
- lokale `tools.exec.host/security/ask`
- lokale Standardwerte in `~/.openclaw/exec-approvals.json`
Sie ist absichtlich nur lokal wirksam. Wenn Sie Freigaben für Gateway-Host oder Node-Host
Sie ist absichtlich nur lokal. Wenn Sie Genehmigungen für Gateway-Hosts oder Node-Hosts
remote ändern müssen, verwenden Sie weiterhin `openclaw approvals set --gateway` oder
`openclaw approvals set --node <id|name|ip>`.
Für einen Node-Host wenden Sie stattdessen dieselbe Freigabedatei auf diesem Node an:
Für einen Node-Host wenden Sie stattdessen dieselbe Genehmigungsdatei auf diesem Node an:
```bash
openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
@ -186,43 +186,43 @@ EOF
Wichtige Einschränkung nur für lokal:
- `openclaw exec-policy` synchronisiert keine Node-Freigaben
- `openclaw exec-policy` synchronisiert keine Node-Genehmigungen
- `openclaw exec-policy set --host node` wird abgelehnt
- Node-Ausführungsfreigaben werden zur Laufzeit vom Node abgerufen, daher müssen Node-bezogene Aktualisierungen über `openclaw approvals --node ...` erfolgen
- Node-Exec-Genehmigungen werden zur Laufzeit vom Node abgerufen, daher müssen zielgerichtete Aktualisierungen für Nodes `openclaw approvals --node ...` verwenden
Abkürzung nur für die Sitzung:
Kurzform nur für die Sitzung:
- `/exec security=full ask=off` ändert nur die aktuelle Sitzung.
- `/elevated full` ist eine Break-Glass-Abkürzung, die Ausführungsfreigaben für diese Sitzung ebenfalls überspringt.
- `/elevated full` ist eine Notfall-Kurzform, die für diese Sitzung auch Exec-Genehmigungen überspringt.
Wenn die Host-Freigabedatei strenger bleibt als die Konfiguration, gewinnt weiterhin die strengere Host-Richtlinie.
Wenn die Host-Genehmigungsdatei strenger bleibt als die Konfiguration, gewinnt weiterhin die strengere Host-Richtlinie.
## Richtlinienoptionen
## Richtlinienschalter
### Security (`exec.security`)
### Sicherheit (`exec.security`)
- **deny**: blockiert alle Anfragen zur Host-Ausführung.
- **allowlist**: erlaubt nur Befehle auf der Zulassungsliste.
- **full**: erlaubt alles (entspricht elevated).
- **deny**: alle Host-Exec-Anfragen blockieren.
- **allowlist**: nur Befehle aus der Allowlist erlauben.
- **full**: alles erlauben (entspricht elevated).
### Ask (`exec.ask`)
- **off**: niemals nachfragen.
- **on-miss**: nur nachfragen, wenn die Zulassungsliste nicht passt.
- **off**: nie nachfragen.
- **on-miss**: nur nachfragen, wenn die Allowlist nicht passt.
- **always**: bei jedem Befehl nachfragen.
- Dauerhaftes Vertrauen über `allow-always` unterdrückt Eingabeaufforderungen nicht, wenn der effektive ask-Modus `always` ist
- Dauerhaftes Vertrauen per `allow-always` unterdrückt Rückfragen nicht, wenn der wirksame Ask-Modus `always` ist
### Ask-Fallback (`askFallback`)
Wenn eine Eingabeaufforderung erforderlich ist, aber keine UI erreichbar ist, entscheidet das Fallback:
Wenn eine Rückfrage erforderlich ist, aber keine UI erreichbar ist, entscheidet der Fallback:
- **deny**: blockieren.
- **allowlist**: nur erlauben, wenn die Zulassungsliste passt.
- **allowlist**: nur erlauben, wenn die Allowlist passt.
- **full**: erlauben.
### Härtung für Inline-Interpreterauswertung (`tools.exec.strictInlineEval`)
### Härtung für Inline-Interpreter-Eval (`tools.exec.strictInlineEval`)
Wenn `tools.exec.strictInlineEval=true`, behandelt OpenClaw Formen der Inline-Codeauswertung als nur per Freigabe erlaubt, auch wenn das Interpreter-Binary selbst auf der Zulassungsliste steht.
Wenn `tools.exec.strictInlineEval=true`, behandelt OpenClaw Inline-Code-Eval-Formen als nur nach Genehmigung erlaubt, selbst wenn die Interpreter-Binärdatei selbst in der Allowlist steht.
Beispiele:
@ -234,18 +234,18 @@ Beispiele:
- `lua -e`
- `osascript -e`
Dies ist eine zusätzliche Schutzmaßnahme für Interpreter-Lader, die sich nicht sauber auf einen stabilen Dateiopeanden abbilden lassen. Im strikten Modus gilt:
Dies ist Defense-in-Depth für Interpreter-Loader, die sich nicht sauber auf einen stabilen Dateiopeanden abbilden lassen. Im strikten Modus:
- diese Befehle benötigen weiterhin eine explizite Freigabe;
- `allow-always` speichert für sie nicht automatisch neue Zulassungslisteneinträge.
- benötigen diese Befehle weiterhin eine explizite Genehmigung;
- persistiert `allow-always` dafür nicht automatisch neue Allowlist-Einträge.
## Zulassungsliste (pro Agent)
## Allowlist (pro Agent)
Zulassungslisten gelten **pro Agent**. Wenn mehrere Agents vorhanden sind, wechseln Sie in der
macOS-App zu dem Agent, den Sie bearbeiten möchten. Muster sind **globale Abgleiche ohne Beachtung der Groß-/Kleinschreibung**.
Muster sollten zu **Binary-Pfaden** aufgelöst werden (Einträge nur mit Basename werden ignoriert).
Veraltete `agents.default`-Einträge werden beim Laden nach `agents.main` migriert.
Shell-Verkettungen wie `echo ok && pwd` erfordern weiterhin, dass jedes Segment der obersten Ebene die Regeln der Zulassungsliste erfüllt.
Allowlists gelten **pro Agent**. Wenn mehrere Agenten vorhanden sind, wechseln Sie in der macOS-App den Agenten,
den Sie bearbeiten. Muster sind **globale Übereinstimmungen ohne Beachtung der Groß-/Kleinschreibung**.
Muster sollten zu **Binärpfaden** aufgelöst werden (Einträge nur mit Basename werden ignoriert).
Alte `agents.default`-Einträge werden beim Laden nach `agents.main` migriert.
Shell-Ketten wie `echo ok && pwd` erfordern weiterhin, dass jedes Top-Level-Segment die Allowlist-Regeln erfüllt.
Beispiele:
@ -253,45 +253,44 @@ Beispiele:
- `~/.local/bin/*`
- `/opt/homebrew/bin/rg`
Jeder Eintrag in der Zulassungsliste erfasst:
Jeder Allowlist-Eintrag verfolgt:
- **id** stabile UUID für die UI-Identität (optional)
- **last used** Zeitstempel
- **last used command**
- **last resolved path**
## CLI von Skills automatisch zulassen
## Skill-CLIs automatisch erlauben
Wenn **CLI von Skills automatisch zulassen** aktiviert ist, werden ausführbare Dateien, auf die bekannte Skills verweisen,
auf Nodes (macOS-Node oder kopfloser Node-Host) als auf der Zulassungsliste behandelt. Dazu wird
`skills.bins` über Gateway-RPC verwendet, um die Binärdateiliste des Skills abzurufen. Deaktivieren Sie dies, wenn Sie strikte manuelle Zulassungslisten möchten.
Wenn **Auto-allow skill CLIs** aktiviert ist, werden von bekannten Skills referenzierte ausführbare Dateien
auf Nodes (macOS-Node oder Headless-Node-Host) als auf der Allowlist behandelt. Dabei wird
`skills.bins` über die Gateway-RPC verwendet, um die Liste der Skill-Binaries abzurufen. Deaktivieren Sie dies, wenn Sie strikte manuelle Allowlists möchten.
Wichtige Hinweise zum Vertrauensmodell:
Wichtige Vertrauenshinweise:
- Dies ist eine **implizite Komfort-Zulassungsliste**, getrennt von manuellen Pfadeinträgen in der Zulassungsliste.
- Sie ist für vertrauenswürdige Operatorumgebungen gedacht, in denen Gateway und Node innerhalb derselben Vertrauensgrenze liegen.
- Wenn Sie striktes explizites Vertrauen benötigen, lassen Sie `autoAllowSkills: false` gesetzt und verwenden Sie nur manuelle Pfadeinträge in der Zulassungsliste.
- Dies ist eine **implizite Convenience-Allowlist**, getrennt von manuellen Pfad-Allowlist-Einträgen.
- Sie ist für vertrauenswürdige Operatorumgebungen gedacht, in denen Gateway und Node dieselbe Vertrauensgrenze teilen.
- Wenn Sie striktes explizites Vertrauen benötigen, belassen Sie `autoAllowSkills: false` und verwenden Sie nur manuelle Pfad-Allowlist-Einträge.
## Sichere Binaries (nur stdin)
`tools.exec.safeBins` definiert eine kleine Liste von **nur-stdin**-Binaries (zum Beispiel `cut`),
die im Modus `allowlist` **ohne** explizite Einträge in der Zulassungsliste ausgeführt werden können. Sichere Binaries lehnen
positionale Dateiar gumente und pfadähnliche Token ab, sodass sie nur auf dem eingehenden Stream arbeiten können.
`tools.exec.safeBins` definiert eine kleine Liste von **nur-stdin**-Binärdateien (zum Beispiel `cut`),
die im Allowlist-Modus **ohne** explizite Allowlist-Einträge ausgeführt werden können. Sichere Binaries lehnen
positionale Dateiar gumente und pfadähnliche Tokens ab, sodass sie nur auf dem eingehenden Stream arbeiten können.
Behandeln Sie dies als engen Schnellpfad für Stream-Filter, nicht als allgemeine Vertrauensliste.
Fügen Sie **keine** Interpreter- oder Runtime-Binaries (zum Beispiel `python3`, `node`, `ruby`, `bash`, `sh`, `zsh`) zu `safeBins` hinzu.
Wenn ein Befehl Code auswerten, Unterbefehle ausführen oder konstruktionsbedingt Dateien lesen kann, bevorzugen Sie explizite Einträge in der Zulassungsliste und lassen Sie Freigabeaufforderungen aktiviert.
Wenn ein Befehl Code auswerten, Unterbefehle ausführen oder per Design Dateien lesen kann, bevorzugen Sie explizite Allowlist-Einträge und lassen Sie Genehmigungsabfragen aktiviert.
Benutzerdefinierte sichere Binaries müssen ein explizites Profil in `tools.exec.safeBinProfiles.<bin>` definieren.
Die Validierung ist allein anhand der Form von argv deterministisch (keine Prüfungen auf Dateiexistenz im Host-Dateisystem), was
Oracle-Verhalten über Dateiexistenz durch Unterschiede zwischen Erlauben und Verweigern verhindert.
Dateiorientierte Optionen werden für Standard-Safe-Bins verweigert (zum Beispiel `sort -o`, `sort --output`,
Die Validierung erfolgt deterministisch allein aus der argv-Form (keine Host-Dateisystem-Existenzprüfungen),
wodurch Oracle-Verhalten zur Dateiexistenz durch Allow/Deny-Unterschiede verhindert wird.
Dateiorientierte Optionen werden für standardmäßige sichere Binaries abgelehnt (zum Beispiel `sort -o`, `sort --output`,
`sort --files0-from`, `sort --compress-program`, `sort --random-source`,
`sort --temporary-directory`/`-T`, `wc --files0-from`, `jq -f/--from-file`,
`grep -f/--file`).
Sichere Binaries erzwingen außerdem eine explizite Richtlinie pro Binary für Flags, die das Nur-stdin-
Verhalten aufheben (zum Beispiel `sort -o/--output/--compress-program` und rekursive grep-Flags).
Lange Optionen werden im Safe-Bin-Modus fehlersicher validiert: unbekannte Flags und mehrdeutige
Sichere Binaries erzwingen außerdem eine explizite Richtlinie pro Binärdatei für Flags, die das Nur-stdin-Verhalten aufheben (zum Beispiel `sort -o/--output/--compress-program` und rekursive grep-Flags).
Lange Optionen werden im Modus für sichere Binaries fail-closed validiert: unbekannte Flags und mehrdeutige
Abkürzungen werden abgelehnt.
Durch Safe-Bin-Profile verweigerte Flags:
Abgelehnte Flags nach Safe-Bin-Profil:
[//]: # "SAFE_BIN_DENIED_FLAGS:START"
@ -302,34 +301,34 @@ Durch Safe-Bin-Profile verweigerte Flags:
[//]: # "SAFE_BIN_DENIED_FLAGS:END"
Sichere Binaries erzwingen außerdem, dass argv-Token zur Ausführungszeit als **wörtlicher Text** behandelt werden (kein Globbing
und keine `$VARS`-Erweiterung) für Nur-stdin-Segmente, sodass Muster wie `*` oder `$HOME/...` nicht
zum Einschleusen von Dateilesen verwendet werden können.
Sichere Binaries müssen außerdem aus vertrauenswürdigen Binary-Verzeichnissen aufgelöst werden (Systemstandards plus optionale
`tools.exec.safeBinTrustedDirs`). `PATH`-Einträge werden niemals automatisch als vertrauenswürdig behandelt.
Die standardmäßig vertrauenswürdigen Verzeichnisse für sichere Binaries sind absichtlich minimal: `/bin`, `/usr/bin`.
Wenn sich Ihr Safe-Bin-Executable in Paketmanager- oder Benutzerpfaden befindet (zum Beispiel
Sichere Binaries erzwingen außerdem, dass argv-Tokens zur Ausführungszeit als **wörtlicher Text** behandelt werden (kein Globbing
und keine `$VARS`-Expansion) für nur-stdin-Segmente, sodass Muster wie `*` oder `$HOME/...` nicht
verwendet werden können, um Dateilesevorgänge einzuschmuggeln.
Sichere Binaries müssen außerdem aus vertrauenswürdigen Binary-Verzeichnissen aufgelöst werden (Systemstandardwerte plus optionale
`tools.exec.safeBinTrustedDirs`). `PATH`-Einträge werden niemals automatisch als vertrauenswürdig eingestuft.
Die standardmäßigen vertrauenswürdigen Verzeichnisse für sichere Binaries sind absichtlich minimal: `/bin`, `/usr/bin`.
Wenn sich Ihre ausführbare sichere Binary in Paketmanager-/Benutzerpfaden befindet (zum Beispiel
`/opt/homebrew/bin`, `/usr/local/bin`, `/opt/local/bin`, `/snap/bin`), fügen Sie sie explizit
zu `tools.exec.safeBinTrustedDirs` hinzu.
Shell-Verkettungen und Umleitungen werden im Modus `allowlist` nicht automatisch erlaubt.
Shell-Verkettung und Umleitungen werden im Allowlist-Modus nicht automatisch erlaubt.
Shell-Verkettung (`&&`, `||`, `;`) ist erlaubt, wenn jedes Segment der obersten Ebene die Zulassungsliste erfüllt
(einschließlich sicherer Binaries oder automatischer Zulassung von Skills). Umleitungen werden im Modus `allowlist` weiterhin nicht unterstützt.
Befehlssubstitution (`$()` / Backticks) wird beim Parsen der Zulassungsliste abgelehnt, auch innerhalb
Shell-Verkettung (`&&`, `||`, `;`) ist erlaubt, wenn jedes Top-Level-Segment die Allowlist erfüllt
(einschließlich sicherer Binaries oder automatischer Skill-Allowlist). Umleitungen bleiben im Allowlist-Modus nicht unterstützt.
Befehlssubstitution (`$()` / Backticks) wird beim Allowlist-Parsen abgelehnt, auch innerhalb
doppelter Anführungszeichen; verwenden Sie einfache Anführungszeichen, wenn Sie wörtlichen `$()`-Text benötigen.
Bei Freigaben der macOS-Companion-App wird roher Shell-Text, der Shell-Steuer- oder Erweiterungssyntax enthält
(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`), als Nichttreffer der Zulassungsliste behandelt, sofern
das Shell-Binary selbst nicht auf der Zulassungsliste steht.
Für Shell-Wrapper (`bash|sh|zsh ... -c/-lc`) werden anforderungsbezogene env-Overrides auf eine
kleine explizite Zulassungsliste reduziert (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
Bei Entscheidungen vom Typ „immer erlauben“ im Modus `allowlist` speichern bekannte
Dispatch-Wrapper (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) innere Executable-Pfade statt Wrapper-Pfaden.
Shell-Multiplexer (`busybox`, `toybox`) werden für Shell-Applets (`sh`, `ash`,
usw.) ebenfalls entpackt, sodass innere Executables statt Multiplexer-Binaries gespeichert werden. Wenn ein Wrapper oder
Multiplexer nicht sicher entpackt werden kann, wird kein Eintrag in der Zulassungsliste automatisch gespeichert.
Wenn Sie Interpreter wie `python3` oder `node` auf die Zulassungsliste setzen, sollten Sie `tools.exec.strictInlineEval=true` bevorzugen, damit Inline-Eval weiterhin eine explizite Freigabe erfordert. Im strikten Modus kann `allow-always` weiterhin harmlose Interpreter-/Skriptaufrufe speichern, aber Träger von Inline-Eval werden nicht automatisch gespeichert.
Bei Genehmigungen in der macOS-Companion-App wird roher Shell-Text, der Shell-Steuer- oder Expansionssyntax enthält
(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`), als Allowlist-Fehlschlag behandelt, sofern
nicht die Shell-Binary selbst auf der Allowlist steht.
Für Shell-Wrapper (`bash|sh|zsh ... -c/-lc`) werden anfragebezogene env-Überschreibungen auf eine
kleine explizite Allowlist reduziert (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
Bei Entscheidungen `allow-always` im Allowlist-Modus persistieren bekannte Dispatch-Wrapper
(`env`, `nice`, `nohup`, `stdbuf`, `timeout`) innere ausführbare Pfade statt Wrapper-Pfade.
Shell-Multiplexer (`busybox`, `toybox`) werden auch für Shell-Applets (`sh`, `ash`,
usw.) entpackt, sodass innere ausführbare Dateien statt Multiplexer-Binaries persistiert werden. Wenn ein Wrapper oder
Multiplexer nicht sicher entpackt werden kann, wird kein Allowlist-Eintrag automatisch persistiert.
Wenn Sie Interpreter wie `python3` oder `node` auf die Allowlist setzen, bevorzugen Sie `tools.exec.strictInlineEval=true`, damit Inline-Eval weiterhin eine explizite Genehmigung erfordert. Im strikten Modus kann `allow-always` weiterhin harmlose Interpreter-/Skriptaufrufe persistieren, aber Inline-Eval-Träger werden nicht automatisch persistiert.
Standardmäßig sichere Binaries:
Standardmäßige sichere Binaries:
[//]: # "SAFE_BIN_DEFAULTS:START"
@ -337,214 +336,214 @@ Standardmäßig sichere Binaries:
[//]: # "SAFE_BIN_DEFAULTS:END"
`grep` und `sort` sind nicht in der Standardliste enthalten. Wenn Sie sich bewusst dafür entscheiden, behalten Sie explizite Einträge in der Zulassungsliste für
deren Workflows, die nicht nur stdin verwenden.
`grep` und `sort` sind nicht in der Standardliste. Wenn Sie sie aktivieren, behalten Sie explizite Allowlist-Einträge für
ihre Nicht-stdin-Workflows bei.
Für `grep` im Safe-Bin-Modus geben Sie das Muster mit `-e`/`--regexp` an; die
positionale Musterform wird abgelehnt, damit Dateiopeanden nicht als mehrdeutige positionale Argumente eingeschleust werden können.
positionale Musterform wird abgelehnt, damit Dateiopeanden nicht als mehrdeutige positionale Argumente eingeschmuggelt werden können.
### Sichere Binaries im Vergleich zur Zulassungsliste
### Sichere Binaries im Vergleich zur Allowlist
| Thema | `tools.exec.safeBins` | Zulassungsliste (`exec-approvals.json`) |
| Thema | `tools.exec.safeBins` | Allowlist (`exec-approvals.json`) |
| ---------------- | ------------------------------------------------------ | ------------------------------------------------------------ |
| Ziel | Schmale stdin-Filter automatisch erlauben | Bestimmten Executables explizit vertrauen |
| Abgleichstyp | Executable-Name + argv-Richtlinie für sichere Binaries | Glob-Muster des aufgelösten Executable-Pfads |
| Argumentbereich | Durch Safe-Bin-Profil und Literal-Token-Regeln eingeschränkt | Nur Pfadabgleich; Argumente liegen sonst in Ihrer Verantwortung |
| Typische Beispiele | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, benutzerdefinierte CLIs |
| Ziel | Enge stdin-Filter automatisch erlauben | Bestimmten ausführbaren Dateien explizit vertrauen |
| Übereinstimmungstyp | Name der ausführbaren Datei + Safe-Bin-argv-Richtlinie | Glob-Muster für aufgelösten Pfad der ausführbaren Datei |
| Argumentbereich | Durch Safe-Bin-Profil und Regeln für Literal-Tokens eingeschränkt | Nur Pfadabgleich; Argumente liegen ansonsten in Ihrer Verantwortung |
| Typische Beispiele | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, benutzerdefinierte CLIs |
| Beste Verwendung | Texttransformationen mit geringem Risiko in Pipelines | Jedes Tool mit breiterem Verhalten oder Nebeneffekten |
Ort der Konfiguration:
Konfigurationsort:
- `safeBins` stammt aus der Konfiguration (`tools.exec.safeBins` oder pro Agent `agents.list[].tools.exec.safeBins`).
- `safeBinTrustedDirs` stammt aus der Konfiguration (`tools.exec.safeBinTrustedDirs` oder pro Agent `agents.list[].tools.exec.safeBinTrustedDirs`).
- `safeBinProfiles` stammt aus der Konfiguration (`tools.exec.safeBinProfiles` oder pro Agent `agents.list[].tools.exec.safeBinProfiles`). Profilschlüssel pro Agent überschreiben globale Schlüssel.
- Einträge in der Zulassungsliste liegen hostlokal in `~/.openclaw/exec-approvals.json` unter `agents.<id>.allowlist` (oder über die Control UI / `openclaw approvals allowlist ...`).
- `safeBins` kommt aus der Konfiguration (`tools.exec.safeBins` oder pro Agent `agents.list[].tools.exec.safeBins`).
- `safeBinTrustedDirs` kommt aus der Konfiguration (`tools.exec.safeBinTrustedDirs` oder pro Agent `agents.list[].tools.exec.safeBinTrustedDirs`).
- `safeBinProfiles` kommt aus der Konfiguration (`tools.exec.safeBinProfiles` oder pro Agent `agents.list[].tools.exec.safeBinProfiles`). Profilschlüssel pro Agent überschreiben globale Schlüssel.
- Allowlist-Einträge liegen in der hostlokalen `~/.openclaw/exec-approvals.json` unter `agents.<id>.allowlist` (oder über die Control UI / `openclaw approvals allowlist ...`).
- `openclaw security audit` warnt mit `tools.exec.safe_bins_interpreter_unprofiled`, wenn Interpreter-/Runtime-Binaries in `safeBins` ohne explizite Profile erscheinen.
- `openclaw doctor --fix` kann fehlende benutzerdefinierte `safeBinProfiles.<bin>`-Einträge als `{}` erzeugen (anschließend prüfen und verschärfen). Interpreter-/Runtime-Binaries werden nicht automatisch erzeugt.
- `openclaw doctor --fix` kann fehlende benutzerdefinierte `safeBinProfiles.<bin>`-Einträge als `{}` vorbereiten (anschließend prüfen und verschärfen). Interpreter-/Runtime-Binaries werden nicht automatisch vorbereitet.
Beispiel für ein benutzerdefiniertes Profil:
__OC_I18N_900005__
Wenn Sie `jq` explizit in `safeBins` aufnehmen, lehnt OpenClaw das Built-in `env` im Safe-Bin-
Modus dennoch ab, sodass `jq -n env` die Host-Prozessumgebung nicht ohne einen expliziten Pfad in der Zulassungsliste
oder eine Freigabeaufforderung ausgeben kann.
Modus weiterhin ab, sodass `jq -n env` die Host-Prozessumgebung nicht ohne expliziten Allowlist-Pfad
oder Genehmigungsabfrage ausgeben kann.
## Bearbeitung in der Control UI
## Bearbeiten in der Control UI
Verwenden Sie **Control UI → Nodes → Exec approvals**, um Standardwerte, agentbezogene
Überschreibungen und Zulassungslisten zu bearbeiten. Wählen Sie einen Geltungsbereich (Standardwerte oder einen Agent), passen Sie die Richtlinie an,
fügen Sie Muster für die Zulassungsliste hinzu oder entfernen Sie sie und klicken Sie dann auf **Save**. Die UI zeigt Metadaten zu **last used**
pro Muster an, damit Sie die Liste übersichtlich halten können.
Verwenden Sie die Karte **Control UI → Nodes → Exec approvals**, um Standardwerte, agentbezogene
Überschreibungen und Allowlists zu bearbeiten. Wählen Sie einen Geltungsbereich (Standards oder einen Agenten), passen Sie die Richtlinie an,
fügen Sie Allowlist-Muster hinzu/entfernen Sie sie und klicken Sie dann auf **Save**. Die UI zeigt
pro Muster Metadaten zu **last used** an, damit Sie die Liste übersichtlich halten können.
Mit der Zielauswahl wählen Sie **Gateway** (lokale Freigaben) oder einen **Node**. Nodes
müssen `system.execApprovals.get/set` ankündigen (macOS-App oder kopfloser Node-Host).
Wenn ein Node noch keine Ausführungsfreigaben ankündigt, bearbeiten Sie seine lokale
Die Zielauswahl wählt **Gateway** (lokale Genehmigungen) oder einen **Node**. Nodes
müssen `system.execApprovals.get/set` ankündigen (macOS-App oder Headless-Node-Host).
Wenn ein Node noch keine Exec-Genehmigungen ankündigt, bearbeiten Sie seine lokale
`~/.openclaw/exec-approvals.json` direkt.
CLI: `openclaw approvals` unterstützt die Bearbeitung für Gateway oder Node (siehe [Approvals CLI](/cli/approvals)).
CLI: `openclaw approvals` unterstützt das Bearbeiten von Gateway oder Node (siehe [Approvals CLI](/cli/approvals)).
## Freigabeablauf
## Genehmigungsablauf
Wenn eine Eingabeaufforderung erforderlich ist, sendet das Gateway `exec.approval.requested` an Operator-Clients.
Die Control UI und die macOS-App lösen dies über `exec.approval.resolve` auf, dann leitet das Gateway die
genehmigte Anforderung an den Node-Host weiter.
Wenn eine Rückfrage erforderlich ist, sendet das Gateway `exec.approval.requested` an Operator-Clients.
Die Control UI und die macOS-App lösen dies über `exec.approval.resolve` auf, danach leitet das Gateway die
genehmigte Anfrage an den Node-Host weiter.
Für `host=node` enthalten Freigabeanforderungen eine kanonische `systemRunPlan`-Payload. Das Gateway verwendet
diesen Plan als maßgeblichen Kontext für Befehl/cwd/Sitzung, wenn genehmigte `system.run`-
Anforderungen weitergeleitet werden.
Für `host=node` enthalten Genehmigungsanfragen eine kanonische Payload `systemRunPlan`. Das Gateway verwendet
diesen Plan als maßgeblichen Befehls-/cwd-/Sitzungskontext, wenn genehmigte `system.run`-
Anfragen weitergeleitet werden.
Das ist für asynchrone Latenz bei Freigaben wichtig:
Das ist wichtig für die Latenz asynchroner Genehmigungen:
- der Node-Exec-Pfad bereitet im Voraus einen kanonischen Plan vor
- der Freigabedatensatz 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 durch den Aufrufer zu vertrauen
- der Node-Exec-Pfad bereitet einen kanonischen Plan im Voraus vor
- der Genehmigungsdatensatz speichert diesen Plan und seine Bindungsmetadaten
- nach der Genehmigung verwendet der endgültig weitergeleitete `system.run`-Aufruf den gespeicherten Plan erneut,
statt späteren Änderungen des Aufrufers zu vertrauen
- wenn der Aufrufer `command`, `rawCommand`, `cwd`, `agentId` oder
`sessionKey` ändert, nachdem die Freigabeanforderung erstellt wurde, lehnt das Gateway die
weitergeleitete Ausführung als Freigabe-Nichtübereinstimmung ab
`sessionKey` ändert, nachdem die Genehmigungsanfrage erstellt wurde, lehnt das Gateway die
weitergeleitete Ausführung als Genehmigungsabweichung ab
## Interpreter-/Runtime-Befehle
Durch Freigaben abgesicherte Interpreter-/Runtime-Ausführungen sind absichtlich konservativ:
Genehmigungsgestützte Interpreter-/Runtime-Ausführungen sind absichtlich konservativ:
- Exakter Kontext aus argv/cwd/env wird immer gebunden.
- Direkte Shell-Skript- und direkte Runtime-Dateiformen werden nach bestem Bemühen an einen konkreten lokalen
- Exakter argv-/cwd-/env-Kontext wird immer gebunden.
- Direkte Shell-Skript- und direkte Runtime-Dateiformen werden bestmöglich an genau einen konkreten lokalen
Dateisnapshot gebunden.
- Häufige Paketmanager-Wrapper-Formen, die sich dennoch zu einer direkten lokalen Datei auflösen lassen (zum Beispiel
- Häufige Paketmanager-Wrapper-Formen, die sich trotzdem zu genau einer direkten lokalen Datei auflösen (zum Beispiel
`pnpm exec`, `pnpm node`, `npm exec`, `npx`), werden vor der Bindung entpackt.
- Wenn OpenClaw für einen Interpreter-/Runtime-Befehl nicht genau eine konkrete lokale Datei identifizieren kann
(zum Beispiel Paketskripte, Eval-Formen, runtime-spezifische Loader-Ketten oder mehrdeutige Formen mit mehreren Dateien),
wird die durch Freigaben abgesicherte Ausführung verweigert, statt semantische Abdeckung zu behaupten, die tatsächlich
nicht vorhanden ist.
- Für diese Workflows sollten Sie Sandboxing, eine separate Host-Grenze oder einen expliziten vertrauenswürdigen
Workflow mit Zulassungsliste/full bevorzugen, bei dem der Operator die breitere Runtime-Semantik akzeptiert.
(zum Beispiel Paketskripte, Eval-Formen, Runtime-spezifische Loader-Ketten oder mehrdeutige Mehrdatei-
Formen), wird die genehmigungsgestützte Ausführung abgelehnt, statt semantische Abdeckung zu behaupten, die sie nicht
hat.
- Für solche Workflows bevorzugen Sie Sandboxing, eine separate Host-Grenze oder einen explizit vertrauenswürdigen
Allowlist-/Full-Workflow, bei dem der Operator die weitergehende Runtime-Semantik akzeptiert.
Wenn Freigaben erforderlich sind, gibt das Exec-Tool sofort eine Freigabe-ID zurück. Verwenden Sie diese ID, um
spätere Systemereignisse zuzuordnen (`Exec finished` / `Exec denied`). Wenn vor dem
Timeout keine Entscheidung eintrifft, wird die Anforderung als Freigabe-Timeout behandelt und als Grund für die Verweigerung angezeigt.
Wenn Genehmigungen erforderlich sind, gibt das Exec-Tool sofort mit einer Genehmigungs-ID zurück. Verwenden Sie diese ID, um
spätere Systemereignisse (`Exec finished` / `Exec denied`) zuzuordnen. Wenn vor dem
Timeout keine Entscheidung eingeht, wird die Anfrage als Genehmigungs-Timeout behandelt und als Ablehnungsgrund ausgegeben.
### Verhalten bei der Zustellung von Folgeaktionen
### Verhalten bei Follow-up-Zustellung
Nachdem eine genehmigte asynchrone Ausführung abgeschlossen ist, sendet OpenClaw einen nachfolgenden `agent`-Turn an dieselbe Sitzung.
Nachdem ein genehmigter asynchroner Exec abgeschlossen ist, sendet OpenClaw einen Follow-up-Turn des Typs `agent` an dieselbe Sitzung.
- Wenn ein gültiges externes Zustellziel vorhanden ist (zustellbarer Kanal plus Ziel `to`), verwendet die Zustellung der Folgeaktion diesen Kanal.
- In reinem Webchat oder internen Sitzungsabläufen ohne externes Ziel bleibt die Zustellung der Folgeaktion nur sitzungsintern (`deliver: false`).
- Wenn ein Aufrufer explizit eine strikte externe Zustellung anfordert, aber kein externer Kanal aufgelöst werden kann, schlägt die Anforderung mit `INVALID_REQUEST` fehl.
- Wenn `bestEffortDeliver` aktiviert ist und kein externer Kanal aufgelöst werden kann, wird die Zustellung statt eines Fehlers auf nur sitzungsintern herabgestuft.
- Wenn ein gültiges externes Zustellungsziel existiert (zustellbarer Channel plus Ziel `to`), verwendet die Follow-up-Zustellung diesen Channel.
- In reinen Webchat- oder internen Sitzungsabläufen ohne externes Ziel bleibt die Follow-up-Zustellung sitzungsintern (`deliver: false`).
- Wenn ein Aufrufer explizit strikte externe Zustellung anfordert, aber kein externer Channel aufgelöst werden kann, schlägt die Anfrage mit `INVALID_REQUEST` fehl.
- Wenn `bestEffortDeliver` aktiviert ist und kein externer Channel aufgelöst werden kann, wird die Zustellung auf sitzungsintern herabgestuft, statt fehlzuschlagen.
Der Bestätigungsdialog enthält:
- Befehl + Argumente
- cwd
- Agent-ID
- aufgelöster Executable-Pfad
- Host- und Richtlinienmetadaten
- aufgelösten Pfad der ausführbaren Datei
- Host- + Richtlinienmetadaten
Aktionen:
- **Allow once** → jetzt ausführen
- **Always allow** → zur Zulassungsliste hinzufügen + ausführen
- **Always allow** → zur Allowlist hinzufügen + ausführen
- **Deny** → blockieren
## Weiterleitung von Freigaben an Chat-Kanäle
## Genehmigungsweiterleitung an Chat-Channels
Sie können Aufforderungen für Exec-Freigaben an jeden Chat-Kanal weiterleiten (einschließlich Plugin-Kanälen) und sie
mit `/approve` genehmigen. Dies verwendet die normale Pipeline für ausgehende Zustellung.
Sie können Exec-Genehmigungsabfragen an jeden Chat-Channel (einschließlich Plugin-Channels) weiterleiten und
sie mit `/approve` genehmigen. Dies verwendet die normale Pipeline für ausgehende Zustellung.
Konfiguration:
__OC_I18N_900006__
Antwort im Chat:
__OC_I18N_900007__
Der Befehl `/approve` verarbeitet sowohl Exec-Freigaben als auch Plugin-Freigaben. Wenn die ID nicht zu einer ausstehenden Exec-Freigabe passt, wird automatisch stattdessen nach Plugin-Freigaben gesucht.
Der Befehl `/approve` verarbeitet sowohl Exec-Genehmigungen als auch Plugin-Genehmigungen. Wenn die ID nicht zu einer ausstehenden Exec-Genehmigung passt, prüft er automatisch stattdessen Plugin-Genehmigungen.
### Weiterleitung von Plugin-Freigaben
### Weiterleitung von Plugin-Genehmigungen
Die Weiterleitung von Plugin-Freigaben verwendet dieselbe Zustellungspipeline wie Exec-Freigaben, hat aber eine eigene
unabhängige Konfiguration unter `approvals.plugin`. Das Aktivieren oder Deaktivieren der einen hat keine Auswirkungen auf die andere.
Die Weiterleitung von Plugin-Genehmigungen verwendet dieselbe Zustellungspipeline wie Exec-Genehmigungen, hat aber eine eigene
unabhängige Konfiguration unter `approvals.plugin`. Das Aktivieren oder Deaktivieren der einen wirkt sich nicht auf die andere aus.
__OC_I18N_900008__
Die Konfigurationsstruktur ist identisch mit `approvals.exec`: `enabled`, `mode`, `agentFilter`,
`sessionFilter` und `targets` funktionieren gleich.
Die Form der Konfiguration ist identisch mit `approvals.exec`: `enabled`, `mode`, `agentFilter`,
`sessionFilter` und `targets` funktionieren auf dieselbe Weise.
Kanäle, die gemeinsame interaktive Antworten unterstützen, stellen für Exec- und
Plugin-Freigaben dieselben Freigabeschaltflächen dar. Kanäle ohne gemeinsame interaktive UI greifen auf Klartext mit
Anweisungen für `/approve` zurück.
Channels, die gemeinsame interaktive Antworten unterstützen, rendern dieselben Genehmigungsbuttons sowohl für Exec- als auch für
Plugin-Genehmigungen. Channels ohne gemeinsame interaktive UI fallen auf Klartext mit `/approve`-
Anweisungen zurück.
### Freigaben im selben Chat auf jedem Kanal
### Genehmigungen im selben Chat auf jedem Channel
Wenn eine Exec- oder Plugin-Freigabeanforderung von einer zustellbaren Chat-Oberfläche stammt, kann derselbe Chat sie
nun standardmäßig mit `/approve` genehmigen. Das gilt für Kanäle wie Slack, Matrix und
Microsoft Teams zusätzlich zu den bereits vorhandenen Abläufen in Web-UI und Terminal-UI.
Wenn eine Exec- oder Plugin-Genehmigungsanfrage von einer zustellbaren Chat-Oberfläche ausgeht, kann derselbe Chat
sie jetzt standardmäßig mit `/approve` genehmigen. Dies gilt für Channels wie Slack, Matrix und
Microsoft Teams zusätzlich zu den bestehenden Abläufen über Web-UI und Terminal-UI.
Dieser gemeinsame Pfad über Textbefehle verwendet das normale Kanal-Authentifizierungsmodell für diese Unterhaltung. Wenn der
ursprüngliche Chat bereits Befehle senden und Antworten empfangen kann, benötigen Freigabeanforderungen keinen
separaten nativen Zustelladapter mehr, nur damit sie ausstehend bleiben.
Dieser gemeinsame Textbefehlsweg verwendet das normale Channel-Auth-Modell für diese Konversation. Wenn der
ursprüngliche Chat bereits Befehle senden und Antworten empfangen kann, benötigen Genehmigungsanfragen nicht länger einen
separaten nativen Zustellungsadapter, nur um ausstehend zu bleiben.
Discord und Telegram unterstützen ebenfalls `/approve` im selben Chat, aber diese Kanäle verwenden weiterhin ihre
aufgelöste Liste zulässiger Genehmiger zur Autorisierung, auch wenn die native Freigabezustellung deaktiviert ist.
Discord und Telegram unterstützen ebenfalls `/approve` im selben Chat, aber diese Channels verwenden weiterhin ihre
aufgelöste Liste der Genehmigenden für die Autorisierung, selbst wenn native Genehmigungszustellung deaktiviert ist.
Für Telegram und andere native Freigabe-Clients, die das Gateway direkt aufrufen,
ist dieses Fallback absichtlich auf Fehler vom Typ „Freigabe nicht gefunden“ begrenzt. Eine echte
Exec-Freigabeverweigerung bzw. ein echter Fehler wird nicht stillschweigend als Plugin-Freigabe erneut versucht.
Für Telegram und andere native Genehmigungsclients, die das Gateway direkt aufrufen,
ist dieser Fallback absichtlich auf Fehler „Genehmigung nicht gefunden“ begrenzt. Ein echter
Exec-Genehmigungsfehler bzw. eine echte Ablehnung wird nicht stillschweigend erneut als Plugin-Genehmigung versucht.
### Native Freigabezustellung
### Native Genehmigungszustellung
Einige Kanäle können außerdem als native Freigabe-Clients fungieren. Native Clients ergänzen Genehmiger-DMs, Fanout an den Ursprungs-Chat
und kanalspezifische interaktive UX für Freigaben zusätzlich zum gemeinsamen `/approve`-Ablauf im selben Chat.
Einige Channels können auch als native Genehmigungsclients fungieren. Native Clients fügen DMs für Genehmigende, Fanout in den Ursprungs-Chat
und kanalspezifische interaktive Genehmigungs-UX zusätzlich zum gemeinsamen `/approve`-Ablauf im selben Chat hinzu.
Wenn native Freigabekarten/-schaltflächen verfügbar sind, ist diese native UI der primäre
agentseitige Pfad. Der Agent sollte dann nicht zusätzlich einen doppelten einfachen Chat-
Befehl `/approve` ausgeben, es sei denn, das Tool-Ergebnis sagt, dass Chat-Freigaben nicht verfügbar sind oder
eine manuelle Freigabe der einzige verbleibende Pfad ist.
Wenn native Genehmigungskarten/-Buttons verfügbar sind, ist diese native UI der primäre
agentenseitige Pfad. Der Agent sollte dann nicht zusätzlich einen doppelten Klartext-
Befehl `/approve` im Chat ausgeben, außer wenn das Tool-Ergebnis sagt, dass Chat-Genehmigungen nicht verfügbar sind oder
manuelle Genehmigung der einzig verbleibende Weg ist.
Allgemeines Modell:
- die Host-Exec-Richtlinie entscheidet weiterhin, ob eine Exec-Freigabe erforderlich ist
- `approvals.exec` steuert die Weiterleitung von Freigabeaufforderungen an andere Chat-Ziele
- `channels.<channel>.execApprovals` steuert, ob dieser Kanal als nativer Freigabe-Client fungiert
- die Host-Exec-Richtlinie entscheidet weiterhin, ob eine Exec-Genehmigung erforderlich ist
- `approvals.exec` steuert die Weiterleitung von Genehmigungsabfragen an andere Chat-Ziele
- `channels.<channel>.execApprovals` steuert, ob dieser Channel als nativer Genehmigungsclient fungiert
Native Freigabe-Clients aktivieren automatisch DM-first-Zustellung, wenn alle folgenden Bedingungen erfüllt sind:
Native Genehmigungsclients aktivieren standardmäßig automatisch eine Zustellung mit DMs an Genehmigende zuerst, wenn all dies zutrifft:
- der Kanal unterstützt native Freigabezustellung
- Genehmiger können aus explizitem `execApprovals.approvers` oder den
dokumentierten Fallback-Quellen dieses Kanals aufgelöst werden
- der Channel unterstützt native Genehmigungszustellung
- Genehmigende können aus expliziten `execApprovals.approvers` oder den
dokumentierten Fallback-Quellen dieses Channels aufgelöst werden
- `channels.<channel>.execApprovals.enabled` ist nicht gesetzt oder `"auto"`
Setzen Sie `enabled: false`, um einen nativen Freigabe-Client explizit zu deaktivieren. Setzen Sie `enabled: true`, um ihn
zu erzwingen, wenn Genehmiger aufgelöst werden. Öffentliche Zustellung an den Ursprungs-Chat bleibt explizit über
Setzen Sie `enabled: false`, um einen nativen Genehmigungsclient explizit zu deaktivieren. Setzen Sie `enabled: true`, um
ihn zu erzwingen, wenn Genehmigende aufgelöst werden. Öffentliche Zustellung an den Ursprungs-Chat bleibt explizit über
`channels.<channel>.execApprovals.target`.
FAQ: [Warum gibt es zwei Konfigurationen für Exec-Freigaben bei Chat-Freigaben?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals)
FAQ: [Warum gibt es zwei Exec-Genehmigungskonfigurationen für Chat-Genehmigungen?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals)
- Discord: `channels.discord.execApprovals.*`
- Slack: `channels.slack.execApprovals.*`
- Telegram: `channels.telegram.execApprovals.*`
Diese nativen Freigabe-Clients ergänzen DM-Routing und optionales Fanout an den Kanal zusätzlich zum gemeinsamen
`/approve`-Ablauf im selben Chat und den gemeinsamen Freigabeschaltflächen.
Diese nativen Genehmigungsclients fügen DM-Routing und optionales Channel-Fanout zusätzlich zum gemeinsamen
`/approve`-Ablauf im selben Chat und den gemeinsamen Genehmigungsbuttons hinzu.
Gemeinsames Verhalten:
- Slack, Matrix, Microsoft Teams und ähnliche zustellbare Chats verwenden das normale Kanal-Authentifizierungsmodell
- Slack, Matrix, Microsoft Teams und ähnliche zustellbare Chats verwenden das normale Channel-Auth-Modell
für `/approve` im selben Chat
- wenn ein nativer Freigabe-Client automatisch aktiviert wird, ist das Standardziel für die native Zustellung Genehmiger-DMs
- für Discord und Telegram können nur aufgelöste Genehmiger genehmigen oder verweigern
- Discord-Genehmiger können explizit sein (`execApprovals.approvers`) oder aus `commands.ownerAllowFrom` abgeleitet werden
- Telegram-Genehmiger können explizit sein (`execApprovals.approvers`) oder aus bestehender Eigentümerkonfiguration abgeleitet werden (`allowFrom`, plus `defaultTo` für Direktnachrichten, wo unterstützt)
- Slack-Genehmiger können explizit sein (`execApprovals.approvers`) oder aus `commands.ownerAllowFrom` abgeleitet werden
- native Slack-Schaltflächen behalten die Art der Freigabe-ID bei, sodass `plugin:`-IDs Plugin-Freigaben
- wenn ein nativer Genehmigungsclient automatisch aktiviert wird, ist das standardmäßige native Zustellungsziel DMs für Genehmigende
- bei Discord und Telegram können nur aufgelöste Genehmigende genehmigen oder ablehnen
- Discord-Genehmigende können explizit sein (`execApprovals.approvers`) oder aus `commands.ownerAllowFrom` abgeleitet werden
- Telegram-Genehmigende können explizit sein (`execApprovals.approvers`) oder aus vorhandener Owner-Konfiguration abgeleitet werden (`allowFrom`, plus `defaultTo` für Direktnachrichten, wo unterstützt)
- Slack-Genehmigende können explizit sein (`execApprovals.approvers`) oder aus `commands.ownerAllowFrom` abgeleitet werden
- native Slack-Buttons bewahren die Art der Genehmigungs-ID, sodass `plugin:`-IDs Plugin-Genehmigungen
ohne eine zweite Slack-lokale Fallback-Ebene auflösen können
- natives Matrix-DM-/Kanal-Routing und Reaktionskürzel verarbeiten sowohl Exec- als auch Plugin-Freigaben;
die Plugin-Autorisierung kommt weiterhin von `channels.matrix.dm.allowFrom`
- der Anforderer muss kein Genehmiger sein
- natives Matrix-DM-/Channel-Routing und Reaktionskürzel verarbeiten sowohl Exec- als auch Plugin-Genehmigungen;
die Plugin-Autorisierung kommt weiterhin aus `channels.matrix.dm.allowFrom`
- der Anfragende muss kein Genehmigender sein
- der Ursprungs-Chat kann direkt mit `/approve` genehmigen, wenn dieser Chat bereits Befehle und Antworten unterstützt
- native Discord-Freigabeschaltflächen routen nach Art der Freigabe-ID: `plugin:`-IDs gehen
direkt zu Plugin-Freigaben, alles andere zu Exec-Freigaben
- native Telegram-Freigabeschaltflächen folgen demselben begrenzten Exec-zu-Plugin-Fallback wie `/approve`
- wenn natives `target` die Zustellung an den Ursprungs-Chat aktiviert, enthalten Freigabeaufforderungen den Befehlstext
- ausstehende Exec-Freigaben laufen standardmäßig nach 30 Minuten ab
- wenn keine Operator-UI oder kein konfigurierter Freigabe-Client die Anforderung annehmen kann, fällt die Aufforderung auf `askFallback` zurück
- native Discord-Genehmigungsbuttons routen nach Art der Genehmigungs-ID: `plugin:`-IDs gehen
direkt zu Plugin-Genehmigungen, alles andere geht zu Exec-Genehmigungen
- native Telegram-Genehmigungsbuttons folgen demselben begrenzten Exec-zu-Plugin-Fallback wie `/approve`
- wenn natives `target` die Zustellung an den Ursprungs-Chat aktiviert, enthalten Genehmigungsabfragen den Befehlstext
- ausstehende Exec-Genehmigungen laufen standardmäßig nach 30 Minuten ab
- wenn keine Operator-UI oder kein konfigurierter Genehmigungsclient die Anfrage annehmen kann, fällt die Abfrage auf `askFallback` zurück
Telegram verwendet standardmäßig Genehmiger-DMs (`target: "dm"`). Sie können zu `channel` oder `both` wechseln, wenn Sie
möchten, dass Freigabeaufforderungen auch im ursprünglichen Telegram-Chat/-Thema erscheinen. Bei Telegram-Forenthemen
bewahrt OpenClaw das Thema für die Freigabeaufforderung und die Folgeaktion nach der Freigabe.
Telegram verwendet standardmäßig DMs an Genehmigende (`target: "dm"`). Sie können zu `channel` oder `both` wechseln, wenn Sie möchten,
dass Genehmigungsabfragen auch im ursprünglichen Telegram-Chat/Topic erscheinen. Bei Telegram-Forenthemen
bewahrt OpenClaw das Thema sowohl für die Genehmigungsabfrage als auch für das Follow-up nach der Genehmigung.
Siehe:
@ -555,38 +554,38 @@ Siehe:
__OC_I18N_900009__
Sicherheitshinweise:
- Unix-Socket-Modus `0600`, Token wird in `exec-approvals.json` gespeichert.
- Unix-Socket-Modus `0600`, Token gespeichert in `exec-approvals.json`.
- Same-UID-Peer-Prüfung.
- Challenge/Response (Nonce + HMAC-Token + Request-Hash) + kurze TTL.
## Systemereignisse
Der Lebenszyklus von Exec wird als Systemnachrichten angezeigt:
Der Exec-Lebenszyklus wird als Systemnachrichten angezeigt:
- `Exec running` (nur wenn der Befehl den Schwellenwert für die Laufmeldung überschreitet)
- `Exec finished`
- `Exec denied`
Diese werden in die Sitzung des Agents gepostet, nachdem der Node das Ereignis gemeldet hat.
Exec-Freigaben auf dem Gateway-Host geben dieselben Lebenszyklusereignisse aus, wenn der Befehl abgeschlossen ist (und optional, wenn er länger als den Schwellenwert läuft).
Durch Freigaben geschützte Execs verwenden die Freigabe-ID in diesen Nachrichten erneut als `runId`, damit sie leicht zugeordnet werden können.
Diese werden an die Sitzung des Agenten gesendet, nachdem der Node das Ereignis gemeldet hat.
Genehmigungen für Gateway-Host-Exec erzeugen dieselben Lebenszyklusereignisse, wenn der Befehl abgeschlossen ist (und optional, wenn er länger als der Schwellenwert läuft).
Durch Genehmigungen abgesicherte Execs verwenden in diesen Nachrichten die Genehmigungs-ID erneut als `runId`, damit sie leicht zugeordnet werden können.
## Verhalten bei verweigerter Freigabe
## Verhalten bei abgelehnter Genehmigung
Wenn eine asynchrone Exec-Freigabe verweigert wird, verhindert OpenClaw, dass der Agent
Ausgabe aus einer früheren Ausführung desselben Befehls in der Sitzung wiederverwendet. Der Grund für die Verweigerung
wird mit einem expliziten Hinweis weitergegeben, dass keine Befehlsausgabe verfügbar ist; das verhindert,
dass der Agent behauptet, es gebe neue Ausgabe, oder den verweigerten Befehl mit
veralteten Ergebnissen aus einer früheren erfolgreichen Ausführung wiederholt.
Wenn eine asynchrone Exec-Genehmigung abgelehnt wird, verhindert OpenClaw, dass der Agent
Ausgaben eines früheren Laufs desselben Befehls in der Sitzung wiederverwendet. Der Ablehnungsgrund
wird zusammen mit einer expliziten Anweisung übergeben, dass keine Befehlsausgabe verfügbar ist, was
verhindert, dass der Agent behauptet, es gebe neue Ausgabe, oder den abgelehnten Befehl mit
veralteten Ergebnissen eines früheren erfolgreichen Laufs wiederholt.
## Auswirkungen
- **full** ist leistungsstark; bevorzugen Sie nach Möglichkeit Zulassungslisten.
- **ask** bindet Sie ein, ermöglicht aber weiterhin schnelle Freigaben.
- Zulassungslisten pro Agent verhindern, dass Freigaben eines Agents in andere übergreifen.
- Freigaben gelten nur für Host-Exec-Anforderungen von **autorisierten Absendern**. Nicht autorisierte Absender können kein `/exec` ausführen.
- `/exec security=full` ist eine sitzungsbezogene Komfortfunktion für autorisierte Operatoren und überspringt Freigaben absichtlich.
Um Host-Exec hart zu blockieren, setzen Sie die Freigabesicherheit auf `deny` oder verweigern Sie das Tool `exec` über die Tool-Richtlinie.
- **full** ist mächtig; bevorzugen Sie wenn möglich Allowlists.
- **ask** hält Sie im Ablauf, ermöglicht aber weiterhin schnelle Genehmigungen.
- Allowlists pro Agent verhindern, dass die Genehmigungen eines Agenten in andere übergreifen.
- Genehmigungen gelten nur für Host-Exec-Anfragen von **autorisierten Sendern**. Nicht autorisierte Sender können `/exec` nicht ausführen.
- `/exec security=full` ist eine Sitzungs-Kurzform für autorisierte Operatoren und überspringt Genehmigungen absichtlich.
Um Host-Exec vollständig zu blockieren, setzen Sie die Genehmigungssicherheit auf `deny` oder verweigern Sie das Tool `exec` über die Tool-Richtlinie.
Verwandt:
@ -598,5 +597,5 @@ Verwandt:
- [Exec](/de/tools/exec) — Tool zur Ausführung von Shell-Befehlen
- [Sandboxing](/de/gateway/sandboxing) — Sandbox-Modi und Workspace-Zugriff
- [Security](/de/gateway/security) — Sicherheitsmodell und Härtung
- [Sandbox vs Tool Policy vs Elevated](/de/gateway/sandbox-vs-tool-policy-vs-elevated) — wann welches verwendet werden sollte
- [Sicherheit](/de/gateway/security) — Sicherheitsmodell und Härtung
- [Sandbox vs Tool-Richtlinie vs Elevated](/de/gateway/sandbox-vs-tool-policy-vs-elevated) — wann was verwendet werden sollte

180
docs/de/tools/exec.md
View File

@ -1,85 +1,85 @@
---
read_when:
- Verwenden oder Ändern des Exec-Tools
- Debuggen des stdin- oder TTY-Verhaltens
- Fehlerbehebung beim stdin- oder TTY-Verhalten
summary: Verwendung des Exec-Tools, stdin-Modi und TTY-Unterstützung
title: Exec-Tool
x-i18n:
generated_at: "2026-04-06T03:13:03Z"
generated_at: "2026-04-21T13:37:32Z"
model: gpt-5.4
provider: openai
source_hash: 28388971c627292dba9bf65ae38d7af8cde49a33bb3b5fc8b20da4f0e350bedd
source_hash: 5018468f31bb76fc142ddef7002c7bbc617406de7ce912670d1b9edef6a9a042
source_path: tools/exec.md
workflow: 15
---
# Exec-Tool
Führt Shell-Befehle im Workspace aus. Unterstützt Ausführung im Vordergrund und Hintergrund über `process`.
Wenn `process` nicht erlaubt ist, läuft `exec` synchron und ignoriert `yieldMs`/`background`.
Hintergrundsitzungen sind pro Agent begrenzt; `process` sieht nur Sitzungen desselben Agents.
Führen Sie Shell-Befehle im Workspace aus. Unterstützt Vordergrund- und Hintergrundausführung über `process`.
Wenn `process` nicht erlaubt ist, wird `exec` synchron ausgeführt und ignoriert `yieldMs`/`background`.
Hintergrundsitzungen sind pro Agent begrenzt; `process` sieht nur Sitzungen desselben Agenten.
## Parameter
- `command` (erforderlich)
- `workdir` (Standard: cwd)
- `env` (Überschreibungen für Schlüssel/Wert)
- `yieldMs` (Standard 10000): automatischer Hintergrundmodus nach Verzögerung
- `workdir` (Standard ist cwd)
- `env` (Schlüssel-/Wert-Überschreibungen)
- `yieldMs` (Standard 10000): nach Verzögerung automatisch in den Hintergrund
- `background` (bool): sofort im Hintergrund ausführen
- `timeout` (Sekunden, Standard 1800): bei Ablauf beenden
- `pty` (bool): in einem Pseudo-Terminal ausführen, wenn verfügbar (TTY-only-CLIs, Coding-Agents, Terminal-UIs)
- `pty` (bool): in einem Pseudo-Terminal ausführen, wenn verfügbar (nur-TTY-CLIs, Coding-Agents, Terminal-UIs)
- `host` (`auto | sandbox | gateway | node`): wo ausgeführt werden soll
- `security` (`deny | allowlist | full`): Durchsetzungsmodus für `gateway`/`node`
- `ask` (`off | on-miss | always`): Genehmigungsaufforderungen für `gateway`/`node`
- `security` (`deny | allowlist | full`): Erzwingungsmodus für `gateway`/`node`
- `ask` (`off | on-miss | always`): Freigabeaufforderungen für `gateway`/`node`
- `node` (string): Node-ID/-Name für `host=node`
- `elevated` (bool): erhöhten Modus anfordern (aus der Sandbox auf den konfigurierten Host-Pfad ausbrechen); `security=full` wird nur erzwungen, wenn `elevated` zu `full` aufgelöst wird
- `elevated` (bool): erhöhten Modus anfordern (die Sandbox verlassen und auf dem konfigurierten Host-Pfad ausführen); `security=full` wird nur erzwungen, wenn `elevated` zu `full` aufgelöst wird
Hinweise:
- `host` verwendet standardmäßig `auto`: Sandbox, wenn die Sandbox-Laufzeit für die Sitzung aktiv ist, sonst Gateway.
- `auto` ist die Standard-Routing-Strategie, kein Wildcard. `host=node` pro Aufruf ist aus `auto` heraus erlaubt; `host=gateway` pro Aufruf ist nur erlaubt, wenn keine Sandbox-Laufzeit aktiv ist.
- Ohne zusätzliche Konfiguration funktioniert `host=auto` weiterhin einfach: keine Sandbox bedeutet Auflösung zu `gateway`; eine aktive Sandbox bedeutet, dass in der Sandbox geblieben wird.
- `elevated` verlässt die Sandbox auf den konfigurierten Host-Pfad: standardmäßig `gateway` oder `node`, wenn `tools.exec.host=node` gesetzt ist (oder die Sitzungsstandardeinstellung `host=node` ist). Es ist nur verfügbar, wenn erhöhter Zugriff für die aktuelle Sitzung bzw. den aktuellen Provider aktiviert ist.
- Genehmigungen für `gateway`/`node` werden über `~/.openclaw/exec-approvals.json` gesteuert.
- `node` erfordert einen gekoppelten Node (Begleit-App oder headless Node-Host).
- `host` hat standardmäßig `auto`: `sandbox`, wenn die Sandbox-Runtime für die Sitzung aktiv ist, andernfalls `gateway`.
- `auto` ist die Standard-Routing-Strategie, kein Platzhalter. Pro Aufruf ist `host=node` von `auto` aus erlaubt; pro Aufruf ist `host=gateway` nur erlaubt, wenn keine Sandbox-Runtime aktiv ist.
- Ohne zusätzliche Konfiguration funktioniert `host=auto` weiterhin „einfach so“: ohne Sandbox wird es zu `gateway`; mit aktiver Sandbox bleibt es in der Sandbox.
- `elevated` verlässt die Sandbox auf den konfigurierten Host-Pfad: standardmäßig `gateway` oder `node`, wenn `tools.exec.host=node` gesetzt ist (oder der Sitzungsstandard `host=node` ist). Es ist nur verfügbar, wenn erhöhter Zugriff für die aktuelle Sitzung/den aktuellen Provider aktiviert ist.
- `gateway`-/`node`-Freigaben werden über `~/.openclaw/exec-approvals.json` gesteuert.
- `node` erfordert einen gepairten Node (Companion-App oder Headless-Node-Host).
- Wenn mehrere Nodes verfügbar sind, setzen Sie `exec.node` oder `tools.exec.node`, um einen auszuwählen.
- `exec host=node` ist der einzige Shell-Ausführungspfad für Nodes; der Legacy-Wrapper `nodes.run` wurde entfernt.
- Auf Nicht-Windows-Hosts verwendet exec `SHELL`, wenn gesetzt; wenn `SHELL` auf `fish` gesetzt ist, wird `bash` (oder `sh`)
aus `PATH` bevorzugt, um mit fish inkompatible Skripte zu vermeiden, und erst dann auf `SHELL` zurückgegriffen, wenn keines von beiden existiert.
- Auf Windows-Hosts bevorzugt exec die Erkennung von PowerShell 7 (`pwsh`) (Program Files, ProgramW6432, dann PATH),
und fällt dann auf Windows PowerShell 5.1 zurück.
- Auf Nicht-Windows-Hosts verwendet `exec` `SHELL`, wenn gesetzt; wenn `SHELL` `fish` ist, bevorzugt es `bash` (oder `sh`)
aus `PATH`, um mit `fish` inkompatible Skripte zu vermeiden, und fällt dann auf `SHELL` zurück, wenn keines von beiden existiert.
- Auf Windows-Hosts bevorzugt `exec` die Erkennung von PowerShell 7 (`pwsh`) (Program Files, ProgramW6432, dann PATH)
und fällt danach auf Windows PowerShell 5.1 zurück.
- Host-Ausführung (`gateway`/`node`) lehnt `env.PATH` und Loader-Überschreibungen (`LD_*`/`DYLD_*`) ab, um
Binary-Hijacking oder eingeschleusten Code zu verhindern.
- OpenClaw setzt `OPENCLAW_SHELL=exec` in der Umgebungsvariablen des gestarteten Befehls (einschließlich PTY- und Sandbox-Ausführung), damit Shell-/Profilregeln den Kontext des Exec-Tools erkennen können.
Binary-Hijacking oder injizierten Code zu verhindern.
- OpenClaw setzt `OPENCLAW_SHELL=exec` in der Umgebung des gestarteten Befehls (einschließlich PTY- und Sandbox-Ausführung), damit Shell-/Profilregeln den Kontext des Exec-Tools erkennen können.
- Wichtig: Sandboxing ist standardmäßig **deaktiviert**. Wenn Sandboxing deaktiviert ist, wird implizites `host=auto`
zu `gateway` aufgelöst. Explizites `host=sandbox` schlägt weiterhin geschlossen fehl, statt stillschweigend
auf dem Gateway-Host zu laufen. Aktivieren Sie Sandboxing oder verwenden Sie `host=gateway` mit Genehmigungen.
- Script-Preflight-Prüfungen (für häufige Python-/Node-Shell-Syntaxfehler) untersuchen nur Dateien innerhalb der
effektiven `workdir`-Grenze. Wenn ein Skriptpfad außerhalb von `workdir` aufgelöst wird, wird der Preflight für
diese Datei übersprungen.
- Für lang laufende Arbeiten, die jetzt starten, starten Sie sie einmal und verlassen Sie sich auf das automatische
Completion-Wake, wenn es aktiviert ist und der Befehl Ausgabe erzeugt oder fehlschlägt.
Verwenden Sie `process` für Logs, Status, Eingaben oder Eingriffe; emulieren Sie kein
Scheduling mit Sleep-Schleifen, Timeout-Schleifen oder wiederholtem Polling.
- Für Arbeiten, die später oder nach Zeitplan stattfinden sollen, verwenden Sie cron statt
auf dem Gateway-Host auszuführen. Aktivieren Sie Sandboxing oder verwenden Sie `host=gateway` mit Freigaben.
- Skript-Preflight-Prüfungen (für häufige Python-/Node-Shell-Syntaxfehler) prüfen nur Dateien innerhalb der
wirksamen `workdir`-Grenze. Wenn ein Skriptpfad außerhalb von `workdir` aufgelöst wird, wird die Preflight-Prüfung
für diese Datei übersprungen.
- Für lang laufende Arbeit, die jetzt startet, starten Sie sie einmal und verlassen Sie sich auf das automatische
Abschluss-Wake-up, wenn es aktiviert ist und der Befehl Ausgabe erzeugt oder fehlschlägt.
Verwenden Sie `process` für Logs, Status, Eingaben oder Eingriffe; emulieren Sie keine
Planung mit Sleep-Schleifen, Timeout-Schleifen oder wiederholtem Polling.
- Für Arbeit, die später oder nach Zeitplan erfolgen soll, verwenden Sie Cron statt
`exec`-Sleep-/Delay-Mustern.
## Konfiguration
- `tools.exec.notifyOnExit` (Standard: true): Wenn true, stellen im Hintergrund ausgeführte Exec-Sitzungen beim Beenden ein Systemereignis in die Queue und fordern einen Heartbeat an.
- `tools.exec.approvalRunningNoticeMs` (Standard: 10000): sendet einen einzelnen Hinweis „läuft“, wenn ein genehmigungspflichtiger Exec länger als diesen Wert läuft (0 deaktiviert).
- `tools.exec.host` (Standard: `auto`; wird zu `sandbox` aufgelöst, wenn die Sandbox-Laufzeit aktiv ist, sonst zu `gateway`)
- `tools.exec.notifyOnExit` (Standard: true): wenn true, stellen in den Hintergrund verschobene Exec-Sitzungen beim Beenden ein Systemereignis in die Warteschlange und fordern einen Heartbeat an.
- `tools.exec.approvalRunningNoticeMs` (Standard: 10000): gibt genau einen Hinweis „running“ aus, wenn ein freigabegesteuerter Exec länger als dies läuft (0 deaktiviert).
- `tools.exec.host` (Standard: `auto`; wird zu `sandbox` aufgelöst, wenn die Sandbox-Runtime aktiv ist, sonst zu `gateway`)
- `tools.exec.security` (Standard: `deny` für Sandbox, `full` für Gateway + Node, wenn nicht gesetzt)
- `tools.exec.ask` (Standard: `off`)
- Host-Exec ohne Genehmigung ist der Standard für Gateway + Node. Wenn Sie Genehmigungen/Allowlist-Verhalten möchten, verschärfen Sie sowohl `tools.exec.*` als auch die Host-`~/.openclaw/exec-approvals.json`; siehe [Exec approvals](/de/tools/exec-approvals#no-approval-yolo-mode).
- YOLO kommt von den Standardwerten der Host-Richtlinie (`security=full`, `ask=off`), nicht von `host=auto`. Wenn Sie Gateway- oder Node-Routing erzwingen möchten, setzen Sie `tools.exec.host` oder verwenden Sie `/exec host=...`.
- Im Modus `security=full` plus `ask=off` folgt Host-Exec direkt der konfigurierten Richtlinie; es gibt keinen zusätzlichen heuristischen Vorfilter für Befehlsverschleierung.
- Host-Exec ohne Freigabe ist der Standard für Gateway + Node. Wenn Sie Freigaben/Allowlist-Verhalten möchten, verschärfen Sie sowohl `tools.exec.*` als auch die Host-`~/.openclaw/exec-approvals.json`; siehe [Exec approvals](/de/tools/exec-approvals#no-approval-yolo-mode).
- YOLO kommt von den Host-Richtlinienstandards (`security=full`, `ask=off`), nicht von `host=auto`. Wenn Sie Gateway- oder Node-Routing erzwingen möchten, setzen Sie `tools.exec.host` oder verwenden Sie `/exec host=...`.
- Im Modus `security=full` plus `ask=off` folgt Host-Exec direkt der konfigurierten Richtlinie; es gibt keine zusätzliche heuristische Vorfilterung zur Befehlsverschleierung oder zusätzliche Ablehnungsschicht für Skript-Preflight.
- `tools.exec.node` (Standard: nicht gesetzt)
- `tools.exec.strictInlineEval` (Standard: false): Wenn true, erfordern Inline-Interpreter-Eval-Formen wie `python -c`, `node -e`, `ruby -e`, `perl -e`, `php -r`, `lua -e` und `osascript -e` immer eine explizite Genehmigung. `allow-always` kann weiterhin harmlose Interpreter-/Skriptaufrufe dauerhaft speichern, aber Inline-Eval-Formen fragen trotzdem jedes Mal nach.
- `tools.exec.pathPrepend`: Liste von Verzeichnissen, die für Exec-Läufe an `PATH` vorangestellt werden (nur Gateway + Sandbox).
- `tools.exec.safeBins`: stdin-only sichere Binaries, die ohne explizite Allowlist-Einträge ausgeführt werden können. Details zum Verhalten finden Sie unter [Safe bins](/de/tools/exec-approvals#safe-bins-stdin-only).
- `tools.exec.safeBinTrustedDirs`: zusätzliche explizite Verzeichnisse, denen bei Pfadprüfungen für `safeBins` vertraut wird. `PATH`-Einträge werden niemals automatisch als vertrauenswürdig behandelt. Eingebaute Standardwerte sind `/bin` und `/usr/bin`.
- `tools.exec.safeBinProfiles`: optionale benutzerdefinierte argv-Richtlinie pro Safe Bin (`minPositional`, `maxPositional`, `allowedValueFlags`, `deniedFlags`).
- `tools.exec.strictInlineEval` (Standard: false): wenn true, erfordern Inline-Interpreter-Eval-Formen wie `python -c`, `node -e`, `ruby -e`, `perl -e`, `php -r`, `lua -e` und `osascript -e` immer eine explizite Freigabe. `allow-always` kann weiterhin harmlose Interpreter-/Skriptaufrufe dauerhaft speichern, aber Inline-Eval-Formen fordern trotzdem jedes Mal erneut eine Freigabe an.
- `tools.exec.pathPrepend`: Liste von Verzeichnissen, die für Exec-Ausführungen an `PATH` vorangestellt werden sollen (nur Gateway + Sandbox).
- `tools.exec.safeBins`: nur-stdin-sichere Binaries, die ohne explizite Allowlist-Einträge ausgeführt werden können. Verhaltensdetails finden Sie unter [Safe bins](/de/tools/exec-approvals#safe-bins-stdin-only).
- `tools.exec.safeBinTrustedDirs`: zusätzliche explizite Verzeichnisse, denen bei Pfadprüfungen für `safeBins` vertraut wird. `PATH`-Einträge sind nie automatisch vertrauenswürdig. Eingebaute Standards sind `/bin` und `/usr/bin`.
- `tools.exec.safeBinProfiles`: optionale benutzerdefinierte argv-Richtlinie pro safe bin (`minPositional`, `maxPositional`, `allowedValueFlags`, `deniedFlags`).
Beispiel:
@ -95,29 +95,29 @@ Beispiel:
### PATH-Behandlung
- `host=gateway`: führt Ihren `PATH` aus der Login-Shell mit der Exec-Umgebung zusammen. Überschreibungen von `env.PATH` werden
für Host-Ausführung abgelehnt. Der Daemon selbst läuft weiterhin mit minimalem `PATH`:
- `host=gateway`: führt Ihr Login-Shell-`PATH` mit der Exec-Umgebung zusammen. `env.PATH`-Überschreibungen werden
für die Host-Ausführung abgelehnt. Der Daemon selbst läuft weiterhin mit einem minimalen `PATH`:
- macOS: `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, `/bin`
- Linux: `/usr/local/bin`, `/usr/bin`, `/bin`
- `host=sandbox`: führt `sh -lc` (Login-Shell) im Container aus, sodass `/etc/profile` `PATH` zurücksetzen kann.
OpenClaw stellt `env.PATH` nach dem Laden des Profils über eine interne Umgebungsvariable voran (ohne Shell-Interpolation);
`tools.exec.pathPrepend` gilt auch hier.
- `host=node`: Nur nicht blockierte env-Überschreibungen, die Sie übergeben, werden an den Node gesendet. Überschreibungen von `env.PATH` werden
für Host-Ausführung abgelehnt und von Node-Hosts ignoriert. Wenn Sie zusätzliche PATH-Einträge auf einem Node benötigen,
konfigurieren Sie die Service-Umgebung des Node-Hosts (systemd/launchd) oder installieren Sie Tools an Standardorten.
- `host=node`: nur nicht blockierte `env`-Überschreibungen, die Sie übergeben, werden an den Node gesendet. `env.PATH`-Überschreibungen werden
für die Host-Ausführung abgelehnt und von Node-Hosts ignoriert. Wenn Sie zusätzliche PATH-Einträge auf einem Node benötigen,
konfigurieren Sie die Dienstumgebung des Node-Hosts (systemd/launchd) oder installieren Sie Tools an Standardorten.
Node-Binding pro Agent (verwenden Sie den Index der Agent-Liste in der Konfiguration):
Node-Bindung pro Agent (verwenden Sie den Agent-Listenindex in der Konfiguration):
```bash
openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
```
Control UI: Die Registerkarte Nodes enthält ein kleines Panel „Exec node binding“ für dieselben Einstellungen.
Control UI: Die Registerkarte „Nodes“ enthält ein kleines Panel „Exec node binding“ für dieselben Einstellungen.
## Sitzungsüberschreibungen (`/exec`)
Verwenden Sie `/exec`, um **pro Sitzung** Standardwerte für `host`, `security`, `ask` und `node` festzulegen.
Verwenden Sie `/exec`, um **pro Sitzung** Standards für `host`, `security`, `ask` und `node` festzulegen.
Senden Sie `/exec` ohne Argumente, um die aktuellen Werte anzuzeigen.
Beispiel:
@ -128,49 +128,49 @@ Beispiel:
## Autorisierungsmodell
`/exec` wird nur für **autorisierte Sender** berücksichtigt (Kanal-Allowlists/Pairing plus `commands.useAccessGroups`).
Es aktualisiert **nur den Sitzungsstatus** und schreibt keine Konfiguration. Um exec vollständig zu deaktivieren, sperren Sie es per Tool-
Richtlinie (`tools.deny: ["exec"]` oder pro Agent). Host-Genehmigungen gelten weiterhin, es sei denn, Sie setzen explizit
`/exec` wird nur für **autorisierte Absender** berücksichtigt (Channel-Allowlists/Pairing plus `commands.useAccessGroups`).
Es aktualisiert **nur den Sitzungsstatus** und schreibt keine Konfiguration. Um Exec hart zu deaktivieren, verweigern Sie es über die Tool-
Richtlinie (`tools.deny: ["exec"]` oder pro Agent). Host-Freigaben gelten weiterhin, es sei denn, Sie setzen explizit
`security=full` und `ask=off`.
## Exec-Genehmigungen (Begleit-App / Node-Host)
## Exec approvals (Companion-App / Node-Host)
Sandboxed Agents können pro Anfrage eine Genehmigung verlangen, bevor `exec` auf dem Gateway- oder Node-Host ausgeführt wird.
Sandboxed Agents können pro Anfrage eine Freigabe verlangen, bevor `exec` auf dem Gateway- oder Node-Host ausgeführt wird.
Siehe [Exec approvals](/de/tools/exec-approvals) für Richtlinie, Allowlist und UI-Ablauf.
Wenn Genehmigungen erforderlich sind, gibt das Exec-Tool sofort mit
`status: "approval-pending"` und einer Genehmigungs-ID zurück. Sobald genehmigt (oder abgelehnt / mit Timeout beendet),
sendet das Gateway Systemereignisse (`Exec finished` / `Exec denied`). Wenn der Befehl nach `tools.exec.approvalRunningNoticeMs`
noch läuft, wird ein einzelner Hinweis `Exec running` ausgegeben.
Auf Kanälen mit nativen Genehmigungskarten/-Buttons sollte sich der Agent zuerst auf diese
native UI verlassen und einen manuellen `/approve`-Befehl nur dann einfügen, wenn das Tool-
Ergebnis ausdrücklich sagt, dass Chat-Genehmigungen nicht verfügbar sind oder manuelle Genehmigung der
einzige Weg ist.
Wenn Freigaben erforderlich sind, gibt das Exec-Tool sofort mit
`status: "approval-pending"` und einer Freigabe-ID zurück. Sobald freigegeben (oder abgelehnt / Timeout),
gibt das Gateway Systemereignisse aus (`Exec finished` / `Exec denied`). Wenn der Befehl nach
`tools.exec.approvalRunningNoticeMs` noch läuft, wird genau ein Hinweis `Exec running` ausgegeben.
Auf Channels mit nativen Freigabekarten/-buttons sollte sich der Agent zuerst auf diese
native UI verlassen und nur dann einen manuellen `/approve`-Befehl einfügen, wenn das Tool-
Ergebnis ausdrücklich sagt, dass Chat-Freigaben nicht verfügbar sind oder eine manuelle Freigabe
der einzige Weg ist.
## Allowlist + Safe Bins
## Allowlist + safe bins
Die manuelle Durchsetzung der Allowlist gleicht nur **aufgelöste Binary-Pfade** ab (keine Basename-Treffer). Wenn
`security=allowlist`, werden Shell-Befehle nur dann automatisch erlaubt, wenn jedes Pipeline-Segment
allowgelistet oder ein Safe Bin ist. Verkettungen (`;`, `&&`, `||`) und Umleitungen werden im
Allowlist-Modus abgelehnt, es sei denn, jedes Top-Level-Segment erfüllt die Allowlist (einschließlich Safe Bins).
Die manuelle Allowlist-Erzwingung gleicht nur **aufgelöste Binärpfade** ab (keine Basename-Abgleiche). Wenn
`security=allowlist` gesetzt ist, werden Shell-Befehle nur dann automatisch erlaubt, wenn jedes Pipeline-Segment
auf der Allowlist steht oder ein safe bin ist. Verkettung (`;`, `&&`, `||`) und Umleitungen werden im
Allowlist-Modus abgelehnt, es sei denn, jedes Top-Level-Segment erfüllt die Allowlist (einschließlich safe bins).
Umleitungen bleiben nicht unterstützt.
Dauerhaftes Vertrauen per `allow-always` umgeht diese Regel nicht: Ein verketteter Befehl erfordert weiterhin, dass jedes
Dauerhaftes `allow-always`-Vertrauen umgeht diese Regel nicht: Ein verketteter Befehl erfordert weiterhin, dass jedes
Top-Level-Segment übereinstimmt.
`autoAllowSkills` ist ein separater Komfortpfad in den Exec-Genehmigungen. Er ist nicht dasselbe wie
manuelle Pfad-Allowlist-Einträge. Für strikt explizites Vertrauen lassen Sie `autoAllowSkills` deaktiviert.
`autoAllowSkills` ist ein separater Komfortpfad in Exec-Freigaben. Es ist nicht dasselbe wie
manuelle Pfad-Allowlist-Einträge. Für striktes explizites Vertrauen lassen Sie `autoAllowSkills` deaktiviert.
Verwenden Sie die beiden Steuerelemente für unterschiedliche Aufgaben:
- `tools.exec.safeBins`: kleine, stdin-only Stream-Filter.
- `tools.exec.safeBinTrustedDirs`: explizite zusätzliche vertrauenswürdige Verzeichnisse für ausführbare Safe-Bin-Pfade.
- `tools.exec.safeBinProfiles`: explizite argv-Richtlinie für benutzerdefinierte Safe Bins.
- `tools.exec.safeBins`: kleine, nur-stdin-Stream-Filter.
- `tools.exec.safeBinTrustedDirs`: explizite zusätzliche vertrauenswürdige Verzeichnisse für Pfade ausführbarer safe bins.
- `tools.exec.safeBinProfiles`: explizite argv-Richtlinie für benutzerdefinierte safe bins.
- Allowlist: explizites Vertrauen für Pfade zu ausführbaren Dateien.
Behandeln Sie `safeBins` nicht als generische Allowlist, und fügen Sie keine Interpreter-/Laufzeit-Binaries hinzu (zum Beispiel `python3`, `node`, `ruby`, `bash`). Wenn Sie diese benötigen, verwenden Sie explizite Allowlist-Einträge und lassen Sie Genehmigungsaufforderungen aktiviert.
`openclaw security audit` warnt, wenn bei Einträgen für Interpreter-/Laufzeit-`safeBins` explizite Profile fehlen, und `openclaw doctor --fix` kann fehlende benutzerdefinierte `safeBinProfiles`-Einträge erzeugen.
Behandeln Sie `safeBins` nicht als generische Allowlist und fügen Sie keine Interpreter-/Runtime-Binaries hinzu (zum Beispiel `python3`, `node`, `ruby`, `bash`). Wenn Sie diese benötigen, verwenden Sie explizite Allowlist-Einträge und lassen Sie Freigabeaufforderungen aktiviert.
`openclaw security audit` warnt, wenn bei Interpreter-/Runtime-`safeBins`-Einträgen explizite Profile fehlen, und `openclaw doctor --fix` kann fehlende benutzerdefinierte `safeBinProfiles`-Einträge erzeugen.
`openclaw security audit` und `openclaw doctor` warnen auch, wenn Sie explizit Binaries mit breitem Verhalten wie `jq` wieder zu `safeBins` hinzufügen.
Wenn Sie Interpreter explizit allowlisten, aktivieren Sie `tools.exec.strictInlineEval`, damit Inline-Code-Eval-Formen weiterhin eine neue Genehmigung erfordern.
Wenn Sie Interpreter explizit auf die Allowlist setzen, aktivieren Sie `tools.exec.strictInlineEval`, damit Inline-Code-Eval-Formen weiterhin eine neue Freigabe erfordern.
Vollständige Richtliniendetails und Beispiele finden Sie unter [Exec approvals](/de/tools/exec-approvals#safe-bins-stdin-only) und [Safe bins versus allowlist](/de/tools/exec-approvals#safe-bins-versus-allowlist).
@ -189,7 +189,7 @@ Hintergrund + Poll:
{"tool":"process","action":"poll","sessionId":"<id>"}
```
Polling dient zur bedarfsgesteuerten Statusabfrage, nicht für Warteschleifen. Wenn automatisches Completion-Wake
Polling ist für Status auf Abruf gedacht, nicht für Warteschleifen. Wenn das automatische Abschluss-Wake-up
aktiviert ist, kann der Befehl die Sitzung wecken, wenn er Ausgabe erzeugt oder fehlschlägt.
Tasten senden (tmux-Stil):
@ -200,13 +200,13 @@ Tasten senden (tmux-Stil):
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Up","Up","Enter"]}
```
Submit (nur CR senden):
Absenden (nur CR senden):
```json
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
```
Paste (standardmäßig mit Klammerung):
Einfügen (standardmäßig in Klammern gesetzt):
```json
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }
@ -214,8 +214,8 @@ Paste (standardmäßig mit Klammerung):
## apply_patch
`apply_patch` ist ein Untertool von `exec` für strukturierte Bearbeitungen über mehrere Dateien hinweg.
Es ist standardmäßig für OpenAI- und OpenAI-Codex-Modelle aktiviert. Verwenden Sie Konfiguration nur,
`apply_patch` ist ein Untertool von `exec` für strukturierte dateiübergreifende Bearbeitungen.
Es ist standardmäßig für OpenAI- und OpenAI-Codex-Modelle aktiviert. Verwenden Sie die Konfiguration nur,
wenn Sie es deaktivieren oder auf bestimmte Modelle beschränken möchten:
```json5
@ -231,14 +231,14 @@ wenn Sie es deaktivieren oder auf bestimmte Modelle beschränken möchten:
Hinweise:
- Nur für OpenAI-/OpenAI-Codex-Modelle verfügbar.
- Die Tool-Richtlinie gilt weiterhin; `allow: ["write"]` erlaubt implizit `apply_patch`.
- Die Konfiguration liegt unter `tools.exec.applyPatch`.
- Die Tool-Richtlinie gilt weiterhin; `allow: ["write"]` erlaubt implizit auch `apply_patch`.
- Die Konfiguration befindet sich unter `tools.exec.applyPatch`.
- `tools.exec.applyPatch.enabled` ist standardmäßig `true`; setzen Sie es auf `false`, um das Tool für OpenAI-Modelle zu deaktivieren.
- `tools.exec.applyPatch.workspaceOnly` ist standardmäßig `true` (innerhalb des Workspace begrenzt). Setzen Sie es nur dann auf `false`, wenn Sie ausdrücklich möchten, dass `apply_patch` außerhalb des Workspace-Verzeichnisses schreibt/löscht.
- `tools.exec.applyPatch.workspaceOnly` ist standardmäßig `true` (auf den Workspace beschränkt). Setzen Sie es nur dann auf `false`, wenn Sie ausdrücklich möchten, dass `apply_patch` außerhalb des Workspace-Verzeichnisses schreibt/löscht.
## Verwandt
- [Exec Approvals](/de/tools/exec-approvals) — Genehmigungsschranken für Shell-Befehle
- [Exec approvals](/de/tools/exec-approvals) — Freigabeschranken für Shell-Befehle
- [Sandboxing](/de/gateway/sandboxing) — Ausführen von Befehlen in sandboxed Umgebungen
- [Background Process](/de/gateway/background-process) — lang laufendes exec- und process-Tool
- [Background Process](/de/gateway/background-process) — lang laufendes `exec` und `process`-Tool
- [Security](/de/gateway/security) — Tool-Richtlinie und erhöhter Zugriff

288
docs/de/tools/slash-commands.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Chat-Befehle verwenden oder konfigurieren
- Befehlsrouting oder Berechtigungen debuggen
- Verwendung oder Konfiguration von Chat-Befehlen
- Fehlerbehebung bei Befehlsrouting oder Berechtigungen
summary: 'Slash-Befehle: Text vs. nativ, Konfiguration und unterstützte Befehle'
title: Slash-Befehle
x-i18n:
generated_at: "2026-04-12T23:34:01Z"
generated_at: "2026-04-21T13:38:03Z"
model: gpt-5.4
provider: openai
source_hash: 9ef6f54500fa2ce3b873a8398d6179a0882b8bf6fba38f61146c64671055505e
source_hash: d90ddee54af7c05b7fdf486590561084581d750e42cd14674d43bbdc0984df5d
source_path: tools/slash-commands.md
workflow: 15
---
@ -23,14 +23,14 @@ Es gibt zwei verwandte Systeme:
- **Befehle**: eigenständige `/...`-Nachrichten.
- **Direktiven**: `/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`.
- Direktiven werden aus der Nachricht entfernt, bevor das Modell sie sieht.
- In normalen Chat-Nachrichten (nicht nur Direktiven) werden sie als „Inline-Hinweise“ behandelt und **persistieren** keine Sitzungseinstellungen.
- In Nachrichten, die nur aus Direktiven bestehen (die Nachricht enthält nur Direktiven), werden sie für die Sitzung persistent gespeichert und mit einer Bestätigung beantwortet.
- In normalen Chat-Nachrichten (nicht nur Direktiven) werden sie als „Inline-Hinweise“ behandelt und **persistieren keine** Sitzungseinstellungen.
- In Nachrichten, die nur Direktiven enthalten (die Nachricht enthält nur Direktiven), werden sie in der Sitzung persistiert und beantworten mit einer Bestätigung.
- Direktiven werden nur für **autorisierte Absender** angewendet. Wenn `commands.allowFrom` gesetzt ist, ist dies die einzige
verwendete Allowlist; andernfalls ergibt sich die Autorisierung aus Channel-Allowlists/Pairing plus `commands.useAccessGroups`.
Nicht autorisierte Absender sehen Direktiven als normalen Text.
verwendete Zulassungsliste; andernfalls stammt die Autorisierung aus Kanal-Zulassungslisten/Pairing plus `commands.useAccessGroups`.
Nicht autorisierte Absender sehen Direktiven als Klartext behandelt.
Es gibt außerdem einige **Inline-Kurzbefehle** (nur für allowlistete/autorisierte Absender): `/help`, `/commands`, `/status`, `/whoami` (`/id`).
Sie werden sofort ausgeführt, werden entfernt, bevor das Modell die Nachricht sieht, und der verbleibende Text läuft normal weiter.
Es gibt außerdem einige **Inline-Kurzbefehle** (nur für zugelassene/autorisierte Absender): `/help`, `/commands`, `/status`, `/whoami` (`/id`).
Sie werden sofort ausgeführt, werden entfernt, bevor das Modell die Nachricht sieht, und der verbleibende Text läuft durch den normalen Ablauf weiter.
## Konfiguration
@ -59,92 +59,92 @@ Sie werden sofort ausgeführt, werden entfernt, bevor das Modell die Nachricht s
}
```
- `commands.text` (Standard: `true`) aktiviert das Parsen von `/...` in Chat-Nachrichten.
- Auf Oberflächen ohne native Befehle (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams) funktionieren Textbefehle auch dann noch, wenn Sie dies auf `false` setzen.
- `commands.native` (Standard: `"auto"`) registriert native Befehle.
- Auto: an für Discord/Telegram; aus für Slack (bis Sie Slash-Befehle hinzufügen); ignoriert für Provider ohne native Unterstützung.
- Setzen Sie `channels.discord.commands.native`, `channels.telegram.commands.native` oder `channels.slack.commands.native`, um pro Provider zu überschreiben (Bool oder `"auto"`).
- `commands.text` (Standard `true`) aktiviert das Parsen von `/...` in Chat-Nachrichten.
- Auf Oberflächen ohne native Befehle (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams) funktionieren Textbefehle weiterhin, selbst wenn Sie dies auf `false` setzen.
- `commands.native` (Standard `"auto"`) registriert native Befehle.
- Auto: an für Discord/Telegram; aus für Slack (bis Sie Slash-Befehle hinzufügen); ignoriert für Anbieter ohne native Unterstützung.
- Setzen Sie `channels.discord.commands.native`, `channels.telegram.commands.native` oder `channels.slack.commands.native`, um pro Anbieter zu überschreiben (bool oder `"auto"`).
- `false` löscht beim Start zuvor registrierte Befehle auf Discord/Telegram. Slack-Befehle werden in der Slack-App verwaltet und nicht automatisch entfernt.
- `commands.nativeSkills` (Standard: `"auto"`) registriert **Skill**-Befehle nativ, wenn unterstützt.
- Auto: an für Discord/Telegram; aus für Slack (Slack erfordert einen Slash-Befehl pro Skill).
- Setzen Sie `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` oder `channels.slack.commands.nativeSkills`, um pro Provider zu überschreiben (Bool oder `"auto"`).
- `commands.bash` (Standard: `false`) aktiviert `! <cmd>`, um Host-Shell-Befehle auszuführen (`/bash <cmd>` ist ein Alias; erfordert `tools.elevated`-Allowlists).
- `commands.bashForegroundMs` (Standard: `2000`) steuert, wie lange Bash wartet, bevor in den Hintergrundmodus gewechselt wird (`0` verschiebt sofort in den Hintergrund).
- `commands.config` (Standard: `false`) aktiviert `/config` (liest/schreibt `openclaw.json`).
- `commands.mcp` (Standard: `false`) aktiviert `/mcp` (liest/schreibt OpenClaw-verwaltete MCP-Konfiguration unter `mcp.servers`).
- `commands.plugins` (Standard: `false`) aktiviert `/plugins` (Plugin-Erkennung/-Status plus Installations- und Aktivierungs-/Deaktivierungssteuerung).
- `commands.debug` (Standard: `false`) aktiviert `/debug` (nur Laufzeit-Überschreibungen).
- `commands.restart` (Standard: `true`) aktiviert `/restart` plus Tool-Aktionen zum Neustart des Gateways.
- `commands.ownerAllowFrom` (optional) setzt die explizite Owner-Allowlist für nur für Owner verfügbare Befehls-/Tool-Oberflächen. Dies ist getrennt von `commands.allowFrom`.
- `commands.ownerDisplay` steuert, wie Owner-IDs im System-Prompt erscheinen: `raw` oder `hash`.
- `commands.nativeSkills` (Standard `"auto"`) registriert **Skill**-Befehle nativ, wenn unterstützt.
- Auto: an für Discord/Telegram; aus für Slack (Slack erfordert das Anlegen eines Slash-Befehls pro Skill).
- Setzen Sie `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` oder `channels.slack.commands.nativeSkills`, um pro Anbieter zu überschreiben (bool oder `"auto"`).
- `commands.bash` (Standard `false`) aktiviert `! <cmd>` zum Ausführen von Host-Shell-Befehlen (`/bash <cmd>` ist ein Alias; erfordert `tools.elevated`-Zulassungslisten).
- `commands.bashForegroundMs` (Standard `2000`) steuert, wie lange Bash wartet, bevor in den Hintergrundmodus gewechselt wird (`0` schickt sofort in den Hintergrund).
- `commands.config` (Standard `false`) aktiviert `/config` (liest/schreibt `openclaw.json`).
- `commands.mcp` (Standard `false`) aktiviert `/mcp` (liest/schreibt die von OpenClaw verwaltete MCP-Konfiguration unter `mcp.servers`).
- `commands.plugins` (Standard `false`) aktiviert `/plugins` (Plugin-Erkennung/Status plus Installations- und Aktivierungs-/Deaktivierungssteuerung).
- `commands.debug` (Standard `false`) aktiviert `/debug` (nur Laufzeit-Überschreibungen).
- `commands.restart` (Standard `true`) aktiviert `/restart` plus Gateway-Neustart-Tool-Aktionen.
- `commands.ownerAllowFrom` (optional) setzt die explizite Zulassungsliste der Eigentümer für nur-Eigentümer-Befehls-/Tool-Oberflächen. Dies ist getrennt von `commands.allowFrom`.
- `commands.ownerDisplay` steuert, wie Eigentümer-IDs im System-Prompt erscheinen: `raw` oder `hash`.
- `commands.ownerDisplaySecret` setzt optional das HMAC-Secret, das verwendet wird, wenn `commands.ownerDisplay="hash"` gesetzt ist.
- `commands.allowFrom` (optional) setzt eine Provider-spezifische Allowlist für die Befehlsautorisierung. Wenn konfiguriert, ist dies die
einzige Autorisierungsquelle für Befehle und Direktiven (Channel-Allowlists/Pairing und `commands.useAccessGroups`
werden ignoriert). Verwenden Sie `"*"` als globalen Standard; Provider-spezifische Schlüssel überschreiben ihn.
- `commands.useAccessGroups` (Standard: `true`) erzwingt Allowlists/Richtlinien für Befehle, wenn `commands.allowFrom` nicht gesetzt ist.
- `commands.allowFrom` (optional) setzt eine anbieterbezogene Zulassungsliste für die Befehlsautorisierung. Wenn konfiguriert, ist sie die
einzige Autorisierungsquelle für Befehle und Direktiven (Kanal-Zulassungslisten/Pairing und `commands.useAccessGroups`
werden ignoriert). Verwenden Sie `"*"` für einen globalen Standard; anbieterbezogene Schlüssel überschreiben ihn.
- `commands.useAccessGroups` (Standard `true`) erzwingt Zulassungslisten/Richtlinien für Befehle, wenn `commands.allowFrom` nicht gesetzt ist.
## Befehlsliste
Aktuelle Source of Truth:
Aktuelle Single Source of Truth:
- Core-Built-ins stammen aus `src/auto-reply/commands-registry.shared.ts`
- Kern-Integrationen stammen aus `src/auto-reply/commands-registry.shared.ts`
- generierte Dock-Befehle stammen aus `src/auto-reply/commands-registry.data.ts`
- Plugin-Befehle stammen aus Plugin-`registerCommand()`-Aufrufen
- die tatsächliche Verfügbarkeit auf Ihrem Gateway hängt weiterhin von Konfigurationsflags, der Channel-Oberfläche und installierten/aktivierten Plugins ab
- Plugin-Befehle stammen aus Plugin-Aufrufen von `registerCommand()`
- die tatsächliche Verfügbarkeit auf Ihrem Gateway hängt weiterhin von Konfigurationsflags, Kanaloberfläche und installierten/aktivierten Plugins ab
### Core-Built-in-Befehle
### Integrierte Kernbefehle
Heute verfügbare integrierte Befehle:
- `/new [model]` startet eine neue Sitzung; `/reset` ist der Alias zum Zurücksetzen.
- `/compact [instructions]` verdichtet den Sitzungskontext. Siehe [/concepts/compaction](/de/concepts/compaction).
- `/stop` bricht den aktuellen Durchlauf ab.
- `/session idle <duration|off>` und `/session max-age <duration|off>` verwalten den Ablauf der Thread-Bindung.
- `/think <off|minimal|low|medium|high|xhigh>` setzt die Thinking-Stufe. Aliasse: `/thinking`, `/t`.
- `/compact [instructions]` komprimiert den Sitzungskontext. Siehe [/concepts/compaction](/de/concepts/compaction).
- `/stop` bricht die aktuelle Ausführung ab.
- `/session idle <duration|off>` und `/session max-age <duration|off>` verwalten das Ablaufen der Thread-Bindung.
- `/think <level>` setzt die Thinking-Stufe. Die Optionen stammen aus dem Anbieterprofil des aktiven Modells; gängige Stufen sind `off`, `minimal`, `low`, `medium` und `high`, mit benutzerdefinierten Stufen wie `xhigh`, `adaptive`, `max` oder binärem `on` nur dort, wo unterstützt. Aliasse: `/thinking`, `/t`.
- `/verbose on|off|full` schaltet ausführliche Ausgabe um. Alias: `/v`.
- `/trace on|off` schaltet Plugin-Trace-Ausgabe für die aktuelle Sitzung um.
- `/fast [status|on|off]` zeigt den Schnellmodus an oder setzt ihn.
- `/fast [status|on|off]` zeigt den Fast-Modus an oder setzt ihn.
- `/reasoning [on|off|stream]` schaltet die Sichtbarkeit von Reasoning um. Alias: `/reason`.
- `/elevated [on|off|ask|full]` schaltet den Elevated-Modus um. Alias: `/elev`.
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` zeigt Exec-Standardwerte an oder setzt sie.
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` zeigt die Exec-Standards an oder setzt sie.
- `/model [name|#|status]` zeigt das Modell an oder setzt es.
- `/models [provider] [page] [limit=<n>|size=<n>|all]` listet Provider oder Modelle für einen Provider auf.
- `/queue <mode>` verwaltet das Queue-Verhalten (`steer`, `interrupt`, `followup`, `collect`, `steer-backlog`) plus Optionen wie `debounce:2s cap:25 drop:summarize`.
- `/help` zeigt die kurze Hilfezusammenfassung.
- `/commands` zeigt den generierten Befehlskatalog.
- `/tools [compact|verbose]` zeigt, was der aktuelle Agent gerade verwenden kann.
- `/status` zeigt den Laufzeitstatus, einschließlich Provider-Nutzung/Kontingent, sofern verfügbar.
- `/models [provider] [page] [limit=<n>|size=<n>|all]` listet Anbieter oder Modelle für einen Anbieter auf.
- `/queue <mode>` verwaltet Queue-Verhalten (`steer`, `interrupt`, `followup`, `collect`, `steer-backlog`) plus Optionen wie `debounce:2s cap:25 drop:summarize`.
- `/help` zeigt die kurze Hilfezusammenfassung an.
- `/commands` zeigt den generierten Befehlskatalog an.
- `/tools [compact|verbose]` zeigt an, was der aktuelle Agent gerade verwenden kann.
- `/status` zeigt den Laufzeitstatus an, einschließlich Anbieternutzung/Kontingent, falls verfügbar.
- `/tasks` listet aktive/aktuelle Hintergrundaufgaben für die aktuelle Sitzung auf.
- `/context [list|detail|json]` erklärt, wie Kontext zusammengesetzt wird.
- `/context [list|detail|json]` erklärt, wie Kontext zusammengestellt wird.
- `/export-session [path]` exportiert die aktuelle Sitzung nach HTML. Alias: `/export`.
- `/whoami` zeigt Ihre Absender-ID an. Alias: `/id`.
- `/skill <name> [input]` führt einen Skill anhand seines Namens aus.
- `/allowlist [list|add|remove] ...` verwaltet Allowlist-Einträge. Nur Text.
- `/approve <id> <decision>` löst Exec-Genehmigungsaufforderungen auf.
- `/btw <question>` stellt eine Nebenfrage, ohne den zukünftigen Sitzungskontext zu ändern. Siehe [/tools/btw](/de/tools/btw).
- `/subagents list|kill|log|info|send|steer|spawn` verwaltet Sub-Agent-Durchläufe für die aktuelle Sitzung.
- `/skill <name> [input]` führt einen Skill nach Namen aus.
- `/allowlist [list|add|remove] ...` verwaltet Einträge in der Zulassungsliste. Nur Text.
- `/approve <id> <decision>` bearbeitet Exec-Genehmigungsabfragen.
- `/btw <question>` stellt eine Nebenfrage, ohne den künftigen Sitzungskontext zu ändern. Siehe [/tools/btw](/de/tools/btw).
- `/subagents list|kill|log|info|send|steer|spawn` verwaltet Sub-Agent-Ausführungen für die aktuelle Sitzung.
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` verwaltet ACP-Sitzungen und Laufzeitoptionen.
- `/focus <target>` bindet den aktuellen Discord-Thread oder das aktuelle Telegram-Thema/die aktuelle Unterhaltung an ein Sitzungsziel.
- `/focus <target>` bindet den aktuellen Discord-Thread oder das aktuelle Telegram-Thema/Gespräch an ein Sitzungsziel.
- `/unfocus` entfernt die aktuelle Bindung.
- `/agents` listet threadgebundene Agenten für die aktuelle Sitzung auf.
- `/kill <id|#|all>` bricht einen oder alle laufenden Sub-Agenten ab.
- `/steer <id|#> <message>` sendet Steuerung an einen laufenden Sub-Agenten. Alias: `/tell`.
- `/config show|get|set|unset` liest oder schreibt `openclaw.json`. Nur Owner. Erfordert `commands.config: true`.
- `/mcp show|get|set|unset` liest oder schreibt OpenClaw-verwaltete MCP-Server-Konfiguration unter `mcp.servers`. Nur Owner. Erfordert `commands.mcp: true`.
- `/plugins list|inspect|show|get|install|enable|disable` prüft oder verändert den Plugin-Status. `/plugin` ist ein Alias. Schreibzugriffe nur für Owner. Erfordert `commands.plugins: true`.
- `/debug show|set|unset|reset` verwaltet nur zur Laufzeit geltende Konfigurationsüberschreibungen. Nur Owner. Erfordert `commands.debug: true`.
- `/usage off|tokens|full|cost` steuert den Nutzungs-Footer pro Antwort oder gibt eine lokale Kostenzusammenfassung aus.
- `/config show|get|set|unset` liest oder schreibt `openclaw.json`. Nur Eigentümer. Erfordert `commands.config: true`.
- `/mcp show|get|set|unset` liest oder schreibt von OpenClaw verwaltete MCP-Server-Konfiguration unter `mcp.servers`. Nur Eigentümer. Erfordert `commands.mcp: true`.
- `/plugins list|inspect|show|get|install|enable|disable` untersucht oder ändert den Plugin-Status. `/plugin` ist ein Alias. Schreibvorgänge nur für Eigentümer. Erfordert `commands.plugins: true`.
- `/debug show|set|unset|reset` verwaltet nur zur Laufzeit geltende Konfigurationsüberschreibungen. Nur Eigentümer. Erfordert `commands.debug: true`.
- `/usage off|tokens|full|cost` steuert die Nutzungsfußzeile pro Antwort oder gibt eine lokale Kostenzusammenfassung aus.
- `/tts on|off|status|provider|limit|summary|audio|help` steuert TTS. Siehe [/tools/tts](/de/tools/tts).
- `/restart` startet OpenClaw neu, wenn aktiviert. Standard: aktiviert; setzen Sie `commands.restart: false`, um ihn zu deaktivieren.
- `/restart` startet OpenClaw neu, wenn aktiviert. Standard: aktiviert; setzen Sie `commands.restart: false`, um es zu deaktivieren.
- `/activation mention|always` setzt den Gruppenaktivierungsmodus.
- `/send on|off|inherit` setzt die Send-Richtlinie. Nur Owner.
- `/bash <command>` führt einen Host-Shell-Befehl aus. Nur Text. Alias: `! <command>`. Erfordert `commands.bash: true` plus `tools.elevated`-Allowlists.
- `/send on|off|inherit` setzt die Senderichtlinie. Nur Eigentümer.
- `/bash <command>` führt einen Host-Shell-Befehl aus. Nur Text. Alias: `! <command>`. Erfordert `commands.bash: true` plus `tools.elevated`-Zulassungslisten.
- `!poll [sessionId]` prüft einen Bash-Hintergrundjob.
- `!stop [sessionId]` stoppt einen Bash-Hintergrundjob.
### Generierte Dock-Befehle
Dock-Befehle werden aus Channel-Plugins mit Unterstützung für native Befehle generiert. Aktuell gebündelter Satz:
Dock-Befehle werden aus Kanal-Plugins mit Unterstützung für native Befehle generiert. Aktueller gebündelter Satz:
- `/dock-discord` (Alias: `/dock_discord`)
- `/dock-mattermost` (Alias: `/dock_mattermost`)
@ -153,14 +153,14 @@ Dock-Befehle werden aus Channel-Plugins mit Unterstützung für native Befehle g
### Gebündelte Plugin-Befehle
Gebündelte Plugins können weitere Slash-Befehle hinzufügen. Aktuelle gebündelte Befehle in diesem Repo:
Gebündelte Plugins können weitere Slash-Befehle hinzufügen. Aktuelle gebündelte Befehle in diesem Repository:
- `/dreaming [on|off|status|help]` schaltet Memory Dreaming um. Siehe [Dreaming](/de/concepts/dreaming).
- `/pair [qr|status|pending|approve|cleanup|notify]` verwaltet den Geräte-Pairing-/Einrichtungsablauf. Siehe [Pairing](/de/channels/pairing).
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` aktiviert vorübergehend risikoreiche Telefon-Node-Befehle.
- `/voice status|list [limit]|set <voiceId|name>` verwaltet die Talk-Sprachkonfiguration. Auf Discord lautet der native Befehlsname `/talkvoice`.
- `/pair [qr|status|pending|approve|cleanup|notify]` verwaltet den Ablauf für Geräte-Pairing/-Einrichtung. Siehe [Pairing](/de/channels/pairing).
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` aktiviert vorübergehend Hochrisiko-Befehle des Phone-Node.
- `/voice status|list [limit]|set <voiceId|name>` verwaltet die Talk-Sprachkonfiguration. Auf Discord ist der native Befehlsname `/talkvoice`.
- `/card ...` sendet LINE-Rich-Card-Voreinstellungen. Siehe [LINE](/de/channels/line).
- `/codex status|models|threads|resume|compact|review|account|mcp|skills` prüft und steuert das gebündelte Codex-App-Server-Harness. Siehe [Codex Harness](/de/plugins/codex-harness).
- `/codex status|models|threads|resume|compact|review|account|mcp|skills` untersucht und steuert den gebündelten Codex-App-Server-Harness. Siehe [Codex Harness](/de/plugins/codex-harness).
- Nur QQBot-Befehle:
- `/bot-ping`
- `/bot-version`
@ -170,71 +170,71 @@ Gebündelte Plugins können weitere Slash-Befehle hinzufügen. Aktuelle gebünde
### Dynamische Skill-Befehle
Vom Nutzer aufrufbare Skills werden ebenfalls als Slash-Befehle bereitgestellt:
Vom Benutzer aufrufbare Skills werden auch als Slash-Befehle bereitgestellt:
- `/skill <name> [input]` funktioniert immer als generischer Einstiegspunkt.
- Skills können auch als direkte Befehle wie `/prose` erscheinen, wenn der Skill/das Plugin sie registriert.
- die Registrierung nativer Skill-Befehle wird durch `commands.nativeSkills` und `channels.<provider>.commands.nativeSkills` gesteuert.
- Die Registrierung nativer Skill-Befehle wird über `commands.nativeSkills` und `channels.<provider>.commands.nativeSkills` gesteuert.
Hinweise:
- Befehle akzeptieren optional ein `:` zwischen Befehl und Argumenten (z. B. `/think: high`, `/send: on`, `/help:`).
- `/new <model>` akzeptiert einen Modellalias, `provider/model` oder einen Providernamen (unscharfe Übereinstimmung); wenn es keine Übereinstimmung gibt, wird der Text als Nachrichtentext behandelt.
- Für die vollständige Aufschlüsselung der Provider-Nutzung verwenden Sie `openclaw status --usage`.
- `/allowlist add|remove` erfordert `commands.config=true` und berücksichtigt Channel-`configWrites`.
- In Multi-Account-Channels berücksichtigen das konfigurationsbezogene `/allowlist --account <id>` und `/config set channels.<provider>.accounts.<id>...` ebenfalls die `configWrites` des Zielkontos.
- `/usage` steuert den Nutzungs-Footer pro Antwort; `/usage cost` gibt eine lokale Kostenzusammenfassung aus den OpenClaw-Sitzungslogs aus.
- `/restart` ist standardmäßig aktiviert; setzen Sie `commands.restart: false`, um ihn zu deaktivieren.
- `/new <model>` akzeptiert einen Modellalias, `provider/model` oder einen Anbieternamen (unscharfer Abgleich); wenn es keine Übereinstimmung gibt, wird der Text als Nachrichtentext behandelt.
- Für die vollständige Aufschlüsselung der Anbieternutzung verwenden Sie `openclaw status --usage`.
- `/allowlist add|remove` erfordert `commands.config=true` und beachtet kanalbezogene `configWrites`.
- In Kanälen mit mehreren Konten beachten konfigurationsbezogenes `/allowlist --account <id>` und `/config set channels.<provider>.accounts.<id>...` auch `configWrites` des Zielkontos.
- `/usage` steuert die Nutzungsfußzeile pro Antwort; `/usage cost` gibt eine lokale Kostenzusammenfassung aus OpenClaw-Sitzungsprotokollen aus.
- `/restart` ist standardmäßig aktiviert; setzen Sie `commands.restart: false`, um es zu deaktivieren.
- `/plugins install <spec>` akzeptiert dieselben Plugin-Spezifikationen wie `openclaw plugins install`: lokaler Pfad/Archiv, npm-Paket oder `clawhub:<pkg>`.
- `/plugins enable|disable` aktualisiert die Plugin-Konfiguration und kann zu einem Neustart auffordern.
- Nur nativer Discord-Befehl: `/vc join|leave|status` steuert Sprachkanäle (erfordert `channels.discord.voice` und native Befehle; nicht als Text verfügbar).
- Discord-Thread-Bindungsbefehle (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) erfordern, dass effektive Thread-Bindungen aktiviert sind (`session.threadBindings.enabled` und/oder `channels.discord.threadBindings.enabled`).
- Nur auf Discord verfügbarer nativer Befehl: `/vc join|leave|status` steuert Sprachkanäle (erfordert `channels.discord.voice` und native Befehle; nicht als Text verfügbar).
- Discord-Befehle zur Thread-Bindung (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) erfordern, dass effektive Thread-Bindungen aktiviert sind (`session.threadBindings.enabled` und/oder `channels.discord.threadBindings.enabled`).
- ACP-Befehlsreferenz und Laufzeitverhalten: [ACP Agents](/de/tools/acp-agents).
- `/verbose` ist für Debugging und zusätzliche Sichtbarkeit gedacht; lassen Sie es im normalen Gebrauch **aus**.
- `/trace` ist enger gefasst als `/verbose`: Es zeigt nur Plugin-eigene Trace-/Debug-Zeilen und lässt normale ausführliche Tool-Ausgaben ausgeschaltet.
- `/fast on|off` speichert eine sitzungsbezogene Überschreibung. Verwenden Sie in der Sitzungs-UI die Option `inherit`, um sie zu löschen und auf die Standardwerte der Konfiguration zurückzufallen.
- `/fast` ist provider-spezifisch: OpenAI/OpenAI Codex ordnen es auf nativen Responses-Endpunkten `service_tier=priority` zu, während direkte öffentliche Anthropic-Anfragen, einschließlich per OAuth authentifiziertem Datenverkehr an `api.anthropic.com`, es `service_tier=auto` oder `standard_only` zuordnen. Siehe [OpenAI](/de/providers/openai) und [Anthropic](/de/providers/anthropic).
- Zusammenfassungen von Tool-Fehlern werden weiterhin angezeigt, wenn relevant, aber detaillierter Fehlertext wird nur aufgenommen, wenn `/verbose` auf `on` oder `full` steht.
- `/reasoning`, `/verbose` und `/trace` sind in Gruppeneinstellungen riskant: Sie können internes Reasoning, Tool-Ausgabe oder Plugin-Diagnosen offenlegen, die Sie nicht beabsichtigt hatten offenzulegen. Lassen Sie sie vorzugsweise ausgeschaltet, besonders in Gruppenchats.
- `/model` speichert das neue Sitzungsmodell sofort persistent.
- Wenn der Agent inaktiv ist, verwendet der nächste Durchlauf es sofort.
- Wenn bereits ein Durchlauf aktiv ist, markiert OpenClaw einen Live-Wechsel als ausstehend und startet erst an einem sauberen Wiederholungszeitpunkt in das neue Modell neu.
- Wenn Tool-Aktivität oder Antwortausgabe bereits begonnen hat, kann der ausstehende Wechsel bis zu einer späteren Wiederholungsmöglichkeit oder dem nächsten Nutzerzug in der Warteschlange bleiben.
- **Schnellpfad:** Nur-Befehl-Nachrichten von allowlisteten Absendern werden sofort verarbeitet (umgehen Queue + Modell).
- **Gruppen-Erwähnungs-Schranke:** Nur-Befehl-Nachrichten von allowlisteten Absendern umgehen Erwähnungsanforderungen.
- **Inline-Kurzbefehle (nur allowlistete Absender):** bestimmte Befehle funktionieren auch eingebettet in eine normale Nachricht und werden entfernt, bevor das Modell den verbleibenden Text sieht.
- Beispiel: `hey /status` löst eine Statusantwort aus, und der verbleibende Text läuft normal weiter.
- Derzeit: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
- Nicht autorisierte Nur-Befehl-Nachrichten werden stillschweigend ignoriert, und Inline-`/...`-Token werden als normaler Text behandelt.
- **Skill-Befehle:** `user-invocable` Skills werden als Slash-Befehle bereitgestellt. Namen werden auf `a-z0-9_` bereinigt (max. 32 Zeichen); bei Kollisionen werden numerische Suffixe angehängt (z. B. `_2`).
- `/skill <name> [input]` führt einen Skill anhand des Namens aus (nützlich, wenn native Befehlsgrenzen Befehle pro Skill verhindern).
- `/trace` ist enger gefasst als `/verbose`: Es zeigt nur plugin-eigene Trace-/Debug-Zeilen an und lässt normales ausführliches Tool-Logging ausgeschaltet.
- `/fast on|off` persistiert eine Sitzungsüberschreibung. Verwenden Sie in der Sitzungs-UI die Option `inherit`, um sie zu löschen und auf Konfigurationsstandards zurückzufallen.
- `/fast` ist anbieterspezifisch: OpenAI/OpenAI Codex ordnen es auf nativen Responses-Endpunkten `service_tier=priority` zu, während direkte öffentliche Anthropic-Anfragen, einschließlich an `api.anthropic.com` gesendetem OAuth-authentifiziertem Datenverkehr, es `service_tier=auto` oder `standard_only` zuordnen. Siehe [OpenAI](/de/providers/openai) und [Anthropic](/de/providers/anthropic).
- Zusammenfassungen von Tool-Fehlern werden weiterhin angezeigt, wenn relevant, aber detaillierter Fehlertext wird nur eingeschlossen, wenn `/verbose` `on` oder `full` ist.
- `/reasoning`, `/verbose` und `/trace` sind in Gruppensettings riskant: Sie können internes Reasoning, Tool-Ausgaben oder Plugin-Diagnosen offenlegen, die Sie nicht beabsichtigt hatten. Lassen Sie sie bevorzugt deaktiviert, insbesondere in Gruppenchats.
- `/model` persistiert das neue Sitzungsmodell sofort.
- Wenn der Agent untätig ist, verwendet die nächste Ausführung es sofort.
- Wenn bereits eine Ausführung aktiv ist, markiert OpenClaw einen Live-Wechsel als ausstehend und startet erst an einem sauberen Wiederholungspunkt in das neue Modell neu.
- Wenn Tool-Aktivität oder Antwortausgabe bereits begonnen hat, kann der ausstehende Wechsel bis zu einer späteren Wiederholungsmöglichkeit oder dem nächsten Benutzerzug in der Warteschlange bleiben.
- **Schnellpfad:** Nur-Befehl-Nachrichten von zugelassenen Absendern werden sofort verarbeitet (umgehen Queue + Modell).
- **Gruppen-Erwähnungs-Gating:** Nur-Befehl-Nachrichten von zugelassenen Absendern umgehen Erwähnungsanforderungen.
- **Inline-Kurzbefehle (nur für zugelassene Absender):** Bestimmte Befehle funktionieren auch, wenn sie in eine normale Nachricht eingebettet sind, und werden entfernt, bevor das Modell den verbleibenden Text sieht.
- Beispiel: `hey /status` löst eine Statusantwort aus, und der verbleibende Text läuft durch den normalen Ablauf weiter.
- Aktuell: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
- Nicht autorisierte Nur-Befehl-Nachrichten werden stillschweigend ignoriert, und Inline-`/...`-Token werden als Klartext behandelt.
- **Skill-Befehle:** `user-invocable`-Skills werden als Slash-Befehle bereitgestellt. Namen werden auf `a-z0-9_` bereinigt (maximal 32 Zeichen); bei Kollisionen werden numerische Suffixe angehängt (z. B. `_2`).
- `/skill <name> [input]` führt einen Skill nach Namen aus (nützlich, wenn native Befehlsgrenzen Befehle pro Skill verhindern).
- Standardmäßig werden Skill-Befehle als normale Anfrage an das Modell weitergeleitet.
- Skills können optional `command-dispatch: tool` deklarieren, um den Befehl direkt an ein Tool zu leiten (deterministisch, ohne Modell).
- Skills können optional `command-dispatch: tool` deklarieren, um den Befehl direkt an ein Tool zu routen (deterministisch, ohne Modell).
- Beispiel: `/prose` (OpenProse-Plugin) — siehe [OpenProse](/de/prose).
- **Argumente nativer Befehle:** Discord verwendet Autocomplete für dynamische Optionen (und Button-Menüs, wenn Sie erforderliche Argumente weglassen). Telegram und Slack zeigen ein Button-Menü an, wenn ein Befehl Auswahlmöglichkeiten unterstützt und Sie das Argument weglassen.
- **Argumente nativer Befehle:** Discord verwendet Autovervollständigung für dynamische Optionen (und Button-Menüs, wenn Sie erforderliche Argumente weglassen). Telegram und Slack zeigen ein Button-Menü an, wenn ein Befehl Auswahlmöglichkeiten unterstützt und Sie das Argument weglassen.
## `/tools`
`/tools` beantwortet eine Laufzeitfrage, keine Konfigurationsfrage: **was dieser Agent in
dieser Unterhaltung gerade verwenden kann**.
`/tools` beantwortet eine Laufzeitfrage, keine Konfigurationsfrage: **was dieser Agent jetzt gerade in
diesem Gespräch verwenden kann**.
- Standard-`/tools` ist kompakt und für schnelles Überfliegen optimiert.
- `/tools verbose` fügt kurze Beschreibungen hinzu.
- Oberflächen mit nativen Befehlen, die Argumente unterstützen, stellen denselben Moduswechsel als `compact|verbose` bereit.
- Ergebnisse sind sitzungsbezogen, daher können Änderungen an Agent, Channel, Thread, Absenderautorisierung oder Modell
- Oberflächen mit nativen Befehlen, die Argumente unterstützen, bieten denselben Moduswechsel als `compact|verbose`.
- Ergebnisse sind sitzungsbezogen, daher kann das Ändern von Agent, Kanal, Thread, Absenderautorisierung oder Modell
die Ausgabe ändern.
- `/tools` enthält Tools, die zur Laufzeit tatsächlich erreichbar sind, einschließlich Core-Tools, verbundener
Plugin-Tools und Channel-eigener Tools.
- `/tools` enthält Tools, die zur Laufzeit tatsächlich erreichbar sind, einschließlich Kern-Tools, verbundener
Plugin-Tools und kanalbezogener Tools.
Für Profil- und Override-Bearbeitung verwenden Sie das Tools-Panel in der Control UI oder Konfigurations-/Katalogoberflächen,
anstatt `/tools` als statischen Katalog zu behandeln.
Für das Bearbeiten von Profilen und Überschreibungen verwenden Sie das Tools-Panel der Control-UI oder Konfigurations-/Katalogoberflächen, statt
`/tools` als statischen Katalog zu behandeln.
## Nutzungsoberflächen (was wo angezeigt wird)
- **Provider-Nutzung/Kontingent** (Beispiel: „Claude 80% left“) wird in `/status` für den aktuellen Modell-Provider angezeigt, wenn Nutzungsverfolgung aktiviert ist. OpenClaw normalisiert Provider-Fenster auf `% left`; bei MiniMax werden Prozentfelder, die nur den verbleibenden Anteil enthalten, vor der Anzeige invertiert, und Antworten mit `model_remains` bevorzugen den Chat-Modell-Eintrag plus ein modellmarkiertes Tariflabel.
- **Token-/Cache-Zeilen** in `/status` können auf den neuesten Usage-Eintrag im Transcript zurückfallen, wenn der Live-Sitzungs-Snapshot unvollständig ist. Bereits vorhandene Live-Werte ungleich null haben weiterhin Vorrang, und der Transcript-Fallback kann auch das aktive Laufzeit-Modelllabel plus eine größere promptorientierte Gesamtsumme wiederherstellen, wenn gespeicherte Summen fehlen oder kleiner sind.
- **Tokens/Kosten pro Antwort** werden mit `/usage off|tokens|full` gesteuert (an normale Antworten angehängt).
- `/model status` bezieht sich auf **Modelle/Auth/Endpunkte**, nicht auf Nutzung.
- **Anbieternutzung/Kontingent** (Beispiel: „Claude 80% left“) erscheint in `/status` für den aktuellen Modellanbieter, wenn Nutzungsverfolgung aktiviert ist. OpenClaw normalisiert Anbieterfenster zu `% left`; bei MiniMax werden verbleibend-only-Prozentfelder vor der Anzeige invertiert, und Antworten mit `model_remains` bevorzugen den Chat-Modelleintrag plus ein modellmarkiertes Plan-Label.
- **Token-/Cache-Zeilen** in `/status` können auf den neuesten Nutzungseintrag im Transkript zurückfallen, wenn der Live-Sitzungs-Snapshot spärlich ist. Vorhandene von null verschiedene Live-Werte haben weiterhin Vorrang, und der Transkript-Fallback kann auch das aktive Laufzeitmodell-Label plus eine größere promptorientierte Gesamtsumme wiederherstellen, wenn gespeicherte Summen fehlen oder kleiner sind.
- **Tokens/Kosten pro Antwort** werden über `/usage off|tokens|full` gesteuert (an normale Antworten angehängt).
- `/model status` betrifft **Modelle/Auth/Endpunkte**, nicht die Nutzung.
## Modellauswahl (`/model`)
@ -253,14 +253,14 @@ Beispiele:
Hinweise:
- `/model` und `/model list` zeigen einen kompakten nummerierten Auswahlbereich (Modellfamilie + verfügbare Provider).
- Auf Discord öffnen `/model` und `/models` einen interaktiven Auswahlbereich mit Provider- und Modell-Dropdowns plus einem Schritt zum Absenden.
- `/model <#>` wählt aus diesem Auswahlbereich aus (und bevorzugt nach Möglichkeit den aktuellen Provider).
- `/model status` zeigt die Detailansicht, einschließlich konfiguriertem Provider-Endpunkt (`baseUrl`) und API-Modus (`api`), sofern verfügbar.
- `/model` und `/model list` zeigen eine kompakte, nummerierte Auswahl an (Modellfamilie + verfügbare Anbieter).
- Auf Discord öffnen `/model` und `/models` eine interaktive Auswahl mit Dropdowns für Anbieter und Modell plus einem Submit-Schritt.
- `/model <#>` wählt aus dieser Auswahl aus (und bevorzugt wenn möglich den aktuellen Anbieter).
- `/model status` zeigt die Detailansicht an, einschließlich konfiguriertem Anbieter-Endpunkt (`baseUrl`) und API-Modus (`api`), sofern verfügbar.
## Debug-Overrides
## Debug-Überschreibungen
`/debug` ermöglicht das Setzen von **nur zur Laufzeit geltenden** Konfigurations-Overrides (Memory, nicht Festplatte). Nur Owner. Standardmäßig deaktiviert; aktivieren Sie es mit `commands.debug: true`.
`/debug` ermöglicht das Setzen von **nur zur Laufzeit gültigen** Konfigurationsüberschreibungen (Arbeitsspeicher, nicht Festplatte). Nur Eigentümer. Standardmäßig deaktiviert; aktivieren Sie es mit `commands.debug: true`.
Beispiele:
@ -274,12 +274,12 @@ Beispiele:
Hinweise:
- Overrides gelten sofort für neue Konfigurationslesevorgänge, schreiben aber **nicht** in `openclaw.json`.
- Verwenden Sie `/debug reset`, um alle Overrides zu löschen und zur Konfiguration auf der Festplatte zurückzukehren.
- Überschreibungen gelten sofort für neue Konfigurationslesevorgänge, schreiben aber **nicht** in `openclaw.json`.
- Verwenden Sie `/debug reset`, um alle Überschreibungen zu löschen und zur Konfiguration auf Datenträger zurückzukehren.
## Plugin-Trace-Ausgabe
`/trace` ermöglicht das Umschalten von **sitzungsbezogenen Plugin-Trace-/Debug-Zeilen**, ohne den vollständigen Verbose-Modus einzuschalten.
`/trace` ermöglicht das Umschalten **sitzungsbezogener pluginbezogener Trace-/Debug-Zeilen**, ohne den vollständigen ausführlichen Modus einzuschalten.
Beispiele:
@ -295,12 +295,12 @@ Hinweise:
- `/trace on` aktiviert Plugin-Trace-Zeilen für die aktuelle Sitzung.
- `/trace off` deaktiviert sie wieder.
- Plugin-Trace-Zeilen können in `/status` und als diagnostische Folgemeldung nach der normalen Assistentenantwort erscheinen.
- `/trace` ersetzt `/debug` nicht; `/debug` verwaltet weiterhin nur Laufzeit-Konfigurations-Overrides.
- `/trace` ersetzt `/debug` nicht; `/debug` verwaltet weiterhin nur zur Laufzeit gültige Konfigurationsüberschreibungen.
- `/trace` ersetzt `/verbose` nicht; normale ausführliche Tool-/Statusausgabe gehört weiterhin zu `/verbose`.
## Konfigurationsaktualisierungen
`/config` schreibt in Ihre Konfiguration auf der Festplatte (`openclaw.json`). Nur Owner. Standardmäßig deaktiviert; aktivieren Sie es mit `commands.config: true`.
`/config` schreibt in Ihre Konfiguration auf Datenträger (`openclaw.json`). Nur Eigentümer. Standardmäßig deaktiviert; aktivieren Sie es mit `commands.config: true`.
Beispiele:
@ -315,11 +315,11 @@ Beispiele:
Hinweise:
- Die Konfiguration wird vor dem Schreiben validiert; ungültige Änderungen werden abgelehnt.
- `/config`-Aktualisierungen bleiben über Neustarts hinweg erhalten.
- Aktualisierungen durch `/config` bleiben über Neustarts hinweg erhalten.
## MCP-Aktualisierungen
`/mcp` schreibt von OpenClaw verwaltete MCP-Serverdefinitionen unter `mcp.servers`. Nur Owner. Standardmäßig deaktiviert; aktivieren Sie es mit `commands.mcp: true`.
`/mcp` schreibt von OpenClaw verwaltete MCP-Serverdefinitionen unter `mcp.servers`. Nur Eigentümer. Standardmäßig deaktiviert; aktivieren Sie es mit `commands.mcp: true`.
Beispiele:
@ -332,12 +332,12 @@ Beispiele:
Hinweise:
- `/mcp` speichert die Konfiguration in der OpenClaw-Konfiguration, nicht in Pi-eigenen Projekteinstellungen.
- Laufzeit-Adapter entscheiden, welche Transporte tatsächlich ausführbar sind.
- `/mcp` speichert Konfiguration in der OpenClaw-Konfiguration, nicht in Pi-eigenen Projekteinstellungen.
- Laufzeitadapter entscheiden, welche Transporte tatsächlich ausführbar sind.
## Plugin-Aktualisierungen
`/plugins` ermöglicht es Operatoren, erkannte Plugins zu prüfen und deren Aktivierung in der Konfiguration umzuschalten. Schreibgeschützte Abläufe können `/plugin` als Alias verwenden. Standardmäßig deaktiviert; aktivieren Sie es mit `commands.plugins: true`.
`/plugins` ermöglicht es Operatoren, erkannte Plugins zu prüfen und die Aktivierung in der Konfiguration umzuschalten. Nur-Lese-Abläufe können `/plugin` als Alias verwenden. Standardmäßig deaktiviert; aktivieren Sie es mit `commands.plugins: true`.
Beispiele:
@ -351,41 +351,41 @@ Beispiele:
Hinweise:
- `/plugins list` und `/plugins show` verwenden echte Plugin-Erkennung anhand des aktuellen Workspace plus der Konfiguration auf der Festplatte.
- `/plugins enable|disable` aktualisiert nur die Plugin-Konfiguration; Plugins werden dadurch nicht installiert oder deinstalliert.
- Starten Sie das Gateway nach Änderungen an enable/disable neu, damit sie wirksam werden.
- `/plugins list` und `/plugins show` verwenden echte Plugin-Erkennung gegen den aktuellen Workspace plus die Konfiguration auf Datenträger.
- `/plugins enable|disable` aktualisiert nur die Plugin-Konfiguration; Plugins werden nicht installiert oder deinstalliert.
- Starten Sie das Gateway nach Änderungen an Aktivieren/Deaktivieren neu, damit sie angewendet werden.
## Hinweise zu Oberflächen
- **Textbefehle** laufen in der normalen Chat-Sitzung (DMs teilen sich `main`, Gruppen haben ihre eigene Sitzung).
- **Textbefehle** laufen in der normalen Chatsitzung (DMs teilen sich `main`, Gruppen haben ihre eigene Sitzung).
- **Native Befehle** verwenden isolierte Sitzungen:
- Discord: `agent:<agentId>:discord:slash:<userId>`
- Slack: `agent:<agentId>:slack:slash:<userId>` (Präfix über `channels.slack.slashCommand.sessionPrefix` konfigurierbar)
- Telegram: `telegram:slash:<userId>` (zielt über `CommandTargetSessionKey` auf die Chat-Sitzung)
- **`/stop`** zielt auf die aktive Chat-Sitzung, damit der aktuelle Durchlauf abgebrochen werden kann.
- **Slack:** `channels.slack.slashCommand` wird weiterhin für einen einzelnen Befehl im Stil von `/openclaw` unterstützt. Wenn Sie `commands.native` aktivieren, müssen Sie einen Slack-Slash-Befehl pro integrierten Befehl erstellen (mit denselben Namen wie `/help`). Menüs für Befehlsargumente werden bei Slack als ephemere Block-Kit-Buttons bereitgestellt.
- Native Slack-Ausnahme: Registrieren Sie `/agentstatus` (nicht `/status`), weil Slack `/status` reserviert. Text-`/status` funktioniert in Slack-Nachrichten weiterhin.
- Telegram: `telegram:slash:<userId>` (zielt über `CommandTargetSessionKey` auf die Chatsitzung)
- **`/stop`** zielt auf die aktive Chatsitzung, damit die aktuelle Ausführung abgebrochen werden kann.
- **Slack:** `channels.slack.slashCommand` wird weiterhin für einen einzelnen Befehl im Stil von `/openclaw` unterstützt. Wenn Sie `commands.native` aktivieren, müssen Sie einen Slack-Slash-Befehl pro integriertem Befehl anlegen (mit denselben Namen wie `/help`). Menüs für Befehlsargumente werden in Slack als ephemere Block-Kit-Buttons bereitgestellt.
- Native Slack-Ausnahme: Registrieren Sie `/agentstatus` (nicht `/status`), weil Slack `/status` reserviert. Text-`/status` funktioniert weiterhin in Slack-Nachrichten.
## BTW-Nebenfragen
`/btw` ist eine schnelle **Nebenfrage** zur aktuellen Sitzung.
Im Gegensatz zu normalem Chat:
Anders als normaler Chat:
- verwendet sie die aktuelle Sitzung als Hintergrundkontext,
- läuft sie als separater **tool-loser** Einmalaufruf,
- ändert sie den zukünftigen Sitzungskontext nicht,
- wird sie nicht in den Transcript-Verlauf geschrieben,
- wird sie als Live-Seitenergebnis statt als normale Assistentennachricht zugestellt.
- verwendet es die aktuelle Sitzung als Hintergrundkontext,
- läuft es als separater **tool-loser** One-Shot-Aufruf,
- ändert es den zukünftigen Sitzungskontext nicht,
- wird es nicht in den Transkriptverlauf geschrieben,
- wird es als Live-Nebenergebnis statt als normale Assistentennachricht zugestellt.
Dadurch ist `/btw` nützlich, wenn Sie eine vorübergehende Klärung möchten, während die Haupt-
Das macht `/btw` nützlich, wenn Sie eine vorübergehende Klärung möchten, während die Haupt-
aufgabe weiterläuft.
Beispiel:
```text
/btw what are we doing right now?
/btw was machen wir gerade?
```
Siehe [BTW Side Questions](/de/tools/btw) für das vollständige Verhalten und die
Details der Client-UX.
Siehe [BTW Side Questions](/de/tools/btw) für das vollständige Verhalten und Details
zur Client-UX.

156
docs/de/tools/thinking.md
View File

@ -1,127 +1,131 @@
---
read_when:
- Anpassen von Thinking, Schnellmodus oder der Verarbeitung bzw. Standardwerte von Direktiven für ausführliche Ausgabe
summary: Syntax für Direktiven für /think, /fast, /verbose, /trace und die Sichtbarkeit von Reasoning
title: Thinking-Stufen
- Parsing oder Standardwerte für Thinking-, Fast-Mode- oder Verbose-Direktiven anpassen
summary: Direktivsyntax für /think, /fast, /verbose, /trace und die Sichtbarkeit von Reasoning
title: Thinking-Level
x-i18n:
generated_at: "2026-04-21T06:31:57Z"
generated_at: "2026-04-21T13:38:06Z"
model: gpt-5.4
provider: openai
source_hash: edee9420e1cc3eccfa18d87061c4a4d6873e70cb51fff85305fafbcd6a5d6a7d
source_hash: 1b0217f6e5a5cb3400090f31ad5271ca61848a40f77d3f942851e7c2f2352886
source_path: tools/thinking.md
workflow: 15
---
# Thinking-Stufen (`/think`-Direktiven)
# Thinking-Level (/think-Direktiven)
## Was es bewirkt
- Inline-Direktive in jedem eingehenden Text: `/t <level>`, `/think:<level>` oder `/thinking <level>`.
- Stufen (Aliasse): `off | minimal | low | medium | high | xhigh | adaptive | max`
- Inline-Direktive in jedem eingehenden Body: `/t <level>`, `/think:<level>` oder `/thinking <level>`.
- Level (Aliase): `off | minimal | low | medium | high | xhigh | adaptive | max`
- minimal → „think“
- low → „think hard“
- medium → „think harder“
- high → „ultrathink“ (maximales Budget)
- xhigh → „ultrathink+“ (GPT-5.2 + Codex-Modelle und Anthropic Claude Opus 4.7 effort)
- xhigh → „ultrathink+“ (GPT-5.2- und Codex-Modelle sowie Anthropic Claude Opus 4.7 effort)
- adaptive → vom Provider verwaltetes adaptives Thinking (unterstützt für Claude 4.6 auf Anthropic/Bedrock und Anthropic Claude Opus 4.7)
- max → maximales Reasoning des Providers (derzeit Anthropic Claude Opus 4.7)
- max → maximales Provider-Reasoning (derzeit Anthropic Claude Opus 4.7)
- `x-high`, `x_high`, `extra-high`, `extra high` und `extra_high` werden auf `xhigh` abgebildet.
- `highest` wird auf `high` abgebildet.
- Hinweise zu Providern:
- `adaptive` wird in nativen Befehlsmenüs und Auswahllisten nur für Provider/Modelle angezeigt, die Unterstützung für adaptives Thinking deklarieren. Es bleibt als getippte Direktive zur Kompatibilität mit vorhandenen Konfigurationen und Aliasen weiterhin akzeptiert.
- `max` wird in nativen Befehlsmenüs und Auswahllisten nur für Provider/Modelle angezeigt, die Unterstützung für maximales Thinking deklarieren. Vorhandene gespeicherte Einstellungen `max` werden auf die größte unterstützte Stufe für das ausgewählte Modell umgebildet, wenn das Modell `max` nicht unterstützt.
- Anthropic-Claude-4.6-Modelle verwenden standardmäßig `adaptive`, wenn keine explizite Thinking-Stufe gesetzt ist.
- Anthropic Claude Opus 4.7 verwendet standardmäßig kein adaptives Thinking. Der Standard für API-effort bleibt Eigentum des Providers, sofern Sie nicht explizit eine Thinking-Stufe setzen.
- Anthropic Claude Opus 4.7 bildet `/think xhigh` auf adaptives Thinking plus `output_config.effort: "xhigh"` ab, weil `/think` eine Thinking-Direktive ist und `xhigh` die Opus-4.7-Einstellung für effort ist.
- Anthropic Claude Opus 4.7 bietet auch `/think max`; es wird auf denselben vom Provider verwalteten Pfad für maximalen effort abgebildet.
- OpenAI-GPT-Modelle bilden `/think` über die modellabhängige Unterstützung der Responses API für effort ab. `/think off` sendet `reasoning.effort: "none"` nur dann, wenn das Zielmodell dies unterstützt; andernfalls lässt OpenClaw die Payload für deaktiviertes Reasoning weg, statt einen nicht unterstützten Wert zu senden.
- MiniMax (`minimax/*`) auf dem Anthropic-kompatiblen Streaming-Pfad verwendet standardmäßig `thinking: { type: "disabled" }`, sofern Sie Thinking nicht explizit in Modellparametern oder Anfrageparametern setzen. Dies vermeidet durchgesickerte Deltas von `reasoning_content` aus dem nicht nativen Anthropic-Stream-Format von MiniMax.
- Z.AI (`zai/*`) unterstützt nur binäres Thinking (`on`/`off`). Jede Stufe außer `off` wird als `on` behandelt (auf `low` abgebildet).
- Moonshot (`moonshot/*`) bildet `/think off` auf `thinking: { type: "disabled" }` und jede Stufe außer `off` auf `thinking: { type: "enabled" }` ab. Wenn Thinking aktiviert ist, akzeptiert Moonshot für `tool_choice` nur `auto|none`; OpenClaw normalisiert inkompatible Werte auf `auto`.
- Thinking-Menüs und -Picker sind providerprofilgesteuert. Provider-Plugins deklarieren den genauen Level-Satz für das ausgewählte Modell, einschließlich Labels wie binäres `on`.
- `adaptive`, `xhigh` und `max` werden nur für Provider-/Modellprofile angezeigt, die sie unterstützen. Eingegebene Direktiven für nicht unterstützte Level werden mit den gültigen Optionen dieses Modells abgelehnt.
- Bereits gespeicherte, nicht unterstützte Level, einschließlich alter `max`-Werte nach einem Modellwechsel, werden auf das höchste unterstützte Level für das ausgewählte Modell umgebildet.
- Anthropic-Claude-4.6-Modelle verwenden standardmäßig `adaptive`, wenn kein explizites Thinking-Level gesetzt ist.
- Anthropic Claude Opus 4.7 verwendet standardmäßig kein adaptives Thinking. Sein standardmäßiger API-effort bleibt providerseitig verwaltet, sofern Sie nicht explizit ein Thinking-Level setzen.
- Anthropic Claude Opus 4.7 bildet `/think xhigh` auf adaptives Thinking plus `output_config.effort: "xhigh"` ab, weil `/think` eine Thinking-Direktive ist und `xhigh` die Opus-4.7-effort-Einstellung ist.
- Anthropic Claude Opus 4.7 stellt auch `/think max` bereit; dies wird auf denselben providerseitigen Pfad für maximalen effort abgebildet.
- OpenAI-GPT-Modelle bilden `/think` über modellabhängige Unterstützung für effort in der Responses API ab. `/think off` sendet `reasoning.effort: "none"` nur dann, wenn das Zielmodell dies unterstützt; andernfalls lässt OpenClaw die deaktivierte Reasoning-Payload weg, statt einen nicht unterstützten Wert zu senden.
- MiniMax (`minimax/*`) auf dem Anthropic-kompatiblen Streaming-Pfad verwendet standardmäßig `thinking: { type: "disabled" }`, sofern Sie Thinking nicht explizit in Modellparametern oder Request-Parametern setzen. Dies verhindert durchgesickerte `reasoning_content`-Deltas aus dem nicht nativen Anthropic-Stream-Format von MiniMax.
- Z.AI (`zai/*`) unterstützt nur binäres Thinking (`on`/`off`). Jedes andere Level als `off` wird als `on` behandelt (abgebildet auf `low`).
- Moonshot (`moonshot/*`) bildet `/think off` auf `thinking: { type: "disabled" }` und jedes andere Level als `off` auf `thinking: { type: "enabled" }` ab. Wenn Thinking aktiviert ist, akzeptiert Moonshot für `tool_choice` nur `auto|none`; OpenClaw normalisiert inkompatible Werte auf `auto`.
## Reihenfolge der Auflösung
## Auflösungsreihenfolge
1. Inline-Direktive in der Nachricht (gilt nur für diese Nachricht).
2. Sitzungsüberschreibung (gesetzt durch das Senden einer Nachricht, die nur aus einer Direktive besteht).
3. Standard pro Agent (`agents.list[].thinkingDefault` in der Konfiguration).
4. Globaler Standard (`agents.defaults.thinkingDefault` in der Konfiguration).
5. Fallback: `adaptive` für Anthropic-Claude-4.6-Modelle, `off` für Anthropic Claude Opus 4.7, sofern nicht explizit konfiguriert, `low` für andere Reasoning-fähige Modelle, sonst `off`.
2. Sitzungsüberschreibung (gesetzt durch Senden einer Nachricht, die nur aus einer Direktive besteht).
3. Standardwert pro Agent (`agents.list[].thinkingDefault` in der Konfiguration).
4. Globaler Standardwert (`agents.defaults.thinkingDefault` in der Konfiguration).
5. Fallback: vom Provider deklarierter Standardwert, falls verfügbar, `low` für andere Katalogmodelle mit aktivierter Reasoning-Fähigkeit, sonst `off`.
## Einen Sitzungsstandard setzen
- Senden Sie eine Nachricht, die **nur** aus der Direktive besteht (Leerraum ist erlaubt), z. B. `/think:medium` oder `/t high`.
- Das bleibt für die aktuelle Sitzung bestehen (standardmäßig pro Absender); wird durch `/think:off` oder einen Leerlauf-Reset der Sitzung gelöscht.
- Es wird eine Bestätigungsantwort gesendet (`Thinking level set to high.` / `Thinking disabled.`). Wenn die Stufe ungültig ist (z. B. `/thinking big`), wird der Befehl mit einem Hinweis abgelehnt, und der Sitzungsstatus bleibt unverändert.
- Senden Sie `/think` (oder `/think:`) ohne Argument, um die aktuelle Thinking-Stufe zu sehen.
- Senden Sie eine Nachricht, die **nur** aus der Direktive besteht (Leerraum erlaubt), z. B. `/think:medium` oder `/t high`.
- Das bleibt für die aktuelle Sitzung bestehen (standardmäßig pro Absender); zurückgesetzt durch `/think:off` oder Sitzungs-Idle-Reset.
- Eine Bestätigungsantwort wird gesendet (`Thinking level set to high.` / `Thinking disabled.`). Wenn das Level ungültig ist (z. B. `/thinking big`), wird der Befehl mit einem Hinweis abgelehnt und der Sitzungszustand bleibt unverändert.
- Senden Sie `/think` (oder `/think:`) ohne Argument, um das aktuelle Thinking-Level anzuzeigen.
## Anwendung nach Agent
- **Embedded Pi**: Die aufgelöste Stufe wird an die Laufzeit des In-Process-Pi-Agenten übergeben.
- **Eingebettetes Pi**: Das aufgelöste Level wird an die In-Process-Agent-Laufzeit von Pi übergeben.
## Schnellmodus (`/fast`)
## Fast-Modus (/fast)
- Stufen: `on|off`.
- Eine Nachricht, die nur aus einer Direktive besteht, schaltet eine Sitzungsüberschreibung für den Schnellmodus um und antwortet mit `Fast mode enabled.` / `Fast mode disabled.`.
- Senden Sie `/fast` (oder `/fast status`) ohne Modus, um den aktuellen effektiven Status des Schnellmodus zu sehen.
- OpenClaw löst den Schnellmodus in dieser Reihenfolge auf:
1. Inline-/nur-Direktive `/fast on|off`
- Level: `on|off`.
- Eine Nachricht, die nur aus einer Direktive besteht, schaltet eine Sitzungsüberschreibung für den Fast-Modus um und antwortet mit `Fast mode enabled.` / `Fast mode disabled.`.
- Senden Sie `/fast` (oder `/fast status`) ohne Modus, um den aktuell wirksamen Fast-Mode-Status anzuzeigen.
- OpenClaw löst den Fast-Modus in dieser Reihenfolge auf:
1. Inline-/Direktive-only-`/fast on|off`
2. Sitzungsüberschreibung
3. Standard pro Agent (`agents.list[].fastModeDefault`)
3. Standardwert pro Agent (`agents.list[].fastModeDefault`)
4. Konfiguration pro Modell: `agents.defaults.models["<provider>/<model>"].params.fastMode`
5. Fallback: `off`
- Für `openai/*` wird der Schnellmodus auf die Prioritätsverarbeitung von OpenAI abgebildet, indem bei unterstützten Responses-Anfragen `service_tier=priority` gesendet wird.
- Für `openai-codex/*` sendet der Schnellmodus dasselbe Flag `service_tier=priority` bei Codex Responses. OpenClaw behält einen gemeinsamen Umschalter `/fast` für beide Authentifizierungspfade bei.
- Für direkte öffentliche `anthropic/*`-Anfragen, einschließlich per OAuth authentifiziertem Datenverkehr an `api.anthropic.com`, wird der Schnellmodus auf die Service-Tiers von Anthropic abgebildet: `/fast on` setzt `service_tier=auto`, `/fast off` setzt `service_tier=standard_only`.
- Für `openai/*` wird der Fast-Modus auf priorisierte OpenAI-Verarbeitung abgebildet, indem bei unterstützten Responses-Requests `service_tier=priority` gesendet wird.
- Für `openai-codex/*` sendet der Fast-Modus dasselbe Flag `service_tier=priority` bei Codex Responses. OpenClaw verwendet einen gemeinsamen `/fast`-Schalter über beide Auth-Pfade hinweg.
- Für direkte öffentliche `anthropic/*`-Requests, einschließlich per OAuth authentifiziertem Traffic an `api.anthropic.com`, wird der Fast-Modus auf Anthropic-Service-Tiers abgebildet: `/fast on` setzt `service_tier=auto`, `/fast off` setzt `service_tier=standard_only`.
- Für `minimax/*` auf dem Anthropic-kompatiblen Pfad schreibt `/fast on` (oder `params.fastMode: true`) `MiniMax-M2.7` in `MiniMax-M2.7-highspeed` um.
- Explizite Anthropic-Modellparameter `serviceTier` / `service_tier` überschreiben den Standard des Schnellmodus, wenn beide gesetzt sind. OpenClaw überspringt weiterhin das Einfügen des Anthropic-Service-Tiers für Base-URLs von Nicht-Anthropic-Proxys.
- Explizite Anthropic-Modellparameter `serviceTier` / `service_tier` überschreiben den Standard des Fast-Modus, wenn beide gesetzt sind. OpenClaw überspringt weiterhin die Einfügung von Anthropic-Service-Tiers für nicht-Anthropic-Proxy-`baseUrl`s.
## Direktiven für ausführliche Ausgabe (`/verbose` oder `/v`)
## Verbose-Direktiven (/verbose oder /v)
- Stufen: `on` (minimal) | `full` | `off` (Standard).
- Eine Nachricht, die nur aus einer Direktive besteht, schaltet die ausführliche Ausgabe für die Sitzung um und antwortet mit `Verbose logging enabled.` / `Verbose logging disabled.`; ungültige Stufen liefern einen Hinweis, ohne den Status zu ändern.
- `/verbose off` speichert eine explizite Sitzungsüberschreibung; löschen Sie sie über die Sitzungs-UI, indem Sie `inherit` wählen.
- Eine Inline-Direktive wirkt sich nur auf diese Nachricht aus; ansonsten gelten Standardwerte für Sitzung/global.
- Senden Sie `/verbose` (oder `/verbose:`) ohne Argument, um die aktuelle Stufe für ausführliche Ausgabe zu sehen.
- Wenn die ausführliche Ausgabe aktiviert ist, senden Agenten, die strukturierte Tool-Ergebnisse ausgeben (Pi, andere JSON-Agenten), jeden Tool-Aufruf als eigene Nachricht nur mit Metadaten zurück, mit dem Präfix `<emoji> <tool-name>: <arg>`, sofern verfügbar (Pfad/Befehl). Diese Tool-Zusammenfassungen werden gesendet, sobald jedes Tool startet (separate Blasen), nicht als Streaming-Deltas.
- Zusammenfassungen von Tool-Fehlern bleiben im normalen Modus sichtbar, aber rohe Fehlersuffixe werden verborgen, sofern `verbose` nicht `on` oder `full` ist.
- Wenn `verbose` `full` ist, werden Tool-Ausgaben nach Abschluss ebenfalls weitergeleitet (separate Blase, auf eine sichere Länge gekürzt). Wenn Sie während eines laufenden Vorgangs `/verbose on|full|off` umschalten, berücksichtigen nachfolgende Tool-Blasen die neue Einstellung.
- Level: `on` (minimal) | `full` | `off` (Standard).
- Eine Nachricht, die nur aus einer Direktive besteht, schaltet Verbose auf Sitzungsebene um und antwortet mit `Verbose logging enabled.` / `Verbose logging disabled.`; ungültige Level liefern einen Hinweis zurück, ohne den Zustand zu ändern.
- `/verbose off` speichert eine explizite Sitzungsüberschreibung; löschen Sie sie über die Sessions-UI, indem Sie `inherit` auswählen.
- Eine Inline-Direktive gilt nur für diese Nachricht; Sitzungs-/globale Standardwerte gelten sonst.
- Senden Sie `/verbose` (oder `/verbose:`) ohne Argument, um das aktuelle Verbose-Level anzuzeigen.
- Wenn Verbose aktiviert ist, senden Agenten, die strukturierte Tool-Ergebnisse ausgeben (Pi, andere JSON-Agenten), jeden Tool-Aufruf als eigene Nachricht nur mit Metadaten zurück, sofern verfügbar mit Präfix `<emoji> <tool-name>: <arg>` (Pfad/Befehl). Diese Tool-Zusammenfassungen werden gesendet, sobald jedes Tool startet (separate Bubbles), nicht als Streaming-Deltas.
- Zusammenfassungen von Tool-Fehlern bleiben im normalen Modus sichtbar, aber rohe Detailsuffixe von Fehlern werden ausgeblendet, sofern Verbose nicht `on` oder `full` ist.
- Wenn Verbose `full` ist, werden Tool-Ausgaben nach Abschluss ebenfalls weitergeleitet (separate Bubble, auf eine sichere Länge gekürzt). Wenn Sie `/verbose on|full|off` während einer laufenden Ausführung umschalten, berücksichtigen nachfolgende Tool-Bubbles die neue Einstellung.
## Plugin-Trace-Direktiven (`/trace`)
## Plugin-Trace-Direktiven (/trace)
- Stufen: `on` | `off` (Standard).
- Eine Nachricht, die nur aus einer Direktive besteht, schaltet die Plugin-Trace-Ausgabe für die Sitzung um und antwortet mit `Plugin trace enabled.` / `Plugin trace disabled.`.
- Eine Inline-Direktive wirkt sich nur auf diese Nachricht aus; ansonsten gelten Standardwerte für Sitzung/global.
- Senden Sie `/trace` (oder `/trace:`) ohne Argument, um die aktuelle Trace-Stufe zu sehen.
- `/trace` ist enger gefasst als `/verbose`: Es zeigt nur Plugin-eigene Trace-/Debug-Zeilen wie Active-Memory-Debug-Zusammenfassungen an.
- Trace-Zeilen können in `/status` und als nachfolgende Diagnosenachricht nach der normalen Assistentenantwort erscheinen.
- Level: `on` | `off` (Standard).
- Eine Nachricht, die nur aus einer Direktive besteht, schaltet die Plugin-Trace-Ausgabe auf Sitzungsebene um und antwortet mit `Plugin trace enabled.` / `Plugin trace disabled.`.
- Eine Inline-Direktive gilt nur für diese Nachricht; Sitzungs-/globale Standardwerte gelten sonst.
- Senden Sie `/trace` (oder `/trace:`) ohne Argument, um das aktuelle Trace-Level anzuzeigen.
- `/trace` ist enger als `/verbose`: Es zeigt nur plugin-eigene Trace-/Debug-Zeilen wie Debug-Zusammenfassungen von Active Memory an.
- Trace-Zeilen können in `/status` und als nachfolgende Diagnosenachricht nach der normalen Assistant-Antwort erscheinen.
## Sichtbarkeit von Reasoning (`/reasoning`)
## Sichtbarkeit von Reasoning (/reasoning)
- Stufen: `on|off|stream`.
- Level: `on|off|stream`.
- Eine Nachricht, die nur aus einer Direktive besteht, schaltet um, ob Thinking-Blöcke in Antworten angezeigt werden.
- Wenn aktiviert, wird Reasoning als **separate Nachricht** gesendet, mit dem Präfix `Reasoning:`.
- `stream` (nur Telegram): streamt Reasoning in die Telegram-Entwurfsblase, während die Antwort erzeugt wird, und sendet dann die endgültige Antwort ohne Reasoning.
- Wenn aktiviert, wird Reasoning als **separate Nachricht** mit dem Präfix `Reasoning:` gesendet.
- `stream` (nur Telegram): streamt Reasoning in die Telegram-Entwurfs-Bubble, während die Antwort erzeugt wird, und sendet dann die finale Antwort ohne Reasoning.
- Alias: `/reason`.
- Senden Sie `/reasoning` (oder `/reasoning:`) ohne Argument, um die aktuelle Reasoning-Stufe zu sehen.
- Reihenfolge der Auflösung: Inline-Direktive, dann Sitzungsüberschreibung, dann Standard pro Agent (`agents.list[].reasoningDefault`), dann Fallback (`off`).
- Senden Sie `/reasoning` (oder `/reasoning:`) ohne Argument, um das aktuelle Reasoning-Level anzuzeigen.
- Auflösungsreihenfolge: Inline-Direktive, dann Sitzungsüberschreibung, dann Standardwert pro Agent (`agents.list[].reasoningDefault`), dann Fallback (`off`).
## Verwandt
- Dokumentation zum Elevated-Modus finden Sie unter [Elevated mode](/de/tools/elevated).
- Die Dokumentation zum Elevated mode finden Sie unter [Elevated mode](/de/tools/elevated).
## Heartbeats
- Der Body des Heartbeat-Probes ist der konfigurierte Heartbeat-Prompt (Standard: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Inline-Direktiven in einer Heartbeat-Nachricht gelten wie üblich (vermeiden Sie jedoch, Sitzungsstandards über Heartbeats zu ändern).
- Die Zustellung von Heartbeat verwendet standardmäßig nur die endgültige Payload. Um auch die separate Nachricht `Reasoning:` zu senden (falls verfügbar), setzen Sie `agents.defaults.heartbeat.includeReasoning: true` oder pro Agent `agents.list[].heartbeat.includeReasoning: true`.
- Der Heartbeat-Probe-Body ist der konfigurierte Heartbeat-Prompt (Standard: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Inline-Direktiven in einer Heartbeat-Nachricht gelten wie üblich (vermeiden Sie aber, Sitzungsstandardwerte über Heartbeats zu ändern).
- Die Heartbeat-Zustellung verwendet standardmäßig nur die finale Payload. Um zusätzlich die separate `Reasoning:`-Nachricht zu senden (falls verfügbar), setzen Sie `agents.defaults.heartbeat.includeReasoning: true` oder pro Agent `agents.list[].heartbeat.includeReasoning: true`.
## Webchat-UI
## Web-Chat-UI
- Der Thinking-Selektor im Webchat spiegelt beim Laden der Seite die gespeicherte Stufe der Sitzung aus dem eingehenden Sitzungsspeicher bzw. der Konfiguration wider.
- Die Auswahl einer anderen Stufe schreibt die Sitzungsüberschreibung sofort über `sessions.patch`; sie wartet nicht auf das nächste Senden und ist keine einmalige Überschreibung `thinkingOnce`.
- Die erste Option ist immer `Default (<resolved level>)`, wobei der aufgelöste Standard vom aktiven Sitzungsmodell kommt: `adaptive` für Claude 4.6 auf Anthropic, `off` für Anthropic Claude Opus 4.7, sofern nicht konfiguriert, `low` für andere Reasoning-fähige Modelle, sonst `off`.
- Der Picker bleibt Provider-sensitiv:
- die meisten Provider zeigen `off | minimal | low | medium | high`
- Anthropic/Bedrock Claude 4.6 zeigt `off | minimal | low | medium | high | adaptive`
- Anthropic Claude Opus 4.7 zeigt `off | minimal | low | medium | high | xhigh | adaptive | max`
- Z.AI zeigt binär `off | on`
- `/think:<level>` funktioniert weiterhin und aktualisiert dieselbe gespeicherte Sitzungsstufe, sodass Chat-Direktiven und der Picker synchron bleiben.
- Der Thinking-Selektor im Web-Chat spiegelt beim Laden der Seite das gespeicherte Level der Sitzung aus dem eingehenden Sitzungs-Store bzw. der Konfiguration wider.
- Die Auswahl eines anderen Levels schreibt die Sitzungsüberschreibung sofort über `sessions.patch`; sie wartet nicht auf das nächste Senden und ist keine einmalige `thinkingOnce`-Überschreibung.
- Die erste Option ist immer `Default (<resolved level>)`, wobei der aufgelöste Standardwert aus dem Thinking-Profil des Providers des aktiven Sitzungsmodells stammt.
- Der Picker verwendet `thinkingOptions`, die von der Gateway-Sitzungszeile zurückgegeben werden. Die Browser-UI verwaltet keine eigene Regex-Liste für Provider; Plugins besitzen die modellspezifischen Level-Sätze.
- `/think:<level>` funktioniert weiterhin und aktualisiert dasselbe gespeicherte Sitzungslevel, sodass Chat-Direktiven und der Picker synchron bleiben.
## Provider-Profile
- Provider-Plugins können `resolveThinkingProfile(ctx)` bereitstellen, um die unterstützten Level und den Standardwert des Modells zu definieren.
- Jedes Profil-Level hat eine gespeicherte kanonische `id` (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` oder `max`) und kann ein Anzeige-`label` enthalten. Binäre Provider verwenden `{ id: "low", label: "on" }`.
- Veröffentliche Legacy-Hooks (`supportsXHighThinking`, `isBinaryThinking` und `resolveDefaultThinkingLevel`) bleiben als Kompatibilitätsadapter erhalten, aber neue benutzerdefinierte Level-Sätze sollten `resolveThinkingProfile` verwenden.
- Gateway-Zeilen stellen `thinkingOptions` und `thinkingDefault` bereit, sodass ACP/Chat-Clients dasselbe Profil rendern, das auch von der Laufzeitvalidierung verwendet wird.