diff --git a/docs/de/channels/zalouser.md b/docs/de/channels/zalouser.md
index 7e2ab5936..1b6a6b437 100644
--- a/docs/de/channels/zalouser.md
+++ b/docs/de/channels/zalouser.md
@@ -1,14 +1,14 @@
---
read_when:
- Zalo Personal für OpenClaw einrichten
- - Fehlerbehebung beim Zalo Personal-Login oder Nachrichtenfluss
+ - Fehlersuche bei der Anmeldung oder dem Nachrichtenfluss von Zalo Personal
summary: Unterstützung für persönliche Zalo-Konten über natives zca-js (QR-Anmeldung), Funktionen und Konfiguration
title: Zalo privat
x-i18n:
- generated_at: "2026-05-02T22:17:01Z"
+ generated_at: "2026-05-04T18:23:31Z"
model: gpt-5.5
provider: openai
- source_hash: 0096775e0017e504130f2e19e05ab8114eadb873a9e11f79ea8f0dd91297567f
+ source_hash: 0f6d27f0ca502e6426abe21d609efd0a168a0b6b0fafe8d52d59f1a717da1ed5
source_path: channels/zalouser.md
workflow: 16
---
@@ -16,33 +16,33 @@ x-i18n:
Status: experimentell. Diese Integration automatisiert ein **persönliches Zalo-Konto** über natives `zca-js` innerhalb von OpenClaw.
-Dies ist eine inoffizielle Integration und kann zur Sperrung oder Deaktivierung des Kontos führen. Nutzung auf eigenes Risiko.
+Dies ist eine inoffizielle Integration und kann zur Kontosperrung oder zum Bann führen. Die Nutzung erfolgt auf eigenes Risiko.
## Gebündeltes Plugin
-Zalo Personal wird in aktuellen OpenClaw-Versionen als gebündeltes Plugin ausgeliefert, daher benötigen normale
-paketierte Builds keine separate Installation.
+Zalo Personal wird in aktuellen OpenClaw-Releases als gebündeltes Plugin ausgeliefert, sodass normale
+paketierte Builds keine separate Installation benötigen.
Wenn Sie einen älteren Build oder eine benutzerdefinierte Installation verwenden, die Zalo Personal ausschließt,
installieren Sie das npm-Paket direkt:
- Installation über CLI: `openclaw plugins install @openclaw/zalouser`
-- Angeheftete Version: `openclaw plugins install @openclaw/zalouser@2026.5.2`
+- Fixierte Version: `openclaw plugins install @openclaw/zalouser@2026.5.2`
- Oder aus einem Source-Checkout: `openclaw plugins install ./path/to/local/zalouser-plugin`
- Details: [Plugins](/de/tools/plugin)
-Es ist keine externe `zca`/`openzca`-CLI-Binärdatei erforderlich.
+Es ist kein externes `zca`/`openzca`-CLI-Binary erforderlich.
-## Schnelleinrichtung (Einsteiger)
+## Schnelle Einrichtung (Einsteiger)
-1. Stellen Sie sicher, dass das Zalo-Personal-Plugin verfügbar ist.
- - Aktuelle paketierte OpenClaw-Versionen bündeln es bereits.
+1. Stellen Sie sicher, dass das Zalo Personal-Plugin verfügbar ist.
+ - Aktuelle paketierte OpenClaw-Releases enthalten es bereits.
- Ältere/benutzerdefinierte Installationen können es manuell mit den obigen Befehlen hinzufügen.
2. Anmelden (QR, auf dem Gateway-Rechner):
- `openclaw channels login --channel zalouser`
- Scannen Sie den QR-Code mit der mobilen Zalo-App.
-3. Kanal aktivieren:
+3. Aktivieren Sie den Kanal:
```json5
{
@@ -63,15 +63,15 @@ Es ist keine externe `zca`/`openzca`-CLI-Binärdatei erforderlich.
- Läuft vollständig im Prozess über `zca-js`.
- Verwendet native Event-Listener, um eingehende Nachrichten zu empfangen.
- Sendet Antworten direkt über die JS-API (Text/Medien/Link).
-- Entwickelt für Anwendungsfälle mit „persönlichem Konto“, bei denen die Zalo Bot API nicht verfügbar ist.
+- Entwickelt für Anwendungsfälle mit „persönlichen Konten“, in denen die Zalo Bot API nicht verfügbar ist.
## Benennung
-Die Kanal-ID ist `zalouser`, um ausdrücklich zu machen, dass hier ein **persönliches Zalo-Benutzerkonto** automatisiert wird (inoffiziell). Wir halten `zalo` für eine mögliche zukünftige offizielle Zalo-API-Integration reserviert.
+Die Kanal-ID ist `zalouser`, um ausdrücklich zu machen, dass dies ein **persönliches Zalo-Benutzerkonto** automatisiert (inoffiziell). Wir halten `zalo` für eine potenzielle zukünftige offizielle Zalo-API-Integration reserviert.
## IDs finden (Verzeichnis)
-Verwenden Sie die Verzeichnis-CLI, um Peers/Gruppen und deren IDs zu ermitteln:
+Verwenden Sie die Verzeichnis-CLI, um Peers/Gruppen und ihre IDs zu ermitteln:
```bash
openclaw directory self --channel zalouser
@@ -81,14 +81,16 @@ openclaw directory groups list --channel zalouser --query "work"
## Grenzen
-- Ausgehender Text wird auf ca. 2000 Zeichen aufgeteilt (Zalo-Client-Grenzen).
+- Ausgehender Text wird in Blöcke von ca. 2000 Zeichen aufgeteilt (Zalo-Client-Grenzen).
- Streaming ist standardmäßig blockiert.
## Zugriffskontrolle (DMs)
`channels.zalouser.dmPolicy` unterstützt: `pairing | allowlist | open | disabled` (Standard: `pairing`).
-`channels.zalouser.allowFrom` akzeptiert Benutzer-IDs oder Namen. Während der Einrichtung werden Namen über die prozessinterne Kontaktsuche des Plugins zu IDs aufgelöst.
+`channels.zalouser.allowFrom` sollte stabile Zalo-Benutzer-IDs verwenden. Während der interaktiven Einrichtung können eingegebene Namen mithilfe der prozessinternen Kontaktsuche des Plugins in IDs aufgelöst werden.
+
+Wenn ein Rohname in der Konfiguration verbleibt, löst der Start ihn nur auf, wenn `channels.zalouser.dangerouslyAllowNameMatching: true` aktiviert ist. Ohne diese ausdrückliche Aktivierung sind Senderprüfungen zur Laufzeit ausschließlich ID-basiert, und Rohnamen werden für die Autorisierung ignoriert.
Genehmigen über:
@@ -97,18 +99,18 @@ Genehmigen über:
## Gruppenzugriff (optional)
-- Standard: `channels.zalouser.groupPolicy = "open"` (Gruppen erlaubt). Verwenden Sie `channels.defaults.groupPolicy`, um den Standard zu überschreiben, wenn nichts festgelegt ist.
+- Standard: `channels.zalouser.groupPolicy = "open"` (Gruppen erlaubt). Verwenden Sie `channels.defaults.groupPolicy`, um den Standard zu überschreiben, wenn er nicht gesetzt ist.
- Auf eine Allowlist beschränken mit:
- `channels.zalouser.groupPolicy = "allowlist"`
- - `channels.zalouser.groups` (Schlüssel sollten stabile Gruppen-IDs sein; Namen werden beim Start nach Möglichkeit zu IDs aufgelöst)
- - `channels.zalouser.groupAllowFrom` (steuert, welche Absender in erlaubten Gruppen den Bot auslösen können)
+ - `channels.zalouser.groups` (Schlüssel sollten stabile Gruppen-IDs sein; Namen werden beim Start nur dann in IDs aufgelöst, wenn `channels.zalouser.dangerouslyAllowNameMatching: true` aktiviert ist)
+ - `channels.zalouser.groupAllowFrom` (steuert, welche Sender in erlaubten Gruppen den Bot auslösen können)
- Alle Gruppen blockieren: `channels.zalouser.groupPolicy = "disabled"`.
- Der Konfigurationsassistent kann nach Gruppen-Allowlists fragen.
-- Beim Start löst OpenClaw Gruppen-/Benutzernamen in Allowlists zu IDs auf und protokolliert die Zuordnung.
-- Gruppen-Allowlist-Abgleich erfolgt standardmäßig nur per ID. Nicht aufgelöste Namen werden für die Authentifizierung ignoriert, sofern nicht `channels.zalouser.dangerouslyAllowNameMatching: true` aktiviert ist.
-- `channels.zalouser.dangerouslyAllowNameMatching: true` ist ein Break-Glass-Kompatibilitätsmodus, der den Abgleich veränderlicher Gruppennamen wieder aktiviert.
-- Wenn `groupAllowFrom` nicht festgelegt ist, greift die Laufzeit für Absenderprüfungen in Gruppen auf `allowFrom` zurück.
-- Absenderprüfungen gelten sowohl für normale Gruppennachrichten als auch für Steuerbefehle (zum Beispiel `/new`, `/reset`).
+- Beim Start löst OpenClaw Gruppen-/Benutzernamen in Allowlists in IDs auf und protokolliert die Zuordnung nur, wenn `channels.zalouser.dangerouslyAllowNameMatching: true` aktiviert ist.
+- Der Abgleich der Gruppen-Allowlist ist standardmäßig ausschließlich ID-basiert. Nicht aufgelöste Namen werden für die Authentifizierung ignoriert, sofern `channels.zalouser.dangerouslyAllowNameMatching: true` nicht aktiviert ist.
+- `channels.zalouser.dangerouslyAllowNameMatching: true` ist ein Break-Glass-Kompatibilitätsmodus, der die veränderliche Namensauflösung beim Start und den Abgleich von Gruppennamen zur Laufzeit wieder aktiviert.
+- Wenn `groupAllowFrom` nicht gesetzt ist, fällt die Laufzeit für Gruppensenderprüfungen auf `allowFrom` zurück.
+- Senderprüfungen gelten sowohl für normale Gruppennachrichten als auch für Steuerbefehle (zum Beispiel `/new`, `/reset`).
Beispiel:
@@ -132,10 +134,10 @@ Beispiel:
- `channels.zalouser.groups..requireMention` steuert, ob Gruppenantworten eine Erwähnung erfordern.
- Auflösungsreihenfolge: exakte Gruppen-ID/exakter Gruppenname -> normalisierter Gruppen-Slug -> `*` -> Standard (`true`).
- Dies gilt sowohl für Gruppen auf der Allowlist als auch für den offenen Gruppenmodus.
-- Das Zitieren einer Bot-Nachricht zählt als implizite Erwähnung zur Gruppenaktivierung.
-- Autorisierte Steuerbefehle (zum Beispiel `/new`) können Mention-Gating umgehen.
-- Wenn eine Gruppennachricht übersprungen wird, weil eine Erwähnung erforderlich ist, speichert OpenClaw sie als ausstehende Gruppenhistorie und nimmt sie in die nächste verarbeitete Gruppennachricht auf.
-- Das Limit für die Gruppenhistorie ist standardmäßig `messages.groupChat.historyLimit` (Fallback `50`). Sie können es pro Konto mit `channels.zalouser.historyLimit` überschreiben.
+- Das Zitieren einer Bot-Nachricht zählt als implizite Erwähnung für die Gruppenaktivierung.
+- Autorisierte Steuerbefehle (zum Beispiel `/new`) können das Mention-Gating umgehen.
+- Wenn eine Gruppennachricht übersprungen wird, weil eine Erwähnung erforderlich ist, speichert OpenClaw sie als ausstehenden Gruppenverlauf und bezieht sie in die nächste verarbeitete Gruppennachricht ein.
+- Das Gruppenverlaufslimit ist standardmäßig `messages.groupChat.historyLimit` (Fallback `50`). Sie können es pro Konto mit `channels.zalouser.historyLimit` überschreiben.
Beispiel:
@@ -155,7 +157,7 @@ Beispiel:
## Mehrere Konten
-Konten werden in OpenClaw-State `zalouser`-Profilen zugeordnet. Beispiel:
+Konten werden in OpenClaw-State auf `zalouser`-Profile abgebildet. Beispiel:
```json5
{
@@ -173,11 +175,11 @@ Konten werden in OpenClaw-State `zalouser`-Profilen zugeordnet. Beispiel:
## Tippen, Reaktionen und Zustellbestätigungen
-- OpenClaw sendet vor dem Versand einer Antwort ein Tipp-Event (Best Effort).
+- OpenClaw sendet ein Tipp-Event, bevor eine Antwort versendet wird (Best Effort).
- Die Nachrichtenreaktionsaktion `react` wird für `zalouser` in Kanalaktionen unterstützt.
- Verwenden Sie `remove: true`, um ein bestimmtes Reaktions-Emoji aus einer Nachricht zu entfernen.
- Reaktionssemantik: [Reaktionen](/de/tools/reactions)
-- Für eingehende Nachrichten, die Event-Metadaten enthalten, sendet OpenClaw Zugestellt- und Gesehen-Bestätigungen (Best Effort).
+- Für eingehende Nachrichten, die Event-Metadaten enthalten, sendet OpenClaw Bestätigungen für zugestellt + gesehen (Best Effort).
## Fehlerbehebung
@@ -188,12 +190,12 @@ Konten werden in OpenClaw-State `zalouser`-Profilen zugeordnet. Beispiel:
**Allowlist-/Gruppenname wurde nicht aufgelöst:**
-- Verwenden Sie numerische IDs in `allowFrom`/`groupAllowFrom`/`groups` oder exakte Freundes-/Gruppennamen.
+- Verwenden Sie numerische IDs in `allowFrom`/`groupAllowFrom` und stabile Gruppen-IDs in `groups`. Wenn Sie absichtlich exakte Freunde-/Gruppennamen benötigen, aktivieren Sie `channels.zalouser.dangerouslyAllowNameMatching: true`.
**Upgrade von alter CLI-basierter Einrichtung:**
-- Entfernen Sie alle alten Annahmen über einen externen `zca`-Prozess.
-- Der Kanal läuft jetzt vollständig in OpenClaw ohne externe CLI-Binärdateien.
+- Entfernen Sie alle alten Annahmen zu externen `zca`-Prozessen.
+- Der Kanal läuft jetzt vollständig in OpenClaw ohne externe CLI-Binaries.
## Verwandt
diff --git a/docs/de/cli/daemon.md b/docs/de/cli/daemon.md
index a7d5aefe4..a7378a001 100644
--- a/docs/de/cli/daemon.md
+++ b/docs/de/cli/daemon.md
@@ -1,23 +1,23 @@
---
read_when:
- Sie verwenden `openclaw daemon ...` weiterhin in Skripten
- - Sie benötigen Befehle für den Dienstlebenszyklus (install/start/stop/restart/status)
+ - Sie benötigen Befehle für den Dienst-Lebenszyklus (install/start/stop/restart/status)
summary: CLI-Referenz für `openclaw daemon` (Legacy-Alias für die Gateway-Dienstverwaltung)
title: Daemon
x-i18n:
- generated_at: "2026-05-02T22:17:12Z"
+ generated_at: "2026-05-04T18:23:45Z"
model: gpt-5.5
provider: openai
- source_hash: 3f11b75bf2781e69f6f59b23364f06cf359f9f24407f25f19b9d2186f7158512
+ source_hash: f84e11fc50bdf38da518a8fcf415ae461a2688c2299f996eee384357c0d04a05
source_path: cli/daemon.md
workflow: 16
---
# `openclaw daemon`
-Veralteter Alias für Befehle zur Verwaltung des Gateway-Dienstes.
+Legacy-Alias für Befehle zur Verwaltung des Gateway-Dienstes.
-`openclaw daemon ...` wird derselben Dienststeuerungsoberfläche zugeordnet wie die Dienstbefehle von `openclaw gateway ...`.
+`openclaw daemon ...` wird derselben Oberfläche zur Dienststeuerung zugeordnet wie die Dienstbefehle von `openclaw gateway ...`.
## Verwendung
@@ -32,34 +32,35 @@ openclaw daemon uninstall
## Unterbefehle
-- `status`: Installationsstatus des Dienstes anzeigen und Gateway-Integrität prüfen
+- `status`: Dienstinstallationsstatus anzeigen und Gateway-Zustand prüfen
- `install`: Dienst installieren (`launchd`/`systemd`/`schtasks`)
- `uninstall`: Dienst entfernen
- `start`: Dienst starten
- `stop`: Dienst stoppen
- `restart`: Dienst neu starten
-## Allgemeine Optionen
+## Häufige Optionen
- `status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
- `install`: `--port`, `--runtime `, `--token`, `--force`, `--json`
-- `restart`: `--force`, `--wait `, `--json`
+- `restart`: `--safe`, `--force`, `--wait `, `--json`
- Lebenszyklus (`uninstall|start|stop`): `--json`
Hinweise:
-- `status` löst konfigurierte Authentifizierungs-SecretRefs für die Prüf-Authentifizierung auf, wenn möglich.
-- Wenn ein erforderlicher Authentifizierungs-SecretRef in diesem Befehlspfad nicht aufgelöst ist, meldet `daemon status --json` `rpc.authWarning`, wenn die Prüf-Konnektivität/-Authentifizierung fehlschlägt; übergeben Sie `--token`/`--password` explizit oder lösen Sie zuerst die Secret-Quelle auf.
-- Wenn die Prüfung erfolgreich ist, werden Warnungen zu nicht aufgelösten Authentifizierungsreferenzen unterdrückt, um falsch positive Meldungen zu vermeiden.
-- `status --deep` fügt einen Best-Effort-Scan des Dienstes auf Systemebene hinzu. Wenn andere gateway-ähnliche Dienste gefunden werden, gibt die menschenlesbare Ausgabe Hinweise zur Bereinigung aus und warnt, dass ein Gateway pro Maschine weiterhin die normale Empfehlung ist.
-- Bei Linux-systemd-Installationen umfassen `status`-Prüfungen auf Token-Abweichungen sowohl `Environment=`- als auch `EnvironmentFile=`-Unit-Quellen.
-- Abweichungsprüfungen lösen `gateway.auth.token`-SecretRefs über die zusammengeführte Laufzeitumgebung auf (zuerst die Umgebung des Dienstbefehls, dann die Prozessumgebung als Fallback).
-- Wenn Token-Authentifizierung nicht effektiv aktiv ist (expliziter `gateway.auth.mode` von `password`/`none`/`trusted-proxy` oder nicht gesetzter Modus, bei dem das Passwort gewinnen kann und kein Token-Kandidat gewinnen kann), überspringen Token-Abweichungsprüfungen die Auflösung des Konfigurationstokens.
-- Wenn Token-Authentifizierung ein Token erfordert und `gateway.auth.token` über SecretRef verwaltet wird, validiert `install`, dass der SecretRef auflösbar ist, speichert das aufgelöste Token aber nicht in den Metadaten der Dienstumgebung.
-- Wenn Token-Authentifizierung ein Token erfordert und der konfigurierte Token-SecretRef nicht aufgelöst ist, schlägt die Installation sicher fehl.
+- `status` löst konfigurierte Auth-SecretRefs für die Prüfungsauthentifizierung auf, wenn möglich.
+- Wenn ein erforderlicher Auth-SecretRef in diesem Befehlspfad nicht aufgelöst ist, meldet `daemon status --json` `rpc.authWarning`, wenn Prüfungsverbindung oder -authentifizierung fehlschlagen; übergeben Sie `--token`/`--password` explizit oder lösen Sie zuerst die Secret-Quelle auf.
+- Wenn die Prüfung erfolgreich ist, werden Warnungen zu nicht aufgelösten Auth-Refs unterdrückt, um Fehlalarme zu vermeiden.
+- `status --deep` fügt einen Best-Effort-Systemscan auf Dienstebene hinzu. Wenn dabei andere Gateway-ähnliche Dienste gefunden werden, gibt die menschenlesbare Ausgabe Bereinigungshinweise aus und warnt, dass ein Gateway pro Maschine weiterhin die normale Empfehlung ist.
+- Bei Linux-systemd-Installationen berücksichtigen `status`-Token-Drift-Prüfungen sowohl `Environment=`- als auch `EnvironmentFile=`-Unit-Quellen.
+- Drift-Prüfungen lösen `gateway.auth.token`-SecretRefs mit zusammengeführter Laufzeitumgebung auf (zuerst die Dienstbefehlsumgebung, dann als Fallback die Prozessumgebung).
+- Wenn Token-Authentifizierung nicht effektiv aktiv ist (expliziter `gateway.auth.mode` von `password`/`none`/`trusted-proxy` oder ein nicht gesetzter Modus, bei dem das Passwort gewinnen kann und kein Token-Kandidat gewinnen kann), überspringen Token-Drift-Prüfungen die Auflösung des Konfigurations-Tokens.
+- Wenn Token-Authentifizierung ein Token erfordert und `gateway.auth.token` durch SecretRef verwaltet wird, validiert `install`, dass der SecretRef auflösbar ist, speichert das aufgelöste Token aber nicht dauerhaft in den Dienstumgebungsmetadaten.
+- Wenn Token-Authentifizierung ein Token erfordert und der konfigurierte Token-SecretRef nicht aufgelöst ist, schlägt die Installation geschlossen fehl.
- Wenn sowohl `gateway.auth.token` als auch `gateway.auth.password` konfiguriert sind und `gateway.auth.mode` nicht gesetzt ist, wird die Installation blockiert, bis der Modus explizit gesetzt ist.
-- Unter macOS hält `install` LaunchAgent-plists nur für den Eigentümer zugänglich und lädt verwaltete Dienstumgebungswerte über eine nur für den Eigentümer zugängliche Datei und einen Wrapper, statt API-Schlüssel oder Authentifizierungsprofil-Umgebungsreferenzen in `EnvironmentVariables` zu serialisieren.
-- Wenn Sie absichtlich mehrere Gateways auf einem Host ausführen, isolieren Sie Ports, Konfiguration/Zustand und Arbeitsbereiche; siehe [/gateway#multiple-gateways-same-host](/de/gateway#multiple-gateways-same-host).
+- Unter macOS hält `install` LaunchAgent-plists nur für den Eigentümer zugänglich und lädt verwaltete Dienstumgebungswerte über eine nur für den Eigentümer zugängliche Datei und einen Wrapper, statt API-Schlüssel oder Auth-Profil-Env-Refs in `EnvironmentVariables` zu serialisieren.
+- Wenn Sie absichtlich mehrere Gateways auf einem Host betreiben, isolieren Sie Ports, Konfiguration/Zustand und Arbeitsbereiche; siehe [/gateway#multiple-gateways-same-host](/de/gateway#multiple-gateways-same-host).
+- `restart --safe` weist das laufende Gateway an, aktive Arbeit vorab zu prüfen und einen zusammengeführten Neustart einzuplanen, nachdem aktive Arbeit abgearbeitet ist. Ein einfaches `restart` behält das bestehende Verhalten des Dienstmanagers bei; `--force` bleibt der Pfad für eine sofortige Überschreibung.
## Bevorzugt
diff --git a/docs/de/cli/gateway.md b/docs/de/cli/gateway.md
index 5f4535ede..026293a4e 100644
--- a/docs/de/cli/gateway.md
+++ b/docs/de/cli/gateway.md
@@ -1,28 +1,28 @@
---
read_when:
- Gateway über die CLI ausführen (Entwicklung oder Server)
- - Debugging von Gateway-Authentifizierung, Bind-Modi und Konnektivität
- - Gateways über Bonjour erkennen (lokales + Wide-Area-DNS-SD)
+ - Debuggen der Gateway-Authentifizierung, Bind-Modi und Konnektivität
+ - Gateways über Bonjour erkennen (lokales + Weitbereichs-DNS-SD)
sidebarTitle: Gateway
-summary: OpenClaw Gateway CLI (`openclaw gateway`) — Gateways ausführen, abfragen und ermitteln
+summary: OpenClaw Gateway CLI (`openclaw gateway`) — Gateways starten, abfragen und entdecken
title: Gateway
x-i18n:
- generated_at: "2026-05-02T22:17:27Z"
+ generated_at: "2026-05-04T18:23:39Z"
model: gpt-5.5
provider: openai
- source_hash: f7f948a8f0ee6e065afa02f354e690ad5cc4f71bdb8b8674f1b0396c439ab242
+ source_hash: 310867c59148577f2e8ce6f708da6bce936e09243ce7fbe5daeb453c6b3b370d
source_path: cli/gateway.md
workflow: 16
---
-Das Gateway ist der WebSocket-Server von OpenClaw (Kanäle, Nodes, Sitzungen, Hooks). Die Unterbefehle auf dieser Seite gehören zu `openclaw gateway …`.
+The Gateway ist OpenClaws WebSocket-Server (Kanäle, Nodes, Sitzungen, Hooks). Die Unterbefehle auf dieser Seite befinden sich unter `openclaw gateway …`.
- Lokale Einrichtung für mDNS + Wide-Area-DNS-SD.
+ Lokales mDNS + Wide-Area-DNS-SD-Einrichtung.
-
- Wie OpenClaw Gateways bekannt macht und findet.
+
+ Wie OpenClaw Gateways ankündigt und findet.
Gateway-Konfigurationsschlüssel auf oberster Ebene.
@@ -37,7 +37,7 @@ Führen Sie einen lokalen Gateway-Prozess aus:
openclaw gateway
```
-Vordergrund-Alias:
+Alias für den Vordergrund:
```bash
openclaw gateway run
@@ -45,12 +45,12 @@ openclaw gateway run
- - Standardmäßig verweigert das Gateway den Start, sofern `gateway.mode=local` nicht in `~/.openclaw/openclaw.json` gesetzt ist. Verwenden Sie `--allow-unconfigured` für Ad-hoc-/Entwicklungsläufe.
- - `openclaw onboard --mode local` und `openclaw setup` sollen `gateway.mode=local` schreiben. Wenn die Datei existiert, aber `gateway.mode` fehlt, behandeln Sie dies als beschädigte oder überschriebene Konfiguration und reparieren Sie sie, statt implizit lokalen Modus anzunehmen.
- - Wenn die Datei existiert und `gateway.mode` fehlt, behandelt das Gateway dies als verdächtigen Konfigurationsschaden und weigert sich, für Sie „lokal zu raten“.
- - Das Binden über Loopback hinaus ohne Authentifizierung ist blockiert (Sicherheitsleitplanke).
- - `SIGUSR1` löst einen In-Process-Neustart aus, wenn er autorisiert ist (`commands.restart` ist standardmäßig aktiviert; setzen Sie `commands.restart: false`, um manuellen Neustart zu blockieren, während Anwenden/Aktualisieren von Gateway-Tool/-Konfiguration weiterhin erlaubt bleibt).
- - `SIGINT`/`SIGTERM`-Handler stoppen den Gateway-Prozess, stellen aber keinen benutzerdefinierten Terminalzustand wieder her. Wenn Sie die CLI mit einer TUI oder Raw-Mode-Eingabe umschließen, stellen Sie das Terminal vor dem Beenden wieder her.
+ - Standardmäßig verweigert der Gateway den Start, sofern `gateway.mode=local` nicht in `~/.openclaw/openclaw.json` gesetzt ist. Verwenden Sie `--allow-unconfigured` für Ad-hoc-/Entwicklungsstarts.
+ - Von `openclaw onboard --mode local` und `openclaw setup` wird erwartet, dass sie `gateway.mode=local` schreiben. Wenn die Datei vorhanden ist, aber `gateway.mode` fehlt, behandeln Sie dies als fehlerhafte oder überschriebene Konfiguration und reparieren Sie sie, statt den lokalen Modus implizit anzunehmen.
+ - Wenn die Datei vorhanden ist und `gateway.mode` fehlt, behandelt der Gateway dies als verdächtigen Konfigurationsschaden und verweigert es, für Sie „lokal zu raten“.
+ - Das Binden über loopback hinaus ohne Authentifizierung wird blockiert (Sicherheitsleitplanke).
+ - `SIGUSR1` löst einen prozessinternen Neustart aus, wenn dies autorisiert ist (`commands.restart` ist standardmäßig aktiviert; setzen Sie `commands.restart: false`, um einen manuellen Neustart zu blockieren, während Anwenden/Aktualisieren von Gateway-Tool/-Konfiguration weiterhin erlaubt bleibt).
+ - `SIGINT`-/`SIGTERM`-Handler stoppen den Gateway-Prozess, stellen aber keinen benutzerdefinierten Terminalzustand wieder her. Wenn Sie die CLI mit einer TUI oder Raw-Mode-Eingabe umschließen, stellen Sie das Terminal vor dem Beenden wieder her.
@@ -58,37 +58,37 @@ openclaw gateway run
### Optionen
- WebSocket-Port (Standard kommt aus Konfiguration/Umgebung; üblicherweise `18789`).
+ WebSocket-Port (Standardwert stammt aus Konfiguration/Env; normalerweise `18789`).
Bind-Modus des Listeners.
- Authentifizierungsmodus überschreiben.
+ Überschreibung des Authentifizierungsmodus.
- Token überschreiben (setzt auch `OPENCLAW_GATEWAY_TOKEN` für den Prozess).
+ Token-Überschreibung (setzt auch `OPENCLAW_GATEWAY_TOKEN` für den Prozess).
- Passwort überschreiben.
+ Passwortüberschreibung.
Gateway-Passwort aus einer Datei lesen.
- Gateway über Tailscale bereitstellen.
+ Gateway über Tailscale verfügbar machen.
- Tailscale-serve/funnel-Konfiguration beim Herunterfahren zurücksetzen.
+ Tailscale-Serve-/Funnel-Konfiguration beim Herunterfahren zurücksetzen.
- Gateway-Start ohne `gateway.mode=local` in der Konfiguration erlauben. Umgeht die Startschutzprüfung nur für Ad-hoc-/Entwicklungs-Bootstrap; schreibt oder repariert die Konfigurationsdatei nicht.
+ Gateway-Start ohne `gateway.mode=local` in der Konfiguration erlauben. Umgeht die Startschutzprüfung nur für Ad-hoc-/Entwicklungs-Bootstrapping; schreibt oder repariert die Konfigurationsdatei nicht.
- Entwicklungskonfiguration + Arbeitsbereich erstellen, falls sie fehlen (überspringt BOOTSTRAP.md).
+ Entwicklungskonfiguration + Workspace erstellen, falls sie fehlen (überspringt BOOTSTRAP.md).
- Entwicklungskonfiguration + Zugangsdaten + Sitzungen + Arbeitsbereich zurücksetzen (erfordert `--dev`).
+ Entwicklungskonfiguration + Anmeldedaten + Sitzungen + Workspace zurücksetzen (erfordert `--dev`).
Vor dem Start jeden vorhandenen Listener auf dem ausgewählten Port beenden.
@@ -106,30 +106,40 @@ openclaw gateway run
Alias für `--ws-log compact`.
- Rohereignisse des Modell-Streams in JSONL protokollieren.
+ Rohdaten von Modell-Stream-Ereignissen in jsonl protokollieren.
- JSONL-Pfad für Roh-Streams.
+ jsonl-Pfad für Rohdatenstreams.
+## Gateway neu starten
+
+```bash
+openclaw gateway restart
+openclaw gateway restart --safe
+openclaw gateway restart --force
+```
+
+`openclaw gateway restart --safe` fordert den laufenden Gateway auf, aktive OpenClaw-Arbeit vor dem Neustart vorab zu prüfen. Wenn Warteschlangenoperationen, Antwortzustellung, eingebettete Läufe oder Task-Läufe aktiv sind, meldet der Gateway die Blocker, fasst doppelte sichere Neustartanforderungen zusammen und startet neu, sobald die aktive Arbeit abgearbeitet ist. Einfaches `restart` behält das bestehende Service-Manager-Verhalten aus Kompatibilitätsgründen bei. Verwenden Sie `--force` nur, wenn Sie ausdrücklich den sofortigen Override-Pfad wünschen.
+
-Inline angegebenes `--password` kann in lokalen Prozessauflistungen offengelegt werden. Verwenden Sie bevorzugt `--password-file`, Umgebungsvariablen oder ein durch SecretRef gestütztes `gateway.auth.password`.
+Inline-`--password` kann in lokalen Prozesslisten sichtbar werden. Bevorzugen Sie `--password-file`, Env oder ein SecretRef-gestütztes `gateway.auth.password`.
-### Startprofiling
+### Start-Profiling
-- Setzen Sie `OPENCLAW_GATEWAY_STARTUP_TRACE=1`, um Phasenzeiten während des Gateway-Starts zu protokollieren, einschließlich `eventLoopMax`-Verzögerung je Phase und Plugin-Lookup-Table-Zeiten für installierten Index, Manifest-Registry, Startplanung und Owner-Map-Arbeit.
-- Setzen Sie `OPENCLAW_DIAGNOSTICS=timeline` mit `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=`, um nach bestem Aufwand eine JSONL-Zeitachse der Startdiagnose für externe QA-Harnesses zu schreiben. Sie können das Flag auch mit `diagnostics.flags: ["timeline"]` in der Konfiguration aktivieren; der Pfad wird weiterhin über die Umgebung bereitgestellt. Fügen Sie `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` hinzu, um Event-Loop-Stichproben einzubeziehen.
-- Führen Sie `pnpm test:startup:gateway -- --runs 5 --warmup 1` aus, um den Gateway-Start zu benchmarken. Der Benchmark zeichnet die erste Prozessausgabe, `/healthz`, `/readyz`, Starttrace-Zeiten, Event-Loop-Verzögerung und Zeitdetails der Plugin-Lookup-Table auf.
+- Setzen Sie `OPENCLAW_GATEWAY_STARTUP_TRACE=1`, um Phasenzeiten während des Gateway-Starts zu protokollieren, einschließlich `eventLoopMax`-Verzögerung pro Phase sowie Plugin-Lookup-Table-Zeiten für installed-index, Manifest-Registry, Startplanung und owner-map-Arbeit.
+- Setzen Sie `OPENCLAW_DIAGNOSTICS=timeline` mit `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=`, um eine Best-Effort-JSONL-Startdiagnose-Timeline für externe QA-Harnesses zu schreiben. Sie können das Flag auch mit `diagnostics.flags: ["timeline"]` in der Konfiguration aktivieren; der Pfad wird weiterhin über Env bereitgestellt. Fügen Sie `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` hinzu, um Event-Loop-Samples einzubeziehen.
+- Führen Sie `pnpm test:startup:gateway -- --runs 5 --warmup 1` aus, um den Gateway-Start zu benchmarken. Der Benchmark erfasst die erste Prozessausgabe, `/healthz`, `/readyz`, Start-Trace-Zeiten, Event-Loop-Verzögerung und Zeitdetails der Plugin-Lookup-Table.
-## Laufendes Gateway abfragen
+## Laufenden Gateway abfragen
-Alle Abfragebefehle verwenden WebSocket-RPC.
+Alle Abfragebefehle verwenden WebSocket RPC.
- Standard: menschenlesbar (farbig in TTY).
- - `--json`: maschinenlesbares JSON (ohne Styling/Spinner).
+ - `--json`: maschinenlesbares JSON (kein Styling/Spinner).
- `--no-color` (oder `NO_COLOR=1`): ANSI deaktivieren, während das menschenlesbare Layout beibehalten wird.
@@ -137,14 +147,14 @@ Alle Abfragebefehle verwenden WebSocket-RPC.
- `--url `: Gateway-WebSocket-URL.
- `--token `: Gateway-Token.
- `--password `: Gateway-Passwort.
- - `--timeout `: Timeout/Budget (variiert je Befehl).
+ - `--timeout `: Timeout/Budget (variiert je nach Befehl).
- `--expect-final`: auf eine „final“-Antwort warten (Agent-Aufrufe).
-Wenn Sie `--url` setzen, fällt die CLI nicht auf Konfigurations- oder Umgebungs-Zugangsdaten zurück. Übergeben Sie `--token` oder `--password` explizit. Fehlende explizite Zugangsdaten sind ein Fehler.
+Wenn Sie `--url` setzen, fällt die CLI nicht auf Konfigurations- oder Umgebungs-Anmeldedaten zurück. Übergeben Sie `--token` oder `--password` explizit. Fehlende explizite Anmeldedaten sind ein Fehler.
### `gateway health`
@@ -153,11 +163,11 @@ Wenn Sie `--url` setzen, fällt die CLI nicht auf Konfigurations- oder Umgebungs
openclaw gateway health --url ws://127.0.0.1:18789
```
-Der HTTP-Endpunkt `/healthz` ist eine Liveness-Probe: Er antwortet, sobald der Server HTTP beantworten kann. Der HTTP-Endpunkt `/readyz` ist strenger und bleibt rot, solange Plugin-Sidecars beim Start, Kanäle oder konfigurierte Hooks sich noch stabilisieren. Lokale oder authentifizierte detaillierte Readiness-Antworten enthalten einen `eventLoop`-Diagnoseblock mit Event-Loop-Verzögerung, Event-Loop-Auslastung, CPU-Kernverhältnis und einem `degraded`-Flag.
+Der HTTP-Endpunkt `/healthz` ist eine Liveness-Probe: Er antwortet, sobald der Server HTTP beantworten kann. Der HTTP-Endpunkt `/readyz` ist strenger und bleibt rot, während Start-Plugin-Sidecars, Kanäle oder konfigurierte Hooks noch initialisiert werden. Lokale oder authentifizierte detaillierte Readiness-Antworten enthalten einen `eventLoop`-Diagnoseblock mit Event-Loop-Verzögerung, Event-Loop-Auslastung, CPU-Kern-Verhältnis und einem `degraded`-Flag.
### `gateway usage-cost`
-Nutzungskostenübersichten aus Sitzungslogs abrufen.
+Nutzungs- und Kostenzusammenfassungen aus Sitzungslogs abrufen.
```bash
openclaw gateway usage-cost
@@ -171,7 +181,7 @@ openclaw gateway usage-cost --json
### `gateway stability`
-Den aktuellen Diagnose-Stabilitätsrekorder von einem laufenden Gateway abrufen.
+Aktuellen Diagnose-Stabilitätsrecorder von einem laufenden Gateway abrufen.
```bash
openclaw gateway stability
@@ -182,19 +192,19 @@ openclaw gateway stability --json
```
- Maximale Anzahl aktueller Ereignisse, die aufgenommen werden (max. `1000`).
+ Maximale Anzahl der einzubeziehenden aktuellen Ereignisse (max. `1000`).
- Nach Diagnoseereignistyp filtern, etwa `payload.large` oder `diagnostic.memory.pressure`.
+ Nach Diagnoseereignistyp filtern, zum Beispiel `payload.large` oder `diagnostic.memory.pressure`.
- Nur Ereignisse nach einer Diagnose-Sequenznummer einbeziehen.
+ Nur Ereignisse nach einer Diagnosesequenznummer einbeziehen.
- Ein persistiertes Stabilitäts-Bundle lesen, statt das laufende Gateway aufzurufen. Verwenden Sie `--bundle latest` (oder einfach `--bundle`) für das neueste Bundle im Zustandsverzeichnis, oder übergeben Sie direkt einen Bundle-JSON-Pfad.
+ Ein persistiertes Stabilitäts-Bundle lesen, statt den laufenden Gateway aufzurufen. Verwenden Sie `--bundle latest` (oder nur `--bundle`) für das neueste Bundle unter dem Zustandsverzeichnis, oder übergeben Sie direkt einen Bundle-JSON-Pfad.
- Eine teilbare Support-Diagnose-ZIP schreiben, statt Stabilitätsdetails auszugeben.
+ Eine teilbare ZIP-Datei mit Support-Diagnosen schreiben, statt Stabilitätsdetails auszugeben.
Ausgabepfad für `--export`.
@@ -202,15 +212,15 @@ openclaw gateway stability --json
- - Datensätze bewahren operative Metadaten auf: Ereignisnamen, Zählwerte, Byte-Größen, Speichermesswerte, Warteschlangen-/Sitzungsstatus, Kanal-/Plugin-Namen und redigierte Sitzungszusammenfassungen. Sie bewahren keinen Chattext, keine Webhook-Nachrichtenkörper, keine Tool-Ausgaben, keine Rohinhalte von Anfragen oder Antworten, keine Token, Cookies, geheimen Werte, Hostnamen oder rohen Sitzungs-IDs auf. Setzen Sie `diagnostics.enabled: false`, um den Rekorder vollständig zu deaktivieren.
- - Bei fatalen Gateway-Beendigungen, Shutdown-Timeouts und Startfehlern nach einem Neustart schreibt OpenClaw denselben Diagnose-Snapshot nach `~/.openclaw/logs/stability/openclaw-stability-*.json`, wenn der Rekorder Ereignisse enthält. Prüfen Sie das neueste Bundle mit `openclaw gateway stability --bundle latest`; `--limit`, `--type` und `--since-seq` gelten auch für die Bundle-Ausgabe.
+ - Datensätze behalten Betriebsmetadaten: Ereignisnamen, Zählwerte, Bytegrößen, Speichermesswerte, Warteschlangen-/Sitzungszustand, Kanal-/Plugin-Namen und redigierte Sitzungszusammenfassungen. Sie behalten keine Chat-Texte, Webhook-Bodys, Tool-Ausgaben, Rohdaten von Anfrage- oder Antwortbodys, Tokens, Cookies, geheime Werte, Hostnamen oder rohen Sitzungs-IDs. Setzen Sie `diagnostics.enabled: false`, um den Recorder vollständig zu deaktivieren.
+ - Bei fatalen Gateway-Beendigungen, Shutdown-Timeouts und Startfehlern nach Neustarts schreibt OpenClaw denselben Diagnose-Snapshot nach `~/.openclaw/logs/stability/openclaw-stability-*.json`, wenn der Recorder Ereignisse enthält. Prüfen Sie das neueste Bundle mit `openclaw gateway stability --bundle latest`; `--limit`, `--type` und `--since-seq` gelten auch für Bundle-Ausgaben.
### `gateway diagnostics export`
-Eine lokale Diagnose-ZIP schreiben, die zum Anhängen an Fehlerberichte vorgesehen ist. Zum Datenschutzmodell und den Bundle-Inhalten siehe [Diagnoseexport](/de/gateway/diagnostics).
+Schreibt eine lokale Diagnose-ZIP-Datei, die zum Anhängen an Fehlerberichte gedacht ist. Informationen zum Datenschutzmodell und zu Bundle-Inhalten finden Sie unter [Diagnoseexport](/de/gateway/diagnostics).
```bash
openclaw gateway diagnostics export
@@ -219,13 +229,13 @@ openclaw gateway diagnostics export --json
```
- ZIP-Ausgabepfad. Standard ist ein Support-Export im Zustandsverzeichnis.
+ Ausgabe-ZIP-Pfad. Standardmäßig ein Support-Export unter dem Zustandsverzeichnis.
- Maximale Anzahl bereinigter Logzeilen, die aufgenommen werden.
+ Maximale Anzahl bereinigter Logzeilen, die einbezogen werden.
- Maximale Anzahl zu prüfender Log-Bytes.
+ Maximale Anzahl an Logbytes, die geprüft werden.
Gateway-WebSocket-URL für den Health-Snapshot.
@@ -246,13 +256,13 @@ openclaw gateway diagnostics export --json
Geschriebenen Pfad, Größe und Manifest als JSON ausgeben.
-Der Export enthält ein Manifest, eine Markdown-Zusammenfassung, Konfigurationsstruktur, bereinigte Konfigurationsdetails, bereinigte Logzusammenfassungen, bereinigte Gateway-Status-/Health-Snapshots und das neueste Stabilitäts-Bundle, wenn eines vorhanden ist.
+Der Export enthält ein Manifest, eine Markdown-Zusammenfassung, Konfigurationsstruktur, bereinigte Konfigurationsdetails, bereinigte Logzusammenfassungen, bereinigte Gateway-Status-/Health-Snapshots und das neueste Stabilitäts-Bundle, falls eines vorhanden ist.
-Er ist zum Teilen gedacht. Er bewahrt operative Details auf, die beim Debugging helfen, etwa unbedenkliche OpenClaw-Logfelder, Subsystemnamen, Statuscodes, Dauerwerte, konfigurierte Modi, Ports, Plugin-IDs, Provider-IDs, nicht geheime Feature-Einstellungen und redigierte operative Logmeldungen. Er lässt Chattext, Webhook-Nachrichtenkörper, Tool-Ausgaben, Zugangsdaten, Cookies, Konto-/Nachrichtenkennungen, Prompt-/Instruktionstext, Hostnamen und geheime Werte aus oder redigiert sie. Wenn eine Nachricht im LogTape-Stil wie Benutzer-/Chat-/Tool-Payload-Text aussieht, bewahrt der Export nur auf, dass eine Nachricht ausgelassen wurde, plus ihre Byte-Anzahl.
+Er ist zum Teilen gedacht. Er behält Betriebsdetails, die beim Debugging helfen, etwa sichere OpenClaw-Logfelder, Subsystemnamen, Statuscodes, Dauern, konfigurierte Modi, Ports, Plugin-IDs, Provider-IDs, nicht geheime Feature-Einstellungen und redigierte operative Logmeldungen. Er lässt Chat-Texte, Webhook-Bodys, Tool-Ausgaben, Anmeldedaten, Cookies, Konto-/Nachrichtenkennungen, Prompt-/Anweisungstext, Hostnamen und geheime Werte aus oder redigiert sie. Wenn eine LogTape-artige Meldung wie Benutzer-/Chat-/Tool-Payload-Text aussieht, behält der Export nur bei, dass eine Meldung ausgelassen wurde, plus deren Byteanzahl.
### `gateway status`
-`gateway status` zeigt den Gateway-Dienst (launchd/systemd/schtasks) sowie optional eine Prüfung der Verbindungs-/Authentifizierungsfähigkeit.
+`gateway status` zeigt den Gateway-Dienst (launchd/systemd/schtasks) plus eine optionale Prüfung der Konnektivitäts-/Authentifizierungsfähigkeit.
```bash
openclaw gateway status
@@ -261,54 +271,54 @@ openclaw gateway status --require-rpc
```
- Ein explizites Prüfziel hinzufügen. Konfiguriertes Remote-Ziel + localhost werden weiterhin geprüft.
+ Fügen Sie ein explizites Prüfziel hinzu. Die konfigurierte Gegenstelle und localhost werden weiterhin geprüft.
Token-Authentifizierung für die Prüfung.
- Passwort-Authentifizierung für die Prüfung.
+ Passwortauthentifizierung für die Prüfung.
- Prüf-Timeout.
+ Zeitlimit für die Prüfung.
- Verbindungsprüfung überspringen (Nur-Dienst-Ansicht).
+ Überspringen Sie die Konnektivitätsprüfung (nur Service-Ansicht).
Auch Dienste auf Systemebene scannen.
- Die standardmäßige Verbindungsprüfung zu einer Leseprüfung erweitern und mit einem Nicht-Null-Exitcode beenden, wenn diese Leseprüfung fehlschlägt. Kann nicht mit `--no-probe` kombiniert werden.
+ Stufen Sie die Standard-Konnektivitätsprüfung auf eine Leseprüfung hoch und beenden Sie mit einem Nicht-Null-Code, wenn diese Leseprüfung fehlschlägt. Kann nicht mit `--no-probe` kombiniert werden.
- `gateway status` bleibt für Diagnosen verfügbar, selbst wenn die lokale CLI-Konfiguration fehlt oder ungültig ist.
- - Das standardmäßige `gateway status` weist den Servicestatus, die WebSocket-Verbindung und die beim Handshake sichtbare Authentifizierungsfähigkeit nach. Es weist keine Lese-/Schreib-/Admin-Operationen nach.
- - Diagnose-Probes verändern bei der erstmaligen Geräteauthentifizierung nichts: Sie verwenden ein vorhandenes zwischengespeichertes Geräte-Token erneut, falls eines existiert, erstellen aber keine neue CLI-Geräteidentität oder einen schreibgeschützten Geräte-Pairing-Eintrag nur zur Statusprüfung.
- - `gateway status` löst konfigurierte Auth-SecretRefs für Probe-Authentifizierung auf, wenn möglich.
- - Wenn ein erforderlicher Auth-SecretRef in diesem Befehlspfad nicht aufgelöst wird, meldet `gateway status --json` `rpc.authWarning`, wenn Probe-Konnektivität/-Authentifizierung fehlschlägt; übergeben Sie `--token`/`--password` explizit oder lösen Sie zuerst die Secret-Quelle auf.
- - Wenn die Probe erfolgreich ist, werden Warnungen zu nicht aufgelösten Auth-Refs unterdrückt, um Fehlalarme zu vermeiden.
- - Verwenden Sie `--require-rpc` in Skripten und Automatisierung, wenn ein lauschender Service nicht ausreicht und auch RPC-Aufrufe mit Lese-Scope fehlerfrei sein müssen.
- - `--deep` fügt einen Best-Effort-Scan nach zusätzlichen launchd/systemd/schtasks-Installationen hinzu. Wenn mehrere gateway-ähnliche Services erkannt werden, gibt die menschenlesbare Ausgabe Hinweise zur Bereinigung aus und warnt, dass die meisten Setups einen Gateway pro Maschine ausführen sollten.
- - Die menschenlesbare Ausgabe enthält den aufgelösten Pfad der Datei-Logs sowie eine Momentaufnahme der CLI-gegen-Service-Konfigurationspfade/-Gültigkeit, um Profil- oder Statusverzeichnis-Abweichungen zu diagnostizieren.
+ - Das standardmäßige `gateway status` weist Service-Zustand, WebSocket-Verbindung und die zum Handshake-Zeitpunkt sichtbare Authentifizierungsfähigkeit nach. Es weist keine Lese-/Schreib-/Admin-Vorgänge nach.
+ - Diagnoseprüfungen verändern bei erstmaliger Geräteauthentifizierung nichts: Sie verwenden ein vorhandenes zwischengespeichertes Geräte-Token erneut, wenn eines existiert, erstellen aber keine neue CLI-Geräteidentität oder schreibgeschützte Geräte-Pairing-Aufzeichnung nur zur Statusprüfung.
+ - `gateway status` löst konfigurierte Authentifizierungs-SecretRefs für die Prüf-Authentifizierung nach Möglichkeit auf.
+ - Wenn ein erforderlicher Authentifizierungs-SecretRef in diesem Befehlszweig nicht aufgelöst wird, meldet `gateway status --json` `rpc.authWarning`, wenn Prüfkonnektivität/Authentifizierung fehlschlägt; übergeben Sie `--token`/`--password` explizit oder lösen Sie zuerst die Secret-Quelle auf.
+ - Wenn die Prüfung erfolgreich ist, werden Warnungen zu nicht aufgelösten Authentifizierungsreferenzen unterdrückt, um Fehlalarme zu vermeiden.
+ - Verwenden Sie `--require-rpc` in Skripten und Automatisierung, wenn ein lauschender Dienst nicht ausreicht und auch RPC-Aufrufe mit Leseumfang funktionieren müssen.
+ - `--deep` fügt einen Best-Effort-Scan nach zusätzlichen launchd/systemd/schtasks-Installationen hinzu. Wenn mehrere gateway-ähnliche Dienste erkannt werden, gibt die menschenlesbare Ausgabe Bereinigungshinweise aus und warnt, dass die meisten Setups ein Gateway pro Maschine ausführen sollten.
+ - Die menschenlesbare Ausgabe enthält den aufgelösten Datei-Logpfad sowie eine Momentaufnahme der CLI-vs-Service-Konfigurationspfade/-Gültigkeit, um Profil- oder Statusverzeichnis-Abweichungen zu diagnostizieren.
- Bei Linux-systemd-Installationen lesen Service-Auth-Drift-Prüfungen sowohl `Environment=`- als auch `EnvironmentFile=`-Werte aus der Unit (einschließlich `%h`, zitierter Pfade, mehrerer Dateien und optionaler `-`-Dateien).
- - Drift-Prüfungen lösen `gateway.auth.token`-SecretRefs mithilfe der zusammengeführten Laufzeit-Umgebung auf (zuerst Service-Befehlsumgebung, dann Prozessumgebung als Fallback).
- - Wenn Token-Authentifizierung nicht effektiv aktiv ist (expliziter `gateway.auth.mode` von `password`/`none`/`trusted-proxy` oder nicht gesetzter Modus, bei dem Passwort gewinnen kann und kein Token-Kandidat gewinnen kann), überspringen Token-Drift-Prüfungen die Auflösung des Konfigurationstokens.
+ - Drift-Prüfungen lösen `gateway.auth.token`-SecretRefs mithilfe der zusammengeführten Laufzeitumgebung auf (zuerst Service-Befehlsumgebung, dann Prozessumgebung als Fallback).
+ - Wenn Token-Authentifizierung nicht effektiv aktiv ist (expliziter `gateway.auth.mode` von `password`/`none`/`trusted-proxy` oder nicht gesetzter Modus, bei dem Passwort gewinnen kann und kein Token-Kandidat gewinnen kann), überspringen Token-Drift-Prüfungen die Auflösung des Konfigurations-Tokens.
### `gateway probe`
-`gateway probe` ist der Befehl zum „Alles debuggen“. Er probt immer:
+`gateway probe` ist der Befehl zum „Alles debuggen“. Er prüft immer:
-- Ihren konfigurierten Remote-Gateway (falls gesetzt), und
-- localhost (loopback) **auch wenn Remote konfiguriert ist**.
+- Ihr konfiguriertes Remote-Gateway (falls gesetzt), und
+- localhost (loopback) **auch wenn remote konfiguriert ist**.
Wenn Sie `--url` übergeben, wird dieses explizite Ziel vor beiden hinzugefügt. Die menschenlesbare Ausgabe beschriftet die Ziele als:
@@ -317,7 +327,7 @@ Wenn Sie `--url` übergeben, wird dieses explizite Ziel vor beiden hinzugefügt.
- `Local loopback`
-Wenn mehrere Gateways erreichbar sind, gibt der Befehl alle aus. Mehrere Gateways werden unterstützt, wenn Sie isolierte Profile/Ports verwenden (z. B. einen Rettungs-Bot), aber die meisten Installationen führen weiterhin einen einzelnen Gateway aus.
+Wenn mehrere Gateways erreichbar sind, werden alle ausgegeben. Mehrere Gateways werden unterstützt, wenn Sie isolierte Profile/Ports verwenden (z. B. einen Rescue-Bot), aber die meisten Installationen führen weiterhin ein einzelnes Gateway aus.
```bash
@@ -328,50 +338,50 @@ openclaw gateway probe --json
- `Reachable: yes` bedeutet, dass mindestens ein Ziel eine WebSocket-Verbindung akzeptiert hat.
- - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` meldet, was die Probe über die Authentifizierung nachweisen konnte. Das ist von der Erreichbarkeit getrennt.
- - `Read probe: ok` bedeutet, dass Detail-RPC-Aufrufe mit Lese-Scope (`health`/`status`/`system-presence`/`config.get`) ebenfalls erfolgreich waren.
- - `Read probe: limited - missing scope: operator.read` bedeutet, dass die Verbindung erfolgreich war, RPC mit Lese-Scope aber eingeschränkt ist. Dies wird als **beeinträchtigte** Erreichbarkeit gemeldet, nicht als vollständiger Fehler.
- - `Read probe: failed` nach `Connect: ok` bedeutet, dass der Gateway die WebSocket-Verbindung akzeptiert hat, die nachfolgenden Lesediagnosen aber eine Zeitüberschreitung hatten oder fehlgeschlagen sind. Auch dies ist **beeinträchtigte** Erreichbarkeit, kein unerreichbarer Gateway.
- - Wie `gateway status` verwendet die Probe vorhandene zwischengespeicherte Geräteauthentifizierung erneut, erstellt aber keine erstmalige Geräteidentität oder Pairing-Zustand.
+ - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` meldet, was die Prüfung über die Authentifizierung nachweisen konnte. Das ist von der Erreichbarkeit getrennt.
+ - `Read probe: ok` bedeutet, dass Detail-RPC-Aufrufe mit Leseumfang (`health`/`status`/`system-presence`/`config.get`) ebenfalls erfolgreich waren.
+ - `Read probe: limited - missing scope: operator.read` bedeutet, dass die Verbindung erfolgreich war, der RPC mit Leseumfang aber eingeschränkt ist. Dies wird als **eingeschränkte** Erreichbarkeit gemeldet, nicht als vollständiger Fehler.
+ - `Read probe: failed` nach `Connect: ok` bedeutet, dass das Gateway die WebSocket-Verbindung akzeptiert hat, nachfolgende Lesediagnosen aber abgelaufen oder fehlgeschlagen sind. Auch dies ist **eingeschränkte** Erreichbarkeit, kein unerreichbares Gateway.
+ - Wie `gateway status` verwendet die Prüfung vorhandene zwischengespeicherte Geräteauthentifizierung erneut, erstellt aber keine erstmalige Geräteidentität oder keinen Pairing-Zustand.
- Der Exit-Code ist nur dann ungleich null, wenn kein geprüftes Ziel erreichbar ist.
Oberste Ebene:
- - `ok`: mindestens ein Ziel ist erreichbar.
- - `degraded`: mindestens ein Ziel hat eine Verbindung akzeptiert, aber die vollständige Detail-RPC-Diagnose nicht abgeschlossen.
- - `capability`: beste über erreichbare Ziele beobachtete Fähigkeit (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` oder `unknown`).
- - `primaryTargetId`: bestes Ziel, das in dieser Reihenfolge als aktiver Gewinner behandelt werden soll: explizite URL, SSH-Tunnel, konfigurierter Remote, dann local loopback.
- - `warnings[]`: Best-Effort-Warnungsdatensätze mit `code`, `message` und optionalen `targetIds`.
- - `network`: local loopback-/Tailnet-URL-Hinweise, abgeleitet aus der aktuellen Konfiguration und Host-Netzwerkumgebung.
- - `discovery.timeoutMs` und `discovery.count`: das tatsächlich verwendete Discovery-Budget bzw. die Ergebnisanzahl für diesen Probe-Durchlauf.
+ - `ok`: Mindestens ein Ziel ist erreichbar.
+ - `degraded`: Mindestens ein Ziel hat eine Verbindung akzeptiert, aber die vollständige Detail-RPC-Diagnose nicht abgeschlossen.
+ - `capability`: beste Fähigkeit, die über erreichbare Ziele hinweg gesehen wurde (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` oder `unknown`).
+ - `primaryTargetId`: bestes Ziel, das in dieser Reihenfolge als aktiver Gewinner behandelt werden sollte: explizite URL, SSH-Tunnel, konfigurierte Gegenstelle, dann local loopback.
+ - `warnings[]`: Best-Effort-Warndatensätze mit `code`, `message` und optionalen `targetIds`.
+ - `network`: local loopback-/Tailnet-URL-Hinweise, abgeleitet aus aktueller Konfiguration und Host-Netzwerk.
+ - `discovery.timeoutMs` und `discovery.count`: das tatsächliche Ermittlungsbudget bzw. die Ergebnisanzahl, die für diesen Prüfdurchlauf verwendet wurden.
Pro Ziel (`targets[].connect`):
- - `ok`: Erreichbarkeit nach Verbindung + Einstufung als beeinträchtigt.
+ - `ok`: Erreichbarkeit nach Verbindung + eingeschränkter Klassifizierung.
- `rpcOk`: vollständiger Detail-RPC-Erfolg.
- - `scopeLimited`: Detail-RPC ist wegen fehlendem Operator-Scope fehlgeschlagen.
+ - `scopeLimited`: Detail-RPC ist wegen fehlendem Operator-Umfang fehlgeschlagen.
Pro Ziel (`targets[].auth`):
- - `role`: Auth-Rolle, wie in `hello-ok` gemeldet, wenn verfügbar.
- - `scopes`: gewährte Scopes, wie in `hello-ok` gemeldet, wenn verfügbar.
- - `capability`: die offengelegte Auth-Fähigkeitseinstufung für dieses Ziel.
+ - `role`: in `hello-ok` gemeldete Authentifizierungsrolle, sofern verfügbar.
+ - `scopes`: in `hello-ok` gemeldete gewährte Umfänge, sofern verfügbar.
+ - `capability`: die offengelegte Klassifizierung der Authentifizierungsfähigkeit für dieses Ziel.
- - `ssh_tunnel_failed`: SSH-Tunnel-Einrichtung fehlgeschlagen; der Befehl ist auf direkte Probes zurückgefallen.
- - `multiple_gateways`: mehr als ein Ziel war erreichbar; dies ist ungewöhnlich, sofern Sie nicht absichtlich isolierte Profile ausführen, etwa einen Rettungs-Bot.
- - `auth_secretref_unresolved`: ein konfigurierter Auth-SecretRef konnte für ein fehlgeschlagenes Ziel nicht aufgelöst werden.
- - `probe_scope_limited`: WebSocket-Verbindung erfolgreich, aber die Lese-Probe wurde durch fehlendes `operator.read` eingeschränkt.
+ - `ssh_tunnel_failed`: SSH-Tunnel-Einrichtung ist fehlgeschlagen; der Befehl ist auf direkte Prüfungen zurückgefallen.
+ - `multiple_gateways`: Mehr als ein Ziel war erreichbar; das ist ungewöhnlich, sofern Sie nicht absichtlich isolierte Profile ausführen, etwa einen Rescue-Bot.
+ - `auth_secretref_unresolved`: Ein konfigurierter Authentifizierungs-SecretRef konnte für ein fehlgeschlagenes Ziel nicht aufgelöst werden.
+ - `probe_scope_limited`: WebSocket-Verbindung war erfolgreich, aber die Leseprüfung wurde durch fehlendes `operator.read` eingeschränkt.
#### Remote über SSH (Parität zur Mac-App)
-Der Modus „Remote over SSH“ der macOS-App verwendet eine lokale Portweiterleitung, sodass der Remote-Gateway (der möglicherweise nur an loopback gebunden ist) unter `ws://127.0.0.1:` erreichbar wird.
+Der macOS-App-Modus „Remote über SSH“ verwendet eine lokale Port-Weiterleitung, sodass das Remote-Gateway (das möglicherweise nur an loopback gebunden ist) unter `ws://127.0.0.1:` erreichbar wird.
CLI-Äquivalent:
@@ -383,13 +393,13 @@ openclaw gateway probe --ssh user@gateway-host
`user@host` oder `user@host:port` (Port ist standardmäßig `22`).
- Identity-Datei.
+ Identitätsdatei.
- Wählt den ersten gefundenen Gateway-Host als SSH-Ziel aus dem aufgelösten Discovery-Endpunkt (`local.` plus die konfigurierte Wide-Area-Domain, falls vorhanden). Reine TXT-Hinweise werden ignoriert.
+ Wählen Sie den ersten ermittelten Gateway-Host als SSH-Ziel aus dem aufgelösten Ermittlungsendpunkt (`local.` plus die konfigurierte Wide-Area-Domain, falls vorhanden). Nur-TXT-Hinweise werden ignoriert.
-Konfiguration (optional, als Standardwerte verwendet):
+Konfiguration (optional, wird als Standardwerte verwendet):
- `gateway.remote.sshTarget`
- `gateway.remote.sshIdentity`
@@ -404,7 +414,7 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
```
- JSON-Objekt-Zeichenfolge für Parameter.
+ JSON-Objektzeichenfolge für Parameter.
Gateway-WebSocket-URL.
@@ -416,10 +426,10 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
Gateway-Passwort.
- Zeitüberschreitungsbudget.
+ Zeitbudget.
- Hauptsächlich für agentenartige RPCs, die Zwischenereignisse vor einer finalen Payload streamen.
+ Hauptsächlich für agentenartige RPCs, die Zwischenereignisse vor einer finalen Nutzlast streamen.
Maschinenlesbare JSON-Ausgabe.
@@ -429,7 +439,7 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
`--params` muss gültiges JSON sein.
-## Den Gateway-Service verwalten
+## Gateway-Dienst verwalten
```bash
openclaw gateway install
@@ -441,9 +451,9 @@ openclaw gateway uninstall
### Mit einem Wrapper installieren
-Verwenden Sie `--wrapper`, wenn der verwaltete Service über ein anderes ausführbares Programm starten muss, zum Beispiel einen
-Secrets-Manager-Shim oder einen Run-as-Helfer. Der Wrapper erhält die normalen Gateway-Argumente und ist
-dafür verantwortlich, am Ende `openclaw` oder Node mit diesen Argumenten auszuführen.
+Verwenden Sie `--wrapper`, wenn der verwaltete Dienst über eine andere ausführbare Datei starten muss, zum Beispiel ein
+Secrets-Manager-Shim oder ein Run-as-Helfer. Der Wrapper erhält die normalen Gateway-Argumente und ist
+dafür verantwortlich, letztlich `openclaw` oder Node mit diesen Argumenten per exec zu starten.
```bash
cat > ~/.local/bin/openclaw-doppler <<'EOF'
@@ -457,7 +467,7 @@ openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
openclaw gateway restart
```
-Sie können den Wrapper auch über die Umgebung setzen. `gateway install` prüft, dass der Pfad eine
+Sie können den Wrapper auch über die Umgebung festlegen. `gateway install` validiert, dass der Pfad eine
ausführbare Datei ist, schreibt den Wrapper in die Service-`ProgramArguments` und persistiert
`OPENCLAW_WRAPPER` in der Service-Umgebung für spätere erzwungene Neuinstallationen, Updates und Doctor-
Reparaturen.
@@ -483,39 +493,39 @@ openclaw gateway restart
- - Verwenden Sie `gateway restart`, um einen verwalteten Service neu zu starten. Verketten Sie `gateway stop` und `gateway start` nicht als Ersatz für einen Neustart; unter macOS deaktiviert `gateway stop` absichtlich den LaunchAgent, bevor er gestoppt wird.
- - `gateway restart --wait 30s` überschreibt das konfigurierte Drain-Budget für diesen Neustart. Zahlen ohne Einheit sind Millisekunden; Einheiten wie `s`, `m` und `h` werden akzeptiert. `--wait 0` wartet unbegrenzt.
- - `gateway restart --force` überspringt den Drain für aktive Arbeit und startet sofort neu. Verwenden Sie dies, wenn ein Operator die aufgelisteten Task-Blocker bereits geprüft hat und den Gateway jetzt wieder verfügbar machen möchte.
+ - Verwenden Sie `gateway restart`, um einen verwalteten Dienst neu zu starten. Verketten Sie `gateway stop` und `gateway start` nicht als Neustartersatz; unter macOS deaktiviert `gateway stop` den LaunchAgent absichtlich, bevor er gestoppt wird.
+ - `gateway restart --wait 30s` überschreibt das konfigurierte Restart-Drain-Budget für diesen Neustart. Reine Zahlen sind Millisekunden; Einheiten wie `s`, `m` und `h` werden akzeptiert. `--wait 0` wartet unbegrenzt.
+ - `gateway restart --force` überspringt das Drain aktiver Arbeit und startet sofort neu. Verwenden Sie dies, wenn ein Operator die aufgeführten Task-Blocker bereits geprüft hat und das Gateway jetzt zurückhaben möchte.
- Lebenszyklusbefehle akzeptieren `--json` für Skripting.
-
- - Wenn Token-Authentifizierung ein Token erfordert und `gateway.auth.token` SecretRef-verwaltet ist, prüft `gateway install`, dass der SecretRef auflösbar ist, persistiert das aufgelöste Token aber nicht in Service-Umgebungsmetadaten.
+
+ - Wenn Token-Authentifizierung ein Token erfordert und `gateway.auth.token` per SecretRef verwaltet wird, validiert `gateway install`, dass der SecretRef auflösbar ist, persistiert das aufgelöste Token aber nicht in Service-Umgebungsmetadaten.
- Wenn Token-Authentifizierung ein Token erfordert und der konfigurierte Token-SecretRef nicht aufgelöst ist, schlägt die Installation geschlossen fehl, statt Fallback-Klartext zu persistieren.
- Für Passwortauthentifizierung bei `gateway run` bevorzugen Sie `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` oder ein SecretRef-gestütztes `gateway.auth.password` gegenüber inline `--password`.
- - Im abgeleiteten Auth-Modus lockert ein nur in der Shell gesetztes `OPENCLAW_GATEWAY_PASSWORD` die Token-Anforderungen für die Installation nicht; verwenden Sie dauerhafte Konfiguration (`gateway.auth.password` oder Konfigurations-`env`), wenn Sie einen verwalteten Service installieren.
- - Wenn sowohl `gateway.auth.token` als auch `gateway.auth.password` konfiguriert sind und `gateway.auth.mode` nicht gesetzt ist, wird die Installation blockiert, bis der Modus explizit gesetzt ist.
+ - Im abgeleiteten Authentifizierungsmodus lockert ein nur in der Shell gesetztes `OPENCLAW_GATEWAY_PASSWORD` die Token-Anforderungen bei der Installation nicht; verwenden Sie dauerhafte Konfiguration (`gateway.auth.password` oder Konfigurations-`env`), wenn Sie einen verwalteten Dienst installieren.
+ - Wenn sowohl `gateway.auth.token` als auch `gateway.auth.password` konfiguriert sind und `gateway.auth.mode` nicht gesetzt ist, wird die Installation blockiert, bis der Modus explizit gesetzt wird.
-## Gateways entdecken (Bonjour)
+## Gateways ermitteln (Bonjour)
-`gateway discover` sucht nach Gateway-Beacons (`_openclaw-gw._tcp`).
+`gateway discover` scannt nach Gateway-Beacons (`_openclaw-gw._tcp`).
- Multicast DNS-SD: `local.`
- Unicast DNS-SD (Wide-Area Bonjour): Wählen Sie eine Domain (Beispiel: `openclaw.internal.`) und richten Sie Split-DNS + einen DNS-Server ein; siehe [Bonjour](/de/gateway/bonjour).
-Nur Gateways mit aktivierter Bonjour-Discovery (Standard) kündigen den Beacon an.
+Nur Gateways mit aktivierter Bonjour-Erkennung (Standard) kündigen den Beacon an.
-Wide-Area-Discovery-Datensätze enthalten (TXT):
+Wide-Area-Erkennungsdatensätze enthalten (TXT):
-- `role` (Gateway-Rollenhinweis)
+- `role` (Hinweis auf die Gateway-Rolle)
- `transport` (Transporthinweis, z. B. `gateway`)
- `gatewayPort` (WebSocket-Port, normalerweise `18789`)
-- `sshPort` (optional; Clients setzen SSH-Ziele standardmäßig auf `22`, wenn er fehlt)
+- `sshPort` (optional; Clients verwenden standardmäßig `22` als SSH-Ziel, wenn er fehlt)
- `tailnetDns` (MagicDNS-Hostname, wenn verfügbar)
-- `gatewayTls` / `gatewayTlsSha256` (TLS aktiviert + Zertifikatsfingerabdruck)
+- `gatewayTls` / `gatewayTlsSha256` (TLS aktiviert + Zertifikat-Fingerabdruck)
- `cliPath` (Remote-Installationshinweis, der in die Wide-Area-Zone geschrieben wird)
### `gateway discover`
@@ -525,7 +535,7 @@ openclaw gateway discover
```
- Timeout pro Befehl (browse/resolve).
+ Timeout pro Befehl (Durchsuchen/Auflösen).
Maschinenlesbare Ausgabe (deaktiviert auch Formatierung/Spinner).
@@ -539,9 +549,9 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl'
```
-- Die CLI scannt `local.` sowie die konfigurierte Wide-Area-Domain, wenn eine aktiviert ist.
+- Die CLI scannt `local.` plus die konfigurierte Wide-Area-Domain, wenn eine aktiviert ist.
- `wsUrl` in der JSON-Ausgabe wird aus dem aufgelösten Service-Endpunkt abgeleitet, nicht aus reinen TXT-Hinweisen wie `lanHost` oder `tailnetDns`.
-- Bei `local.` mDNS werden `sshPort` und `cliPath` nur gesendet, wenn `discovery.mdns.mode` auf `full` gesetzt ist. Wide-Area-DNS-SD schreibt weiterhin `cliPath`; `sshPort` bleibt auch dort optional.
+- Bei `local.`-mDNS werden `sshPort` und `cliPath` nur per Broadcast gesendet, wenn `discovery.mdns.mode` auf `full` gesetzt ist. Wide-Area-DNS-SD schreibt `cliPath` weiterhin; `sshPort` bleibt auch dort optional.
diff --git a/docs/de/cli/models.md b/docs/de/cli/models.md
index d3fd6f5fc..bb551a1d2 100644
--- a/docs/de/cli/models.md
+++ b/docs/de/cli/models.md
@@ -1,26 +1,26 @@
---
read_when:
- - Sie möchten Standardmodelle ändern oder den Authentifizierungsstatus des Providers anzeigen
- - Sie möchten verfügbare Modelle/Provider scannen und Auth-Profile debuggen
+ - Sie möchten Standardmodelle ändern oder den Provider-Authentifizierungsstatus anzeigen
+ - Sie möchten verfügbare Modelle/Provider scannen und Authentifizierungsprofile debuggen
summary: CLI-Referenz für `openclaw models` (status/list/set/scan, Aliasse, Fallbacks, Authentifizierung)
title: Modelle
x-i18n:
- generated_at: "2026-05-01T06:40:55Z"
+ generated_at: "2026-05-04T18:23:31Z"
model: gpt-5.5
provider: openai
- source_hash: 538d3e4808329737fdc044dc6e14e5c7c78052e75d8a8b3b257b1ebd821c84d1
+ source_hash: dc7842f02e29aa0ac2ae88f3d42bba71f1890a58ab22d818dbee0585bc562fea
source_path: cli/models.md
workflow: 16
---
# `openclaw models`
-Modellerkennung, Scannen und Konfiguration (Standardmodell, Fallbacks, Auth-Profile).
+Modellerkennung, Scan und Konfiguration (Standardmodell, Fallbacks, Auth-Profile).
Verwandt:
- Provider + Modelle: [Modelle](/de/providers/models)
-- Konzepte zur Modellauswahl + `/models`-Slash-Befehl: [Modelle-Konzept](/de/concepts/models)
+- Konzepte zur Modellauswahl + Slash-Befehl `/models`: [Modellkonzept](/de/concepts/models)
- Provider-Auth-Einrichtung: [Erste Schritte](/de/start/getting-started)
## Häufige Befehle
@@ -32,76 +32,77 @@ openclaw models set
openclaw models scan
```
-`openclaw models status` zeigt die aufgelösten Standard-/Fallback-Modelle sowie eine Auth-Übersicht.
-Wenn Provider-Nutzungssnapshots verfügbar sind, enthält der OAuth/API-Key-Statusabschnitt
+`openclaw models status` zeigt die aufgelösten Standard-/Fallback-Werte plus einen Auth-Überblick.
+Wenn Snapshots zur Provider-Nutzung verfügbar sind, enthält der Abschnitt zum OAuth/API-Schlüssel-Status
Provider-Nutzungsfenster und Kontingent-Snapshots.
-Aktuelle Provider für Nutzungsfenster: Anthropic, GitHub Copilot, Gemini CLI, OpenAI
+Aktuelle Provider mit Nutzungsfenstern: Anthropic, GitHub Copilot, Gemini CLI, OpenAI
Codex, MiniMax, Xiaomi und z.ai. Nutzungs-Auth stammt aus Provider-spezifischen Hooks,
-wenn verfügbar; andernfalls fällt OpenClaw auf passende OAuth/API-Key-
-Zugangsdaten aus Auth-Profilen, Env oder Konfiguration zurück.
-In der `--json`-Ausgabe ist `auth.providers` die Env-/Config-/Store-bewusste Provider-
-Übersicht, während `auth.oauth` nur die Integrität der Auth-Store-Profile beschreibt.
-Fügen Sie `--probe` hinzu, um Live-Auth-Probes gegen jedes konfigurierte Provider-Profil auszuführen.
-Probes sind echte Anfragen (sie können Tokens verbrauchen und Rate Limits auslösen).
-Verwenden Sie `--agent `, um den Modell-/Auth-Zustand eines konfigurierten Agenten zu prüfen. Wenn ausgelassen,
+wenn verfügbar; andernfalls fällt OpenClaw auf passende OAuth/API-Schlüssel-
+Anmeldedaten aus Auth-Profilen, Umgebungsvariablen oder Konfiguration zurück.
+In der `--json`-Ausgabe ist `auth.providers` die Umgebungs-/Konfigurations-/Store-bewusste
+Provider-Übersicht, während `auth.oauth` nur den Zustand der Auth-Store-Profile enthält.
+Fügen Sie `--probe` hinzu, um Live-Auth-Probes für jedes konfigurierte Provider-Profil auszuführen.
+Probes sind echte Anfragen (sie können Tokens verbrauchen und Ratenlimits auslösen).
+Verwenden Sie `--agent `, um den Modell-/Auth-Zustand eines konfigurierten Agents zu prüfen. Wenn ausgelassen,
verwendet der Befehl `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`, falls gesetzt, andernfalls den
-konfigurierten Standardagenten.
-Probe-Zeilen können aus Auth-Profilen, Env-Zugangsdaten oder `models.json` stammen.
+konfigurierten Standard-Agent.
+Probe-Zeilen können aus Auth-Profilen, Umgebungs-Anmeldedaten oder `models.json` stammen.
Hinweise:
- `models set ` akzeptiert `provider/model` oder einen Alias.
- `models list` ist schreibgeschützt: Es liest Konfiguration, Auth-Profile, vorhandenen Katalogzustand
- und Provider-eigene Katalogzeilen, schreibt `models.json` aber nicht neu.
-- Die Spalte `Auth` ist Provider-bezogen und schreibgeschützt. Sie wird aus lokalen
- Auth-Profilmetadaten, Env-Markern, konfigurierten Provider-Keys, lokalen Provider-
- Markern, AWS-Bedrock-Env-/Profilmarkern und synthetischen Auth-Metadaten von Plugins berechnet;
- sie lädt keine Provider-Runtime, liest keine Keychain-Secrets, ruft keine Provider-
- APIs auf und belegt keine exakte Ausführungsbereitschaft pro Modell.
+ und Provider-eigene Katalogzeilen, schreibt aber `models.json`
+ nicht neu.
+- Die Spalte `Auth` ist Provider-weit und schreibgeschützt. Sie wird aus lokalen
+ Auth-Profilmetadaten, Umgebungsmarkern, konfigurierten Provider-Schlüsseln, lokalen Provider-
+ Markern, AWS-Bedrock-Umgebungs-/Profilmarkern und synthetischen Auth-Metadaten von Plugins berechnet;
+ sie lädt keine Provider-Laufzeit, liest keine Keychain-Secrets, ruft keine Provider-
+ APIs auf und beweist keine exakte Ausführungsbereitschaft pro Modell.
- `models list --all --provider ` kann Provider-eigene statische Katalogzeilen
aus Plugin-Manifesten oder gebündelten Provider-Katalogmetadaten enthalten, auch wenn Sie
sich bei diesem Provider noch nicht authentifiziert haben. Diese Zeilen werden weiterhin als
nicht verfügbar angezeigt, bis passende Auth konfiguriert ist.
-- `models list` hält die Control Plane reaktionsfähig, während die Provider-Katalog-
- Erkennung langsam ist. Die Standard- und konfigurierten Ansichten fallen nach kurzer Wartezeit
- auf konfigurierte oder synthetische Modellzeilen zurück und lassen die Erkennung im
- Hintergrund abschließen. Verwenden Sie `--all`, wenn Sie den exakten vollständig erkannten Katalog benötigen
- und bereit sind, auf die Provider-Erkennung zu warten.
-- Ein breites `models list --all` führt Manifest-Katalogzeilen über Registry-Zeilen zusammen,
- ohne Provider-Runtime-Supplement-Hooks zu laden. Provider-gefilterte Manifest-
- Schnellpfade verwenden nur Provider, die als `static` markiert sind; Provider, die als `refreshable`
- markiert sind, bleiben Registry-/Cache-gestützt und hängen Manifest-Zeilen als Supplements an, während
- Provider, die als `runtime` markiert sind, bei Registry-/Runtime-Erkennung bleiben.
-- `models list` hält native Modellmetadaten und Runtime-Caps getrennt. In der Tabellen-
- ausgabe zeigt `Ctx` `contextTokens/contextWindow`, wenn sich ein effektiver Runtime-
- Cap vom nativen Kontextfenster unterscheidet; JSON-Zeilen enthalten `contextTokens`,
- wenn ein Provider diesen Cap bereitstellt.
-- `models list --provider ` filtert nach Provider-ID, etwa `moonshot` oder
- `openai-codex`. Es akzeptiert keine Anzeigelabels aus interaktiven Provider-
- Auswahlen, etwa `Moonshot AI`.
-- Modellreferenzen werden durch Aufteilen am **ersten** `/` geparst. Wenn die Modell-ID `/` enthält (OpenRouter-Stil), geben Sie das Provider-Präfix an (Beispiel: `openrouter/moonshotai/kimi-k2`).
+- `models list` hält die Steuerungsebene reaktionsfähig, während die Provider-Katalog-
+ Erkennung langsam ist. Die Standard- und konfigurierten Ansichten fallen nach kurzer Wartezeit auf konfigurierte oder
+ synthetische Modellzeilen zurück und lassen die Erkennung im
+ Hintergrund abschließen. Verwenden Sie `--all`, wenn Sie den exakten vollständigen erkannten Katalog benötigen und
+ bereit sind, auf die Provider-Erkennung zu warten.
+- Breites `models list --all` führt Manifest-Katalogzeilen über Registry-Zeilen zusammen,
+ ohne Provider-Laufzeit-Ergänzungs-Hooks zu laden. Provider-gefilterte Manifest-
+ Schnellpfade verwenden nur Provider, die als `static` markiert sind; Provider, die als `refreshable` markiert sind,
+ bleiben Registry-/Cache-basiert und hängen Manifestzeilen als Ergänzungen an, während
+ Provider, die als `runtime` markiert sind, bei Registry-/Laufzeit-Erkennung bleiben.
+- `models list` hält native Modellmetadaten und Laufzeitgrenzen getrennt. In der Tabellen-
+ Ausgabe zeigt `Ctx` `contextTokens/contextWindow`, wenn sich eine effektive Laufzeit-
+ Grenze vom nativen Kontextfenster unterscheidet; JSON-Zeilen enthalten `contextTokens`,
+ wenn ein Provider diese Grenze bereitstellt.
+- `models list --provider ` filtert nach Provider-ID, z. B. `moonshot` oder
+ `openai-codex`. Es akzeptiert keine Anzeigenamen aus interaktiven Provider-
+ Auswahlmenüs, z. B. `Moonshot AI`.
+- Modellreferenzen werden durch Aufteilen beim **ersten** `/` geparst. Wenn die Modell-ID `/` enthält (OpenRouter-Stil), geben Sie das Provider-Präfix an (Beispiel: `openrouter/moonshotai/kimi-k2`).
- Wenn Sie den Provider auslassen, löst OpenClaw die Eingabe zuerst als Alias auf, dann
- als eindeutigen Match eines konfigurierten Providers für diese exakte Modell-ID, und erst danach
+ als eindeutige Übereinstimmung eines konfigurierten Providers für genau diese Modell-ID, und erst danach
fällt es mit einer Deprecation-Warnung auf den konfigurierten Standard-Provider zurück.
Wenn dieser Provider das konfigurierte Standardmodell nicht mehr bereitstellt, fällt OpenClaw
auf den ersten konfigurierten Provider/das erste konfigurierte Modell zurück, statt einen
- veralteten entfernten Provider-Standard anzuzeigen.
-- `models status` kann in der Auth-Ausgabe `marker()` für nicht geheime Platzhalter anzeigen (zum Beispiel `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`), statt sie als Secrets zu maskieren.
+ veralteten Standard eines entfernten Providers anzuzeigen.
+- `models status` kann `marker()` in der Auth-Ausgabe für nicht geheime Platzhalter anzeigen (zum Beispiel `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`), statt sie als Secrets zu maskieren.
-### Modelle scannen
+### Modell-Scan
`models scan` liest den öffentlichen `:free`-Katalog von OpenRouter und bewertet Kandidaten für
-Fallback-Nutzung. Der Katalog selbst ist öffentlich, daher benötigen reine Metadaten-Scans
-keinen OpenRouter-Key.
+die Fallback-Nutzung. Der Katalog selbst ist öffentlich, daher benötigen Metadaten-only-Scans keinen
+OpenRouter-Schlüssel.
Standardmäßig versucht OpenClaw, Tool- und Bildunterstützung mit Live-Modellaufrufen zu prüfen.
-Wenn kein OpenRouter-Key konfiguriert ist, fällt der Befehl auf reine Metadaten-
+Wenn kein OpenRouter-Schlüssel konfiguriert ist, fällt der Befehl auf eine Metadaten-only-
Ausgabe zurück und erklärt, dass `:free`-Modelle weiterhin `OPENROUTER_API_KEY` für
Probes und Inferenz benötigen.
Optionen:
-- `--no-probe` (nur Metadaten; keine Konfigurations-/Secrets-Suche)
+- `--no-probe` (nur Metadaten; keine Konfigurations-/Secret-Suche)
- `--min-params `
- `--max-age-days `
- `--provider `
@@ -114,7 +115,7 @@ Optionen:
- `--set-image`
- `--json`
-`--set-default` und `--set-image` erfordern Live-Probes; reine Metadaten-Scan-
+`--set-default` und `--set-image` erfordern Live-Probes; Metadaten-only-Scan-
Ergebnisse dienen nur zur Information und werden nicht auf die Konfiguration angewendet.
### Modellstatus
@@ -126,14 +127,14 @@ Optionen:
- `--check` (Exit 1=abgelaufen/fehlend, 2=läuft bald ab)
- `--probe` (Live-Probe konfigurierter Auth-Profile)
- `--probe-provider ` (einen Provider prüfen)
-- `--probe-profile ` (wiederholte oder kommagetrennte Profil-IDs)
+- `--probe-profile ` (wiederholte oder durch Kommas getrennte Profil-IDs)
- `--probe-timeout `
- `--probe-concurrency `
- `--probe-max-tokens `
-- `--agent ` (konfigurierte Agenten-ID; überschreibt `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`)
+- `--agent ` (konfigurierte Agent-ID; überschreibt `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`)
`--json` reserviert stdout für die JSON-Nutzlast. Auth-Profil-, Provider-
-und Startdiagnosen werden an stderr geleitet, damit Skripte stdout direkt
+und Startdiagnosen werden nach stderr geleitet, damit Skripte stdout direkt
in Tools wie `jq` pipen können.
Probe-Statusgruppen:
@@ -147,7 +148,7 @@ Probe-Statusgruppen:
- `unknown`
- `no_model`
-Zu erwartende Probe-Detail-/Reason-Code-Fälle:
+Zu erwartende Fälle für Probe-Details/Reason-Codes:
- `excluded_by_auth_order`: Ein gespeichertes Profil existiert, aber explizites
`auth.order.` hat es ausgelassen, daher meldet die Probe den Ausschluss, statt
@@ -157,7 +158,7 @@ Zu erwartende Probe-Detail-/Reason-Code-Fälle:
- `no_model`: Provider-Auth existiert, aber OpenClaw konnte keinen prüfbaren
Modellkandidaten für diesen Provider auflösen.
-## Aliasse + Fallbacks
+## Aliase + Fallbacks
```bash
openclaw models aliases list
@@ -168,24 +169,32 @@ openclaw models fallbacks list
```bash
openclaw models auth add
+openclaw models auth list [--provider ] [--json]
openclaw models auth login --provider
openclaw models auth setup-token --provider
openclaw models auth paste-token
```
`models auth add` ist der interaktive Auth-Helfer. Er kann einen Provider-Auth-
-Flow (OAuth/API-Key) starten oder Sie je nach ausgewähltem Provider zum manuellen Token-Einfügen führen.
+Flow (OAuth/API-Schlüssel) starten oder Sie je nach gewähltem
+Provider zum manuellen Einfügen eines Tokens führen.
-`models auth login` führt den Auth-Flow eines Provider-Plugins aus (OAuth/API-Key). Verwenden Sie
+`models auth list` listet gespeicherte Auth-Profile für den ausgewählten Agent auf, ohne
+Token-, API-Schlüssel- oder OAuth-Secret-Material auszugeben. Verwenden Sie `--provider `, um
+auf einen Provider wie `openai-codex` zu filtern, und `--json` für Skripting.
+
+`models auth login` führt den Auth-Flow (OAuth/API-Schlüssel) eines Provider-Plugins aus. Verwenden Sie
`openclaw plugins list`, um zu sehen, welche Provider installiert sind.
Verwenden Sie `openclaw models auth --agent `, um Auth-Ergebnisse in einen
-bestimmten konfigurierten Agenten-Store zu schreiben. Das übergeordnete Flag `--agent` wird von
-`add`, `login`, `setup-token`, `paste-token` und `login-github-copilot` beachtet.
+bestimmten konfigurierten Agent-Store zu schreiben. Das übergeordnete Flag `--agent` wird von
+`add`, `list`, `login`, `setup-token`, `paste-token` und
+`login-github-copilot` berücksichtigt.
Beispiele:
```bash
openclaw models auth login --provider openai-codex --set-default
+openclaw models auth list --provider openai-codex
```
Hinweise:
@@ -195,14 +204,14 @@ Hinweise:
- `setup-token` erfordert ein interaktives TTY und führt die Token-Auth-
Methode des Providers aus (standardmäßig die `setup-token`-Methode dieses Providers, wenn er
eine bereitstellt).
-- `paste-token` akzeptiert einen Token-String, der anderswo oder durch Automatisierung erzeugt wurde.
+- `paste-token` akzeptiert eine an anderer Stelle oder durch Automatisierung generierte Token-Zeichenfolge.
- `paste-token` erfordert `--provider`, fragt nach dem Token-Wert und schreibt
- ihn in die Standardprofil-ID `:manual`, sofern Sie nicht
+ ihn in die Standard-Profil-ID `:manual`, sofern Sie nicht
`--profile-id` übergeben.
- `paste-token --expires-in ` speichert einen absoluten Token-Ablauf aus einer
relativen Dauer wie `365d` oder `12h`.
-- Anthropic-Hinweis: Anthropic-Mitarbeitende haben uns mitgeteilt, dass Claude-CLI-Nutzung im OpenClaw-Stil wieder erlaubt ist, daher behandelt OpenClaw Claude-CLI-Wiederverwendung und `claude -p`-Nutzung für diese Integration als genehmigt, sofern Anthropic keine neue Richtlinie veröffentlicht.
-- Anthropic `setup-token` / `paste-token` bleiben als unterstützter OpenClaw-Token-Pfad verfügbar, aber OpenClaw bevorzugt jetzt Claude-CLI-Wiederverwendung und `claude -p`, wenn verfügbar.
+- Anthropic-Hinweis: Anthropic-Mitarbeiter 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 genehmigt, sofern Anthropic keine neue Richtlinie veröffentlicht.
+- Anthropic `setup-token` / `paste-token` bleiben als unterstützter OpenClaw-Token-Pfad verfügbar, aber OpenClaw bevorzugt jetzt die Wiederverwendung der Claude CLI und `claude -p`, wenn verfügbar.
## Verwandt
diff --git a/docs/de/cli/proxy.md b/docs/de/cli/proxy.md
index 6b62153a4..9cc641124 100644
--- a/docs/de/cli/proxy.md
+++ b/docs/de/cli/proxy.md
@@ -1,36 +1,31 @@
---
read_when:
- Sie müssen das vom Betreiber verwaltete Proxy-Routing vor der Bereitstellung validieren
- - Sie müssen den OpenClaw-Transportdatenverkehr lokal zur Fehlersuche erfassen
- - Sie möchten Debug-Proxy-Sitzungen, Blobs oder integrierte Abfragevoreinstellungen prüfen
-summary: CLI-Referenz für `openclaw proxy`, einschließlich der betreiberverwalteten Proxy-Validierung und der lokalen Prüfansicht für Debug-Proxy-Erfassungen
+ - Sie müssen OpenClaw-Transportdatenverkehr lokal zur Fehlerbehebung erfassen
+ - Sie möchten Debug-Proxy-Sitzungen, Blobs oder integrierte Abfragevoreinstellungen untersuchen
+summary: CLI-Referenz für `openclaw proxy`, einschließlich der betreiberverwalteten Proxy-Validierung und des lokalen Inspektors für Debug-Proxy-Erfassungen
title: Proxy
x-i18n:
- generated_at: "2026-05-04T06:41:36Z"
+ generated_at: "2026-05-04T18:23:43Z"
model: gpt-5.5
provider: openai
- source_hash: 9589bedafb97c31bcb6536a04307cd0c6550e1f307693bd4401785d79f34a1eb
+ source_hash: 092c4e946dcab5e78e37d6fc77bb067b7a649368f8571fa127e462a85fa14ce5
source_path: cli/proxy.md
workflow: 16
---
# `openclaw proxy`
-Validieren Sie vom Betreiber verwaltetes Proxy-Routing oder führen Sie den lokalen expliziten Debug-Proxy aus
-und prüfen Sie erfassten Traffic.
+Validieren Sie das vom Betreiber verwaltete Proxy-Routing, oder führen Sie den lokalen expliziten Debug-Proxy aus und prüfen Sie den erfassten Datenverkehr.
-Verwenden Sie `validate`, um einen vom Betreiber verwalteten Forward-Proxy vor dem Aktivieren des
-OpenClaw-Proxy-Routings vorab zu prüfen. Die anderen Befehle sind Debugging-Werkzeuge für
-Untersuchungen auf Transportebene: Sie können einen lokalen Proxy starten, einen untergeordneten Befehl
-mit aktivierter Erfassung ausführen, Erfassungssitzungen auflisten, häufige Traffic-Muster abfragen, erfasste
-Blobs lesen und lokale Erfassungsdaten löschen.
+Verwenden Sie `validate`, um einen vom Betreiber verwalteten Forward-Proxy vor der Aktivierung des OpenClaw-Proxy-Routings vorab zu prüfen. Die anderen Befehle sind Debugging-Werkzeuge für Untersuchungen auf Transportebene: Sie können einen lokalen Proxy starten, einen untergeordneten Befehl mit aktivierter Erfassung ausführen, Erfassungssitzungen auflisten, häufige Datenverkehrsmuster abfragen, erfasste Blobs lesen und lokale Erfassungsdaten bereinigen.
## Befehle
```bash
openclaw proxy start [--host ] [--port ]
openclaw proxy run [--host ] [--port ] --
-openclaw proxy validate [--json] [--proxy-url ] [--allowed-url ] [--denied-url ] [--timeout-ms ]
+openclaw proxy validate [--json] [--proxy-url ] [--allowed-url ] [--denied-url ] [--apns-reachable] [--apns-authority ] [--timeout-ms ]
openclaw proxy coverage
openclaw proxy sessions [--limit ]
openclaw proxy query --preset [--session ]
@@ -40,25 +35,19 @@ openclaw proxy purge
## Validieren
-`openclaw proxy validate` prüft die effektive vom Betreiber verwaltete Proxy-URL aus
-`--proxy-url`, der Konfiguration oder `OPENCLAW_PROXY_URL`. Es meldet ein Konfigurationsproblem, wenn
-kein Proxy aktiviert und konfiguriert ist; verwenden Sie `--proxy-url` für eine einmalige Vorabprüfung,
-bevor Sie die Konfiguration ändern. Standardmäßig wird geprüft, ob ein öffentliches Ziel
-über den Proxy erfolgreich erreicht wird und ob der Proxy keinen temporären Loopback-Canary erreichen kann.
-Benutzerdefinierte abgelehnte Ziele sind fail-closed: HTTP-Antworten und mehrdeutige
-Transportfehler schlagen beide fehl, sofern Sie kein bereitstellungsspezifisches Ablehnungssignal
-separat verifizieren können.
+`openclaw proxy validate` prüft die effektive vom Betreiber verwaltete Proxy-URL aus `--proxy-url`, der Konfiguration oder `OPENCLAW_PROXY_URL`. Es meldet ein Konfigurationsproblem, wenn kein Proxy aktiviert und konfiguriert ist; verwenden Sie `--proxy-url` für eine einmalige Vorabprüfung, bevor Sie die Konfiguration ändern. Standardmäßig wird überprüft, dass ein öffentliches Ziel über den Proxy erfolgreich erreichbar ist und dass der Proxy keinen temporären Loopback-Canary erreichen kann. Benutzerdefinierte verweigerte Ziele werden bei Fehlern verweigernd behandelt: HTTP-Antworten und mehrdeutige Transportfehler schlagen beide fehl, sofern Sie kein bereitstellungsspezifisches Verweigerungssignal separat überprüfen können. Fügen Sie `--apns-reachable` hinzu, um zusätzlich einen APNs-HTTP/2-CONNECT-Tunnel über den Proxy zu öffnen und zu bestätigen, dass Sandbox-APNs antwortet; die Prüfung verwendet absichtlich ein ungültiges Provider-Token, daher ist eine APNs-Antwort `403 InvalidProviderToken` ein erfolgreiches Erreichbarkeitssignal.
Optionen:
-- `--json`: Maschinenlesbares JSON ausgeben.
-- `--proxy-url `: Diese Proxy-URL statt Konfiguration oder env validieren.
-- `--allowed-url `: Ein Ziel hinzufügen, das über den Proxy erfolgreich sein soll. Wiederholen, um mehrere Ziele zu prüfen.
-- `--denied-url `: Ein Ziel hinzufügen, das vom Proxy blockiert werden soll. Wiederholen, um mehrere Ziele zu prüfen.
+- `--json`: Gibt maschinenlesbares JSON aus.
+- `--proxy-url `: Validiert diese Proxy-URL anstelle von Konfiguration oder Umgebung.
+- `--allowed-url `: Fügt ein Ziel hinzu, das über den Proxy erfolgreich erreichbar sein soll. Wiederholen Sie die Option, um mehrere Ziele zu prüfen.
+- `--denied-url `: Fügt ein Ziel hinzu, das vom Proxy blockiert werden soll. Wiederholen Sie die Option, um mehrere Ziele zu prüfen.
+- `--apns-reachable`: Überprüft zusätzlich, dass Sandbox-APNs-HTTP/2 über den Proxy erreichbar ist.
+- `--apns-authority `: APNs-Autorität, die mit `--apns-reachable` geprüft wird (`https://api.sandbox.push.apple.com` standardmäßig; Produktion ist `https://api.push.apple.com`).
- `--timeout-ms `: Zeitlimit pro Anfrage in Millisekunden.
-Siehe [Netzwerk-Proxy](/de/security/network-proxy) für Hinweise zur Bereitstellung und
-Ablehnungssemantik.
+Siehe [Network Proxy](/de/security/network-proxy) für Bereitstellungshinweise und Verweigerungssemantik.
## Abfrage-Presets
@@ -74,13 +63,13 @@ Ablehnungssemantik.
## Hinweise
- `start` verwendet standardmäßig `127.0.0.1`, sofern `--host` nicht gesetzt ist.
-- `run` startet einen lokalen Debug-Proxy und führt anschließend den Befehl nach `--` aus.
-- Das direkte Upstream-Forwarding des Debug-Proxys öffnet Upstream-Sockets für Diagnosen. Wenn der von OpenClaw verwaltete Proxy-Modus aktiv ist, ist direktes Forwarding für Proxy-Anfragen und CONNECT-Tunnel standardmäßig deaktiviert; setzen Sie `OPENCLAW_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1` nur für genehmigte lokale Diagnosen.
-- `validate` wird mit Code 1 beendet, wenn die Proxy-Konfiguration oder Zielprüfungen fehlschlagen.
+- `run` startet einen lokalen Debug-Proxy und führt dann den Befehl nach `--` aus.
+- Die direkte Upstream-Weiterleitung des Debug-Proxys öffnet Upstream-Sockets für Diagnosezwecke. Wenn der von OpenClaw verwaltete Proxy-Modus aktiv ist, ist die direkte Weiterleitung für Proxy-Anfragen und CONNECT-Tunnel standardmäßig deaktiviert; setzen Sie `OPENCLAW_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1` nur für genehmigte lokale Diagnosen.
+- `validate` beendet sich mit Code 1, wenn die Proxy-Konfiguration oder Zielprüfungen fehlschlagen.
- Erfassungen sind lokale Debugging-Daten; verwenden Sie `openclaw proxy purge`, wenn Sie fertig sind.
## Verwandte Themen
-- [CLI-Referenz](/de/cli)
-- [Netzwerk-Proxy](/de/security/network-proxy)
-- [Authentifizierung für vertrauenswürdige Proxys](/de/gateway/trusted-proxy-auth)
+- [CLI reference](/de/cli)
+- [Network Proxy](/de/security/network-proxy)
+- [Trusted proxy auth](/de/gateway/trusted-proxy-auth)
diff --git a/docs/de/gateway/cli-backends.md b/docs/de/gateway/cli-backends.md
index c2ca09105..318716fca 100644
--- a/docs/de/gateway/cli-backends.md
+++ b/docs/de/gateway/cli-backends.md
@@ -1,21 +1,21 @@
---
read_when:
- Sie möchten einen zuverlässigen Fallback, wenn API-Provider ausfallen
- - Sie verwenden Codex CLI oder andere lokale KI-CLIs und möchten sie wiederverwenden
+ - Sie führen die Codex CLI oder andere lokale KI-CLIs aus und möchten sie wiederverwenden
- Sie möchten die MCP-Loopback-Bridge für den Zugriff auf CLI-Backend-Tools verstehen
summary: 'CLI-Backends: lokaler KI-CLI-Fallback mit optionaler MCP-Tool-Bridge'
title: CLI-Backends
x-i18n:
- generated_at: "2026-05-02T20:46:26Z"
+ generated_at: "2026-05-04T18:23:39Z"
model: gpt-5.5
provider: openai
- source_hash: f343469d6a42dc6146196355dc2ba3feed045515c3d8446941b90971aadc9a16
+ source_hash: 55534c48c5e226857b9320fd369416583e5c2efc80eabd4746f939afdd027dc1
source_path: gateway/cli-backends.md
workflow: 16
---
-OpenClaw kann **lokale KI-CLIs** als **Nur-Text-Fallback** ausführen, wenn API-Provider ausgefallen,
-rate-limitiert oder vorübergehend fehlerhaft sind. Dies ist absichtlich konservativ:
+OpenClaw kann **lokale AI CLIs** als **rein textbasierten Fallback** ausführen, wenn API-Provider ausfallen,
+rate-limitiert sind oder sich vorübergehend fehlerhaft verhalten. Dies ist bewusst konservativ:
- **OpenClaw-Tools werden nicht direkt injiziert**, aber Backends mit `bundleMcp: true`
können Gateway-Tools über eine Loopback-MCP-Bridge erhalten.
@@ -23,11 +23,11 @@ rate-limitiert oder vorübergehend fehlerhaft sind. Dies ist absichtlich konserv
- **Sitzungen werden unterstützt** (damit Folge-Turns kohärent bleiben).
- **Bilder können durchgereicht werden**, wenn die CLI Bildpfade akzeptiert.
-Dies ist eher als **Sicherheitsnetz** gedacht als als primärer Pfad. Verwenden Sie es, wenn Sie
-Textantworten möchten, die „immer funktionieren“, ohne von externen APIs abhängig zu sein.
+Dies ist als **Sicherheitsnetz** statt als primärer Pfad gedacht. Nutzen Sie es, wenn Sie
+Textantworten wünschen, die „immer funktionieren“, ohne von externen APIs abhängig zu sein.
Wenn Sie eine vollständige Harness-Laufzeit mit ACP-Sitzungssteuerung, Hintergrundaufgaben,
-Thread-/Konversationsbindung und persistenten externen Coding-Sitzungen wünschen, verwenden Sie stattdessen
+Thread-/Konversationsbindung und persistenten externen Coding-Sitzungen möchten, verwenden Sie stattdessen
[ACP Agents](/de/tools/acp-agents). CLI-Backends sind kein ACP.
## Einsteigerfreundlicher Schnellstart
@@ -56,7 +56,7 @@ Befehlspfad hinzu:
}
```
-Das ist alles. Keine Schlüssel, keine zusätzliche Authentifizierungskonfiguration über die CLI selbst hinaus erforderlich.
+Das ist alles. Keine Schlüssel, keine zusätzliche Auth-Konfiguration über die CLI selbst hinaus erforderlich.
Wenn Sie ein gebündeltes CLI-Backend als **primären Nachrichten-Provider** auf einem
Gateway-Host verwenden, lädt OpenClaw jetzt automatisch das zugehörige gebündelte Plugin, wenn Ihre Konfiguration
@@ -87,7 +87,7 @@ Fügen Sie Ihrer Fallback-Liste ein CLI-Backend hinzu, damit es nur ausgeführt
Hinweise:
- Wenn Sie `agents.defaults.models` (Allowlist) verwenden, müssen Sie dort auch Ihre CLI-Backend-Modelle aufnehmen.
-- Wenn der primäre Provider fehlschlägt (Authentifizierung, Rate Limits, Timeouts), versucht OpenClaw
+- Wenn der primäre Provider fehlschlägt (Auth, Rate Limits, Timeouts), versucht OpenClaw
als Nächstes das CLI-Backend.
## Konfigurationsübersicht
@@ -98,7 +98,7 @@ Alle CLI-Backends befinden sich unter:
agents.defaults.cliBackends
```
-Jeder Eintrag wird durch eine **Provider-ID** indiziert (z. B. `codex-cli`, `my-cli`).
+Jeder Eintrag wird durch eine **Provider-ID** (z. B. `codex-cli`, `my-cli`) geschlüsselt.
Die Provider-ID wird zur linken Seite Ihrer Modellreferenz:
```
@@ -150,42 +150,48 @@ Die Provider-ID wird zur linken Seite Ihrer Modellreferenz:
1. **Wählt ein Backend** basierend auf dem Provider-Präfix (`codex-cli/...`) aus.
2. **Erstellt einen System-Prompt** mit demselben OpenClaw-Prompt und Workspace-Kontext.
3. **Führt die CLI aus** mit einer Sitzungs-ID (falls unterstützt), damit der Verlauf konsistent bleibt.
- Das gebündelte `claude-cli`-Backend hält pro OpenClaw-Sitzung einen Claude-stdio-Prozess aktiv
+ Das gebündelte `claude-cli`-Backend hält pro OpenClaw-Sitzung einen Claude-stdio-Prozess am Leben
und sendet Folge-Turns über stream-json-stdin.
4. **Parst die Ausgabe** (JSON oder Klartext) und gibt den finalen Text zurück.
-5. **Persistiert Sitzungs-IDs** pro Backend, damit Folge-Turns dieselbe CLI-Sitzung wiederverwenden.
+5. **Persistiert Sitzungs-IDs** pro Backend, sodass Folge-Turns dieselbe CLI-Sitzung wiederverwenden.
Das gebündelte Anthropic-Backend `claude-cli` wird wieder unterstützt. Anthropic-Mitarbeiter
-haben uns mitgeteilt, dass die Claude-CLI-Nutzung im OpenClaw-Stil wieder erlaubt ist, daher behandelt OpenClaw
-die Nutzung von `claude -p` für diese Integration als genehmigt, sofern Anthropic keine
+teilten uns mit, dass eine Claude-CLI-Nutzung im OpenClaw-Stil wieder erlaubt ist, daher behandelt OpenClaw
+die Nutzung von `claude -p` für diese Integration als genehmigt, solange Anthropic keine
neue Richtlinie veröffentlicht.
-Das gebündelte OpenAI-Backend `codex-cli` übergibt OpenClaws System-Prompt über
-Codexs Konfigurationsüberschreibung `model_instructions_file` (`-c
+Das gebündelte OpenAI-Backend `codex-cli` übergibt den System-Prompt von OpenClaw über
+Codex' Konfigurationsüberschreibung `model_instructions_file` (`-c
model_instructions_file="..."`). Codex stellt kein Claude-artiges
-`--append-system-prompt`-Flag bereit, daher schreibt OpenClaw den zusammengesetzten Prompt in eine
-temporäre Datei für jede neue Codex-CLI-Sitzung.
+`--append-system-prompt`-Flag bereit, daher schreibt OpenClaw den zusammengesetzten Prompt für jede neue Codex-CLI-Sitzung
+in eine temporäre Datei.
Das gebündelte Anthropic-Backend `claude-cli` erhält den OpenClaw-Skills-Snapshot
-auf zwei Arten: den kompakten OpenClaw-Skills-Katalog im angehängten System-Prompt und
-ein temporäres Claude-Code-Plugin, das mit `--plugin-dir` übergeben wird. Das Plugin enthält
-nur die zulässigen Skills für diesen Agenten/diese Sitzung, sodass der native Skill-Resolver von Claude Code
-dieselbe gefilterte Menge sieht, die OpenClaw andernfalls im
-Prompt bewerben würde. Skill-Env-/API-Schlüssel-Overrides werden weiterhin von OpenClaw auf die
-Child-Prozessumgebung für den Lauf angewendet.
+auf zwei Wegen: den kompakten OpenClaw-Skills-Katalog im angehängten System-Prompt und
+ein temporäres Claude Code-Plugin, das mit `--plugin-dir` übergeben wird. Das Plugin enthält
+nur die zulässigen Skills für diesen Agent/diese Sitzung, sodass der native Skill-Resolver von Claude Code
+dieselbe gefilterte Menge sieht, die OpenClaw sonst im Prompt bewerben würde.
+Skill-Env-/API-Schlüssel-Overrides werden weiterhin von OpenClaw auf die
+Kindprozessumgebung für den Lauf angewendet.
-Claude CLI hat außerdem einen eigenen nicht interaktiven Berechtigungsmodus. OpenClaw bildet diesen
-auf die vorhandene Exec-Richtlinie ab, statt Claude-spezifische Konfiguration hinzuzufügen: Wenn die
-effektiv angeforderte Exec-Richtlinie YOLO ist (`tools.exec.security: "full"` und
+Claude CLI verfügt außerdem über einen eigenen nicht interaktiven Berechtigungsmodus. OpenClaw bildet diesen
+auf die bestehende Exec-Policy ab, statt Claude-spezifische Konfiguration hinzuzufügen: Wenn die
+effektiv angeforderte Exec-Policy YOLO ist (`tools.exec.security: "full"` und
`tools.exec.ask: "off"`), fügt OpenClaw `--permission-mode bypassPermissions` hinzu.
-Agentenspezifische Einstellungen unter `agents.list[].tools.exec` überschreiben globale `tools.exec` für
-diesen Agenten. Um einen anderen Claude-Modus zu erzwingen, legen Sie explizite rohe Backend-Argumente
+Agent-spezifische Einstellungen unter `agents.list[].tools.exec` überschreiben globale `tools.exec`-Einstellungen für
+diesen Agent. Um einen anderen Claude-Modus zu erzwingen, setzen Sie explizite rohe Backend-Argumente
wie `--permission-mode default` oder `--permission-mode acceptEdits` unter
-`agents.defaults.cliBackends.claude-cli.args` und entsprechende `resumeArgs` fest.
+`agents.defaults.cliBackends.claude-cli.args` sowie passende `resumeArgs`.
-Bevor OpenClaw das gebündelte `claude-cli`-Backend verwenden kann, muss Claude Code selbst
+Das gebündelte Anthropic-Backend `claude-cli` bildet außerdem OpenClaw-`/think`-Stufen
+auf das native `--effort`-Flag von Claude Code für nicht deaktivierte Stufen ab. `minimal` und
+`low` werden auf `low` abgebildet, `adaptive` und `medium` auf `medium`, und `high`,
+`xhigh` sowie `max` direkt. Andere CLI-Backends benötigen ihr zugehöriges Plugin, um
+einen äquivalenten argv-Mapper zu deklarieren, bevor `/think` die gestartete CLI beeinflussen kann.
+
+Bevor OpenClaw das gebündelte Backend `claude-cli` verwenden kann, muss Claude Code selbst
bereits auf demselben Host angemeldet sein:
```bash
@@ -194,8 +200,8 @@ claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default
```
-Verwenden Sie `agents.defaults.cliBackends.claude-cli.command` nur, wenn das `claude`-
-Binary nicht bereits in `PATH` vorhanden ist.
+Verwenden Sie `agents.defaults.cliBackends.claude-cli.command` nur, wenn das `claude`-Binary
+nicht bereits auf `PATH` liegt.
## Sitzungen
@@ -205,54 +211,53 @@ Binary nicht bereits in `PATH` vorhanden ist.
`resumeArgs` (ersetzt `args` beim Fortsetzen) und optional `resumeOutput`
(für Nicht-JSON-Fortsetzungen).
- `sessionMode`:
- - `always`: immer eine Sitzungs-ID senden (neue UUID, wenn keine gespeichert ist).
- - `existing`: nur dann eine Sitzungs-ID senden, wenn zuvor eine gespeichert wurde.
- - `none`: niemals eine Sitzungs-ID senden.
+ - `always`: Immer eine Sitzungs-ID senden (neue UUID, falls keine gespeichert ist).
+ - `existing`: Nur dann eine Sitzungs-ID senden, wenn zuvor eine gespeichert wurde.
+ - `none`: Nie eine Sitzungs-ID senden.
- `claude-cli` verwendet standardmäßig `liveSession: "claude-stdio"`, `output: "jsonl"`
- und `input: "stdin"`, damit Folge-Turns den laufenden Claude-Prozess wiederverwenden,
- solange er aktiv ist. Warmes stdio ist jetzt der Standard, auch für benutzerdefinierte Konfigurationen,
+ und `input: "stdin"`, sodass Folge-Turns den laufenden Claude-Prozess wiederverwenden, solange
+ er aktiv ist. Warmes stdio ist jetzt der Standard, auch für benutzerdefinierte Konfigurationen,
die Transportfelder auslassen. Wenn das Gateway neu startet oder der inaktive Prozess
- beendet wird, setzt OpenClaw anhand der gespeicherten Claude-Sitzungs-ID fort. Gespeicherte Sitzungs-
+ beendet wird, setzt OpenClaw von der gespeicherten Claude-Sitzungs-ID fort. Gespeicherte Sitzungs-
IDs werden vor dem Fortsetzen gegen ein vorhandenes lesbares Projekttranskript geprüft,
- sodass Phantom-Bindungen mit `reason=transcript-missing` bereinigt werden,
- statt stillschweigend eine neue Claude-CLI-Sitzung unter `--resume` zu starten.
+ sodass Phantom-Bindungen mit `reason=transcript-missing` gelöscht werden, statt stillschweigend
+ eine neue Claude-CLI-Sitzung unter `--resume` zu starten.
- Claude-Live-Sitzungen behalten begrenzte JSONL-Ausgabeschutzmechanismen bei. Standardwerte erlauben bis zu
8 MiB und 20.000 rohe JSONL-Zeilen pro Turn. Tool-intensive Claude-Turns können
- diese pro Backend mit
+ diese pro Backend erhöhen mit
`agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars`
- und `maxTurnLines` erhöhen; OpenClaw begrenzt diese Einstellungen auf 64 MiB und 100.000
+ und `maxTurnLines`; OpenClaw begrenzt diese Einstellungen auf 64 MiB und 100.000
Zeilen.
-- Gespeicherte CLI-Sitzungen sind Provider-eigene Kontinuität. Der implizite tägliche Sitzungs-
- Reset trennt sie nicht; `/reset` und explizite `session.reset`-Richtlinien tun dies weiterhin.
+- Gespeicherte CLI-Sitzungen sind Provider-eigene Kontinuität. Das implizite tägliche Sitzungs-
+ Zurücksetzen unterbricht sie nicht; `/reset` und explizite `session.reset`-Policies tun dies weiterhin.
-Serialisierungshinweise:
+Hinweise zur Serialisierung:
-- `serialize: true` hält Läufe derselben Lane geordnet.
+- `serialize: true` hält Läufe auf derselben Lane geordnet.
- Die meisten CLIs serialisieren auf einer Provider-Lane.
-- OpenClaw verwirft die Wiederverwendung gespeicherter CLI-Sitzungen, wenn sich die ausgewählte Authentifizierungsidentität ändert,
- einschließlich einer geänderten Auth-Profil-ID, eines statischen API-Schlüssels, eines statischen Tokens oder einer OAuth-
- Kontoidentität, wenn die CLI eine offenlegt. OAuth-Zugriffs- und Refresh-Token-
- Rotation trennt die gespeicherte CLI-Sitzung nicht. Wenn eine CLI keine
- stabile OAuth-Konto-ID offenlegt, lässt OpenClaw diese CLI die Resume-Berechtigungen durchsetzen.
+- OpenClaw verwirft die Wiederverwendung gespeicherter CLI-Sitzungen, wenn sich die ausgewählte Auth-Identität ändert,
+ einschließlich einer geänderten Auth-Profil-ID, eines statischen API-Schlüssels, statischen Tokens oder einer OAuth-
+ Kontoidentität, sofern die CLI eine offenlegt. Die Rotation von OAuth-Zugriffs- und Refresh-Tokens
+ unterbricht die gespeicherte CLI-Sitzung nicht. Wenn eine CLI keine
+ stabile OAuth-Konto-ID offenlegt, lässt OpenClaw diese CLI die Fortsetzungsberechtigungen durchsetzen.
## Fallback-Präludium aus claude-cli-Sitzungen
Wenn ein `claude-cli`-Versuch auf einen Nicht-CLI-Kandidaten in
-[`agents.defaults.model.fallbacks`](/de/concepts/model-failover) ausweicht, seedet OpenClaw
-den nächsten Versuch mit einem Kontext-Präludium, das aus dem lokalen
-JSONL-Transkript von Claude Code unter `~/.claude/projects/` gewonnen wurde. Ohne diesen Seed würde der Fallback-
-Provider kalt starten, weil OpenClaws eigenes Sitzungstranskript für
-`claude-cli`-Läufe leer ist.
+[`agents.defaults.model.fallbacks`](/de/concepts/model-failover) failovert, versieht OpenClaw
+den nächsten Versuch mit einem Kontext-Präludium, das aus dem lokalen JSONL-Transkript von Claude Code unter
+`~/.claude/projects/` gewonnen wird. Ohne diesen Seed würde der Fallback-
+Provider kalt starten, da OpenClaws eigenes Sitzungstranskript für `claude-cli`-Läufe leer ist.
-- Das Präludium bevorzugt die neueste `/compact`-Zusammenfassung oder den `compact_boundary`-
- Marker und hängt dann die jüngsten Post-Boundary-Turns bis zu einem Zeichen-
- Budget an. Pre-Boundary-Turns werden verworfen, weil die Zusammenfassung sie bereits repräsentiert.
+- Das Präludium bevorzugt die neueste `/compact`-Zusammenfassung oder den Marker `compact_boundary`
+ und hängt dann die neuesten Turns nach der Boundary bis zu einem Zeichen-
+ Budget an. Turns vor der Boundary werden verworfen, da die Zusammenfassung sie bereits repräsentiert.
- Tool-Blöcke werden zu kompakten Hinweisen `(tool call: name)` und
- `(tool result: …)` zusammengeführt, um das Prompt-Budget realistisch zu halten. Die Zusammenfassung wird
- mit `(truncated)` gekennzeichnet, wenn sie überläuft.
+ `(tool result: …)` zusammengeführt, um das Prompt-Budget ehrlich zu halten. Die Zusammenfassung wird
+ als `(truncated)` gekennzeichnet, wenn sie überläuft.
- Same-Provider-Fallbacks von `claude-cli` zu `claude-cli` verlassen sich auf Claudes eigenes
`--resume` und überspringen das Präludium.
-- Der Seed verwendet die vorhandene Claude-Sitzungsdateipfad-Validierung wieder, sodass
+- Der Seed verwendet dieselbe Validierung des Claude-Sitzungsdateipfads erneut, sodass
beliebige Pfade nicht gelesen werden können.
## Bilder (Durchreichen)
@@ -271,11 +276,11 @@ aus einfachen Pfaden laden.
## Eingaben / Ausgaben
-- `output: "json"` (Standard) versucht, JSON zu parsen und Text plus Sitzungs-ID zu extrahieren.
-- Für Gemini-CLI-JSON-Ausgabe liest OpenClaw Antworttext aus `response` und
+- `output: "json"` (Standard) versucht, JSON zu parsen und Text sowie Sitzungs-ID zu extrahieren.
+- Für Gemini-CLI-JSON-Ausgaben liest OpenClaw Antworttext aus `response` und
Nutzung aus `stats`, wenn `usage` fehlt oder leer ist.
-- `output: "jsonl"` parst JSONL-Streams (zum Beispiel Codex CLI `--json`) und extrahiert die finale Agentennachricht plus Sitzungs-
- IDs, sofern vorhanden.
+- `output: "jsonl"` parst JSONL-Streams (zum Beispiel Codex CLI `--json`) und extrahiert die finale Agent-Nachricht sowie Sitzungs-
+ Identifikatoren, sofern vorhanden.
- `output: "text"` behandelt stdout als finale Antwort.
Eingabemodi:
@@ -309,18 +314,18 @@ Das gebündelte Google-Plugin registriert außerdem einen Standard für `google-
- `sessionIdFields: ["session_id", "sessionId"]`
Voraussetzung: Die lokale Gemini CLI muss installiert und als
-`gemini` in `PATH` verfügbar sein (`brew install gemini-cli` oder
+`gemini` auf `PATH` verfügbar sein (`brew install gemini-cli` oder
`npm install -g @google/gemini-cli`).
Gemini-CLI-JSON-Hinweise:
- Antworttext wird aus dem JSON-Feld `response` gelesen.
-- Nutzung fällt auf `stats` zurück, wenn `usage` fehlt oder leer ist.
+- Die Nutzung fällt auf `stats` zurück, wenn `usage` fehlt oder leer ist.
- `stats.cached` wird in OpenClaw `cacheRead` normalisiert.
-- Wenn `stats.input` fehlt, leitet OpenClaw Eingabetokens aus
+- Wenn `stats.input` fehlt, leitet OpenClaw Eingabe-Token aus
`stats.input_tokens - stats.cached` ab.
-Nur bei Bedarf überschreiben (häufig: absoluter `command`-Pfad).
+Überschreiben Sie dies nur bei Bedarf (häufig: absoluter `command`-Pfad).
## Plugin-eigene Standardwerte
@@ -328,9 +333,9 @@ CLI-Backend-Standardwerte sind jetzt Teil der Plugin-Oberfläche:
- Plugins registrieren sie mit `api.registerCliBackend(...)`.
- Die Backend-`id` wird zum Provider-Präfix in Modellreferenzen.
-- Die Benutzerkonfiguration in `agents.defaults.cliBackends.` überschreibt weiterhin den Plugin-Standard.
+- Benutzerkonfiguration in `agents.defaults.cliBackends.` überschreibt weiterhin den Plugin-Standardwert.
- Backend-spezifische Konfigurationsbereinigung bleibt über den optionalen
- `normalizeConfig`-Hook im Besitz des Plugins.
+ `normalizeConfig`-Hook Plugin-eigen.
Plugins, die kleine Kompatibilitäts-Shims für Prompts/Nachrichten benötigen, können
bidirektionale Texttransformationen deklarieren, ohne einen Provider oder ein CLI-Backend zu ersetzen:
@@ -350,54 +355,54 @@ api.registerTextTransforms({
});
```
-`input` schreibt den System-Prompt und den an die CLI übergebenen Benutzer-Prompt um. `output`
+`input` schreibt den System-Prompt und den Benutzer-Prompt um, die an die CLI übergeben werden. `output`
schreibt gestreamte Assistant-Deltas und geparsten finalen Text um, bevor OpenClaw
-seine eigenen Kontrollmarker und die Kanalzustellung verarbeitet.
+seine eigenen Steuerungsmarker und die Kanalzustellung verarbeitet.
Für CLIs, die mit Claude Code stream-json kompatibles JSONL ausgeben, setzen Sie
`jsonlDialect: "claude-stream-json"` in der Konfiguration dieses Backends.
-## Bundle-MCP-Overlays
+## Gebündelte MCP-Overlays
-CLI-Backends erhalten OpenClaw-Tool-Aufrufe **nicht** direkt, aber ein Backend kann
-mit `bundleMcp: true` ein generiertes MCP-Konfigurations-Overlay aktivieren.
+CLI-Backends erhalten **keine** OpenClaw-Toolaufrufe direkt, aber ein Backend kann
+sich mit `bundleMcp: true` für ein generiertes MCP-Konfigurations-Overlay entscheiden.
Aktuelles gebündeltes Verhalten:
- `claude-cli`: generierte strikte MCP-Konfigurationsdatei
- `codex-cli`: Inline-Konfigurationsüberschreibungen für `mcp_servers`; der generierte
OpenClaw-loopback-Server wird mit Codex' Tool-Genehmigungsmodus pro Server markiert,
- sodass MCP-Aufrufe nicht durch lokale Genehmigungsaufforderungen blockiert werden können
+ sodass MCP-Aufrufe nicht durch lokale Genehmigungsaufforderungen blockieren können
- `google-gemini-cli`: generierte Gemini-Systemeinstellungsdatei
-Wenn Bundle MCP aktiviert ist, führt OpenClaw Folgendes aus:
+Wenn gebündeltes MCP aktiviert ist, führt OpenClaw Folgendes aus:
-- startet einen loopback-HTTP-MCP-Server, der Gateway-Tools für den CLI-Prozess verfügbar macht
+- startet einen loopback-HTTP-MCP-Server, der Gateway-Tools für den CLI-Prozess bereitstellt
- authentifiziert die Bridge mit einem Token pro Sitzung (`OPENCLAW_MCP_TOKEN`)
-- beschränkt den Tool-Zugriff auf die aktuelle Sitzung sowie den Konto- und Kanalkontext
-- lädt aktivierte Bundle-MCP-Server für den aktuellen Workspace
-- führt sie mit vorhandenen MCP-Konfigurations-/Einstellungsstrukturen des Backends zusammen
-- schreibt die Startkonfiguration mit dem Backend-eigenen Integrationsmodus aus der besitzenden Erweiterung um
+- beschränkt Tool-Zugriff auf den aktuellen Sitzungs-, Konto- und Kanalkontext
+- lädt aktivierte Bundle-MCP-Server für den aktuellen Arbeitsbereich
+- führt sie mit jeder vorhandenen MCP-Konfigurations-/Einstellungsstruktur des Backends zusammen
+- schreibt die Startkonfiguration mithilfe des Backend-eigenen Integrationsmodus aus der besitzenden Erweiterung um
-Wenn keine MCP-Server aktiviert sind, injiziert OpenClaw dennoch eine strikte Konfiguration, wenn ein
-Backend Bundle MCP aktiviert, damit Hintergrundläufe isoliert bleiben.
+Wenn keine MCP-Server aktiviert sind, injiziert OpenClaw weiterhin eine strikte Konfiguration, wenn ein
+Backend gebündeltes MCP aktiviert, damit Hintergrundläufe isoliert bleiben.
-Sitzungsbezogene gebündelte MCP-Runtimes werden zur Wiederverwendung innerhalb einer Sitzung zwischengespeichert und anschließend
-nach `mcp.sessionIdleTtlMs` Millisekunden Leerlaufzeit bereinigt (Standard: 10
-Minuten; setzen Sie `0`, um dies zu deaktivieren). Einmalige eingebettete Läufe wie Auth-Probes,
-Slug-Generierung und Active-Memory-Abruf räumen am Ende des Laufs auf, damit stdio-
+Sitzungsgebundene gebündelte MCP-Runtimes werden zur Wiederverwendung innerhalb einer Sitzung zwischengespeichert und dann
+nach `mcp.sessionIdleTtlMs` Millisekunden Leerlaufzeit entfernt (Standard: 10
+Minuten; setzen Sie `0`, um dies zu deaktivieren). Einmalige eingebettete Läufe wie Auth-Prüfungen,
+Slug-Generierung und Active-Memory-Abruf fordern beim Laufende eine Bereinigung an, damit stdio-
Kindprozesse und Streamable-HTTP/SSE-Streams den Lauf nicht überdauern.
## Einschränkungen
-- **Keine direkten OpenClaw-Tool-Aufrufe.** OpenClaw injiziert keine Tool-Aufrufe in
+- **Keine direkten OpenClaw-Toolaufrufe.** OpenClaw injiziert keine Toolaufrufe in
das CLI-Backend-Protokoll. Backends sehen Gateway-Tools nur, wenn sie
`bundleMcp: true` aktivieren.
- **Streaming ist Backend-spezifisch.** Einige Backends streamen JSONL; andere puffern
bis zum Beenden.
- **Strukturierte Ausgaben** hängen vom JSON-Format der CLI ab.
- **Codex-CLI-Sitzungen** werden über Textausgabe fortgesetzt (kein JSONL), was weniger
- strukturiert ist als der anfängliche `--json`-Lauf. OpenClaw-Sitzungen funktionieren weiterhin
+ strukturiert ist als der anfängliche `--json`-Lauf. OpenClaw-Sitzungen funktionieren dennoch
normal.
## Fehlerbehebung
@@ -405,10 +410,10 @@ Kindprozesse und Streamable-HTTP/SSE-Streams den Lauf nicht überdauern.
- **CLI nicht gefunden**: Setzen Sie `command` auf einen vollständigen Pfad.
- **Falscher Modellname**: Verwenden Sie `modelAliases`, um `provider/model` → CLI-Modell zuzuordnen.
- **Keine Sitzungskontinuität**: Stellen Sie sicher, dass `sessionArg` gesetzt ist und `sessionMode` nicht
- `none` ist (Codex CLI kann derzeit nicht mit JSON-Ausgabe fortsetzen).
-- **Bilder werden ignoriert**: Setzen Sie `imageArg` (und verifizieren Sie, dass die CLI Dateipfade unterstützt).
+ `none` ist (Codex CLI kann derzeit nicht mit JSON-Ausgabe fortgesetzt werden).
+- **Bilder ignoriert**: Setzen Sie `imageArg` (und prüfen Sie, ob die CLI Dateipfade unterstützt).
-## Verwandte Themen
+## Verwandt
- [Gateway-Runbook](/de/gateway)
- [Lokale Modelle](/de/gateway/local-models)
diff --git a/docs/de/help/testing-live.md b/docs/de/help/testing-live.md
index e1f96f568..a79d02f5e 100644
--- a/docs/de/help/testing-live.md
+++ b/docs/de/help/testing-live.md
@@ -1,29 +1,29 @@
---
read_when:
- - Live-Modellmatrix-/CLI-Backend-/ACP-/Medien-Provider-Smoke-Tests ausführen
- - Fehlerbehebung bei der Auflösung von Live-Test-Anmeldeinformationen
- - Einen neuen Provider-spezifischen Live-Test hinzufügen
+ - Ausführen von Smoke-Tests für Live-Modellmatrix / CLI-Backend / ACP / Medien-Provider
+ - Fehlerbehebung bei der Anmeldedatenauflösung für Live-Tests
+ - Hinzufügen eines neuen Provider-spezifischen Live-Tests
sidebarTitle: Live tests
-summary: 'Live-Tests (mit Netzwerkzugriff): Modellmatrix, CLI-Backends, ACP, Medien-Provider, Zugangsdaten'
-title: 'Tests: Live-Suiten'
+summary: 'Live-Tests (mit Netzwerkzugriff): Modellmatrix, CLI-Backends, ACP, Medien-Provider, Anmeldedaten'
+title: 'Tests: Live-Test-Suites'
x-i18n:
- generated_at: "2026-05-03T06:38:45Z"
+ generated_at: "2026-05-04T18:23:47Z"
model: gpt-5.5
provider: openai
- source_hash: 4057d8875fa3404108e89e4381c1dd14e96abbc2af13c4934fc6c0dbf878fc00
+ source_hash: 03b8ca6348137a55c8d5f67c9c166a130a75a744f6a433cb00496756b29d7016
source_path: help/testing-live.md
workflow: 16
---
-Für Schnellstart, QA-Runner, Unit-/Integration-Suites und Docker-Flows siehe
-[Testing](/de/help/testing). Diese Seite behandelt die **Live**-Testsuites (mit
-Netzwerkzugriff): Model-Matrix, CLI-Backends, ACP und Live-Tests für
-Medien-Provider sowie den Umgang mit Zugangsdaten.
+Für Schnellstart, QA-Runner, Unit-/Integrations-Suites und Docker-Abläufe siehe
+[Testing](/de/help/testing). Diese Seite behandelt die **Live**-Testsuites
+(mit Netzwerkzugriff): Modellmatrix, CLI-Backends, ACP und Live-Tests für
+Medien-Provider sowie die Verarbeitung von Zugangsdaten.
-## Live: lokale Smoke-Befehle für Profile
+## Live: Smoke-Befehle für lokales Profil
-Laden Sie vor Ad-hoc-Live-Prüfungen `~/.profile`, damit Provider-Schlüssel und
-lokale Tool-Pfade mit Ihrer Shell übereinstimmen:
+Sourcen Sie `~/.profile` vor Ad-hoc-Live-Prüfungen, damit Provider-Schlüssel und
+lokale Tool-Pfade zu Ihrer Shell passen:
```bash
source ~/.profile
@@ -37,105 +37,106 @@ pnpm openclaw infer tts convert --local --json \
--output /tmp/openclaw-live-smoke.mp3
```
-Sicherer Readiness-Smoke-Test für Sprachanrufe:
+Sicherer Smoke-Test für Voice-Call-Bereitschaft:
```bash
pnpm openclaw voicecall setup --json
pnpm openclaw voicecall smoke --to "+15555550123"
```
-`voicecall smoke` ist ein Dry Run, sofern `--yes` nicht ebenfalls gesetzt ist. Verwenden Sie `--yes` nur,
-wenn Sie absichtlich einen echten Benachrichtigungsanruf auslösen möchten. Für Twilio, Telnyx und
-Plivo erfordert eine erfolgreiche Readiness-Prüfung eine öffentliche Webhook-URL; rein lokale
-loopback/private Fallbacks werden bewusst abgelehnt.
+`voicecall smoke` ist ein Dry Run, sofern nicht zusätzlich `--yes` angegeben ist.
+Verwenden Sie `--yes` nur, wenn Sie bewusst einen echten Benachrichtigungsanruf
+auslösen möchten. Für Twilio, Telnyx und Plivo erfordert eine erfolgreiche
+Bereitschaftsprüfung eine öffentliche Webhook-URL; ausschließlich lokale
+loopback/private Fallbacks werden absichtlich abgelehnt.
## Live: Capability-Sweep für Android-Node
- Test: `src/gateway/android-node.capabilities.live.test.ts`
- Skript: `pnpm android:test:integration`
-- Ziel: **jeden aktuell angekündigten Befehl** eines verbundenen Android-Node ausführen und das Befehlsvertragsverhalten prüfen.
+- Ziel: **jeden aktuell beworbenen Befehl** eines verbundenen Android-Nodes aufrufen und das Verhalten des Befehlsvertrags prüfen.
- Umfang:
- - Vorbedingtes/manuelles Setup (die Suite installiert/startet/paart die App nicht).
- - Gateway-Validierung von `node.invoke` Befehl für Befehl für den ausgewählten Android-Node.
-- Erforderliches Vorab-Setup:
+ - Vorbereitete/manuelle Einrichtung (die Suite installiert, startet oder koppelt die App nicht).
+ - Befehlsweise Gateway-Validierung per `node.invoke` für den ausgewählten Android-Node.
+- Erforderliche Vorab-Einrichtung:
- Android-App ist bereits verbunden und mit dem Gateway gekoppelt.
- App bleibt im Vordergrund.
- - Berechtigungen/Erfassungseinwilligung sind für die Fähigkeiten erteilt, von denen Sie erwarten, dass sie bestehen.
+ - Berechtigungen/Erfassungseinwilligung sind für die Capabilities erteilt, die erfolgreich sein sollen.
- Optionale Ziel-Overrides:
- `OPENCLAW_ANDROID_NODE_ID` oder `OPENCLAW_ANDROID_NODE_NAME`.
- `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`.
-- Vollständige Details zum Android-Setup: [Android App](/de/platforms/android)
+- Vollständige Android-Einrichtungsdetails: [Android-App](/de/platforms/android)
-## Live: Model-Smoke-Test (Profilschlüssel)
+## Live: Modell-Smoke-Test (Profilschlüssel)
Live-Tests sind in zwei Ebenen aufgeteilt, damit wir Fehler isolieren können:
-- „Direktes Model“ sagt uns, ob der Provider/das Model mit dem angegebenen Schlüssel überhaupt antworten kann.
-- „Gateway-Smoke-Test“ sagt uns, ob die vollständige Gateway+Agent-Pipeline für dieses Model funktioniert (Sitzungen, Verlauf, Tools, Sandbox-Richtlinie usw.).
+- „Direktmodell“ zeigt uns, ob der Provider/das Modell mit dem angegebenen Schlüssel überhaupt antworten kann.
+- „Gateway-Smoke-Test“ zeigt uns, ob die vollständige Gateway+Agent-Pipeline für dieses Modell funktioniert (Sessions, Verlauf, Tools, Sandbox-Richtlinie usw.).
-### Ebene 1: Direkter Model-Completion-Test (kein Gateway)
+### Ebene 1: Direkte Modellvervollständigung (kein Gateway)
- Test: `src/agents/models.profiles.live.test.ts`
- Ziel:
- - Erkannte Models enumerieren
- - Mit `getApiKeyForModel` Models auswählen, für die Sie Zugangsdaten haben
- - Pro Model eine kleine Completion ausführen (und bei Bedarf gezielte Regressionstests)
+ - Erkannte Modelle aufzählen
+ - Mit `getApiKeyForModel` Modelle auswählen, für die Sie Zugangsdaten haben
+ - Eine kleine Vervollständigung pro Modell ausführen (und gezielte Regressionen, wo nötig)
- Aktivierung:
- `pnpm test:live` (oder `OPENCLAW_LIVE_TEST=1`, wenn Vitest direkt aufgerufen wird)
-- Setzen Sie `OPENCLAW_LIVE_MODELS=modern` (oder `all`, Alias für modern), um diese Suite tatsächlich auszuführen; andernfalls wird sie übersprungen, damit `pnpm test:live` auf Gateway-Smoke-Tests fokussiert bleibt
-- Models auswählen:
+- Setzen Sie `OPENCLAW_LIVE_MODELS=modern` (oder `all`, Alias für modern), um diese Suite tatsächlich auszuführen; andernfalls wird sie übersprungen, damit `pnpm test:live` auf den Gateway-Smoke-Test fokussiert bleibt
+- Modellauswahl:
- `OPENCLAW_LIVE_MODELS=modern`, um die moderne Allowlist auszuführen (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4.3)
- `OPENCLAW_LIVE_MODELS=all` ist ein Alias für die moderne Allowlist
- oder `OPENCLAW_LIVE_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,..."` (kommagetrennte Allowlist)
- - Modern/all-Sweeps verwenden standardmäßig ein kuratiertes High-Signal-Limit; setzen Sie `OPENCLAW_LIVE_MAX_MODELS=0` für einen vollständigen modernen Sweep oder eine positive Zahl für ein kleineres Limit.
- - Vollständige Sweeps verwenden `OPENCLAW_LIVE_TEST_TIMEOUT_MS` für das gesamte Timeout des direkten Model-Tests. Standard: 60 Minuten.
- - Direct-Model-Probes laufen standardmäßig mit 20-facher Parallelität; setzen Sie `OPENCLAW_LIVE_MODEL_CONCURRENCY`, um dies zu überschreiben.
-- Provider auswählen:
+ - Modern/all-Sweeps verwenden standardmäßig eine kuratierte, aussagekräftige Obergrenze; setzen Sie `OPENCLAW_LIVE_MAX_MODELS=0` für einen vollständigen modernen Sweep oder eine positive Zahl für eine kleinere Obergrenze.
+ - Vollständige Sweeps verwenden `OPENCLAW_LIVE_TEST_TIMEOUT_MS` als Timeout für den gesamten Direktmodell-Test. Standard: 60 Minuten.
+ - Direktmodell-Prüfungen laufen standardmäßig mit 20-facher Parallelität; setzen Sie `OPENCLAW_LIVE_MODEL_CONCURRENCY`, um dies zu überschreiben.
+- Provider-Auswahl:
- `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (kommagetrennte Allowlist)
-- Woher Schlüssel kommen:
+- Herkunft der Schlüssel:
- Standardmäßig: Profilspeicher und Env-Fallbacks
- Setzen Sie `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um ausschließlich den **Profilspeicher** zu erzwingen
-- Warum es das gibt:
+- Zweck:
- Trennt „Provider-API ist defekt / Schlüssel ist ungültig“ von „Gateway-Agent-Pipeline ist defekt“
- - Enthält kleine, isolierte Regressionstests (Beispiel: OpenAI Responses/Codex Responses Reasoning-Replay + Tool-Call-Flows)
+ - Enthält kleine, isolierte Regressionen (Beispiel: OpenAI Responses/Codex Responses Reasoning-Replay + Tool-Call-Abläufe)
### Ebene 2: Gateway + Dev-Agent-Smoke-Test (was „@openclaw“ tatsächlich tut)
- Test: `src/gateway/gateway-models.profiles.live.test.ts`
- Ziel:
- Ein In-Process-Gateway starten
- - Eine `agent:dev:*`-Sitzung erstellen/patchen (Model-Override pro Lauf)
- - Models mit Schlüsseln durchlaufen und prüfen:
+ - Eine `agent:dev:*`-Session erstellen/patchen (Modell-Override pro Lauf)
+ - Modelle mit Schlüsseln durchlaufen und prüfen:
- „aussagekräftige“ Antwort (keine Tools)
- - ein echter Tool-Aufruf funktioniert (Lese-Probe)
- - optionale zusätzliche Tool-Probes (exec+read-Probe)
+ - ein echter Tool-Aufruf funktioniert (`read`-Prüfung)
+ - optionale zusätzliche Tool-Prüfungen (`exec+read`-Prüfung)
- OpenAI-Regressionspfade (nur Tool-Call → Follow-up) funktionieren weiterhin
-- Probe-Details (damit Sie Fehler schnell erklären können):
- - `read`-Probe: Der Test schreibt eine Nonce-Datei in den Workspace und bittet den Agent, sie zu `read`en und die Nonce zurückzugeben.
- - `exec+read`-Probe: Der Test bittet den Agent, per `exec` eine Nonce in eine temporäre Datei zu schreiben und sie dann per `read` zurückzulesen.
- - Bild-Probe: Der Test hängt eine generierte PNG-Datei (cat + zufälliger Code) an und erwartet, dass das Model `cat ` zurückgibt.
+- Prüfungsdetails (damit Sie Fehler schnell erklären können):
+ - `read`-Prüfung: Der Test schreibt eine Nonce-Datei in den Workspace und bittet den Agent, sie per `read` zu lesen und die Nonce zurückzugeben.
+ - `exec+read`-Prüfung: Der Test bittet den Agent, per `exec` eine Nonce in eine temporäre Datei zu schreiben und sie anschließend per `read` zurückzulesen.
+ - Bildprüfung: Der Test hängt ein generiertes PNG an (Katze + zufälliger Code) und erwartet, dass das Modell `cat ` zurückgibt.
- Implementierungsreferenz: `src/gateway/gateway-models.profiles.live.test.ts` und `src/gateway/live-image-probe.ts`.
- Aktivierung:
- `pnpm test:live` (oder `OPENCLAW_LIVE_TEST=1`, wenn Vitest direkt aufgerufen wird)
-- Models auswählen:
+- Modellauswahl:
- Standard: moderne Allowlist (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4.3)
- `OPENCLAW_LIVE_GATEWAY_MODELS=all` ist ein Alias für die moderne Allowlist
- - Oder setzen Sie `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (oder eine kommagetrennte Liste), um einzugrenzen
- - Modern/all-Gateway-Sweeps verwenden standardmäßig ein kuratiertes High-Signal-Limit; setzen Sie `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` für einen vollständigen modernen Sweep oder eine positive Zahl für ein kleineres Limit.
-- Provider auswählen („OpenRouter alles“ vermeiden):
+ - Oder setzen Sie `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (oder eine kommagetrennte Liste), um einzuschränken
+ - Modern/all-Gateway-Sweeps verwenden standardmäßig eine kuratierte, aussagekräftige Obergrenze; setzen Sie `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` für einen vollständigen modernen Sweep oder eine positive Zahl für eine kleinere Obergrenze.
+- Provider-Auswahl („OpenRouter alles“ vermeiden):
- `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (kommagetrennte Allowlist)
-- Tool- und Bild-Probes sind in diesem Live-Test immer aktiv:
- - `read`-Probe + `exec+read`-Probe (Tool-Stress)
- - Bild-Probe läuft, wenn das Model Unterstützung für Bildeingaben ankündigt
- - Flow (übergeordnet):
- - Test erzeugt ein winziges PNG mit „CAT“ + zufälligem Code (`src/gateway/live-image-probe.ts`)
- - Sendet es per `agent` `attachments: [{ mimeType: "image/png", content: "" }]`
+- Tool- und Bildprüfungen sind in diesem Live-Test immer aktiviert:
+ - `read`-Prüfung + `exec+read`-Prüfung (Tool-Stresstest)
+ - Die Bildprüfung läuft, wenn das Modell Unterstützung für Bildeingaben bewirbt
+ - Ablauf (grob):
+ - Der Test generiert ein kleines PNG mit „CAT“ + zufälligem Code (`src/gateway/live-image-probe.ts`)
+ - Sendet es über `agent` `attachments: [{ mimeType: "image/png", content: "" }]`
- Gateway parst Anhänge in `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`)
- - Eingebetteter Agent leitet eine multimodale Benutzer-Nachricht an das Model weiter
+ - Eingebetteter Agent leitet eine multimodale Nutzernachricht an das Modell weiter
- Assertion: Antwort enthält `cat` + den Code (OCR-Toleranz: kleinere Fehler erlaubt)
-Um zu sehen, was Sie auf Ihrer Maschine testen können (und die genauen `provider/model`-IDs), führen Sie aus:
+Um zu sehen, was Sie auf Ihrem Rechner testen können (und die genauen `provider/model`-IDs), führen Sie aus:
```bash
openclaw models list
@@ -147,24 +148,24 @@ openclaw models list --json
## Live: CLI-Backend-Smoke-Test (Claude, Codex, Gemini oder andere lokale CLIs)
- Test: `src/gateway/gateway-cli-backend.live.test.ts`
-- Ziel: die Gateway- und Agent-Pipeline mit einem lokalen CLI-Backend validieren, ohne Ihre Standardkonfiguration zu berühren.
-- Backend-spezifische Smoke-Defaults liegen in der `cli-backend.ts`-Definition des besitzenden Plugins.
+- Ziel: die Gateway+Agent-Pipeline mit einem lokalen CLI-Backend validieren, ohne Ihre Standardkonfiguration zu berühren.
+- Backend-spezifische Smoke-Standards liegen in der `cli-backend.ts`-Definition des besitzenden Plugins.
- Aktivieren:
- `pnpm test:live` (oder `OPENCLAW_LIVE_TEST=1`, wenn Vitest direkt aufgerufen wird)
- `OPENCLAW_LIVE_CLI_BACKEND=1`
-- Defaults:
- - Standard-Provider/-Model: `claude-cli/claude-sonnet-4-6`
+- Standards:
+ - Standard-Provider/-Modell: `claude-cli/claude-sonnet-4-6`
- Befehls-/Argument-/Bildverhalten stammt aus den Metadaten des besitzenden CLI-Backend-Plugins.
- Overrides (optional):
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.5"`
- `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"`
- `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'`
- - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, um einen echten Bildanhang zu senden (Pfade werden in den Prompt injiziert). Docker-Rezepte deaktivieren dies standardmäßig, sofern es nicht explizit angefordert wird.
+ - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, um einen echten Bildanhang zu senden (Pfade werden in den Prompt injiziert). Docker-Rezepte deaktivieren dies standardmäßig, sofern es nicht ausdrücklich angefordert wird.
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, um Bilddateipfade als CLI-Argumente statt per Prompt-Injektion zu übergeben.
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (oder `"list"`), um zu steuern, wie Bildargumente übergeben werden, wenn `IMAGE_ARG` gesetzt ist.
- - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, um einen zweiten Turn zu senden und den Resume-Flow zu validieren.
- - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=1`, um sich für die Claude Sonnet -> Opus Same-Session-Continuity-Probe zu entscheiden, wenn das ausgewählte Model ein Switch-Ziel unterstützt. Docker-Rezepte deaktivieren dies standardmäßig zugunsten der Aggregatzuverlässigkeit.
- - `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1`, um sich für die MCP/Tool-loopback-Probe zu entscheiden. Docker-Rezepte deaktivieren dies standardmäßig, sofern es nicht explizit angefordert wird.
+ - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, um eine zweite Runde zu senden und den Resume-Ablauf zu validieren.
+ - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=1`, um die Kontinuitätsprüfung Claude Sonnet -> Opus in derselben Session zu aktivieren, wenn das ausgewählte Modell ein Wechselziel unterstützt. Docker-Rezepte deaktivieren dies standardmäßig zugunsten der aggregierten Zuverlässigkeit.
+ - `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1`, um die MCP/Tool-loopback-Prüfung zu aktivieren. Docker-Rezepte deaktivieren dies standardmäßig, sofern es nicht ausdrücklich angefordert wird.
Beispiel:
@@ -181,10 +182,11 @@ OPENCLAW_LIVE_TEST=1 \
pnpm test:live src/agents/cli-runner/bundle-mcp.gemini.live.test.ts
```
-Dies fordert Gemini nicht auf, eine Antwort zu generieren. Es schreibt dieselben Systemeinstellungen,
-die OpenClaw an Gemini übergibt, und führt dann `gemini --debug mcp list` aus, um nachzuweisen, dass ein
-gespeicherter `transport: "streamable-http"`-Server in Geminis HTTP-MCP-Form normalisiert wird
-und sich mit einem lokalen streamable-HTTP-MCP-Server verbinden kann.
+Dabei wird Gemini nicht aufgefordert, eine Antwort zu generieren. Es schreibt
+dieselben Systemeinstellungen, die OpenClaw Gemini gibt, und führt dann
+`gemini --debug mcp list` aus, um nachzuweisen, dass ein gespeicherter Server mit
+`transport: "streamable-http"` in Geminis HTTP-MCP-Format normalisiert wird und
+sich mit einem lokalen streamable-HTTP-MCP-Server verbinden kann.
Docker-Rezept:
@@ -203,28 +205,37 @@ pnpm test:docker:live-cli-backend:gemini
Hinweise:
-- Der Docker-Runner liegt unter `scripts/test-live-cli-backend-docker.sh`.
-- Er führt den Live-CLI-Backend-Smoke-Test innerhalb des Repo-Docker-Images als nicht-root-`node`-Benutzer aus.
-- Er löst CLI-Smoke-Metadaten aus dem besitzenden Plugin auf und installiert dann das passende Linux-CLI-Paket (`@anthropic-ai/claude-code`, `@openai/codex` oder `@google/gemini-cli`) in ein zwischengespeichertes beschreibbares Präfix unter `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (Standard: `~/.cache/openclaw/docker-cli-tools`).
-- `pnpm test:docker:live-cli-backend:claude-subscription` erfordert portables Claude-Code-Subscription-OAuth entweder über `~/.claude/.credentials.json` mit `claudeAiOauth.subscriptionType` oder `CLAUDE_CODE_OAUTH_TOKEN` aus `claude setup-token`. Es weist zuerst direktes `claude -p` in Docker nach und führt dann zwei Gateway-CLI-Backend-Turns aus, ohne Anthropic-API-Key-Env-Vars beizubehalten. Diese Subscription-Lane deaktiviert die Claude-MCP/Tool- und Bild-Probes standardmäßig, weil Claude die Nutzung durch Drittanbieter-Apps derzeit über Extra-Usage-Billing statt über normale Subscription-Plan-Limits routet.
-- Der Live-CLI-Backend-Smoke-Test übt jetzt denselben End-to-End-Flow für Claude, Codex und Gemini aus: Text-Turn, Bildklassifizierungs-Turn und dann MCP-`cron`-Tool-Aufruf, verifiziert über die Gateway-CLI.
-- Claudes Standard-Smoke-Test patcht außerdem die Sitzung von Sonnet auf Opus und verifiziert, dass sich die wiederaufgenommene Sitzung weiterhin an eine frühere Notiz erinnert.
+- Der Docker-Runner befindet sich unter `scripts/test-live-cli-backend-docker.sh`.
+- Er führt den Live-CLI-Backend-Smoke-Test im Repo-Docker-Image als nicht-root-`node`-Benutzer aus.
+- Er löst CLI-Smoke-Metadaten aus dem besitzenden Plugin auf und installiert anschließend das passende Linux-CLI-Paket (`@anthropic-ai/claude-code`, `@openai/codex` oder `@google/gemini-cli`) in ein gecachtes beschreibbares Präfix unter `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (Standard: `~/.cache/openclaw/docker-cli-tools`).
+- `pnpm test:docker:live-cli-backend:claude-subscription` erfordert portables Claude Code Subscription OAuth entweder über `~/.claude/.credentials.json` mit `claudeAiOauth.subscriptionType` oder `CLAUDE_CODE_OAUTH_TOKEN` aus `claude setup-token`. Es weist zuerst direktes `claude -p` in Docker nach und führt dann zwei Gateway-CLI-Backend-Runden ohne Beibehaltung von Anthropic-API-Key-Env-Vars aus. Diese Subscription-Lane deaktiviert standardmäßig die Claude-MCP/Tool- und Bildprüfungen, weil Claude die Nutzung durch Drittanbieter-Apps derzeit über zusätzliche Nutzungsabrechnung statt über normale Subscription-Plan-Limits leitet.
+- Der Live-CLI-Backend-Smoke-Test übt jetzt denselben End-to-End-Ablauf für Claude, Codex und Gemini aus: Textrunde, Bildklassifizierungsrunde, dann MCP-`cron`-Tool-Aufruf, der über die Gateway-CLI verifiziert wird.
+- Claudes Standard-Smoke-Test patcht außerdem die Session von Sonnet auf Opus und prüft, ob sich die fortgesetzte Session weiterhin an eine frühere Notiz erinnert.
+
+## Live: Erreichbarkeit des APNs-HTTP/2-Proxys
+
+- Test: `src/infra/push-apns-http2.live.test.ts`
+- Ziel: über einen lokalen HTTP-CONNECT-Proxy einen Tunnel zum Apple-Sandbox-APNs-Endpunkt aufbauen, die APNs-HTTP/2-Validierungsanfrage senden und prüfen, dass Apples echte `403 InvalidProviderToken`-Antwort über den Proxy-Pfad zurückkommt.
+- Aktivieren:
+ - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_APNS_REACHABILITY=1 pnpm test:live src/infra/push-apns-http2.live.test.ts`
+- Optionales Timeout:
+ - `OPENCLAW_LIVE_APNS_TIMEOUT_MS=30000`
## Live: ACP-Bind-Smoke-Test (`/acp spawn ... --bind here`)
- Test: `src/gateway/gateway-acp-bind.live.test.ts`
-- Ziel: Validieren Sie den echten ACP-Conversation-Bind-Flow mit einem Live-ACP-Agenten:
+- Ziel: echten ACP-Conversation-Bind-Ablauf mit einem Live-ACP-Agent validieren:
- `/acp spawn --bind here` senden
- - eine synthetische Message-Channel-Unterhaltung an Ort und Stelle binden
- - eine normale Folgenachricht in derselben Unterhaltung senden
- - prüfen, dass die Folgenachricht im Transkript der gebundenen ACP-Sitzung landet
+ - eine synthetische Message-Channel-Konversation direkt binden
+ - eine normale Folgeanfrage in derselben Konversation senden
+ - prüfen, dass die Folgeanfrage im Transkript der gebundenen ACP-Sitzung landet
- Aktivieren:
- `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts`
- `OPENCLAW_LIVE_ACP_BIND=1`
- Standardwerte:
- - ACP-Agenten in Docker: `claude,codex,gemini`
+ - ACP-Agents in Docker: `claude,codex,gemini`
- ACP-Agent für direktes `pnpm test:live ...`: `claude`
- - Synthetischer Kanal: Unterhaltungskontext im Slack-DM-Stil
+ - Synthetischer Kanal: Slack-DM-artiger Konversationskontext
- ACP-Backend: `acpx`
- Überschreibungen:
- `OPENCLAW_LIVE_ACP_BIND_AGENT=claude`
@@ -240,9 +251,9 @@ Hinweise:
- `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1`
- `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.5`
- Hinweise:
- - Diese Lane verwendet die Gateway-Oberfläche `chat.send` mit synthetischen, nur für Administratoren vorgesehenen originating-route-Feldern, damit Tests Message-Channel-Kontext anhängen können, ohne eine externe Zustellung vorzutäuschen.
- - Wenn `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` nicht gesetzt ist, verwendet der Test die integrierte Agenten-Registry des eingebetteten `acpx`-Plugins für den ausgewählten ACP-Harness-Agenten.
- - Die MCP-Erstellung per Cron für gebundene Sitzungen erfolgt standardmäßig nach bestem Aufwand, weil externe ACP-Harnesses MCP-Aufrufe abbrechen können, nachdem der Bind-/Image-Nachweis bestanden wurde; setzen Sie `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1`, um diese Cron-Prüfung nach dem Bind strikt zu machen.
+ - Diese Lane verwendet die Gateway-Oberfläche `chat.send` mit ausschließlich Admin-zugelassenen synthetischen Feldern für die Ursprungsroute, damit Tests Message-Channel-Kontext anhängen können, ohne eine externe Zustellung vorzutäuschen.
+ - Wenn `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` nicht gesetzt ist, verwendet der Test die integrierte Agent-Registry des eingebetteten `acpx`-Plugins für den ausgewählten ACP-Harness-Agent.
+ - Die MCP-Erstellung per Cron für gebundene Sitzungen ist standardmäßig Best-Effort, weil externe ACP-Harnesses MCP-Aufrufe abbrechen können, nachdem der Bind-/Image-Nachweis bestanden wurde; setzen Sie `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1`, um diese Cron-Prüfung nach dem Binden strikt zu machen.
Beispiel:
@@ -258,7 +269,7 @@ Docker-Rezept:
pnpm test:docker:live-acp-bind
```
-Docker-Rezepte für einzelne Agenten:
+Docker-Rezepte für einzelne Agents:
```bash
pnpm test:docker:live-acp-bind:claude
@@ -270,38 +281,39 @@ pnpm test:docker:live-acp-bind:opencode
Docker-Hinweise:
-- Der Docker-Runner befindet sich unter `scripts/test-live-acp-bind-docker.sh`.
-- Standardmäßig führt er den ACP-Bind-Smoke nacheinander gegen die aggregierten Live-CLI-Agenten aus: `claude`, `codex`, dann `gemini`.
+- Der Docker-Runner liegt unter `scripts/test-live-acp-bind-docker.sh`.
+- Standardmäßig führt er den ACP-Bind-Smoke nacheinander gegen die aggregierten Live-CLI-Agents aus: `claude`, `codex`, dann `gemini`.
- Verwenden Sie `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=droid`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` oder `OPENCLAW_LIVE_ACP_BIND_AGENTS=opencode`, um die Matrix einzugrenzen.
-- Er lädt `~/.profile`, stellt das passende CLI-Authentifizierungsmaterial im Container bereit und installiert dann bei Bedarf die angeforderte Live-CLI (`@anthropic-ai/claude-code`, `@openai/codex`, Factory Droid über `https://app.factory.ai/cli`, `@google/gemini-cli` oder `opencode-ai`). Das ACP-Backend selbst ist das eingebettete Paket `acpx/runtime` aus dem offiziellen `acpx`-Plugin.
-- Die Droid-Docker-Variante stellt `~/.factory` für Einstellungen bereit, leitet `FACTORY_API_KEY` weiter und benötigt diesen API-Schlüssel, weil lokale Factory-OAuth-/Keyring-Authentifizierung nicht portabel in den Container ist. Sie verwendet den integrierten Registry-Eintrag `droid exec --output-format acp` von ACPX.
-- Die OpenCode-Docker-Variante ist eine strikte Einzel-Agent-Regressions-Lane. Sie schreibt nach dem Laden von `~/.profile` ein temporäres `OPENCODE_CONFIG_CONTENT`-Standardmodell aus `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL` (Standard `opencode/kimi-k2.6`), und `pnpm test:docker:live-acp-bind:opencode` verlangt ein gebundenes Assistententranskript, statt den generischen Skip nach dem Bind zu akzeptieren.
-- Direkte `acpx`-CLI-Aufrufe sind nur ein manueller Ausweichpfad, um Verhalten außerhalb des Gateway zu vergleichen. Der Docker-ACP-Bind-Smoke testet das eingebettete `acpx`-Runtime-Backend von OpenClaw.
+- Er liest `~/.profile`, stellt das passende CLI-Auth-Material im Container bereit und installiert anschließend die angeforderte Live-CLI (`@anthropic-ai/claude-code`, `@openai/codex`, Factory Droid über `https://app.factory.ai/cli`, `@google/gemini-cli` oder `opencode-ai`), falls sie fehlt. Das ACP-Backend selbst ist das eingebettete Paket `acpx/runtime` aus dem offiziellen `acpx`-Plugin.
+- Die Droid-Docker-Variante stellt `~/.factory` für Einstellungen bereit, leitet `FACTORY_API_KEY` weiter und benötigt diesen API-Schlüssel, weil lokale Factory-OAuth-/Keyring-Authentifizierung nicht portabel in den Container ist. Sie verwendet den integrierten ACPX-Registry-Eintrag `droid exec --output-format acp`.
+- Die OpenCode-Docker-Variante ist eine strikte Regressions-Lane für einen einzelnen Agent. Sie schreibt nach dem Einlesen von `~/.profile` ein temporäres Standardmodell für `OPENCODE_CONFIG_CONTENT` aus `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL` (Standard `opencode/kimi-k2.6`), und `pnpm test:docker:live-acp-bind:opencode` verlangt ein gebundenes Assistant-Transkript, statt den generischen Skip nach dem Binden zu akzeptieren.
+- Direkte `acpx`-CLI-Aufrufe sind nur ein manueller Workaround-Pfad zum Vergleichen des Verhaltens außerhalb des Gateway. Der Docker-ACP-Bind-Smoke testet das eingebettete `acpx`-Runtime-Backend von OpenClaw.
## Live: Codex-App-Server-Harness-Smoke
-- Ziel: Validieren Sie den Plugin-eigenen Codex-Harness über die normale Gateway-
- Methode `agent`:
+- Ziel: den Plugin-eigenen Codex-Harness über die normale Gateway-Methode
+ `agent` validieren:
- das gebündelte `codex`-Plugin laden
- `OPENCLAW_AGENT_RUNTIME=codex` auswählen
- - eine erste Gateway-Agent-Runde an `openai/gpt-5.5` senden, wobei der Codex-Harness erzwungen wird
- - eine zweite Runde an dieselbe OpenClaw-Sitzung senden und prüfen, dass der App-Server-
+ - einen ersten Gateway-Agent-Turn an `openai/gpt-5.5` senden, wobei der Codex-Harness erzwungen wird
+ - einen zweiten Turn an dieselbe OpenClaw-Sitzung senden und prüfen, dass der App-Server-
Thread fortgesetzt werden kann
- - `/codex status` und `/codex models` über denselben Gateway-Befehlspfad ausführen
- - optional zwei von Guardian geprüfte Shell-Proben mit erhöhten Rechten ausführen: einen harmlosen
+ - `/codex status` und `/codex models` über denselben Gateway-Befehlspfad
+ ausführen
+ - optional zwei von Guardian geprüfte Shell-Probes mit erhöhten Rechten ausführen: einen harmlosen
Befehl, der genehmigt werden sollte, und einen Fake-Secret-Upload, der
- abgelehnt werden sollte, sodass der Agent zurückfragt
+ abgelehnt werden sollte, sodass der Agent nachfragt
- Test: `src/gateway/gateway-codex-harness.live.test.ts`
- Aktivieren: `OPENCLAW_LIVE_CODEX_HARNESS=1`
- Standardmodell: `openai/gpt-5.5`
-- Optionale Image-Probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
-- Optionale MCP-/Tool-Probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
-- Optionale Guardian-Probe: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`
-- Der Smoke verwendet `agentRuntime.id: "codex"`, sodass ein defekter Codex-Harness
- nicht durch stilles Zurückfallen auf PI bestehen kann.
-- Authentifizierung: Codex-App-Server-Authentifizierung aus der lokalen Codex-Abonnementanmeldung. Docker-
- Smokes können außerdem `OPENAI_API_KEY` für Nicht-Codex-Proben bereitstellen, wenn zutreffend,
- sowie optional kopierte Dateien `~/.codex/auth.json` und `~/.codex/config.toml`.
+- Optionaler Image-Probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
+- Optionaler MCP-/Tool-Probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
+- Optionaler Guardian-Probe: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`
+- Der Smoke verwendet `agentRuntime.id: "codex"`, sodass ein defekter Codex-Harness nicht
+ durch stilles Zurückfallen auf PI bestehen kann.
+- Authentifizierung: Codex-App-Server-Authentifizierung aus dem lokalen Codex-Abonnement-Login. Docker-
+ Smokes können bei Bedarf auch `OPENAI_API_KEY` für Nicht-Codex-Probes bereitstellen,
+ plus optional kopierte `~/.codex/auth.json` und `~/.codex/config.toml`.
Lokales Rezept:
@@ -324,21 +336,21 @@ pnpm test:docker:live-codex-harness
Docker-Hinweise:
-- Der Docker-Runner befindet sich unter `scripts/test-live-codex-harness-docker.sh`.
-- Er lädt das gemountete `~/.profile`, übergibt `OPENAI_API_KEY`, kopiert vorhandene Codex-CLI-
- Authentifizierungsdateien, installiert `@openai/codex` in ein beschreibbares, gemountetes npm-
- Präfix, stellt den Quellbaum bereit und führt dann nur den Codex-Harness-Live-Test aus.
-- Docker aktiviert standardmäßig die Image-, MCP-/Tool- und Guardian-Proben. Setzen Sie
+- Der Docker-Runner liegt unter `scripts/test-live-codex-harness-docker.sh`.
+- Er liest das eingebundene `~/.profile`, übergibt `OPENAI_API_KEY`, kopiert Codex-CLI-
+ Auth-Dateien, sofern vorhanden, installiert `@openai/codex` in ein beschreibbares eingebundenes npm-
+ Präfix, stellt den Quellbaum bereit und führt dann nur den Live-Test für den Codex-Harness aus.
+- Docker aktiviert die Image-, MCP-/Tool- und Guardian-Probes standardmäßig. Setzen Sie
`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` oder
`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` oder
`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, wenn Sie einen engeren Debug-
Lauf benötigen.
-- Docker verwendet dieselbe explizite Codex-Runtime-Konfiguration, sodass Legacy-Aliasse oder PI-
+- Docker verwendet dieselbe explizite Codex-Runtime-Konfiguration, sodass Legacy-Aliasse oder ein PI-
Fallback eine Codex-Harness-Regression nicht verbergen können.
### Empfohlene Live-Rezepte
-Enge, explizite Allowlists sind am schnellsten und am wenigsten instabil:
+Enge, explizite Allowlists sind am schnellsten und am wenigsten anfällig:
- Einzelnes Modell, direkt (kein Gateway):
- `OPENCLAW_LIVE_MODELS="openai/gpt-5.5" pnpm test:live src/agents/models.profiles.live.test.ts`
@@ -360,12 +372,12 @@ Enge, explizite Allowlists sind am schnellsten und am wenigsten instabil:
Hinweise:
-- `google/...` verwendet die Gemini-API (API-Schlüssel).
-- `google-antigravity/...` verwendet die Antigravity-OAuth-Bridge (Agent-Endpunkt im Stil von Cloud Code Assist).
-- `google-gemini-cli/...` verwendet die lokale Gemini-CLI auf Ihrem Rechner (separate Authentifizierung und Tooling-Eigenheiten).
-- Gemini-API vs. Gemini-CLI:
- - API: OpenClaw ruft Googles gehostete Gemini-API per HTTP auf (API-Schlüssel / Profil-Authentifizierung); das meinen die meisten Benutzer mit „Gemini“.
- - CLI: OpenClaw startet eine lokale `gemini`-Binärdatei über die Shell; sie hat ihre eigene Authentifizierung und kann sich anders verhalten (Streaming-/Tool-Unterstützung/Versionsabweichung).
+- `google/...` verwendet die Gemini API (API-Schlüssel).
+- `google-antigravity/...` verwendet die Antigravity-OAuth-Bridge (Cloud-Code-Assist-artiger Agent-Endpunkt).
+- `google-gemini-cli/...` verwendet die lokale Gemini CLI auf Ihrem Rechner (separate Authentifizierung und Tooling-Eigenheiten).
+- Gemini API vs. Gemini CLI:
+ - API: OpenClaw ruft Googles gehostete Gemini API über HTTP auf (API-Schlüssel / Profil-Authentifizierung); das meinen die meisten Nutzer mit „Gemini“.
+ - CLI: OpenClaw startet ein lokales `gemini`-Binary per Shell; es hat eigene Authentifizierung und kann sich anders verhalten (Streaming-/Tool-Unterstützung/Versionsversatz).
## Live: Modellmatrix (was wir abdecken)
@@ -375,10 +387,10 @@ Es gibt keine feste „CI-Modellliste“ (Live ist Opt-in), aber dies sind die *
Dies ist der Lauf für „gängige Modelle“, von dem wir erwarten, dass er funktionsfähig bleibt:
-- OpenAI (nicht Codex): `openai/gpt-5.5`
+- OpenAI (Nicht-Codex): `openai/gpt-5.5`
- OpenAI Codex OAuth: `openai-codex/gpt-5.5`
- Anthropic: `anthropic/claude-opus-4-6` (oder `anthropic/claude-sonnet-4-6`)
-- Google (Gemini-API): `google/gemini-3.1-pro-preview` und `google/gemini-3-flash-preview` (ältere Gemini-2.x-Modelle vermeiden)
+- Google (Gemini API): `google/gemini-3.1-pro-preview` und `google/gemini-3-flash-preview` (ältere Gemini-2.x-Modelle vermeiden)
- Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` und `google-antigravity/gemini-3-flash`
- DeepSeek: `deepseek/deepseek-v4-flash` und `deepseek/deepseek-v4-pro`
- Z.AI (GLM): `zai/glm-5.1`
@@ -387,7 +399,7 @@ Dies ist der Lauf für „gängige Modelle“, von dem wir erwarten, dass er fun
Gateway-Smoke mit Tools + Image ausführen:
`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,deepseek/deepseek-v4-flash,zai/glm-5.1,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
-### Baseline: Tool-Aufrufe (Read + optional Exec)
+### Basis: Tool-Aufrufe (Read + optional Exec)
Wählen Sie mindestens eines pro Provider-Familie:
@@ -398,31 +410,31 @@ Wählen Sie mindestens eines pro Provider-Familie:
- Z.AI (GLM): `zai/glm-5.1`
- MiniMax: `minimax/MiniMax-M2.7`
-Optionale zusätzliche Abdeckung (nice to have):
+Optionale zusätzliche Abdeckung (nützlich):
-- xAI: `xai/grok-4.3` (oder die neueste verfügbare Version)
-- Mistral: `mistral/`… (wählen Sie ein „tools“-fähiges Modell aus, das Sie aktiviert haben)
-- Cerebras: `cerebras/`… (wenn Sie Zugriff haben)
+- xAI: `xai/grok-4.3` (oder neuestes verfügbares Modell)
+- Mistral: `mistral/`… (wählen Sie ein „tools“-fähiges Modell, das bei Ihnen aktiviert ist)
+- Cerebras: `cerebras/`… (falls Sie Zugriff haben)
- LM Studio: `lmstudio/`… (lokal; Tool-Aufrufe hängen vom API-Modus ab)
### Vision: Image senden (Anhang → multimodale Nachricht)
-Nehmen Sie mindestens ein image-fähiges Modell in `OPENCLAW_LIVE_GATEWAY_MODELS` auf (Claude-/Gemini-/OpenAI-vision-fähige Varianten usw.), um die Image-Probe auszuführen.
+Nehmen Sie mindestens ein bildfähiges Modell in `OPENCLAW_LIVE_GATEWAY_MODELS` auf (Claude-/Gemini-/OpenAI-Varianten mit Vision-Fähigkeit usw.), um den Image-Probe auszuführen.
### Aggregatoren / alternative Gateways
Wenn Sie Schlüssel aktiviert haben, unterstützen wir auch Tests über:
-- OpenRouter: `openrouter/...` (Hunderte von Modellen; verwenden Sie `openclaw models scan`, um tool- und image-fähige Kandidaten zu finden)
+- OpenRouter: `openrouter/...` (Hunderte Modelle; verwenden Sie `openclaw models scan`, um Kandidaten mit Tool- und Image-Fähigkeit zu finden)
- OpenCode: `opencode/...` für Zen und `opencode-go/...` für Go (Authentifizierung über `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`)
-Weitere Provider, die Sie in die Live-Matrix aufnehmen können (wenn Sie Zugangsdaten/Konfiguration haben):
+Weitere Provider, die Sie in die Live-Matrix aufnehmen können (falls Sie Zugangsdaten/Konfiguration haben):
- Integriert: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot`
- Über `models.providers` (benutzerdefinierte Endpunkte): `minimax` (Cloud/API) sowie jeder OpenAI-/Anthropic-kompatible Proxy (LM Studio, vLLM, LiteLLM usw.)
-Codieren Sie „alle Modelle“ in Dokumentationen nicht fest. Die maßgebliche Liste ist das, was `discoverModels(...)` auf Ihrem Rechner zurückgibt, plus die verfügbaren Schlüssel.
+Codieren Sie nicht „alle Modelle“ fest in der Dokumentation. Maßgeblich ist die Liste, die `discoverModels(...)` auf Ihrem Rechner zurückgibt, plus die jeweils verfügbaren Schlüssel.
## Zugangsdaten (niemals committen)
@@ -430,45 +442,45 @@ Codieren Sie „alle Modelle“ in Dokumentationen nicht fest. Die maßgebliche
Live-Tests finden Zugangsdaten auf dieselbe Weise wie die CLI. Praktische Auswirkungen:
- Wenn die CLI funktioniert, sollten Live-Tests dieselben Schlüssel finden.
-- Wenn ein Live-Test „keine Anmeldedaten“ meldet, debuggen Sie ihn genauso, wie Sie `openclaw models list` / die Modellauswahl debuggen würden.
+- Wenn ein Live-Test „no creds“ meldet, debuggen Sie dies genauso, wie Sie `openclaw models list` / die Modellauswahl debuggen würden.
-- Auth-Profile pro Agent: `~/.openclaw/agents//agent/auth-profiles.json` (das ist in den Live-Tests mit „Profilschlüsseln“ gemeint)
+- Authentifizierungsprofile pro Agent: `~/.openclaw/agents//agent/auth-profiles.json` (das ist in den Live-Tests mit „Profilschlüssel“ gemeint)
- Konfiguration: `~/.openclaw/openclaw.json` (oder `OPENCLAW_CONFIG_PATH`)
-- Legacy-State-Verzeichnis: `~/.openclaw/credentials/` (wird, falls vorhanden, in das gestagte Live-Home kopiert, ist aber nicht der zentrale Speicher für Profilschlüssel)
-- Lokale Live-Läufe kopieren standardmäßig die aktive Konfiguration, die `auth-profiles.json`-Dateien pro Agent, Legacy-`credentials/` und unterstützte Auth-Verzeichnisse externer CLIs in ein temporäres Test-Home; gestagte Live-Homes überspringen `workspace/` und `sandboxes/`, und Pfad-Overrides für `agents.*.workspace` / `agentDir` werden entfernt, damit Probes nicht auf Ihrem echten Host-Workspace laufen.
+- Veraltetes Zustandsverzeichnis: `~/.openclaw/credentials/` (wird, wenn vorhanden, in das gestagte Live-Home kopiert, ist aber nicht der Hauptspeicher für Profilschlüssel)
+- Lokale Live-Ausführungen kopieren standardmäßig die aktive Konfiguration, die `auth-profiles.json`-Dateien pro Agent, veraltete `credentials/` und unterstützte Authentifizierungsverzeichnisse externer CLIs in ein temporäres Test-Home; gestagte Live-Homes überspringen `workspace/` und `sandboxes/`, und Pfad-Overrides für `agents.*.workspace` / `agentDir` werden entfernt, damit Probes nicht auf Ihrem echten Host-Workspace laufen.
-Wenn Sie Env-Schlüssel verwenden möchten (z. B. exportiert in Ihrer `~/.profile`), führen Sie lokale Tests nach `source ~/.profile` aus oder verwenden Sie die Docker-Runner unten (sie können `~/.profile` in den Container mounten).
+Wenn Sie sich auf Umgebungsschlüssel verlassen möchten (z. B. aus Ihrer `~/.profile` exportiert), führen Sie lokale Tests nach `source ~/.profile` aus, oder verwenden Sie die Docker-Runner unten (sie können `~/.profile` in den Container einbinden).
-## Deepgram Live (Audiotranskription)
+## Deepgram live (Audiotranskription)
- Test: `extensions/deepgram/audio.live.test.ts`
- Aktivieren: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts`
-## BytePlus Coding-Plan Live
+## BytePlus-Coding-Plan live
- Test: `extensions/byteplus/live.test.ts`
- Aktivieren: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts`
- Optionaler Modell-Override: `BYTEPLUS_CODING_MODEL=ark-code-latest`
-## ComfyUI Workflow-Medien Live
+## ComfyUI-Workflow-Medien live
- Test: `extensions/comfy/comfy.live.test.ts`
- Aktivieren: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts`
- Umfang:
- - Führt die gebündelten comfy-Pfade für Bild, Video und `music_generate` aus
- - Überspringt jede Capability, sofern `plugins.entries.comfy.config.` nicht konfiguriert ist
+ - Übt die gebündelten comfy-Pfade für Bild, Video und `music_generate` aus
+ - Überspringt jede Fähigkeit, sofern `plugins.entries.comfy.config.` nicht konfiguriert ist
- Nützlich nach Änderungen an comfy-Workflow-Übermittlung, Polling, Downloads oder Plugin-Registrierung
-## Bildgenerierung Live
+## Bildgenerierung live
- Test: `test/image-generation.runtime.live.test.ts`
- Befehl: `pnpm test:live test/image-generation.runtime.live.test.ts`
- Harness: `pnpm test:live:media image`
- Umfang:
- - Listet jedes registrierte Bildgenerierungs-Provider-Plugin auf
- - Lädt fehlende Provider-Env-Variablen vor dem Prüfen aus Ihrer Login-Shell (`~/.profile`)
- - Verwendet standardmäßig Live-/Env-API-Schlüssel vor gespeicherten Auth-Profilen, damit veraltete Testschlüssel in `auth-profiles.json` keine echten Shell-Anmeldedaten verdecken
- - Überspringt Provider ohne verwendbare Authentifizierung/Profil/Modell
+ - Enumeriert jedes registrierte Bildgenerierungs-Provider-Plugin
+ - Lädt fehlende Provider-Umgebungsvariablen vor dem Probing aus Ihrer Login-Shell (`~/.profile`)
+ - Verwendet standardmäßig Live-/Umgebungs-API-Schlüssel vor gespeicherten Authentifizierungsprofilen, sodass veraltete Testschlüssel in `auth-profiles.json` echte Shell-Anmeldedaten nicht verdecken
+ - Überspringt Provider ohne nutzbare Authentifizierung/nutzbares Profil/nutzbares Modell
- Führt jeden konfigurierten Provider durch die gemeinsame Bildgenerierungs-Runtime:
- `:generate`
- `:edit`, wenn der Provider Bearbeitungsunterstützung deklariert
@@ -486,10 +498,10 @@ Wenn Sie Env-Schlüssel verwenden möchten (z. B. exportiert in Ihrer `~/.profil
- `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="deepinfra"`
- `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,openrouter/google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"`
- `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,openrouter:generate,xai:default-generate,xai:default-edit"`
-- Optionales Auth-Verhalten:
- - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Authentifizierung über den Profilspeicher zu erzwingen und reine Env-Overrides zu ignorieren
+- Optionales Authentifizierungsverhalten:
+ - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Authentifizierung über den Profilspeicher zu erzwingen und reine Umgebungs-Overrides zu ignorieren
-Fügen Sie für den ausgelieferten CLI-Pfad einen `infer`-Smoke-Test hinzu, nachdem der Provider-/Runtime-Live-Test bestanden hat:
+Fügen Sie für den ausgelieferten CLI-Pfad einen `infer`-Smoke-Test hinzu, nachdem der Provider-/Runtime-Live-Test erfolgreich war:
```bash
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_INFER_CLI_TEST=1 pnpm test:live -- test/image-generation.infer-cli.live.test.ts
@@ -501,23 +513,21 @@ openclaw infer image generate \
--json
```
-Dies deckt CLI-Argument-Parsing, Konfigurations-/Default-Agent-Auflösung, Aktivierung gebündelter
-Plugins, die gemeinsame Bildgenerierungs-Runtime und die Live-Provider-
-Anfrage ab. Plugin-Abhängigkeiten müssen vor dem Laden der Runtime vorhanden sein.
+Dies deckt CLI-Argument-Parsing, Auflösung von Konfiguration/Standard-Agent, Aktivierung gebündelter Plugins, die gemeinsame Bildgenerierungs-Runtime und die Live-Provider-Anfrage ab. Plugin-Abhängigkeiten müssen vor dem Runtime-Laden vorhanden sein.
-## Musikgenerierung Live
+## Musikgenerierung live
- Test: `extensions/music-generation-providers.live.test.ts`
- Aktivieren: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts`
- Harness: `pnpm test:live:media music`
- Umfang:
- - Führt den gemeinsamen gebündelten Musikgenerierungs-Provider-Pfad aus
+ - Übt den gemeinsamen gebündelten Musikgenerierungs-Provider-Pfad aus
- Deckt derzeit Google und MiniMax ab
- - Lädt Provider-Env-Variablen vor dem Prüfen aus Ihrer Login-Shell (`~/.profile`)
- - Verwendet standardmäßig Live-/Env-API-Schlüssel vor gespeicherten Auth-Profilen, damit veraltete Testschlüssel in `auth-profiles.json` keine echten Shell-Anmeldedaten verdecken
- - Überspringt Provider ohne verwendbare Authentifizierung/Profil/Modell
- - Führt beide deklarierten Runtime-Modi aus, wenn verfügbar:
- - `generate` mit Prompt-only-Eingabe
+ - Lädt Provider-Umgebungsvariablen vor dem Probing aus Ihrer Login-Shell (`~/.profile`)
+ - Verwendet standardmäßig Live-/Umgebungs-API-Schlüssel vor gespeicherten Authentifizierungsprofilen, sodass veraltete Testschlüssel in `auth-profiles.json` echte Shell-Anmeldedaten nicht verdecken
+ - Überspringt Provider ohne nutzbare Authentifizierung/nutzbares Profil/nutzbares Modell
+ - Führt beide deklarierten Runtime-Modi aus, sofern verfügbar:
+ - `generate` mit reiner Prompt-Eingabe
- `edit`, wenn der Provider `capabilities.edit.enabled` deklariert
- Aktuelle Abdeckung der gemeinsamen Lane:
- `google`: `generate`, `edit`
@@ -526,51 +536,51 @@ Anfrage ab. Plugin-Abhängigkeiten müssen vor dem Laden der Runtime vorhanden s
- Optionale Eingrenzung:
- `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"`
- `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.6"`
-- Optionales Auth-Verhalten:
- - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Authentifizierung über den Profilspeicher zu erzwingen und reine Env-Overrides zu ignorieren
+- Optionales Authentifizierungsverhalten:
+ - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Authentifizierung über den Profilspeicher zu erzwingen und reine Umgebungs-Overrides zu ignorieren
-## Videogenerierung Live
+## Videogenerierung live
- Test: `extensions/video-generation-providers.live.test.ts`
- Aktivieren: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts`
- Harness: `pnpm test:live:media video`
- Umfang:
- - Führt den gemeinsamen gebündelten Videogenerierungs-Provider-Pfad aus
- - Verwendet standardmäßig den release-sicheren Smoke-Pfad: Nicht-FAL-Provider, eine Text-zu-Video-Anfrage pro Provider, ein einsekündiger Lobster-Prompt und eine Provider-spezifische Operationsobergrenze aus `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (standardmäßig `180000`)
- - Überspringt FAL standardmäßig, weil Provider-seitige Warteschlangenlatenz die Release-Zeit dominieren kann; übergeben Sie `--video-providers fal` oder `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, um ihn explizit auszuführen
- - Lädt Provider-Env-Variablen vor dem Prüfen aus Ihrer Login-Shell (`~/.profile`)
- - Verwendet standardmäßig Live-/Env-API-Schlüssel vor gespeicherten Auth-Profilen, damit veraltete Testschlüssel in `auth-profiles.json` keine echten Shell-Anmeldedaten verdecken
- - Überspringt Provider ohne verwendbare Authentifizierung/Profil/Modell
+ - Übt den gemeinsamen gebündelten Videogenerierungs-Provider-Pfad aus
+ - Verwendet standardmäßig den release-sicheren Smoke-Pfad: Nicht-FAL-Provider, eine Text-zu-Video-Anfrage pro Provider, Ein-Sekunden-Hummer-Prompt und eine Operationsobergrenze pro Provider aus `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (standardmäßig `180000`)
+ - Überspringt FAL standardmäßig, weil die Provider-seitige Warteschlangenlatenz die Release-Zeit dominieren kann; übergeben Sie `--video-providers fal` oder `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, um ihn explizit auszuführen
+ - Lädt Provider-Umgebungsvariablen vor dem Probing aus Ihrer Login-Shell (`~/.profile`)
+ - Verwendet standardmäßig Live-/Umgebungs-API-Schlüssel vor gespeicherten Authentifizierungsprofilen, sodass veraltete Testschlüssel in `auth-profiles.json` echte Shell-Anmeldedaten nicht verdecken
+ - Überspringt Provider ohne nutzbare Authentifizierung/nutzbares Profil/nutzbares Modell
- Führt standardmäßig nur `generate` aus
- - Setzen Sie `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, um auch deklarierte Transform-Modi auszuführen, wenn verfügbar:
- - `imageToVideo`, wenn der Provider `capabilities.imageToVideo.enabled` deklariert und der ausgewählte Provider/das ausgewählte Modell im gemeinsamen Sweep buffer-gestützte lokale Bildeingabe akzeptiert
- - `videoToVideo`, wenn der Provider `capabilities.videoToVideo.enabled` deklariert und der ausgewählte Provider/das ausgewählte Modell im gemeinsamen Sweep buffer-gestützte lokale Videoeingabe akzeptiert
+ - Setzen Sie `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, um auch deklarierte Transformationsmodi auszuführen, sofern verfügbar:
+ - `imageToVideo`, wenn der Provider `capabilities.imageToVideo.enabled` deklariert und der ausgewählte Provider/das ausgewählte Modell im gemeinsamen Sweep pufferbasierte lokale Bildeingabe akzeptiert
+ - `videoToVideo`, wenn der Provider `capabilities.videoToVideo.enabled` deklariert und der ausgewählte Provider/das ausgewählte Modell im gemeinsamen Sweep pufferbasierte lokale Videoeingabe akzeptiert
- Aktuelle deklarierte, aber im gemeinsamen Sweep übersprungene `imageToVideo`-Provider:
- `vydra`, weil das gebündelte `veo3` nur Text unterstützt und das gebündelte `kling` eine Remote-Bild-URL erfordert
- Provider-spezifische Vydra-Abdeckung:
- `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts`
- - diese Datei führt `veo3` Text-zu-Video sowie eine `kling`-Lane aus, die standardmäßig eine Remote-Bild-URL-Fixture verwendet
+ - diese Datei führt `veo3` Text-zu-Video plus eine `kling`-Lane aus, die standardmäßig ein Remote-Bild-URL-Fixture verwendet
- Aktuelle `videoToVideo`-Live-Abdeckung:
- `runway` nur, wenn das ausgewählte Modell `runway/gen4_aleph` ist
- Aktuelle deklarierte, aber im gemeinsamen Sweep übersprungene `videoToVideo`-Provider:
- `alibaba`, `qwen`, `xai`, weil diese Pfade derzeit Remote-`http(s)`-/MP4-Referenz-URLs erfordern
- - `google`, weil die aktuelle gemeinsame Gemini-/Veo-Lane lokale buffer-gestützte Eingabe verwendet und dieser Pfad im gemeinsamen Sweep nicht akzeptiert wird
+ - `google`, weil die aktuelle gemeinsame Gemini-/Veo-Lane lokale pufferbasierte Eingabe verwendet und dieser Pfad im gemeinsamen Sweep nicht akzeptiert wird
- `openai`, weil der aktuellen gemeinsamen Lane Garantien für organisationsspezifischen Zugriff auf Video-Inpainting/-Remix fehlen
- Optionale Eingrenzung:
- `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="deepinfra,google,openai,runway"`
- `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"`
- - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, um jeden Provider in den Standard-Sweep einzuschließen, einschließlich FAL
- - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, um die Obergrenze pro Provider-Operation für einen aggressiven Smoke-Lauf zu reduzieren
-- Optionales Auth-Verhalten:
- - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Authentifizierung über den Profilspeicher zu erzwingen und reine Env-Overrides zu ignorieren
+ - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, um jeden Provider in den Standardsweep einzubeziehen, einschließlich FAL
+ - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, um die Operationsobergrenze jedes Providers für einen aggressiven Smoke-Lauf zu reduzieren
+- Optionales Authentifizierungsverhalten:
+ - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Authentifizierung über den Profilspeicher zu erzwingen und reine Umgebungs-Overrides zu ignorieren
## Medien-Live-Harness
- Befehl: `pnpm test:live:media`
- Zweck:
- Führt die gemeinsamen Bild-, Musik- und Video-Live-Suites über einen einzigen repo-nativen Einstiegspunkt aus
- - Lädt fehlende Provider-Env-Variablen automatisch aus `~/.profile`
- - Grenzt jede Suite standardmäßig automatisch auf Provider ein, die aktuell verwendbare Authentifizierung haben
+ - Lädt fehlende Provider-Umgebungsvariablen automatisch aus `~/.profile`
+ - Grenzt jede Suite standardmäßig automatisch auf Provider ein, die aktuell nutzbare Authentifizierung haben
- Verwendet `scripts/test-live.mjs` wieder, sodass Heartbeat- und Quiet-Mode-Verhalten konsistent bleiben
- Beispiele:
- `pnpm test:live:media`
@@ -580,4 +590,4 @@ Anfrage ab. Plugin-Abhängigkeiten müssen vor dem Laden der Runtime vorhanden s
## Verwandt
-- [Testing](/de/help/testing) — Unit-, Integrations-, QA- und Docker-Suites
+- [Testen](/de/help/testing) — Unit-, Integrations-, QA- und Docker-Suites
diff --git a/docs/de/plugins/hooks.md b/docs/de/plugins/hooks.md
index 459cf8695..e6ee2920a 100644
--- a/docs/de/plugins/hooks.md
+++ b/docs/de/plugins/hooks.md
@@ -1,27 +1,26 @@
---
read_when:
- - Sie erstellen ein Plugin, das before_tool_call, before_agent_reply, Nachrichten-Hooks oder Lifecycle-Hooks benötigt
- - Sie müssen Tool-Aufrufe eines Plugins blockieren, umschreiben oder genehmigungspflichtig machen
+ - Sie erstellen ein Plugin, das `before_tool_call`, `before_agent_reply`, Nachrichten-Hooks oder Lifecycle-Hooks benötigt
+ - Sie müssen Tool-Aufrufe eines Plugins blockieren, umschreiben oder dafür eine Genehmigung verlangen
- Sie entscheiden zwischen internen Hooks und Plugin-Hooks
-summary: 'Plugin-Hooks: Agent-, Tool-, Nachrichten-, Sitzungs- und Gateway-Lebenszyklusereignisse abfangen'
+summary: 'Plugin-Einhängepunkte: Agenten-, Werkzeug-, Nachrichten-, Sitzungs- und Gateway-Lebenszyklusereignisse abfangen'
title: Plugin-Hooks
x-i18n:
- generated_at: "2026-05-03T21:36:08Z"
+ generated_at: "2026-05-04T18:23:48Z"
model: gpt-5.5
provider: openai
- source_hash: 2c4ed060f1b89917e1f2f46d2da9448cd562edbcd6ce03bc9b1a83da3ed9a591
+ source_hash: 37c7273036463c87e478db5678822b676c89447caee65f2f3f47a45194d1e37b
source_path: plugins/hooks.md
workflow: 16
---
Plugin-Hooks sind prozessinterne Erweiterungspunkte für OpenClaw-Plugins. Verwenden Sie sie,
-wenn ein Plugin Agent-Läufe, Tool-Aufrufe, den Nachrichtenfluss,
-den Sitzungslebenszyklus, das Subagent-Routing, Installationen oder den Gateway-Start
-prüfen oder ändern muss.
+wenn ein Plugin Agent-Ausführungen, Tool-Aufrufe, Nachrichtenfluss,
+Session-Lifecycle, Subagent-Routing, Installationen oder den Gateway-Start prüfen oder ändern muss.
-Verwenden Sie stattdessen [interne Hooks](/de/automation/hooks), wenn Sie ein kleines
-vom Betreiber installiertes `HOOK.md`-Skript für Befehls- und Gateway-Ereignisse wie
-`/new`, `/reset`, `/stop`, `agent:bootstrap` oder `gateway:startup` benötigen.
+Verwenden Sie stattdessen [interne Hooks](/de/automation/hooks), wenn Sie ein kleines,
+vom Operator installiertes `HOOK.md`-Skript für Befehls- und Gateway-Ereignisse wie
+`/new`, `/reset`, `/stop`, `agent:bootstrap` oder `gateway:startup` möchten.
## Schnellstart
@@ -57,20 +56,19 @@ export default definePluginEntry({
});
```
-Hook-Handler werden sequenziell in absteigender `priority` ausgeführt. Hooks
-mit gleicher Priorität behalten die Registrierungsreihenfolge bei.
+Hook-Handler werden sequenziell in absteigender `priority` ausgeführt. Hooks mit gleicher Priorität
+behalten die Registrierungsreihenfolge bei.
`api.on(name, handler, opts?)` akzeptiert:
-- `priority` — Reihenfolge der Handler (höhere Werte werden zuerst ausgeführt).
-- `timeoutMs` — optionales Budget pro Hook. Wenn gesetzt, bricht der Hook-Runner
- diesen Handler nach Ablauf des Budgets ab und fährt mit dem nächsten fort,
- anstatt langsame Einrichtung oder Abrufarbeit das vom Aufrufer konfigurierte
- Modell-Timeout verbrauchen zu lassen. Lassen Sie es weg, um das standardmäßige
- Beobachtungs-/Entscheidungs-Timeout zu verwenden, das der Hook-Runner allgemein
- anwendet.
+- `priority` — Handler-Reihenfolge (höher wird zuerst ausgeführt).
+- `timeoutMs` — optionales Budget pro Hook. Wenn gesetzt, bricht der Hook-Runner diesen
+ Handler nach Ablauf des Budgets ab und fährt mit dem nächsten fort, statt
+ langsame Einrichtung oder Abrufarbeit das vom Aufrufer konfigurierte Modell-Timeout
+ verbrauchen zu lassen. Lassen Sie es weg, um das standardmäßige Beobachtungs-/Entscheidungs-Timeout zu verwenden, das der
+ Hook-Runner generisch anwendet.
-Betreiber können Hook-Budgets auch ohne Änderung des Plugin-Codes festlegen:
+Operatoren können Hook-Budgets auch festlegen, ohne Plugin-Code zu patchen:
```json
{
@@ -90,37 +88,36 @@ Betreiber können Hook-Budgets auch ohne Änderung des Plugin-Codes festlegen:
}
```
-`hooks.timeouts.` überschreibt `hooks.timeoutMs`, das wiederum den
-vom Plugin verfassten Wert `api.on(..., { timeoutMs })` überschreibt. Jeder
-konfigurierte Wert muss eine positive Ganzzahl von höchstens 600000 Millisekunden
-sein. Bevorzugen Sie Überschreibungen pro Hook für bekannt langsame Hooks, damit
-ein Plugin nicht überall ein längeres Budget erhält.
+`hooks.timeouts.` überschreibt `hooks.timeoutMs`, das den
+vom Plugin geschriebenen Wert `api.on(..., { timeoutMs })` überschreibt. Jeder konfigurierte Wert muss
+eine positive Ganzzahl von höchstens 600000 Millisekunden sein. Bevorzugen Sie Überschreibungen pro Hook
+für bekannte langsame Hooks, damit ein Plugin nicht überall ein längeres Budget erhält.
Jeder Hook erhält `event.context.pluginConfig`, die aufgelöste Konfiguration für das
-Plugin, das diesen Handler registriert hat. Verwenden Sie sie für Hook-Entscheidungen,
-die aktuelle Plugin-Optionen benötigen; OpenClaw injiziert sie pro Handler, ohne das
-gemeinsam genutzte Event-Objekt zu verändern, das andere Plugins sehen.
+Plugin, das diesen Handler registriert hat. Verwenden Sie sie für Hook-Entscheidungen, die
+aktuelle Plugin-Optionen benötigen; OpenClaw injiziert sie pro Handler, ohne das
+gemeinsame Ereignisobjekt zu verändern, das andere Plugins sehen.
## Hook-Katalog
-Hooks sind nach der Oberfläche gruppiert, die sie erweitern. Namen in **Fettdruck**
-akzeptieren ein Entscheidungsergebnis (blockieren, abbrechen, überschreiben oder
-Genehmigung anfordern); alle anderen dienen nur der Beobachtung.
+Hooks sind nach der Oberfläche gruppiert, die sie erweitern. Namen in **Fettdruck** akzeptieren ein
+Entscheidungsergebnis (blockieren, abbrechen, überschreiben oder Genehmigung anfordern); alle anderen dienen
+nur der Beobachtung.
**Agent-Turn**
-- `before_model_resolve` — Provider oder Modell überschreiben, bevor Sitzungsnachrichten geladen werden
-- `agent_turn_prepare` — eingereihte Plugin-Turn-Injektionen verbrauchen und Same-Turn-Kontext vor Prompt-Hooks hinzufügen
+- `before_model_resolve` — Provider oder Modell überschreiben, bevor Session-Nachrichten geladen werden
+- `agent_turn_prepare` — in die Warteschlange gestellte Plugin-Turn-Injektionen verbrauchen und Kontext für denselben Turn vor Prompt-Hooks hinzufügen
- `before_prompt_build` — dynamischen Kontext oder System-Prompt-Text vor dem Modellaufruf hinzufügen
-- `before_agent_start` — nur Kompatibilität für eine kombinierte Phase; bevorzugen Sie die beiden Hooks oben
+- `before_agent_start` — nur Kompatibilitätsphase als Kombination; bevorzugen Sie die beiden Hooks oben
- **`before_agent_reply`** — den Modell-Turn mit einer synthetischen Antwort oder Stille kurzschließen
-- **`before_agent_finalize`** — die natürliche endgültige Antwort prüfen und einen weiteren Modell-Durchlauf anfordern
-- `agent_end` — endgültige Nachrichten, Erfolgsstatus und Laufdauer beobachten
-- `heartbeat_prompt_contribution` — nur Heartbeat-Kontext für Hintergrundmonitor- und Lebenszyklus-Plugins hinzufügen
+- **`before_agent_finalize`** — die natürliche finale Antwort prüfen und einen weiteren Modelllauf anfordern
+- `agent_end` — finale Nachrichten, Erfolgsstatus und Ausführungsdauer beobachten
+- `heartbeat_prompt_contribution` — reinen Heartbeat-Kontext für Hintergrundmonitor- und Lifecycle-Plugins hinzufügen
**Konversationsbeobachtung**
-- `model_call_started` / `model_call_ended` — bereinigte Provider-/Modellaufruf-Metadaten, Timing, Ergebnis und begrenzte Request-ID-Hashes ohne Prompt- oder Antwortinhalt beobachten
+- `model_call_started` / `model_call_ended` — bereinigte Metadaten von Provider-/Modellaufrufen, Timing, Ergebnis und begrenzte Request-ID-Hashes ohne Prompt- oder Antwortinhalt beobachten
- `llm_input` — Provider-Eingabe beobachten (System-Prompt, Prompt, Verlauf)
- `llm_output` — Provider-Ausgabe beobachten
@@ -128,7 +125,7 @@ Genehmigung anfordern); alle anderen dienen nur der Beobachtung.
- **`before_tool_call`** — Tool-Parameter umschreiben, Ausführung blockieren oder Genehmigung anfordern
- `after_tool_call` — Tool-Ergebnisse, Fehler und Dauer beobachten
-- **`tool_result_persist`** — die aus einem Tool-Ergebnis erzeugte Assistentennachricht umschreiben
+- **`tool_result_persist`** — die aus einem Tool-Ergebnis erzeugte Assistant-Nachricht umschreiben
- **`before_message_write`** — einen laufenden Nachrichtenschreibvorgang prüfen oder blockieren (selten)
**Nachrichten und Zustellung**
@@ -138,23 +135,23 @@ Genehmigung anfordern); alle anderen dienen nur der Beobachtung.
- **`message_sending`** — ausgehenden Inhalt umschreiben oder Zustellung abbrechen
- `message_sent` — Erfolg oder Fehlschlag der ausgehenden Zustellung beobachten
- **`before_dispatch`** — einen ausgehenden Dispatch vor der Kanalübergabe prüfen oder umschreiben
-- **`reply_dispatch`** — an der endgültigen Reply-Dispatch-Pipeline teilnehmen
+- **`reply_dispatch`** — an der finalen Reply-Dispatch-Pipeline teilnehmen
-**Sitzungen und Compaction**
+**Sessions und Compaction**
-- `session_start` / `session_end` — Grenzen des Sitzungslebenszyklus nachverfolgen
+- `session_start` / `session_end` — Grenzen des Session-Lifecycles verfolgen
- `before_compaction` / `after_compaction` — Compaction-Zyklen beobachten oder annotieren
-- `before_reset` — Sitzungs-Reset-Ereignisse beobachten (`/reset`, programmatische Resets)
+- `before_reset` — Session-Reset-Ereignisse beobachten (`/reset`, programmatische Resets)
-**Subagents**
+**Subagenten**
-- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — Subagent-Routing und Abschlusszustellung koordinieren
+- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — Subagent-Routing und Zustellung bei Abschluss koordinieren
-**Lebenszyklus**
+**Lifecycle**
- `gateway_start` / `gateway_stop` — Plugin-eigene Dienste mit dem Gateway starten oder stoppen
-- `cron_changed` — vom Gateway verwaltete Cron-Lebenszyklusänderungen beobachten (hinzugefügt, aktualisiert, entfernt, gestartet, beendet, geplant)
-- **`before_install`** — Installationsscans für Skills oder Plugins prüfen und optional blockieren
+- `cron_changed` — Änderungen am Gateway-eigenen Cron-Lifecycle beobachten (hinzugefügt, aktualisiert, entfernt, gestartet, abgeschlossen, geplant)
+- **`before_install`** — Skill- oder Plugin-Installationsscans prüfen und optional blockieren
## Richtlinie für Tool-Aufrufe
@@ -165,7 +162,7 @@ Genehmigung anfordern); alle anderen dienen nur der Beobachtung.
- optional `event.runId`
- optional `event.toolCallId`
- Kontextfelder wie `ctx.agentId`, `ctx.sessionKey`, `ctx.sessionId`,
- `ctx.runId`, `ctx.jobId` (gesetzt bei Cron-gesteuerten Läufen) und diagnostisches `ctx.trace`
+ `ctx.runId`, `ctx.jobId` (bei cron-gesteuerten Ausführungen gesetzt) und diagnostisches `ctx.trace`
Es kann zurückgeben:
@@ -193,83 +190,100 @@ Regeln:
- `block: true` ist terminal und überspringt Handler mit niedrigerer Priorität.
- `block: false` wird als keine Entscheidung behandelt.
- `params` schreibt die Tool-Parameter für die Ausführung um.
-- `requireApproval` pausiert den Agent-Lauf und fragt den Benutzer über Plugin-
- Genehmigungen. Der Befehl `/approve` kann sowohl Exec- als auch Plugin-Genehmigungen bestätigen.
-- Ein `block: true` mit niedrigerer Priorität kann weiterhin blockieren, nachdem ein Hook
- mit höherer Priorität eine Genehmigung angefordert hat.
+- `requireApproval` pausiert die Agent-Ausführung und fragt den Benutzer über Plugin-
+ Genehmigungen. Der Befehl `/approve` kann sowohl exec- als auch Plugin-Genehmigungen freigeben.
+- Ein `block: true` mit niedrigerer Priorität kann weiterhin blockieren, nachdem ein Hook mit höherer Priorität
+ eine Genehmigung angefordert hat.
- `onResolution` erhält die aufgelöste Genehmigungsentscheidung — `allow-once`,
`allow-always`, `deny`, `timeout` oder `cancelled`.
-Gebündelte Plugins, die Richtlinien auf Host-Ebene benötigen, können vertrauenswürdige
-Tool-Richtlinien mit `api.registerTrustedToolPolicy(...)` registrieren. Diese werden vor
-gewöhnlichen `before_tool_call`-Hooks und vor Entscheidungen externer Plugins ausgeführt.
-Verwenden Sie sie nur für host-vertrauenswürdige Gates wie Workspace-Richtlinien,
-Budgetdurchsetzung oder Sicherheit reservierter Workflows. Externe Plugins sollten normale
-`before_tool_call`-Hooks verwenden.
+Gebündelte Plugins, die eine Richtlinie auf Host-Ebene benötigen, können vertrauenswürdige Tool-Richtlinien
+mit `api.registerTrustedToolPolicy(...)` registrieren. Diese laufen vor gewöhnlichen
+`before_tool_call`-Hooks und vor Entscheidungen externer Plugins. Verwenden Sie sie nur
+für vom Host vertrauenswürdige Gates wie Workspace-Richtlinien, Budgetdurchsetzung oder
+reservierte Workflow-Sicherheit. Externe Plugins sollten normale `before_tool_call`-
+Hooks verwenden.
### Persistenz von Tool-Ergebnissen
-Tool-Ergebnisse können strukturierte `details` für UI-Rendering, Diagnostik,
-Medien-Routing oder Plugin-eigene Metadaten enthalten. Behandeln Sie `details` als
-Laufzeitmetadaten, nicht als Prompt-Inhalt:
+Tool-Ergebnisse können strukturierte `details` für UI-Rendering, Diagnosen,
+Medienrouting oder Plugin-eigene Metadaten enthalten. Behandeln Sie `details` als Runtime-Metadaten,
+nicht als Prompt-Inhalt:
- OpenClaw entfernt `toolResult.details` vor Provider-Replay und Compaction-
- Eingabe, damit Metadaten nicht zu Modellkontext werden.
-- Persistierte Sitzungseinträge behalten nur begrenzte `details`. Übergrößen-Details werden
+ Eingabe, damit Metadaten nicht zum Modellkontext werden.
+- Persistierte Session-Einträge behalten nur begrenzte `details`. Zu große Details werden
durch eine kompakte Zusammenfassung und `persistedDetailsTruncated: true` ersetzt.
-- `tool_result_persist` und `before_message_write` laufen vor der endgültigen
- Persistenzobergrenze. Hooks sollten zurückgegebene `details` dennoch klein halten und
- vermeiden, Prompt-relevanten Text nur in `details` abzulegen; legen Sie für das Modell
- sichtbare Tool-Ausgaben in `content` ab.
+- `tool_result_persist` und `before_message_write` laufen vor der finalen
+ Persistenzobergrenze. Hooks sollten zurückgegebene `details` trotzdem klein halten und vermeiden,
+ promptrelevanten Text ausschließlich in `details` abzulegen; legen Sie für das Modell sichtbare Tool-Ausgabe
+ in `content` ab.
## Prompt- und Modell-Hooks
Verwenden Sie für neue Plugins die phasenspezifischen Hooks:
-- `before_model_resolve`: erhält nur den aktuellen Prompt und Anhangsmetadaten.
- Geben Sie `providerOverride` oder `modelOverride` zurück.
-- `agent_turn_prepare`: erhält den aktuellen Prompt, vorbereitete Sitzungsnachrichten
- und alle exactly-once eingereihten Injektionen, die für diese Sitzung entnommen wurden.
- Geben Sie `prependContext` oder `appendContext` zurück.
-- `before_prompt_build`: erhält den aktuellen Prompt und Sitzungsnachrichten.
+- `before_model_resolve`: erhält nur den aktuellen Prompt und Anhang-
+ Metadaten. Geben Sie `providerOverride` oder `modelOverride` zurück.
+- `agent_turn_prepare`: erhält den aktuellen Prompt, vorbereitete Session-Nachrichten
+ und alle genau einmal in die Warteschlange gestellten Injektionen, die für diese Session entnommen wurden. Geben Sie
+ `prependContext` oder `appendContext` zurück.
+- `before_prompt_build`: erhält den aktuellen Prompt und Session-Nachrichten.
Geben Sie `prependContext`, `appendContext`, `systemPrompt`,
`prependSystemContext` oder `appendSystemContext` zurück.
- `heartbeat_prompt_contribution`: läuft nur für Heartbeat-Turns und gibt
- `prependContext` oder `appendContext` zurück. Er ist für Hintergrundmonitore gedacht,
- die den aktuellen Zustand zusammenfassen müssen, ohne vom Benutzer initiierte Turns zu ändern.
+ `prependContext` oder `appendContext` zurück. Es ist für Hintergrundmonitore
+ gedacht, die den aktuellen Zustand zusammenfassen müssen, ohne vom Benutzer initiierte Turns zu ändern.
-`before_agent_start` bleibt aus Kompatibilitätsgründen erhalten. Bevorzugen Sie die
-expliziten Hooks oben, damit Ihr Plugin nicht von einer älteren kombinierten Phase abhängt.
+`before_agent_start` bleibt aus Kompatibilitätsgründen bestehen. Bevorzugen Sie die expliziten Hooks oben,
+damit Ihr Plugin nicht von einer älteren kombinierten Phase abhängt.
-`before_agent_start` und `agent_end` enthalten `event.runId`, wenn OpenClaw den
-aktiven Lauf identifizieren kann. Derselbe Wert ist auch über `ctx.runId` verfügbar.
-Cron-gesteuerte Läufe stellen außerdem `ctx.jobId` (die ID des auslösenden Cron-Jobs) bereit,
-damit Plugin-Hooks Metriken, Seiteneffekte oder Zustand auf einen bestimmten geplanten
+`before_agent_start` und `agent_end` enthalten `event.runId`, wenn OpenClaw
+die aktive Ausführung identifizieren kann. Derselbe Wert ist auch über `ctx.runId` verfügbar.
+Cron-gesteuerte Ausführungen stellen außerdem `ctx.jobId` bereit (die ID des auslösenden Cron-Jobs), damit
+Plugin-Hooks Metriken, Seiteneffekte oder Zustand auf einen bestimmten geplanten
Job begrenzen können.
-Bei kanalbasierten Läufen ist `ctx.messageProvider` die Provider-Oberfläche wie
+Bei kanalbasierten Ausführungen ist `ctx.messageProvider` die Provider-Oberfläche wie
`discord` oder `telegram`, während `ctx.channelId` die Zielkennung der Konversation ist,
-wenn OpenClaw sie aus dem Sitzungsschlüssel oder den Zustellungsmetadaten ableiten kann.
+wenn OpenClaw sie aus dem Session-Schlüssel oder den Zustellungsmetadaten ableiten kann.
`agent_end` ist ein Beobachtungs-Hook und läuft nach dem Turn fire-and-forget. Der
-Hook-Runner wendet ein Timeout von 30 Sekunden an, damit ein hängendes Plugin oder ein
-Embedding-Endpunkt das Hook-Promise nicht dauerhaft offen lässt. Ein Timeout wird
-protokolliert und OpenClaw fährt fort; Plugin-eigene Netzwerkarbeit wird dadurch nicht
-abgebrochen, sofern das Plugin nicht auch ein eigenes Abort-Signal verwendet.
+Hook-Runner wendet ein Timeout von 30 Sekunden an, damit ein festhängendes Plugin oder ein Embedding-
+Endpoint das Hook-Promise nicht dauerhaft ausstehend lassen kann. Ein Timeout wird protokolliert und
+OpenClaw fährt fort; Plugin-eigene Netzwerkarbeit wird dadurch nicht abgebrochen, es sei denn, das
+Plugin verwendet auch sein eigenes Abort-Signal.
Verwenden Sie `model_call_started` und `model_call_ended` für Provider-Aufruf-Telemetrie,
-die keine rohen Prompts, Verläufe, Antworten, Header, Request-Bodys oder Provider-Request-IDs
-erhalten soll. Diese Hooks enthalten stabile Metadaten wie `runId`, `callId`, `provider`,
-`model`, optional `api`/`transport`, terminales `durationMs`/`outcome` und
-`upstreamRequestIdHash`, wenn OpenClaw einen begrenzten Provider-Request-ID-Hash ableiten kann.
+die keine Roh-Prompts, Verläufe, Antworten, Header, Request-
+Bodies oder Provider-Request-IDs erhalten soll. Diese Hooks enthalten stabile Metadaten wie
+`runId`, `callId`, `provider`, `model`, optional `api`/`transport`, terminale
+`durationMs`/`outcome` und `upstreamRequestIdHash`, wenn OpenClaw einen
+begrenzten Provider-Request-ID-Hash ableiten kann.
-`before_agent_finalize` läuft nur, wenn ein Harness kurz davorsteht, eine natürliche
-endgültige Assistentenantwort zu akzeptieren. Es ist nicht der `/stop`-Abbruchpfad und
-läuft nicht, wenn der Benutzer einen Turn abbricht. Geben Sie `{ action: "revise", reason }`
-zurück, um den Harness vor der Finalisierung um einen weiteren Modell-Durchlauf zu bitten,
-`{ action: "finalize", reason? }`, um die Finalisierung zu erzwingen, oder lassen Sie ein
-Ergebnis weg, um fortzufahren. Native Codex-`Stop`-Hooks werden als OpenClaw-
-`before_agent_finalize`-Entscheidungen in diesen Hook weitergeleitet.
+`before_agent_finalize` läuft nur, wenn ein Harness kurz davor ist, eine natürliche
+finale Assistant-Antwort zu akzeptieren. Es ist nicht der `/stop`-Abbruchpfad und läuft nicht,
+wenn der Benutzer einen Turn abbricht. Geben Sie `{ action: "revise", reason }` zurück, um
+beim Harness einen weiteren Modelllauf vor der Finalisierung anzufordern, `{ action:
+"finalize", reason? }`, um die Finalisierung zu erzwingen, oder lassen Sie ein Ergebnis weg, um fortzufahren.
+Native Codex-`Stop`-Hooks werden in diesen Hook als OpenClaw-
+`before_agent_finalize`-Entscheidungen weitergeleitet.
+
+Wenn `action: "revise"` zurückgegeben wird, können Plugins `retry`-Metadaten einschließen, um
+den zusätzlichen Modelllauf begrenzt und replay-sicher zu machen:
+
+```typescript
+type BeforeAgentFinalizeRetry = {
+ instruction: string;
+ idempotencyKey?: string;
+ maxAttempts?: number;
+};
+```
+
+`instruction` wird an den Revisionsgrund angehängt, der an den Harness gesendet wird.
+`idempotencyKey` ermöglicht dem Host, Wiederholungen für dieselbe Plugin-Anfrage über
+äquivalente Finalisierungsentscheidungen hinweg zu zählen, und `maxAttempts` begrenzt, wie viele zusätzliche Durchläufe der
+Host erlaubt, bevor er mit der natürlichen finalen Antwort fortfährt.
Nicht gebündelte Plugins, die `llm_input`, `llm_output`,
`before_agent_finalize` oder `agent_end` benötigen, müssen Folgendes setzen:
@@ -288,115 +302,115 @@ Nicht gebündelte Plugins, die `llm_input`, `llm_output`,
}
```
-Prompt-mutierende Hooks und dauerhafte Next-Turn-Injektionen können pro Plugin
+Prompt-verändernde Hooks und dauerhafte Next-Turn-Injektionen können pro Plugin
mit `plugins.entries..hooks.allowPromptInjection=false` deaktiviert werden.
-### Sitzungserweiterungen und Next-Turn-Injektionen
+### Session-Erweiterungen und Next-Turn-Injektionen
Workflow-Plugins können kleinen JSON-kompatiblen Sitzungszustand mit
-`api.registerSessionExtension(...)` persistieren und ihn über die Gateway-
-Methode `sessions.pluginPatch` aktualisieren. Sitzungszeilen projizieren registrierten
-Erweiterungszustand über `pluginExtensions`, sodass Control UI und andere Clients
-Plugin-eigenen Status darstellen können, ohne Plugin-Interna zu kennen.
+`api.registerSessionExtension(...)` persistieren und ihn über die Gateway-Methode
+`sessions.pluginPatch` aktualisieren. Sitzungszeilen projizieren registrierten Erweiterungszustand
+über `pluginExtensions`, sodass Control UI und andere Clients
+Plugin-eigenen Status rendern können, ohne Plugin-Interna kennen zu müssen.
-Verwenden Sie `api.enqueueNextTurnInjection(...)`, wenn ein Plugin dauerhaften Kontext benötigt, der genau einmal
-die nächste Modellrunde erreicht. OpenClaw verarbeitet eingereihte Injections vor
-Prompt-Hooks, verwirft abgelaufene Injections und dedupliziert pro Plugin nach
-`idempotencyKey`. Dies ist der richtige Integrationspunkt für Genehmigungsfortsetzungen, Richtlinienzusammenfassungen,
-Deltas von Hintergrundmonitoren und Befehlsfortsetzungen, die dem
-Modell in der nächsten Runde sichtbar sein sollen, aber nicht zu dauerhaftem System-Prompt-Text werden dürfen.
+Verwenden Sie `api.enqueueNextTurnInjection(...)`, wenn ein Plugin dauerhaften Kontext
+benötigt, der genau einmal den nächsten Modell-Turn erreicht. OpenClaw leert eingereihte Injections vor
+Prompt-Hooks, verwirft abgelaufene Injections und dedupliziert pro Plugin nach `idempotencyKey`.
+Dies ist die richtige Schnittstelle für Approval-Fortsetzungen, Policy-Zusammenfassungen,
+Deltas von Hintergrundmonitoren und Befehlsfortsetzungen, die im nächsten Turn für
+das Modell sichtbar sein sollen, aber nicht zu dauerhaftem System-Prompt-Text werden sollen.
-Bereinigungssemantik ist Teil des Vertrags. Bereinigung von Session-Erweiterungen und
-Bereinigungs-Callbacks des Laufzeit-Lebenszyklus erhalten `reset`, `delete`, `disable` oder
+Cleanup-Semantik ist Teil des Vertrags. Cleanup für Session-Erweiterungen und
+Runtime-Lifecycle-Cleanup-Callbacks erhalten `reset`, `delete`, `disable` oder
`restart`. Der Host entfernt den persistenten Session-Erweiterungszustand des besitzenden Plugins
-und ausstehende Next-Turn-Injections bei Reset/Delete/Disable; Restart behält
-dauerhaften Session-Zustand bei, während Bereinigungs-Callbacks Plugins erlauben, Scheduler-
-Jobs, Ausführungskontext und andere Out-of-Band-Ressourcen der alten Laufzeit-
-Generation freizugeben.
+und ausstehende Next-Turn-Injections für reset/delete/disable; restart behält
+dauerhaften Sitzungszustand bei, während Cleanup-Callbacks Plugins ermöglichen,
+Scheduler-Jobs, Laufkontext und andere Out-of-Band-Ressourcen für die alte Runtime-Generation
+freizugeben.
-## Nachrichten-Hooks
+## Message-Hooks
-Verwenden Sie Nachrichten-Hooks für Routing und Zustellungsrichtlinien auf Kanalebene:
+Verwenden Sie Message-Hooks für Routing und Zustellrichtlinien auf Kanalebene:
-- `message_received`: eingehende Inhalte, Absender, `threadId`, `messageId`,
- `senderId`, optionale Ausführungs-/Session-Korrelation und Metadaten beobachten.
+- `message_received`: eingehenden Inhalt, Absender, `threadId`, `messageId`,
+ `senderId`, optionale Run-/Sitzungskorrelation und Metadaten beobachten.
- `message_sending`: `content` umschreiben oder `{ cancel: true }` zurückgeben.
- `message_sent`: endgültigen Erfolg oder Fehler beobachten.
Bei reinen Audio-TTS-Antworten kann `content` das verborgene gesprochene Transkript
-enthalten, auch wenn die Kanalnutzlast keinen sichtbaren Text/keine sichtbare Beschriftung enthält. Das Umschreiben dieses
+enthalten, auch wenn die Kanal-Payload keinen sichtbaren Text/keine sichtbare Caption hat. Das Umschreiben dieses
`content` aktualisiert nur das für Hooks sichtbare Transkript; es wird nicht als
-Medienbeschriftung gerendert.
+Medien-Caption gerendert.
-Nachrichten-Hook-Kontexte stellen stabile Korrelationsfelder bereit, wenn verfügbar:
+Message-Hook-Kontexte stellen stabile Korrelationsfelder bereit, wenn verfügbar:
`ctx.sessionKey`, `ctx.runId`, `ctx.messageId`, `ctx.senderId`, `ctx.trace`,
`ctx.traceId`, `ctx.spanId`, `ctx.parentSpanId` und `ctx.callDepth`. Bevorzugen Sie
-diese First-Class-Felder, bevor Sie ältere Metadaten lesen.
+diese First-Class-Felder, bevor Sie Legacy-Metadaten lesen.
Bevorzugen Sie typisierte Felder `threadId` und `replyToId`, bevor Sie kanalspezifische
Metadaten verwenden.
Entscheidungsregeln:
-- `message_sending` mit `cancel: true` ist endgültig.
+- `message_sending` mit `cancel: true` ist terminal.
- `message_sending` mit `cancel: false` wird als keine Entscheidung behandelt.
-- Umgeschriebener `content` wird an Hooks mit niedrigerer Priorität weitergegeben, sofern ein späterer Hook
- die Zustellung nicht abbricht.
+- Umgeschriebener `content` läuft weiter zu Hooks mit niedrigerer Priorität, sofern kein späterer Hook
+ die Zustellung abbricht.
-## Installations-Hooks
+## Install-Hooks
-`before_install` wird nach dem integrierten Scan für Installationen von Skills und Plugins ausgeführt.
-Geben Sie zusätzliche Befunde oder `{ block: true, blockReason }` zurück, um die
+`before_install` wird nach dem integrierten Scan für Skill- und Plugin-Installationen ausgeführt.
+Geben Sie zusätzliche Findings oder `{ block: true, blockReason }` zurück, um die
Installation zu stoppen.
-`block: true` ist endgültig. `block: false` wird als keine Entscheidung behandelt.
+`block: true` ist terminal. `block: false` wird als keine Entscheidung behandelt.
-## Gateway-Lebenszyklus
+## Gateway-Lifecycle
Verwenden Sie `gateway_start` für Plugin-Dienste, die Gateway-eigenen Zustand benötigen. Der
Kontext stellt `ctx.config`, `ctx.workspaceDir` und `ctx.getCron?.()` für
-Cron-Inspektion und -Aktualisierungen bereit. Verwenden Sie `gateway_stop`, um lang laufende
-Ressourcen zu bereinigen.
+Cron-Inspektion und Aktualisierungen bereit. Verwenden Sie `gateway_stop`, um langlaufende
+Ressourcen aufzuräumen.
-Verlassen Sie sich für Plugin-eigene Laufzeitdienste nicht auf den internen Hook
+Verlassen Sie sich für Plugin-eigene Runtime-Dienste nicht auf den internen Hook
`gateway:startup`.
-`cron_changed` wird für Gateway-eigene Cron-Lebenszyklusereignisse mit einer typisierten
-Ereignisnutzlast ausgelöst, die die Gründe `added`, `updated`, `removed`, `started`, `finished`
-und `scheduled` abdeckt. Das Ereignis enthält einen Snapshot `PluginHookGatewayCronJob`
-(einschließlich `state.nextRunAtMs`, `state.lastRunStatus` und
+`cron_changed` wird bei Gateway-eigenen Cron-Lifecycle-Ereignissen mit einer typisierten
+Event-Payload ausgelöst, die die Gründe `added`, `updated`, `removed`, `started`, `finished`
+und `scheduled` abdeckt. Das Event enthält einen `PluginHookGatewayCronJob`-
+Snapshot (einschließlich `state.nextRunAtMs`, `state.lastRunStatus` und
`state.lastError`, falls vorhanden) sowie einen `PluginHookGatewayCronDeliveryStatus`
von `not-requested` | `delivered` | `not-delivered` | `unknown`. Entfernte
-Ereignisse enthalten weiterhin den Snapshot des gelöschten Jobs, damit externe Scheduler den
-Zustand abgleichen können. Verwenden Sie `ctx.getCron?.()` und `ctx.config` aus dem Laufzeit-
-Kontext, wenn Sie externe Weck-Scheduler synchronisieren, und behalten Sie OpenClaw als
-Quelle der Wahrheit für Fälligkeitsprüfungen und Ausführung bei.
+Events enthalten weiterhin den Snapshot des gelöschten Jobs, damit externe Scheduler
+den Zustand abgleichen können. Verwenden Sie beim Synchronisieren externer Wake-Scheduler
+`ctx.getCron?.()` und `ctx.config` aus dem Runtime-Kontext und behalten Sie OpenClaw als
+Source of Truth für Fälligkeitsprüfungen und Ausführung bei.
-## Bevorstehende Veraltungen
+## Anstehende Deprecations
-Einige Hook-nahe Oberflächen sind veraltet, werden aber weiterhin unterstützt. Migrieren Sie
+Einige Hook-nahe Oberflächen sind deprecated, werden aber weiterhin unterstützt. Migrieren Sie
vor dem nächsten Major-Release:
-- **Klartext-Kanalumschläge** in Handlern für `inbound_claim` und `message_received`.
- Lesen Sie stattdessen `BodyForAgent` und die strukturierten Benutzerkontext-Blöcke,
- statt flachen Umschlagtext zu parsen. Siehe
- [Klartext-Kanalumschläge → BodyForAgent](/de/plugins/sdk-migration#active-deprecations).
+- **Plaintext channel envelopes** in `inbound_claim`- und `message_received`-
+ Handlern. Lesen Sie `BodyForAgent` und die strukturierten Benutzerkontext-Blöcke,
+ statt flachen Envelope-Text zu parsen. Siehe
+ [Plaintext channel envelopes → BodyForAgent](/de/plugins/sdk-migration#active-deprecations).
- **`before_agent_start`** bleibt aus Kompatibilitätsgründen erhalten. Neue Plugins sollten
- stattdessen `before_model_resolve` und `before_prompt_build` anstelle der kombinierten
+ `before_model_resolve` und `before_prompt_build` statt der kombinierten
Phase verwenden.
- **`onResolution` in `before_tool_call`** verwendet jetzt die typisierte
Union `PluginApprovalResolution` (`allow-once` / `allow-always` / `deny` /
- `timeout` / `cancelled`) anstelle eines frei formulierten `string`.
+ `timeout` / `cancelled`) statt eines frei formulierten `string`.
-Die vollständige Liste — Registrierung der Speicher-Capability, Thinking-
-Profil des Providers, externe Auth-Provider, Provider-Discovery-Typen, Zugriffshelfer für die Task-Laufzeit
-und die Umbenennung von `command-auth` zu `command-status` — finden Sie unter
-[Plugin SDK-Migration → Aktive Veraltungen](/de/plugins/sdk-migration#active-deprecations).
+Die vollständige Liste — Memory-Capability-Registrierung, Provider-Thinking-
+Profil, externe Auth-Provider, Provider-Discovery-Typen, Task-Runtime-
+Accessors und die Umbenennung `command-auth` → `command-status` — finden Sie unter
+[Plugin SDK migration → Active deprecations](/de/plugins/sdk-migration#active-deprecations).
-## Verwandte Themen
+## Verwandt
-- [Plugin SDK-Migration](/de/plugins/sdk-migration) — aktive Veraltungen und Zeitplan für Entfernung
-- [Plugins erstellen](/de/plugins/building-plugins)
+- [Plugin SDK migration](/de/plugins/sdk-migration) — aktive Deprecations und Zeitplan für Entfernungen
+- [Plugins bauen](/de/plugins/building-plugins)
- [Plugin SDK-Überblick](/de/plugins/sdk-overview)
- [Plugin-Einstiegspunkte](/de/plugins/sdk-entrypoints)
- [Interne Hooks](/de/automation/hooks)
diff --git a/docs/de/plugins/sdk-overview.md b/docs/de/plugins/sdk-overview.md
index a627dbeea..705c32d3a 100644
--- a/docs/de/plugins/sdk-overview.md
+++ b/docs/de/plugins/sdk-overview.md
@@ -1,27 +1,27 @@
---
read_when:
- - Sie müssen wissen, welchen SDK-Unterpfad Sie für den Import verwenden müssen
- - Sie möchten eine Referenz für alle Registrierungsmethoden der OpenClawPluginApi
+ - Sie müssen wissen, aus welchem SDK-Unterpfad Sie importieren müssen
+ - Sie möchten eine Referenz für alle Registrierungsmethoden von OpenClawPluginApi
- Sie suchen nach einem bestimmten SDK-Export
sidebarTitle: Plugin SDK overview
-summary: Import-Map, API-Referenz zur Registrierung und SDK-Architektur
-title: Plugin-SDK-Übersicht
+summary: Import-Map, Referenz zur Registrierungs-API und SDK-Architektur
+title: Übersicht zum Plugin SDK
x-i18n:
- generated_at: "2026-05-02T06:42:26Z"
+ generated_at: "2026-05-04T18:24:37Z"
model: gpt-5.5
provider: openai
- source_hash: be5fa531e603fb6d87f84e3193ebd61be1431b57b8f284871ae15f34ca93fc69
+ source_hash: 8187e7d4cfb9d6fb19bbdebfbaea0bb4d98fa5cea4742d0f82a765ae5bc60127
source_path: plugins/sdk-overview.md
workflow: 16
---
-Das Plugin-SDK ist der typisierte Vertrag zwischen Plugins und Core. Diese Seite ist die
+Das Plugin-SDK ist die typisierte Schnittstelle zwischen Plugins und Core. Diese Seite ist die
Referenz dafür, **was importiert werden soll** und **was Sie registrieren können**.
Diese Seite richtet sich an Plugin-Autoren, die `openclaw/plugin-sdk/*` innerhalb von
OpenClaw verwenden. Für externe Apps, Skripte, Dashboards, CI-Jobs und IDE-Erweiterungen,
- die Agents über das Gateway ausführen möchten, verwenden Sie stattdessen das
+ die Agents über den Gateway ausführen möchten, verwenden Sie stattdessen das
[OpenClaw App SDK](/de/concepts/openclaw-sdk) und das Paket `@openclaw/sdk`.
@@ -39,28 +39,28 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
```
Jeder Unterpfad ist ein kleines, eigenständiges Modul. Dadurch bleibt der Start schnell und
-Probleme mit zirkulären Abhängigkeiten werden vermieden. Für channelspezifische Entry-/Build-Helfer
+Probleme mit zirkulären Abhängigkeiten werden vermieden. Für Channel-spezifische Entry-/Build-Helfer
bevorzugen Sie `openclaw/plugin-sdk/channel-core`; behalten Sie `openclaw/plugin-sdk/core` für
-die breitere Dachoberfläche und gemeinsam genutzte Helfer wie
-`buildChannelConfigSchema`.
+die breitere Sammeloberfläche und gemeinsam genutzte Helfer wie
+`buildChannelConfigSchema` bei.
-Für die Channel-Konfiguration veröffentlichen Sie das vom Channel verwaltete JSON Schema über
+Für die Channel-Konfiguration veröffentlichen Sie das Channel-eigene JSON Schema über
`openclaw.plugin.json#channelConfigs`. Der Unterpfad `plugin-sdk/channel-config-schema`
ist für gemeinsam genutzte Schema-Primitiven und den generischen Builder vorgesehen. Die
gebündelten Plugins von OpenClaw verwenden `plugin-sdk/bundled-channel-config-schema` für beibehaltene
-Schemas gebündelter Channels. Veraltete Kompatibilitätsexporte bleiben auf
-`plugin-sdk/channel-config-schema-legacy`; keiner der beiden Unterpfade für gebündelte Schemas ist ein
+Schemas gebündelter Channels. Veraltete Kompatibilitätsexporte verbleiben unter
+`plugin-sdk/channel-config-schema-legacy`; keiner der beiden gebündelten Schema-Unterpfade ist ein
Muster für neue Plugins.
- Importieren Sie keine Provider- oder Channel-gebrandeten Convenience-Seams (zum Beispiel
+ Importieren Sie keine Provider- oder Channel-gebrandeten Convenience-Schnittstellen (zum Beispiel
`openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`).
- Gebündelte Plugins setzen generische SDK-Unterpfade innerhalb ihrer eigenen `api.ts`- /
- `runtime-api.ts`-Barrels zusammen; Core-Verbraucher sollten entweder diese Plugin-lokalen
- Barrels verwenden oder einen schmalen generischen SDK-Vertrag hinzufügen, wenn ein Bedarf wirklich
- channelübergreifend ist.
+ Gebündelte Plugins setzen generische SDK-Unterpfade innerhalb ihrer eigenen `api.ts`-/
+ `runtime-api.ts`-Barrels zusammen; Core-Consumer sollten entweder diese Plugin-lokalen
+ Barrels verwenden oder einen engen generischen SDK-Vertrag hinzufügen, wenn ein Bedarf wirklich
+ Channel-übergreifend ist.
-Eine kleine Gruppe von Hilfs-Seams für gebündelte Plugins erscheint weiterhin in der generierten Export-Map,
+Eine kleine Gruppe von Helfer-Schnittstellen für gebündelte Plugins erscheint weiterhin in der generierten Export-Map,
wenn sie nachverfolgte Owner-Nutzung haben. Sie existieren nur für die Wartung gebündelter Plugins
und werden nicht als Importpfade für neue Drittanbieter-Plugins empfohlen.
@@ -72,132 +72,132 @@ generische Channel-SDK-Unterpfade.
## Unterpfadreferenz
-Das Plugin-SDK wird als Satz schmaler Unterpfade bereitgestellt, gruppiert nach Bereich (Plugin-
-Entry, Channel, Provider, Auth, Runtime, Capability, Memory und reservierte
+Das Plugin-SDK wird als Sammlung enger Unterpfade bereitgestellt, gruppiert nach Bereich (Plugin-
+Entry, Channel, Provider, Authentifizierung, Runtime, Capability, Memory und reservierte
Helfer für gebündelte Plugins). Den vollständigen Katalog, gruppiert und verlinkt, finden Sie unter
[Plugin-SDK-Unterpfade](/de/plugins/sdk-subpaths).
-Die generierte Liste von über 200 Unterpfaden befindet sich in `scripts/lib/plugin-sdk-entrypoints.json`.
+Die generierte Liste mit über 200 Unterpfaden befindet sich in `scripts/lib/plugin-sdk-entrypoints.json`.
## Registrierungs-API
-Der `register(api)`-Callback erhält ein `OpenClawPluginApi`-Objekt mit diesen
+Der Callback `register(api)` erhält ein `OpenClawPluginApi`-Objekt mit diesen
Methoden:
### Capability-Registrierung
-| Methode | Was sie registriert |
-| ------------------------------------------------ | -------------------------------------- |
-| `api.registerProvider(...)` | Textinferenz (LLM) |
+| Methode | Was registriert wird |
+| ------------------------------------------------ | ------------------------------------- |
+| `api.registerProvider(...)` | Textinferenz (LLM) |
| `api.registerAgentHarness(...)` | Experimenteller Low-Level-Agent-Executor |
-| `api.registerCliBackend(...)` | Lokales CLI-Inferenz-Backend |
-| `api.registerChannel(...)` | Messaging-Channel |
-| `api.registerSpeechProvider(...)` | Text-to-Speech- / STT-Synthese |
-| `api.registerRealtimeTranscriptionProvider(...)` | Streaming-Echtzeittranskription |
-| `api.registerRealtimeVoiceProvider(...)` | Duplex-Echtzeit-Sprachsessions |
-| `api.registerMediaUnderstandingProvider(...)` | Bild-/Audio-/Videoanalyse |
-| `api.registerImageGenerationProvider(...)` | Bilderzeugung |
-| `api.registerMusicGenerationProvider(...)` | Musikerzeugung |
-| `api.registerVideoGenerationProvider(...)` | Videoerzeugung |
-| `api.registerWebFetchProvider(...)` | Web-Fetch-/Scrape-Provider |
-| `api.registerWebSearchProvider(...)` | Websuche |
+| `api.registerCliBackend(...)` | Lokales CLI-Inferenz-Backend |
+| `api.registerChannel(...)` | Messaging-Channel |
+| `api.registerSpeechProvider(...)` | Text-to-Speech-/STT-Synthese |
+| `api.registerRealtimeTranscriptionProvider(...)` | Streaming-Echtzeittranskription |
+| `api.registerRealtimeVoiceProvider(...)` | Duplex-Echtzeit-Sprachsitzungen |
+| `api.registerMediaUnderstandingProvider(...)` | Bild-/Audio-/Videoanalyse |
+| `api.registerImageGenerationProvider(...)` | Bilderzeugung |
+| `api.registerMusicGenerationProvider(...)` | Musikerzeugung |
+| `api.registerVideoGenerationProvider(...)` | Videoerzeugung |
+| `api.registerWebFetchProvider(...)` | Web-Fetch-/Scrape-Provider |
+| `api.registerWebSearchProvider(...)` | Websuche |
### Tools und Befehle
-| Methode | Was sie registriert |
-| ------------------------------- | ------------------------------------------------ |
+| Methode | Was registriert wird |
+| ------------------------------- | --------------------------------------------- |
| `api.registerTool(tool, opts?)` | Agent-Tool (erforderlich oder `{ optional: true }`) |
-| `api.registerCommand(def)` | Benutzerdefinierter Befehl (umgeht das LLM) |
+| `api.registerCommand(def)` | Benutzerdefinierter Befehl (umgeht das LLM) |
Plugin-Befehle können `agentPromptGuidance` setzen, wenn der Agent einen kurzen,
-befehlseigenen Routing-Hinweis benötigt. Beschränken Sie diesen Text auf den Befehl selbst; fügen Sie keine
+befehlsseitigen Routing-Hinweis benötigt. Beschränken Sie diesen Text auf den Befehl selbst; fügen Sie keine
Provider- oder Plugin-spezifische Policy zu Core-Prompt-Buildern hinzu.
### Infrastruktur
-| Methode | Was sie registriert |
-| ---------------------------------------------- | ------------------------------------------- |
-| `api.registerHook(events, handler, opts?)` | Event-Hook |
-| `api.registerHttpRoute(params)` | Gateway-HTTP-Endpunkt |
-| `api.registerGatewayMethod(name, handler)` | Gateway-RPC-Methode |
-| `api.registerGatewayDiscoveryService(service)` | Lokaler Gateway-Discovery-Advertiser |
-| `api.registerCli(registrar, opts?)` | CLI-Unterbefehl |
-| `api.registerService(service)` | Hintergrunddienst |
-| `api.registerInteractiveHandler(registration)` | Interaktiver Handler |
-| `api.registerAgentToolResultMiddleware(...)` | Runtime-Tool-Result-Middleware |
-| `api.registerMemoryPromptSupplement(builder)` | Additiver promptnaher Memory-Abschnitt |
-| `api.registerMemoryCorpusSupplement(adapter)` | Additiver Memory-Such-/Lesekorpus |
+| Methode | Was registriert wird |
+| ---------------------------------------------- | ------------------------------------------ |
+| `api.registerHook(events, handler, opts?)` | Event-Hook |
+| `api.registerHttpRoute(params)` | Gateway-HTTP-Endpunkt |
+| `api.registerGatewayMethod(name, handler)` | Gateway-RPC-Methode |
+| `api.registerGatewayDiscoveryService(service)` | Lokaler Gateway-Discovery-Advertiser |
+| `api.registerCli(registrar, opts?)` | CLI-Unterbefehl |
+| `api.registerService(service)` | Hintergrunddienst |
+| `api.registerInteractiveHandler(registration)` | Interaktiver Handler |
+| `api.registerAgentToolResultMiddleware(...)` | Runtime-Middleware für Tool-Ergebnisse |
+| `api.registerMemoryPromptSupplement(builder)` | Additiver Prompt-Abschnitt nahe Memory |
+| `api.registerMemoryCorpusSupplement(adapter)` | Additiver Memory-Such-/Lese-Korpus |
### Host-Hooks für Workflow-Plugins
-Host-Hooks sind die SDK-Seams für Plugins, die am Host-
+Host-Hooks sind die SDK-Schnittstellen für Plugins, die am Host-
Lifecycle teilnehmen müssen, statt nur einen Provider, Channel oder ein Tool hinzuzufügen. Sie sind
-generische Verträge; der Plan-Modus kann sie verwenden, aber ebenso Genehmigungs-Workflows,
+generische Verträge; Plan Mode kann sie verwenden, ebenso aber Approval-Workflows,
Workspace-Policy-Gates, Hintergrundmonitore, Einrichtungsassistenten und UI-Begleit-
Plugins.
-| Methode | Vertrag, den sie besitzt |
+| Methode | Vertrag, den sie besitzt |
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
-| `api.registerSessionExtension(...)` | Plugin-eigener, JSON-kompatibler Session-State, der über Gateway-Sessions projiziert wird |
-| `api.enqueueNextTurnInjection(...)` | Dauerhafter genau-einmal-Kontext, der für eine Session in den nächsten Agent-Turn injiziert wird |
-| `api.registerTrustedToolPolicy(...)` | Gebündelte/vertrauenswürdige Pre-Plugin-Tool-Policy, die Tool-Parameter blockieren oder umschreiben kann |
-| `api.registerToolMetadata(...)` | Tool-Katalog-Anzeigemetadaten ohne Änderung der Tool-Implementierung |
-| `api.registerCommand(...)` | Bereichsgebundene Plugin-Befehle; Befehlsergebnisse können `continueAgent: true` setzen; native Discord-Befehle unterstützen `descriptionLocalizations` |
-| `api.registerControlUiDescriptor(...)` | Control-UI-Contribution-Deskriptoren für Session-, Tool-, Run- oder Settings-Oberflächen |
+| `api.registerSessionExtension(...)` | Plugin-eigener, JSON-kompatibler Sitzungszustand, der über Gateway-Sitzungen projiziert wird |
+| `api.enqueueNextTurnInjection(...)` | Dauerhafter Exactly-once-Kontext, der in den nächsten Agent-Turn für eine Sitzung injiziert wird |
+| `api.registerTrustedToolPolicy(...)` | Gebündelte/vertrauenswürdige Pre-Plugin-Tool-Policy, die Tool-Parameter blockieren oder umschreiben kann |
+| `api.registerToolMetadata(...)` | Anzeige-Metadaten des Tool-Katalogs, ohne die Tool-Implementierung zu ändern |
+| `api.registerCommand(...)` | Scoped Plugin-Befehle; Befehlsergebnisse können `continueAgent: true` setzen; native Discord-Befehle unterstützen `descriptionLocalizations` |
+| `api.registerControlUiDescriptor(...)` | Control-UI-Beitragsdeskriptoren für Sitzungs-, Tool-, Lauf- oder Einstellungsoberflächen |
| `api.registerRuntimeLifecycle(...)` | Cleanup-Callbacks für Plugin-eigene Runtime-Ressourcen auf Reset-/Delete-/Reload-Pfaden |
-| `api.registerAgentEventSubscription(...)` | Bereinigte Event-Abonnements für Workflow-State und Monitore |
-| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Pro-Run-Plugin-Scratch-State, der beim terminalen Run-Lifecycle gelöscht wird |
-| `api.registerSessionSchedulerJob(...)` | Plugin-eigene Session-Scheduler-Job-Records mit deterministischem Cleanup |
+| `api.registerAgentEventSubscription(...)` | Bereinigte Event-Abonnements für Workflow-Zustand und Monitore |
+| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Plugin-Scratch-State pro Lauf, der beim terminalen Lauf-Lifecycle gelöscht wird |
+| `api.registerSessionSchedulerJob(...)` | Plugin-eigene Session-Scheduler-Job-Records mit deterministischem Cleanup |
-Die Verträge trennen die Autorität bewusst:
+Die Verträge teilen Autorität bewusst auf:
- Externe Plugins können Session-Erweiterungen, UI-Deskriptoren, Befehle, Tool-
Metadaten, Next-Turn-Injections und normale Hooks besitzen.
- Vertrauenswürdige Tool-Policies laufen vor gewöhnlichen `before_tool_call`-Hooks und sind
- nur gebündelten Plugins vorbehalten, weil sie an der Host-Sicherheits-Policy teilnehmen.
-- Reservierter Befehlsbesitz ist nur gebündelten Plugins vorbehalten. Externe Plugins sollten ihre
+ nur gebündelt, weil sie an der Host-Sicherheits-Policy teilnehmen.
+- Reservierter Befehlsbesitz ist nur gebündelt. Externe Plugins sollten ihre
eigenen Befehlsnamen oder Aliase verwenden.
-- `allowPromptInjection=false` deaktiviert promptverändernde Hooks einschließlich
+- `allowPromptInjection=false` deaktiviert prompt-verändernde Hooks einschließlich
`agent_turn_prepare`, `before_prompt_build`, `heartbeat_prompt_contribution`,
Prompt-Felder aus dem Legacy-`before_agent_start` und
`enqueueNextTurnInjection`.
-Beispiele für Nicht-Plan-Verbraucher:
+Beispiele für Nicht-Plan-Consumer:
| Plugin-Archetyp | Verwendete Hooks |
-| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| Genehmigungs-Workflow | Session-Erweiterung, Befehlsfortsetzung, Next-Turn-Injection, UI-Deskriptor |
-| Budget-/Workspace-Policy-Gate | Vertrauenswürdige Tool-Policy, Tool-Metadaten, Session-Projektion |
-| Hintergrund-Lifecycle-Monitor | Runtime-Lifecycle-Cleanup, Agent-Event-Abonnement, Besitz/Cleanup des Session-Schedulers, Heartbeat-Prompt-Beitrag, UI-Deskriptor |
-| Einrichtungs- oder Onboarding-Assistent | Session-Erweiterung, bereichsgebundene Befehle, Control-UI-Deskriptor |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Approval-Workflow | Session-Erweiterung, Befehlsfortsetzung, Next-Turn-Injection, UI-Deskriptor |
+| Budget-/Workspace-Policy-Gate | Vertrauenswürdige Tool-Policy, Tool-Metadaten, Sitzungsprojektion |
+| Hintergrund-Lifecycle-Monitor | Runtime-Lifecycle-Cleanup, Agent-Event-Abonnement, Session-Scheduler-Besitz/-Cleanup, Heartbeat-Prompt-Beitrag, UI-Deskriptor |
+| Einrichtungs- oder Onboarding-Assistent | Session-Erweiterung, scoped Befehle, Control-UI-Deskriptor |
Reservierte Core-Admin-Namespaces (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) bleiben immer `operator.admin`, selbst wenn ein Plugin versucht, einen
- schmaleren Gateway-Method-Scope zuzuweisen. Bevorzugen Sie Plugin-spezifische Präfixe für
+ engeren Gateway-Methoden-Scope zuzuweisen. Bevorzugen Sie Plugin-spezifische Präfixe für
Plugin-eigene Methoden.
Gebündelte Plugins können `api.registerAgentToolResultMiddleware(...)` verwenden, wenn
sie ein Tool-Ergebnis nach der Ausführung und bevor die Runtime
- dieses Ergebnis zurück in das Modell einspeist, umschreiben müssen. Dies ist der vertrauenswürdige, runtime-neutrale
- Seam für asynchrone Output-Reducer wie tokenjuice.
+ dieses Ergebnis zurück in das Modell einspeist, umschreiben müssen. Dies ist die vertrauenswürdige Runtime-neutrale
+ Schnittstelle für asynchrone Output-Reducer wie tokenjuice.
Gebündelte Plugins müssen `contracts.agentToolResultMiddleware` für jede
-zielgerichtete Runtime deklarieren, zum Beispiel `["pi", "codex"]`. Externe Plugins
+Ziel-Runtime deklarieren, zum Beispiel `["pi", "codex"]`. Externe Plugins
können diese Middleware nicht registrieren; verwenden Sie normale OpenClaw-Plugin-Hooks für Arbeit,
-die kein Pre-Model-Tool-Result-Timing benötigt. Der alte, nur für Pi geltende eingebettete
-Registrierungspfad der Erweiterungs-Factory wurde entfernt.
+die kein Timing für Tool-Ergebnisse vor dem Modell benötigt. Der alte, nur für Pi bestimmte eingebettete
+Registrierungspfad der Extension-Factory wurde entfernt.
### Gateway-Discovery-Registrierung
-`api.registerGatewayDiscoveryService(...)` ermöglicht es einem Plugin, den aktiven
-Gateway über einen lokalen Discovery-Transport wie mDNS/Bonjour bekanntzugeben. OpenClaw ruft den
-Dienst beim Start des Gateway auf, wenn lokale Discovery aktiviert ist, übergibt die
-aktuellen Gateway-Ports und nicht geheime TXT-Hinweisdaten und ruft beim Herunterfahren des Gateway den zurückgegebenen
-`stop`-Handler auf.
+`api.registerGatewayDiscoveryService(...)` ermöglicht einem Plugin, den aktiven
+Gateway über einen lokalen Erkennungstransport wie mDNS/Bonjour anzukündigen. OpenClaw ruft den
+Dienst während des Gateway-Starts auf, wenn lokale Erkennung aktiviert ist, übergibt die
+aktuellen Gateway-Ports und nicht geheimen TXT-Hinweisdaten und ruft beim
+Herunterfahren des Gateways den zurückgegebenen `stop`-Handler auf.
```typescript
api.registerGatewayDiscoveryService({
@@ -213,20 +213,20 @@ api.registerGatewayDiscoveryService({
});
```
-Gateway-Discovery-Plugins dürfen beworbene TXT-Werte nicht als Geheimnisse oder
-Authentifizierung behandeln. Discovery ist ein Routing-Hinweis; Gateway-Authentifizierung und TLS-Pinning
-bleiben für Vertrauen zuständig.
+Gateway-Erkennungs-Plugins dürfen angekündigte TXT-Werte nicht als Geheimnisse oder
+Authentifizierung behandeln. Erkennung ist ein Routing-Hinweis; Gateway-Authentifizierung und TLS-Pinning
+bleiben für die Vertrauensstellung zuständig.
### CLI-Registrierungsmetadaten
`api.registerCli(registrar, opts?)` akzeptiert zwei Arten von Metadaten auf oberster Ebene:
-- `commands`: explizite Befehlswurzeln, die dem Registrar gehören
-- `descriptors`: Befehlsdeskriptoren zur Parse-Zeit, die für Root-CLI-Hilfe,
- Routing und verzögerte Plugin-CLI-Registrierung verwendet werden
+- `commands`: explizite Befehlswurzeln im Besitz des Registrars
+- `descriptors`: Deskriptoren für Befehle zur Parse-Zeit, die für die Root-CLI-Hilfe,
+ das Routing und die verzögerte CLI-Registrierung von Plugins verwendet werden
Wenn ein Plugin-Befehl im normalen Root-CLI-Pfad verzögert geladen bleiben soll,
-stellen Sie `descriptors` bereit, die jede von diesem Registrar offengelegte
+stellen Sie `descriptors` bereit, die jede von diesem Registrar bereitgestellte
Befehlswurzel auf oberster Ebene abdecken.
```typescript
@@ -248,94 +248,98 @@ api.registerCli(
```
Verwenden Sie `commands` allein nur, wenn Sie keine verzögerte Root-CLI-Registrierung benötigen.
-Dieser eifrige Kompatibilitätspfad wird weiterhin unterstützt, installiert aber keine
+Dieser eifrige Kompatibilitätspfad wird weiterhin unterstützt, installiert jedoch keine
deskriptorbasierten Platzhalter für verzögertes Laden zur Parse-Zeit.
### CLI-Backend-Registrierung
-`api.registerCliBackend(...)` ermöglicht es einem Plugin, die Standardkonfiguration für ein lokales
+`api.registerCliBackend(...)` ermöglicht einem Plugin, die Standardkonfiguration für ein lokales
KI-CLI-Backend wie `codex-cli` zu besitzen.
- Die Backend-`id` wird zum Provider-Präfix in Modellreferenzen wie `codex-cli/gpt-5`.
- Die Backend-`config` verwendet dieselbe Form wie `agents.defaults.cliBackends.`.
-- Die Benutzerkonfiguration hat weiterhin Vorrang. OpenClaw führt `agents.defaults.cliBackends.` über der
- Plugin-Standardkonfiguration zusammen, bevor die CLI ausgeführt wird.
+- Die Benutzerkonfiguration hat weiterhin Vorrang. OpenClaw führt `agents.defaults.cliBackends.` mit dem
+ Plugin-Standard zusammen, bevor die CLI ausgeführt wird.
- Verwenden Sie `normalizeConfig`, wenn ein Backend nach dem Zusammenführen Kompatibilitätsumschreibungen benötigt
(zum Beispiel die Normalisierung alter Flag-Formen).
+- Verwenden Sie `resolveExecutionArgs` für anfragebezogene argv-Umschreibungen, die zum
+ CLI-Dialekt gehören, etwa das Zuordnen von OpenClaw-Denkstufen zu einem nativen Effort-Flag.
### Exklusive Slots
-| Methode | Was sie registriert |
-| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Methode | Was sie registriert |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `api.registerContextEngine(id, factory)` | Kontext-Engine (jeweils eine aktiv). Der `assemble()`-Callback erhält `availableTools` und `citationsMode`, damit die Engine Prompt-Ergänzungen anpassen kann. |
-| `api.registerMemoryCapability(capability)` | Einheitliche Speicherfähigkeit |
-| `api.registerMemoryPromptSection(builder)` | Builder für Speicher-Prompt-Abschnitte |
-| `api.registerMemoryFlushPlan(resolver)` | Resolver für Speicher-Flush-Pläne |
-| `api.registerMemoryRuntime(runtime)` | Speicher-Runtime-Adapter |
+| `api.registerMemoryCapability(capability)` | Einheitliche Memory-Funktion |
+| `api.registerMemoryPromptSection(builder)` | Builder für Memory-Prompt-Abschnitte |
+| `api.registerMemoryFlushPlan(resolver)` | Resolver für Memory-Flush-Pläne |
+| `api.registerMemoryRuntime(runtime)` | Memory-Runtime-Adapter |
-### Speicher-Embedding-Adapter
+### Memory-Embedding-Adapter
-| Methode | Was sie registriert |
-| ---------------------------------------------- | ------------------------------------------------ |
-| `api.registerMemoryEmbeddingProvider(adapter)` | Speicher-Embedding-Adapter für das aktive Plugin |
+| Methode | Was sie registriert |
+| ---------------------------------------------- | ---------------------------------------------------- |
+| `api.registerMemoryEmbeddingProvider(adapter)` | Memory-Embedding-Adapter für das aktive Plugin |
-- `registerMemoryCapability` ist die bevorzugte exklusive Speicher-Plugin-API.
-- `registerMemoryCapability` kann auch `publicArtifacts.listArtifacts(...)`
- offenlegen, damit Begleit-Plugins exportierte Speicherartefakte über
- `openclaw/plugin-sdk/memory-host-core` konsumieren können, statt in das private Layout eines bestimmten
- Speicher-Plugins zu greifen.
+- `registerMemoryCapability` ist die bevorzugte exklusive Memory-Plugin-API.
+- `registerMemoryCapability` kann außerdem `publicArtifacts.listArtifacts(...)`
+ bereitstellen, damit Begleit-Plugins exportierte Memory-Artefakte über
+ `openclaw/plugin-sdk/memory-host-core` nutzen können, statt auf das private Layout eines bestimmten
+ Memory-Plugins zuzugreifen.
- `registerMemoryPromptSection`, `registerMemoryFlushPlan` und
- `registerMemoryRuntime` sind legacy-kompatible exklusive Speicher-Plugin-APIs.
-- `MemoryFlushPlan.model` kann den Flush-Turn an eine exakte `provider/model`-Referenz
- wie `ollama/qwen3:8b` binden, ohne die aktive Fallback-Kette zu erben.
-- `registerMemoryEmbeddingProvider` ermöglicht es dem aktiven Speicher-Plugin, eine
+ `registerMemoryRuntime` sind abwärtskompatible exklusive Memory-Plugin-APIs.
+- `MemoryFlushPlan.model` kann den Flush-Turn an eine exakte `provider/model`-
+ Referenz wie `ollama/qwen3:8b` binden, ohne die aktive Fallback-
+ Kette zu übernehmen.
+- `registerMemoryEmbeddingProvider` ermöglicht dem aktiven Memory-Plugin, eine
oder mehrere Embedding-Adapter-IDs zu registrieren (zum Beispiel `openai`, `gemini` oder eine benutzerdefinierte
vom Plugin definierte ID).
-- Benutzerkonfigurationen wie `agents.defaults.memorySearch.provider` und
- `agents.defaults.memorySearch.fallback` werden gegen diese registrierten
+- Benutzerkonfiguration wie `agents.defaults.memorySearch.provider` und
+ `agents.defaults.memorySearch.fallback` wird gegen diese registrierten
Adapter-IDs aufgelöst.
### Ereignisse und Lebenszyklus
-| Methode | Was sie bewirkt |
-| -------------------------------------------- | -------------------------------- |
-| `api.on(hookName, handler, opts?)` | Typisierter Lebenszyklus-Hook |
-| `api.onConversationBindingResolved(handler)` | Conversation-Binding-Callback |
+| Methode | Was sie bewirkt |
+| -------------------------------------------- | ---------------------------------- |
+| `api.on(hookName, handler, opts?)` | Typisierter Lebenszyklus-Hook |
+| `api.onConversationBindingResolved(handler)` | Callback für Konversationsbindung |
-Siehe [Plugin-Hooks](/de/plugins/hooks) für Beispiele, gängige Hook-Namen und Guard-Semantik.
+Siehe [Plugin-Hooks](/de/plugins/hooks) für Beispiele, gängige Hook-Namen und Guard-
+Semantik.
-### Hook-Entscheidungssemantik
+### Semantik von Hook-Entscheidungen
-- `before_tool_call`: Die Rückgabe von `{ block: true }` ist terminal. Sobald ein Handler sie setzt, werden Handler mit niedrigerer Priorität übersprungen.
-- `before_tool_call`: Die Rückgabe von `{ block: false }` wird als keine Entscheidung behandelt (genauso wie das Weglassen von `block`), nicht als Override.
-- `before_install`: Die Rückgabe von `{ block: true }` ist terminal. Sobald ein Handler sie setzt, werden Handler mit niedrigerer Priorität übersprungen.
-- `before_install`: Die Rückgabe von `{ block: false }` wird als keine Entscheidung behandelt (genauso wie das Weglassen von `block`), nicht als Override.
-- `reply_dispatch`: Die Rückgabe von `{ handled: true, ... }` ist terminal. Sobald ein Handler den Dispatch beansprucht, werden Handler mit niedrigerer Priorität und der standardmäßige Modell-Dispatch-Pfad übersprungen.
-- `message_sending`: Die Rückgabe von `{ cancel: true }` ist terminal. Sobald ein Handler sie setzt, werden Handler mit niedrigerer Priorität übersprungen.
-- `message_sending`: Die Rückgabe von `{ cancel: false }` wird als keine Entscheidung behandelt (genauso wie das Weglassen von `cancel`), nicht als Override.
-- `message_received`: Verwenden Sie das typisierte Feld `threadId`, wenn Sie eingehendes Thread-/Themen-Routing benötigen. Behalten Sie `metadata` für kanalspezifische Extras bei.
+- `before_tool_call`: Die Rückgabe von `{ block: true }` ist terminal. Sobald ein Handler dies setzt, werden Handler mit niedrigerer Priorität übersprungen.
+- `before_tool_call`: Die Rückgabe von `{ block: false }` wird als keine Entscheidung behandelt (genauso wie das Weglassen von `block`), nicht als Überschreibung.
+- `before_install`: Die Rückgabe von `{ block: true }` ist terminal. Sobald ein Handler dies setzt, werden Handler mit niedrigerer Priorität übersprungen.
+- `before_install`: Die Rückgabe von `{ block: false }` wird als keine Entscheidung behandelt (genauso wie das Weglassen von `block`), nicht als Überschreibung.
+- `reply_dispatch`: Die Rückgabe von `{ handled: true, ... }` ist terminal. Sobald ein Handler den Versand beansprucht, werden Handler mit niedrigerer Priorität und der Standardpfad für den Modellversand übersprungen.
+- `message_sending`: Die Rückgabe von `{ cancel: true }` ist terminal. Sobald ein Handler dies setzt, werden Handler mit niedrigerer Priorität übersprungen.
+- `message_sending`: Die Rückgabe von `{ cancel: false }` wird als keine Entscheidung behandelt (genauso wie das Weglassen von `cancel`), nicht als Überschreibung.
+- `message_received`: Verwenden Sie das typisierte Feld `threadId`, wenn Sie eingehendes Thread-/Topic-Routing benötigen. Behalten Sie `metadata` für kanalspezifische Extras bei.
- `message_sending`: Verwenden Sie die typisierten Routing-Felder `replyToId` / `threadId`, bevor Sie auf kanalspezifische `metadata` zurückfallen.
-- `gateway_start`: Verwenden Sie `ctx.config`, `ctx.workspaceDir` und `ctx.getCron?.()` für den Gateway-eigenen Startzustand, statt sich auf interne `gateway:startup`-Hooks zu verlassen.
-- `cron_changed`: Beobachten Sie Gateway-eigene Änderungen am Cron-Lebenszyklus. Verwenden Sie `event.job?.state?.nextRunAtMs` und `ctx.getCron?.()`, wenn Sie externe Wake-Scheduler synchronisieren, und behalten Sie OpenClaw als Quelle der Wahrheit für Fälligkeitsprüfungen und Ausführung bei.
+- `gateway_start`: Verwenden Sie `ctx.config`, `ctx.workspaceDir` und `ctx.getCron?.()` für gatewayeigenen Startzustand, statt sich auf interne `gateway:startup`-Hooks zu verlassen.
+- `cron_changed`: Beobachten Sie gatewayeigene Cron-Lebenszyklusänderungen. Verwenden Sie `event.job?.state?.nextRunAtMs` und `ctx.getCron?.()`, wenn Sie externe Wake-Scheduler synchronisieren, und behalten Sie OpenClaw als Quelle der Wahrheit für Fälligkeitsprüfungen und Ausführung bei.
### API-Objektfelder
-| Feld | Typ | Beschreibung |
-| ------------------------ | ------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `api.id` | `string` | Plugin-ID |
-| `api.name` | `string` | Anzeigename |
-| `api.version` | `string?` | Plugin-Version (optional) |
-| `api.description` | `string?` | Plugin-Beschreibung (optional) |
-| `api.source` | `string` | Plugin-Quellpfad |
-| `api.rootDir` | `string?` | Plugin-Stammverzeichnis (optional) |
-| `api.config` | `OpenClawConfig` | Aktueller Konfigurations-Snapshot (aktiver In-Memory-Runtime-Snapshot, wenn verfügbar) |
-| `api.pluginConfig` | `Record` | Plugin-spezifische Konfiguration aus `plugins.entries..config` |
-| `api.runtime` | `PluginRuntime` | [Runtime-Helfer](/de/plugins/sdk-runtime) |
-| `api.logger` | `PluginLogger` | Bereichsbezogener Logger (`debug`, `info`, `warn`, `error`) |
-| `api.registrationMode` | `PluginRegistrationMode` | Aktueller Lademodus; `"setup-runtime"` ist das leichtgewichtige Start-/Setup-Fenster vor dem vollständigen Eintrag |
-| `api.resolvePath(input)` | `(string) => string` | Pfad relativ zum Plugin-Stamm auflösen |
+| Feld | Typ | Beschreibung |
+| ------------------------ | ------------------------- | -------------------------------------------------------------------------------------------------- |
+| `api.id` | `string` | Plugin-ID |
+| `api.name` | `string` | Anzeigename |
+| `api.version` | `string?` | Plugin-Version (optional) |
+| `api.description` | `string?` | Plugin-Beschreibung (optional) |
+| `api.source` | `string` | Plugin-Quellpfad |
+| `api.rootDir` | `string?` | Plugin-Stammverzeichnis (optional) |
+| `api.config` | `OpenClawConfig` | Aktueller Konfigurations-Snapshot (aktiver In-Memory-Runtime-Snapshot, wenn verfügbar) |
+| `api.pluginConfig` | `Record` | Plugin-spezifische Konfiguration aus `plugins.entries..config` |
+| `api.runtime` | `PluginRuntime` | [Runtime-Hilfsfunktionen](/de/plugins/sdk-runtime) |
+| `api.logger` | `PluginLogger` | Bereichsgebundener Logger (`debug`, `info`, `warn`, `error`) |
+| `api.registrationMode` | `PluginRegistrationMode` | Aktueller Lademodus; `"setup-runtime"` ist das schlanke Start-/Einrichtungsfenster vor dem vollständigen Einstieg |
+| `api.resolvePath(input)` | `(string) => string` | Pfad relativ zum Plugin-Stamm auflösen |
-## Interne Modulkonvention
+## Konvention für interne Module
Verwenden Sie innerhalb Ihres Plugins lokale Barrel-Dateien für interne Importe:
@@ -348,56 +352,56 @@ my-plugin/
```
- Importieren Sie Ihr eigenes Plugin niemals über `openclaw/plugin-sdk/`
- aus Produktionscode. Leiten Sie interne Importe über `./api.ts` oder
+ Importieren Sie Ihr eigenes Plugin in Produktionscode niemals über `openclaw/plugin-sdk/`.
+ Leiten Sie interne Importe über `./api.ts` oder
`./runtime-api.ts`. Der SDK-Pfad ist ausschließlich der externe Vertrag.
-Öffentliche Oberflächen gebündelter Plugins, die über Facades geladen werden (`api.ts`, `runtime-api.ts`,
-`index.ts`, `setup-entry.ts` und ähnliche öffentliche Einstiegdateien), bevorzugen den
+Über Facades geladene öffentliche Oberflächen gebündelter Plugins (`api.ts`, `runtime-api.ts`,
+`index.ts`, `setup-entry.ts` und ähnliche öffentliche Einstiegdateien) bevorzugen den
aktiven Runtime-Konfigurations-Snapshot, wenn OpenClaw bereits ausgeführt wird. Wenn noch kein Runtime-
-Snapshot existiert, fallen sie auf die aufgelöste Konfigurationsdatei auf dem Datenträger zurück.
-Paketierte gebündelte Plugin-Facades sollten über die Plugin-
+Snapshot vorhanden ist, fallen sie auf die aufgelöste Konfigurationsdatei auf der Festplatte zurück.
+Paketierte Facades gebündelter Plugins sollten über die Plugin-
Facade-Loader von OpenClaw geladen werden; direkte Importe aus `dist/extensions/...` umgehen die Manifest-
und Runtime-Sidecar-Prüfungen, die paketierte Installationen für Plugin-eigenen Code verwenden.
-Provider-Plugins können ein schmales Plugin-lokales Contract-Barrel offenlegen, wenn ein
-Helfer absichtlich Provider-spezifisch ist und noch nicht in einen generischen SDK-
+Provider-Plugins können ein schmales pluginlokales Vertrags-Barrel bereitstellen, wenn ein
+Hilfsprogramm absichtlich providerspezifisch ist und noch nicht in einen generischen SDK-
Unterpfad gehört. Gebündelte Beispiele:
-- **Anthropic**: öffentliche `api.ts`- / `contract-api.ts`-Schnittstelle für Claude-
- Beta-Header- und `service_tier`-Stream-Helfer.
+- **Anthropic**: öffentliche `api.ts`- / `contract-api.ts`-Nahtstelle für Claude-
+ Beta-Header- und `service_tier`-Stream-Hilfsfunktionen.
- **`@openclaw/openai-provider`**: `api.ts` exportiert Provider-Builder,
- Standardmodell-Helfer und Realtime-Provider-Builder.
+ Hilfsfunktionen für Standardmodelle und Realtime-Provider-Builder.
- **`@openclaw/openrouter-provider`**: `api.ts` exportiert den Provider-Builder
- plus Onboarding-/Konfigurationshelfer.
+ sowie Hilfsfunktionen für Onboarding/Konfiguration.
- Produktionscode von Erweiterungen sollte auch Importe von `openclaw/plugin-sdk/`
- vermeiden. Wenn ein Helfer wirklich geteilt wird, heben Sie ihn in einen neutralen SDK-Unterpfad
+ Produktionscode von Plugins sollte ebenfalls Importe aus `openclaw/plugin-sdk/`
+ vermeiden. Wenn ein Hilfsprogramm wirklich gemeinsam genutzt wird, heben Sie es auf einen neutralen SDK-Unterpfad
wie `openclaw/plugin-sdk/speech`, `.../provider-model-shared` oder eine andere
- fähigkeitsorientierte Oberfläche, statt zwei Plugins miteinander zu koppeln.
+ funktionsorientierte Oberfläche, statt zwei Plugins miteinander zu koppeln.
-## Verwandt
+## Verwandte
Optionen für `definePluginEntry` und `defineChannelPluginEntry`.
- Vollständige Referenz des Namespace `api.runtime`.
+ Vollständige Referenz für den Namespace `api.runtime`.
Paketierung, Manifeste und Konfigurationsschemas.
-
- Test-Hilfsprogramme und Lint-Regeln.
+
+ Testhilfen und Lint-Regeln.
Migration von veralteten Oberflächen.
-
- Detaillierte Architektur und Fähigkeitsmodell.
+
+ Tiefgehende Architektur und Capability-Modell.
diff --git a/docs/de/security/network-proxy.md b/docs/de/security/network-proxy.md
index 0903475c6..38a491ec7 100644
--- a/docs/de/security/network-proxy.md
+++ b/docs/de/security/network-proxy.md
@@ -1,40 +1,40 @@
---
read_when:
- - Sie möchten Defense-in-Depth gegen SSRF- und DNS-Rebinding-Angriffe
- - Konfigurieren eines externen Forward-Proxys für OpenClaw-Laufzeitdatenverkehr
-summary: So leiten Sie den HTTP- und WebSocket-Verkehr der OpenClaw-Laufzeitumgebung über einen vom Betreiber verwalteten Filter-Proxy weiter
+ - Sie möchten mehrschichtigen Schutz gegen SSRF- und DNS-Rebinding-Angriffe
+ - Externen Forward-Proxy für OpenClaw-Runtime-Datenverkehr konfigurieren
+summary: So leiten Sie den HTTP- und WebSocket-Datenverkehr der OpenClaw-Laufzeit über einen vom Betreiber verwalteten Filter-Proxy
title: Netzwerk-Proxy
x-i18n:
- generated_at: "2026-05-04T06:43:57Z"
+ generated_at: "2026-05-04T18:24:31Z"
model: gpt-5.5
provider: openai
- source_hash: fc7140c5ced0e7454a6f85d1ea8f3256bbd28cc0cb42eeafe8e5e6439b90e3f0
+ source_hash: eedbf3bac14800c34c7ca2e3b6879dac360a88d51b5b7449ddf41a4dd471648b
source_path: security/network-proxy.md
workflow: 16
---
-# Netzwerkproxy
+# Netzwerk-Proxy
-OpenClaw kann HTTP- und WebSocket-Traffic zur Laufzeit über einen vom Betreiber verwalteten Forward Proxy leiten. Dies ist eine optionale Defense-in-Depth-Maßnahme für Deployments, die zentrale Egress-Kontrolle, stärkeren SSRF-Schutz und bessere Netzwerk-Auditierbarkeit wünschen.
+OpenClaw kann HTTP- und WebSocket-Datenverkehr zur Laufzeit über einen vom Betreiber verwalteten Forward-Proxy leiten. Dies ist eine optionale mehrschichtige Schutzmaßnahme für Bereitstellungen, die zentrale Egress-Kontrolle, stärkeren SSRF-Schutz und bessere Überprüfbarkeit des Netzwerks wünschen.
-OpenClaw liefert, lädt, startet, konfiguriert oder zertifiziert keinen Proxy. Sie betreiben die Proxy-Technologie, die zu Ihrer Umgebung passt, und OpenClaw leitet normale prozesslokale HTTP- und WebSocket-Clients darüber.
+OpenClaw liefert keinen Proxy mit, lädt keinen Proxy herunter, startet, konfiguriert oder zertifiziert keinen Proxy. Sie betreiben die Proxy-Technologie, die zu Ihrer Umgebung passt, und OpenClaw leitet normale prozesslokale HTTP- und WebSocket-Clients darüber.
## Warum einen Proxy verwenden?
-Ein Proxy gibt Betreibern einen zentralen Netzwerkkontrollpunkt für ausgehenden HTTP- und WebSocket-Traffic. Das kann auch außerhalb von SSRF-Härtung nützlich sein:
+Ein Proxy gibt Betreibern einen zentralen Netzwerk-Kontrollpunkt für ausgehenden HTTP- und WebSocket-Datenverkehr. Das kann auch außerhalb der SSRF-Härtung nützlich sein:
-- Zentrale Richtlinie: pflegen Sie eine Egress-Richtlinie, statt sich darauf zu verlassen, dass jede HTTP-Aufrufstelle der Anwendung die Netzwerkregeln korrekt umsetzt.
-- Prüfungen zur Verbindungszeit: bewerten Sie das Ziel nach der DNS-Auflösung und unmittelbar bevor der Proxy die Upstream-Verbindung öffnet.
-- DNS-Rebinding-Abwehr: verringern Sie die Lücke zwischen einer DNS-Prüfung auf Anwendungsebene und der tatsächlichen ausgehenden Verbindung.
-- Breitere JavaScript-Abdeckung: leiten Sie gewöhnliche Clients wie `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch und ähnliche über denselben Pfad.
-- Auditierbarkeit: protokollieren Sie erlaubte und abgelehnte Ziele an der Egress-Grenze.
-- Betriebliche Kontrolle: setzen Sie Zielregeln, Netzwerksegmentierung, Rate Limits oder ausgehende Allowlists durch, ohne OpenClaw neu zu bauen.
+- Zentrale Richtlinie: Pflegen Sie eine Egress-Richtlinie, statt sich darauf zu verlassen, dass jede HTTP-Aufrufstelle der Anwendung die Netzwerkregeln korrekt umsetzt.
+- Prüfungen zur Verbindungszeit: Bewerten Sie das Ziel nach der DNS-Auflösung und unmittelbar bevor der Proxy die Upstream-Verbindung öffnet.
+- Schutz vor DNS-Rebinding: Reduzieren Sie die Lücke zwischen einer DNS-Prüfung auf Anwendungsebene und der tatsächlichen ausgehenden Verbindung.
+- Breitere JavaScript-Abdeckung: Leiten Sie gewöhnliche `fetch`-, `node:http`-, `node:https`-, WebSocket-, axios-, got-, node-fetch- und ähnliche Clients über denselben Pfad.
+- Überprüfbarkeit: Protokollieren Sie erlaubte und verweigerte Ziele an der Egress-Grenze.
+- Betriebliche Kontrolle: Erzwingen Sie Zielregeln, Netzwerksegmentierung, Ratenlimits oder ausgehende Allowlists, ohne OpenClaw neu zu bauen.
-Proxy-Routing ist eine Schutzplanke auf Prozessebene für normalen HTTP- und WebSocket-Egress. Es gibt Betreibern einen Fail-Closed-Pfad, um unterstützte JavaScript-HTTP-Clients über ihren eigenen filternden Proxy zu leiten, ist aber keine Netzwerk-Sandbox auf Betriebssystemebene und sorgt nicht dafür, dass OpenClaw die Zielrichtlinie des Proxys zertifiziert.
+Proxy-Routing ist eine Guardrail auf Prozessebene für normalen HTTP- und WebSocket-Egress. Es gibt Betreibern einen Fail-Closed-Pfad, um unterstützte JavaScript-HTTP-Clients über ihren eigenen filternden Proxy zu leiten, ist aber keine Netzwerk-Sandbox auf Betriebssystemebene und bedeutet nicht, dass OpenClaw die Zielrichtlinie des Proxys zertifiziert.
-## Wie OpenClaw Traffic leitet
+## Wie OpenClaw Datenverkehr leitet
-Wenn `proxy.enabled=true` gesetzt und eine Proxy-URL konfiguriert ist, leiten geschützte Laufzeitprozesse wie `openclaw gateway run`, `openclaw node run` und `openclaw agent --local` normalen HTTP- und WebSocket-Egress über den konfigurierten Proxy:
+Wenn `proxy.enabled=true` ist und eine Proxy-URL konfiguriert wurde, leiten geschützte Laufzeitprozesse wie `openclaw gateway run`, `openclaw node run` und `openclaw agent --local` normalen HTTP- und WebSocket-Egress über den konfigurierten Proxy:
```text
OpenClaw process
@@ -43,27 +43,27 @@ OpenClaw process
WebSocket clients -> operator-managed filtering proxy -> public internet
```
-Der öffentliche Vertrag ist das Routing-Verhalten, nicht die internen Node-Hooks, mit denen es implementiert wird. OpenClaw Gateway Control-Plane-WebSocket-Clients verwenden einen schmalen direkten Pfad für local loopback Gateway-RPC-Traffic, wenn die Gateway-URL `localhost` oder eine wörtliche Loopback-IP wie `127.0.0.1` oder `[::1]` verwendet. Dieser Control-Plane-Pfad muss Loopback-Gateways erreichen können, selbst wenn der Betreiber-Proxy Loopback-Ziele blockiert. Normale HTTP- und WebSocket-Anfragen zur Laufzeit verwenden weiterhin den konfigurierten Proxy.
+Der öffentliche Vertrag ist das Routing-Verhalten, nicht die internen Node-Hooks, mit denen es implementiert wird. OpenClaw Gateway-Control-Plane-WebSocket-Clients verwenden einen schmalen direkten Pfad für lokalen Gateway-RPC-Datenverkehr über local loopback, wenn die Gateway-URL `localhost` oder eine wörtliche Loopback-IP wie `127.0.0.1` oder `[::1]` verwendet. Dieser Control-Plane-Pfad muss Loopback-Gateways erreichen können, selbst wenn der Betreiber-Proxy Loopback-Ziele blockiert. Normale HTTP- und WebSocket-Anfragen zur Laufzeit verwenden weiterhin den konfigurierten Proxy.
-Intern verwendet OpenClaw zwei Routing-Hooks auf Prozessebene für diese Funktion:
+Intern verwendet OpenClaw für diese Funktion zwei Routing-Hooks auf Prozessebene:
- Undici-Dispatcher-Routing deckt `fetch`, Undici-basierte Clients und Transports ab, die ihren eigenen Undici-Dispatcher bereitstellen.
-- `global-agent`-Routing deckt Aufrufer von Node-Core `node:http` und `node:https` ab, einschließlich vieler Bibliotheken, die auf `http.request`, `https.request`, `http.get` und `https.get` aufbauen. Der verwaltete Proxy-Modus erzwingt diesen globalen Agent, damit explizite Node-HTTP-Agents den Betreiber-Proxy nicht versehentlich umgehen.
+- `global-agent`-Routing deckt Node-Core-Aufrufer von `node:http` und `node:https` ab, einschließlich vieler Bibliotheken, die auf `http.request`, `https.request`, `http.get` und `https.get` aufbauen. Der verwaltete Proxy-Modus erzwingt diesen globalen Agent, damit explizite Node-HTTP-Agents den Betreiber-Proxy nicht versehentlich umgehen.
-Einige Plugins besitzen eigene Transports, die explizite Proxy-Verdrahtung benötigen, auch wenn Routing auf Prozessebene vorhanden ist. Beispielsweise verwendet der Bot-API-Transport von Telegram seinen eigenen HTTP/1-Undici-Dispatcher und berücksichtigt daher Prozess-Proxy-Umgebungsvariablen plus den verwalteten `OPENCLAW_PROXY_URL`-Fallback in diesem owner-spezifischen Transportpfad.
+Einige Plugins besitzen eigene Transports, die eine explizite Proxy-Verdrahtung benötigen, auch wenn Routing auf Prozessebene vorhanden ist. Beispielsweise verwendet der Bot-API-Transport von Telegram seinen eigenen HTTP/1-Undici-Dispatcher und berücksichtigt deshalb die Prozess-Proxy-Umgebung plus den verwalteten `OPENCLAW_PROXY_URL`-Fallback in diesem owner-spezifischen Transport-Pfad.
-Die Proxy-URL selbst muss `http://` verwenden. HTTPS-Ziele werden weiterhin über den Proxy mit HTTP `CONNECT` unterstützt; dies bedeutet nur, dass OpenClaw einen einfachen HTTP-Forward-Proxy-Listener wie `http://127.0.0.1:3128` erwartet.
+Die Proxy-URL selbst muss `http://` verwenden. HTTPS-Ziele werden über den Proxy weiterhin mit HTTP `CONNECT` unterstützt; das bedeutet lediglich, dass OpenClaw einen einfachen HTTP-Forward-Proxy-Listener wie `http://127.0.0.1:3128` erwartet.
-Während der Proxy aktiv ist, löscht OpenClaw `no_proxy`, `NO_PROXY` und `GLOBAL_AGENT_NO_PROXY`. Diese Bypass-Listen sind zielbasiert, sodass `localhost` oder `127.0.0.1` dort dazu führen würde, dass SSRF-Ziele mit hohem Risiko den filternden Proxy umgehen.
+Während der Proxy aktiv ist, entfernt OpenClaw `no_proxy`, `NO_PROXY` und `GLOBAL_AGENT_NO_PROXY`. Diese Umgehungslisten sind zielbasiert; wenn dort `localhost` oder `127.0.0.1` verbleiben würde, könnten risikoreiche SSRF-Ziele den filternden Proxy überspringen.
-Beim Herunterfahren stellt OpenClaw die vorherige Proxy-Umgebung wieder her und setzt den zwischengespeicherten Prozess-Routing-Zustand zurück.
+Beim Herunterfahren stellt OpenClaw die vorherige Proxy-Umgebung wieder her und setzt zwischengespeicherten Prozess-Routing-Status zurück.
## Verwandte Proxy-Begriffe
- `proxy.enabled` / `proxy.proxyUrl`: ausgehendes Forward-Proxy-Routing für OpenClaw-Laufzeit-Egress. Diese Seite dokumentiert diese Funktion.
-- `gateway.auth.mode: "trusted-proxy"`: eingehende identitätsbewusste Reverse-Proxy-Authentifizierung für Gateway-Zugriff. Siehe [Trusted-Proxy-Authentifizierung](/de/gateway/trusted-proxy-auth).
-- `openclaw proxy`: lokaler Debug-Proxy und Erfassungsinspektor für Entwicklung und Support. Siehe [openclaw proxy](/de/cli/proxy).
-- Channel- oder Provider-spezifische Proxy-Einstellungen: owner-spezifische Overrides für einen bestimmten Transport. Bevorzugen Sie den verwalteten Netzwerkproxy, wenn das Ziel zentrale Egress-Kontrolle über die Laufzeit hinweg ist.
+- `gateway.auth.mode: "trusted-proxy"`: eingehende identitätsbewusste Reverse-Proxy-Authentifizierung für Gateway-Zugriff. Siehe [Authentifizierung über vertrauenswürdigen Proxy](/de/gateway/trusted-proxy-auth).
+- `openclaw proxy`: lokaler Debug-Proxy und Capture-Inspector für Entwicklung und Support. Siehe [openclaw proxy](/de/cli/proxy).
+- Kanal- oder Provider-spezifische Proxy-Einstellungen: owner-spezifische Überschreibungen für einen bestimmten Transport. Bevorzugen Sie den verwalteten Netzwerk-Proxy, wenn das Ziel eine zentrale Egress-Kontrolle über die Laufzeit hinweg ist.
## Konfiguration
@@ -81,7 +81,7 @@ OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
`proxy.proxyUrl` hat Vorrang vor `OPENCLAW_PROXY_URL`.
-Wenn `enabled=true` gesetzt ist, aber keine gültige Proxy-URL konfiguriert ist, schlagen geschützte Befehle beim Start fehl, statt auf direkten Netzwerkzugriff zurückzufallen.
+Wenn `enabled=true` ist, aber keine gültige Proxy-URL konfiguriert wurde, schlagen geschützte Befehle beim Start fehl, statt auf direkten Netzwerkzugriff zurückzufallen.
Für verwaltete Gateway-Dienste, die mit `openclaw gateway start` gestartet werden, sollten Sie die URL bevorzugt in der Konfiguration speichern:
@@ -92,40 +92,40 @@ openclaw gateway install --force
openclaw gateway start
```
-Der Umgebungs-Fallback eignet sich am besten für Vordergrundausführungen. Wenn Sie ihn mit einem installierten Dienst verwenden, legen Sie `OPENCLAW_PROXY_URL` in die dauerhafte Dienstumgebung, etwa `$OPENCLAW_STATE_DIR/.env` oder `~/.openclaw/.env`, und installieren Sie den Dienst anschließend neu, damit launchd, systemd oder Scheduled Tasks das Gateway mit diesem Wert starten.
+Der Umgebungs-Fallback eignet sich am besten für Vordergrundläufe. Wenn Sie ihn mit einem installierten Dienst verwenden, legen Sie `OPENCLAW_PROXY_URL` in der dauerhaften Umgebung des Dienstes ab, etwa in `$OPENCLAW_STATE_DIR/.env` oder `~/.openclaw/.env`, und installieren Sie den Dienst anschließend neu, damit launchd, systemd oder Geplante Aufgaben das Gateway mit diesem Wert startet.
-Für `openclaw --container ...`-Befehle leitet OpenClaw `OPENCLAW_PROXY_URL` an die containerbezogene untergeordnete CLI weiter, wenn sie gesetzt ist. Die URL muss aus dem Container heraus erreichbar sein; `127.0.0.1` verweist auf den Container selbst, nicht auf den Host. OpenClaw lehnt Loopback-Proxy-URLs für containerbezogene Befehle ab, sofern Sie diese Sicherheitsprüfung nicht ausdrücklich außer Kraft setzen.
+Für `openclaw --container ...`-Befehle leitet OpenClaw `OPENCLAW_PROXY_URL` an die containerbezogene Child-CLI weiter, wenn es gesetzt ist. Die URL muss aus dem Container heraus erreichbar sein; `127.0.0.1` verweist auf den Container selbst, nicht auf den Host. OpenClaw weist Loopback-Proxy-URLs für containerbezogene Befehle zurück, es sei denn, Sie überschreiben diese Sicherheitsprüfung ausdrücklich.
## Proxy-Anforderungen
-Die Proxy-Richtlinie ist die Sicherheitsgrenze. OpenClaw kann nicht verifizieren, dass der Proxy die richtigen Ziele blockiert.
+Die Proxy-Richtlinie ist die Sicherheitsgrenze. OpenClaw kann nicht überprüfen, ob der Proxy die richtigen Ziele blockiert.
Konfigurieren Sie den Proxy so, dass er:
-- nur an Loopback oder eine private vertrauenswürdige Schnittstelle bindet.
-- den Zugriff so beschränkt, dass nur der OpenClaw-Prozess, Host, Container oder das Dienstkonto ihn verwenden kann.
+- Nur an Loopback oder eine private vertrauenswürdige Schnittstelle bindet.
+- Den Zugriff so einschränkt, dass nur der OpenClaw-Prozess, Host, Container oder das Dienstkonto ihn verwenden kann.
- Ziele selbst auflöst und Ziel-IPs nach der DNS-Auflösung blockiert.
- Richtlinien zur Verbindungszeit sowohl für einfache HTTP-Anfragen als auch für HTTPS-`CONNECT`-Tunnel anwendet.
-- zielbasierte Bypässe für Loopback-, private, link-lokale, Metadata-, Multicast-, reservierte oder Dokumentationsbereiche ablehnt.
-- Hostname-Allowlists vermeidet, sofern Sie dem DNS-Auflösungspfad nicht vollständig vertrauen.
-- Ziel, Entscheidung, Status und Grund protokolliert, ohne Request-Bodys, Autorisierungs-Header, Cookies oder andere Geheimnisse zu protokollieren.
-- die Proxy-Richtlinie unter Versionskontrolle hält und Änderungen wie sicherheitssensitive Konfiguration prüft.
+- Zielbasierte Umgehungen für Loopback-, private, link-lokale, Metadaten-, Multicast-, reservierte oder Dokumentationsbereiche ablehnt.
+- Hostname-Allowlists vermeidet, es sei denn, Sie vertrauen dem DNS-Auflösungspfad vollständig.
+- Ziel, Entscheidung, Status und Grund protokolliert, ohne Anfragetexte, Autorisierungs-Header, Cookies oder andere Geheimnisse zu protokollieren.
+- Proxy-Richtlinien unter Versionskontrolle hält und Änderungen wie sicherheitssensitive Konfiguration prüft.
## Empfohlene blockierte Ziele
-Verwenden Sie diese Denylist als Ausgangspunkt für jeden Forward Proxy, jede Firewall oder jede Egress-Richtlinie.
+Verwenden Sie diese Denylist als Ausgangspunkt für jeden Forward-Proxy sowie jede Firewall- oder Egress-Richtlinie.
-Die Klassifizierungslogik auf OpenClaw-Anwendungsebene befindet sich in `src/infra/net/ssrf.ts` und `src/shared/net/ip.ts`. Die relevanten Paritäts-Hooks sind `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` und die eingebettete IPv4-Sentinel-Behandlung für NAT64, 6to4, Teredo, ISATAP und IPv4-mapped-Formen. Diese Dateien sind nützliche Referenzen, wenn Sie eine externe Proxy-Richtlinie pflegen, aber OpenClaw exportiert oder erzwingt diese Regeln nicht automatisch in Ihrem Proxy.
+Die Klassifizierungslogik auf OpenClaw-Anwendungsebene befindet sich in `src/infra/net/ssrf.ts` und `src/shared/net/ip.ts`. Die relevanten Paritäts-Hooks sind `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` und die eingebettete IPv4-Sentinel-Behandlung für NAT64, 6to4, Teredo, ISATAP und IPv4-gemappte Formen. Diese Dateien sind nützliche Referenzen bei der Pflege einer externen Proxy-Richtlinie, aber OpenClaw exportiert oder erzwingt diese Regeln nicht automatisch in Ihrem Proxy.
-| Bereich oder Host | Warum blockieren |
+| Bereich oder Host | Warum blockieren |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------- |
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4-Loopback |
| `::1/128` | IPv6-Loopback |
-| `0.0.0.0/8`, `::/128` | Nicht spezifizierte und This-Network-Adressen |
+| `0.0.0.0/8`, `::/128` | Nicht angegebene und This-Network-Adressen |
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Private Netzwerke nach RFC1918 |
-| `169.254.0.0/16`, `fe80::/10` | Link-lokale Adressen und gängige Cloud-Metadata-Pfade |
-| `169.254.169.254`, `metadata.google.internal` | Cloud-Metadata-Dienste |
-| `100.64.0.0/10` | Gemeinsamer Adressraum für Carrier-grade NAT |
+| `169.254.0.0/16`, `fe80::/10` | Link-lokale Adressen und gängige Cloud-Metadatenpfade |
+| `169.254.169.254`, `metadata.google.internal` | Cloud-Metadatendienste |
+| `100.64.0.0/10` | Gemeinsamer Adressraum für Carrier-Grade-NAT |
| `198.18.0.0/15`, `2001:2::/48` | Benchmarking-Bereiche |
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Special-Use- und Dokumentationsbereiche |
| `224.0.0.0/4`, `ff00::/8` | Multicast |
@@ -134,9 +134,9 @@ Die Klassifizierungslogik auf OpenClaw-Anwendungsebene befindet sich in `src/inf
| `100::/64`, `2001:20::/28` | IPv6-Discard- und ORCHIDv2-Bereiche |
| `64:ff9b::/96`, `64:ff9b:1::/48` | NAT64-Präfixe mit eingebettetem IPv4 |
| `2002::/16`, `2001::/32` | 6to4 und Teredo mit eingebettetem IPv4 |
-| `::/96`, `::ffff:0:0/96` | IPv4-kompatibles und IPv4-mapped IPv6 |
+| `::/96`, `::ffff:0:0/96` | IPv4-kompatibles und IPv4-gemapptes IPv6 |
-Wenn Ihr Cloud-Provider oder Ihre Netzwerkplattform zusätzliche Metadata-Hosts oder reservierte Bereiche dokumentiert, fügen Sie diese ebenfalls hinzu.
+Wenn Ihr Cloud-Provider oder Ihre Netzwerkplattform zusätzliche Metadaten-Hosts oder reservierte Bereiche dokumentiert, fügen Sie diese ebenfalls hinzu.
## Validierung
@@ -146,9 +146,9 @@ Validieren Sie den Proxy von demselben Host, Container oder Dienstkonto aus, auf
openclaw proxy validate --proxy-url http://127.0.0.1:3128
```
-Standardmäßig prüft der Befehl, wenn keine benutzerdefinierten Ziele bereitgestellt werden, dass `https://example.com/` erfolgreich ist, und startet einen temporären Loopback-Canary, den der Proxy nicht erreichen darf. Die standardmäßige Ablehnungsprüfung gilt als bestanden, wenn der Proxy eine Nicht-2xx-Ablehnungsantwort zurückgibt oder den Canary mit einem Transportfehler blockiert; sie schlägt fehl, wenn eine erfolgreiche Antwort den Canary erreicht. Wenn kein Proxy aktiviert und konfiguriert ist, meldet die Validierung ein Konfigurationsproblem; verwenden Sie `--proxy-url` für einen einmaligen Preflight, bevor Sie die Konfiguration ändern. Verwenden Sie `--allowed-url` und `--denied-url`, um deployment-spezifische Erwartungen zu testen. Benutzerdefinierte abgelehnte Ziele sind Fail-Closed: Jede HTTP-Antwort bedeutet, dass das Ziel über den Proxy erreichbar war, und jeder Transportfehler wird als nicht schlüssig gemeldet, weil OpenClaw nicht beweisen kann, dass der Proxy einen erreichbaren Ursprung blockiert hat. Bei einem Validierungsfehler beendet sich der Befehl mit Code 1.
+Standardmäßig prüft der Befehl, wenn keine benutzerdefinierten Ziele angegeben werden, dass `https://example.com/` erfolgreich ist, und startet einen temporären Loopback-Canary, den der Proxy nicht erreichen darf. Die standardmäßige verweigerte Prüfung gilt als bestanden, wenn der Proxy eine Nicht-2xx-Verweigerungsantwort zurückgibt oder den Canary mit einem Transportfehler blockiert; sie schlägt fehl, wenn eine erfolgreiche Antwort den Canary erreicht. Wenn kein Proxy aktiviert und konfiguriert ist, meldet die Validierung ein Konfigurationsproblem; verwenden Sie `--proxy-url` für einen einmaligen Preflight, bevor Sie die Konfiguration ändern. Verwenden Sie `--allowed-url` und `--denied-url`, um bereitstellungsspezifische Erwartungen zu testen. Fügen Sie `--apns-reachable` hinzu, um außerdem zu prüfen, ob direkte APNs-HTTP/2-Zustellung einen CONNECT-Tunnel durch den Proxy öffnen und eine Sandbox-APNs-Antwort empfangen kann; die Prüfung verwendet absichtlich ein ungültiges Provider-Token, daher wird `403 InvalidProviderToken` erwartet und zählt als erreichbar. Benutzerdefinierte verweigerte Ziele sind Fail-Closed: Jede HTTP-Antwort bedeutet, dass das Ziel über den Proxy erreichbar war, und jeder Transportfehler wird als nicht eindeutig gemeldet, weil OpenClaw nicht beweisen kann, dass der Proxy einen erreichbaren Ursprung blockiert hat. Bei einem Validierungsfehler beendet sich der Befehl mit Code 1.
-Verwenden Sie `--json` für Automatisierung. Die JSON-Ausgabe enthält das Gesamtergebnis, die effektive Proxy-Konfigurationsquelle, etwaige Konfigurationsfehler und jede Zielprüfung. Proxy-URL-Anmeldedaten werden in Text- und JSON-Ausgabe geschwärzt:
+Verwenden Sie `--json` für Automatisierung. Die JSON-Ausgabe enthält das Gesamtergebnis, die effektive Proxy-Konfigurationsquelle, alle Konfigurationsfehler und jede Zielprüfung. Zugangsdaten in Proxy-URLs werden in Text- und JSON-Ausgabe redigiert:
```json
{
@@ -165,12 +165,18 @@ Verwenden Sie `--json` für Automatisierung. Die JSON-Ausgabe enthält das Gesam
"url": "https://example.com/",
"ok": true,
"status": 200
+ },
+ {
+ "kind": "apns",
+ "url": "https://api.sandbox.push.apple.com",
+ "ok": true,
+ "status": 403
}
]
}
```
-Sie können die Validierung auch manuell mit `curl` durchführen:
+Sie können auch manuell mit `curl` validieren:
```bash
curl -x http://127.0.0.1:3128 https://example.com/
@@ -178,7 +184,7 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/
curl -x http://127.0.0.1:3128 http://169.254.169.254/
```
-Die öffentliche Anfrage sollte erfolgreich sein. Die Loopback- und Metadatenanfragen sollten vom Proxy blockiert werden. Bei `openclaw proxy validate` kann der integrierte Loopback-Canary eine Proxy-Ablehnung von einem erreichbaren Ursprungsziel unterscheiden. Benutzerdefinierte `--denied-url`-Prüfungen haben diesen Canary nicht. Behandeln Sie daher sowohl HTTP-Antworten als auch uneindeutige Transportfehler als Validierungsfehler, es sei denn, Ihr Proxy stellt ein bereitstellungsspezifisches Ablehnungssignal bereit, das Sie separat verifizieren können.
+Die öffentliche Anfrage sollte erfolgreich sein. Die Loopback- und Metadatenanfragen sollten vom Proxy blockiert werden. Bei `openclaw proxy validate` kann die integrierte Loopback-Canary-Prüfung eine Proxy-Ablehnung von einem erreichbaren Ursprung unterscheiden. Benutzerdefinierte `--denied-url`-Prüfungen haben diese Canary-Prüfung nicht. Behandeln Sie daher sowohl HTTP-Antworten als auch mehrdeutige Transportfehler als Validierungsfehler, es sei denn, Ihr Proxy stellt ein bereitstellungsspezifisches Ablehnungssignal bereit, das Sie separat verifizieren können.
Aktivieren Sie anschließend das OpenClaw-Proxy-Routing:
@@ -188,7 +194,7 @@ openclaw config set proxy.proxyUrl http://127.0.0.1:3128
openclaw gateway run
```
-oder legen Sie Folgendes fest:
+oder legen Sie fest:
```yaml
proxy:
@@ -199,10 +205,10 @@ proxy:
## Einschränkungen
- Der Proxy verbessert die Abdeckung für prozesslokale JavaScript-HTTP- und WebSocket-Clients, ist aber keine Netzwerk-Sandbox auf Betriebssystemebene.
-- Raw-`net`-, `tls`- und `http2`-Sockets, native Add-ons und untergeordnete Prozesse können das Proxy-Routing auf Node-Ebene umgehen, sofern sie Proxy-Umgebungsvariablen nicht erben und respektieren.
-- IRC ist ein Raw-TCP/TLS-Kanal außerhalb des vom Betreiber verwalteten Forward-Proxy-Routings. Legen Sie in Bereitstellungen, die sämtlichen ausgehenden Datenverkehr über diesen Forward Proxy erzwingen, `channels.irc.enabled=false` fest, sofern direkter ausgehender IRC-Datenverkehr nicht ausdrücklich genehmigt ist.
-- Der lokale Debug-Proxy ist Diagnosewerkzeug, und seine direkte Upstream-Weiterleitung für Proxy-Anfragen und CONNECT-Tunnel ist standardmäßig deaktiviert, solange der verwaltete Proxy-Modus aktiv ist. Aktivieren Sie die direkte Weiterleitung nur für genehmigte lokale Diagnosen.
-- Lokale WebUIs von Benutzern und lokale Modellserver sollten bei Bedarf in der Betreiber-Proxy-Richtlinie auf die Allowlist gesetzt werden. OpenClaw stellt für sie keine allgemeine Umgehung des lokalen Netzwerks bereit.
-- Die Proxy-Umgehung der Gateway-Control-Plane ist absichtlich auf `localhost` und wörtliche Loopback-IP-URLs beschränkt. Verwenden Sie `ws://127.0.0.1:18789`, `ws://[::1]:18789` oder `ws://localhost:18789` für lokale direkte Gateway-Control-Plane-Verbindungen. Andere Hostnamen werden wie gewöhnlicher hostnamenbasierter Datenverkehr geroutet.
+- Raw-`net`-, `tls`- und `http2`-Sockets, native Addons und untergeordnete Prozesse können das Proxy-Routing auf Node-Ebene umgehen, sofern sie Proxy-Umgebungsvariablen nicht übernehmen und beachten.
+- IRC ist ein Raw-TCP/TLS-Kanal außerhalb des operatorverwalteten Forward-Proxy-Routings. Setzen Sie in Bereitstellungen, die den gesamten ausgehenden Datenverkehr über diesen Forward Proxy erfordern, `channels.irc.enabled=false`, sofern direkter ausgehender IRC-Datenverkehr nicht ausdrücklich genehmigt ist.
+- Der lokale Debug-Proxy ist ein Diagnosewerkzeug, und seine direkte Upstream-Weiterleitung für Proxy-Anfragen und CONNECT-Tunnel ist standardmäßig deaktiviert, während der verwaltete Proxy-Modus aktiv ist; aktivieren Sie direkte Weiterleitung nur für genehmigte lokale Diagnosen.
+- Lokale WebUIs der Benutzer und lokale Modellserver sollten bei Bedarf in der Operator-Proxy-Richtlinie auf die Allowlist gesetzt werden; OpenClaw stellt für sie keine allgemeine Umgehung des lokalen Netzwerks bereit.
+- Die Proxy-Umgehung der Gateway-Control-Plane ist absichtlich auf `localhost` und literale Loopback-IP-URLs beschränkt. Verwenden Sie `ws://127.0.0.1:18789`, `ws://[::1]:18789` oder `ws://localhost:18789` für lokale direkte Gateway-Control-Plane-Verbindungen; andere Hostnamen werden wie gewöhnlicher hostnamebasierter Datenverkehr geroutet.
- OpenClaw prüft, testet oder zertifiziert Ihre Proxy-Richtlinie nicht.
-- Behandeln Sie Änderungen an der Proxy-Richtlinie als sicherheitsrelevante betriebliche Änderungen.
+- Behandeln Sie Änderungen an Proxy-Richtlinien als sicherheitssensible betriebliche Änderungen.
diff --git a/docs/de/tools/thinking.md b/docs/de/tools/thinking.md
index 33745e08b..ca4e227f5 100644
--- a/docs/de/tools/thinking.md
+++ b/docs/de/tools/thinking.md
@@ -1,143 +1,144 @@
---
read_when:
- - Anpassen des Parsings oder der Standardwerte für thinking-, fast-mode- oder verbose-Direktiven
-summary: Direktivensyntax für /think, /fast, /verbose, /trace und Sichtbarkeit des Denkprozesses
+ - Anpassen der Auswertung oder Standardwerte für Denkmodus-, Schnellmodus- oder Ausführlichkeitsdirektiven
+summary: Direktivensyntax für /think, /fast, /verbose, /trace und die Sichtbarkeit der Denkprozesse
title: Denkstufen
x-i18n:
- generated_at: "2026-05-04T02:26:33Z"
+ generated_at: "2026-05-04T18:24:30Z"
model: gpt-5.5
provider: openai
- source_hash: 6fa1b0a2b5f7b93a706488c3ad39dfe08c08eed0bdd30880eb4c07d730ee4d4f
+ source_hash: fcd1cd76ca5d0b08656e0629df656ad8aa037201d8de68093b3e46eb0708f811
source_path: tools/thinking.md
workflow: 16
---
-## Was es tut
+## Funktionsweise
-- Inline-Direktive in einem beliebigen eingehenden Text: `/t `, `/think:` oder `/thinking `.
-- Stufen (Aliase): `off | minimal | low | medium | high | xhigh | adaptive | max`
+- Inline-Direktive in einem beliebigen eingehenden Inhalt: `/t `, `/think:` oder `/thinking `.
+- Stufen (Aliasse): `off | minimal | low | medium | high | xhigh | adaptive | max`
- minimal → „denken“
- - low → „intensiv denken“
- - medium → „intensiver denken“
+ - low → „gründlich denken“
+ - medium → „noch gründlicher denken“
- high → „ultradenken“ (maximales Budget)
- - xhigh → „ultradenken+“ (GPT-5.2+ und Codex-Modelle sowie Anthropic Claude Opus 4.7 effort)
- - adaptive → vom Provider verwaltetes adaptives Denken (unterstützt für Claude 4.6 auf Anthropic/Bedrock, Anthropic Claude Opus 4.7 und Google Gemini dynamic thinking)
- - max → maximales Reasoning des Providers (Anthropic Claude Opus 4.7; Ollama ordnet dies seinem höchsten nativen `think`-Aufwand zu)
+ - xhigh → „ultradenken+“ (GPT-5.2+ und Codex-Modelle sowie Anthropic Claude Opus 4.7-Aufwand)
+ - adaptive → Provider-verwaltetes adaptives Denken (unterstützt für Claude 4.6 auf Anthropic/Bedrock, Anthropic Claude Opus 4.7 und dynamisches Denken von Google Gemini)
+ - max → maximales Provider-Reasoning (Anthropic Claude Opus 4.7; Ollama ordnet dies seinem höchsten nativen `think`-Aufwand zu)
- `x-high`, `x_high`, `extra-high`, `extra high` und `extra_high` werden `xhigh` zugeordnet.
- `highest` wird `high` zugeordnet.
- Provider-Hinweise:
- - Thinking-Menüs und Auswahlfelder werden durch das Provider-Profil gesteuert. Provider-Plugins deklarieren die exakte Stufenmenge für das ausgewählte Modell, einschließlich Labels wie binärem `on`.
- - `adaptive`, `xhigh` und `max` werden nur für Provider-/Modellprofile angeboten, die sie unterstützen. Eingegebene Direktiven für nicht unterstützte Stufen werden mit den gültigen Optionen dieses Modells abgelehnt.
- - Vorhandene gespeicherte nicht unterstützte Stufen werden anhand des Provider-Profilrangs neu zugeordnet. `adaptive` fällt bei nicht adaptiven Modellen auf `medium` zurück, während `xhigh` und `max` auf die größte unterstützte Nicht-`off`-Stufe für das ausgewählte Modell zurückfallen.
- - Anthropic-Claude-4.6-Modelle verwenden standardmäßig `adaptive`, wenn keine explizite Thinking-Stufe festgelegt ist.
- - Anthropic Claude Opus 4.7 verwendet nicht standardmäßig adaptives Denken. Der API-effort-Standard bleibt Provider-eigen, sofern Sie nicht explizit eine Thinking-Stufe festlegen.
- - Anthropic Claude Opus 4.7 ordnet `/think xhigh` adaptivem Denken plus `output_config.effort: "xhigh"` zu, weil `/think` eine Thinking-Direktive ist und `xhigh` die Opus-4.7-effort-Einstellung ist.
- - Anthropic Claude Opus 4.7 stellt außerdem `/think max` bereit; es wird demselben Provider-eigenen Pfad für maximalen effort zugeordnet.
- - DeepSeek-V4-Modelle stellen `/think xhigh|max` bereit; beide werden DeepSeek `reasoning_effort: "max"` zugeordnet, während niedrigere Nicht-`off`-Stufen `high` zugeordnet werden.
- - Ollama-Modelle mit Thinking-Unterstützung stellen `/think low|medium|high|max` bereit; `max` wird dem nativen `think: "high"` zugeordnet, weil Ollamas native API die effort-Zeichenfolgen `low`, `medium` und `high` akzeptiert.
- - OpenAI-GPT-Modelle ordnen `/think` über die modellspezifische Unterstützung für Responses-API-effort zu. `/think off` sendet `reasoning.effort: "none"` nur, wenn das Zielmodell dies unterstützt; andernfalls lässt OpenClaw die deaktivierte Reasoning-Nutzlast weg, statt einen nicht unterstützten Wert zu senden.
- - Benutzerdefinierte OpenAI-kompatible Katalogeinträge können `/think xhigh` aktivieren, indem sie `models.providers..models[].compat.supportedReasoningEfforts` so setzen, dass `"xhigh"` enthalten ist. Dies nutzt dieselben Kompatibilitätsmetadaten, die ausgehende OpenAI-Reasoning-effort-Nutzlasten zuordnen, sodass Menüs, Sitzungsvalidierung, Agent-CLI und `llm-task` mit dem Transportverhalten übereinstimmen.
- - Veraltete konfigurierte OpenRouter-Hunter-Alpha-Refs überspringen Proxy-Reasoning-Injektion, weil diese eingestellte Route endgültigen Antworttext über Reasoning-Felder zurückgeben konnte.
- - Google Gemini ordnet `/think adaptive` Geminis Provider-eigenem dynamischem Denken zu. Gemini-3-Anfragen lassen ein festes `thinkingLevel` weg, während Gemini-2.5-Anfragen `thinkingBudget: -1` senden; feste Stufen werden weiterhin dem nächstliegenden Gemini-`thinkingLevel` oder Budget für diese Modellfamilie zugeordnet.
- - MiniMax (`minimax/*`) auf dem Anthropic-kompatiblen Streaming-Pfad verwendet standardmäßig `thinking: { type: "disabled" }`, sofern Sie Thinking nicht explizit in Modellparametern oder Anfrageparametern festlegen. Dies vermeidet durchgesickerte `reasoning_content`-Deltas aus MiniMax’ nicht nativem Anthropic-Stream-Format.
- - Z.AI (`zai/*`) unterstützt nur binäres Thinking (`on`/`off`). Jede Nicht-`off`-Stufe wird als `on` behandelt (`low` zugeordnet).
- - Moonshot (`moonshot/*`) ordnet `/think off` `thinking: { type: "disabled" }` zu und jede Nicht-`off`-Stufe `thinking: { type: "enabled" }`. Wenn Thinking aktiviert ist, akzeptiert Moonshot nur `tool_choice` `auto|none`; OpenClaw normalisiert inkompatible Werte zu `auto`.
+ - Denken-Menüs und Auswahlfelder werden vom Provider-Profil gesteuert. Provider-Plugins deklarieren den exakten Stufensatz für das ausgewählte Modell, einschließlich Labels wie binärem `on`.
+ - `adaptive`, `xhigh` und `max` werden nur für Provider-/Modellprofile angezeigt, die sie unterstützen. Eingegebene Direktiven für nicht unterstützte Stufen werden mit den gültigen Optionen dieses Modells zurückgewiesen.
+ - Vorhandene gespeicherte nicht unterstützte Stufen werden anhand der Rangfolge des Provider-Profils neu zugeordnet. `adaptive` fällt bei nicht adaptiven Modellen auf `medium` zurück, während `xhigh` und `max` auf die größte unterstützte nicht-`off`-Stufe für das ausgewählte Modell zurückfallen.
+ - Anthropic Claude 4.6-Modelle verwenden standardmäßig `adaptive`, wenn keine explizite Denkstufe festgelegt ist.
+ - Anthropic Claude Opus 4.7 verwendet nicht standardmäßig adaptives Denken. Sein API-Effort-Standardwert bleibt Provider-eigen, sofern Sie nicht explizit eine Denkstufe festlegen.
+ - Anthropic Claude Opus 4.7 ordnet `/think xhigh` adaptivem Denken plus `output_config.effort: "xhigh"` zu, weil `/think` eine Denken-Direktive ist und `xhigh` die Opus 4.7-Effort-Einstellung ist.
+ - Anthropic Claude Opus 4.7 stellt außerdem `/think max` bereit; es wird demselben Provider-eigenen maximalen Effort-Pfad zugeordnet.
+ - DeepSeek V4-Modelle stellen `/think xhigh|max` bereit; beide werden DeepSeek `reasoning_effort: "max"` zugeordnet, während niedrigere nicht-`off`-Stufen `high` zugeordnet werden.
+ - Denkfähige Ollama-Modelle stellen `/think low|medium|high|max` bereit; `max` wird nativem `think: "high"` zugeordnet, weil Ollamas native API die Effort-Strings `low`, `medium` und `high` akzeptiert.
+ - OpenAI-GPT-Modelle ordnen `/think` über die modellspezifische Effort-Unterstützung der Responses API zu. `/think off` sendet `reasoning.effort: "none"` nur, wenn das Zielmodell dies unterstützt; andernfalls lässt OpenClaw die deaktivierte Reasoning-Nutzlast weg, statt einen nicht unterstützten Wert zu senden.
+ - Benutzerdefinierte OpenAI-kompatible Katalogeinträge können `/think xhigh` aktivieren, indem `models.providers..models[].compat.supportedReasoningEfforts` so gesetzt wird, dass es `"xhigh"` enthält. Dies verwendet dieselben Kompatibilitätsmetadaten, die ausgehende OpenAI-Reasoning-Effort-Nutzlasten zuordnen, sodass Menüs, Sitzungsvalidierung, Agent-CLI und `llm-task` mit dem Transportverhalten übereinstimmen.
+ - Veraltete konfigurierte OpenRouter Hunter Alpha-Refs überspringen die Proxy-Reasoning-Injektion, weil diese eingestellte Route finalen Antworttext über Reasoning-Felder zurückgeben konnte.
+ - Google Gemini ordnet `/think adaptive` dem Provider-eigenen dynamischen Denken von Gemini zu. Gemini 3-Anfragen lassen ein festes `thinkingLevel` weg, während Gemini 2.5-Anfragen `thinkingBudget: -1` senden; feste Stufen werden weiterhin der nächstliegenden Gemini-`thinkingLevel`- oder Budget-Einstellung für diese Modellfamilie zugeordnet.
+ - MiniMax (`minimax/*`) auf dem Anthropic-kompatiblen Streaming-Pfad verwendet standardmäßig `thinking: { type: "disabled" }`, sofern Sie Denken nicht explizit in Modellparametern oder Anfrageparametern festlegen. Dadurch werden ungewollt weitergeleitete `reasoning_content`-Deltas aus dem nicht nativen Anthropic-Stream-Format von MiniMax vermieden.
+ - Z.AI (`zai/*`) unterstützt nur binäres Denken (`on`/`off`). Jede nicht-`off`-Stufe wird als `on` behandelt (`low` zugeordnet).
+ - Moonshot (`moonshot/*`) ordnet `/think off` `thinking: { type: "disabled" }` zu und jede nicht-`off`-Stufe `thinking: { type: "enabled" }`. Wenn Denken aktiviert ist, akzeptiert Moonshot nur `tool_choice` `auto|none`; OpenClaw normalisiert inkompatible Werte zu `auto`.
## Auflösungsreihenfolge
1. Inline-Direktive in der Nachricht (gilt nur für diese Nachricht).
-2. Sitzungsüberschreibung (durch Senden einer Nur-Direktive-Nachricht festgelegt).
-3. Agent-spezifischer Standard (`agents.list[].thinkingDefault` in der Konfiguration).
+2. Sitzungsüberschreibung (durch 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: vom Provider deklarierter Standard, sofern verfügbar; andernfalls werden Reasoning-fähige Modelle zu `medium` oder zur nächstliegenden unterstützten Nicht-`off`-Stufe für dieses Modell aufgelöst, und Nicht-Reasoning-Modelle bleiben `off`.
+5. Fallback: Provider-deklarierter Standardwert, wenn verfügbar; andernfalls werden Reasoning-fähige Modelle zu `medium` oder zur nächstliegenden unterstützten nicht-`off`-Stufe für dieses Modell aufgelöst, und nicht Reasoning-fähige Modelle bleiben `off`.
-## Einen Sitzungsstandard festlegen
+## Sitzungsstandard festlegen
-- Senden Sie eine Nachricht, die **nur** die Direktive enthält (Leerraum zulässig), z. B. `/think:medium` oder `/t high`.
-- Das bleibt für die aktuelle Sitzung erhalten (standardmäßig pro Absender); gelöscht durch `/think:off` oder Zurücksetzen nach Sitzungsleerlauf.
-- Eine Bestätigungsantwort wird 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 Sitzungszustand bleibt unverändert.
-- Senden Sie `/think` (oder `/think:`) ohne Argument, um die aktuelle Thinking-Stufe anzuzeigen.
+- 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); gelöscht durch `/think:off` oder eine Leerlauf-Zurücksetzung der Sitzung.
+- 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 zurückgewiesen und der Sitzungszustand bleibt unverändert.
+- Senden Sie `/think` (oder `/think:`) ohne Argument, um die aktuelle Denkstufe anzuzeigen.
-## Anwendung nach Agent
+## Anwendung pro Agent
-- **Eingebetteter Pi**: Die aufgelöste Stufe wird an die prozessinterne Pi-Agent-Laufzeit übergeben.
+- **Eingebettetes Pi**: Die aufgelöste Stufe wird an die prozessinterne Pi-Agent-Laufzeit übergeben.
+- **Claude-CLI-Backend**: Nicht-`off`-Stufen werden bei Verwendung von `claude-cli` als `--effort` an Claude Code übergeben; siehe [CLI-Backends](/de/gateway/cli-backends).
## Schnellmodus (/fast)
- Stufen: `on|off`.
-- Eine Nur-Direktive-Nachricht schaltet eine Schnellmodus-Sitzungsüberschreibung um und antwortet mit `Fast mode enabled.` / `Fast mode disabled.`.
-- Senden Sie `/fast` (oder `/fast status`) ohne Modus, um den aktuell wirksamen Schnellmoduszustand anzuzeigen.
+- Eine Direktive-only-Nachricht 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 aktuell wirksamen Schnellmodus-Zustand anzuzeigen.
- OpenClaw löst den Schnellmodus in dieser Reihenfolge auf:
- 1. Inline-/Nur-Direktive `/fast on|off`
+ 1. Inline-/Direktive-only `/fast on|off`
2. Sitzungsüberschreibung
- 3. Agent-spezifischer Standard (`agents.list[].fastModeDefault`)
- 4. Modellbezogene Konfiguration: `agents.defaults.models["/"].params.fastMode`
+ 3. Standard pro Agent (`agents.list[].fastModeDefault`)
+ 4. Konfiguration pro Modell: `agents.defaults.models["/"].params.fastMode`
5. Fallback: `off`
-- Für `openai/*` wird der Schnellmodus auf OpenAI priority processing abgebildet, indem bei unterstützten Responses-Anfragen `service_tier=priority` gesendet wird.
-- Für `openai-codex/*` sendet der Schnellmodus dasselbe `service_tier=priority`-Flag bei Codex Responses. OpenClaw verwendet einen gemeinsamen `/fast`-Schalter für beide Authentifizierungspfade.
-- Für direkte öffentliche `anthropic/*`-Anfragen, einschließlich OAuth-authentifiziertem Datenverkehr an `api.anthropic.com`, wird der Schnellmodus 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 Schnellmodusstandard, wenn beide gesetzt sind. OpenClaw überspringt Anthropic-Service-Tier-Injektion weiterhin für Nicht-Anthropic-Proxy-Basis-URLs.
+- Für `openai/*` wird der Schnellmodus OpenAI-Prioritätsverarbeitung zugeordnet, 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 `/fast`-Schalter für beide Authentifizierungspfade bei.
+- Für direkte öffentliche `anthropic/*`-Anfragen, einschließlich per OAuth authentifiziertem Traffic an `api.anthropic.com`, wird der Schnellmodus Anthropic-Service-Tiers zugeordnet: `/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` zu `MiniMax-M2.7-highspeed` um.
+- Explizite Anthropic-Modellparameter `serviceTier` / `service_tier` überschreiben den Schnellmodus-Standardwert, wenn beide gesetzt sind. OpenClaw überspringt weiterhin die Anthropic-Service-Tier-Injektion für nicht-Anthropic-Proxy-Basis-URLs.
- `/status` zeigt `Fast` nur an, wenn der Schnellmodus aktiviert ist.
## Ausführliche Direktiven (/verbose oder /v)
- Stufen: `on` (minimal) | `full` | `off` (Standard).
-- Eine Nur-Direktive-Nachricht schaltet ausführliche Sitzungsprotokollierung um und antwortet mit `Verbose logging enabled.` / `Verbose logging disabled.`; ungültige Stufen geben einen Hinweis zurück, ohne den Zustand zu ändern.
-- `/verbose off` speichert eine explizite Sitzungsüberschreibung; löschen Sie sie über die Sitzungsoberfläche, indem Sie `inherit` auswählen.
-- Eine Inline-Direktive betrifft nur diese Nachricht; andernfalls gelten Sitzungs-/globale Standards.
+- Eine Direktive-only-Nachricht schaltet die ausführliche Sitzungsprotokollierung um und antwortet mit `Verbose logging enabled.` / `Verbose logging disabled.`; ungültige Stufen geben 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` wählen.
+- Eine Inline-Direktive wirkt sich nur auf diese Nachricht aus; andernfalls gelten Sitzungs-/globale Standards.
- Senden Sie `/verbose` (oder `/verbose:`) ohne Argument, um die aktuelle Ausführlichkeitsstufe anzuzeigen.
-- Wenn ausführliche Ausgabe aktiviert ist, senden Agents, die strukturierte Tool-Ergebnisse ausgeben (Pi, andere JSON-Agents), jeden Tool-Aufruf als eigene reine Metadaten-Nachricht zurück, sofern verfügbar mit ` : ` vorangestellt. Diese Tool-Zusammenfassungen werden gesendet, sobald jedes Tool startet (separate Sprechblasen), nicht als Streaming-Deltas.
-- Zusammenfassungen von Tool-Fehlern bleiben im normalen Modus sichtbar, aber Rohfehlerdetail-Suffixe werden ausgeblendet, sofern verbose nicht `on` oder `full` ist.
-- Wenn verbose `full` ist, werden Tool-Ausgaben nach Abschluss ebenfalls weitergeleitet (separate Sprechblase, auf eine sichere Länge gekürzt). Wenn Sie `/verbose on|full|off` umschalten, während ein Lauf aktiv ist, berücksichtigen nachfolgende Tool-Sprechblasen die neue Einstellung.
-- `agents.defaults.toolProgressDetail` steuert die Form der `/verbose`-Tool-Zusammenfassungen und der Tool-Zeilen in Fortschrittsentwürfen. Verwenden Sie `"explain"` (Standard) für kompakte menschenlesbare Labels wie `🛠️ Exec: checking JS syntax`; verwenden Sie `"raw"`, wenn Sie auch den Rohbefehl bzw. das Rohdetail zum Debugging angehängt haben möchten. Agent-spezifisches `agents.list[].toolProgressDetail` überschreibt den Standard.
+- Wenn verbose aktiviert ist, senden Agents, die strukturierte Tool-Ergebnisse ausgeben (Pi, andere JSON-Agents), jeden Tool-Aufruf als eigene Nur-Metadaten-Nachricht zurück, mit dem Präfix ` : `, wenn verfügbar. Diese Tool-Zusammenfassungen werden gesendet, sobald jedes Tool startet (separate Nachrichtenblasen), nicht als Streaming-Deltas.
+- Tool-Fehlerzusammenfassungen bleiben im Normalmodus sichtbar, aber Rohdetails zu Fehlern als Suffixe werden ausgeblendet, sofern verbose nicht `on` oder `full` ist.
+- Wenn verbose `full` ist, werden Tool-Ausgaben nach Abschluss ebenfalls weitergeleitet (separate Nachrichtenblase, auf eine sichere Länge gekürzt). Wenn Sie `/verbose on|full|off` umschalten, während ein Lauf läuft, beachten nachfolgende Tool-Nachrichtenblasen die neue Einstellung.
+- `agents.defaults.toolProgressDetail` steuert die Form der `/verbose`-Tool-Zusammenfassungen und Tool-Zeilen in Fortschrittsentwürfen. Verwenden Sie `"explain"` (Standard) für kompakte menschliche Labels wie `🛠️ Exec: checking JS syntax`; verwenden Sie `"raw"`, wenn Sie außerdem den rohen Befehl bzw. das rohe Detail zum Debuggen anhängen möchten. `agents.list[].toolProgressDetail` pro Agent überschreibt den Standard.
- `explain`: `🛠️ Exec: check JS syntax for /tmp/app.js`
- `raw`: `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js`
## Plugin-Trace-Direktiven (/trace)
- Stufen: `on` | `off` (Standard).
-- Eine Nur-Direktive-Nachricht schaltet die Plugin-Trace-Ausgabe für die Sitzung um und antwortet mit `Plugin trace enabled.` / `Plugin trace disabled.`.
-- Eine Inline-Direktive betrifft nur diese Nachricht; andernfalls gelten Sitzungs-/globale Standards.
+- Eine Direktive-only-Nachricht schaltet die Plugin-Trace-Ausgabe der Sitzung um und antwortet mit `Plugin trace enabled.` / `Plugin trace disabled.`.
+- Eine Inline-Direktive wirkt sich nur auf diese Nachricht aus; andernfalls gelten Sitzungs-/globale Standards.
- Senden Sie `/trace` (oder `/trace:`) ohne Argument, um die aktuelle Trace-Stufe anzuzeigen.
-- `/trace` ist enger gefasst als `/verbose`: Es legt nur Plugin-eigene Trace-/Debug-Zeilen offen, etwa Active-Memory-Debug-Zusammenfassungen.
+- `/trace` ist enger gefasst als `/verbose`: Es legt nur Plugin-eigene Trace-/Debug-Zeilen offen, z. B. Active Memory-Debug-Zusammenfassungen.
- Trace-Zeilen können in `/status` und als nachfolgende Diagnosenachricht nach der normalen Assistant-Antwort erscheinen.
## Reasoning-Sichtbarkeit (/reasoning)
- Stufen: `on|off|stream`.
-- Eine Nur-Direktive-Nachricht schaltet um, ob Thinking-Blöcke in Antworten angezeigt werden.
+- Eine Direktive-only-Nachricht schaltet um, ob Denkblöcke in Antworten angezeigt werden.
- Wenn aktiviert, wird Reasoning als **separate Nachricht** mit dem Präfix `Reasoning:` gesendet.
-- `stream` (nur Telegram): streamt Reasoning in die Telegram-Entwurfsblase, während die Antwort generiert wird, und sendet danach die endgültige Antwort ohne Reasoning.
+- `stream` (nur Telegram): streamt Reasoning in die Telegram-Entwurfsblase, während die Antwort generiert wird, und sendet danach die finale Antwort ohne Reasoning.
- Alias: `/reason`.
- Senden Sie `/reasoning` (oder `/reasoning:`) ohne Argument, um die aktuelle Reasoning-Stufe anzuzeigen.
-- Auflösungsreihenfolge: Inline-Direktive, dann Sitzungsüberschreibung, dann Agent-spezifischer Standard (`agents.list[].reasoningDefault`), dann Fallback (`off`).
+- Auflösungsreihenfolge: Inline-Direktive, dann Sitzungsüberschreibung, dann Standard pro Agent (`agents.list[].reasoningDefault`), dann Fallback (`off`).
-Fehlgeformte Reasoning-Tags lokaler Modelle werden konservativ behandelt. Geschlossene `...`-Blöcke bleiben bei normalen Antworten ausgeblendet, und nicht geschlossene Reasoning-Inhalte nach bereits sichtbarem Text werden ebenfalls ausgeblendet. Wenn eine Antwort vollständig in ein einzelnes nicht geschlossenes öffnendes Tag eingeschlossen ist und andernfalls als leerer Text ausgeliefert würde, entfernt OpenClaw das fehlgeformte öffnende Tag und liefert den verbleibenden Text aus.
+Fehlerhafte Reasoning-Tags lokaler Modelle werden konservativ behandelt. Geschlossene ...-Blöcke bleiben bei normalen Antworten ausgeblendet, und nicht geschlossenes Reasoning nach bereits sichtbarem Text wird ebenfalls ausgeblendet. Wenn eine Antwort vollständig in ein einzelnes nicht geschlossenes öffnendes Tag eingeschlossen ist und andernfalls als leerer Text ausgeliefert würde, entfernt OpenClaw das fehlerhafte öffnende Tag und liefert den verbleibenden Text aus.
-## Verwandtes
+## Siehe auch
- Die Dokumentation zum erhöhten Modus finden Sie unter [Erhöhter Modus](/de/tools/elevated).
## Heartbeats
-- Der Heartbeat-Prüftext 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 durch Heartbeats zu ändern).
-- Die Heartbeat-Zustellung verwendet standardmäßig nur die endgültige Nutzlast. Um zusätzlich die separate `Reasoning:`-Nachricht zu senden (sofern verfügbar), setzen Sie `agents.defaults.heartbeat.includeReasoning: true` oder agent-spezifisch `agents.list[].heartbeat.includeReasoning: true`.
+- Der Inhalt der Heartbeat-Prüfung 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 gewohnt (vermeiden Sie jedoch, Sitzungsstandards aus Heartbeats heraus zu ändern).
+- Die Heartbeat-Zustellung verwendet standardmäßig nur die finale Nutzlast. Um zusätzlich die separate Nachricht `Reasoning:` zu senden (wenn verfügbar), setzen Sie `agents.defaults.heartbeat.includeReasoning: true` oder pro Agent `agents.list[].heartbeat.includeReasoning: true`.
-## Webchat-Oberfläche
+## Webchat-UI
-- Der Thinking-Auswahlschalter 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 `thinkingOnce`-Überschreibung.
-- Die erste Option ist immer `Default ()`, wobei der aufgelöste Standard aus dem Provider-Thinking-Profil des aktiven Sitzungsmodells plus derselben Fallback-Logik stammt, die `/status` und `session_status` verwenden.
-- Der Picker verwendet `thinkingLevels`, die von der Gateway-Sitzungszeile bzw. den Standards zurückgegeben werden, wobei `thinkingOptions` als Legacy-Label-Liste beibehalten wird. Die Browseroberfläche führt keine eigene Provider-Regex-Liste; Plugins besitzen modellspezifische Stufensätze.
-- `/think:` funktioniert weiterhin und aktualisiert dieselbe gespeicherte Sitzungsstufe, sodass Chat-Direktiven und Picker synchron bleiben.
+- Die Denken-Auswahl im Webchat spiegelt beim Laden der Seite die gespeicherte Stufe der Sitzung aus dem eingehenden Sitzungsspeicher bzw. der Konfiguration wider.
+- Wenn Sie eine andere Stufe auswählen, wird die Sitzungsüberschreibung sofort per `sessions.patch` geschrieben; sie wartet nicht auf das nächste Senden und ist keine einmalige `thinkingOnce`-Überschreibung.
+- Die erste Option ist immer `Default ()`, wobei der aufgelöste Standard aus dem Provider-Denkprofil des aktiven Sitzungsmodells plus derselben Fallback-Logik stammt, die `/status` und `session_status` verwenden.
+- Das Auswahlfeld verwendet `thinkingLevels`, die von der Gateway-Sitzungszeile bzw. den Standardwerten zurückgegeben werden, wobei `thinkingOptions` als Legacy-Label-Liste beibehalten wird. Die Browser-UI hält keine eigene Provider-Regex-Liste vor; Plugins besitzen modellspezifische Stufensätze.
+- `/think:` funktioniert weiterhin und aktualisiert dieselbe gespeicherte Sitzungsstufe, sodass Chat-Direktiven und Auswahlfeld synchron bleiben.
## Provider-Profile
- Provider-Plugins können `resolveThinkingProfile(ctx)` bereitstellen, um die unterstützten Stufen und den Standardwert des Modells zu definieren.
-- Provider-Plugins, die Claude-Modelle als Proxy bereitstellen, sollten `resolveClaudeThinkingProfile(modelId)` aus `openclaw/plugin-sdk/provider-model-shared` wiederverwenden, damit direkte Anthropic- und Proxy-Kataloge abgestimmt bleiben.
-- Jede Profilstufe hat eine gespeicherte kanonische `id` (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` oder `max`) und kann ein anzuzeigendes `label` enthalten. Binäre Provider verwenden `{ id: "low", label: "on" }`.
+- Provider-Plugins, die Claude-Modelle per Proxy weiterleiten, sollten `resolveClaudeThinkingProfile(modelId)` aus `openclaw/plugin-sdk/provider-model-shared` wiederverwenden, damit direkte Anthropic- und Proxy-Kataloge abgestimmt bleiben.
+- Jede Profilstufe 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" }`.
- Tool-Plugins, die eine explizite Thinking-Überschreibung validieren müssen, sollten `api.runtime.agent.resolveThinkingPolicy({ provider, model })` plus `api.runtime.agent.normalizeThinkingLevel(...)` verwenden; sie sollten keine eigenen Provider-/Modell-Stufenlisten pflegen.
-- Tool-Plugins mit Zugriff auf konfigurierte benutzerdefinierte Modellmetadaten können `catalog` an `resolveThinkingPolicy` übergeben, damit Opt-ins von `compat.supportedReasoningEfforts` in der Plugin-seitigen Validierung berücksichtigt werden.
-- Veröffentlichte Legacy-Hooks (`supportsXHighThinking`, `isBinaryThinking` und `resolveDefaultThinkingLevel`) bleiben als Kompatibilitätsadapter erhalten, neue benutzerdefinierte Stufensätze sollten jedoch `resolveThinkingProfile` verwenden.
-- Gateway-Zeilen/-Standardwerte legen `thinkingLevels`, `thinkingOptions` und `thinkingDefault` offen, damit ACP-/Chat-Clients dieselben Profil-IDs und Labels darstellen, die auch die Laufzeitvalidierung verwendet.
+- Tool-Plugins mit Zugriff auf konfigurierte benutzerdefinierte Modellmetadaten können `catalog` an `resolveThinkingPolicy` übergeben, damit Opt-ins für `compat.supportedReasoningEfforts` in der Plugin-seitigen Validierung berücksichtigt werden.
+- Veröffentlichte Legacy-Hooks (`supportsXHighThinking`, `isBinaryThinking` und `resolveDefaultThinkingLevel`) bleiben als Kompatibilitätsadapter bestehen, aber neue benutzerdefinierte Stufensätze sollten `resolveThinkingProfile` verwenden.
+- Gateway-Zeilen/-Standardwerte stellen `thinkingLevels`, `thinkingOptions` und `thinkingDefault` bereit, damit ACP-/Chat-Clients dieselben Profil-IDs und Labels rendern, die auch die Laufzeitvalidierung verwendet.