From fdce0bc61dd60fd0eab2bb7e459bf949da309573 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Thu, 23 Apr 2026 15:00:21 +0000 Subject: [PATCH] chore(i18n): refresh de translations --- docs/de/channels/matrix-push-rules.md | 157 +++++ docs/de/channels/matrix.md | 755 +++++++------------- docs/de/ci.md | 121 ++-- docs/de/gateway/authentication.md | 129 ++-- docs/de/gateway/cli-backends.md | 198 +++--- docs/de/help/testing.md | 979 +++++++++++++------------- 6 files changed, 1145 insertions(+), 1194 deletions(-) create mode 100644 docs/de/channels/matrix-push-rules.md diff --git a/docs/de/channels/matrix-push-rules.md b/docs/de/channels/matrix-push-rules.md new file mode 100644 index 000000000..03ad3168c --- /dev/null +++ b/docs/de/channels/matrix-push-rules.md @@ -0,0 +1,157 @@ +--- +read_when: + - Einrichten von leisem Matrix-Streaming für selbstgehostetes Synapse oder Tuwunel + - Benutzer möchten Benachrichtigungen nur bei abgeschlossenen Blöcken, nicht bei jeder Vorschau-Bearbeitung +summary: Matrix-Push-Regeln pro Empfänger für leise finalisierte Vorschau-Bearbeitungen +title: Matrix-Push-Regeln für leise Vorschauen +x-i18n: + generated_at: "2026-04-23T14:55:30Z" + model: gpt-5.4 + provider: openai + source_hash: dbfdf2552ca352858d4e8d03a2a0f5f3b420d33b01063c111c0335c0229f0534 + source_path: channels/matrix-push-rules.md + workflow: 15 +--- + +# Matrix-Push-Regeln für leise Vorschauen + +Wenn `channels.matrix.streaming` auf `"quiet"` gesetzt ist, bearbeitet OpenClaw ein einzelnes Vorschau-Ereignis direkt vor Ort und markiert die finalisierte Bearbeitung mit einem benutzerdefinierten Content-Flag. Matrix-Clients benachrichtigen nur bei der finalen Bearbeitung, wenn eine Push-Regel pro Benutzer zu diesem Flag passt. Diese Seite richtet sich an Betreiber, die Matrix selbst hosten und diese Regel für jedes Empfängerkonto installieren möchten. + +Wenn Sie nur das standardmäßige Matrix-Benachrichtigungsverhalten möchten, verwenden Sie `streaming: "partial"` oder lassen Sie Streaming deaktiviert. Siehe [Einrichtung des Matrix-Kanals](/de/channels/matrix#streaming-previews). + +## Voraussetzungen + +- Empfängerbenutzer = die Person, die die Benachrichtigung erhalten soll +- Bot-Benutzer = das OpenClaw-Matrix-Konto, das die Antwort sendet +- verwenden Sie für die folgenden API-Aufrufe das Zugriffstoken des Empfängerbenutzers +- gleichen Sie `sender` in der Push-Regel mit der vollständigen MXID des Bot-Benutzers ab +- das Empfängerkonto muss bereits funktionierende Pusher haben — Regeln für leise Vorschauen funktionieren nur, wenn die normale Matrix-Push-Zustellung fehlerfrei funktioniert + +## Schritte + + + + +```json5 +{ + channels: { + matrix: { + streaming: "quiet", + }, + }, +} +``` + + + + + Verwenden Sie nach Möglichkeit ein vorhandenes Client-Sitzungstoken erneut. Um ein neues zu erstellen: + +```bash +curl -sS -X POST \ + "https://matrix.example.org/_matrix/client/v3/login" \ + -H "Content-Type: application/json" \ + --data '{ + "type": "m.login.password", + "identifier": { "type": "m.id.user", "user": "@alice:example.org" }, + "password": "REDACTED" + }' +``` + + + + + +```bash +curl -sS \ + -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ + "https://matrix.example.org/_matrix/client/v3/pushers" +``` + +Wenn keine Pusher zurückgegeben werden, beheben Sie zuerst die normale Matrix-Push-Zustellung für dieses Konto, bevor Sie fortfahren. + + + + + OpenClaw markiert finalisierte rein textbasierte Vorschau-Bearbeitungen mit `content["com.openclaw.finalized_preview"] = true`. Installieren Sie eine Regel, die auf diesen Marker plus die Bot-MXID als Absender passt: + +```bash +curl -sS -X PUT \ + "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" \ + -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + --data '{ + "conditions": [ + { "kind": "event_match", "key": "type", "pattern": "m.room.message" }, + { + "kind": "event_property_is", + "key": "content.m\\.relates_to.rel_type", + "value": "m.replace" + }, + { + "kind": "event_property_is", + "key": "content.com\\.openclaw\\.finalized_preview", + "value": true + }, + { "kind": "event_match", "key": "sender", "pattern": "@bot:example.org" } + ], + "actions": [ + "notify", + { "set_tweak": "sound", "value": "default" }, + { "set_tweak": "highlight", "value": false } + ] + }' +``` + + Ersetzen Sie vor dem Ausführen Folgendes: + + - `https://matrix.example.org`: die Basis-URL Ihres Homeservers + - `$USER_ACCESS_TOKEN`: das Zugriffstoken des Empfängerbenutzers + - `openclaw-finalized-preview-botname`: eine Regel-ID, die pro Bot und Empfänger eindeutig ist (Muster: `openclaw-finalized-preview-`) + - `@bot:example.org`: Ihre OpenClaw-Bot-MXID, nicht die des Empfängers + + + + + +```bash +curl -sS \ + -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ + "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" +``` + +Testen Sie dann eine gestreamte Antwort. Im leisen Modus zeigt der Raum eine unauffällige Entwurfsvorschau an und benachrichtigt einmal, wenn der Block oder Turn abgeschlossen ist. + + + + +Um die Regel später zu entfernen, senden Sie `DELETE` an dieselbe Regel-URL mit dem Token des Empfängers. + +## Hinweise zu mehreren Bots + +Push-Regeln werden über `ruleId` indiziert: Ein erneutes `PUT` gegen dieselbe ID aktualisiert eine einzelne Regel. Wenn mehrere OpenClaw-Bots denselben Empfänger benachrichtigen, erstellen Sie eine Regel pro Bot mit einer eindeutigen Absenderübereinstimmung. + +Neue benutzerdefinierte `override`-Regeln werden vor den standardmäßigen Unterdrückungsregeln eingefügt, daher ist kein zusätzlicher Ordnungsparameter erforderlich. Die Regel wirkt sich nur auf rein textbasierte Vorschau-Bearbeitungen aus, die direkt vor Ort finalisiert werden können; Media-Fallbacks und Stale-Preview-Fallbacks verwenden die normale Matrix-Zustellung. + +## Hinweise zum Homeserver + + + + Es ist keine spezielle Änderung an `homeserver.yaml` erforderlich. Wenn normale Matrix-Benachrichtigungen diesen Benutzer bereits erreichen, sind das Empfängertoken und der oben gezeigte `pushrules`-Aufruf der wichtigste Einrichtungsschritt. + + Wenn Sie Synapse hinter einem Reverse-Proxy oder mit Workern betreiben, stellen Sie sicher, dass `/_matrix/client/.../pushrules/` Synapse korrekt erreicht. Die Push-Zustellung wird vom Hauptprozess oder von `synapse.app.pusher` / konfigurierten Pusher-Workern verarbeitet — stellen Sie sicher, dass diese fehlerfrei funktionieren. + + + + + Derselbe Ablauf wie bei Synapse; für den Marker der finalisierten Vorschau ist keine Tuwunel-spezifische Konfiguration erforderlich. + + Wenn Benachrichtigungen verschwinden, während der Benutzer auf einem anderen Gerät aktiv ist, prüfen Sie, ob `suppress_push_when_active` aktiviert ist. Tuwunel hat diese Option in 1.4.2 (September 2025) hinzugefügt, und sie kann Pushes zu anderen Geräten absichtlich unterdrücken, während ein Gerät aktiv ist. + + + + +## Verwandte Themen + +- [Einrichtung des Matrix-Kanals](/de/channels/matrix) +- [Streaming-Konzepte](/de/concepts/streaming) diff --git a/docs/de/channels/matrix.md b/docs/de/channels/matrix.md index 94f687afe..85bd8cc9c 100644 --- a/docs/de/channels/matrix.md +++ b/docs/de/channels/matrix.md @@ -1,14 +1,14 @@ --- read_when: - - Einrichten von Matrix in OpenClaw - - Konfigurieren von Matrix-E2EE und Verifizierung -summary: Matrix-Unterstützungsstatus, Einrichtung und Konfigurationsbeispiele + - Matrix in OpenClaw einrichten + - Matrix-E2EE und Verifizierung konfigurieren +summary: Status des Matrix-Supports, Einrichtungs- und Konfigurationsbeispiele title: Matrix x-i18n: - generated_at: "2026-04-23T13:58:04Z" + generated_at: "2026-04-23T14:55:32Z" model: gpt-5.4 provider: openai - source_hash: 14873e9d65994138d26ad0bc1bf9bc6e00bea17f9306d592c757503d363de71a + source_hash: 2e9d4d656b47aca2dacb00e591378cb26631afc5b634074bc26e21741b418b47 source_path: channels/matrix.md workflow: 15 --- @@ -23,8 +23,8 @@ Es verwendet das offizielle `matrix-js-sdk` und unterstützt DMs, Räume, Thread Matrix wird in aktuellen OpenClaw-Releases als gebündeltes Plugin ausgeliefert, daher benötigen normale paketierte Builds keine separate Installation. -Wenn Sie eine ältere Build-Version oder eine benutzerdefinierte Installation ohne Matrix verwenden, installieren -Sie es manuell: +Wenn du eine ältere Build-Version oder eine benutzerdefinierte Installation verwendest, die Matrix ausschließt, installiere +es manuell: Von npm installieren: @@ -42,15 +42,15 @@ Siehe [Plugins](/de/tools/plugin) für das Plugin-Verhalten und Installationsreg ## Einrichtung -1. Stellen Sie sicher, dass das Matrix-Plugin verfügbar ist. +1. Stelle sicher, dass das Matrix-Plugin verfügbar ist. - Aktuelle paketierte OpenClaw-Releases enthalten es bereits. - Ältere/benutzerdefinierte Installationen können es mit den obigen Befehlen manuell hinzufügen. -2. Erstellen Sie ein Matrix-Konto auf Ihrem Homeserver. -3. Konfigurieren Sie `channels.matrix` mit entweder: +2. Erstelle ein Matrix-Konto auf deinem Homeserver. +3. Konfiguriere `channels.matrix` mit entweder: - `homeserver` + `accessToken`, oder - `homeserver` + `userId` + `password`. -4. Starten Sie das Gateway neu. -5. Starten Sie eine DM mit dem Bot oder laden Sie ihn in einen Raum ein. +4. Starte das Gateway neu. +5. Starte eine DM mit dem Bot oder lade ihn in einen Raum ein. - Neue Matrix-Einladungen funktionieren nur, wenn `channels.matrix.autoJoin` sie zulässt. Interaktive Einrichtungswege: @@ -64,26 +64,26 @@ Der Matrix-Assistent fragt nach: - Homeserver-URL - Authentifizierungsmethode: Access-Token oder Passwort -- Benutzer-ID (nur bei Passwortauthentifizierung) -- optionalem Gerätenamen +- Benutzer-ID (nur bei Passwort-Authentifizierung) +- optionaler Gerätename - ob E2EE aktiviert werden soll - ob Raumzugriff und automatisches Beitreten bei Einladungen konfiguriert werden sollen Wichtige Verhaltensweisen des Assistenten: -- Wenn Matrix-Authentifizierungs-Umgebungsvariablen bereits vorhanden sind und für dieses Konto noch keine Authentifizierung in der Konfiguration gespeichert ist, bietet der Assistent eine Umgebungsvariablen-Verknüpfung an, damit die Authentifizierung in Umgebungsvariablen bleibt. -- Kontonamen werden auf die Konto-ID normalisiert. Zum Beispiel wird aus `Ops Bot` `ops-bot`. -- DM-Allowlist-Einträge akzeptieren `@user:server` direkt; Anzeigenamen funktionieren nur, wenn eine Live-Verzeichnissuche genau einen Treffer findet. -- Raum-Allowlist-Einträge akzeptieren Raum-IDs und Aliasse direkt. Bevorzugen Sie `!room:server` oder `#alias:server`; nicht aufgelöste Namen werden zur Laufzeit von der Allowlist-Auflösung ignoriert. -- Im Allowlist-Modus für automatisches Beitreten bei Einladungen nur stabile Einladungsziele verwenden: `!roomId:server`, `#alias:server` oder `*`. Reine Raumnamen werden abgelehnt. -- Um Raumnamen vor dem Speichern aufzulösen, verwenden Sie `openclaw channels resolve --channel matrix "Project Room"`. +- Wenn Matrix-Auth-Umgebungsvariablen bereits vorhanden sind und für dieses Konto noch keine Authentifizierung in der Konfiguration gespeichert ist, bietet der Assistent eine Umgebungsvariablen-Verknüpfung an, damit die Authentifizierung in Umgebungsvariablen verbleibt. +- Kontonamen werden auf die Konto-ID normalisiert. Zum Beispiel wird `Ops Bot` zu `ops-bot`. +- DM-Allowlist-Einträge akzeptieren direkt `@user:server`; Anzeigenamen funktionieren nur, wenn die Live-Verzeichnissuche genau eine Übereinstimmung findet. +- Raum-Allowlist-Einträge akzeptieren direkt Raum-IDs und Aliase. Bevorzuge `!room:server` oder `#alias:server`; nicht aufgelöste Namen werden zur Laufzeit bei der Allowlist-Auflösung ignoriert. +- Im Allowlist-Modus für automatisches Beitreten bei Einladungen dürfen nur stabile Einladungsziele verwendet werden: `!roomId:server`, `#alias:server` oder `*`. Einfache Raumnamen werden abgelehnt. +- Um Raumnamen vor dem Speichern aufzulösen, verwende `openclaw channels resolve --channel matrix "Project Room"`. -`channels.matrix.autoJoin` ist standardmäßig auf `off` gesetzt. +`channels.matrix.autoJoin` hat standardmäßig den Wert `off`. -Wenn Sie es nicht festlegen, tritt der Bot eingeladenen Räumen oder neuen DM-artigen Einladungen nicht bei. Er erscheint also nicht in neuen Gruppen oder eingeladenen DMs, es sei denn, Sie treten zuerst manuell bei. +Wenn du es nicht setzt, tritt der Bot eingeladenen Räumen oder neuen DM-artigen Einladungen nicht bei, sodass er nicht in neuen Gruppen oder eingeladenen DMs erscheint, sofern du ihn nicht zuerst manuell beitreten lässt. -Setzen Sie `autoJoin: "allowlist"` zusammen mit `autoJoinAllowlist`, um einzuschränken, welche Einladungen akzeptiert werden, oder setzen Sie `autoJoin: "always"`, wenn er jeder Einladung beitreten soll. +Setze `autoJoin: "allowlist"` zusammen mit `autoJoinAllowlist`, um einzuschränken, welche Einladungen akzeptiert werden, oder setze `autoJoin: "always"`, wenn er jeder Einladung beitreten soll. Im Modus `allowlist` akzeptiert `autoJoinAllowlist` nur `!roomId:server`, `#alias:server` oder `*`. @@ -133,7 +133,7 @@ Minimale tokenbasierte Einrichtung: } ``` -Passwortbasierte Einrichtung (Token wird nach der Anmeldung zwischengespeichert): +Passwortbasierte Einrichtung (das Token wird nach der Anmeldung zwischengespeichert): ```json5 { @@ -151,7 +151,7 @@ Passwortbasierte Einrichtung (Token wird nach der Anmeldung zwischengespeichert) Matrix speichert zwischengespeicherte Anmeldedaten in `~/.openclaw/credentials/matrix/`. Das Standardkonto verwendet `credentials.json`; benannte Konten verwenden `credentials-.json`. -Wenn dort zwischengespeicherte Anmeldedaten vorhanden sind, behandelt OpenClaw Matrix für Einrichtungs-, Doctor- und Channel-Status-Erkennung als konfiguriert, auch wenn die aktuelle Authentifizierung nicht direkt in der Konfiguration gesetzt ist. +Wenn dort zwischengespeicherte Anmeldedaten vorhanden sind, betrachtet OpenClaw Matrix für Einrichtung, Doctor und Channel-Status-Erkennung als konfiguriert, auch wenn die aktuelle Authentifizierung nicht direkt in der Konfiguration gesetzt ist. Entsprechende Umgebungsvariablen (werden verwendet, wenn der Konfigurationsschlüssel nicht gesetzt ist): @@ -162,7 +162,7 @@ Entsprechende Umgebungsvariablen (werden verwendet, wenn der Konfigurationsschl - `MATRIX_DEVICE_ID` - `MATRIX_DEVICE_NAME` -Für Nicht-Standardkonten verwenden Sie kontospezifische Umgebungsvariablen: +Für Nicht-Standardkonten verwende kontoabhängige Umgebungsvariablen: - `MATRIX__HOMESERVER` - `MATRIX__ACCESS_TOKEN` @@ -176,21 +176,21 @@ Beispiel für das Konto `ops`: - `MATRIX_OPS_HOMESERVER` - `MATRIX_OPS_ACCESS_TOKEN` -Für die normalisierte Konto-ID `ops-bot` verwenden Sie: +Für die normalisierte Konto-ID `ops-bot` verwende: - `MATRIX_OPS_X2D_BOT_HOMESERVER` - `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` -Matrix maskiert Satzzeichen in Konto-IDs, damit kontospezifische Umgebungsvariablen kollisionsfrei bleiben. -Zum Beispiel wird `-` zu `_X2D_`, daher wird `ops-prod` zu `MATRIX_OPS_X2D_PROD_*`. +Matrix escaped Satzzeichen in Konto-IDs, damit kontoabhängige Umgebungsvariablen kollisionsfrei bleiben. +Zum Beispiel wird `-` zu `_X2D_`, sodass `ops-prod` zu `MATRIX_OPS_X2D_PROD_*` wird. -Der interaktive Assistent bietet die Umgebungsvariablen-Verknüpfung nur an, wenn diese Authentifizierungs-Umgebungsvariablen bereits vorhanden sind und für das ausgewählte Konto noch keine Matrix-Authentifizierung in der Konfiguration gespeichert ist. +Der interaktive Assistent bietet die Umgebungsvariablen-Verknüpfung nur an, wenn diese Auth-Umgebungsvariablen bereits vorhanden sind und für das ausgewählte Konto noch keine Matrix-Authentifizierung in der Konfiguration gespeichert ist. `MATRIX_HOMESERVER` kann nicht aus einer Workspace-`.env` gesetzt werden; siehe [Workspace-`.env`-Dateien](/de/gateway/security). ## Konfigurationsbeispiel -Dies ist eine praktische Basiskonfiguration mit DM-Pairing, Raum-Allowlist und aktivierter E2EE: +Dies ist eine praxistaugliche Basiskonfiguration mit DM-Pairing, Raum-Allowlist und aktiviertem E2EE: ```json5 { @@ -225,18 +225,17 @@ Dies ist eine praktische Basiskonfiguration mit DM-Pairing, Raum-Allowlist und a } ``` -`autoJoin` gilt für alle Matrix-Einladungen, einschließlich DM-artiger Einladungen. OpenClaw kann -einen eingeladenen Raum zum Zeitpunkt der Einladung nicht zuverlässig als DM oder Gruppe -klassifizieren, daher durchlaufen alle Einladungen zuerst `autoJoin`. -`dm.policy` gilt, nachdem der Bot beigetreten ist und der Raum als DM klassifiziert wurde. +`autoJoin` gilt für alle Matrix-Einladungen, einschließlich DM-artiger Einladungen. OpenClaw kann einen eingeladenen Raum zum Zeitpunkt der Einladung nicht zuverlässig +als DM oder Gruppe klassifizieren, daher laufen alle Einladungen zunächst über `autoJoin`. +`dm.policy` wird angewendet, nachdem der Bot beigetreten ist und der Raum als DM klassifiziert wurde. ## Streaming-Vorschauen Reply-Streaming für Matrix ist Opt-in. -Setzen Sie `channels.matrix.streaming` auf `"partial"`, wenn OpenClaw eine einzelne Live-Vorschau-Antwort -senden, diese Vorschau während der Textgenerierung durch das Modell an Ort und Stelle bearbeiten und sie -abschließend finalisieren soll, wenn die Antwort fertig ist: +Setze `channels.matrix.streaming` auf `"partial"`, wenn OpenClaw eine einzelne Live-Vorschau-Antwort senden, +diese Vorschau während der Textgenerierung durch das Modell an Ort und Stelle bearbeiten und sie anschließend +abschließen soll, sobald die Antwort fertig ist: ```json5 { @@ -248,186 +247,32 @@ abschließend finalisieren soll, wenn die Antwort fertig ist: } ``` -- `streaming: "off"` ist die Standardeinstellung. OpenClaw wartet auf die endgültige Antwort und sendet sie einmal. -- `streaming: "partial"` erstellt eine bearbeitbare Vorschau-Nachricht für den aktuellen Assistant-Block mit normalen Matrix-Textnachrichten. Dadurch bleibt das ältere benachrichtigungsorientierte Vorschau-zuerst-Verhalten von Matrix erhalten, sodass Standard-Clients möglicherweise beim ersten gestreamten Vorschautext benachrichtigen statt beim fertigen Block. -- `streaming: "quiet"` erstellt einen bearbeitbaren stillen Vorschau-Hinweis für den aktuellen Assistant-Block. Verwenden Sie dies nur, wenn Sie zusätzlich Push-Regeln für Empfänger für finalisierte Vorschau-Bearbeitungen konfigurieren. -- `blockStreaming: true` aktiviert separate Matrix-Fortschrittsnachrichten. Wenn Vorschau-Streaming aktiviert ist, behält Matrix den Live-Entwurf für den aktuellen Block bei und bewahrt abgeschlossene Blöcke als separate Nachrichten. +- `streaming: "off"` ist der Standard. OpenClaw wartet auf die endgültige Antwort und sendet sie einmal. +- `streaming: "partial"` erstellt für den aktuellen Assistant-Block eine bearbeitbare Vorschau-Nachricht mit normalen Matrix-Textnachrichten. Dadurch bleibt das ältere Matrix-Verhalten „Vorschau zuerst“ für Benachrichtigungen erhalten, sodass Standard-Clients möglicherweise beim ersten gestreamten Vorschautext benachrichtigen statt beim fertigen Block. +- `streaming: "quiet"` erstellt für den aktuellen Assistant-Block eine bearbeitbare leise Vorschau-Mitteilung. Verwende dies nur, wenn du zusätzlich Empfänger-Push-Regeln für abgeschlossene Vorschau-Bearbeitungen konfigurierst. +- `blockStreaming: true` aktiviert separate Matrix-Fortschrittsnachrichten. Wenn Vorschau-Streaming aktiviert ist, behält Matrix den Live-Entwurf für den aktuellen Block bei und erhält abgeschlossene Blöcke als separate Nachrichten. - Wenn Vorschau-Streaming aktiviert ist und `blockStreaming` deaktiviert ist, bearbeitet Matrix den Live-Entwurf an Ort und Stelle und finalisiert dasselbe Event, wenn der Block oder Turn abgeschlossen ist. -- Wenn die Vorschau nicht mehr in ein einzelnes Matrix-Event passt, beendet OpenClaw das Vorschau-Streaming und fällt auf die normale endgültige Zustellung zurück. +- Wenn die Vorschau nicht mehr in ein einzelnes Matrix-Event passt, beendet OpenClaw das Vorschau-Streaming und greift auf die normale endgültige Zustellung zurück. - Medienantworten senden Anhänge weiterhin normal. Wenn eine veraltete Vorschau nicht mehr sicher wiederverwendet werden kann, redigiert OpenClaw sie vor dem Senden der endgültigen Medienantwort. -- Vorschau-Bearbeitungen verursachen zusätzliche Matrix-API-Aufrufe. Lassen Sie Streaming deaktiviert, wenn Sie das konservativste Rate-Limit-Verhalten möchten. +- Vorschau-Bearbeitungen verursachen zusätzliche Matrix-API-Aufrufe. Lasse Streaming deaktiviert, wenn du das konservativste Verhalten bei Rate-Limits möchtest. -`blockStreaming` aktiviert Vorschau-Entwürfe nicht von selbst. -Verwenden Sie `streaming: "partial"` oder `streaming: "quiet"` für Vorschau-Bearbeitungen; fügen Sie dann `blockStreaming: true` nur hinzu, wenn abgeschlossene Assistant-Blöcke zusätzlich als separate Fortschrittsnachrichten sichtbar bleiben sollen. +`blockStreaming` aktiviert für sich allein keine Entwurfs-Vorschauen. +Verwende `streaming: "partial"` oder `streaming: "quiet"` für Vorschau-Bearbeitungen; füge dann `blockStreaming: true` nur hinzu, wenn abgeschlossene Assistant-Blöcke auch als separate Fortschrittsnachrichten sichtbar bleiben sollen. -Wenn Sie Standard-Matrix-Benachrichtigungen ohne benutzerdefinierte Push-Regeln benötigen, verwenden Sie `streaming: "partial"` für Vorschau-zuerst-Verhalten oder lassen Sie `streaming` für reine Endzustellung deaktiviert. Mit `streaming: "off"`: +Wenn du Standard-Matrix-Benachrichtigungen ohne benutzerdefinierte Push-Regeln benötigst, verwende `streaming: "partial"` für das Verhalten „Vorschau zuerst“ oder lasse `streaming` deaktiviert für eine reine Endzustellung. Bei `streaming: "off"` gilt: - `blockStreaming: true` sendet jeden abgeschlossenen Block als normale benachrichtigende Matrix-Nachricht. -- `blockStreaming: false` sendet nur die endgültige abgeschlossene Antwort als normale benachrichtigende Matrix-Nachricht. +- `blockStreaming: false` sendet nur die endgültige vollständige Antwort als normale benachrichtigende Matrix-Nachricht. -### Selbst gehostete Push-Regeln für stille finalisierte Vorschauen +### Selbstgehostete Push-Regeln für leise abgeschlossene Vorschauen -Wenn Sie Ihre eigene Matrix-Infrastruktur betreiben und stille Vorschauen nur dann benachrichtigen lassen möchten, wenn ein Block oder -eine endgültige Antwort abgeschlossen ist, setzen Sie `streaming: "quiet"` und fügen Sie eine benutzerspezifische Push-Regel für finalisierte Vorschau-Bearbeitungen hinzu. - -Dies ist normalerweise eine Einrichtung pro Empfängerbenutzer, keine globale Konfigurationsänderung für den Homeserver: - -Kurzübersicht, bevor Sie beginnen: - -- Empfängerbenutzer = die Person, die die Benachrichtigung erhalten soll -- Bot-Benutzer = das OpenClaw-Matrix-Konto, das die Antwort sendet -- verwenden Sie für die folgenden API-Aufrufe das Access-Token des Empfängerbenutzers -- gleichen Sie `sender` in der Push-Regel mit der vollständigen MXID des Bot-Benutzers ab - -1. Konfigurieren Sie OpenClaw für stille Vorschauen: - -```json5 -{ - channels: { - matrix: { - streaming: "quiet", - }, - }, -} -``` - -2. Stellen Sie sicher, dass das Empfängerkonto bereits normale Matrix-Push-Benachrichtigungen erhält. Regeln für stille Vorschauen - funktionieren nur, wenn dieser Benutzer bereits funktionierende Pusher/Geräte hat. - -3. Holen Sie das Access-Token des Empfängerbenutzers. - - Verwenden Sie das Token des empfangenden Benutzers, nicht das Token des Bots. - - Die Wiederverwendung eines vorhandenen Client-Sitzungstokens ist in der Regel am einfachsten. - - Wenn Sie ein neues Token ausstellen müssen, können Sie sich über die standardmäßige Matrix Client-Server-API anmelden: - -```bash -curl -sS -X POST \ - "https://matrix.example.org/_matrix/client/v3/login" \ - -H "Content-Type: application/json" \ - --data '{ - "type": "m.login.password", - "identifier": { - "type": "m.id.user", - "user": "@alice:example.org" - }, - "password": "REDACTED" - }' -``` - -4. Verifizieren Sie, dass das Empfängerkonto bereits Pusher hat: - -```bash -curl -sS \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ - "https://matrix.example.org/_matrix/client/v3/pushers" -``` - -Wenn dies keine aktiven Pusher/Geräte zurückgibt, beheben Sie zuerst normale Matrix-Benachrichtigungen, bevor Sie die -unten stehende OpenClaw-Regel hinzufügen. - -OpenClaw markiert finalisierte reine Text-Vorschau-Bearbeitungen mit: - -```json -{ - "com.openclaw.finalized_preview": true -} -``` - -5. Erstellen Sie für jedes Empfängerkonto, das diese Benachrichtigungen erhalten soll, eine Override-Push-Regel: - -```bash -curl -sS -X PUT \ - "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ - -H "Content-Type: application/json" \ - --data '{ - "conditions": [ - { "kind": "event_match", "key": "type", "pattern": "m.room.message" }, - { - "kind": "event_property_is", - "key": "content.m\\.relates_to.rel_type", - "value": "m.replace" - }, - { - "kind": "event_property_is", - "key": "content.com\\.openclaw\\.finalized_preview", - "value": true - }, - { "kind": "event_match", "key": "sender", "pattern": "@bot:example.org" } - ], - "actions": [ - "notify", - { "set_tweak": "sound", "value": "default" }, - { "set_tweak": "highlight", "value": false } - ] - }' -``` - -Ersetzen Sie diese Werte, bevor Sie den Befehl ausführen: - -- `https://matrix.example.org`: Ihre Homeserver-Basis-URL -- `$USER_ACCESS_TOKEN`: das Access-Token des empfangenden Benutzers -- `openclaw-finalized-preview-botname`: eine Regel-ID, die für diesen Bot bei diesem empfangenden Benutzer eindeutig ist -- `@bot:example.org`: die MXID Ihres OpenClaw-Matrix-Bots, nicht die MXID des empfangenden Benutzers - -Wichtig für Setups mit mehreren Bots: - -- Push-Regeln sind über `ruleId` gekennzeichnet. Ein erneutes `PUT` mit derselben Regel-ID aktualisiert diese eine Regel. -- Wenn ein empfangender Benutzer für mehrere OpenClaw-Matrix-Bot-Konten benachrichtigen soll, erstellen Sie eine Regel pro Bot mit einer eindeutigen Regel-ID für jede `sender`-Übereinstimmung. -- Ein einfaches Muster ist `openclaw-finalized-preview-`, zum Beispiel `openclaw-finalized-preview-ops` oder `openclaw-finalized-preview-support`. - -Die Regel wird anhand des Event-Senders ausgewertet: - -- authentifizieren Sie sich mit dem Token des empfangenden Benutzers -- gleichen Sie `sender` mit der MXID des OpenClaw-Bots ab - -6. Verifizieren Sie, dass die Regel vorhanden ist: - -```bash -curl -sS \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ - "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" -``` - -7. Testen Sie eine gestreamte Antwort. Im stillen Modus sollte der Raum eine stille Entwurfs-Vorschau anzeigen, und die abschließende - Bearbeitung an Ort und Stelle sollte benachrichtigen, sobald der Block oder Turn abgeschlossen ist. - -Wenn Sie die Regel später entfernen müssen, löschen Sie dieselbe Regel-ID mit dem Token des empfangenden Benutzers: - -```bash -curl -sS -X DELETE \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ - "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" -``` - -Hinweise: - -- Erstellen Sie die Regel mit dem Access-Token des empfangenden Benutzers, nicht mit dem des Bots. -- Neue benutzerdefinierte `override`-Regeln werden vor den standardmäßigen Unterdrückungsregeln eingefügt, daher ist kein zusätzlicher Ordnungsparameter erforderlich. -- Dies betrifft nur reine Text-Vorschau-Bearbeitungen, die OpenClaw sicher an Ort und Stelle finalisieren kann. Medien-Fallbacks und Fallbacks bei veralteten Vorschauen verwenden weiterhin die normale Matrix-Zustellung. -- Wenn `GET /_matrix/client/v3/pushers` keine Pusher anzeigt, hat der Benutzer für dieses Konto/Gerät noch keine funktionierende Matrix-Push-Zustellung. - -#### Synapse - -Für Synapse ist die obige Einrichtung normalerweise bereits ausreichend: - -- Für finalisierte OpenClaw-Vorschau-Benachrichtigungen ist keine spezielle Änderung in `homeserver.yaml` erforderlich. -- Wenn Ihre Synapse-Bereitstellung bereits normale Matrix-Push-Benachrichtigungen sendet, sind das Benutzertoken und der obige `pushrules`-Aufruf der wichtigste Einrichtungsschritt. -- Wenn Sie Synapse hinter einem Reverse Proxy oder mit Workers betreiben, stellen Sie sicher, dass `/_matrix/client/.../pushrules/` Synapse korrekt erreicht. -- Wenn Sie Synapse-Workers verwenden, stellen Sie sicher, dass Pusher funktionsfähig sind. Die Push-Zustellung wird vom Hauptprozess oder von `synapse.app.pusher` / konfigurierten Pusher-Workers verarbeitet. - -#### Tuwunel - -Für Tuwunel verwenden Sie denselben Einrichtungsablauf und denselben `push-rule`-API-Aufruf wie oben gezeigt: - -- Für den Marker der finalisierten Vorschau selbst ist keine Tuwunel-spezifische Konfiguration erforderlich. -- Wenn normale Matrix-Benachrichtigungen für diesen Benutzer bereits funktionieren, sind das Benutzertoken und der obige `pushrules`-Aufruf der wichtigste Einrichtungsschritt. -- Wenn Benachrichtigungen zu verschwinden scheinen, während der Benutzer auf einem anderen Gerät aktiv ist, prüfen Sie, ob `suppress_push_when_active` aktiviert ist. Tuwunel hat diese Option in Tuwunel 1.4.2 am 12. September 2025 hinzugefügt, und sie kann Pushes an andere Geräte absichtlich unterdrücken, während ein Gerät aktiv ist. +Leises Streaming (`streaming: "quiet"`) benachrichtigt Empfänger erst, wenn ein Block oder Turn abgeschlossen ist — eine benutzerspezifische Push-Regel muss den Marker für abgeschlossene Vorschauen abgleichen. Siehe [Matrix-Push-Regeln für leise Vorschauen](/de/channels/matrix-push-rules) für die vollständige Einrichtung (Empfänger-Token, Pusher-Prüfung, Regelinstallation, Hinweise pro Homeserver). ## Bot-zu-Bot-Räume Standardmäßig werden Matrix-Nachrichten von anderen konfigurierten OpenClaw-Matrix-Konten ignoriert. -Verwenden Sie `allowBots`, wenn Sie absichtlich Inter-Agent-Matrix-Verkehr möchten: +Verwende `allowBots`, wenn du absichtlich Matrix-Datenverkehr zwischen Agents zulassen möchtest: ```json5 { @@ -445,16 +290,16 @@ Verwenden Sie `allowBots`, wenn Sie absichtlich Inter-Agent-Matrix-Verkehr möch ``` - `allowBots: true` akzeptiert Nachrichten von anderen konfigurierten Matrix-Bot-Konten in erlaubten Räumen und DMs. -- `allowBots: "mentions"` akzeptiert diese Nachrichten in Räumen nur dann, wenn sie diesen Bot sichtbar erwähnen. DMs sind weiterhin erlaubt. +- `allowBots: "mentions"` akzeptiert diese Nachrichten in Räumen nur, wenn sie diesen Bot sichtbar erwähnen. DMs sind weiterhin erlaubt. - `groups..allowBots` überschreibt die Einstellung auf Kontoebene für einen Raum. -- OpenClaw ignoriert weiterhin Nachrichten von derselben Matrix-Benutzer-ID, um Selbstantwort-Schleifen zu vermeiden. -- Matrix stellt hier kein natives Bot-Flag bereit; OpenClaw behandelt „von Bot verfasst“ als „von einem anderen konfigurierten Matrix-Konto auf diesem OpenClaw-Gateway gesendet“. +- OpenClaw ignoriert weiterhin Nachrichten von derselben Matrix-Benutzer-ID, um Schleifen durch Selbstantworten zu vermeiden. +- Matrix stellt hier kein natives Bot-Flag bereit; OpenClaw behandelt „von einem Bot verfasst“ als „von einem anderen konfigurierten Matrix-Konto auf diesem OpenClaw-Gateway gesendet“. -Verwenden Sie strikte Raum-Allowlists und Erwähnungsanforderungen, wenn Sie Bot-zu-Bot-Verkehr in gemeinsam genutzten Räumen aktivieren. +Verwende strikte Raum-Allowlists und Erwähnungsanforderungen, wenn du Bot-zu-Bot-Datenverkehr in gemeinsam genutzten Räumen aktivierst. ## Verschlüsselung und Verifizierung -In verschlüsselten (E2EE-)Räumen verwenden ausgehende Bild-Events `thumbnail_file`, sodass Bildvorschauen zusammen mit dem vollständigen Anhang verschlüsselt werden. Unverschlüsselte Räume verwenden weiterhin einfaches `thumbnail_url`. Keine Konfiguration erforderlich — das Plugin erkennt den E2EE-Status automatisch. +In verschlüsselten (E2EE-)Räumen verwenden ausgehende Bild-Events `thumbnail_file`, sodass Bildvorschauen zusammen mit dem vollständigen Anhang verschlüsselt werden. Unverschlüsselte Räume verwenden weiterhin einfaches `thumbnail_url`. Es ist keine Konfiguration erforderlich — das Plugin erkennt den E2EE-Status automatisch. Verschlüsselung aktivieren: @@ -472,92 +317,22 @@ Verschlüsselung aktivieren: } ``` -Verifizierungsstatus prüfen: +Verifizierungsbefehle (alle unterstützen `--verbose` für Diagnoseausgaben und `--json` für maschinenlesbare Ausgabe): -```bash -openclaw matrix verify status -``` +| Befehl | Zweck | +| ------------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| `openclaw matrix verify status` | Cross-Signing- und Geräteverifizierungsstatus prüfen | +| `openclaw matrix verify status --include-recovery-key --json` | Den gespeicherten Wiederherstellungsschlüssel einbeziehen | +| `openclaw matrix verify bootstrap` | Cross-Signing und Verifizierung bootstrapen (siehe unten) | +| `openclaw matrix verify bootstrap --force-reset-cross-signing` | Die aktuelle Cross-Signing-Identität verwerfen und eine neue erstellen | +| `openclaw matrix verify device ""` | Dieses Gerät mit einem Wiederherstellungsschlüssel verifizieren | +| `openclaw matrix verify backup status` | Zustand der Raumschlüssel-Sicherung prüfen | +| `openclaw matrix verify backup restore` | Raumschlüssel aus der Serversicherung wiederherstellen | +| `openclaw matrix verify backup reset --yes` | Die aktuelle Sicherung löschen und eine neue Ausgangsbasis erstellen (kann Secret Storage neu erstellen) | -Ausführlicher Status (vollständige Diagnosen): - -```bash -openclaw matrix verify status --verbose -``` - -Den gespeicherten Recovery Key in maschinenlesbarer Ausgabe einschließen: - -```bash -openclaw matrix verify status --include-recovery-key --json -``` - -Cross-Signing- und Verifizierungsstatus bootstrappen: - -```bash -openclaw matrix verify bootstrap -``` - -Ausführliche Bootstrap-Diagnosen: - -```bash -openclaw matrix verify bootstrap --verbose -``` - -Vor dem Bootstrap ein neues Zurücksetzen der Cross-Signing-Identität erzwingen: - -```bash -openclaw matrix verify bootstrap --force-reset-cross-signing -``` - -Dieses Gerät mit einem Recovery Key verifizieren: - -```bash -openclaw matrix verify device "" -``` - -Ausführliche Details zur Geräteverifizierung: - -```bash -openclaw matrix verify device "" --verbose -``` - -Integrität des Raumschlüssel-Backups prüfen: - -```bash -openclaw matrix verify backup status -``` - -Ausführliche Diagnosen zum Backup-Zustand: - -```bash -openclaw matrix verify backup status --verbose -``` - -Raumschlüssel aus dem Server-Backup wiederherstellen: - -```bash -openclaw matrix verify backup restore -``` - -Ausführliche Diagnosen zur Wiederherstellung: - -```bash -openclaw matrix verify backup restore --verbose -``` - -Das aktuelle Server-Backup löschen und eine neue Backup-Basis erstellen. Wenn der gespeicherte -Backup-Schlüssel nicht sauber geladen werden kann, kann dieses Zurücksetzen auch den Secret Storage neu erstellen, sodass -künftige Kaltstarts den neuen Backup-Schlüssel laden können: - -```bash -openclaw matrix verify backup reset --yes -``` - -Alle `verify`-Befehle sind standardmäßig kompakt (einschließlich stiller interner SDK-Protokollierung) und zeigen detaillierte Diagnosen nur mit `--verbose`. -Verwenden Sie `--json` für eine vollständige maschinenlesbare Ausgabe in Skripten. - -In Setups mit mehreren Konten verwenden Matrix-CLI-Befehle das implizite Matrix-Standardkonto, sofern Sie nicht `--account ` übergeben. -Wenn Sie mehrere benannte Konten konfigurieren, setzen Sie zuerst `channels.matrix.defaultAccount`, sonst stoppen diese impliziten CLI-Operationen und fordern Sie auf, ein Konto explizit auszuwählen. -Verwenden Sie `--account`, wann immer Verifizierungs- oder Geräteoperationen gezielt auf ein benanntes Konto angewendet werden sollen: +In Multi-Account-Setups verwenden Matrix-CLI-Befehle implizit das Matrix-Standardkonto, sofern du nicht `--account ` übergibst. +Wenn du mehrere benannte Konten konfigurierst, setze zuerst `channels.matrix.defaultAccount`, sonst werden diese impliziten CLI-Operationen angehalten und fordern dich auf, ein Konto explizit auszuwählen. +Verwende `--account`, wenn Verifizierungs- oder Geräteoperationen explizit auf ein benanntes Konto zielen sollen: ```bash openclaw matrix verify status --account assistant @@ -567,41 +342,32 @@ openclaw matrix devices list --account assistant Wenn Verschlüsselung für ein benanntes Konto deaktiviert oder nicht verfügbar ist, verweisen Matrix-Warnungen und Verifizierungsfehler auf den Konfigurationsschlüssel dieses Kontos, zum Beispiel `channels.matrix.accounts.assistant.encryption`. -### Was „verifiziert“ bedeutet + + + OpenClaw betrachtet ein Gerät nur dann als verifiziert, wenn deine eigene Cross-Signing-Identität es signiert. `verify status --verbose` zeigt drei Vertrauenssignale: -OpenClaw behandelt dieses Matrix-Gerät nur dann als verifiziert, wenn es durch Ihre eigene Cross-Signing-Identität verifiziert ist. -In der Praxis zeigt `openclaw matrix verify status --verbose` drei Vertrauenssignale an: + - `Locally trusted`: nur von diesem Client als vertrauenswürdig eingestuft + - `Cross-signing verified`: das SDK meldet Verifizierung über Cross-Signing + - `Signed by owner`: von deinem eigenen Self-Signing-Schlüssel signiert -- `Locally trusted`: Dieses Gerät wird nur vom aktuellen Client als vertrauenswürdig eingestuft -- `Cross-signing verified`: Das SDK meldet das Gerät als über Cross-Signing verifiziert -- `Signed by owner`: Das Gerät ist mit Ihrem eigenen Self-Signing-Schlüssel signiert + `Verified by owner` wird nur dann zu `yes`, wenn Cross-Signing oder Owner-Signing vorhanden ist. Lokales Vertrauen allein reicht nicht aus. -`Verified by owner` wird nur dann zu `yes`, wenn eine Cross-Signing-Verifizierung oder eine Signierung durch den Eigentümer vorhanden ist. -Lokales Vertrauen allein reicht nicht aus, damit OpenClaw das Gerät als vollständig verifiziert behandelt. + -### Was Bootstrap tut + + `verify bootstrap` ist der Reparatur- und Einrichtungsbefehl für verschlüsselte Konten. Der Reihe nach: -`openclaw matrix verify bootstrap` ist der Reparatur- und Einrichtungsbefehl für verschlüsselte Matrix-Konten. -Er führt in dieser Reihenfolge Folgendes aus: + - bootstrapped Secret Storage und verwendet nach Möglichkeit einen vorhandenen Wiederherstellungsschlüssel wieder + - bootstrapped Cross-Signing und lädt fehlende öffentliche Cross-Signing-Schlüssel hoch + - markiert und cross-signiert das aktuelle Gerät + - erstellt eine serverseitige Raumschlüssel-Sicherung, falls noch keine vorhanden ist -- bootstrapt den Secret Storage und verwendet dabei nach Möglichkeit einen vorhandenen Recovery Key erneut -- bootstrapt Cross-Signing und lädt fehlende öffentliche Cross-Signing-Schlüssel hoch -- versucht, das aktuelle Gerät zu markieren und per Cross-Signing zu signieren -- erstellt ein neues serverseitiges Raumschlüssel-Backup, falls noch keines vorhanden ist + Wenn der Homeserver UIA zum Hochladen von Cross-Signing-Schlüsseln verlangt, versucht OpenClaw zuerst ohne Authentifizierung, dann `m.login.dummy`, dann `m.login.password` (erfordert `channels.matrix.password`). Verwende `--force-reset-cross-signing` nur, wenn du die aktuelle Identität absichtlich verwerfen willst. -Wenn der Homeserver interaktive Authentifizierung verlangt, um Cross-Signing-Schlüssel hochzuladen, versucht OpenClaw den Upload zuerst ohne Authentifizierung, dann mit `m.login.dummy` und anschließend mit `m.login.password`, wenn `channels.matrix.password` konfiguriert ist. + -Verwenden Sie `--force-reset-cross-signing` nur, wenn Sie die aktuelle Cross-Signing-Identität absichtlich verwerfen und eine neue erstellen möchten. - -Wenn Sie das aktuelle Raumschlüssel-Backup absichtlich verwerfen und eine neue -Backup-Basis für zukünftige Nachrichten beginnen möchten, verwenden Sie `openclaw matrix verify backup reset --yes`. -Tun Sie dies nur, wenn Sie akzeptieren, dass nicht wiederherstellbarer alter verschlüsselter Verlauf -nicht verfügbar bleibt und dass OpenClaw den Secret Storage möglicherweise neu erstellt, wenn das aktuelle Backup- -Geheimnis nicht sicher geladen werden kann. - -### Neue Backup-Basis - -Wenn Sie künftige verschlüsselte Nachrichten funktionsfähig halten und den Verlust nicht wiederherstellbaren alten Verlaufs akzeptieren möchten, führen Sie diese Befehle der Reihe nach aus: + + Wenn du möchtest, dass zukünftige verschlüsselte Nachrichten weiter funktionieren und akzeptierst, dass nicht wiederherstellbarer alter Verlauf verloren geht: ```bash openclaw matrix verify backup reset --yes @@ -609,115 +375,88 @@ openclaw matrix verify backup status --verbose openclaw matrix verify status ``` -Fügen Sie jedem Befehl `--account ` hinzu, wenn Sie gezielt ein benanntes Matrix-Konto ansprechen möchten. + Füge `--account ` hinzu, um ein benanntes Konto als Ziel zu verwenden. Dabei kann auch Secret Storage neu erstellt werden, wenn das aktuelle Sicherungsgeheimnis nicht sicher geladen werden kann. -### Startverhalten + -Wenn `encryption: true` gesetzt ist, verwendet Matrix standardmäßig `startupVerification` mit dem Wert `"if-unverified"`. -Wenn dieses Gerät beim Start noch nicht verifiziert ist, fordert Matrix beim Start die Selbstverifizierung in einem anderen Matrix-Client an, -überspringt doppelte Anfragen, solange bereits eine aussteht, und wendet vor erneuten Versuchen nach Neustarts eine lokale Cooldown-Zeit an. -Fehlgeschlagene Anfrageversuche werden standardmäßig früher erneut versucht als erfolgreiche Anfrageerstellungen. -Setzen Sie `startupVerification: "off"`, um automatische Startanfragen zu deaktivieren, oder passen Sie `startupVerificationCooldownHours` -an, wenn Sie ein kürzeres oder längeres Wiederholungsfenster möchten. + + Mit `encryption: true` ist `startupVerification` standardmäßig `"if-unverified"`. Beim Start fordert ein nicht verifiziertes Gerät die Selbstverifizierung in einem anderen Matrix-Client an, überspringt Duplikate und wendet eine Abkühlzeit an. Passe dies mit `startupVerificationCooldownHours` an oder deaktiviere es mit `startupVerification: "off"`. -Beim Start wird außerdem automatisch ein konservativer Crypto-Bootstrap-Durchlauf ausgeführt. -Dieser Durchlauf versucht zuerst, den aktuellen Secret Storage und die aktuelle Cross-Signing-Identität wiederzuverwenden, und vermeidet ein Zurücksetzen von Cross-Signing, sofern Sie keinen expliziten Bootstrap-Reparaturablauf ausführen. + Beim Start wird außerdem ein konservativer Crypto-Bootstrap-Durchlauf ausgeführt, der die aktuelle Secret Storage und die aktuelle Cross-Signing-Identität wiederverwendet. Wenn der Bootstrap-Status fehlerhaft ist, versucht OpenClaw eine geschützte Reparatur auch ohne `channels.matrix.password`; wenn der Homeserver Passwort-UIA verlangt, protokolliert der Start eine Warnung und bleibt nicht fatal. Bereits vom Owner signierte Geräte bleiben erhalten. -Wenn beim Start dennoch ein fehlerhafter Bootstrap-Status gefunden wird, kann OpenClaw einen geschützten Reparaturpfad versuchen, selbst wenn `channels.matrix.password` nicht konfiguriert ist. -Wenn der Homeserver für diese Reparatur passwortbasierte UIA verlangt, protokolliert OpenClaw eine Warnung und hält den Start nicht-fatal, anstatt den Bot abzubrechen. -Wenn das aktuelle Gerät bereits vom Eigentümer signiert ist, bewahrt OpenClaw diese Identität, anstatt sie automatisch zurückzusetzen. + Siehe [Matrix migration](/de/install/migrating-matrix) für den vollständigen Upgrade-Ablauf. -Siehe [Matrix migration](/de/install/migrating-matrix) für den vollständigen Upgrade-Ablauf, Einschränkungen, Recovery-Befehle und häufige Migrationsmeldungen. + -### Verifizierungshinweise + + Matrix veröffentlicht Hinweise zum Verifizierungslebenszyklus im strikten DM-Verifizierungsraum als `m.notice`-Nachrichten: Anfrage, bereit (mit Hinweis „Verify by emoji“), Start/Abschluss und SAS-Details (Emoji/Dezimal), wenn verfügbar. -Matrix veröffentlicht Hinweise zum Verifizierungslebenszyklus direkt im strikten DM-Verifizierungsraum als `m.notice`-Nachrichten. -Dazu gehören: + Eingehende Anfragen von einem anderen Matrix-Client werden verfolgt und automatisch akzeptiert. Bei Selbstverifizierung startet OpenClaw den SAS-Ablauf automatisch und bestätigt seine eigene Seite, sobald die Emoji-Verifizierung verfügbar ist — du musst aber weiterhin in deinem Matrix-Client vergleichen und „They match“ bestätigen. -- Hinweise zu Verifizierungsanfragen -- Hinweise, dass die Verifizierung bereit ist (mit ausdrücklicher Anleitung „Mit Emoji verifizieren“) -- Hinweise zu Beginn und Abschluss der Verifizierung -- SAS-Details (Emoji und Dezimalzahlen), sofern verfügbar + Systemhinweise zur Verifizierung werden nicht an die Agent-Chat-Pipeline weitergeleitet. -Eingehende Verifizierungsanfragen von einem anderen Matrix-Client werden von OpenClaw verfolgt und automatisch akzeptiert. -Bei Selbstverifizierungsabläufen startet OpenClaw den SAS-Ablauf außerdem automatisch, sobald die Emoji-Verifizierung verfügbar wird, und bestätigt seine eigene Seite. -Bei Verifizierungsanfragen von einem anderen Matrix-Benutzer/-Gerät akzeptiert OpenClaw die Anfrage automatisch und wartet dann darauf, dass der SAS-Ablauf normal weitergeht. -Sie müssen die Emoji- oder dezimalen SAS-Werte weiterhin in Ihrem Matrix-Client vergleichen und dort „Sie stimmen überein“ bestätigen, um die Verifizierung abzuschließen. + -OpenClaw akzeptiert selbst initiierte doppelte Abläufe nicht blind automatisch. Beim Start wird das Erstellen einer neuen Anfrage übersprungen, wenn bereits eine Selbstverifizierungsanfrage aussteht. - -Hinweise des Verifizierungsprotokolls/-systems werden nicht an die Agent-Chat-Pipeline weitergeleitet und erzeugen daher kein `NO_REPLY`. - -### Gerätehygiene - -Alte, von OpenClaw verwaltete Matrix-Geräte können sich im Konto ansammeln und das Vertrauensmodell für verschlüsselte Räume schwerer nachvollziehbar machen. -Listen Sie sie auf mit: + + Alte von OpenClaw verwaltete Geräte können sich ansammeln. Auflisten und bereinigen: ```bash openclaw matrix devices list -``` - -Entfernen Sie veraltete, von OpenClaw verwaltete Geräte mit: - -```bash openclaw matrix devices prune-stale ``` -### Crypto-Store + -Matrix-E2EE verwendet den offiziellen Rust-Kryptopfad des `matrix-js-sdk` in Node, mit `fake-indexeddb` als IndexedDB-Shim. Der Kryptostatus wird in einer Snapshot-Datei (`crypto-idb-snapshot.json`) gespeichert und beim Start wiederhergestellt. Die Snapshot-Datei ist sensibler Laufzeitstatus und wird mit restriktiven Dateiberechtigungen gespeichert. + + Matrix-E2EE verwendet den offiziellen Rust-Crypto-Pfad von `matrix-js-sdk` mit `fake-indexeddb` als IndexedDB-Shim. Der Crypto-Status wird in `crypto-idb-snapshot.json` persistiert (mit restriktiven Dateiberechtigungen). -Verschlüsselter Laufzeitstatus liegt unter Roots pro Konto und pro Benutzer-Token-Hash in -`~/.openclaw/matrix/accounts//__//`. -Dieses Verzeichnis enthält den Sync-Store (`bot-storage.json`), den Crypto-Store (`crypto/`), -die Recovery-Key-Datei (`recovery-key.json`), den IndexedDB-Snapshot (`crypto-idb-snapshot.json`), -Thread-Bindings (`thread-bindings.json`) und den Startup-Verifizierungsstatus (`startup-verification.json`). -Wenn sich das Token ändert, die Kontoidentität aber gleich bleibt, verwendet OpenClaw den besten vorhandenen -Root für dieses Konto-/Homeserver-/Benutzer-Tupel erneut, sodass vorheriger Sync-Status, Crypto-Status, Thread-Bindings -und Startup-Verifizierungsstatus sichtbar bleiben. + Der verschlüsselte Laufzeitstatus liegt unter `~/.openclaw/matrix/accounts//__//` und umfasst den Sync-Store, den Crypto-Store, den Wiederherstellungsschlüssel, den IDB-Snapshot, Thread-Bindungen und den Startverifizierungsstatus. Wenn sich das Token ändert, die Kontoidentität aber gleich bleibt, verwendet OpenClaw das beste vorhandene Root erneut, damit der bisherige Status sichtbar bleibt. + + + ## Profilverwaltung -Aktualisieren Sie das Matrix-Selbstprofil für das ausgewählte Konto mit: +Aktualisiere das Matrix-Selbstprofil für das ausgewählte Konto mit: ```bash openclaw matrix profile set --name "OpenClaw Assistant" openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png ``` -Fügen Sie `--account ` hinzu, wenn Sie gezielt ein benanntes Matrix-Konto ansprechen möchten. +Füge `--account ` hinzu, wenn du explizit ein benanntes Matrix-Konto als Ziel verwenden möchtest. -Matrix akzeptiert `mxc://`-Avatar-URLs direkt. Wenn Sie eine `http://`- oder `https://`-Avatar-URL übergeben, lädt OpenClaw sie zuerst zu Matrix hoch und speichert die aufgelöste `mxc://`-URL zurück in `channels.matrix.avatarUrl` (oder die ausgewählte Konto-Überschreibung). +Matrix akzeptiert `mxc://`-Avatar-URLs direkt. Wenn du eine `http://`- oder `https://`-Avatar-URL übergibst, lädt OpenClaw sie zuerst zu Matrix hoch und speichert die aufgelöste `mxc://`-URL zurück in `channels.matrix.avatarUrl` (oder in die ausgewählte Konto-Überschreibung). ## Threads -Matrix unterstützt native Matrix-Threads sowohl für automatische Antworten als auch für Sends von Message-Tools. +Matrix unterstützt native Matrix-Threads sowohl für automatische Antworten als auch für Sendungen über Message-Tools. -- `dm.sessionScope: "per-user"` (Standard) hält das Routing von Matrix-DMs absenderspezifisch, sodass mehrere DM-Räume eine Sitzung teilen können, wenn sie zu demselben Gegenüber aufgelöst werden. -- `dm.sessionScope: "per-room"` isoliert jeden Matrix-DM-Raum in seinen eigenen Sitzungsschlüssel und verwendet dabei weiterhin normale DM-Authentifizierungs- und Allowlist-Prüfungen. -- Explizite Matrix-Conversation-Bindings haben weiterhin Vorrang vor `dm.sessionScope`, sodass gebundene Räume und Threads ihre gewählte Zielsitzung beibehalten. -- `threadReplies: "off"` hält Antworten auf der obersten Ebene und belässt eingehende Thread-Nachrichten in der übergeordneten Sitzung. +- `dm.sessionScope: "per-user"` (Standard) hält Matrix-DM-Routing absenderbezogen, sodass mehrere DM-Räume eine Sitzung gemeinsam nutzen können, wenn sie zum selben Peer aufgelöst werden. +- `dm.sessionScope: "per-room"` isoliert jeden Matrix-DM-Raum in seinen eigenen Sitzungsschlüssel, verwendet aber weiterhin normale DM-Authentifizierungs- und Allowlist-Prüfungen. +- Explizite Matrix-Konversationsbindungen haben weiterhin Vorrang vor `dm.sessionScope`, sodass gebundene Räume und Threads ihre gewählte Zielsitzung beibehalten. +- `threadReplies: "off"` hält Antworten auf Top-Level-Ebene und belässt eingehende Thread-Nachrichten in der Parent-Sitzung. - `threadReplies: "inbound"` antwortet innerhalb eines Threads nur dann, wenn die eingehende Nachricht bereits in diesem Thread war. -- `threadReplies: "always"` hält Raumantworten in einem Thread mit der auslösenden Nachricht als Wurzel und leitet diese Conversation ab der ersten auslösenden Nachricht durch die passende threadbezogene Sitzung. -- `dm.threadReplies` überschreibt die Einstellung auf oberster Ebene nur für DMs. So können Sie zum Beispiel Raum-Threads isoliert halten und DMs flach lassen. -- Eingehende Thread-Nachrichten enthalten die Thread-Wurzel-Nachricht als zusätzlichen Agent-Kontext. -- Sends von Message-Tools übernehmen automatisch den aktuellen Matrix-Thread, wenn das Ziel derselbe Raum oder dasselbe DM-Benutzerziel ist, sofern kein explizites `threadId` angegeben wird. -- Die Wiederverwendung desselben sitzungsbezogenen DM-Benutzerziels greift nur, wenn die Metadaten der aktuellen Sitzung dasselbe DM-Gegenüber auf demselben Matrix-Konto nachweisen; andernfalls fällt OpenClaw auf normales benutzerbezogenes Routing zurück. -- Wenn OpenClaw erkennt, dass ein Matrix-DM-Raum mit einem anderen DM-Raum auf derselben gemeinsamen Matrix-DM-Sitzung kollidiert, veröffentlicht es in diesem Raum einmalig ein `m.notice` mit dem `/focus`-Escape-Hatch, wenn Thread-Bindings aktiviert sind und der `dm.sessionScope`-Hinweis gilt. -- Laufzeit-Thread-Bindings werden für Matrix unterstützt. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` und threadgebundenes `/acp spawn` funktionieren in Matrix-Räumen und DMs. -- Top-Level-`/focus` in einem Matrix-Raum/DM erstellt einen neuen Matrix-Thread und bindet ihn an die Zielsitzung, wenn `threadBindings.spawnSubagentSessions=true`. -- Wenn `/focus` oder `/acp spawn --thread here` innerhalb eines bestehenden Matrix-Threads ausgeführt wird, bindet es stattdessen diesen aktuellen Thread. +- `threadReplies: "always"` hält Raumantworten in einem Thread, der an der auslösenden Nachricht verankert ist, und leitet diese Konversation ab der ersten auslösenden Nachricht über die passende threadbezogene Sitzung. +- `dm.threadReplies` überschreibt die Top-Level-Einstellung nur für DMs. So kannst du zum Beispiel Raum-Threads isoliert halten und DMs flach halten. +- Eingehende Thread-Nachrichten enthalten die Thread-Root-Nachricht als zusätzlichen Agent-Kontext. +- Sendungen über Message-Tools übernehmen den aktuellen Matrix-Thread automatisch, wenn das Ziel derselbe Raum oder dasselbe DM-Benutzerziel ist, sofern keine explizite `threadId` angegeben wird. +- Die Wiederverwendung desselben sitzungsbezogenen DM-Benutzerziels greift nur, wenn die Metadaten der aktuellen Sitzung denselben DM-Peer auf demselben Matrix-Konto nachweisen; andernfalls fällt OpenClaw auf normales benutzerbezogenes Routing zurück. +- Wenn OpenClaw erkennt, dass ein Matrix-DM-Raum mit einem anderen DM-Raum in derselben gemeinsam genutzten Matrix-DM-Sitzung kollidiert, veröffentlicht es einmalig ein `m.notice` in diesem Raum mit dem `/focus`-Escape-Hatch, wenn Thread-Bindungen aktiviert sind und dem Hinweis `dm.sessionScope`. +- Laufzeit-Thread-Bindungen werden für Matrix unterstützt. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` und threadgebundenes `/acp spawn` funktionieren in Matrix-Räumen und DMs. +- Top-Level-`/focus` in einem Matrix-Raum oder einer DM erstellt einen neuen Matrix-Thread und bindet ihn an die Zielsitzung, wenn `threadBindings.spawnSubagentSessions=true`. +- Das Ausführen von `/focus` oder `/acp spawn --thread here` innerhalb eines bestehenden Matrix-Threads bindet stattdessen diesen aktuellen Thread. -## ACP-Conversation-Bindings +## ACP-Konversationsbindungen -Matrix-Räume, DMs und bestehende Matrix-Threads können in dauerhafte ACP-Workspaces umgewandelt werden, ohne die Chat-Oberfläche zu ändern. +Matrix-Räume, DMs und bestehende Matrix-Threads können in dauerhafte ACP-Arbeitsbereiche verwandelt werden, ohne die Chat-Oberfläche zu ändern. Schneller Operator-Ablauf: -- Führen Sie `/acp spawn codex --bind here` innerhalb der Matrix-DM, des Raums oder des bestehenden Threads aus, den Sie weiterverwenden möchten. -- In einer Matrix-DM oder einem Raum auf oberster Ebene bleibt die aktuelle DM bzw. der aktuelle Raum die Chat-Oberfläche, und künftige Nachrichten werden an die erzeugte ACP-Sitzung geleitet. -- Innerhalb eines bestehenden Matrix-Threads bindet `--bind here` diesen aktuellen Thread an Ort und Stelle. -- `/new` und `/reset` setzen dieselbe gebundene ACP-Sitzung an Ort und Stelle zurück. +- Führe `/acp spawn codex --bind here` innerhalb der Matrix-DM, des Raums oder des bestehenden Threads aus, den du weiterverwenden möchtest. +- In einer Matrix-DM oder einem Raum auf Top-Level-Ebene bleibt die aktuelle DM bzw. der aktuelle Raum die Chat-Oberfläche, und zukünftige Nachrichten werden an die erzeugte ACP-Sitzung geleitet. +- Innerhalb eines bestehenden Matrix-Threads bindet `--bind here` diesen aktuellen Thread direkt. +- `/new` und `/reset` setzen dieselbe gebundene ACP-Sitzung direkt zurück. - `/acp close` schließt die ACP-Sitzung und entfernt die Bindung. Hinweise: @@ -725,9 +464,9 @@ Hinweise: - `--bind here` erstellt keinen untergeordneten Matrix-Thread. - `threadBindings.spawnAcpSessions` ist nur für `/acp spawn --thread auto|here` erforderlich, wenn OpenClaw einen untergeordneten Matrix-Thread erstellen oder binden muss. -### Thread-Binding-Konfiguration +### Thread-Bindungs-Konfiguration -Matrix übernimmt globale Standardwerte aus `session.threadBindings` und unterstützt auch kanalbezogene Überschreibungen: +Matrix übernimmt globale Standardwerte aus `session.threadBindings` und unterstützt auch channelbezogene Überschreibungen: - `threadBindings.enabled` - `threadBindings.idleHours` @@ -735,10 +474,10 @@ Matrix übernimmt globale Standardwerte aus `session.threadBindings` und unterst - `threadBindings.spawnSubagentSessions` - `threadBindings.spawnAcpSessions` -Thread-gebundene Spawn-Flags für Matrix sind Opt-in: +Threadgebundene Spawn-Flags für Matrix sind Opt-in: -- Setzen Sie `threadBindings.spawnSubagentSessions: true`, damit Top-Level-`/focus` neue Matrix-Threads erstellen und binden darf. -- Setzen Sie `threadBindings.spawnAcpSessions: true`, damit `/acp spawn --thread auto|here` ACP-Sitzungen an Matrix-Threads binden darf. +- Setze `threadBindings.spawnSubagentSessions: true`, damit Top-Level-`/focus` neue Matrix-Threads erstellen und binden darf. +- Setze `threadBindings.spawnAcpSessions: true`, damit `/acp spawn --thread auto|here` ACP-Sitzungen an Matrix-Threads binden darf. ## Reaktionen @@ -750,20 +489,20 @@ Matrix unterstützt ausgehende Reaktionsaktionen, eingehende Reaktionsbenachrich - `emoji=""` entfernt die eigenen Reaktionen des Bot-Kontos auf dieses Event. - `remove: true` entfernt nur die angegebene Emoji-Reaktion des Bot-Kontos. -Der Geltungsbereich von Ack-Reaktionen wird in der standardmäßigen OpenClaw-Auflösungsreihenfolge bestimmt: +Der Geltungsbereich von Ack-Reaktionen wird in der Standard-Reihenfolge von OpenClaw aufgelöst: - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` -- Emoji-Fallback der Agent-Identität +- Fallback auf das Agent-Identity-Emoji -Der Geltungsbereich der Ack-Reaktion wird in dieser Reihenfolge bestimmt: +Der Scope von Ack-Reaktionen wird in dieser Reihenfolge aufgelöst: - `channels["matrix"].accounts..ackReactionScope` - `channels["matrix"].ackReactionScope` - `messages.ackReactionScope` -Der Modus für Reaktionsbenachrichtigungen wird in dieser Reihenfolge bestimmt: +Der Modus für Reaktionsbenachrichtigungen wird in dieser Reihenfolge aufgelöst: - `channels["matrix"].accounts..reactionNotifications` - `channels["matrix"].reactionNotifications` @@ -771,30 +510,30 @@ Der Modus für Reaktionsbenachrichtigungen wird in dieser Reihenfolge bestimmt: Verhalten: -- `reactionNotifications: "own"` leitet hinzugefügte `m.reaction`-Events weiter, wenn sie auf vom Bot verfasste Matrix-Nachrichten abzielen. +- `reactionNotifications: "own"` leitet hinzugefügte `m.reaction`-Events weiter, wenn sie auf vom Bot verfasste Matrix-Nachrichten zielen. - `reactionNotifications: "off"` deaktiviert Reaktions-System-Events. -- Das Entfernen von Reaktionen wird nicht in System-Events synthetisiert, weil Matrix diese als Redactions und nicht als eigenständige `m.reaction`-Entfernungen darstellt. +- Das Entfernen von Reaktionen wird nicht in System-Events synthetisiert, da Matrix diese als Redactions und nicht als eigenständige `m.reaction`-Entfernungen darstellt. ## Verlaufskontext -- `channels.matrix.historyLimit` steuert, wie viele aktuelle Raumnachrichten als `InboundHistory` einbezogen werden, wenn eine Matrix-Raumnachricht den Agent auslöst. Fällt zurück auf `messages.groupChat.historyLimit`; wenn beide nicht gesetzt sind, ist der effektive Standardwert `0`. Setzen Sie `0`, um dies zu deaktivieren. -- Der Verlauf von Matrix-Räumen ist nur raumbezogen. DMs verwenden weiterhin den normalen Sitzungsverlauf. -- Der Verlauf von Matrix-Räumen ist nur für ausstehende Nachrichten: OpenClaw puffert Raumnachrichten, die noch keine Antwort ausgelöst haben, und erstellt dann einen Snapshot dieses Fensters, wenn eine Erwähnung oder ein anderer Auslöser eintrifft. -- Die aktuelle auslösende Nachricht ist nicht in `InboundHistory` enthalten; sie bleibt im Hauptteil der eingehenden Nachricht für diesen Turn. -- Wiederholungen desselben Matrix-Events verwenden erneut den ursprünglichen Verlaufs-Snapshot, statt zu neueren Raumnachrichten weiterzudriften. +- `channels.matrix.historyLimit` steuert, wie viele aktuelle Raumnachrichten als `InboundHistory` einbezogen werden, wenn eine Matrix-Raumnachricht den Agent auslöst. Fällt auf `messages.groupChat.historyLimit` zurück; wenn beide nicht gesetzt sind, ist der effektive Standardwert `0`. Setze `0`, um dies zu deaktivieren. +- Der Matrix-Raumverlauf ist nur raumbezogen. DMs verwenden weiterhin den normalen Sitzungsverlauf. +- Der Matrix-Raumverlauf ist nur für ausstehende Nachrichten: OpenClaw puffert Raumnachrichten, die noch keine Antwort ausgelöst haben, und erstellt dann einen Snapshot dieses Fensters, wenn eine Erwähnung oder ein anderer Auslöser eintrifft. +- Die aktuelle Auslösernachricht ist nicht in `InboundHistory` enthalten; sie bleibt für diesen Turn im Hauptteil der eingehenden Nachricht. +- Wiederholungen desselben Matrix-Events verwenden den ursprünglichen Verlaufssnapshot erneut, statt auf neuere Raumnachrichten vorzurücken. -## Kontextsichbarkeit +## Kontextsichtigkeit -Matrix unterstützt die gemeinsame Steuerung `contextVisibility` für ergänzenden Raumkontext wie abgerufenen Antworttext, Thread-Wurzeln und ausstehenden Verlauf. +Matrix unterstützt die gemeinsame Steuerung `contextVisibility` für ergänzenden Raumkontext wie abgerufenen Antworttext, Thread-Roots und ausstehenden Verlauf. -- `contextVisibility: "all"` ist der Standard. Ergänzender Kontext wird unverändert beibehalten. -- `contextVisibility: "allowlist"` filtert ergänzenden Kontext auf Absender, die durch die aktiven Allowlist-Prüfungen für Raum/Benutzer zugelassen sind. -- `contextVisibility: "allowlist_quote"` verhält sich wie `allowlist`, behält aber weiterhin eine explizit zitierte Antwort bei. +- `contextVisibility: "all"` ist der Standard. Ergänzender Kontext bleibt unverändert erhalten. +- `contextVisibility: "allowlist"` filtert ergänzenden Kontext auf Absender, die durch die aktiven Raum-/Benutzer-Allowlist-Prüfungen zugelassen sind. +- `contextVisibility: "allowlist_quote"` verhält sich wie `allowlist`, behält aber dennoch eine explizit zitierte Antwort. -Diese Einstellung wirkt sich auf die Sichtbarkeit ergänzenden Kontexts aus, nicht darauf, ob die eingehende Nachricht selbst eine Antwort auslösen kann. -Die Autorisierung für Auslöser kommt weiterhin von `groupPolicy`, `groups`, `groupAllowFrom` und den DM-Policy-Einstellungen. +Diese Einstellung wirkt sich auf die Sichtbarkeit ergänzenden Kontexts aus, nicht darauf, ob die eingehende Nachricht selbst eine Antwort auslösen darf. +Die Autorisierung für Auslöser kommt weiterhin aus `groupPolicy`, `groups`, `groupAllowFrom` und den DM-Richtlinieneinstellungen. -## DM- und Raum-Policy +## DM- und Raumrichtlinie ```json5 { @@ -826,19 +565,19 @@ openclaw pairing list matrix openclaw pairing approve matrix ``` -Wenn ein nicht genehmigter Matrix-Benutzer Ihnen vor der Genehmigung weiterhin Nachrichten sendet, verwendet OpenClaw denselben ausstehenden Pairing-Code erneut und sendet nach einer kurzen Cooldown-Zeit möglicherweise erneut eine Erinnerungsantwort, anstatt einen neuen Code auszustellen. +Wenn dir ein nicht genehmigter Matrix-Benutzer vor der Genehmigung weiterhin Nachrichten sendet, verwendet OpenClaw denselben ausstehenden Pairing-Code erneut und sendet nach einer kurzen Abkühlzeit möglicherweise erneut eine Erinnerungsantwort, statt einen neuen Code zu erzeugen. Siehe [Pairing](/de/channels/pairing) für den gemeinsamen DM-Pairing-Ablauf und das Speicherlayout. ## Reparatur direkter Räume -Wenn der Direktnachrichtenstatus aus dem Tritt gerät, kann OpenClaw veraltete `m.direct`-Zuordnungen erhalten, die auf alte Solo-Räume statt auf die aktive DM zeigen. Prüfen Sie die aktuelle Zuordnung für ein Gegenüber mit: +Wenn der Status von Direktnachrichten aus dem Takt gerät, kann OpenClaw veraltete `m.direct`-Zuordnungen erhalten, die auf alte Einzelräume statt auf die aktive DM verweisen. Prüfe die aktuelle Zuordnung für einen Peer mit: ```bash openclaw matrix direct inspect --user-id @alice:example.org ``` -Reparieren Sie sie mit: +Repariere sie mit: ```bash openclaw matrix direct repair --user-id @alice:example.org @@ -847,48 +586,48 @@ openclaw matrix direct repair --user-id @alice:example.org Der Reparaturablauf: - bevorzugt eine strikte 1:1-DM, die bereits in `m.direct` zugeordnet ist -- fällt zurück auf eine aktuell beigetretene strikte 1:1-DM mit diesem Benutzer -- erstellt einen neuen direkten Raum und schreibt `m.direct` neu, wenn keine intakte DM vorhanden ist +- fällt auf jede aktuell beigetretene strikte 1:1-DM mit diesem Benutzer zurück +- erstellt einen neuen direkten Raum und schreibt `m.direct` neu, wenn keine gesunde DM existiert -Der Reparaturablauf löscht alte Räume nicht automatisch. Er wählt nur die intakte DM aus und aktualisiert die Zuordnung, damit neue Matrix-Sends, Verifizierungshinweise und andere Direktnachrichtenabläufe wieder den richtigen Raum ansprechen. +Der Reparaturablauf löscht alte Räume nicht automatisch. Er wählt nur die gesunde DM aus und aktualisiert die Zuordnung, sodass neue Matrix-Sendungen, Verifizierungshinweise und andere Direktnachrichten-Abläufe wieder auf den richtigen Raum zielen. -## Exec-Freigaben +## Exec-Genehmigungen -Matrix kann als nativer Freigabe-Client für ein Matrix-Konto fungieren. Die nativen -DM-/Channel-Routing-Regler befinden sich weiterhin unter der Exec-Freigabenkonfiguration: +Matrix kann als nativer Genehmigungs-Client für ein Matrix-Konto fungieren. Die nativen +DM-/Channel-Routing-Schalter liegen weiterhin unter der Exec-Genehmigungskonfiguration: - `channels.matrix.execApprovals.enabled` -- `channels.matrix.execApprovals.approvers` (optional; fällt zurück auf `channels.matrix.dm.allowFrom`) +- `channels.matrix.execApprovals.approvers` (optional; fällt auf `channels.matrix.dm.allowFrom` zurück) - `channels.matrix.execApprovals.target` (`dm` | `channel` | `both`, Standard: `dm`) - `channels.matrix.execApprovals.agentFilter` - `channels.matrix.execApprovals.sessionFilter` -Approver müssen Matrix-Benutzer-IDs wie `@owner:example.org` sein. Matrix aktiviert native Freigaben automatisch, wenn `enabled` nicht gesetzt oder `"auto"` ist und mindestens ein Approver aufgelöst werden kann. Exec-Freigaben verwenden zuerst `execApprovals.approvers` und können auf `channels.matrix.dm.allowFrom` zurückfallen. Plugin-Freigaben autorisieren über `channels.matrix.dm.allowFrom`. Setzen Sie `enabled: false`, um Matrix explizit als nativen Freigabe-Client zu deaktivieren. Freigabeanfragen fallen andernfalls auf andere konfigurierte Freigaberouten oder die Fallback-Policy für Freigaben zurück. +Genehmigende müssen Matrix-Benutzer-IDs wie `@owner:example.org` sein. Matrix aktiviert native Genehmigungen automatisch, wenn `enabled` nicht gesetzt oder `"auto"` ist und mindestens ein Genehmigender aufgelöst werden kann. Exec-Genehmigungen verwenden zuerst `execApprovals.approvers` und können auf `channels.matrix.dm.allowFrom` zurückfallen. Plugin-Genehmigungen autorisieren über `channels.matrix.dm.allowFrom`. Setze `enabled: false`, um Matrix explizit als nativen Genehmigungs-Client zu deaktivieren. Genehmigungsanfragen fallen andernfalls auf andere konfigurierte Genehmigungswege oder die Fallback-Richtlinie für Genehmigungen zurück. -Native Matrix-Routing unterstützt beide Freigabearten: +Matrix-Native-Routing unterstützt beide Genehmigungsarten: -- `channels.matrix.execApprovals.*` steuert den nativen DM-/Channel-Fanout-Modus für Matrix-Freigabeaufforderungen. -- Exec-Freigaben verwenden den Exec-Approver-Satz aus `execApprovals.approvers` oder `channels.matrix.dm.allowFrom`. -- Plugin-Freigaben verwenden die Matrix-DM-Allowlist aus `channels.matrix.dm.allowFrom`. -- Matrix-Reaktions-Shortcuts und Nachrichtenaktualisierungen gelten für Exec- und Plugin-Freigaben. +- `channels.matrix.execApprovals.*` steuert den nativen DM-/Channel-Fanout-Modus für Matrix-Genehmigungsaufforderungen. +- Exec-Genehmigungen verwenden die Exec-Genehmigenden aus `execApprovals.approvers` oder `channels.matrix.dm.allowFrom`. +- Plugin-Genehmigungen verwenden die Matrix-DM-Allowlist aus `channels.matrix.dm.allowFrom`. +- Matrix-Reaktionskürzel und Nachrichtenaktualisierungen gelten sowohl für Exec- als auch für Plugin-Genehmigungen. -Zustellregeln: +Zustellungsregeln: -- `target: "dm"` sendet Freigabeaufforderungen an DMs der Approver -- `target: "channel"` sendet die Aufforderung zurück an den auslösenden Matrix-Raum oder die auslösende DM -- `target: "both"` sendet an DMs der Approver und an den auslösenden Matrix-Raum oder die auslösende DM +- `target: "dm"` sendet Genehmigungsaufforderungen an DMs der Genehmigenden +- `target: "channel"` sendet die Aufforderung zurück an den auslösenden Matrix-Raum oder die DM +- `target: "both"` sendet an DMs der Genehmigenden und an den auslösenden Matrix-Raum oder die DM -Matrix-Freigabeaufforderungen initialisieren Reaktions-Shortcuts auf der primären Freigabenachricht: +Matrix-Genehmigungsaufforderungen setzen Reaktionskürzel auf der primären Genehmigungsnachricht: - `✅` = einmal erlauben - `❌` = ablehnen -- `♾️` = immer erlauben, wenn diese Entscheidung durch die effektive Exec-Policy zulässig ist +- `♾️` = immer erlauben, wenn diese Entscheidung durch die effektive Exec-Richtlinie zulässig ist -Approver können auf diese Nachricht reagieren oder die Fallback-Slash-Befehle verwenden: `/approve allow-once`, `/approve allow-always` oder `/approve deny`. +Genehmigende können auf diese Nachricht reagieren oder die Fallback-Slash-Befehle verwenden: `/approve allow-once`, `/approve allow-always` oder `/approve deny`. -Nur aufgelöste Approver können erlauben oder ablehnen. Bei Exec-Freigaben enthält die Channel-Zustellung den Befehlstext, daher `channel` oder `both` nur in vertrauenswürdigen Räumen aktivieren. +Nur aufgelöste Genehmigende können genehmigen oder ablehnen. Bei Exec-Genehmigungen umfasst die Channel-Zustellung den Befehlstext, daher solltest du `channel` oder `both` nur in vertrauenswürdigen Räumen aktivieren. -Überschreibung pro Konto: +Kontoabhängige Überschreibung: - `channels.matrix.accounts..execApprovals` @@ -896,11 +635,11 @@ Verwandte Dokumentation: [Exec approvals](/de/tools/exec-approvals) ## Slash-Befehle -Matrix-Slash-Befehle (zum Beispiel `/new`, `/reset`, `/model`) funktionieren direkt in DMs. In Räumen erkennt OpenClaw außerdem Slash-Befehle, denen die eigene Matrix-Erwähnung des Bots vorangestellt ist, sodass `@bot:server /new` den Befehlspfad auslöst, ohne dass ein benutzerdefinierter Regex für Erwähnungen nötig ist. Dadurch bleibt der Bot reaktionsfähig für raumartige Beiträge im Stil `@mention /command`, die von Element und ähnlichen Clients erzeugt werden, wenn ein Benutzer den Bot per Tab-Vervollständigung einfügt, bevor er den Befehl tippt. +Matrix-Slash-Befehle (zum Beispiel `/new`, `/reset`, `/model`) funktionieren direkt in DMs. In Räumen erkennt OpenClaw zusätzlich Slash-Befehle, denen die eigene Matrix-Erwähnung des Bots vorangestellt ist, sodass `@bot:server /new` den Befehlspfad auslöst, ohne dass ein benutzerdefinierter Erwähnungs-Regex erforderlich ist. So bleibt der Bot reaktionsfähig auf raumtypische Beiträge im Stil `@mention /command`, die Element und ähnliche Clients senden, wenn ein Benutzer den Bot per Tab-Vervollständigung auswählt, bevor er den Befehl eintippt. -Autorisierungsregeln gelten weiterhin: Absender von Befehlen müssen dieselben DM- oder Raum-Allowlist-/Owner-Richtlinien erfüllen wie bei normalen Nachrichten. +Autorisierungsregeln gelten weiterhin: Befehlssender müssen genau wie bei normalen Nachrichten die DM- oder Raum-Allowlist-/Owner-Richtlinien erfüllen. -## Mehrere Konten +## Multi-Account ```json5 { @@ -930,24 +669,24 @@ Autorisierungsregeln gelten weiterhin: Absender von Befehlen müssen dieselben D } ``` -Werte auf oberster Ebene unter `channels.matrix` dienen als Standardwerte für benannte Konten, sofern ein Konto sie nicht überschreibt. -Sie können geerbte Raumeinträge mit `groups..account` auf ein Matrix-Konto beschränken. -Einträge ohne `account` bleiben über alle Matrix-Konten hinweg gemeinsam, und Einträge mit `account: "default"` funktionieren weiterhin, wenn das Standardkonto direkt auf oberster Ebene unter `channels.matrix.*` konfiguriert ist. -Partielle gemeinsame Authentifizierungsstandardwerte erzeugen für sich genommen kein separates implizites Standardkonto. OpenClaw synthetisiert das Top-Level-Konto `default` nur dann, wenn dieses Standardkonto frische Authentifizierung hat (`homeserver` plus `accessToken` oder `homeserver` plus `userId` und `password`); benannte Konten können dennoch über `homeserver` plus `userId` auffindbar bleiben, wenn zwischengespeicherte Anmeldedaten die Authentifizierung später erfüllen. -Wenn Matrix bereits genau ein benanntes Konto hat oder `defaultAccount` auf einen vorhandenen benannten Kontoschlüssel zeigt, bewahrt die Reparatur/Einrichtungs-Hochstufung von Einzelkonto zu Mehrkonten dieses Konto, statt einen neuen Eintrag `accounts.default` zu erzeugen. Nur Matrix-Authentifizierungs-/Bootstrap-Schlüssel werden in dieses hochgestufte Konto verschoben; gemeinsame Richtlinienschlüssel für die Zustellung bleiben auf oberster Ebene. -Setzen Sie `defaultAccount`, wenn OpenClaw ein benanntes Matrix-Konto für implizites Routing, Probing und CLI-Operationen bevorzugen soll. -Wenn mehrere Matrix-Konten konfiguriert sind und eine Konto-ID `default` ist, verwendet OpenClaw dieses Konto implizit, auch wenn `defaultAccount` nicht gesetzt ist. -Wenn Sie mehrere benannte Konten konfigurieren, setzen Sie `defaultAccount` oder übergeben Sie `--account ` für CLI-Befehle, die auf impliziter Kontoauswahl basieren. -Übergeben Sie `--account ` an `openclaw matrix verify ...` und `openclaw matrix devices ...`, wenn Sie diese implizite Auswahl für einen einzelnen Befehl überschreiben möchten. +Top-Level-Werte unter `channels.matrix` dienen als Standardwerte für benannte Konten, sofern ein Konto sie nicht überschreibt. +Du kannst geerbte Raumeinträge mit `groups..account` auf ein Matrix-Konto begrenzen. +Einträge ohne `account` bleiben über alle Matrix-Konten hinweg gemeinsam genutzt, und Einträge mit `account: "default"` funktionieren weiterhin, wenn das Standardkonto direkt auf Top-Level unter `channels.matrix.*` konfiguriert ist. +Partielle gemeinsame Auth-Standardwerte erzeugen für sich genommen kein separates implizites Standardkonto. OpenClaw synthetisiert das Top-Level-Konto `default` nur dann, wenn dieses Standardkonto frische Authentifizierung hat (`homeserver` plus `accessToken` oder `homeserver` plus `userId` und `password`); benannte Konten können dennoch über `homeserver` plus `userId` auffindbar bleiben, wenn zwischengespeicherte Anmeldedaten die Authentifizierung später erfüllen. +Wenn Matrix bereits genau ein benanntes Konto hat oder `defaultAccount` auf einen vorhandenen benannten Kontoschlüssel verweist, bewahrt die Reparatur-/Einrichtungs-Promotion von Einzelkonto zu Multi-Account dieses Konto, statt einen neuen Eintrag `accounts.default` zu erstellen. Nur Matrix-Auth-/Bootstrap-Schlüssel werden in dieses hochgestufte Konto verschoben; gemeinsame Zustellungsrichtlinien-Schlüssel bleiben auf der obersten Ebene. +Setze `defaultAccount`, wenn OpenClaw für implizites Routing, Probing und CLI-Operationen ein benanntes Matrix-Konto bevorzugen soll. +Wenn mehrere Matrix-Konten konfiguriert sind und eine Konto-ID `default` ist, verwendet OpenClaw dieses Konto implizit auch dann, wenn `defaultAccount` nicht gesetzt ist. +Wenn du mehrere benannte Konten konfigurierst, setze `defaultAccount` oder übergib `--account ` für CLI-Befehle, die auf impliziter Kontoauswahl beruhen. +Übergebe `--account ` an `openclaw matrix verify ...` und `openclaw matrix devices ...`, wenn du diese implizite Auswahl für einen einzelnen Befehl überschreiben möchtest. -Siehe [Configuration reference](/de/gateway/configuration-reference#multi-account-all-channels) für das gemeinsame Muster mit mehreren Konten. +Siehe [Configuration reference](/de/gateway/configuration-reference#multi-account-all-channels) für das gemeinsame Multi-Account-Muster. ## Private/LAN-Homeserver -Standardmäßig blockiert OpenClaw private/interne Matrix-Homeserver zum Schutz vor SSRF, sofern Sie -nicht explizit pro Konto ein Opt-in setzen. +Standardmäßig blockiert OpenClaw private/interne Matrix-Homeserver zum Schutz vor SSRF, sofern du +nicht explizit pro Konto zustimmst. -Wenn Ihr Homeserver auf localhost, einer LAN-/Tailscale-IP oder einem internen Hostnamen läuft, aktivieren Sie +Wenn dein Homeserver auf localhost, einer LAN-/Tailscale-IP oder einem internen Hostnamen läuft, aktiviere `network.dangerouslyAllowPrivateNetwork` für dieses Matrix-Konto: ```json5 @@ -974,12 +713,12 @@ openclaw matrix account add \ --access-token syt_ops_xxx ``` -Dieses Opt-in erlaubt nur vertrauenswürdige private/interne Ziele. Öffentliche Homeserver im Klartext wie -`http://matrix.example.org:8008` bleiben blockiert. Verwenden Sie nach Möglichkeit `https://`. +Dieses Opt-in erlaubt nur vertrauenswürdige private/interne Ziele. Öffentliche Homeserver mit Klartext wie +`http://matrix.example.org:8008` bleiben blockiert. Bevorzuge nach Möglichkeit `https://`. -## Proxying für Matrix-Datenverkehr +## Matrix-Datenverkehr über Proxy leiten -Wenn Ihre Matrix-Bereitstellung einen expliziten ausgehenden HTTP(S)-Proxy benötigt, setzen Sie `channels.matrix.proxy`: +Wenn deine Matrix-Bereitstellung einen expliziten ausgehenden HTTP(S)-Proxy benötigt, setze `channels.matrix.proxy`: ```json5 { @@ -993,86 +732,86 @@ Wenn Ihre Matrix-Bereitstellung einen expliziten ausgehenden HTTP(S)-Proxy benö } ``` -Benannte Konten können den Standardwert der obersten Ebene mit `channels.matrix.accounts..proxy` überschreiben. -OpenClaw verwendet dieselbe Proxy-Einstellung für den laufenden Matrix-Datenverkehr und für Account-Status-Probes. +Benannte Konten können den Top-Level-Standard mit `channels.matrix.accounts..proxy` überschreiben. +OpenClaw verwendet dieselbe Proxy-Einstellung für laufenden Matrix-Datenverkehr und Prüfungen des Kontostatus. ## Zielauflösung -Matrix akzeptiert diese Zielformen überall dort, wo OpenClaw Sie nach einem Raum- oder Benutzerziel fragt: +Matrix akzeptiert diese Zielformen überall dort, wo OpenClaw dich nach einem Raum- oder Benutzerziel fragt: - Benutzer: `@user:server`, `user:@user:server` oder `matrix:user:@user:server` - Räume: `!room:server`, `room:!room:server` oder `matrix:room:!room:server` -- Aliasse: `#alias:server`, `channel:#alias:server` oder `matrix:channel:#alias:server` +- Aliase: `#alias:server`, `channel:#alias:server` oder `matrix:channel:#alias:server` -Die Live-Verzeichnissuche verwendet das angemeldete Matrix-Konto: +Die Live-Verzeichnisauflösung verwendet das angemeldete Matrix-Konto: -- Benutzersuchen fragen das Matrix-Benutzerverzeichnis auf diesem Homeserver ab. -- Raumsuchen akzeptieren explizite Raum-IDs und Aliasse direkt und fallen dann auf die Suche in beigetretenen Raumnamen für dieses Konto zurück. -- Die Suche nach Namen beigetretener Räume erfolgt best effort. Wenn ein Raumname nicht zu einer ID oder einem Alias aufgelöst werden kann, wird er von der Laufzeit-Auflösung der Allowlist ignoriert. +- Benutzerabfragen durchsuchen das Matrix-Benutzerverzeichnis auf diesem Homeserver. +- Raumabfragen akzeptieren explizite Raum-IDs und Aliase direkt und fallen dann auf die Suche nach beigetretenen Raumnamen für dieses Konto zurück. +- Die Suche nach Namen beigetretener Räume ist Best-Effort. Wenn ein Raumname nicht zu einer ID oder einem Alias aufgelöst werden kann, wird er bei der Laufzeit-Auflösung der Allowlist ignoriert. ## Konfigurationsreferenz -- `enabled`: aktiviert oder deaktiviert den Channel. +- `enabled`: den Channel aktivieren oder deaktivieren. - `name`: optionales Label für das Konto. - `defaultAccount`: bevorzugte Konto-ID, wenn mehrere Matrix-Konten konfiguriert sind. - `homeserver`: Homeserver-URL, zum Beispiel `https://matrix.example.org`. -- `network.dangerouslyAllowPrivateNetwork`: erlaubt diesem Matrix-Konto, sich mit privaten/internen Homeservern zu verbinden. Aktivieren Sie dies, wenn der Homeserver zu `localhost`, einer LAN-/Tailscale-IP oder einem internen Host wie `matrix-synapse` aufgelöst wird. -- `proxy`: optionale HTTP(S)-Proxy-URL für Matrix-Datenverkehr. Benannte Konten können den Standardwert der obersten Ebene mit ihrem eigenen `proxy` überschreiben. +- `network.dangerouslyAllowPrivateNetwork`: diesem Matrix-Konto erlauben, sich mit privaten/internen Homeservern zu verbinden. Aktiviere dies, wenn der Homeserver zu `localhost`, einer LAN-/Tailscale-IP oder einem internen Host wie `matrix-synapse` aufgelöst wird. +- `proxy`: optionale HTTP(S)-Proxy-URL für Matrix-Datenverkehr. Benannte Konten können den Top-Level-Standard mit ihrem eigenen `proxy` überschreiben. - `userId`: vollständige Matrix-Benutzer-ID, zum Beispiel `@bot:example.org`. -- `accessToken`: Access-Token für tokenbasierte Authentifizierung. Klartextwerte und SecretRef-Werte werden für `channels.matrix.accessToken` und `channels.matrix.accounts..accessToken` über Env-/Datei-/Exec-Provider hinweg unterstützt. Siehe [Secrets Management](/de/gateway/secrets). +- `accessToken`: Access-Token für tokenbasierte Authentifizierung. Klartextwerte und SecretRef-Werte werden für `channels.matrix.accessToken` und `channels.matrix.accounts..accessToken` bei env-/file-/exec-Providern unterstützt. Siehe [Secrets Management](/de/gateway/secrets). - `password`: Passwort für passwortbasierte Anmeldung. Klartextwerte und SecretRef-Werte werden unterstützt. - `deviceId`: explizite Matrix-Geräte-ID. -- `deviceName`: Anzeigename des Geräts für die Passwortanmeldung. -- `avatarUrl`: gespeicherte Selbst-Avatar-URL für Profilsynchronisierung und `profile set`-Aktualisierungen. -- `initialSyncLimit`: maximale Anzahl von Events, die beim Start-Sync abgerufen werden. -- `encryption`: aktiviert E2EE. -- `allowlistOnly`: wenn `true`, wird die Raum-Policy `open` auf `allowlist` hochgestuft und alle aktiven DM-Policies außer `disabled` (einschließlich `pairing` und `open`) werden auf `allowlist` gesetzt. Wirkt sich nicht auf `disabled`-Policies aus. -- `allowBots`: erlaubt Nachrichten von anderen konfigurierten OpenClaw-Matrix-Konten (`true` oder `"mentions"`). +- `deviceName`: Anzeigename des Geräts für die Passwort-Anmeldung. +- `avatarUrl`: gespeicherte Self-Avatar-URL für Profilsynchronisierung und `profile set`-Aktualisierungen. +- `initialSyncLimit`: maximale Anzahl an Events, die beim Startup-Sync abgerufen werden. +- `encryption`: E2EE aktivieren. +- `allowlistOnly`: wenn `true`, wird die Raumrichtlinie `open` auf `allowlist` hochgestuft und alle aktiven DM-Richtlinien außer `disabled` (einschließlich `pairing` und `open`) werden zu `allowlist` erzwungen. Hat keine Auswirkung auf `disabled`-Richtlinien. +- `allowBots`: Nachrichten von anderen konfigurierten OpenClaw-Matrix-Konten zulassen (`true` oder `"mentions"`). - `groupPolicy`: `open`, `allowlist` oder `disabled`. - `contextVisibility`: Sichtbarkeitsmodus für ergänzenden Raumkontext (`all`, `allowlist`, `allowlist_quote`). -- `groupAllowFrom`: Allowlist von Benutzer-IDs für Raumverkehr. Vollständige Matrix-Benutzer-IDs sind am sichersten; exakte Verzeichnisübereinstimmungen werden beim Start und bei Änderungen der Allowlist aufgelöst, während der Monitor läuft. Nicht aufgelöste Namen werden ignoriert. -- `historyLimit`: maximale Anzahl von Raumnachrichten, die als Gruppenverlaufs-Kontext einbezogen werden. Fällt zurück auf `messages.groupChat.historyLimit`; wenn beide nicht gesetzt sind, ist der effektive Standardwert `0`. Setzen Sie `0`, um dies zu deaktivieren. +- `groupAllowFrom`: Allowlist von Benutzer-IDs für Raumdatenverkehr. Vollständige Matrix-Benutzer-IDs sind am sichersten; exakte Verzeichnisübereinstimmungen werden beim Start und bei Änderungen der Allowlist aufgelöst, während der Monitor läuft. Nicht aufgelöste Namen werden ignoriert. +- `historyLimit`: maximale Anzahl an Raumnachrichten, die als Gruppenverlaufs-Kontext einbezogen werden. Fällt auf `messages.groupChat.historyLimit` zurück; wenn beide nicht gesetzt sind, ist der effektive Standardwert `0`. Setze `0`, um dies zu deaktivieren. - `replyToMode`: `off`, `first`, `all` oder `batched`. - `markdown`: optionale Markdown-Rendering-Konfiguration für ausgehenden Matrix-Text. -- `streaming`: `off` (Standard), `"partial"`, `"quiet"`, `true` oder `false`. `"partial"` und `true` aktivieren Vorschau-zuerst-Entwurfsaktualisierungen mit normalen Matrix-Textnachrichten. `"quiet"` verwendet nicht benachrichtigende Vorschau-Hinweise für selbst gehostete Push-Regel-Setups. `false` entspricht `"off"`. +- `streaming`: `off` (Standard), `"partial"`, `"quiet"`, `true` oder `false`. `"partial"` und `true` aktivieren Vorschau-zuerst-Entwurfsaktualisierungen mit normalen Matrix-Textnachrichten. `"quiet"` verwendet nicht benachrichtigende Vorschau-Hinweise für selbstgehostete Push-Regel-Setups. `false` entspricht `"off"`. - `blockStreaming`: `true` aktiviert separate Fortschrittsnachrichten für abgeschlossene Assistant-Blöcke, während Entwurfs-Vorschau-Streaming aktiv ist. - `threadReplies`: `off`, `inbound` oder `always`. -- `threadBindings`: kanalbezogene Überschreibungen für threadgebundenes Sitzungsrouting und dessen Lebenszyklus. -- `startupVerification`: automatischer Selbstverifizierungs-Anfragemodus beim Start (`if-unverified`, `off`). -- `startupVerificationCooldownHours`: Cooldown vor erneuten Versuchen automatischer Start-Verifizierungsanfragen. -- `textChunkLimit`: Größe ausgehender Nachrichten-Chunks in Zeichen (gilt, wenn `chunkMode` auf `length` gesetzt ist). +- `threadBindings`: channelbezogene Überschreibungen für threadgebundenes Sitzungsrouting und dessen Lebenszyklus. +- `startupVerification`: Modus für automatische Selbstverifizierungsanfragen beim Start (`if-unverified`, `off`). +- `startupVerificationCooldownHours`: Abkühlzeit vor erneutem Versuch automatischer Startverifizierungsanfragen. +- `textChunkLimit`: Größe ausgehender Nachrichten-Chunks in Zeichen (gilt, wenn `chunkMode` auf `length` steht). - `chunkMode`: `length` teilt Nachrichten nach Zeichenanzahl; `newline` teilt an Zeilengrenzen. - `responsePrefix`: optionale Zeichenfolge, die allen ausgehenden Antworten für diesen Channel vorangestellt wird. - `ackReaction`: optionale Überschreibung der Ack-Reaktion für diesen Channel/dieses Konto. -- `ackReactionScope`: optionale Überschreibung des Geltungsbereichs der Ack-Reaktion (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`). +- `ackReactionScope`: optionale Überschreibung des Ack-Reaktionsbereichs (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`). - `reactionNotifications`: Modus für eingehende Reaktionsbenachrichtigungen (`own`, `off`). -- `mediaMaxMb`: Mediengrößenlimit in MB für ausgehende Sends und die Verarbeitung eingehender Medien. -- `autoJoin`: Policy für automatisches Beitreten bei Einladungen (`always`, `allowlist`, `off`). Standard: `off`. Gilt für alle Matrix-Einladungen, einschließlich DM-artiger Einladungen. -- `autoJoinAllowlist`: Räume/Aliasse, die erlaubt sind, wenn `autoJoin` auf `allowlist` gesetzt ist. Alias-Einträge werden während der Einladungsverarbeitung zu Raum-IDs aufgelöst; OpenClaw vertraut nicht auf den vom eingeladenen Raum behaupteten Alias-Status. -- `dm`: DM-Policy-Block (`enabled`, `policy`, `allowFrom`, `sessionScope`, `threadReplies`). -- `dm.policy`: steuert den DM-Zugriff, nachdem OpenClaw dem Raum beigetreten ist und ihn als DM klassifiziert hat. Es ändert nicht, ob einer Einladung automatisch beigetreten wird. -- `dm.allowFrom`: Allowlist von Benutzer-IDs für DM-Verkehr. Vollständige Matrix-Benutzer-IDs sind am sichersten; exakte Verzeichnisübereinstimmungen werden beim Start und bei Änderungen der Allowlist aufgelöst, während der Monitor läuft. Nicht aufgelöste Namen werden ignoriert. -- `dm.sessionScope`: `per-user` (Standard) oder `per-room`. Verwenden Sie `per-room`, wenn Sie möchten, dass jeder Matrix-DM-Raum einen separaten Kontext behält, auch wenn das Gegenüber dasselbe ist. -- `dm.threadReplies`: DM-spezifische Überschreibung der Thread-Policy (`off`, `inbound`, `always`). Überschreibt die Top-Level-Einstellung `threadReplies` sowohl für die Platzierung von Antworten als auch für die Sitzungsisolation in DMs. -- `execApprovals`: Matrix-native Zustellung von Exec-Freigaben (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). -- `execApprovals.approvers`: Matrix-Benutzer-IDs, die Exec-Anfragen genehmigen dürfen. Optional, wenn `dm.allowFrom` die Approver bereits identifiziert. +- `mediaMaxMb`: Obergrenze für Mediengröße in MB für ausgehende Sendungen und eingehende Medienverarbeitung. +- `autoJoin`: Richtlinie für automatisches Beitreten bei Einladungen (`always`, `allowlist`, `off`). Standard: `off`. Gilt für alle Matrix-Einladungen, einschließlich DM-artiger Einladungen. +- `autoJoinAllowlist`: Räume/Aliase, die zulässig sind, wenn `autoJoin` auf `allowlist` steht. Alias-Einträge werden bei der Einladungsverarbeitung zu Raum-IDs aufgelöst; OpenClaw vertraut nicht dem Alias-Status, den der eingeladene Raum behauptet. +- `dm`: DM-Richtlinienblock (`enabled`, `policy`, `allowFrom`, `sessionScope`, `threadReplies`). +- `dm.policy`: steuert den DM-Zugriff, nachdem OpenClaw dem Raum beigetreten ist und ihn als DM klassifiziert hat. Ändert nicht, ob einer Einladung automatisch beigetreten wird. +- `dm.allowFrom`: Allowlist von Benutzer-IDs für DM-Datenverkehr. Vollständige Matrix-Benutzer-IDs sind am sichersten; exakte Verzeichnisübereinstimmungen werden beim Start und bei Änderungen der Allowlist aufgelöst, während der Monitor läuft. Nicht aufgelöste Namen werden ignoriert. +- `dm.sessionScope`: `per-user` (Standard) oder `per-room`. Verwende `per-room`, wenn jeder Matrix-DM-Raum einen separaten Kontext behalten soll, selbst wenn es derselbe Peer ist. +- `dm.threadReplies`: DM-spezifische Überschreibung der Thread-Richtlinie (`off`, `inbound`, `always`). Überschreibt die Top-Level-Einstellung `threadReplies` sowohl für die Platzierung von Antworten als auch für die Sitzungsisolierung in DMs. +- `execApprovals`: Matrix-native Zustellung von Exec-Genehmigungen (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). +- `execApprovals.approvers`: Matrix-Benutzer-IDs, die Exec-Anfragen genehmigen dürfen. Optional, wenn `dm.allowFrom` die Genehmigenden bereits identifiziert. - `execApprovals.target`: `dm | channel | both` (Standard: `dm`). -- `accounts`: benannte Überschreibungen pro Konto. Top-Level-Werte unter `channels.matrix` dienen als Standardwerte für diese Einträge. -- `groups`: Policy-Map pro Raum. Bevorzugen Sie Raum-IDs oder Aliasse; nicht aufgelöste Raumnamen werden zur Laufzeit ignoriert. Sitzungs-/Gruppenidentität verwendet nach der Auflösung die stabile Raum-ID. -- `groups..account`: beschränkt einen geerbten Raumeintrag in Mehrkonten-Setups auf ein bestimmtes Matrix-Konto. -- `groups..allowBots`: Überschreibung auf Raumebene für konfigurierte Bot-Absender (`true` oder `"mentions"`). -- `groups..users`: Allowlist pro Raum für Absender. -- `groups..tools`: Überschreibungen für Erlauben/Verweigern von Tools pro Raum. -- `groups..autoReply`: Überschreibung des Erwähnungs-Gatings auf Raumebene. `true` deaktiviert Erwähnungsanforderungen für diesen Raum; `false` erzwingt sie wieder. -- `groups..skills`: optionaler Skills-Filter auf Raumebene. -- `groups..systemPrompt`: optionales Snippet für den System-Prompt auf Raumebene. -- `rooms`: veralteter Alias für `groups`. +- `accounts`: benannte kontoabhängige Überschreibungen. Top-Level-Werte unter `channels.matrix` dienen als Standardwerte für diese Einträge. +- `groups`: richtlinienbezogene Zuordnung pro Raum. Bevorzuge Raum-IDs oder Aliase; nicht aufgelöste Raumnamen werden zur Laufzeit ignoriert. Sitzungs-/Gruppenidentität verwendet nach der Auflösung die stabile Raum-ID. +- `groups..account`: einen geerbten Raumeintrag in Multi-Account-Setups auf ein bestimmtes Matrix-Konto beschränken. +- `groups..allowBots`: raumbezogene Überschreibung für Sender aus konfigurierten Bots (`true` oder `"mentions"`). +- `groups..users`: senderbezogene Allowlist pro Raum. +- `groups..tools`: raumbezogene Tool-Allow-/Deny-Überschreibungen. +- `groups..autoReply`: raumbezogene Überschreibung für Erwähnungs-Gating. `true` deaktiviert die Erwähnungsanforderungen für diesen Raum; `false` erzwingt sie wieder. +- `groups..skills`: optionaler raumbezogener Skills-Filter. +- `groups..systemPrompt`: optionales raumbezogenes System-Prompt-Snippet. +- `rooms`: Legacy-Alias für `groups`. - `actions`: Tool-Gating pro Aktion (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`). ## Verwandt - [Channels Overview](/de/channels) — alle unterstützten Channels - [Pairing](/de/channels/pairing) — DM-Authentifizierung und Pairing-Ablauf -- [Groups](/de/channels/groups) — Verhalten in Gruppenchats und Erwähnungs-Gating +- [Groups](/de/channels/groups) — Gruppenchat-Verhalten und Erwähnungs-Gating - [Channel Routing](/de/channels/channel-routing) — Sitzungsrouting für Nachrichten - [Security](/de/gateway/security) — Zugriffsmodell und Härtung diff --git a/docs/de/ci.md b/docs/de/ci.md index c878dadfa..ec29a2afb 100644 --- a/docs/de/ci.md +++ b/docs/de/ci.md @@ -1,107 +1,108 @@ --- read_when: - Sie müssen verstehen, warum ein CI-Job ausgeführt wurde oder nicht. - - Sie debuggen fehlschlagende GitHub-Actions-Checks. + - Sie debuggen fehlgeschlagene GitHub-Actions-Prüfungen summary: CI-Job-Graph, Scope-Gates und lokale Befehlsäquivalente title: CI-Pipeline x-i18n: - generated_at: "2026-04-23T13:59:16Z" + generated_at: "2026-04-23T14:55:33Z" model: gpt-5.4 provider: openai - source_hash: c5a8ea0d8e428826169b0e6aced1caeb993106fe79904002125ace86b48cae1f + source_hash: e9a03440ae28a15167fc08d9c66bb1fd719ddfa1517aaecb119c80f2ad826c0d source_path: ci.md workflow: 15 --- # CI-Pipeline -Die CI läuft bei jedem Push nach `main` und bei jedem Pull Request. Sie verwendet intelligentes Scoping, um teure Jobs zu überspringen, wenn sich nur nicht zusammenhängende Bereiche geändert haben. +Die CI läuft bei jedem Push auf `main` und bei jedem Pull Request. Sie verwendet intelligentes Scoping, um teure Jobs zu überspringen, wenn nur nicht zusammenhängende Bereiche geändert wurden. -QA Lab hat eigene CI-Lanes außerhalb des primären intelligent gescopten Workflows. Der -Workflow `Parity gate` läuft bei passenden PR-Änderungen und per manuellem Dispatch; er -baut die private QA-Runtime und vergleicht die agentischen Packs für Mock GPT-5.4 und Opus 4.6. -Der Workflow `QA-Lab - All Lanes` läuft nachts auf `main` und per +QA Lab hat dedizierte CI-Lanes außerhalb des Haupt-Workflows mit intelligentem Scoping. Der +Workflow `Parity gate` läuft bei passenden PR-Änderungen und bei manuellem Dispatch; er +baut die private QA-Laufzeit und vergleicht die agentischen Packs für Mock GPT-5.4 und Opus 4.6. +Der Workflow `QA-Lab - All Lanes` läuft nachts auf `main` und bei manuellem Dispatch; er fächert das Mock-Parity-Gate, die Live-Matrix-Lane und die Live- Telegram-Lane als parallele Jobs auf. Die Live-Jobs verwenden die Umgebung `qa-live-shared`, und die Telegram-Lane verwendet Convex-Leases. `OpenClaw Release -Checks` führt vor der Freigabe eines Releases ebenfalls dieselben QA-Lab-Lanes aus. +Checks` führt außerdem dieselben QA-Lab-Lanes vor der Release-Freigabe aus. -## Job-Überblick +## Job-Übersicht | Job | Zweck | Wann er läuft | | -------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------- | -| `preflight` | Nur-Doku-Änderungen, geänderte Scopes, geänderte extensions erkennen und das CI-Manifest bauen | Immer bei Nicht-Entwurfs-Pushes und PRs | -| `security-scm-fast` | Erkennung privater Schlüssel und Workflow-Audit über `zizmor` | Immer bei Nicht-Entwurfs-Pushes und PRs | -| `security-dependency-audit` | Produktions-Lockfile-Audit ohne Abhängigkeiten gegen npm-Advisories | Immer bei Nicht-Entwurfs-Pushes und PRs | -| `security-fast` | Erforderliches Aggregat für die schnellen Security-Jobs | Immer bei Nicht-Entwurfs-Pushes und PRs | -| `build-artifacts` | `dist/`, Control UI, Prüfungen gebauter Artefakte und wiederverwendbare nachgelagerte Artefakte bauen | Node-relevante Änderungen | -| `checks-fast-core` | Schnelle Linux-Korrektheits-Lanes wie Prüfungen für bundled/plugin-contract/protocol | Node-relevante Änderungen | -| `checks-fast-contracts-channels` | Geshardete Channel-Contract-Prüfungen mit stabilem aggregiertem Check-Ergebnis | Node-relevante Änderungen | -| `checks-node-extensions` | Vollständige Test-Shards für bundled Plugin über die gesamte Extension-Suite | Node-relevante Änderungen | -| `checks-node-core-test` | Core-Node-Test-Shards, ohne Channel-, bundled-, Contract- und Extension-Lanes | Node-relevante Änderungen | -| `extension-fast` | Fokussierte Tests nur für die geänderten bundled Plugin | Pull Requests mit Extension-Änderungen | -| `check` | Geshardetes Äquivalent zum primären lokalen Gate: Prod-Typen, Lint, Guards, Test-Typen und strikter Smoke | Node-relevante Änderungen | -| `check-additional` | Architektur-, Boundary-, Extension-Surface-Guards, Package-Boundary und Gateway-Watch-Shards | Node-relevante Änderungen | -| `build-smoke` | Smoke-Tests für gebaute CLI und Startspeicher-Smoke | Node-relevante Änderungen | -| `checks` | Verifier für Channel-Tests mit gebauten Artefakten plus nur-Push-Node-22-Kompatibilität | Node-relevante Änderungen | -| `check-docs` | Docs-Formatierung, Lint und Broken-Link-Prüfungen | Doku geändert | -| `skills-python` | Ruff + pytest für Python-basierte Skills | Python-Skill-relevante Änderungen | -| `checks-windows` | Windows-spezifische Test-Lanes | Windows-relevante Änderungen | -| `macos-node` | macOS-TypeScript-Test-Lane mit den gemeinsam genutzten gebauten Artefakten | macOS-relevante Änderungen | -| `macos-swift` | Swift-Lint, Build und Tests für die macOS-App | macOS-relevante Änderungen | -| `android` | Android-Unit-Tests für beide Flavors plus ein Debug-APK-Build | Android-relevante Änderungen | +| `preflight` | Erkennt nur-Doku-Änderungen, geänderte Scopes, geänderte Erweiterungen und baut das CI-Manifest | Immer bei Nicht-Entwurf-Pushes und PRs | +| `security-scm-fast` | Erkennung privater Schlüssel und Workflow-Audit über `zizmor` | Immer bei Nicht-Entwurf-Pushes und PRs | +| `security-dependency-audit` | Produktions-Lockfile-Audit ohne Abhängigkeiten gegen npm-Advisories | Immer bei Nicht-Entwurf-Pushes und PRs | +| `security-fast` | Erforderliche Aggregation für die schnellen Sicherheitsjobs | Immer bei Nicht-Entwurf-Pushes und PRs | +| `build-artifacts` | Baut `dist/`, das Control UI, Built-Artifact-Prüfungen und wiederverwendbare nachgelagerte Artefakte | Node-relevante Änderungen | +| `checks-fast-core` | Schnelle Linux-Korrektheits-Lanes wie Prüfungen für gebündelte Plugins/Plugin-Verträge/Protokoll | Node-relevante Änderungen | +| `checks-fast-contracts-channels` | Gesplittete Channel-Vertragsprüfungen mit einem stabilen aggregierten Prüfergebnis | Node-relevante Änderungen | +| `checks-node-extensions` | Vollständige Test-Shards für gebündelte Plugins über die gesamte Erweiterungs-Suite | Node-relevante Änderungen | +| `checks-node-core-test` | Core-Node-Test-Shards, ohne Channel-, gebündelte-, Vertrags- und Erweiterungs-Lanes | Node-relevante Änderungen | +| `extension-fast` | Fokussierte Tests nur für die geänderten gebündelten Plugins | Pull Requests mit Erweiterungsänderungen | +| `check` | Gesplittetes Äquivalent zum wichtigsten lokalen Gate: Prod-Typen, Lint, Guard-Prüfungen, Test-Typen und strenger Smoke-Test | Node-relevante Änderungen | +| `check-additional` | Architektur-, Boundary-, Erweiterungsoberflächen-Guards, Package-Boundary- und Gateway-Watch-Shards | Node-relevante Änderungen | +| `build-smoke` | Smoke-Tests für die gebaute CLI und Startup-Memory-Smoke | Node-relevante Änderungen | +| `checks` | Verifier für Channel-Tests auf Built-Artifacts plus nur bei Pushes Node-22-Kompatibilität | Node-relevante Änderungen | +| `check-docs` | Doku-Formatierung, Lint und Prüfungen auf defekte Links | Doku geändert | +| `skills-python` | Ruff + pytest für Python-gestützte Skills | Python-Skills-relevante Änderungen | +| `checks-windows` | Windows-spezifische Test-Lanes | Windows-relevante Änderungen | +| `macos-node` | macOS-TypeScript-Test-Lane unter Verwendung der gemeinsam genutzten Built-Artifacts | macOS-relevante Änderungen | +| `macos-swift` | Swift-Lint, Build und Tests für die macOS-App | macOS-relevante Änderungen | +| `android` | Android-Unit-Tests für beide Flavors plus ein Debug-APK-Build | Android-relevante Änderungen | -## Reihenfolge für schnelles Fehlschlagen +## Fail-Fast-Reihenfolge -Die Jobs sind so angeordnet, dass günstige Prüfungen fehlschlagen, bevor teure Jobs starten: +Die Jobs sind so angeordnet, dass günstige Prüfungen fehlschlagen, bevor teure Jobs laufen: 1. `preflight` entscheidet, welche Lanes überhaupt existieren. Die Logik `docs-scope` und `changed-scope` sind Schritte innerhalb dieses Jobs, keine eigenständigen Jobs. 2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` und `skills-python` schlagen schnell fehl, ohne auf die schwereren Artefakt- und Plattform-Matrix-Jobs zu warten. -3. `build-artifacts` überlappt mit den schnellen Linux-Lanes, damit nachgelagerte Verbraucher starten können, sobald der gemeinsame Build bereit ist. -4. Danach fächern die schwereren Plattform- und Runtime-Lanes auf: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, das nur-PR-`extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` und `android`. +3. `build-artifacts` überlappt sich mit den schnellen Linux-Lanes, damit nachgelagerte Verbraucher starten können, sobald der gemeinsame Build bereit ist. +4. Danach fächern die schwereren Plattform- und Laufzeit-Lanes auf: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, das nur für PRs laufende `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` und `android`. -Die Scope-Logik befindet sich in `scripts/ci-changed-scope.mjs` und wird durch Unit-Tests in `src/scripts/ci-changed-scope.test.ts` abgedeckt. -Änderungen an CI-Workflows validieren den Node-CI-Graphen sowie das Workflow-Linting, erzwingen aber für sich allein keine nativen Windows-, Android- oder macOS-Builds; diese Plattform-Lanes bleiben auf Änderungen an der jeweiligen Plattformquelle beschränkt. -Windows-Node-Prüfungen sind auf Windows-spezifische Prozess-/Pfad-Wrapper, npm/pnpm/UI-Runner-Helfer, Package-Manager-Konfiguration und die CI-Workflow-Oberflächen begrenzt, die diese Lane ausführen; nicht zusammenhängende Source-, Plugin-, Install-Smoke- und nur-Test-Änderungen bleiben auf den Linux-Node-Lanes, damit sie keinen Windows-Worker mit 16 vCPU für Abdeckung reservieren, die bereits durch die normalen Test-Shards ausgeübt wird. -Der separate Workflow `install-smoke` verwendet dasselbe Scope-Skript über seinen eigenen `preflight`-Job wieder. Er berechnet `run_install_smoke` aus dem engeren Signal `changed-smoke`, sodass Docker-/Install-Smoke bei Installations-, Packaging-, containerrelevanten Änderungen, Production-Änderungen an gebündelten extensions sowie den Core-Surfaces für Plugin/Channel/Gateway/Plugin SDK läuft, die die Docker-Smoke-Jobs abdecken. Nur-Test- und nur-Doku-Änderungen reservieren keine Docker-Worker. Sein QR-Package-Smoke erzwingt, dass die Docker-Schicht `pnpm install` erneut ausgeführt wird, wobei der BuildKit-pnpm-Store-Cache erhalten bleibt, sodass die Installation weiterhin getestet wird, ohne bei jedem Lauf Abhängigkeiten neu herunterzuladen. Sein Gateway-Network-e2e verwendet das früher im Job gebaute Runtime-Image wieder, sodass echte container-zu-container-WebSocket-Abdeckung hinzukommt, ohne einen weiteren Docker-Build hinzuzufügen. Lokal baut `test:docker:all` ein gemeinsames Live-Test-Image und ein gemeinsames Built-App-Image aus `scripts/e2e/Dockerfile` vor und führt dann die Live-/E2E-Smoke-Lanes parallel mit `OPENCLAW_SKIP_DOCKER_BUILD=1` aus; passen Sie die Standard-Parallelität von 4 mit `OPENCLAW_DOCKER_ALL_PARALLELISM` an. Das lokale Aggregat plant standardmäßig nach dem ersten Fehler keine neuen gepoolten Lanes mehr ein, und jede Lane hat ein 120-Minuten-Timeout, das mit `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` überschrieben werden kann. Start- oder Provider-sensitive Lanes laufen exklusiv nach dem parallelen Pool. Der wiederverwendbare Live-/E2E-Workflow spiegelt das Muster mit gemeinsamem Image, indem er vor der Docker-Matrix ein SHA-getaggtes GHCR-Docker-E2E-Image baut und pusht und dann die Matrix mit `OPENCLAW_SKIP_DOCKER_BUILD=1` ausführt. Der geplante Live-/E2E-Workflow führt täglich die vollständige Docker-Suite des Release-Pfads aus. QR- und Installer-Docker-Tests behalten ihre eigenen installationsfokussierten Dockerfiles. Ein separater Job `docker-e2e-fast` führt das begrenzte Docker-Profil für bundled Plugin unter einem Befehls-Timeout von 120 Sekunden aus: Dependency-Reparatur für setup-entry plus synthetische Isolierung von Fehlern im bundled-loader. Die vollständige Matrix für bundled Update/Channel bleibt manuell/Vollsuite, weil sie wiederholte echte npm-update- und doctor-repair-Durchläufe ausführt. +Die Scope-Logik lebt in `scripts/ci-changed-scope.mjs` und ist durch Unit-Tests in `src/scripts/ci-changed-scope.test.ts` abgedeckt. +Änderungen am CI-Workflow validieren den Node-CI-Graphen plus Workflow-Linting, erzwingen aber nicht selbst Windows-, Android- oder macOS-native Builds; diese Plattform-Lanes bleiben auf Änderungen im Plattform-Quellcode beschränkt. +Windows-Node-Prüfungen sind auf Windows-spezifische Prozess-/Pfad-Wrapper, npm/pnpm/UI-Runner-Hilfen, Package-Manager-Konfiguration und die CI-Workflow-Oberflächen beschränkt, die diese Lane ausführen; nicht zusammenhängende Quellcode-, Plugin-, Install-Smoke- und reine Teständerungen bleiben auf den Linux-Node-Lanes, damit sie keinen Windows-Worker mit 16 vCPU für Abdeckung reservieren, die bereits durch die normalen Test-Shards ausgeübt wird. +Der separate Workflow `install-smoke` verwendet dasselbe Scope-Skript über seinen eigenen Job `preflight` erneut. Er berechnet `run_install_smoke` aus dem enger gefassten Signal changed-smoke, sodass Docker/Install-Smoke bei install-, packaging-, container-relevanten Änderungen, Änderungen an der Produktionslogik gebündelter Erweiterungen und an den Core-Oberflächen Plugin/Channel/Gateway/Plugin SDK läuft, die die Docker-Smoke-Jobs ausüben. Reine Test- und reine Doku-Änderungen reservieren keine Docker-Worker. Sein QR-Package-Smoke erzwingt, dass die Docker-Schicht `pnpm install` erneut läuft, wobei der BuildKit-pnpm-Store-Cache erhalten bleibt, sodass die Installation weiter geprüft wird, ohne bei jedem Lauf Abhängigkeiten erneut herunterzuladen. Sein gateway-network-e2e verwendet das früher im Job gebaute Runtime-Image erneut, sodass echte WebSocket-Abdeckung zwischen Containern hinzugefügt wird, ohne einen weiteren Docker-Build hinzuzufügen. Lokal baut `test:docker:all` ein gemeinsames Live-Test-Image und ein gemeinsames Built-App-Image aus `scripts/e2e/Dockerfile` vor und führt dann die Live-/E2E-Smoke-Lanes parallel mit `OPENCLAW_SKIP_DOCKER_BUILD=1` aus; passen Sie die Standard-Parallelität von 4 mit `OPENCLAW_DOCKER_ALL_PARALLELISM` an. Das lokale Aggregat plant standardmäßig nach dem ersten Fehler keine neuen gepoolten Lanes mehr ein, und jede Lane hat ein Timeout von 120 Minuten, überschreibbar mit `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Startup- oder Provider-sensitive Lanes laufen exklusiv nach dem parallelen Pool. Der wiederverwendbare Live-/E2E-Workflow bildet das Muster mit gemeinsamem Image nach, indem er vor der Docker-Matrix ein SHA-getaggtes GHCR-Docker-E2E-Image baut und pusht und dann die Matrix mit `OPENCLAW_SKIP_DOCKER_BUILD=1` ausführt. Der geplante Live-/E2E-Workflow führt täglich die vollständige Docker-Suite des Release-Pfads aus. QR- und Installer-Docker-Tests behalten ihre eigenen install-fokussierten Dockerfiles. Ein separater Job `docker-e2e-fast` führt das begrenzte gebündelte Plugin-Docker-Profil mit einem Befehls-Timeout von 120 Sekunden aus: setup-entry-Abhängigkeitsreparatur plus synthetische Isolierung von Fehlern im gebündelten Loader. Die vollständige Matrix für gebündelte Updates/Channel bleibt manuell/vollständige Suite, weil sie wiederholt echte npm-Update- und doctor-Reparaturdurchläufe ausführt. -Die Logik für lokale Changed-Lanes befindet sich in `scripts/changed-lanes.mjs` und wird von `scripts/check-changed.mjs` ausgeführt. Dieses lokale Gate ist bei Architekturgrenzen strenger als das breite CI-Plattform-Scoping: Änderungen an der Core-Production führen Prod-Typecheck für den Core plus Core-Tests aus, reine Core-Test-Änderungen führen nur Test-Typecheck/Tests für den Core aus, Änderungen an der Extension-Production führen Prod-Typecheck für extensions plus Extension-Tests aus, und reine Extension-Test-Änderungen führen nur Test-Typecheck/Tests für extensions aus. Änderungen am öffentlichen Plugin SDK oder an plugin-contract erweitern die Validierung auf extensions, weil extensions von diesen Core-Contracts abhängen. Reine Versions-Bumps an Release-Metadaten führen gezielte Prüfungen für Version/Konfiguration/Root-Abhängigkeiten aus. Unbekannte Änderungen an Root/Konfiguration schlagen sicherheitshalber auf alle Lanes durch. +Die lokale Logik für Changed-Lanes lebt in `scripts/changed-lanes.mjs` und wird durch `scripts/check-changed.mjs` ausgeführt. Dieses lokale Gate ist bei Architekturgrenzen strenger als das breite CI-Plattform-Scoping: Änderungen an der Core-Produktionslogik führen Core-Prod-Typecheck plus Core-Tests aus, reine Core-Teständerungen führen nur Core-Test-Typecheck/-Tests aus, Änderungen an der Produktionslogik von Erweiterungen führen Erweiterungs-Prod-Typecheck plus Erweiterungstests aus, und reine Erweiterungsteständerungen führen nur Erweiterungstest-Typecheck/-Tests aus. Änderungen an öffentlichem Plugin SDK oder Plugin-Verträgen erweitern die Validierung auf Erweiterungen, weil Erweiterungen von diesen Core-Verträgen abhängen. Reine Versionserhöhungen in Release-Metadaten führen gezielte Prüfungen für Version/Konfiguration/Root-Abhängigkeiten aus. Unbekannte Root-/Konfigurationsänderungen fallen aus Sicherheitsgründen auf alle Lanes zurück. -Bei Pushes fügt die Matrix `checks` die nur-Push-Lane `compat-node22` hinzu. Bei Pull Requests wird diese Lane übersprungen, und die Matrix bleibt auf die normalen Test-/Channel-Lanes fokussiert. +Bei Pushes fügt die Matrix `checks` die nur bei Pushes laufende Lane `compat-node22` hinzu. Bei Pull Requests wird diese Lane übersprungen, und die Matrix bleibt auf die normalen Test-/Channel-Lanes fokussiert. -Die langsamsten Node-Testfamilien sind aufgeteilt oder ausbalanciert, damit jeder Job klein bleibt: Channel-Contracts teilen Registry- und Core-Abdeckung in insgesamt sechs gewichtete Shards auf, Tests für bundled Plugin werden über sechs Extension-Worker ausbalanciert, Auto-Reply läuft als drei ausbalancierte Worker statt sechs winziger Worker, und agentische Gateway-/Plugin-Konfigurationen werden über die bestehenden agentischen Node-Jobs nur für Source verteilt, statt auf gebaute Artefakte zu warten. Breite Browser-, QA-, Medien- und sonstige Plugin-Tests verwenden ihre eigenen dedizierten Vitest-Konfigurationen statt des gemeinsamen Catch-all für Plugin. Die breite Agents-Lane verwendet den gemeinsamen dateiparallelen Vitest-Scheduler, weil sie von Imports/Terminierung dominiert ist statt von einer einzelnen langsamen Testdatei. `runtime-config` läuft mit dem Shard `infra core-runtime`, damit der gemeinsame Runtime-Shard nicht das Tail besitzt. `check-additional` hält Compile-/Canary-Arbeit für Package-Boundary zusammen und trennt Runtime-Topologie-Architektur von Gateway-Watch-Abdeckung; der Boundary-Guard-Shard führt seine kleinen unabhängigen Guards gleichzeitig innerhalb eines Jobs aus. Gateway-Watch, Channel-Tests und der Shard `core support-boundary` laufen gleichzeitig innerhalb von `build-artifacts`, nachdem `dist/` und `dist-runtime/` bereits gebaut wurden. So bleiben ihre alten Check-Namen als leichtgewichtige Verifier-Jobs erhalten, während zwei zusätzliche Blacksmith-Worker und eine zweite Artifact-Consumer-Queue vermieden werden. -Android-CI führt sowohl `testPlayDebugUnitTest` als auch `testThirdPartyDebugUnitTest` aus und baut dann das Play-Debug-APK. Der Third-Party-Flavor hat kein separates Source-Set oder Manifest; seine Unit-Test-Lane kompiliert diesen Flavor dennoch mit den SMS-/Call-Log-BuildConfig-Flags, vermeidet dabei aber einen doppelten Packaging-Job für Debug-APKs bei jedem Android-relevanten Push. -`extension-fast` ist nur für PRs, weil Push-Läufe bereits die vollständigen Test-Shards für bundled Plugin ausführen. Das erhält schnelles Feedback zu geänderten Plugin für Reviews, ohne auf `main` einen zusätzlichen Blacksmith-Worker für Abdeckung zu reservieren, die bereits in `checks-node-extensions` vorhanden ist. +Die langsamsten Node-Testfamilien werden aufgeteilt oder ausbalanciert, damit jeder Job klein bleibt, ohne Runner übermäßig zu reservieren: Channel-Verträge laufen als drei gewichtete Shards, Tests für gebündelte Plugins werden über sechs Erweiterungs-Worker verteilt, kleine Core-Unit-Lanes werden gepaart, Auto-Reply läuft als drei ausbalancierte Worker statt sechs winziger Worker, und agentische Gateway-/Plugin-Konfigurationen werden über die vorhandenen agentischen Node-Quellcode-Jobs verteilt, statt auf Built-Artifacts zu warten. Breite Browser-, QA-, Medien- und sonstige Plugin-Tests verwenden ihre dedizierten Vitest-Konfigurationen statt des gemeinsamen Plugin-Sammel-Setups. Die breite Agents-Lane verwendet den gemeinsamen Dateiparallel-Scheduler von Vitest, weil sie von Importen/Planung dominiert wird statt von einer einzelnen langsamen Testdatei. `runtime-config` läuft mit dem Shard infra core-runtime, damit nicht der gemeinsame Runtime-Shard den Nachlauf besitzt. `check-additional` hält Package-Boundary-Compile-/Canary-Arbeit zusammen und trennt Laufzeittopologie-Architektur von Gateway-Watch-Abdeckung; der Boundary-Guard-Shard führt seine kleinen unabhängigen Guards innerhalb eines Jobs parallel aus. Gateway-Watch, Channel-Tests und der Core-Support-Boundary-Shard laufen innerhalb von `build-artifacts` gleichzeitig, nachdem `dist/` und `dist-runtime/` bereits gebaut wurden; so bleiben ihre alten Prüfnamen als leichtgewichtige Verifier-Jobs erhalten, während zwei zusätzliche Blacksmith-Worker und eine zweite Warteschlange für Artefakt-Verbraucher vermieden werden. +Android-CI führt sowohl `testPlayDebugUnitTest` als auch `testThirdPartyDebugUnitTest` aus und baut dann das Play-Debug-APK. Der Third-Party-Flavor hat kein separates Source-Set und kein eigenes Manifest; seine Unit-Test-Lane kompiliert diesen Flavor dennoch mit den SMS-/Call-Log-BuildConfig-Flags und vermeidet gleichzeitig einen doppelten Packaging-Job für Debug-APK bei jedem Android-relevanten Push. +`extension-fast` ist nur für PRs, weil Push-Läufe bereits die vollständigen Shards für gebündelte Plugins ausführen. Das sorgt für Feedback zu geänderten Plugins in Reviews, ohne auf `main` einen zusätzlichen Blacksmith-Worker für Abdeckung zu reservieren, die bereits in `checks-node-extensions` vorhanden ist. -GitHub kann ersetzte Jobs als `cancelled` markieren, wenn ein neuerer Push auf derselben PR oder derselben `main`-Ref landet. Behandeln Sie das als CI-Rauschen, es sei denn, der neueste Lauf für dieselbe Ref schlägt ebenfalls fehl. Aggregierte Shard-Checks verwenden `!cancelled() && always()`, damit sie normale Shard-Fehler weiterhin melden, aber nicht in die Queue kommen, nachdem der gesamte Workflow bereits ersetzt wurde. -Der CI-Concurrency-Key ist versioniert (`CI-v7-*`), damit ein zombiehafter GitHub-Eintrag in einer alten Queue-Gruppe neuere Main-Läufe nicht auf unbestimmte Zeit blockieren kann. +GitHub kann ersetzte Jobs als `cancelled` markieren, wenn ein neuerer Push auf derselben PR oder demselben `main`-Ref landet. Behandeln Sie das als CI-Rauschen, außer wenn der neueste Lauf für denselben Ref ebenfalls fehlschlägt. Aggregierte Shard-Prüfungen verwenden `!cancelled() && always()`, sodass sie weiterhin normale Shard-Fehler melden, aber nicht in die Queue gestellt werden, nachdem der gesamte Workflow bereits ersetzt wurde. +Der CI-Concurrency-Key ist versioniert (`CI-v7-*`), sodass ein GitHub-seitiger Zombie in einer alten Queue-Gruppe neuere Main-Läufe nicht auf unbestimmte Zeit blockieren kann. ## Runner -| Runner | Jobs | -| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`, schnelle Security-Jobs und Aggregate (`security-scm-fast`, `security-dependency-audit`, `security-fast`), schnelle Prüfungen für protocol/contract/bundled, geshardete Channel-Contract-Prüfungen, `check`-Shards außer Lint, `check-additional`-Shards und -Aggregate, Verifier-Aggregate für Node-Tests, Docs-Prüfungen, Python-Skills, workflow-sanity, labeler, auto-response; der Preflight von install-smoke verwendet ebenfalls GitHub-gehostetes Ubuntu, damit die Blacksmith-Matrix früher in die Queue gehen kann | -| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, Linux-Node-Test-Shards, Test-Shards für bundled Plugin, `android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, das weiterhin so CPU-sensitiv ist, dass 8 vCPU teurer waren, als sie eingespart haben; install-smoke-Docker-Builds, bei denen die Queue-Zeit für 32 vCPU teurer war, als sie eingespart hat | -| `blacksmith-16vcpu-windows-2025` | `checks-windows` | -| `blacksmith-6vcpu-macos-latest` | `macos-node` auf `openclaw/openclaw`; Forks fallen auf `macos-latest` zurück | -| `blacksmith-12vcpu-macos-latest` | `macos-swift` auf `openclaw/openclaw`; Forks fallen auf `macos-latest` zurück | +| Runner | Jobs | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ubuntu-24.04` | `preflight`, schnelle Sicherheitsjobs und Aggregate (`security-scm-fast`, `security-dependency-audit`, `security-fast`), schnelle Prüfungen für Protokoll/Verträge/gebündelte Plugins, gesplittete Channel-Vertragsprüfungen, `check`-Shards außer Lint, `check-additional`-Shards und -Aggregate, Aggregate-Verifier für Node-Tests, Doku-Prüfungen, Python-Skills, workflow-sanity, labeler, auto-response; preflight für install-smoke verwendet ebenfalls GitHub-gehostetes Ubuntu, sodass die Blacksmith-Matrix früher in die Queue gestellt werden kann | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, Linux-Node-Test-Shards, Test-Shards für gebündelte Plugins, `android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, das CPU-sensitiv genug bleibt, dass 8 vCPU mehr Kosten verursachten, als sie einsparten; install-smoke-Docker-Builds, bei denen die Queue-Zeit für 32 vCPU mehr kostete, als sie einsparten | +| `blacksmith-16vcpu-windows-2025` | `checks-windows` | +| `blacksmith-6vcpu-macos-latest` | `macos-node` auf `openclaw/openclaw`; Forks fallen auf `macos-latest` zurück | +| `blacksmith-12vcpu-macos-latest` | `macos-swift` auf `openclaw/openclaw`; Forks fallen auf `macos-latest` zurück | ## Lokale Äquivalente ```bash -pnpm changed:lanes # den lokalen Changed-Lane-Klassifizierer für origin/main...HEAD prüfen -pnpm check:changed # intelligentes lokales Gate: geänderter Typecheck/Lint/Tests nach Boundary-Lane -pnpm check # schnelles lokales Gate: Produktions-tsgo + geshardetes Lint + parallele schnelle Guards +pnpm changed:lanes # lokalen Changed-Lane-Klassifizierer für origin/main...HEAD prüfen +pnpm check:changed # intelligentes lokales Gate: geänderte Typechecks/Lint/Tests nach Boundary-Lane +pnpm check # schnelles lokales Gate: Produktions-tsgo + gesplittetes Lint + parallele schnelle Guards pnpm check:test-types -pnpm check:timed # dasselbe Gate mit Timing pro Phase +pnpm check:timed # dasselbe Gate mit Timings pro Phase pnpm build:strict-smoke pnpm check:architecture pnpm test:gateway:watch-regression pnpm test # Vitest-Tests pnpm test:channels pnpm test:contracts:channels -pnpm check:docs # Docs-Formatierung + Lint + Broken-Links -pnpm build # dist bauen, wenn CI-Artefakt-/build-smoke-Lanes relevant sind -node scripts/ci-run-timings.mjs # Wall Time, Queue-Zeit und langsamste Jobs zusammenfassen +pnpm check:docs # Doku-Formatierung + Lint + defekte Links +pnpm build # `dist` bauen, wenn CI-Artefakt-/build-smoke-Lanes relevant sind +node scripts/ci-run-timings.mjs # Laufzeit, Queue-Zeit und langsamste Jobs zusammenfassen +node scripts/ci-run-timings.mjs --recent 10 # aktuelle erfolgreiche main-CI-Läufe vergleichen ``` diff --git a/docs/de/gateway/authentication.md b/docs/de/gateway/authentication.md index 2366a79ba..53a8ecc66 100644 --- a/docs/de/gateway/authentication.md +++ b/docs/de/gateway/authentication.md @@ -1,37 +1,41 @@ --- read_when: - - Debugging von Modellauthentifizierung oder ablaufendem OAuth - - Dokumentation von Authentifizierung oder Speicherung von Anmeldedaten + - Debugging der Modellauthentifizierung oder des OAuth-Ablaufs + - Dokumentation der Authentifizierung oder der Speicherung von Anmeldedaten summary: 'Modellauthentifizierung: OAuth, API-Schlüssel, Wiederverwendung der Claude CLI und Anthropic-Setup-Token' title: Authentifizierung x-i18n: - generated_at: "2026-04-07T06:14:27Z" + generated_at: "2026-04-23T14:55:29Z" model: gpt-5.4 provider: openai - source_hash: 9db0ad9eccd7e3e3ca328adaad260bc4288a8ccdbe2dc0c24d9fd049b7ab9231 + source_hash: 37a7c20872b915d1d079f0578c933e43cbdb97eca1c60d8c4e6e5137ca83f8b2 source_path: gateway/authentication.md workflow: 15 --- -# Authentifizierung (Modell-Provider) +# Authentifizierung (Modellanbieter) -Diese Seite behandelt die **Authentifizierung von Modell-Providern** (API-Schlüssel, OAuth, Wiederverwendung der Claude CLI und Anthropic-Setup-Token). Informationen zur **Authentifizierung von Gateway-Verbindungen** (Token, Passwort, Trusted Proxy) finden Sie unter [Configuration](/de/gateway/configuration) und [Trusted Proxy Auth](/de/gateway/trusted-proxy-auth). +Diese Seite behandelt die Authentifizierung von **Modellanbietern** (API-Schlüssel, OAuth, Wiederverwendung der Claude CLI und Anthropic-Setup-Token). Informationen zur Authentifizierung der **Gateway-Verbindung** (Token, Passwort, trusted-proxy) finden Sie unter [Configuration](/de/gateway/configuration) und [Trusted Proxy Auth](/de/gateway/trusted-proxy-auth). -OpenClaw unterstützt OAuth und API-Schlüssel für Modell-Provider. Für dauerhaft laufende Gateway-Hosts sind API-Schlüssel normalerweise die am besten vorhersehbare Option. Abonnement-/OAuth-Abläufe werden ebenfalls unterstützt, wenn sie zu Ihrem Provider-Kontomodell passen. +OpenClaw unterstützt OAuth und API-Schlüssel für Modellanbieter. Für dauerhaft +laufende Gateway-Hosts sind API-Schlüssel in der Regel die vorhersehbarste +Option. Abonnement-/OAuth-Abläufe werden ebenfalls unterstützt, wenn sie zu +Ihrem Anbieterkonto-Modell passen. Unter [/concepts/oauth](/de/concepts/oauth) finden Sie den vollständigen OAuth-Ablauf und das Speicherlayout. -Für SecretRef-basierte Authentifizierung (`env`/`file`/`exec`-Provider) siehe [Secrets Management](/de/gateway/secrets). -Zu Regeln für die Eignung von Anmeldedaten und Reason-Codes, die von `models status --probe` verwendet werden, siehe -[Auth Credential Semantics](/de/auth-credential-semantics). +Für SecretRef-basierte Authentifizierung (Anbieter `env`/`file`/`exec`) siehe [Secrets Management](/de/gateway/secrets). +Für Regeln zur Berechtigung von Anmeldedaten bzw. Reason-Codes, die von `models status --probe` verwendet werden, siehe +[Semantik von Auth-Anmeldedaten](/de/auth-credential-semantics). -## Empfohlene Einrichtung (API-Schlüssel, beliebiger Provider) +## Empfohlene Einrichtung (API-Schlüssel, beliebiger Anbieter) -Wenn Sie ein langlebiges Gateway betreiben, beginnen Sie mit einem API-Schlüssel für Ihren gewählten Provider. -Speziell für Anthropic ist die Authentifizierung per API-Schlüssel weiterhin die am besten vorhersehbare Server-Einrichtung, aber OpenClaw unterstützt auch die Wiederverwendung einer lokalen Claude CLI-Anmeldung. +Wenn Sie ein langlebiges Gateway betreiben, beginnen Sie mit einem API-Schlüssel für Ihren gewählten +Anbieter. +Speziell für Anthropic ist die Authentifizierung per API-Schlüssel weiterhin die vorhersehbarste Servereinrichtung, aber OpenClaw unterstützt auch die Wiederverwendung einer lokalen Claude CLI-Anmeldung. -1. Erstellen Sie in der Konsole Ihres Providers einen API-Schlüssel. +1. Erstellen Sie in der Konsole Ihres Anbieters einen API-Schlüssel. 2. Legen Sie ihn auf dem **Gateway-Host** ab (dem Rechner, auf dem `openclaw gateway` läuft). ```bash @@ -39,7 +43,8 @@ export _API_KEY="..." openclaw models status ``` -3. Wenn das Gateway unter systemd/launchd läuft, legen Sie den Schlüssel vorzugsweise in `~/.openclaw/.env` ab, damit der Daemon ihn lesen kann: +3. Wenn das Gateway unter systemd/launchd läuft, legen Sie den Schlüssel + vorzugsweise in `~/.openclaw/.env` ab, damit der Daemon ihn lesen kann: ```bash cat >> ~/.openclaw/.env <<'EOF' @@ -57,16 +62,40 @@ openclaw doctor Wenn Sie Umgebungsvariablen nicht selbst verwalten möchten, kann das Onboarding API-Schlüssel für die Nutzung durch den Daemon speichern: `openclaw onboard`. -Siehe [Help](/de/help) für Details zur Vererbung von Umgebungsvariablen (`env.shellEnv`, -`~/.openclaw/.env`, systemd/launchd). +Einzelheiten zur Vererbung von Umgebungsvariablen (`env.shellEnv`, +`~/.openclaw/.env`, systemd/launchd) finden Sie unter [Help](/de/help). ## Anthropic: Claude CLI und Token-Kompatibilität -Die Authentifizierung per Anthropic-Setup-Token ist in OpenClaw weiterhin als unterstützter Token-Pfad verfügbar. Mitarbeitende von Anthropic haben uns inzwischen mitgeteilt, dass die Nutzung der Claude CLI im Stil von OpenClaw wieder erlaubt ist. Deshalb behandelt OpenClaw die Wiederverwendung der Claude CLI und die Nutzung von `claude -p` für diese Integration als zulässig, sofern Anthropic keine neue Richtlinie veröffentlicht. Wenn die Wiederverwendung der Claude CLI auf dem Host verfügbar ist, ist dies jetzt der bevorzugte Pfad. +Die Authentifizierung per Anthropic-Setup-Token ist in OpenClaw weiterhin als unterstützter +Token-Pfad verfügbar. Anthropic-Mitarbeitende haben uns inzwischen mitgeteilt, dass die Nutzung der Claude CLI im OpenClaw-Stil +wieder erlaubt ist. Daher behandelt OpenClaw die Wiederverwendung der Claude CLI und die Verwendung von `claude -p` +für diese Integration als zulässig, sofern Anthropic keine neue Richtlinie veröffentlicht. Wenn die +Wiederverwendung der Claude CLI auf dem Host verfügbar ist, ist dies jetzt der bevorzugte Pfad. -Für langlebige Gateway-Hosts bleibt ein Anthropic-API-Schlüssel dennoch die am besten vorhersehbare Einrichtung. Wenn Sie eine vorhandene Claude-Anmeldung auf demselben Host wiederverwenden möchten, nutzen Sie beim Onboarding/Konfigurieren den Anthropic-Claude-CLI-Pfad. +Für langlebige Gateway-Hosts ist ein Anthropic-API-Schlüssel weiterhin die am besten vorhersagbare +Einrichtung. Wenn Sie eine bestehende Claude-Anmeldung auf demselben Host wiederverwenden möchten, nutzen Sie den +Anthropic-Claude-CLI-Pfad in Onboarding/Konfiguration. -Manuelle Tokeneingabe (beliebiger Provider; schreibt `auth-profiles.json` + aktualisiert die Konfiguration): +Empfohlene Host-Einrichtung für die Wiederverwendung der Claude CLI: + +```bash +# Auf dem Gateway-Host ausführen +claude auth login +claude auth status --text +openclaw models auth login --provider anthropic --method cli --set-default +``` + +Dies ist eine Einrichtung in zwei Schritten: + +1. Melden Sie Claude Code selbst auf dem Gateway-Host bei Anthropic an. +2. Weisen Sie OpenClaw an, die Anthropic-Modellauswahl auf das lokale Backend `claude-cli` + umzustellen und das passende OpenClaw-Authentifizierungsprofil zu speichern. + +Wenn `claude` nicht im `PATH` liegt, installieren Sie entweder zuerst Claude Code oder setzen Sie +`agents.defaults.cliBackends.claude-cli.command` auf den tatsächlichen Pfad zur Binärdatei. + +Manuelle Token-Eingabe (beliebiger Anbieter; schreibt `auth-profiles.json` und aktualisiert die Konfiguration): ```bash openclaw models auth paste-token --provider openrouter @@ -76,9 +105,9 @@ Verweise auf Auth-Profile werden auch für statische Anmeldedaten unterstützt: - Anmeldedaten vom Typ `api_key` können `keyRef: { source, provider, id }` verwenden - Anmeldedaten vom Typ `token` können `tokenRef: { source, provider, id }` verwenden -- Profile im OAuth-Modus unterstützen keine SecretRef-Anmeldedaten; wenn `auth.profiles..mode` auf `"oauth"` gesetzt ist, wird SecretRef-gestützte `keyRef`-/`tokenRef`-Eingabe für dieses Profil abgelehnt. +- Profile im OAuth-Modus unterstützen keine SecretRef-Anmeldedaten; wenn `auth.profiles..mode` auf `"oauth"` gesetzt ist, wird eine durch SecretRef gestützte Eingabe über `keyRef`/`tokenRef` für dieses Profil abgelehnt. -Automatisierungsfreundliche Prüfung (Exit `1` bei abgelaufen/fehlend, `2` bei bald ablaufend): +Automatisierungsfreundliche Prüfung (Exit-Code `1`, wenn abgelaufen/fehlend, `2`, wenn bald ablaufend): ```bash openclaw models status --check @@ -92,21 +121,26 @@ openclaw models status --probe Hinweise: -- Probe-Zeilen können aus Auth-Profilen, Umgebungs-Anmeldedaten oder `models.json` stammen. -- Wenn ein explizites `auth.order.` ein gespeichertes Profil auslässt, meldet die Probe für dieses Profil `excluded_by_auth_order`, statt es zu verwenden. -- Wenn Authentifizierung vorhanden ist, OpenClaw aber kein sondierbares Modellkandidat für diesen Provider auflösen kann, meldet die Probe `status: no_model`. -- Abkühlzeiten bei Rate Limits können modellspezifisch sein. Ein Profil, das für ein Modell abkühlt, kann für ein verwandtes Modell desselben Providers weiterhin nutzbar sein. +- Probe-Zeilen können aus Auth-Profilen, Anmeldedaten aus der Umgebung oder `models.json` stammen. +- Wenn ein explizites `auth.order.` ein gespeichertes Profil auslässt, meldet die Probe + für dieses Profil `excluded_by_auth_order`, anstatt es zu versuchen. +- Wenn Authentifizierung vorhanden ist, OpenClaw aber kein sondierbares Modell als Kandidat für + diesen Anbieter auflösen kann, meldet die Probe `status: no_model`. +- Cooldowns für Rate-Limits können modellspezifisch sein. Ein Profil, das für ein + Modell im Cooldown ist, kann für ein verwandtes Modell desselben Anbieters weiterhin nutzbar sein. Optionale Betriebsskripte (systemd/Termux) sind hier dokumentiert: -[Auth monitoring scripts](/de/help/scripts#auth-monitoring-scripts) +[Skripte zur Auth-Überwachung](/de/help/scripts#auth-monitoring-scripts) -## Anthropic-Hinweis +## Hinweis zu Anthropic -Das Anthropic-Backend `claude-cli` wird wieder unterstützt. +Das Backend `claude-cli` von Anthropic wird wieder unterstützt. -- Mitarbeitende von Anthropic haben uns mitgeteilt, dass dieser OpenClaw-Integrationspfad wieder erlaubt ist. -- OpenClaw behandelt daher die Wiederverwendung der Claude CLI und die Nutzung von `claude -p` für Anthropic-gestützte Läufe als zulässig, sofern Anthropic keine neue Richtlinie veröffentlicht. -- Anthropic-API-Schlüssel bleiben die am besten vorhersehbare Wahl für langlebige Gateway-Hosts und eine explizite serverseitige Kontrolle der Abrechnung. +- Anthropic-Mitarbeitende haben uns mitgeteilt, dass dieser OpenClaw-Integrationspfad wieder erlaubt ist. +- OpenClaw behandelt daher die Wiederverwendung der Claude CLI und die Verwendung von `claude -p` + für von Anthropic unterstützte Ausführungen als zulässig, sofern Anthropic keine neue Richtlinie veröffentlicht. +- Anthropic-API-Schlüssel bleiben die am besten vorhersagbare Wahl für langlebige Gateway-Hosts + und eine explizite serverseitige Kontrolle der Abrechnung. ## Status der Modellauthentifizierung prüfen @@ -117,32 +151,34 @@ openclaw doctor ## Verhalten bei der Rotation von API-Schlüsseln (Gateway) -Einige Provider unterstützen, eine Anfrage mit alternativen Schlüsseln erneut zu versuchen, wenn ein API-Aufruf an ein Rate Limit des Providers stößt. +Einige Anbieter unterstützen das erneute Versuchen einer Anfrage mit alternativen Schlüsseln, wenn ein API-Aufruf +an ein Rate-Limit des Anbieters stößt. - Prioritätsreihenfolge: - `OPENCLAW_LIVE__KEY` (einzelne Überschreibung) - `_API_KEYS` - `_API_KEY` - `_API_KEY_*` -- Google-Provider schließen zusätzlich `GOOGLE_API_KEY` als weiteren Fallback ein. +- Google-Anbieter enthalten außerdem `GOOGLE_API_KEY` als zusätzlichen Fallback. - Dieselbe Schlüsselliste wird vor der Verwendung dedupliziert. -- OpenClaw versucht es mit dem nächsten Schlüssel nur bei Rate-Limit-Fehlern erneut (zum Beispiel `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent +- OpenClaw versucht den nächsten Schlüssel nur bei Rate-Limit-Fehlern erneut (zum Beispiel + `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached` oder `workers_ai ... quota limit exceeded`). -- Andere Fehler als Rate-Limit-Fehler werden nicht mit alternativen Schlüsseln erneut versucht. +- Fehler, die keine Rate-Limit-Fehler sind, werden nicht mit alternativen Schlüsseln erneut versucht. - Wenn alle Schlüssel fehlschlagen, wird der endgültige Fehler des letzten Versuchs zurückgegeben. ## Steuern, welche Anmeldedaten verwendet werden ### Pro Sitzung (Chat-Befehl) -Verwenden Sie `/model @`, um bestimmte Provider-Anmeldedaten für die aktuelle Sitzung festzulegen (Beispiel-Profile-IDs: `anthropic:default`, `anthropic:work`). +Verwenden Sie `/model @`, um bestimmte Anmeldedaten eines Anbieters für die aktuelle Sitzung festzulegen (Beispiel für Profil-IDs: `anthropic:default`, `anthropic:work`). -Verwenden Sie `/model` (oder `/model list`) für eine kompakte Auswahl; verwenden Sie `/model status` für die vollständige Ansicht (Kandidaten + nächstes Auth-Profil sowie Details zu Provider-Endpunkten, falls konfiguriert). +Verwenden Sie `/model` (oder `/model list`) für eine kompakte Auswahl; verwenden Sie `/model status` für die vollständige Ansicht (Kandidaten + nächstes Auth-Profil sowie Details zum Anbieter-Endpunkt, wenn konfiguriert). ### Pro Agent (CLI-Überschreibung) -Legen Sie eine explizite Überschreibung der Reihenfolge von Auth-Profilen für einen Agenten fest (gespeichert in dessen `auth-state.json`): +Legen Sie eine explizite Überschreibung der Reihenfolge von Auth-Profilen für einen Agenten fest (gespeichert in der `auth-state.json` dieses Agenten): ```bash openclaw models auth order get --provider anthropic @@ -151,14 +187,17 @@ openclaw models auth order clear --provider anthropic ``` Verwenden Sie `--agent `, um einen bestimmten Agenten anzusprechen; lassen Sie es weg, um den konfigurierten Standard-Agenten zu verwenden. -Wenn Sie Probleme mit der Reihenfolge debuggen, zeigt `openclaw models status --probe` ausgelassene gespeicherte Profile als `excluded_by_auth_order` an, statt sie stillschweigend zu überspringen. -Wenn Sie Probleme mit Abkühlzeiten debuggen, beachten Sie, dass Abkühlzeiten bei Rate Limits an eine einzelne Modell-ID statt an das gesamte Provider-Profil gebunden sein können. +Beim Debuggen von Problemen mit der Reihenfolge zeigt `openclaw models status --probe` ausgelassene +gespeicherte Profile als `excluded_by_auth_order` an, anstatt sie stillschweigend zu überspringen. +Beim Debuggen von Cooldown-Problemen sollten Sie beachten, dass Cooldowns für Rate-Limits +an eine einzelne Modell-ID statt an das gesamte Anbieterprofil gebunden sein können. ## Fehlerbehebung -### "No credentials found" +### „Keine Anmeldedaten gefunden“ -Wenn das Anthropic-Profil fehlt, konfigurieren Sie auf dem **Gateway-Host** einen Anthropic-API-Schlüssel oder richten Sie den Anthropic-Setup-Token-Pfad ein und prüfen Sie dann erneut: +Wenn das Anthropic-Profil fehlt, konfigurieren Sie einen Anthropic-API-Schlüssel auf dem +**Gateway-Host** oder richten Sie den Anthropic-Setup-Token-Pfad ein und prüfen Sie dann erneut: ```bash openclaw models status @@ -166,4 +205,6 @@ openclaw models status ### Token läuft bald ab/ist abgelaufen -Führen Sie `openclaw models status` aus, um zu bestätigen, welches Profil bald abläuft. Wenn ein Anthropic-Token-Profil fehlt oder abgelaufen ist, erneuern Sie diese Einrichtung über setup-token oder migrieren Sie zu einem Anthropic-API-Schlüssel. +Führen Sie `openclaw models status` aus, um zu bestätigen, welches Profil bald abläuft. Wenn ein +Anthropic-Token-Profil fehlt oder abgelaufen ist, aktualisieren Sie diese Einrichtung über +setup-token oder migrieren Sie zu einem Anthropic-API-Schlüssel. diff --git a/docs/de/gateway/cli-backends.md b/docs/de/gateway/cli-backends.md index 8d056308a..2b3d3249c 100644 --- a/docs/de/gateway/cli-backends.md +++ b/docs/de/gateway/cli-backends.md @@ -1,47 +1,47 @@ --- read_when: - - Sie möchten einen zuverlässigen Fallback, wenn API-Provider ausfallen - - Sie verwenden Codex CLI oder andere lokale AI CLIs und möchten sie wiederverwenden + - Sie möchten einen zuverlässigen Fallback, wenn API-Anbieter ausfallen + - Sie führen die Codex CLI oder andere lokale AI-CLIs aus und möchten sie wiederverwenden - Sie möchten die MCP-Loopback-Bridge für den Tool-Zugriff des CLI-Backends verstehen summary: 'CLI-Backends: lokaler AI-CLI-Fallback mit optionaler MCP-Tool-Bridge' title: CLI-Backends x-i18n: - generated_at: "2026-04-23T14:01:27Z" + generated_at: "2026-04-23T14:55:30Z" model: gpt-5.4 provider: openai - source_hash: 475923b36e4580d3e4e57014ff2e6b89e9eb52c11b0a0ab1fc8241655b07836e + source_hash: ff7458d18b8a5b716930579241177917fd3edffcf7f6e211c7d570cf76519316 source_path: gateway/cli-backends.md workflow: 15 --- # CLI-Backends (Fallback-Laufzeit) -OpenClaw kann **lokale AI CLIs** als **reinen Text-Fallback** ausführen, wenn API-Provider ausfallen, -rate-limitiert sind oder sich vorübergehend fehlerhaft verhalten. Das ist absichtlich konservativ: +OpenClaw kann **lokale AI-CLIs** als **reinen Text-Fallback** ausführen, wenn API-Anbieter ausgefallen sind, +rate-limitiert werden oder sich vorübergehend fehlerhaft verhalten. Das ist bewusst konservativ: - **OpenClaw-Tools werden nicht direkt injiziert**, aber Backends mit `bundleMcp: true` können Gateway-Tools über eine Loopback-MCP-Bridge erhalten. - **JSONL-Streaming** für CLIs, die es unterstützen. -- **Sitzungen werden unterstützt** (damit Folgezüge kohärent bleiben). +- **Sitzungen werden unterstützt** (damit Folge-Turns konsistent bleiben). - **Bilder können durchgereicht werden**, wenn die CLI Bildpfade akzeptiert. -Das ist als **Sicherheitsnetz** und nicht als primärer Pfad gedacht. Verwenden Sie es, wenn Sie +Das ist als **Sicherheitsnetz** statt als primärer Pfad gedacht. Verwenden Sie es, wenn Sie „funktioniert immer“-Textantworten möchten, ohne sich auf externe APIs zu verlassen. -Wenn Sie eine vollständige Harness-Laufzeit mit ACP-Sitzungssteuerung, Hintergrundaufgaben, -Thread-/Konversationsbindung und persistenten externen Coding-Sitzungen möchten, verwenden Sie -stattdessen [ACP Agents](/de/tools/acp-agents). CLI-Backends sind kein ACP. +Wenn Sie eine vollständige Harness-Laufzeit mit ACP-Sitzungssteuerungen, Hintergrundaufgaben, +Thread-/Unterhaltungsbindung und persistenten externen Coding-Sitzungen möchten, verwenden Sie +stattdessen [ACP Agents](/de/tools/acp-agents). CLI-Backends sind nicht ACP. ## Einsteigerfreundlicher Schnellstart -Sie können Codex CLI **ohne Konfiguration** verwenden (das gebündelte OpenAI Plugin +Sie können die Codex CLI **ohne Konfiguration** verwenden (das gebündelte OpenAI-Plugin registriert ein Standard-Backend): ```bash openclaw agent --message "hi" --model codex-cli/gpt-5.4 ``` -Wenn Ihr Gateway unter launchd/systemd läuft und `PATH` minimal ist, fügen Sie nur den +Wenn Ihr Gateway unter launchd/systemd läuft und PATH minimal ist, fügen Sie nur den Befehlspfad hinzu: ```json5 @@ -60,14 +60,14 @@ Befehlspfad hinzu: Das ist alles. Keine Schlüssel, keine zusätzliche Auth-Konfiguration außer der CLI selbst erforderlich. -Wenn Sie ein gebündeltes CLI-Backend als **primären Nachrichten-Provider** auf einem -Gateway-Host verwenden, lädt OpenClaw jetzt automatisch das besitzende gebündelte Plugin, wenn Ihre Konfiguration -dieses Backend explizit in einer Modellreferenz oder unter +Wenn Sie ein gebündeltes CLI-Backend als **primären Nachrichtenanbieter** auf einem +Gateway-Host verwenden, lädt OpenClaw jetzt automatisch das zugehörige gebündelte Plugin, wenn Ihre Konfiguration +dieses Backend explizit in einer Modell-Referenz oder unter `agents.defaults.cliBackends` referenziert. ## Verwendung als Fallback -Fügen Sie Ihrer Fallback-Liste ein CLI-Backend hinzu, damit es nur ausgeführt wird, wenn primäre Modelle fehlschlagen: +Fügen Sie ein CLI-Backend zu Ihrer Fallback-Liste hinzu, damit es nur ausgeführt wird, wenn primäre Modelle fehlschlagen: ```json5 { @@ -88,11 +88,11 @@ Fügen Sie Ihrer Fallback-Liste ein CLI-Backend hinzu, damit es nur ausgeführt Hinweise: -- Wenn Sie `agents.defaults.models` (Zulassungsliste) 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 Sie `agents.defaults.models` (Allowlist) verwenden, müssen Sie dort auch Ihre CLI-Backend-Modelle einschließen. +- Wenn der primäre Anbieter fehlschlägt (Auth, Rate-Limits, Timeouts), versucht OpenClaw als Nächstes das CLI-Backend. -## Konfigurationsübersicht +## Konfigurationsüberblick Alle CLI-Backends befinden sich unter: @@ -100,8 +100,8 @@ Alle CLI-Backends befinden sich unter: agents.defaults.cliBackends ``` -Jeder Eintrag ist mit einer **Provider-ID** verschlüsselt (z. B. `codex-cli`, `my-cli`). -Die Provider-ID wird zur linken Seite Ihrer Modellreferenz: +Jeder Eintrag wird über eine **Anbieter-ID** verschlüsselt (z. B. `codex-cli`, `my-cli`). +Die Anbieter-ID wird zur linken Seite Ihrer Modell-Referenz: ``` / @@ -147,69 +147,79 @@ Die Provider-ID wird zur linken Seite Ihrer Modellreferenz: ## Funktionsweise -1. **Wählt ein Backend aus** auf Basis des Provider-Präfixes (`codex-cli/...`). -2. **Erstellt einen System-Prompt** unter Verwendung desselben OpenClaw-Prompts und Workspace-Kontexts. -3. **Führt die CLI** mit einer Sitzungs-ID aus (falls unterstützt), damit der Verlauf konsistent bleibt. - Das gebündelte Backend `claude-cli` hält einen Claude-stdio-Prozess pro - OpenClaw-Sitzung am Leben und sendet Folgezüge über stream-json stdin. +1. **Wählt ein Backend aus** basierend auf dem Anbieterpräfix (`codex-cli/...`). +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 einen Claude-stdio-Prozess pro + OpenClaw-Sitzung am Leben und sendet Folge-Turns über stream-json-stdin. 4. **Parst die Ausgabe** (JSON oder Klartext) und gibt den endgültigen Text zurück. -5. **Persistiert Sitzungs-IDs** pro Backend, damit Folgezüge dieselbe CLI-Sitzung wiederverwenden. +5. **Persistiert Sitzungs-IDs** pro Backend, damit Folge-Turns dieselbe CLI-Sitzung wiederverwenden. -Das gebündelte Anthropic-Backend `claude-cli` wird wieder unterstützt. Anthropic-Mitarbeiter -haben uns gesagt, dass die Claude-CLI-Nutzung im Stil von OpenClaw wieder erlaubt ist, daher behandelt OpenClaw -die Nutzung von `claude -p` für diese Integration als zulässig, sofern Anthropic +Das gebündelte Anthropic-`claude-cli`-Backend wird wieder unterstützt. Anthropic-Mitarbeiter +haben uns gesagt, dass die Verwendung der Claude CLI im OpenClaw-Stil wieder erlaubt ist, daher behandelt OpenClaw +die Nutzung von `claude -p` für diese Integration als genehmigt, sofern Anthropic keine neue Richtlinie veröffentlicht. -Das gebündelte OpenAI-Backend `codex-cli` leitet OpenClaws System-Prompt über -Codex' Konfigurationsüberschreibung `model_instructions_file` weiter (`-c -model_instructions_file="..."`). Codex stellt kein Flag im Claude-Stil -`--append-system-prompt` bereit, daher schreibt OpenClaw den zusammengesetzten Prompt für jede neue Codex-CLI-Sitzung in eine +Das gebündelte OpenAI-`codex-cli`-Backend reicht den System-Prompt von OpenClaw über +die Konfigurationsüberschreibung `model_instructions_file` von Codex weiter (`-c +model_instructions_file="..."`). Codex bietet kein Claude-ähnliches +Flag `--append-system-prompt`, 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 +Das gebündelte Anthropic-`claude-cli`-Backend erhält den OpenClaw-Skills-Snapshot 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 für diesen Agenten/diese Sitzung zulässigen Skills, sodass Claudes nativer Skill- -Resolver dieselbe gefilterte Menge sieht, die OpenClaw sonst im Prompt bewerben würde. -Env-/API-Schlüssel-Überschreibungen für Skills werden von OpenClaw weiterhin auf die -Kindprozessumgebung für den Lauf angewendet. +ein temporäres Claude Code Plugin, das mit `--plugin-dir` übergeben wird. Das +Plugin enthält nur die geeigneten Skills für diesen Agenten bzw. diese Sitzung, sodass +der native Skill-Resolver von Claude Code dieselbe gefilterte Menge sieht, die OpenClaw sonst im +Prompt bekannt geben würde. Überschreibungen von Skill-Umgebungsvariablen/API-Schlüsseln werden weiterhin von OpenClaw auf die +Umgebung des untergeordneten Prozesses für den Lauf angewendet. + +Bevor OpenClaw das gebündelte `claude-cli`-Backend verwenden kann, muss Claude Code selbst +bereits auf demselben Host angemeldet sein: + +```bash +claude auth login +claude auth status --text +openclaw models auth login --provider anthropic --method cli --set-default +``` + +Verwenden Sie `agents.defaults.cliBackends.claude-cli.command` nur, wenn die Binärdatei `claude` +nicht bereits auf `PATH` liegt. ## Sitzungen - Wenn die CLI Sitzungen unterstützt, setzen Sie `sessionArg` (z. B. `--session-id`) oder - `sessionArgs` (Platzhalter `{sessionId}`), wenn die ID in mehrere Flags eingefügt werden - muss. + `sessionArgs` (Platzhalter `{sessionId}`), wenn die ID in mehrere Flags eingefügt werden muss. - Wenn die CLI einen **Resume-Unterbefehl** mit anderen Flags verwendet, setzen Sie `resumeArgs` (ersetzt `args` beim Fortsetzen) und optional `resumeOutput` - (für Nicht-JSON-Fortsetzungen). + (für nicht-JSON-Resumes). - `sessionMode`: - `always`: immer eine Sitzungs-ID senden (neue UUID, wenn keine gespeichert ist). - - `existing`: nur dann eine Sitzungs-ID senden, wenn vorher eine gespeichert wurde. + - `existing`: nur eine Sitzungs-ID senden, wenn zuvor eine gespeichert wurde. - `none`: niemals eine Sitzungs-ID senden. -- `claude-cli` verwendet standardmäßig `liveSession: "claude-stdio"`, `output: "jsonl"` - und `input: "stdin"`, sodass Folgezüge den laufenden Claude-Prozess wiederverwenden, während - er aktiv ist. Warmes stdio ist jetzt der Standard, auch bei benutzerdefinierten Konfigurationen, - die Transportfelder auslassen. Wenn das Gateway neu startet oder der Leerlaufprozess - beendet wird, setzt OpenClaw mit 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` gelöscht werden, statt stillschweigend - eine neue Claude-CLI-Sitzung unter `--resume` zu starten. -- Gespeicherte CLI-Sitzungen sind Provider-eigene Kontinuität. Das implizite tägliche Zurücksetzen der Sitzung - unterbricht sie nicht; `/reset` und explizite Richtlinien `session.reset` tun es weiterhin. +- `claude-cli` verwendet standardmäßig `liveSession: "claude-stdio"`, `output: "jsonl"`, + und `input: "stdin"`, sodass Folge-Turns den laufenden Claude-Prozess wiederverwenden, solange + er aktiv ist. Warme 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-IDs + werden vor dem Fortsetzen gegen ein vorhandenes lesbares Projekt-Transkript geprüft, sodass + Phantom-Bindungen mit `reason=transcript-missing` gelöscht werden, anstatt stillschweigend eine neue Claude-CLI-Sitzung unter `--resume` zu starten. +- Gespeicherte CLI-Sitzungen sind anbietereigene Kontinuität. Der implizite tägliche Sitzungs- + reset unterbricht sie nicht; `/reset` und explizite `session.reset`-Richtlinien schon. Hinweise zur Serialisierung: - `serialize: true` hält Läufe in derselben Lane geordnet. -- Die meisten CLIs serialisieren auf einer Provider-Lane. +- Die meisten CLIs serialisieren auf einer Anbieter-Lane. - 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, eines statischen Tokens oder der OAuth- - Kontenidentität, wenn die CLI eine solche bereitstellt. Die Rotation von OAuth-Zugriffs- und Refresh-Tokens - unterbricht die gespeicherte CLI-Sitzung nicht. Wenn eine CLI keine stabile OAuth-Konto-ID bereitstellt, - lässt OpenClaw diese CLI die Resume-Berechtigungen selbst durchsetzen. + Kontoidentität, wenn die CLI eine solche bereitstellt. Die Rotation von OAuth-Zugriffs- und Refresh-Tokens + unterbricht die gespeicherte CLI-Sitzung nicht. Wenn eine CLI keine stabile OAuth-Konto-ID offenlegt, + überlässt OpenClaw dieser CLI die Durchsetzung der Fortsetzungsberechtigungen. -## Bilder (Durchreichung) +## Bilder (Pass-through) Wenn Ihre CLI Bildpfade akzeptiert, setzen Sie `imageArg`: @@ -221,15 +231,15 @@ imageMode: "repeat" OpenClaw schreibt Base64-Bilder in temporäre Dateien. Wenn `imageArg` gesetzt ist, werden diese Pfade als CLI-Argumente übergeben. Wenn `imageArg` fehlt, hängt OpenClaw die Dateipfade an den Prompt an (Pfadinjektion), was für CLIs ausreicht, die lokale -Dateien automatisch aus einfachen Pfaden laden. +Dateien aus reinen Pfaden automatisch laden. -## Eingaben / Ausgaben +## Ein- / Ausgaben - `output: "json"` (Standard) versucht, JSON zu parsen und Text + Sitzungs-ID zu extrahieren. -- Für die Gemini-CLI-JSON-Ausgabe liest OpenClaw Antworttext aus `response` und +- Für die JSON-Ausgabe der Gemini CLI 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 endgültige Agentennachricht sowie Sitzungs- - Kennungen, wenn vorhanden. +- `output: "jsonl"` parst JSONL-Streams (zum Beispiel Codex CLI `--json`) und extrahiert die endgültige Agenten-Nachricht sowie Sitzungs- + kennungen, wenn vorhanden. - `output: "text"` behandelt stdout als endgültige Antwort. Eingabemodi: @@ -240,7 +250,7 @@ Eingabemodi: ## Standardwerte (Plugin-eigen) -Das gebündelte OpenAI Plugin registriert auch einen Standardwert für `codex-cli`: +Das gebündelte OpenAI-Plugin registriert auch einen Standardwert für `codex-cli`: - `command: "codex"` - `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]` @@ -251,7 +261,7 @@ Das gebündelte OpenAI Plugin registriert auch einen Standardwert für `codex-cl - `imageArg: "--image"` - `sessionMode: "existing"` -Das gebündelte Google Plugin registriert auch einen Standardwert für `google-gemini-cli`: +Das gebündelte Google-Plugin registriert auch einen Standardwert für `google-gemini-cli`: - `command: "gemini"` - `args: ["--output-format", "json", "--prompt", "{prompt}"]` @@ -263,31 +273,31 @@ Das gebündelte Google Plugin registriert auch einen Standardwert für `google-g - `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`). Hinweise zu Gemini-CLI-JSON: - Antworttext wird aus dem JSON-Feld `response` gelesen. -- Nutzung fällt auf `stats` zurück, wenn `usage` fehlt oder leer ist. +- Die Nutzung greift 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 Eingabetoken aus `stats.input_tokens - stats.cached` ab. -Überschreiben Sie nur bei Bedarf (üblich: absoluter `command`-Pfad). +Nur bei Bedarf überschreiben (häufig: absoluter `command`-Pfad). ## Plugin-eigene Standardwerte -Standardwerte für CLI-Backends sind jetzt Teil der Plugin-Oberfläche: +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. -- Backend-spezifische Konfigurationsbereinigung bleibt über den optionalen - Hook `normalizeConfig` im Besitz des Plugins. +- Die Backend-`id` wird zum Anbieterpräfix in Modell-Referenzen. +- Die Benutzerkonfiguration in `agents.defaults.cliBackends.` überschreibt weiterhin den Plugin-Standardwert. +- Das backend-spezifische Bereinigen der Konfiguration bleibt über den optionalen + Hook `normalizeConfig` plugin-eigen. -Plugins, die kleine Kompatibilitätsshims für Prompt/Nachrichten benötigen, können -bidirektionale Texttransformationen deklarieren, ohne einen Provider oder ein CLI-Backend zu ersetzen: +Plugins, die kleine Kompatibilitäts-Shims für Prompt/Nachrichten benötigen, können +bidirektionale Texttransformationen deklarieren, ohne einen Anbieter oder ein CLI-Backend zu ersetzen: ```typescript api.registerTextTransforms({ @@ -305,16 +315,16 @@ api.registerTextTransforms({ ``` `input` schreibt den System-Prompt und den Benutzer-Prompt um, die an die CLI übergeben werden. `output` -schreibt gestreamte Assistant-Deltas und geparsten Endtext um, bevor OpenClaw -seine eigenen Kontrollmarker und die Kanalzustellung verarbeitet. +schreibt gestreamte Assistant-Deltas und den geparsten Endtext um, bevor OpenClaw +seine eigenen Kontrollmarker und die Kanalauslieferung verarbeitet. -Für CLIs, die JSONL im Format Claude Code stream-json-kompatibel ausgeben, setzen Sie +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 -CLI-Backends erhalten **keine** direkten OpenClaw-Tool-Aufrufe, aber ein Backend kann -sich mit `bundleMcp: true` für ein generiertes MCP-Konfigurations-Overlay entscheiden. +CLI-Backends erhalten **keine** OpenClaw-Tool-Aufrufe direkt, aber ein Backend kann sich +mit `bundleMcp: true` für ein generiertes MCP-Konfigurations-Overlay anmelden. Aktuelles gebündeltes Verhalten: @@ -324,26 +334,26 @@ Aktuelles gebündeltes Verhalten: Wenn Bundle MCP aktiviert ist, führt OpenClaw Folgendes aus: -- Startet einen Loopback-HTTP-MCP-Server, der Gateway-Tools dem CLI-Prozess bereitstellt +- startet einen HTTP-Loopback-MCP-Server, der Gateway-Tools für den CLI-Prozess bereitstellt - authentifiziert die Bridge mit einem Token pro Sitzung (`OPENCLAW_MCP_TOKEN`) -- begrenzt den Tool-Zugriff auf die aktuelle Sitzung, das aktuelle Konto und den aktuellen Kanalkontext +- begrenzt den Tool-Zugriff auf die aktuelle Sitzung, das Konto und den Kanalkontext - lädt aktivierte Bundle-MCP-Server für den aktuellen Workspace -- führt sie mit jeder vorhandenen MCP-Konfigurations-/Einstellungsform des Backends zusammen -- schreibt die Startkonfiguration mit dem backend-eigenen Integrationsmodus aus der besitzenden Extension um +- führt sie mit einer vorhandenen MCP-Konfigurations-/Einstellungsstruktur des Backends zusammen +- schreibt die Startkonfiguration mithilfe des backend-eigenen Integrationsmodus aus der zugehörigen Erweiterung um -Wenn keine MCP-Server aktiviert sind, injiziert OpenClaw trotzdem eine strikte Konfiguration, wenn sich ein -Backend für Bundle MCP entscheidet, damit Hintergrundläufe isoliert bleiben. +Wenn keine MCP-Server aktiviert sind, injiziert OpenClaw dennoch eine strikte Konfiguration, wenn sich ein +Backend für Bundle MCP anmeldet, damit Hintergrundläufe isoliert bleiben. ## Einschränkungen - **Keine direkten OpenClaw-Tool-Aufrufe.** OpenClaw injiziert keine Tool-Aufrufe in - das CLI-Backend-Protokoll. Backends sehen Gateway-Tools nur dann, wenn sie sich für - `bundleMcp: true` entscheiden. + das CLI-Backend-Protokoll. Backends sehen Gateway-Tools nur, wenn sie sich für + `bundleMcp: true` anmelden. - **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 Lauf mit `--json`. OpenClaw-Sitzungen funktionieren trotzdem +- **Codex-CLI-Sitzungen** werden über Textausgabe fortgesetzt (ohne JSONL), was weniger + strukturiert ist als der ursprüngliche Lauf mit `--json`. OpenClaw-Sitzungen funktionieren weiterhin normal. ## Fehlerbehebung @@ -351,5 +361,5 @@ Backend für Bundle MCP entscheidet, damit Hintergrundläufe isoliert bleiben. - **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). + `none` ist (die Codex CLI kann derzeit nicht mit JSON-Ausgabe fortsetzen). - **Bilder werden ignoriert**: Setzen Sie `imageArg` (und prüfen Sie, ob die CLI Dateipfade unterstützt). diff --git a/docs/de/help/testing.md b/docs/de/help/testing.md index 8095f5022..bbacbadf8 100644 --- a/docs/de/help/testing.md +++ b/docs/de/help/testing.md @@ -2,164 +2,166 @@ read_when: - Tests lokal oder in CI ausführen - Regressionen für Modell-/Provider-Fehler hinzufügen - - Gateway- und Agentenverhalten debuggen -summary: 'Test-Kit: Unit-/E2E-/Live-Suiten, Docker-Runner und was jeder Test abdeckt' + - Gateway- und Agent-Verhalten debuggen +summary: 'Test-Kit: Unit-/E2E-/Live-Suites, Docker-Runner und was jeder Test abdeckt' title: Tests x-i18n: - generated_at: "2026-04-23T14:02:23Z" + generated_at: "2026-04-23T14:55:34Z" model: gpt-5.4 provider: openai - source_hash: fe0e9bdea78cba7e512358d2e4d428da04a2071188e74af2d5419d2c85eafe15 + source_hash: fbec4996699577321116c94f60c01d205d7594ed41aca27c821f1c3d65a7dca3 source_path: help/testing.md workflow: 15 --- # Tests -OpenClaw hat drei Vitest-Suiten (Unit/Integration, E2E, Live) und eine kleine Gruppe von Docker-Runnern. +OpenClaw hat drei Vitest-Suites (Unit/Integration, E2E, Live) und eine kleine Gruppe von Docker-Runnern. -Dieses Dokument ist ein Leitfaden zu „wie wir testen“: +Dieses Dokument ist ein Leitfaden dazu, „wie wir testen“: - Was jede Suite abdeckt (und was sie bewusst _nicht_ abdeckt) -- Welche Befehle Sie für gängige Abläufe ausführen sollten (lokal, vor dem Push, Debugging) +- Welche Befehle für gängige Workflows auszuführen sind (lokal, vor dem Push, Debugging) - Wie Live-Tests Anmeldedaten erkennen und Modelle/Provider auswählen -- Wie Sie Regressionen für reale Modell-/Provider-Probleme hinzufügen +- Wie Regressionen für reale Modell-/Provider-Probleme hinzugefügt werden ## Schnellstart An den meisten Tagen: - Vollständiges Gate (vor dem Push erwartet): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- Schnellere lokale Ausführung der vollständigen Suite auf einer leistungsfähigen Maschine: `pnpm test:max` +- Schnellerer lokaler Lauf der vollständigen Suite auf einem leistungsfähigen Rechner: `pnpm test:max` - Direkte Vitest-Watch-Schleife: `pnpm test:watch` -- Direktes Targeting von Dateien leitet jetzt auch Pfade für Extensions/Kanäle weiter: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Bevorzugen Sie zuerst gezielte Läufe, wenn Sie an einem einzelnen Fehler iterieren. +- Direktes Targeting von Dateien leitet jetzt auch Erweiterungs-/Kanal-Pfade weiter: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Bevorzuge zuerst gezielte Läufe, wenn du an einem einzelnen Fehler arbeitest. - Docker-gestützte QA-Site: `pnpm qa:lab:up` - Linux-VM-gestützte QA-Lane: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Wenn Sie Tests anfassen oder zusätzliche Sicherheit möchten: +Wenn du Tests anfasst oder zusätzliche Sicherheit möchtest: - Coverage-Gate: `pnpm test:coverage` - E2E-Suite: `pnpm test:e2e` -Beim Debuggen realer Provider/Modelle (erfordert echte Anmeldedaten): +Beim Debuggen echter Provider/Modelle (erfordert echte Anmeldedaten): -- Live-Suite (Modelle + Gateway-Tool-/Bild-Probes): `pnpm test:live` -- Eine einzelne Live-Datei still ausführen: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Live-Suite (Modelle + Gateway-Tool-/Image-Probes): `pnpm test:live` +- Eine einzelne Live-Datei ohne viel Ausgabe ausführen: `pnpm test:live -- src/agents/models.profiles.live.test.ts` - Docker-Live-Modell-Sweep: `pnpm test:docker:live-models` - - CI-Abdeckung: Die täglichen `OpenClaw Scheduled Live And E2E Checks` und die manuell + - Jedes ausgewählte Modell führt jetzt einen Text-Turn plus eine kleine Dateilese-artige Probe aus. + Modelle, deren Metadaten `image`-Eingabe ausweisen, führen auch einen kleinen Image-Turn aus. + Deaktiviere die zusätzlichen Probes mit `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` oder + `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0`, wenn du Provider-Fehler isolierst. + - CI-Abdeckung: Das tägliche `OpenClaw Scheduled Live And E2E Checks` und die manuell ausgelösten `OpenClaw Release Checks` rufen beide den wiederverwendbaren Live-/E2E-Workflow mit - `include_live_suites: true` auf, der separate Docker-Live-Modell- - Matrix-Jobs umfasst, nach Providern geshardet. - - Für gezielte CI-Neustarts dispatchen Sie `OpenClaw Live And E2E Checks (Reusable)` + `include_live_suites: true` auf, der separate Docker-Live-Modell-Matrix-Jobs umfasst, + geshardet nach Provider. + - Für gezielte CI-Neustarts dispatch `OpenClaw Live And E2E Checks (Reusable)` mit `include_live_suites: true` und `live_models_only: true`. - - Fügen Sie neue hochrelevante Provider-Secrets zu `scripts/ci-hydrate-live-auth.sh` - sowie `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` und dessen - geplanten/releasebezogenen Aufrufern hinzu. -- Moonshot/Kimi-Kosten-Smoke: Führen Sie mit gesetztem `MOONSHOT_API_KEY` - `openclaw models list --provider moonshot --json` aus und danach ein isoliertes + - Füge neue hochsignifikante Provider-Secrets zu `scripts/ci-hydrate-live-auth.sh` + sowie zu `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` und dessen + geplanten/Release-Callern hinzu. +- Moonshot/Kimi-Kosten-Smoke: Wenn `MOONSHOT_API_KEY` gesetzt ist, führe + `openclaw models list --provider moonshot --json` aus und dann ein isoliertes `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` - gegen `moonshot/kimi-k2.6`. Verifizieren Sie, dass JSON Moonshot/K2.6 meldet und das - Assistant-Transkript normalisierte `usage.cost` speichert. + gegen `moonshot/kimi-k2.6`. Verifiziere, dass das JSON Moonshot/K2.6 meldet und das + Assistant-Transkript normalisiertes `usage.cost` speichert. -Tipp: Wenn Sie nur einen einzigen fehlschlagenden Fall benötigen, grenzen Sie Live-Tests bevorzugt über die unten beschriebenen Env-Zulassungslistenvariablen ein. +Tipp: Wenn du nur einen einzelnen fehlschlagenden Fall brauchst, bevorzuge das Eingrenzen von Live-Tests über die unten beschriebenen Allowlist-Umgebungsvariablen. ## QA-spezifische Runner -Diese Befehle stehen neben den Haupttest-Suiten bereit, wenn Sie den Realismus von QA-Lab benötigen: +Diese Befehle stehen neben den Haupttest-Suites bereit, wenn du mehr QA-Lab-Realismus brauchst: -CI führt QA Lab in dedizierten Workflows aus. `Parity gate` läuft auf passenden PRs und +CI führt QA Lab in dedizierten Workflows aus. `Parity gate` läuft bei passenden PRs und bei manuellem Dispatch mit Mock-Providern. `QA-Lab - All Lanes` läuft nachts auf -`main` und bei manuellem Dispatch mit dem Mock-Parity-Gate, der Live-Matrix-Lane und der -Convex-verwalteten Live-Telegram-Lane als parallele Jobs. `OpenClaw Release Checks` -führt dieselben Lanes vor der Freigabe aus. +`main` und bei manuellem Dispatch mit dem Mock-Parity-Gate, der Live-Matrix-Lane und +der Convex-verwalteten Live-Telegram-Lane als parallele Jobs. `OpenClaw Release Checks` +führt dieselben Lanes vor der Release-Freigabe aus. - `pnpm openclaw qa suite` - Führt repo-gestützte QA-Szenarien direkt auf dem Host aus. - - Führt standardmäßig mehrere ausgewählte Szenarien parallel mit isolierten + - Führt mehrere ausgewählte Szenarien standardmäßig parallel mit isolierten Gateway-Workern aus. `qa-channel` verwendet standardmäßig Concurrency 4 (begrenzt durch die - Zahl der ausgewählten Szenarien). Verwenden Sie `--concurrency `, um die Worker- - Zahl anzupassen, oder `--concurrency 1` für die ältere serielle Lane. - - Beendet mit einem Nicht-Null-Code, wenn ein Szenario fehlschlägt. Verwenden Sie `--allow-failures`, wenn Sie - Artefakte ohne fehlschlagenden Exit-Code möchten. + Anzahl der ausgewählten Szenarien). Verwende `--concurrency `, um die Worker-Anzahl + anzupassen, oder `--concurrency 1` für die ältere serielle Lane. + - Beendet sich mit einem Fehlercode ungleich null, wenn irgendein Szenario fehlschlägt. Verwende `--allow-failures`, wenn du + Artefakte ohne fehlschlagenden Exit-Code möchtest. - Unterstützt die Provider-Modi `live-frontier`, `mock-openai` und `aimock`. `aimock` startet einen lokalen AIMock-gestützten Provider-Server für experimentelle Fixture- und Protokoll-Mock-Abdeckung, ohne die szenariobewusste `mock-openai`-Lane zu ersetzen. - `pnpm openclaw qa suite --runner multipass` - - Führt dieselbe QA-Suite in einer flüchtigen Multipass-Linux-VM aus. - - Behält dasselbe Verhalten zur Szenarioauswahl wie `qa suite` auf dem Host bei. - - Verwendet dieselben Flags zur Provider-/Modellauswahl wie `qa suite`. - - Live-Läufe leiten die unterstützten QA-Authentifizierungseingaben weiter, die für den Gast praktikabel sind: - env-basierte Provider-Schlüssel, den QA-Live-Provider-Konfigurationspfad und `CODEX_HOME`, falls vorhanden. - - Ausgabeverzeichnisse müssen unter dem Repo-Root bleiben, damit der Gast über den - gemounteten Workspace zurückschreiben kann. - - Schreibt den normalen QA-Report + die Zusammenfassung sowie Multipass-Logs unter + - Führt dieselbe QA-Suite innerhalb einer flüchtigen Multipass-Linux-VM aus. + - Behält dasselbe Szenarioauswahlverhalten wie `qa suite` auf dem Host bei. + - Verwendet dieselben Provider-/Modellauswahl-Flags wie `qa suite`. + - Live-Läufe leiten die unterstützten QA-Auth-Eingaben weiter, die für den Gast praktikabel sind: + umgebungsvariablenbasierte Provider-Keys, den Pfad zur QA-Live-Provider-Konfiguration und `CODEX_HOME`, + falls vorhanden. + - Ausgabeverzeichnisse müssen unter dem Repo-Root bleiben, damit der Gast über + den gemounteten Workspace zurückschreiben kann. + - Schreibt den normalen QA-Bericht + die Zusammenfassung sowie Multipass-Logs unter `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - Startet die Docker-gestützte QA-Site für operatorartige QA-Arbeit. - `pnpm test:docker:npm-onboard-channel-agent` - Baut ein npm-Tarball aus dem aktuellen Checkout, installiert es global in - Docker, führt nicht interaktives Onboarding mit OpenAI-API-Key aus, konfiguriert standardmäßig Telegram, + Docker, führt nicht-interaktives Onboarding mit OpenAI-API-Key aus, konfiguriert standardmäßig Telegram, verifiziert, dass das Aktivieren des Plugins Laufzeitabhängigkeiten bei Bedarf installiert, - führt `doctor` aus und führt einen lokalen Agent-Zug gegen einen gemockten OpenAI-Endpunkt aus. - - Verwenden Sie `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, um dieselbe Lane für die verpackte Installation + führt doctor aus und führt einen lokalen Agent-Turn gegen einen gemockten OpenAI-Endpunkt aus. + - Verwende `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, um dieselbe Lane für paketierte Installationen mit Discord auszuführen. - `pnpm test:docker:bundled-channel-deps` - Packt und installiert den aktuellen OpenClaw-Build in Docker, startet das Gateway - mit konfiguriertem OpenAI und aktiviert dann gebündelte Kanäle/Plugins über Konfigurationsbearbeitungen. - - Verifiziert, dass die Setup-Erkennung nicht konfigurierte Plugin-Laufzeitabhängigkeiten - nicht vorhanden lässt, dass der erste konfigurierte Gateway- oder `doctor`-Lauf die Laufzeitabhängigkeiten - jedes gebündelten Plugins bei Bedarf installiert und dass ein zweiter Neustart keine + mit konfiguriertem OpenAI und aktiviert dann gebündelte Kanal-/Plugins über Konfigurationsänderungen. + - Verifiziert, dass die Setup-Erkennung die Laufzeitabhängigkeiten nicht konfigurierter Plugins + nicht installiert, dass der erste konfigurierte Gateway- oder doctor-Lauf jeweils die + Laufzeitabhängigkeiten gebündelter Plugins bei Bedarf installiert und dass ein zweiter Neustart keine bereits aktivierten Abhängigkeiten erneut installiert. - - Installiert außerdem eine bekannte ältere npm-Basislinie, aktiviert Telegram vor dem Ausführen von - `openclaw update --tag ` und verifiziert, dass `doctor` des Kandidaten nach dem - Update Laufzeitabhängigkeiten gebündelter Kanäle ohne eine nachgelagerte Reparatur - durch den Harness behebt. + - Installiert außerdem eine bekannte ältere npm-Baseline, aktiviert Telegram vor dem Ausführen von + `openclaw update --tag ` und verifiziert, dass der doctor des Kandidaten nach dem + Update Laufzeitabhängigkeiten gebündelter Kanäle ohne postinstall-Reparatur auf Harness-Seite repariert. - `pnpm openclaw qa aimock` - - Startet nur den lokalen AIMock-Provider-Server für direkte Protokoll-Smoke- - Tests. + - Startet nur den lokalen AIMock-Provider-Server für direkte Protokoll-Smoke-Tests. - `pnpm openclaw qa matrix` - Führt die Matrix-Live-QA-Lane gegen einen flüchtigen, Docker-gestützten Tuwunel-Homeserver aus. - - Dieser QA-Host ist derzeit nur für Repo/Entwicklung gedacht. Verpackte OpenClaw-Installationen liefern - `qa-lab` nicht mit, daher stellen sie `openclaw qa` nicht bereit. - - Repo-Checkouts laden den gebündelten Runner direkt; ein separater Plugin-Installations- - Schritt ist nicht erforderlich. - - Stellt drei temporäre Matrix-Nutzer (`driver`, `sut`, `observer`) sowie einen privaten Raum bereit und startet dann ein QA-Gateway-Kind mit dem echten Matrix-Plugin als SUT-Transport. - - Verwendet standardmäßig das angeheftete stabile Tuwunel-Image `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Überschreiben Sie dies mit `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, wenn Sie ein anderes Image testen müssen. - - Matrix stellt keine gemeinsamen Flags für Credential-Quellen bereit, da die Lane lokal flüchtige Nutzer bereitstellt. - - Schreibt einen Matrix-QA-Report, eine Zusammenfassung, ein Artefakt mit beobachteten Ereignissen und ein kombiniertes stdout/stderr-Ausgabelog unter `.artifacts/qa-e2e/...`. + - Dieser QA-Host ist heute nur für Repo/Dev gedacht. Paketierte OpenClaw-Installationen liefern + `qa-lab` nicht mit aus, daher stellen sie `openclaw qa` nicht bereit. + - Repo-Checkouts laden den gebündelten Runner direkt; kein separater Plugin-Installationsschritt + ist nötig. + - Stellt drei temporäre Matrix-Benutzer (`driver`, `sut`, `observer`) plus einen privaten Raum bereit und startet dann einen QA-Gateway-Child mit dem echten Matrix-Plugin als SUT-Transport. + - Verwendet standardmäßig das angeheftete stabile Tuwunel-Image `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Überschreibe es mit `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, wenn du ein anderes Image testen musst. + - Matrix stellt keine gemeinsamen Credential-Source-Flags bereit, weil die Lane lokal flüchtige Benutzer bereitstellt. + - Schreibt einen Matrix-QA-Bericht, eine Zusammenfassung, ein Artefakt mit beobachteten Ereignissen und ein kombiniertes stdout/stderr-Ausgabelog unter `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Führt die Telegram-Live-QA-Lane gegen eine echte private Gruppe aus, unter Verwendung der Driver- und SUT-Bot-Tokens aus der Env. + - Führt die Telegram-Live-QA-Lane gegen eine echte private Gruppe aus, unter Verwendung der Driver- und SUT-Bot-Tokens aus der Umgebung. - Erfordert `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` und `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Die Gruppen-ID muss die numerische Telegram-Chat-ID sein. - - Unterstützt `--credential-source convex` für gemeinsam genutzte gepoolte Anmeldedaten. Verwenden Sie standardmäßig den Env-Modus oder setzen Sie `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, um sich für gepoolte Leases zu entscheiden. - - Beendet mit einem Nicht-Null-Code, wenn ein Szenario fehlschlägt. Verwenden Sie `--allow-failures`, wenn Sie - Artefakte ohne fehlschlagenden Exit-Code möchten. - - Erfordert zwei verschiedene Bots in derselben privaten Gruppe, wobei der SUT-Bot einen Telegram-Benutzernamen bereitstellen muss. - - Für stabile Bot-zu-Bot-Beobachtung aktivieren Sie in `@BotFather` den Modus Bot-to-Bot Communication für beide Bots und stellen Sie sicher, dass der Driver-Bot Bot-Verkehr in der Gruppe beobachten kann. - - Schreibt einen Telegram-QA-Report, eine Zusammenfassung und ein Artefakt mit beobachteten Nachrichten unter `.artifacts/qa-e2e/...`. Antwortszenarien enthalten RTT von der Send-Anfrage des Drivers bis zur beobachteten SUT-Antwort. + - Unterstützt `--credential-source convex` für gemeinsam genutzte gepoolte Anmeldedaten. Verwende standardmäßig den Env-Modus oder setze `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, um gepoolte Leases zu verwenden. + - Beendet sich mit einem Fehlercode ungleich null, wenn irgendein Szenario fehlschlägt. Verwende `--allow-failures`, wenn du + Artefakte ohne fehlschlagenden Exit-Code möchtest. + - Erfordert zwei unterschiedliche Bots in derselben privaten Gruppe, wobei der SUT-Bot einen Telegram-Benutzernamen bereitstellen muss. + - Für stabile Beobachtung von Bot-zu-Bot-Kommunikation aktiviere in `@BotFather` den Bot-to-Bot Communication Mode für beide Bots und stelle sicher, dass der Driver-Bot Bot-Traffic in der Gruppe beobachten kann. + - Schreibt einen Telegram-QA-Bericht, eine Zusammenfassung und ein Artefakt mit beobachteten Nachrichten unter `.artifacts/qa-e2e/...`. Antwortszenarien enthalten RTT von der Driver-Sendeanfrage bis zur beobachteten SUT-Antwort. -Live-Transport-Lanes teilen einen gemeinsamen Standardvertrag, damit neue Transporte nicht auseinanderdriften: +Live-Transport-Lanes verwenden einen gemeinsamen Standardvertrag, damit neue Transports nicht auseinanderdriften: -`qa-channel` bleibt die breite synthetische QA-Suite und ist nicht Teil der Live- -Transport-Abdeckungsmatrix. +`qa-channel` bleibt die breite synthetische QA-Suite und ist nicht Teil der Live-Transport-Abdeckungsmatrix. -| Lane | Canary | Erwähnungs-Gating | Zulassungslisten-Block | Antwort auf oberster Ebene | Neustart-Fortsetzung | Thread-Follow-up | Thread-Isolation | Reaktionsbeobachtung | Help-Befehl | -| -------- | ------ | ----------------- | ---------------------- | -------------------------- | -------------------- | ---------------- | ---------------- | -------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Lane | Canary | Mention-Gating | Allowlist-Block | Antwort auf oberster Ebene | Neustart-Fortsetzung | Thread-Follow-up | Thread-Isolation | Beobachtung von Reaktionen | Help-Befehl | +| -------- | ------ | -------------- | --------------- | -------------------------- | -------------------- | ---------------- | ---------------- | -------------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | -### Gemeinsame Telegram-Anmeldedaten über Convex (v1) +### Gemeinsam genutzte Telegram-Anmeldedaten über Convex (v1) Wenn `--credential-source convex` (oder `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) für -`openclaw qa telegram` aktiviert ist, bezieht QA lab ein exklusives Lease aus einem Convex-gestützten Pool, -sendet Heartbeats für dieses Lease, während die Lane läuft, und gibt das Lease beim Herunterfahren frei. +`openclaw qa telegram` aktiviert ist, erwirbt QA lab ein exklusives Lease aus einem Convex-gestützten Pool, sendet +Heartbeat für dieses Lease, während die Lane läuft, und gibt das Lease beim Herunterfahren wieder frei. -Referenzgerüst für das Convex-Projekt: +Referenz-Scaffold für Convex-Projekte: - `qa/convex-credential-broker/` -Erforderliche Env-Variablen: +Erforderliche Umgebungsvariablen: - `OPENCLAW_QA_CONVEX_SITE_URL` (zum Beispiel `https://your-deployment.convex.site`) - Ein Secret für die ausgewählte Rolle: @@ -167,9 +169,9 @@ Erforderliche Env-Variablen: - `OPENCLAW_QA_CONVEX_SECRET_CI` für `ci` - Auswahl der Credential-Rolle: - CLI: `--credential-role maintainer|ci` - - Env-Standard: `OPENCLAW_QA_CREDENTIAL_ROLE` (standardmäßig `ci` in CI, sonst `maintainer`) + - Standardwert aus der Umgebung: `OPENCLAW_QA_CREDENTIAL_ROLE` (standardmäßig `ci` in CI, sonst `maintainer`) -Optionale Env-Variablen: +Optionale Umgebungsvariablen: - `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (Standard `1200000`) - `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (Standard `30000`) @@ -177,11 +179,11 @@ Optionale Env-Variablen: - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (Standard `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (Standard `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (optionale Trace-ID) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` erlaubt Loopback-`http://`-Convex-URLs für rein lokale Entwicklung. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` erlaubt loopback-`http://`-Convex-URLs für rein lokale Entwicklung. `OPENCLAW_QA_CONVEX_SITE_URL` sollte im normalen Betrieb `https://` verwenden. -Maintainer-Admin-Befehle (Pool hinzufügen/entfernen/auflisten) erfordern +Maintainer-Admin-Befehle (Pool hinzufügen/entfernen/listen) erfordern explizit `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. CLI-Helfer für Maintainer: @@ -192,7 +194,7 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Verwenden Sie `--json` für maschinenlesbare Ausgabe in Skripten und CI-Hilfsprogrammen. +Verwende `--json` für maschinenlesbare Ausgabe in Skripten und CI-Utilities. Standard-Endpunktvertrag (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): @@ -217,63 +219,63 @@ Standard-Endpunktvertrag (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - Anfrage: `{ kind?, status?, includePayload?, limit? }` - Erfolg: `{ status: "ok", credentials, count }` -Payload-Form für die Art Telegram: +Payload-Form für Telegram-Art: - `{ groupId: string, driverToken: string, sutToken: string }` - `groupId` muss eine numerische Telegram-Chat-ID als String sein. -- `admin/add` validiert diese Form für `kind: "telegram"` und lehnt fehlerhafte Payloads ab. +- `admin/add` validiert diese Form für `kind: "telegram"` und weist fehlerhafte Payloads zurück. ### Einen Kanal zu QA hinzufügen Das Hinzufügen eines Kanals zum Markdown-QA-System erfordert genau zwei Dinge: 1. Einen Transport-Adapter für den Kanal. -2. Ein Szenariopaket, das den Kanalvertrag ausübt. +2. Ein Szenario-Pack, das den Kanalvertrag ausübt. -Fügen Sie keinen neuen QA-Befehls-Root auf oberster Ebene hinzu, wenn der gemeinsame Host `qa-lab` -den Ablauf besitzen kann. +Füge keinen neuen Top-Level-QA-Befehls-Root hinzu, wenn der gemeinsame `qa-lab`-Host +den Ablauf übernehmen kann. -`qa-lab` besitzt die gemeinsame Host-Mechanik: +`qa-lab` besitzt die gemeinsamen Host-Mechaniken: - den Befehls-Root `openclaw qa` -- Start und Herunterfahren der Suite +- Start und Stopp der Suite - Worker-Concurrency - Schreiben von Artefakten -- Berichterstellung +- Berichtsgenerierung - Szenarioausführung - Kompatibilitäts-Aliasse für ältere `qa-channel`-Szenarien Runner-Plugins besitzen den Transportvertrag: -- wie `openclaw qa ` unter dem gemeinsamen Root `qa` eingehängt wird +- wie `openclaw qa ` unter dem gemeinsamen `qa`-Root eingehängt wird - wie das Gateway für diesen Transport konfiguriert wird - wie Bereitschaft geprüft wird - wie eingehende Ereignisse injiziert werden - wie ausgehende Nachrichten beobachtet werden - wie Transkripte und normalisierter Transportzustand bereitgestellt werden - wie transportgestützte Aktionen ausgeführt werden -- wie transportspezifisches Reset oder Cleanup behandelt wird +- wie transport-spezifisches Zurücksetzen oder Cleanup behandelt wird -Die minimale Einführungsschwelle für einen neuen Kanal ist: +Die minimale Einstiegshürde für einen neuen Kanal ist: -1. Behalten Sie `qa-lab` als Besitzer des gemeinsamen Root `qa` bei. -2. Implementieren Sie den Transport-Runner auf dem gemeinsamen Host-Seam von `qa-lab`. -3. Behalten Sie transportspezifische Mechanik im Runner-Plugin oder Kanal-Harness. -4. Hängen Sie den Runner als `openclaw qa ` ein, statt einen konkurrierenden Root-Befehl zu registrieren. +1. Behalte `qa-lab` als Besitzer des gemeinsamen `qa`-Roots. +2. Implementiere den Transport-Runner auf der gemeinsamen `qa-lab`-Host-Seam. +3. Halte transport-spezifische Mechaniken im Runner-Plugin oder Kanal-Harness. +4. Hänge den Runner als `openclaw qa ` ein, statt einen konkurrierenden Root-Befehl zu registrieren. Runner-Plugins sollten `qaRunners` in `openclaw.plugin.json` deklarieren und ein passendes Array `qaRunnerCliRegistrations` aus `runtime-api.ts` exportieren. - Halten Sie `runtime-api.ts` schlank; lazy CLI- und Runner-Ausführung sollte hinter separaten Entry-Points bleiben. -5. Verfassen oder passen Sie Markdown-Szenarien unter den thematischen Verzeichnissen `qa/scenarios/` an. -6. Verwenden Sie die generischen Szenario-Helfer für neue Szenarien. -7. Halten Sie bestehende Kompatibilitäts-Aliasse funktionsfähig, sofern das Repo keine absichtliche Migration durchführt. + Halte `runtime-api.ts` schlank; lazy CLI- und Runner-Ausführung sollte hinter separaten Entry-Points bleiben. +5. Verfasse oder passe Markdown-Szenarien unter den thematischen Verzeichnissen `qa/scenarios/` an. +6. Verwende die generischen Szenario-Helfer für neue Szenarien. +7. Halte bestehende Kompatibilitäts-Aliasse funktionsfähig, sofern das Repo keine absichtliche Migration durchführt. Die Entscheidungsregel ist strikt: -- Wenn Verhalten einmalig in `qa-lab` ausgedrückt werden kann, platzieren Sie es in `qa-lab`. -- Wenn Verhalten von einem Kanaltransport abhängt, behalten Sie es in diesem Runner-Plugin oder Plugin-Harness. -- Wenn ein Szenario eine neue Fähigkeit benötigt, die von mehr als einem Kanal genutzt werden kann, fügen Sie einen generischen Helper hinzu statt eines kanalspezifischen Zweigs in `suite.ts`. -- Wenn ein Verhalten nur für einen Transport sinnvoll ist, halten Sie das Szenario transportspezifisch und machen Sie das im Szenariovertrag ausdrücklich. +- Wenn ein Verhalten einmalig in `qa-lab` ausgedrückt werden kann, gehört es in `qa-lab`. +- Wenn ein Verhalten von einem Kanaltransport abhängt, halte es im zugehörigen Runner-Plugin oder Plugin-Harness. +- Wenn ein Szenario eine neue Fähigkeit braucht, die mehr als ein Kanal nutzen kann, füge einen generischen Helfer hinzu statt eines kanal-spezifischen Zweigs in `suite.ts`. +- Wenn ein Verhalten nur für einen Transport sinnvoll ist, halte das Szenario transport-spezifisch und mache das im Szenariovertrag explizit. -Bevorzugte generische Helper-Namen für neue Szenarien sind: +Bevorzugte generische Helfernamen für neue Szenarien sind: - `waitForTransportReady` - `waitForChannelReady` @@ -296,102 +298,102 @@ Kompatibilitäts-Aliasse bleiben für bestehende Szenarien verfügbar, darunter: - `formatConversationTranscript` - `resetBus` -Neue Kanalarbeit sollte die generischen Helper-Namen verwenden. +Neue Kanal-Arbeit sollte die generischen Helfernamen verwenden. Kompatibilitäts-Aliasse existieren, um eine Flag-Day-Migration zu vermeiden, nicht als Modell für -neues Verfassen von Szenarien. +neue Szenario-Erstellung. -## Test-Suiten (was wo läuft) +## Test-Suites (was wo läuft) -Betrachten Sie die Suiten als „zunehmenden Realismus“ (und zunehmende Flakiness/Kosten): +Betrachte die Suites als „zunehmenden Realismus“ (und zunehmende Flakiness/Kosten): ### Unit / Integration (Standard) - Befehl: `pnpm test` -- Konfiguration: Nicht gezielte Läufe verwenden das Shard-Set `vitest.full-*.config.ts` und können Multi-Project-Shards für paralleles Scheduling in Konfigurationen pro Projekt aufteilen -- Dateien: Core-/Unit-Inventare unter `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` und die per Whitelist zugelassenen `ui`-Node-Tests, die von `vitest.unit.config.ts` abgedeckt werden +- Konfiguration: nicht gezielte Läufe verwenden das Shard-Set `vitest.full-*.config.ts` und können Multi-Project-Shards für parallele Planung in projektweise Konfigurationen aufteilen +- Dateien: Core-/Unit-Inventare unter `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` und die in `vitest.unit.config.ts` zugelassenen `ui`-Node-Tests - Umfang: - Reine Unit-Tests - - In-Process-Integrationstests (Gateway-Authentifizierung, Routing, Tooling, Parsing, Konfiguration) + - In-Process-Integrationstests (Gateway-Auth, Routing, Tooling, Parsing, Konfiguration) - Deterministische Regressionen für bekannte Fehler - Erwartungen: - Läuft in CI - - Keine echten Schlüssel erforderlich - - Soll schnell und stabil sein + - Keine echten Keys erforderlich + - Sollte schnell und stabil sein - Hinweis zu Projekten: - - Nicht gezieltes `pnpm test` führt jetzt zwölf kleinere Shard-Konfigurationen aus (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) statt eines riesigen nativen Root-Project-Prozesses. Das reduziert Peak-RSS auf ausgelasteten Maschinen und verhindert, dass Auto-Reply-/Extension-Arbeit nicht verwandte Suiten ausbremst. - - `pnpm test --watch` verwendet weiterhin den nativen Root-Project-Graph `vitest.config.ts`, weil eine Multi-Shard-Watch-Schleife nicht praktikabel ist. - - `pnpm test`, `pnpm test:watch` und `pnpm test:perf:imports` leiten explizite Datei-/Verzeichnisziele jetzt zuerst über eingegrenzte Lanes, sodass `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` nicht die vollständigen Startup-Kosten des Root-Projekts zahlen muss. - - `pnpm test:changed` erweitert geänderte Git-Pfade in dieselben eingegrenzten Lanes, wenn der Diff nur routbare Quell-/Testdateien berührt; Konfigurations-/Setup-Bearbeitungen fallen weiterhin auf die breite Neuausführung des Root-Projekts zurück. - - `pnpm check:changed` ist das normale intelligente lokale Gate für enge Arbeit. Es klassifiziert den Diff in Core, Core-Tests, Extensions, Extension-Tests, Apps, Docs, Release-Metadaten und Tooling und führt dann die passenden Typecheck-/Lint-/Test-Lanes aus. Änderungen am öffentlichen Plugin SDK und an Plugin-Verträgen umfassen Extension-Validierung, weil Extensions von diesen Core-Verträgen abhängen. Reine Versionsanhebungen in Release-Metadaten führen gezielte Prüfungen für Version/Konfiguration/Root-Abhängigkeiten aus statt der vollständigen Suite, mit einem Schutz, der Paketänderungen außerhalb des Versionsfelds auf oberster Ebene ablehnt. - - Import-leichte Unit-Tests aus Agents, Commands, Plugins, Auto-Reply-Helpern, `plugin-sdk` und ähnlichen reinen Utility-Bereichen werden über die Lane `unit-fast` geleitet, die `test/setup-openclaw-runtime.ts` überspringt; zustandsbehaftete/laufzeitschwere Dateien bleiben auf den bestehenden Lanes. - - Ausgewählte Helper-Quelldateien aus `plugin-sdk` und `commands` ordnen Changed-Mode-Läufe ebenfalls expliziten Nachbartests in diesen leichten Lanes zu, sodass Helper-Bearbeitungen keine erneute Ausführung der vollständigen schweren Suite für dieses Verzeichnis auslösen. - - `auto-reply` hat jetzt drei dedizierte Buckets: Helper auf oberster Core-Ebene, Integrations-Tests auf oberster Ebene `reply.*` und den Teilbaum `src/auto-reply/reply/**`. Dadurch bleibt die schwerste Reply-Harness-Arbeit von den günstigen Status-/Chunk-/Token-Tests getrennt. -- Hinweis zum Embedded Runner: - - Wenn Sie Discovery-Eingaben des Message-Tools oder den Laufzeitkontext von Compaction ändern, - behalten Sie beide Ebenen der Abdeckung bei. - - Fügen Sie fokussierte Helper-Regressionen für reine Routing-/Normalisierungsgrenzen hinzu. - - Halten Sie auch die Embedded-Runner-Integrationssuiten gesund: + - Nicht gezieltes `pnpm test` führt jetzt zwölf kleinere Shard-Konfigurationen aus (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) statt eines riesigen nativen Root-Project-Prozesses. Das senkt Peak-RSS auf ausgelasteten Rechnern und verhindert, dass Auto-Reply-/Erweiterungs-Arbeit nicht verwandte Suites ausbremst. + - `pnpm test --watch` verwendet weiterhin den nativen Root-Project-Graphen aus `vitest.config.ts`, weil eine Multi-Shard-Watch-Schleife nicht praktikabel ist. + - `pnpm test`, `pnpm test:watch` und `pnpm test:perf:imports` leiten explizite Datei-/Verzeichnis-Targets zuerst durch eingegrenzte Lanes, sodass `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` nicht die gesamten Startup-Kosten des Root-Projekts zahlen muss. + - `pnpm test:changed` erweitert geänderte Git-Pfade in dieselben eingegrenzten Lanes, wenn der Diff nur routbare Quell-/Testdateien berührt; Konfigurations-/Setup-Änderungen fallen weiterhin auf den breiten Root-Project-Rerun zurück. + - `pnpm check:changed` ist das normale smarte lokale Gate für enge Änderungen. Es klassifiziert den Diff in Core, Core-Tests, Erweiterungen, Erweiterungstests, Apps, Docs, Release-Metadaten und Tooling und führt dann die passenden Typecheck-/Lint-/Test-Lanes aus. Änderungen an der öffentlichen Plugin SDK und an Plugin-Verträgen umfassen Erweiterungsvalidierung, weil Erweiterungen von diesen Core-Verträgen abhängen. Reine Versionserhöhungen in Release-Metadaten führen gezielte Version-/Konfigurations-/Root-Dependency-Prüfungen aus statt der vollständigen Suite, mit einer Schutzmaßnahme, die Paketänderungen außerhalb des Versionsfelds auf Top-Level zurückweist. + - Import-leichte Unit-Tests aus Agents, Commands, Plugins, Auto-Reply-Helpern, `plugin-sdk` und ähnlichen reinen Utility-Bereichen laufen über die Lane `unit-fast`, die `test/setup-openclaw-runtime.ts` überspringt; zustandsbehaftete/laufzeitintensive Dateien bleiben auf den bestehenden Lanes. + - Ausgewählte Helper-Quelldateien aus `plugin-sdk` und `commands` mappen Changed-Mode-Läufe auch auf explizite Schwester-Tests in diesen leichten Lanes, sodass Helper-Edits vermeiden, die vollständige schwere Suite für dieses Verzeichnis erneut auszuführen. + - `auto-reply` hat jetzt drei dedizierte Buckets: Top-Level-Core-Helper, Top-Level-Integrationstests `reply.*` und den Unterbaum `src/auto-reply/reply/**`. Das hält die schwerste Reply-Harness-Arbeit von den günstigen Status-/Chunk-/Token-Tests fern. +- Hinweis zum eingebetteten Runner: + - Wenn du Eingaben für die Message-Tool-Erkennung oder den Laufzeitkontext von Compaction änderst, + behalte beide Ebenen der Abdeckung bei. + - Füge fokussierte Helper-Regressionen für reine Routing-/Normalisierungsgrenzen hinzu. + - Halte auch die eingebetteten Runner-Integrations-Suites gesund: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` und `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Diese Suiten verifizieren, dass Scoped-IDs und Compaction-Verhalten weiterhin - durch die echten Pfade `run.ts` / `compact.ts` fließen; reine Helper-Tests sind - kein ausreichender Ersatz für diese Integrationspfade. -- Hinweis zum Pool: + - Diese Suites verifizieren, dass gescopte IDs und Compaction-Verhalten weiterhin + durch die echten Pfade `run.ts` / `compact.ts` fließen; reine Helper-Tests sind kein + ausreichender Ersatz für diese Integrationspfade. +- Hinweis zu Pools: - Die Basis-Vitest-Konfiguration verwendet jetzt standardmäßig `threads`. - - Die gemeinsame Vitest-Konfiguration setzt außerdem `isolate: false` fest und verwendet den nicht isolierten Runner für Root-Projekte, E2E- und Live-Konfigurationen. - - Die Root-UI-Lane behält ihr `jsdom`-Setup und ihren Optimizer bei, läuft jetzt aber ebenfalls auf dem gemeinsamen nicht isolierten Runner. - - Jeder `pnpm test`-Shard erbt dieselben Standardwerte `threads` + `isolate: false` aus der gemeinsamen Vitest-Konfiguration. - - Der gemeinsame Launcher `scripts/run-vitest.mjs` fügt für Vitest-Kindprozesse standardmäßig auch `--no-maglev` hinzu, um bei großen lokalen Läufen die V8-Compile-Churn zu reduzieren. Setzen Sie `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, wenn Sie gegen das Standardverhalten von V8 vergleichen müssen. + - Die gemeinsame Vitest-Konfiguration setzt außerdem `isolate: false` fest und verwendet den nicht isolierten Runner über Root-Projekte, E2E- und Live-Konfigurationen hinweg. + - Die Root-UI-Lane behält ihr `jsdom`-Setup und ihren Optimizer, läuft jetzt aber ebenfalls auf dem gemeinsamen nicht isolierten Runner. + - Jeder `pnpm test`-Shard übernimmt dieselben Standards `threads` + `isolate: false` aus der gemeinsamen Vitest-Konfiguration. + - Der gemeinsame Launcher `scripts/run-vitest.mjs` fügt jetzt standardmäßig auch `--no-maglev` für Vitest-Child-Node-Prozesse hinzu, um V8-Kompilierungs-Churn bei großen lokalen Läufen zu reduzieren. Setze `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, wenn du mit Standard-V8-Verhalten vergleichen musst. - Hinweis zur schnellen lokalen Iteration: - `pnpm changed:lanes` zeigt, welche architektonischen Lanes ein Diff auslöst. - - Der Pre-Commit-Hook führt nach gestagtem Format/Lint `pnpm check:changed --staged` aus, sodass reine Core-Commits keine Kosten für Extension-Tests verursachen, sofern sie keine öffentlichen, extensionseitigen Verträge berühren. Commits nur mit Release-Metadaten bleiben auf der gezielten Lane für Version/Konfiguration/Root-Abhängigkeiten. - - Wenn genau dieselbe gestagte Änderungsmenge bereits mit gleich starken oder stärkeren Gates validiert wurde, verwenden Sie `scripts/committer --fast "" `, um nur die erneute Ausführung des Changed-Scope-Hooks zu überspringen. Gestagtes Format/Lint läuft weiterhin. Erwähnen Sie die abgeschlossenen Gates in Ihrer Übergabe. Das ist auch nach einem isolierten flaky Hook-Fehler akzeptabel, der mit eingegrenztem Nachweis erneut ausgeführt wurde und bestanden hat. - - `pnpm test:changed` leitet über eingegrenzte Lanes, wenn die geänderten Pfade sauber auf eine kleinere Suite abbilden. - - `pnpm test:max` und `pnpm test:changed:max` behalten dasselbe Routing-Verhalten bei, nur mit einer höheren Worker-Obergrenze. - - Die automatische lokale Worker-Skalierung ist jetzt absichtlich konservativ und fährt auch zurück, wenn die Host-Load-Average bereits hoch ist, sodass mehrere gleichzeitige Vitest-Läufe standardmäßig weniger Schaden anrichten. - - Die Basis-Vitest-Konfiguration markiert die Projekte-/Konfigurationsdateien als `forceRerunTriggers`, damit Reruns im Changed-Mode korrekt bleiben, wenn sich das Test-Wiring ändert. - - Die Konfiguration hält `OPENCLAW_VITEST_FS_MODULE_CACHE` auf unterstützten Hosts aktiviert; setzen Sie `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, wenn Sie einen expliziten Cache-Ort für direktes Profiling möchten. -- Hinweis zum Perf-Debug: - - `pnpm test:perf:imports` aktiviert Vitest-Reporting zur Importdauer sowie Ausgabe der Import-Aufschlüsselung. - - `pnpm test:perf:imports:changed` begrenzt dieselbe Profiling-Ansicht auf Dateien, die seit `origin/main` geändert wurden. -- `pnpm test:perf:changed:bench -- --ref ` vergleicht das geroutete `test:changed` mit dem nativen Root-Project-Pfad für diesen festgeschriebenen Diff und gibt Wall Time sowie macOS-Max-RSS aus. -- `pnpm test:perf:changed:bench -- --worktree` benchmarkt den aktuellen unsauberen Tree, indem die Liste geänderter Dateien durch `scripts/test-projects.mjs` und die Root-Vitest-Konfiguration geroutet wird. - - `pnpm test:perf:profile:main` schreibt ein CPU-Profil des Hauptthreads für Vitest/Vite-Startup und Transform-Overhead. + - Der Pre-Commit-Hook führt `pnpm check:changed --staged` nach Staged-Formatierung/Linting aus, sodass reine Core-Commits keine Kosten für Erweiterungstests verursachen, sofern sie keine öffentlichen, erweiterungsseitigen Verträge berühren. Commits mit nur Release-Metadaten bleiben auf der gezielten Version-/Konfigurations-/Root-Dependency-Lane. + - Wenn der exakte gestagte Änderungssatz bereits mit gleich starken oder stärkeren Gates validiert wurde, verwende `scripts/committer --fast "" `, um nur den Changed-Scope-Hook-Rerun zu überspringen. Gestagte Formatierung/Linting laufen weiterhin. Erwähne die abgeschlossenen Gates in deiner Übergabe. Das ist auch akzeptabel, nachdem ein isolierter flaky Hook-Fehler erneut ausgeführt wurde und mit eingegrenztem Nachweis bestanden hat. + - `pnpm test:changed` routet durch eingegrenzte Lanes, wenn die geänderten Pfade sauber auf eine kleinere Suite abgebildet werden. + - `pnpm test:max` und `pnpm test:changed:max` behalten dasselbe Routing-Verhalten bei, nur mit einem höheren Worker-Limit. + - Die automatische Skalierung lokaler Worker ist jetzt absichtlich konservativ und fährt auch zurück, wenn die Host-Load-Average bereits hoch ist, sodass mehrere gleichzeitige Vitest-Läufe standardmäßig weniger Schaden anrichten. + - Die Basis-Vitest-Konfiguration markiert die Projekte/Konfigurationsdateien als `forceRerunTriggers`, damit Changed-Mode-Reruns korrekt bleiben, wenn sich Test-Verdrahtung ändert. + - Die Konfiguration lässt `OPENCLAW_VITEST_FS_MODULE_CACHE` auf unterstützten Hosts aktiviert; setze `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, wenn du einen expliziten Cache-Speicherort für direktes Profiling möchtest. +- Hinweis zum Performance-Debugging: + - `pnpm test:perf:imports` aktiviert Vitest-Importdauer-Reporting plus Ausgabe der Import-Aufschlüsselung. + - `pnpm test:perf:imports:changed` beschränkt dieselbe Profiling-Ansicht auf Dateien, die seit `origin/main` geändert wurden. +- `pnpm test:perf:changed:bench -- --ref ` vergleicht geroutetes `test:changed` mit dem nativen Root-Project-Pfad für diesen festgeschriebenen Diff und gibt Wall Time plus macOS-Max-RSS aus. +- `pnpm test:perf:changed:bench -- --worktree` benchmarkt den aktuellen schmutzigen Tree, indem die Liste geänderter Dateien durch `scripts/test-projects.mjs` und die Root-Vitest-Konfiguration geroutet wird. + - `pnpm test:perf:profile:main` schreibt ein CPU-Profil des Main-Threads für Vitest-/Vite-Startup und Transform-Overhead. - `pnpm test:perf:profile:runner` schreibt CPU-+Heap-Profile des Runners für die Unit-Suite bei deaktivierter Dateiparallelität. ### Stabilität (Gateway) - Befehl: `pnpm test:stability:gateway` -- Konfiguration: `vitest.gateway.config.ts`, auf einen Worker fest erzwungen +- Konfiguration: `vitest.gateway.config.ts`, erzwungen auf einen Worker - Umfang: - - Startet ein echtes Loopback-Gateway mit standardmäßig aktivierter Diagnostik - - Treibt synthetische Churn für Gateway-Nachrichten, Memory und große Payloads durch den diagnostischen Ereignispfad + - Startet ein echtes loopback-Gateway mit standardmäßig aktivierter Diagnostik + - Treibt synthetische Gateway-Nachrichten, Memory- und Large-Payload-Churn über den Diagnostik-Ereignispfad - Fragt `diagnostics.stability` über Gateway-WS-RPC ab - - Deckt Persistenz-Helper des diagnostischen Stabilitäts-Bundles ab - - Stellt sicher, dass der Recorder begrenzt bleibt, synthetische RSS-Samples unter dem Druckbudget bleiben und Queuetiefen pro Sitzung wieder auf null zurücklaufen + - Deckt Persistenz-Helper für das diagnostische Stabilitäts-Bundle ab + - Stellt sicher, dass der Recorder begrenzt bleibt, synthetische RSS-Samples unter dem Druckbudget bleiben und Queue-Tiefen pro Session wieder auf null zurücklaufen - Erwartungen: - - CI-sicher und ohne Schlüssel - - Enge Lane für Follow-up bei Stabilitätsregressionen, kein Ersatz für die vollständige Gateway-Suite + - CI-sicher und ohne Keys + - Schmale Lane zur Nachverfolgung von Stabilitäts-Regressionen, kein Ersatz für die vollständige Gateway-Suite ### E2E (Gateway-Smoke) - Befehl: `pnpm test:e2e` - Konfiguration: `vitest.e2e.config.ts` - Dateien: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` und E2E-Tests gebündelter Plugins unter `extensions/` -- Laufzeitstandardwerte: - - Verwendet Vitest-`threads` mit `isolate: false`, konsistent mit dem Rest des Repos. +- Laufzeit-Standards: + - Verwendet Vitest-`threads` mit `isolate: false`, passend zum Rest des Repos. - Verwendet adaptive Worker (CI: bis zu 2, lokal: standardmäßig 1). - - Läuft standardmäßig im Silent-Modus, um Console-I/O-Overhead zu reduzieren. -- Nützliche Überschreibungen: - - `OPENCLAW_E2E_WORKERS=`, um die Worker-Zahl zu erzwingen (begrenzt auf 16). - - `OPENCLAW_E2E_VERBOSE=1`, um ausführliche Konsolenausgabe wieder zu aktivieren. + - Läuft standardmäßig im Silent-Modus, um den Overhead durch Konsolen-I/O zu reduzieren. +- Nützliche Overrides: + - `OPENCLAW_E2E_WORKERS=`, um die Worker-Anzahl zu erzwingen (begrenzt auf 16). + - `OPENCLAW_E2E_VERBOSE=1`, um wieder ausführliche Konsolenausgabe zu aktivieren. - Umfang: - End-to-End-Verhalten mit mehreren Gateway-Instanzen - - WebSocket-/HTTP-Oberflächen, Node-Pairing und schwereres Networking + - WebSocket-/HTTP-Oberflächen, Node-Pairing und schwergewichtigere Netzwerkarbeit - Erwartungen: - Läuft in CI (wenn in der Pipeline aktiviert) - - Keine echten Schlüssel erforderlich + - Keine echten Keys erforderlich - Mehr bewegliche Teile als Unit-Tests (kann langsamer sein) ### E2E: OpenShell-Backend-Smoke @@ -399,19 +401,19 @@ Betrachten Sie die Suiten als „zunehmenden Realismus“ (und zunehmende Flakin - Befehl: `pnpm test:e2e:openshell` - Datei: `extensions/openshell/src/backend.e2e.test.ts` - Umfang: - - Startet ein isoliertes OpenShell-Gateway auf dem Host über Docker - - Erstellt eine Sandbox aus einem temporären lokalen Dockerfile + - Startet über Docker ein isoliertes OpenShell-Gateway auf dem Host + - Erstellt aus einem temporären lokalen Dockerfile eine Sandbox - Übt OpenClaws OpenShell-Backend über echtes `sandbox ssh-config` + SSH-Exec aus - - Verifiziert Remote-Canonical-Dateisystemverhalten über die Sandbox-FS-Bridge + - Verifiziert remote-kanonisches Dateisystemverhalten über die Sandbox-FS-Bridge - Erwartungen: - - Nur per Opt-in; nicht Teil des Standardlaufs `pnpm test:e2e` - - Erfordert eine lokale `openshell`-CLI plus einen funktionierenden Docker-Daemon - - Verwendet isoliertes `HOME` / `XDG_CONFIG_HOME` und zerstört danach Test-Gateway und Sandbox -- Nützliche Überschreibungen: + - Nur per Opt-in; nicht Teil des standardmäßigen Laufs `pnpm test:e2e` + - Erfordert ein lokales `openshell`-CLI plus einen funktionierenden Docker-Daemon + - Verwendet isoliertes `HOME` / `XDG_CONFIG_HOME` und zerstört danach das Test-Gateway und die Sandbox +- Nützliche Overrides: - `OPENCLAW_E2E_OPENSHELL=1`, um den Test zu aktivieren, wenn die breitere E2E-Suite manuell ausgeführt wird - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, um auf eine nicht standardmäßige CLI-Binärdatei oder ein Wrapper-Skript zu zeigen + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, um auf ein nicht standardmäßiges CLI-Binary oder Wrapper-Skript zu zeigen -### Live (reale Provider + reale Modelle) +### Live (echte Provider + echte Modelle) - Befehl: `pnpm test:live` - Konfiguration: `vitest.live.config.ts` @@ -419,114 +421,114 @@ Betrachten Sie die Suiten als „zunehmenden Realismus“ (und zunehmende Flakin - Standard: **aktiviert** durch `pnpm test:live` (setzt `OPENCLAW_LIVE_TEST=1`) - Umfang: - „Funktioniert dieser Provider/dieses Modell _heute_ tatsächlich mit echten Anmeldedaten?“ - - Erkennt Änderungen an Provider-Formaten, Eigenheiten bei Tool-Aufrufen, Auth-Probleme und Verhalten bei Rate Limits + - Erkennt Änderungen an Provider-Formaten, Tool-Calling-Eigenheiten, Auth-Probleme und Rate-Limit-Verhalten - Erwartungen: - - Von Natur aus nicht CI-stabil (echte Netzwerke, echte Provider-Richtlinien, Kontingente, Ausfälle) + - Absichtlich nicht CI-stabil (echte Netzwerke, echte Provider-Richtlinien, Quoten, Ausfälle) - Kostet Geld / verbraucht Rate Limits - - Bevorzugen Sie eingegrenzte Teilmengen statt „alles“ -- Live-Läufe sourcen `~/.profile`, um fehlende API-Schlüssel aufzunehmen. -- Standardmäßig isolieren Live-Läufe weiterhin `HOME` und kopieren Konfigurations-/Auth-Material in ein temporäres Test-Home, sodass Unit-Fixtures Ihr echtes `~/.openclaw` nicht verändern können. -- Setzen Sie `OPENCLAW_LIVE_USE_REAL_HOME=1` nur dann, wenn Sie absichtlich benötigen, dass Live-Tests Ihr echtes Home-Verzeichnis verwenden. -- `pnpm test:live` verwendet jetzt standardmäßig einen leiseren Modus: Es behält die Fortschrittsausgabe `[live] ...` bei, unterdrückt jedoch den zusätzlichen Hinweis zu `~/.profile` und schaltet Gateway-Bootstrap-Logs/Bonjour-Chatter stumm. Setzen Sie `OPENCLAW_LIVE_TEST_QUIET=0`, wenn Sie die vollständigen Startlogs wieder sehen möchten. -- API-Key-Rotation (providerspezifisch): Setzen Sie `*_API_KEYS` im Komma-/Semikolon-Format oder `*_API_KEY_1`, `*_API_KEY_2` (zum Beispiel `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) oder eine Live-Überschreibung pro Lauf über `OPENCLAW_LIVE_*_KEY`; Tests versuchen bei Antworten mit Rate Limit erneut. + - Bevorzuge eingegrenzte Teilmengen statt „alles“ +- Live-Läufe sourcen `~/.profile`, um fehlende API-Keys aufzunehmen. +- Standardmäßig isolieren Live-Läufe weiterhin `HOME` und kopieren Konfigurations-/Auth-Material in ein temporäres Test-Home, damit Unit-Fixtures dein echtes `~/.openclaw` nicht verändern können. +- Setze `OPENCLAW_LIVE_USE_REAL_HOME=1` nur, wenn Live-Tests absichtlich dein echtes Home-Verzeichnis verwenden sollen. +- `pnpm test:live` verwendet jetzt standardmäßig einen ruhigeren Modus: `[live] ...`-Fortschrittsausgabe bleibt erhalten, aber der zusätzliche Hinweis zu `~/.profile` wird unterdrückt und Gateway-Bootstrap-Logs/Bonjour-Noise werden stummgeschaltet. Setze `OPENCLAW_LIVE_TEST_QUIET=0`, wenn du die vollständigen Startup-Logs zurückhaben möchtest. +- API-Key-Rotation (provider-spezifisch): setze `*_API_KEYS` im Komma-/Semikolon-Format oder `*_API_KEY_1`, `*_API_KEY_2` (zum Beispiel `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) oder pro Live-Override `OPENCLAW_LIVE_*_KEY`; Tests wiederholen sich bei Antworten mit Rate Limits. - Fortschritts-/Heartbeat-Ausgabe: - - Live-Suiten geben jetzt Fortschrittszeilen an stderr aus, damit lange Provider-Aufrufe sichtbar aktiv bleiben, auch wenn Vitests Console-Capture ruhig ist. - - `vitest.live.config.ts` deaktiviert das Abfangen der Vitest-Konsole, sodass Fortschrittszeilen von Provider/Gateway bei Live-Läufen sofort gestreamt werden. - - Passen Sie Heartbeats für direkte Modelle mit `OPENCLAW_LIVE_HEARTBEAT_MS` an. - - Passen Sie Heartbeats für Gateway/Probes mit `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` an. + - Live-Suites geben jetzt Fortschrittszeilen auf stderr aus, sodass bei stiller Vitest-Konsolenerfassung sichtbar bleibt, dass lange Provider-Aufrufe aktiv sind. + - `vitest.live.config.ts` deaktiviert Vitest-Konsolenabfangung, sodass Provider-/Gateway-Fortschrittszeilen bei Live-Läufen sofort gestreamt werden. + - Konfiguriere direkte Modell-Heartbeats mit `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Konfiguriere Gateway-/Probe-Heartbeats mit `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. -## Welche Suite sollte ich ausführen? +## Welche Suite soll ich ausführen? -Verwenden Sie diese Entscheidungstabelle: +Nutze diese Entscheidungstabelle: -- Logik/Tests bearbeiten: Führen Sie `pnpm test` aus (und `pnpm test:coverage`, wenn Sie viel geändert haben) -- Gateway-Networking / WS-Protokoll / Pairing berühren: Ergänzen Sie `pnpm test:e2e` -- Debugging von „mein Bot ist down“ / providerspezifischen Fehlern / Tool-Aufrufen: Führen Sie ein eingegrenztes `pnpm test:live` aus +- Logik/Tests bearbeiten: `pnpm test` ausführen (und `pnpm test:coverage`, wenn du viel geändert hast) +- Gateway-Netzwerk / WS-Protokoll / Pairing anfassen: `pnpm test:e2e` ergänzen +- „Mein Bot ist down“ / provider-spezifische Fehler / Tool-Calling debuggen: ein eingegrenztes `pnpm test:live` ausführen -## Live: Android-Node-Fähigkeitssweep +## Live: Android-Node-Capability-Sweep - Test: `src/gateway/android-node.capabilities.live.test.ts` - Skript: `pnpm android:test:integration` -- Ziel: **Jeden aktuell beworbenen Befehl** eines verbundenen Android-Node aufrufen und das Vertragsverhalten des Befehls validieren. +- Ziel: **jeden aktuell beworbenen Befehl** eines verbundenen Android-Node aufrufen und das Befehlsvertragsverhalten verifizieren. - Umfang: - - Manuelle/vorkonfigurierte Voraussetzungen (die Suite installiert/startet/paart die App nicht). - - Gateway-Validierung `node.invoke` Befehl für Befehl für den ausgewählten Android-Node. -- Erforderliches Vor-Setup: - - Android-App bereits mit dem Gateway verbunden + gepairt. + - Vorbedingte/manuelle Einrichtung (die Suite installiert/startet/paart die App nicht). + - Gateway-Validierung von `node.invoke` Befehl für Befehl für den ausgewählten Android-Node. +- Erforderliche Voreinrichtung: + - Android-App bereits verbunden + mit dem Gateway gepaart. - App im Vordergrund halten. - - Berechtigungen/Aufnahmezustimmung für Fähigkeiten gewähren, die bestehen sollen. -- Optionale Ziel-Überschreibungen: + - Berechtigungen/Capture-Einwilligungen für Capabilities erteilen, deren Erfolg du erwartest. +- 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-Setup-Details: [Android App](/de/platforms/android) -## Live: Modell-Smoke (Profil-Schlüssel) +## Live: Modell-Smoke (Profile-Keys) Live-Tests sind in zwei Ebenen aufgeteilt, damit wir Fehler isolieren können: -- „Direktes Modell“ sagt uns, ob der Provider/das Modell mit dem gegebenen Schlüssel überhaupt antworten kann. -- „Gateway-Smoke“ sagt uns, ob die vollständige Gateway+Agent-Pipeline für dieses Modell funktioniert (Sitzungen, Verlauf, Tools, Sandbox-Richtlinie usw.). +- „Direct model“ sagt uns, ob der Provider/das Modell mit dem angegebenen Key überhaupt antworten kann. +- „Gateway smoke“ sagt uns, ob die vollständige Gateway-+Agent-Pipeline für dieses Modell funktioniert (Sessions, Verlauf, Tools, Sandbox-Richtlinie usw.). ### Ebene 1: Direkte Modell-Completion (ohne Gateway) - Test: `src/agents/models.profiles.live.test.ts` - Ziel: - - Erkannte Modelle aufzählen - - Mit `getApiKeyForModel` Modelle auswählen, für die Sie Anmeldedaten haben + - Erkannte Modelle auflisten + - Mit `getApiKeyForModel` Modelle auswählen, für die du Anmeldedaten hast - Eine kleine Completion pro Modell ausführen (und gezielte Regressionen, wo nötig) -- So aktivieren Sie es: - - `pnpm test:live` (oder `OPENCLAW_LIVE_TEST=1`, wenn Sie Vitest direkt aufrufen) -- Setzen Sie `OPENCLAW_LIVE_MODELS=modern` (oder `all`, Alias für modern), um diese Suite tatsächlich auszuführen; sonst wird sie übersprungen, damit `pnpm test:live` auf Gateway-Smoke fokussiert bleibt -- So wählen Sie Modelle aus: - - `OPENCLAW_LIVE_MODELS=modern`, um die moderne Zulassungsliste auszuführen (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` ist ein Alias für die moderne Zulassungsliste - - oder `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (Komma-Zulassungsliste) - - Moderne/alle Sweeps verwenden standardmäßig eine kuratierte Obergrenze mit hohem Signal; setzen Sie `OPENCLAW_LIVE_MAX_MODELS=0` für einen vollständigen modernen Sweep oder eine positive Zahl für eine kleinere Obergrenze. -- So wählen Sie Provider aus: - - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (Komma-Zulassungsliste) -- Woher die Schlüssel kommen: - - Standardmäßig: Profilspeicher und Env-Fallbacks - - Setzen Sie `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um **nur** den Profilspeicher zu erzwingen +- Aktivierung: + - `pnpm test:live` (oder `OPENCLAW_LIVE_TEST=1`, wenn Vitest direkt aufgerufen wird) +- Setze `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 fokussiert bleibt +- Modellauswahl: + - `OPENCLAW_LIVE_MODELS=modern`, um die moderne Allowlist auszuführen (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` ist ein Alias für die moderne Allowlist + - oder `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (Komma-Allowlist) + - Modern-/All-Sweeps verwenden standardmäßig ein kuratiertes High-Signal-Limit; setze `OPENCLAW_LIVE_MAX_MODELS=0` für einen vollständigen modernen Sweep oder einen positiven Wert für ein kleineres Limit. +- Providerauswahl: + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (Komma-Allowlist) +- Herkunft der Keys: + - Standardmäßig: Profile-Store und Env-Fallbacks + - Setze `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um **nur** den Profile-Store zu erzwingen - Warum das existiert: - - Trennt „Provider-API ist kaputt / Schlüssel ist ungültig“ von „Gateway-Agent-Pipeline ist kaputt“ - - Enthält kleine, isolierte Regressionen (Beispiel: OpenAI-Responses/Codex-Responses Reasoning-Replay + Tool-Call-Flows) + - Trennt „Provider-API ist kaputt / Key ist ungültig“ von „Gateway-Agent-Pipeline ist kaputt“ + - Enthält kleine, isolierte Regressionen (Beispiel: OpenAI-Responses/Codex-Responses-Reasoning-Replay + Tool-Call-Flows) -### Ebene 2: Gateway + Dev-Agent-Smoke (was "@openclaw" tatsächlich tut) +### Ebene 2: Gateway + Dev-Agent-Smoke (was `@openclaw` tatsächlich macht) - Test: `src/gateway/gateway-models.profiles.live.test.ts` - Ziel: - Ein In-Process-Gateway hochfahren - - Eine Sitzung `agent:dev:*` erstellen/patchen (Modell-Override pro Lauf) - - Modelle-mit-Schlüsseln iterieren und Folgendes validieren: + - Eine Session `agent:dev:*` erstellen/patchen (Modell-Override pro Lauf) + - Modelle mit Keys iterieren und Folgendes verifizieren: - „sinnvolle“ Antwort (ohne Tools) - ein echter Tool-Aufruf funktioniert (Read-Probe) - - optionale zusätzliche Tool-Probes (Exec+Read-Probe) - - OpenAI-Regressionspfade (nur Tool-Call → Follow-up) bleiben funktionsfähig -- Probe-Details (damit Sie Fehler schnell erklären können): - - `read`-Probe: Der Test schreibt eine Nonce-Datei in den Workspace und fordert den Agenten auf, sie zu `read`en und die Nonce zurückzugeben. - - `exec+read`-Probe: Der Test fordert den Agenten auf, per `exec` eine Nonce in eine Temp-Datei zu schreiben und sie dann per `read` zurückzulesen. - - Bild-Probe: Der Test hängt ein generiertes PNG an (Katze + randomisierter Code) und erwartet, dass das Modell `cat ` zurückgibt. + - optionale zusätzliche Tool-Probes funktionieren (Exec+Read-Probe) + - OpenAI-Regression-Pfade (nur Tool-Call → Follow-up) funktionieren weiterhin +- Probe-Details (damit du Fehler schnell erklären kannst): + - `read`-Probe: Der Test schreibt eine Nonce-Datei in den Workspace und fordert den Agent auf, sie zu `read`en und die Nonce zurückzugeben. + - `exec+read`-Probe: Der Test fordert den Agent auf, per `exec` eine Nonce in eine temporäre Datei zu schreiben und sie dann wieder zu `read`en. + - Image-Probe: Der Test hängt ein generiertes PNG an (Katze + randomisierter 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`. -- So aktivieren Sie es: - - `pnpm test:live` (oder `OPENCLAW_LIVE_TEST=1`, wenn Sie Vitest direkt aufrufen) -- So wählen Sie Modelle aus: - - Standard: moderne Zulassungsliste (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` ist ein Alias für die moderne Zulassungsliste - - Oder setzen Sie `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (oder eine Komma-Liste) zur Eingrenzung - - Moderne/alle Gateway-Sweeps verwenden standardmäßig eine kuratierte Obergrenze mit hohem Signal; setzen Sie `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` für einen vollständigen modernen Sweep oder eine positive Zahl für eine kleinere Obergrenze. -- So wählen Sie Provider aus (vermeiden Sie „alles von OpenRouter“): - - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (Komma-Zulassungsliste) -- Tool- + Bild-Probes sind in diesem Live-Test immer aktiv: +- Aktivierung: + - `pnpm test:live` (oder `OPENCLAW_LIVE_TEST=1`, wenn Vitest direkt aufgerufen wird) +- Modellauswahl: + - Standard: moderne Allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` ist ein Alias für die moderne Allowlist + - Oder setze `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (oder Komma-Liste), um einzugrenzen + - Modern-/All-Gateway-Sweeps verwenden standardmäßig ein kuratiertes High-Signal-Limit; setze `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` für einen vollständigen modernen Sweep oder einen positiven Wert für ein kleineres Limit. +- Providerauswahl (vermeide „OpenRouter alles“): + - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (Komma-Allowlist) +- Tool- und Image-Probes sind in diesem Live-Test immer aktiv: - `read`-Probe + `exec+read`-Probe (Tool-Stress) - - Die Bild-Probe läuft, wenn das Modell Unterstützung für Bild-Eingaben bewirbt - - Ablauf (High Level): - - Der Test erzeugt ein kleines PNG mit „CAT“ + zufälligem Code (`src/gateway/live-image-probe.ts`) + - Image-Probe läuft, wenn das Modell Unterstützung für Bildeingaben bewirbt + - Ablauf (High-Level): + - Test erzeugt ein winziges 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`) - - Der eingebettete Agent leitet eine multimodale Benutzernachricht an das Modell weiter - - Validierung: Die Antwort enthält `cat` + den Code (OCR-Toleranz: kleine Fehler erlaubt) + - Eingebetteter Agent leitet eine multimodale User-Nachricht an das Modell weiter + - Assertion: Die Antwort enthält `cat` + den Code (OCR-Toleranz: kleinere Fehler erlaubt) -Tipp: Um zu sehen, was Sie auf Ihrer Maschine testen können (und die exakten IDs `provider/model`), führen Sie aus: +Tipp: Um zu sehen, was du auf deinem Rechner testen kannst (und die exakten IDs `provider/model`), führe aus: ```bash openclaw models list @@ -536,23 +538,23 @@ openclaw models list --json ## Live: CLI-Backend-Smoke (Claude, Codex, Gemini oder andere lokale CLIs) - Test: `src/gateway/gateway-cli-backend.live.test.ts` -- Ziel: Die Gateway- + Agent-Pipeline mit einem lokalen CLI-Backend validieren, ohne Ihre Standardkonfiguration zu verändern. -- Backend-spezifische Smoke-Standardwerte liegen in der Definition `cli-backend.ts` der besitzenden Extension. +- Ziel: die Gateway-+Agent-Pipeline mit einem lokalen CLI-Backend validieren, ohne deine Standardkonfiguration anzufassen. +- Backend-spezifische Smoke-Standards liegen in der `cli-backend.ts`-Definition der besitzenden Erweiterung. - Aktivieren: - - `pnpm test:live` (oder `OPENCLAW_LIVE_TEST=1`, wenn Sie Vitest direkt aufrufen) + - `pnpm test:live` (oder `OPENCLAW_LIVE_TEST=1`, wenn Vitest direkt aufgerufen wird) - `OPENCLAW_LIVE_CLI_BACKEND=1` -- Standardwerte: +- Standards: - Standard-Provider/-Modell: `claude-cli/claude-sonnet-4-6` - - Befehl/Args/Bildverhalten stammen aus den Metadaten des besitzenden CLI-Backend-Plugins. -- Überschreibungen (optional): + - Befehl/Args/Image-Verhalten stammen aus den Metadaten des besitzenden CLI-Backend-Plugins. +- Overrides (optional): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `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). - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, um Bilddateipfade als CLI-Args statt per Prompt-Injektion zu übergeben. - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (oder `"list"`), um zu steuern, wie Bild-Args übergeben werden, wenn `IMAGE_ARG` gesetzt ist. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, um einen zweiten Zug zu senden und den Resume-Fluss zu validieren. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, um die standardmäßige Kontinuitätsprobe derselben Sitzung von Claude Sonnet → Opus zu deaktivieren (setzen Sie `1`, um sie zu erzwingen, wenn das ausgewählte Modell ein Umschaltziel unterstützt). + - `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=0`, um die standardmäßige Kontinuitäts-Probe Claude Sonnet -> Opus innerhalb derselben Session zu deaktivieren (setze `1`, um sie zu erzwingen, wenn das ausgewählte Modell ein Umschaltziel unterstützt). Beispiel: @@ -579,30 +581,30 @@ pnpm test:docker:live-cli-backend:gemini Hinweise: -- Der Docker-Runner befindet sich unter `scripts/test-live-cli-backend-docker.sh`. -- Er führt den Live-CLI-Backend-Smoke im Repo-Docker-Image als nicht-root Nutzer `node` aus. -- Er löst CLI-Smoke-Metadaten aus der besitzenden Extension auf und installiert dann 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 beweist zuerst direktes `claude -p` in Docker und führt dann zwei Gateway-CLI-Backend-Züge aus, ohne Env-Variablen für Anthropic-API-Schlüssel beizubehalten. Diese Subscription-Lane deaktiviert standardmäßig die Claude-MCP-/Tool- und Bild-Probes, weil Claude derzeit die Nutzung durch Drittanbieter-Apps über zusätzliche Nutzungskosten statt über normale Subscription-Planlimits abrechnet. -- Der Live-CLI-Backend-Smoke übt jetzt denselben End-to-End-Fluss für Claude, Codex und Gemini aus: Text-Zug, Bildklassifizierungs-Zug, dann MCP-Tool-Aufruf `cron`, verifiziert über das Gateway CLI. -- Claudes Standard-Smoke patcht außerdem die Sitzung von Sonnet auf Opus und verifiziert, dass sich die fortgesetzte Sitzung weiterhin an eine frühere Notiz erinnert. +- Der Docker-Runner liegt unter `scripts/test-live-cli-backend-docker.sh`. +- Er führt den Live-CLI-Backend-Smoke innerhalb des Repo-Docker-Images als nicht-root `node`-Benutzer aus. +- Er löst CLI-Smoke-Metadaten aus der besitzenden Erweiterung auf und installiert dann 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` auf (Standard: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` erfordert portable Claude-Code-Subscription-OAuth über entweder `~/.claude/.credentials.json` mit `claudeAiOauth.subscriptionType` oder `CLAUDE_CODE_OAUTH_TOKEN` aus `claude setup-token`. Es prüft zuerst direkt `claude -p` in Docker und führt dann zwei Gateway-CLI-Backend-Turns aus, ohne Anthropic-API-Key-Umgebungsvariablen beizubehalten. Diese Subscription-Lane deaktiviert standardmäßig die Claude-MCP-/Tool- und Image-Probes, weil Claude die Nutzung durch Drittanbieter-Apps derzeit über Extra-Usage-Billing statt über normale Subscription-Plan-Limits abrechnet. +- Der Live-CLI-Backend-Smoke deckt jetzt denselben vollständigen End-to-End-Flow für Claude, Codex und Gemini ab: Text-Turn, Image-Klassifizierungs-Turn und dann `cron`-Tool-Call über Gateway-CLI verifiziert. +- Claudes standardmäßiger Smoke patcht außerdem die Session von Sonnet auf Opus und verifiziert, dass die fortgesetzte Session sich weiterhin an eine frühere Notiz erinnert. ## Live: ACP-Bind-Smoke (`/acp spawn ... --bind here`) - Test: `src/gateway/gateway-acp-bind.live.test.ts` -- Ziel: den echten ACP-Konversations-Bind-Ablauf mit einem Live-ACP-Agenten validieren: +- Ziel: den echten ACP-Conversation-Bind-Flow mit einem Live-ACP-Agent validieren: - `/acp spawn --bind here` senden - - eine synthetische Message-Channel-Konversation direkt binden + - eine synthetische Message-Channel-Konversation an Ort und Stelle binden - ein normales Follow-up in derselben Konversation senden - - verifizieren, dass das Follow-up im Transkript der gebundenen ACP-Sitzung landet -- Aktivieren: + - verifizieren, dass das Follow-up im Transkript der gebundenen ACP-Session landet +- Aktivierung: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` -- Standardwerte: +- Standards: - ACP-Agents in Docker: `claude,codex,gemini` - ACP-Agent für direktes `pnpm test:live ...`: `claude` - Synthetischer Kanal: Slack-DM-artiger Konversationskontext - ACP-Backend: `acpx` -- Überschreibungen: +- Overrides: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` - `OPENCLAW_LIVE_ACP_BIND_AGENT=gemini` @@ -610,8 +612,8 @@ Hinweise: - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.4` - Hinweise: - - Diese Lane verwendet die Gateway-Oberfläche `chat.send` mit rein adminseitigen synthetischen Feldern für die Ursprungroute, damit Tests Message-Channel-Kontext anhängen können, ohne vorzugeben, extern zuzustellen. - - Wenn `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` nicht gesetzt ist, verwendet der Test die eingebaute Agent-Registry des eingebetteten Plugins `acpx` für den ausgewählten ACP-Harness-Agenten. + - Diese Lane verwendet die Gateway-Oberfläche `chat.send` mit nur für Admin bestimmte synthetische Felder für die Ursprungsroute, sodass Tests Message-Channel-Kontext anhängen können, ohne vorzutäuschen, extern zuzustellen. + - 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. Beispiel: @@ -627,7 +629,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 @@ -637,20 +639,20 @@ pnpm test:docker:live-acp-bind:gemini Docker-Hinweise: -- Der Docker-Runner befindet sich unter `scripts/test-live-acp-bind-docker.sh`. +- Der Docker-Runner liegt unter `scripts/test-live-acp-bind-docker.sh`. - Standardmäßig führt er den ACP-Bind-Smoke nacheinander gegen alle unterstützten Live-CLI-Agents aus: `claude`, `codex`, dann `gemini`. -- Verwenden Sie `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` oder `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, um die Matrix einzugrenzen. -- Er sourct `~/.profile`, staged das passende CLI-Auth-Material in den Container, installiert `acpx` in ein beschreibbares npm-Präfix und installiert dann bei Bedarf die angeforderte Live-CLI (`@anthropic-ai/claude-code`, `@openai/codex` oder `@google/gemini-cli`). -- Innerhalb von Docker setzt der Runner `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, sodass `acpx` die Provider-Env-Variablen aus dem gesourcten Profil dem Kind-Harness-CLI verfügbar hält. +- Verwende `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` oder `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, um die Matrix einzugrenzen. +- Er sourced `~/.profile`, staged das passende CLI-Auth-Material in den Container, installiert `acpx` in ein beschreibbares npm-Präfix und installiert dann die angeforderte Live-CLI (`@anthropic-ai/claude-code`, `@openai/codex` oder `@google/gemini-cli`), falls sie fehlt. +- Innerhalb von Docker setzt der Runner `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, damit `acpx` Provider-Umgebungsvariablen aus dem gesourcten Profil für die Child-Harness-CLI verfügbar hält. ## Live: Codex-App-Server-Harness-Smoke -- Ziel: den plugin-eigenen Codex-Harness über die normale Gateway- - Methode `agent` validieren: +- Ziel: das plugin-eigene Codex-Harness über die normale Gateway-Methode + `agent` validieren: - das gebündelte Plugin `codex` laden - `OPENCLAW_AGENT_RUNTIME=codex` auswählen - - einen ersten Gateway-Agent-Zug an `codex/gpt-5.4` senden - - einen zweiten Zug an dieselbe OpenClaw-Sitzung senden und verifizieren, dass der App-Server- + - einen ersten Gateway-Agent-Turn an `codex/gpt-5.4` senden + - einen zweiten Turn an dieselbe OpenClaw-Session senden und verifizieren, dass der App-Server- Thread fortgesetzt werden kann - `/codex status` und `/codex models` über denselben Gateway-Befehls- pfad ausführen @@ -658,14 +660,14 @@ Docker-Hinweise: Befehl, der genehmigt werden sollte, und einen Fake-Secret-Upload, der abgelehnt werden sollte, sodass der Agent nachfragt - Test: `src/gateway/gateway-codex-harness.live.test.ts` -- Aktivieren: `OPENCLAW_LIVE_CODEX_HARNESS=1` +- Aktivierung: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Standardmodell: `codex/gpt-5.4` -- Optionale Bild-Probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- 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 setzt `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, sodass ein defekter Codex- - Harness nicht bestehen kann, indem er stillschweigend auf PI zurückfällt. -- Auth: `OPENAI_API_KEY` aus der Shell/dem Profil sowie optional kopierte +- Der Smoke setzt `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, sodass ein defektes Codex- + Harness nicht dadurch bestehen kann, dass es stillschweigend auf PI zurückfällt. +- Auth: `OPENAI_API_KEY` aus Shell/Profil sowie optional kopierte `~/.codex/auth.json` und `~/.codex/config.toml` Lokales Rezept: @@ -689,22 +691,22 @@ pnpm test:docker:live-codex-harness Docker-Hinweise: -- Der Docker-Runner befindet sich unter `scripts/test-live-codex-harness-docker.sh`. -- Er sourct das gemountete `~/.profile`, übergibt `OPENAI_API_KEY`, kopiert bei Vorhandensein Codex-CLI- - Auth-Dateien, installiert `@openai/codex` in ein beschreibbares gemountetes npm- - Präfix, staged den Quellbaum und führt dann nur den Codex-Harness-Live-Test aus. -- Docker aktiviert standardmäßig die Bild-, MCP-/Tool- und Guardian-Probes. Setzen Sie +- Der Docker-Runner liegt unter `scripts/test-live-codex-harness-docker.sh`. +- Er sourced das gemountete `~/.profile`, übergibt `OPENAI_API_KEY`, kopiert Codex-CLI- + Auth-Dateien, wenn vorhanden, installiert `@openai/codex` in ein beschreibbares gemountetes npm- + Präfix, staged den Source-Tree und führt dann nur den Live-Test für das Codex-Harness aus. +- Docker aktiviert standardmäßig die Image-, MCP-/Tool- und Guardian-Probes. Setze `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. + `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, wenn du einen engeren Debug- + Lauf brauchst. - Docker exportiert außerdem `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, passend zur Live- - Testkonfiguration, sodass `openai-codex/*`- oder PI-Fallback einen Codex-Harness- - Regressionsfehler nicht verbergen kann. + Testkonfiguration, sodass `openai-codex/*`- oder PI-Fallback keine Regression + im Codex-Harness verbergen kann. ### Empfohlene Live-Rezepte -Enge, explizite Zulassungslisten sind am schnellsten und am wenigsten flaky: +Enge, explizite Allowlists sind am schnellsten und am wenigsten flaky: - Einzelnes Modell, direkt (ohne Gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` @@ -712,7 +714,7 @@ Enge, explizite Zulassungslisten sind am schnellsten und am wenigsten flaky: - Einzelnes Modell, Gateway-Smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Tool-Aufrufe über mehrere Provider hinweg: +- Tool-Calling über mehrere Provider: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Google-Fokus (Gemini-API-Key + Antigravity): @@ -723,33 +725,33 @@ Hinweise: - `google/...` verwendet die Gemini-API (API-Key). - `google-antigravity/...` verwendet die Antigravity-OAuth-Bridge (Cloud-Code-Assist-artiger Agent-Endpunkt). -- `google-gemini-cli/...` verwendet die lokale Gemini CLI auf Ihrer Maschine (separate Auth- und Tooling-Eigenheiten). -- Gemini-API vs. Gemini CLI: - - API: OpenClaw ruft Googles gehostete Gemini-API über HTTP auf (API-Key / Profil-Auth); das meinen die meisten Nutzer mit „Gemini“. - - CLI: OpenClaw ruft eine lokale Binärdatei `gemini` auf; sie hat ihre eigene Auth und kann sich anders verhalten (Streaming/Tool-Unterstützung/Versionsabweichung). +- `google-gemini-cli/...` verwendet die lokale Gemini-CLI auf deinem Rechner (separate Auth + Tooling-Eigenheiten). +- Gemini-API vs. Gemini-CLI: + - API: OpenClaw ruft Googles gehostete Gemini-API über HTTP auf (API-Key / Profil-Auth); das ist, was die meisten Nutzer mit „Gemini“ meinen. + - CLI: OpenClaw führt ein lokales `gemini`-Binary aus; es hat eigene Auth und kann sich anders verhalten (Streaming/Tool-Support/Versions-Skew). ## Live: Modellmatrix (was wir abdecken) -Es gibt keine feste „CI-Modellliste“ (Live ist Opt-in), aber dies sind die **empfohlenen** Modelle, die regelmäßig auf einer Entwickler-Maschine mit Schlüsseln abgedeckt werden sollten. +Es gibt keine feste „CI-Modellliste“ (Live ist Opt-in), aber dies sind die **empfohlenen** Modelle, die regelmäßig auf einem Dev-Rechner mit Keys abgedeckt werden sollten. -### Modernes Smoke-Set (Tool-Aufrufe + Bild) +### Modernes Smoke-Set (Tool-Calling + Image) -Das ist der Lauf für die „gängigen Modelle“, der funktionsfähig bleiben soll: +Dies ist der Lauf für die „gängigen Modelle“, den wir funktionsfähig halten wollen: -- OpenAI (nicht Codex): `openai/gpt-5.4` (optional: `openai/gpt-5.4-mini`) +- OpenAI (nicht-Codex): `openai/gpt-5.4` (optional: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - 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` (vermeiden Sie ältere Gemini-2.x-Modelle) +- 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` - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Gateway-Smoke mit Tools + Bild ausführen: +Gateway-Smoke mit Tools + Image ausführen: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,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,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Basislinie: Tool-Aufrufe (Read + optional Exec) +### Baseline: Tool-Calling (Read + optional Exec) -Wählen Sie mindestens eins pro Provider-Familie: +Wähle mindestens eines pro Provider-Familie: - OpenAI: `openai/gpt-5.4` (oder `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (oder `anthropic/claude-sonnet-4-6`) @@ -760,78 +762,78 @@ Wählen Sie mindestens eins pro Provider-Familie: Optionale zusätzliche Abdeckung (nice to have): - xAI: `xai/grok-4` (oder die neueste verfügbare Version) -- Mistral: `mistral/`… (wählen Sie ein „tools“-fähiges Modell, das Sie aktiviert haben) -- Cerebras: `cerebras/`… (falls Sie Zugriff haben) -- LM Studio: `lmstudio/`… (lokal; Tool-Aufrufe hängen vom API-Modus ab) +- Mistral: `mistral/`… (wähle ein „tools“-fähiges Modell, das du aktiviert hast) +- Cerebras: `cerebras/`… (falls du Zugriff hast) +- LM Studio: `lmstudio/`… (lokal; Tool-Calling hängt vom API-Modus ab) ### Vision: Bild senden (Anhang → multimodale Nachricht) -Nehmen Sie mindestens ein bildfähiges Modell in `OPENCLAW_LIVE_GATEWAY_MODELS` auf (Claude-/Gemini-/OpenAI-Varianten mit Vision-Fähigkeit usw.), um die Bild-Probe auszuüben. +Nimm mindestens ein bildfähiges Modell in `OPENCLAW_LIVE_GATEWAY_MODELS` auf (Claude/Gemini/OpenAI mit Vision-fähigen Varianten usw.), um die Image-Probe auszuführen. ### Aggregatoren / alternative Gateways -Wenn Sie aktivierte Schlüssel haben, unterstützen wir Tests auch über: +Wenn du aktivierte Keys hast, unterstützen wir außerdem Tests über: -- OpenRouter: `openrouter/...` (Hunderte von Modellen; verwenden Sie `openclaw models scan`, um Kandidaten mit Tool- + Bild-Unterstützung zu finden) +- OpenRouter: `openrouter/...` (hunderte Modelle; verwende `openclaw models scan`, um Kandidaten mit Tool-+Image-Fähigkeit zu finden) - OpenCode: `opencode/...` für Zen und `opencode-go/...` für Go (Auth über `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Weitere Provider, die Sie in die Live-Matrix aufnehmen können (wenn Sie Anmeldedaten/Konfiguration haben): +Weitere Provider, die du in die Live-Matrix aufnehmen kannst (wenn du Credentials/Konfiguration hast): - Eingebaut: `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.) +- Über `models.providers` (Custom-Endpoints): `minimax` (Cloud/API) sowie jeder OpenAI-/Anthropic-kompatible Proxy (LM Studio, vLLM, LiteLLM usw.) -Tipp: Versuchen Sie nicht, in der Dokumentation „alle Modelle“ fest einzucodieren. Die maßgebliche Liste ist, was `discoverModels(...)` auf Ihrer Maschine zurückgibt + welche Schlüssel verfügbar sind. +Tipp: Versuche nicht, „alle Modelle“ in der Dokumentation fest zu verdrahten. Die maßgebliche Liste ist das, was `discoverModels(...)` auf deinem Rechner zurückgibt, plus die verfügbaren Keys. -## Anmeldedaten (niemals committen) +## Credentials (niemals committen) -Live-Tests erkennen Anmeldedaten auf dieselbe Weise wie die CLI. Praktische Auswirkungen: +Live-Tests erkennen Credentials auf dieselbe Weise wie die CLI. Praktische Folgen: -- Wenn die CLI funktioniert, sollten Live-Tests dieselben Schlüssel finden. -- Wenn ein Live-Test „keine Anmeldedaten“ meldet, debuggen Sie auf dieselbe Weise wie bei `openclaw models list` / Modellauswahl. +- Wenn die CLI funktioniert, sollten Live-Tests dieselben Keys finden. +- Wenn ein Live-Test „keine Credentials“ meldet, debugge ihn so, wie du `openclaw models list` / Modellauswahl debuggen würdest. -- Auth-Profile pro Agent: `~/.openclaw/agents//agent/auth-profiles.json` (das ist mit „Profil-Schlüsseln“ in den Live-Tests gemeint) +- Pro-Agent-Auth-Profile: `~/.openclaw/agents//agent/auth-profiles.json` (das ist es, was mit „Profile-Keys“ in den Live-Tests gemeint ist) - Konfiguration: `~/.openclaw/openclaw.json` (oder `OPENCLAW_CONFIG_PATH`) -- Veraltetes State-Dir: `~/.openclaw/credentials/` (wird in das staged Live-Home kopiert, wenn vorhanden, aber nicht in den Hauptspeicher für Profil-Schlüssel) -- Lokale Live-Läufe kopieren standardmäßig die aktive Konfiguration, `auth-profiles.json` pro Agent, veraltete `credentials/` und unterstützte externe CLI-Auth-Verzeichnisse in ein temporäres Test-Home; staged Live-Homes überspringen `workspace/` und `sandboxes/`, und Pfadüberschreibungen für `agents.*.workspace` / `agentDir` werden entfernt, sodass Probes Ihren realen Host-Workspace nicht berühren. +- Legacy-State-Verzeichnis: `~/.openclaw/credentials/` (wird, wenn vorhanden, in das gestagte Live-Home kopiert, ist aber nicht der Hauptspeicher für Profile-Keys) +- Lokale Live-Läufe kopieren standardmäßig die aktive Konfiguration, pro-Agent-`auth-profiles.json`-Dateien, Legacy-`credentials/` und unterstützte externe CLI-Auth-Verzeichnisse in ein temporäres Test-Home; gestagte Live-Homes überspringen `workspace/` und `sandboxes/`, und Pfad-Overrides `agents.*.workspace` / `agentDir` werden entfernt, damit Probes nicht in deinen echten Host-Workspace geraten. -Wenn Sie sich auf Env-Schlüssel verlassen möchten (z. B. exportiert in Ihrem `~/.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 du dich auf Env-Keys verlassen willst (z. B. exportiert in deinem `~/.profile`), führe lokale Tests nach `source ~/.profile` aus oder verwende die Docker-Runner unten (sie können `~/.profile` in den Container mounten). -## Deepgram live (Audio-Transkription) +## Deepgram Live (Audio-Transkription) - Test: `extensions/deepgram/audio.live.test.ts` -- Aktivieren: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts` +- Aktivierung: `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` -- Optionale Modellüberschreibung: `BYTEPLUS_CODING_MODEL=ark-code-latest` +- Aktivierung: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts` +- Optionales 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` +- Aktivierung: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Umfang: - - Übt die gebündelten Pfade für comfy-Bilder, -Video und `music_generate` aus - - Überspringt jede Fähigkeit, sofern `models.providers.comfy.` nicht konfiguriert ist - - Nützlich nach Änderungen an comfy-Workflow-Übermittlung, Polling, Downloads oder Plugin-Registrierung + - Deckt die gebündelten comfy-Pfade für Bilder, Videos und `music_generate` ab + - Überspringt jede Capability, sofern `models.providers.comfy.` nicht konfiguriert ist + - Nützlich nach Änderungen an comfy-Workflow-Submission, 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: - - Zählt jedes registrierte Plugin für Bildgenerierungs-Provider auf - - Lädt fehlende Provider-Env-Variablen aus Ihrer Login-Shell (`~/.profile`), bevor Probes ausgeführt werden - - Verwendet standardmäßig Live-/Env-API-Schlüssel vor gespeicherten Auth-Profilen, damit veraltete Testschlüssel in `auth-profiles.json` echte Shell-Anmeldedaten nicht verdecken + - Listet jedes registrierte Plugin für Bildgenerierungs-Provider auf + - Lädt fehlende Provider-Umgebungsvariablen vor dem Testen aus deiner Login-Shell (`~/.profile`) + - Verwendet standardmäßig Live-/Env-API-Keys vor gespeicherten Auth-Profilen, damit veraltete Test-Keys in `auth-profiles.json` keine echten Shell-Credentials maskieren - Überspringt Provider ohne nutzbare Auth/Profil/Modell - - Führt die Standardvarianten der Bildgenerierung über die gemeinsame Laufzeit-Fähigkeit aus: + - Führt die Standardvarianten der Bildgenerierung über die gemeinsame Runtime-Capability aus: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Aktuell abgedeckte gebündelte Provider: +- Derzeit abgedeckte gebündelte Provider: - `fal` - `google` - `minimax` @@ -843,74 +845,74 @@ Wenn Sie sich auf Env-Schlüssel verlassen möchten (z. B. exportiert in Ihrem ` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,xai:default-generate,xai:default-edit"` - Optionales Auth-Verhalten: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Auth aus dem Profilspeicher zu erzwingen und reine Env-Overrides zu ignorieren + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Auth aus dem Profile-Store zu erzwingen und rein env-basierte Overrides zu ignorieren -## 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` +- Aktivierung: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Umfang: - - Übt den gemeinsam gebündelten Pfad für Musikgenerierungs-Provider aus + - Deckt den gemeinsamen gebündelten Pfad für Musikgenerierungs-Provider ab - Deckt derzeit Google und MiniMax ab - - Lädt Provider-Env-Variablen aus Ihrer Login-Shell (`~/.profile`), bevor Probes ausgeführt werden - - Verwendet standardmäßig Live-/Env-API-Schlüssel vor gespeicherten Auth-Profilen, damit veraltete Testschlüssel in `auth-profiles.json` echte Shell-Anmeldedaten nicht verdecken + - Lädt Provider-Umgebungsvariablen vor dem Testen aus deiner Login-Shell (`~/.profile`) + - Verwendet standardmäßig Live-/Env-API-Keys vor gespeicherten Auth-Profilen, damit veraltete Test-Keys in `auth-profiles.json` keine echten Shell-Credentials maskieren - Überspringt Provider ohne nutzbare Auth/Profil/Modell - - Führt beide deklarierten Laufzeitmodi aus, wenn verfügbar: - - `generate` mit reiner Prompt-Eingabe + - Führt beide deklarierten Runtime-Modi aus, wenn verfügbar: + - `generate` mit rein promptbasierter Eingabe - `edit`, wenn der Provider `capabilities.edit.enabled` deklariert - - Aktuelle Abdeckung der gemeinsamen Lane: + - Derzeitige Abdeckung in der gemeinsamen Lane: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: separate Comfy-Live-Datei, nicht dieser gemeinsame Sweep + - `comfy`: separate Comfy-Live-Datei, nicht Teil dieses gemeinsamen Sweeps - Optionale Eingrenzung: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - Optionales Auth-Verhalten: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Auth aus dem Profilspeicher zu erzwingen und reine Env-Overrides zu ignorieren + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Auth aus dem Profile-Store zu erzwingen und rein env-basierte 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` +- Aktivierung: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Umfang: - - Übt den gemeinsam gebündelten Pfad für Videogenerierungs-Provider 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 Obergrenze pro Provider-Operation aus `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (standardmäßig `180000`) - - Überspringt FAL standardmäßig, weil providerseitige Queue-Latenz die Release-Zeit dominieren kann; übergeben Sie `--video-providers fal` oder `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, um es explizit auszuführen - - Lädt Provider-Env-Variablen aus Ihrer Login-Shell (`~/.profile`), bevor Probes ausgeführt werden - - Verwendet standardmäßig Live-/Env-API-Schlüssel vor gespeicherten Auth-Profilen, damit veraltete Testschlüssel in `auth-profiles.json` echte Shell-Anmeldedaten nicht verdecken + - Deckt den gemeinsamen gebündelten Pfad für Videogenerierungs-Provider ab + - Verwendet standardmäßig den release-sicheren Smoke-Pfad: nicht-FAL-Provider, eine Text-zu-Video-Anfrage pro Provider, ein einsekündiger Hummer-Prompt und ein provider-spezifisches Operationslimit aus `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (standardmäßig `180000`) + - Überspringt FAL standardmäßig, weil providerseitige Queue-Latenz die Release-Zeit dominieren kann; übergib `--video-providers fal` oder `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, um es explizit auszuführen + - Lädt Provider-Umgebungsvariablen vor dem Testen aus deiner Login-Shell (`~/.profile`) + - Verwendet standardmäßig Live-/Env-API-Keys vor gespeicherten Auth-Profilen, damit veraltete Test-Keys in `auth-profiles.json` keine echten Shell-Credentials maskieren - Überspringt Provider ohne nutzbare Auth/Profil/Modell - Führt standardmäßig nur `generate` aus - - Setzen Sie `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, um bei Verfügbarkeit auch deklarierte Transformationsmodi auszuführen: - - `imageToVideo`, wenn der Provider `capabilities.imageToVideo.enabled` deklariert und das ausgewählte Provider-/Modell in diesem gemeinsamen Sweep buffer-gestützte lokale Bildeingabe akzeptiert - - `videoToVideo`, wenn der Provider `capabilities.videoToVideo.enabled` deklariert und das ausgewählte Provider-/Modell in diesem gemeinsamen Sweep buffer-gestützte 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 entfernte Bild-URL erfordert + - Setze `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 in diesem 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 in diesem gemeinsamen Sweep buffer-gestützte lokale Videoeingabe akzeptiert + - Derzeit 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 ein Fixture mit entfernter Bild-URL verwendet - - Aktuelle `videoToVideo`-Live-Abdeckung: + - diese Datei führt `veo3` Text-zu-Video sowie standardmäßig eine `kling`-Lane mit einer Fixture für eine Remote-Bild-URL aus + - Derzeitige `videoToVideo`-Live-Abdeckung: - nur `runway`, 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 entfernte Referenz-URLs `http(s)` / MP4 erfordern + - Derzeit deklarierte, aber im gemeinsamen Sweep übersprungene `videoToVideo`-Provider: + - `alibaba`, `qwen`, `xai`, weil diese Pfade derzeit Remote-Referenz-URLs `http(s)` / MP4 erfordern - `google`, weil die aktuelle gemeinsame Gemini-/Veo-Lane lokale buffer-gestützte Eingabe verwendet und dieser Pfad im gemeinsamen Sweep nicht akzeptiert wird - - `openai`, weil der aktuellen gemeinsamen Lane Garantien für org-spezifischen Zugriff auf Video-Inpaint/Remix fehlen + - `openai`, weil die aktuelle gemeinsame Lane keine Garantien für organisationsspezifischen Zugriff auf Video-Inpaint/Remix hat - Optionale Eingrenzung: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="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 einzubeziehen, einschließlich FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, um die Obergrenze jeder Provider-Operation für einen aggressiven Smoke-Lauf zu senken + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, um jeden Provider in den Standard-Sweep aufzunehmen, einschließlich FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, um das Operationslimit pro Provider für einen aggressiven Smoke-Lauf zu reduzieren - Optionales Auth-Verhalten: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Auth aus dem Profilspeicher zu erzwingen und reine Env-Overrides zu ignorieren + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Auth aus dem Profile-Store zu erzwingen und rein env-basierte Overrides zu ignorieren ## Medien-Live-Harness - Befehl: `pnpm test:live:media` - Zweck: - - Führt die gemeinsamen Live-Suiten für Bild, Musik und Video über einen nativen Repo-Entry-Point aus - - Lädt fehlende Provider-Env-Variablen automatisch aus `~/.profile` - - Grenzt jede Suite standardmäßig automatisch auf Provider ein, die aktuell nutzbare Auth haben + - Führt die gemeinsamen Live-Suites für Bild, Musik und Video über einen repo-nativen Entry-Point aus + - Lädt fehlende Provider-Umgebungsvariablen automatisch aus `~/.profile` + - Grenzt jede Suite standardmäßig automatisch auf Provider ein, die derzeit nutzbare Auth haben - Verwendet erneut `scripts/test-live.mjs`, sodass Heartbeat- und Quiet-Mode-Verhalten konsistent bleiben - Beispiele: - `pnpm test:live:media` @@ -918,21 +920,22 @@ Wenn Sie sich auf Env-Schlüssel verlassen möchten (z. B. exportiert in Ihrem ` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Docker-Runner (optionale Prüfungen „funktioniert unter Linux“) +## Docker-Runner (optionale „funktioniert unter Linux“-Checks) -Diese Docker-Runner teilen sich in zwei Gruppen: +Diese Docker-Runner sind in zwei Gruppen aufgeteilt: -- Live-Modell-Runner: `test:docker:live-models` und `test:docker:live-gateway` führen nur ihre jeweils passende Live-Datei mit Profil-Schlüsseln im Repo-Docker-Image aus (`src/agents/models.profiles.live.test.ts` und `src/gateway/gateway-models.profiles.live.test.ts`), wobei Ihr lokales Konfigurationsverzeichnis und Ihr Workspace gemountet werden (und `~/.profile` gesourct wird, falls gemountet). Die passenden lokalen Entry-Points sind `test:live:models-profiles` und `test:live:gateway-profiles`. -- Docker-Live-Runner verwenden standardmäßig eine kleinere Smoke-Obergrenze, damit ein vollständiger Docker-Sweep praktikabel bleibt: +- Live-Modell-Runner: `test:docker:live-models` und `test:docker:live-gateway` führen nur ihre jeweils passende Live-Datei für Profile-Keys innerhalb des Repo-Docker-Images aus (`src/agents/models.profiles.live.test.ts` und `src/gateway/gateway-models.profiles.live.test.ts`), wobei dein lokales Konfigurationsverzeichnis und dein Workspace gemountet werden (und `~/.profile`, falls gemountet, gesourced wird). Die passenden lokalen Entry-Points sind `test:live:models-profiles` und `test:live:gateway-profiles`. +- Docker-Live-Runner verwenden standardmäßig ein kleineres Smoke-Limit, damit ein vollständiger Docker-Sweep praktikabel bleibt: `test:docker:live-models` verwendet standardmäßig `OPENCLAW_LIVE_MAX_MODELS=12`, und `test:docker:live-gateway` verwendet standardmäßig `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` und - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Überschreiben Sie diese Env-Variablen, wenn Sie - ausdrücklich den größeren vollständigen Scan wünschen. -- `test:docker:all` baut das Live-Docker-Image einmal über `test:docker:live-build` und verwendet es dann für die beiden Live-Docker-Lanes erneut. Außerdem baut es ein gemeinsames Image `scripts/e2e/Dockerfile` über `test:docker:e2e-build` und verwendet dieses für die E2E-Container-Smoke-Runner erneut, die die gebaute App ausüben. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Überschreibe diese Env-Variablen, wenn du + ausdrücklich den größeren vollständigen Scan möchtest. +- `test:docker:all` baut das Live-Docker-Image einmal über `test:docker:live-build` und verwendet es dann für die beiden Docker-Lanes für Live erneut. Es baut außerdem ein gemeinsames Image `scripts/e2e/Dockerfile` über `test:docker:e2e-build` und verwendet es erneut für die E2E-Container-Smoke-Runner, die die gebaute App ausführen. +- Container-Smoke-Runner: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` und `test:docker:config-reload` starten einen oder mehrere echte Container und verifizieren höherstufige Integrationspfade. -Die Live-Modell-Docker-Runner binden außerdem nur die benötigten CLI-Auth-Homes ein (oder alle unterstützten, wenn der Lauf nicht eingegrenzt ist) und kopieren sie dann vor dem Lauf in das Container-Home, damit OAuth externer CLI-Tools Tokens aktualisieren kann, ohne den Auth-Speicher des Hosts zu verändern: +Die Docker-Runner für Live-Modelle binden außerdem nur die benötigten CLI-Auth-Homes per Bind-Mount ein (oder alle unterstützten, wenn der Lauf nicht eingegrenzt ist) und kopieren sie dann vor dem Lauf in das Container-Home, damit externe CLI-OAuth Tokens aktualisieren kann, ohne den Auth-Store auf dem Host zu verändern: - Direkte Modelle: `pnpm test:docker:live-models` (Skript: `scripts/test-live-models-docker.sh`) - ACP-Bind-Smoke: `pnpm test:docker:live-acp-bind` (Skript: `scripts/test-live-acp-bind-docker.sh`) @@ -941,132 +944,132 @@ Die Live-Modell-Docker-Runner binden außerdem nur die benötigten CLI-Auth-Home - Gateway + Dev-Agent: `pnpm test:docker:live-gateway` (Skript: `scripts/test-live-gateway-models-docker.sh`) - Open-WebUI-Live-Smoke: `pnpm test:docker:openwebui` (Skript: `scripts/e2e/openwebui-docker.sh`) - Onboarding-Assistent (TTY, vollständiges Scaffolding): `pnpm test:docker:onboard` (Skript: `scripts/e2e/onboard-docker.sh`) -- Npm-Tarball-Onboarding-/Kanal-/Agent-Smoke: `pnpm test:docker:npm-onboard-channel-agent` installiert das gepackte OpenClaw-Tarball global in Docker, konfiguriert OpenAI standardmäßig über Env-Ref-Onboarding plus Telegram, verifiziert, dass das Aktivieren des Plugins seine Laufzeit-Dependencies bei Bedarf installiert, führt `doctor` aus und führt einen gemockten OpenAI-Agent-Zug aus. Verwenden Sie ein vorgebautes Tarball erneut mit `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, überspringen Sie den Host-Neubau mit `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` oder wechseln Sie den Kanal mit `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Gateway-Networking (zwei Container, WS-Auth + Health): `pnpm test:docker:gateway-network` (Skript: `scripts/e2e/gateway-network-docker.sh`) -- Minimale Reasoning-Regression für OpenAI Responses `web_search`: `pnpm test:docker:openai-web-search-minimal` (Skript: `scripts/e2e/openai-web-search-minimal-docker.sh`) führt einen gemockten OpenAI-Server durch Gateway aus, verifiziert, dass `web_search` `reasoning.effort` von `minimal` auf `low` anhebt, erzwingt dann die Ablehnung durch das Provider-Schema und prüft, dass das rohe Detail in den Gateway-Logs erscheint. -- MCP-Kanal-Bridge (geseedetes Gateway + stdio-Bridge + roher Claude-Notification-Frame-Smoke): `pnpm test:docker:mcp-channels` (Skript: `scripts/e2e/mcp-channels-docker.sh`) -- Pi-Bundle-MCP-Tools (echter stdio-MCP-Server + eingebetteter Pi-Profil-allow/deny-Smoke): `pnpm test:docker:pi-bundle-mcp-tools` (Skript: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Cron-/Subagent-MCP-Cleanup (echtes Gateway + stdio-MCP-Kindprozess-Teardown nach isolierten Cron- und One-Shot-Subagent-Läufen): `pnpm test:docker:cron-mcp-cleanup` (Skript: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (Installations-Smoke + `/plugin`-Alias + Neustart-Semantik von Claude-Bundles): `pnpm test:docker:plugins` (Skript: `scripts/e2e/plugins-docker.sh`) -- Plugin-Update unverändert Smoke: `pnpm test:docker:plugin-update` (Skript: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Konfigurations-Reload-Metadaten-Smoke: `pnpm test:docker:config-reload` (Skript: `scripts/e2e/config-reload-source-docker.sh`) -- Laufzeit-Dependencies gebündelter Plugins: `pnpm test:docker:bundled-channel-deps` baut standardmäßig ein kleines Docker-Runner-Image, baut und packt OpenClaw einmal auf dem Host und mountet dann dieses Tarball in jedes Linux-Installationsszenario. Verwenden Sie das Image erneut mit `OPENCLAW_SKIP_DOCKER_BUILD=1`, überspringen Sie den Host-Neubau nach einem frischen lokalen Build mit `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` oder zeigen Sie auf ein vorhandenes Tarball mit `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. -- Grenzen Sie Laufzeit-Dependencies gebündelter Plugins während der Iteration ein, indem Sie nicht relevante Szenarien deaktivieren, zum Beispiel: +- Npm-Tarball-Onboarding/Kanal/Agent-Smoke: `pnpm test:docker:npm-onboard-channel-agent` installiert das gepackte OpenClaw-Tarball global in Docker, konfiguriert OpenAI per env-ref-Onboarding sowie standardmäßig Telegram, verifiziert, dass das Aktivieren des Plugins seine Runtime-Abhängigkeiten bei Bedarf installiert, führt doctor aus und führt einen gemockten OpenAI-Agent-Turn aus. Verwende ein vorgebautes Tarball erneut mit `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, überspringe den Host-Rebuild mit `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` oder wechsle den Kanal mit `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Gateway-Netzwerk (zwei Container, WS-Auth + Health): `pnpm test:docker:gateway-network` (Skript: `scripts/e2e/gateway-network-docker.sh`) +- Minimale OpenAI-Responses-`web_search`-Reasoning-Regression: `pnpm test:docker:openai-web-search-minimal` (Skript: `scripts/e2e/openai-web-search-minimal-docker.sh`) führt einen gemockten OpenAI-Server durch Gateway aus, verifiziert, dass `web_search` `reasoning.effort` von `minimal` auf `low` erhöht, erzwingt dann das Zurückweisen des Provider-Schemas und prüft, dass das rohe Detail in den Gateway-Logs erscheint. +- MCP-Kanal-Bridge (geseedetes Gateway + stdio-Bridge + roher Claude-Benachrichtigungsframe-Smoke): `pnpm test:docker:mcp-channels` (Skript: `scripts/e2e/mcp-channels-docker.sh`) +- Pi-Bundle-MCP-Tools (echter stdio-MCP-Server + eingebetteter Pi-Profil-Allow/Deny-Smoke): `pnpm test:docker:pi-bundle-mcp-tools` (Skript: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Cron-/Subagent-MCP-Cleanup (echtes Gateway + Tear-down des stdio-MCP-Child nach isolierten Cron- und One-Shot-Subagent-Läufen): `pnpm test:docker:cron-mcp-cleanup` (Skript: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugins (Installations-Smoke + `/plugin`-Alias + Neustart-Semantik des Claude-Bundles): `pnpm test:docker:plugins` (Skript: `scripts/e2e/plugins-docker.sh`) +- Smoke für unverändertes Plugin-Update: `pnpm test:docker:plugin-update` (Skript: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- Smoke für Konfigurations-Reload-Metadaten: `pnpm test:docker:config-reload` (Skript: `scripts/e2e/config-reload-source-docker.sh`) +- Runtime-Abhängigkeiten gebündelter Plugins: `pnpm test:docker:bundled-channel-deps` baut standardmäßig ein kleines Docker-Runner-Image, baut und packt OpenClaw einmal auf dem Host und mountet dann dieses Tarball in jedes Linux-Installationsszenario. Verwende das Image erneut mit `OPENCLAW_SKIP_DOCKER_BUILD=1`, überspringe den Host-Rebuild nach einem frischen lokalen Build mit `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` oder zeige auf ein bestehendes Tarball mit `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. +- Grenze Runtime-Abhängigkeiten gebündelter Plugins während der Iteration ein, indem du nicht verwandte Szenarien deaktivierst, zum Beispiel: `OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps`. -Um das gemeinsame Built-App-Image manuell vorzubauen und erneut zu verwenden: +Um das gemeinsame Built-App-Image manuell vorzubauen und wiederzuverwenden: ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -Suite-spezifische Image-Overrides wie `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` haben weiterhin Vorrang, wenn sie gesetzt sind. Wenn `OPENCLAW_SKIP_DOCKER_BUILD=1` auf ein entferntes gemeinsames Image zeigt, ziehen die Skripte es, falls es noch nicht lokal vorhanden ist. Die QR- und Installer-Docker-Tests behalten ihre eigenen Dockerfiles, weil sie Paket-/Installationsverhalten statt der gemeinsamen Laufzeit der gebauten App validieren. +Suite-spezifische Image-Overrides wie `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` haben weiterhin Vorrang, wenn sie gesetzt sind. Wenn `OPENCLAW_SKIP_DOCKER_BUILD=1` auf ein entferntes gemeinsames Image zeigt, ziehen die Skripte es, falls es noch nicht lokal vorhanden ist. Die Docker-Tests für QR und Installer behalten ihre eigenen Dockerfiles, weil sie Paket-/Installationsverhalten statt der gemeinsamen Runtime der gebauten App validieren. -Die Live-Modell-Docker-Runner mounten außerdem den aktuellen Checkout schreibgeschützt und -stagen ihn in ein temporäres Arbeitsverzeichnis im Container. Dadurch bleibt das Laufzeit- -Image schlank, während Vitest weiterhin gegen Ihren exakten lokalen Source/Config-Stand läuft. -Der Staging-Schritt überspringt große lokale Caches und App-Build-Ausgaben wie -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` und app-lokale `.build`- oder -Gradle-Ausgabeverzeichnisse, damit Docker-Live-Läufe nicht Minuten mit dem Kopieren -maschinenspezifischer Artefakte verbringen. -Sie setzen außerdem `OPENCLAW_SKIP_CHANNELS=1`, sodass Gateway-Live-Probes im Container -keine echten Kanal-Worker für Telegram/Discord/etc. starten. -`test:docker:live-models` führt weiterhin `pnpm test:live` aus, daher sollten Sie -`OPENCLAW_LIVE_GATEWAY_*` ebenfalls durchreichen, wenn Sie Gateway- -Live-Abdeckung in dieser Docker-Lane eingrenzen oder ausschließen müssen. -`test:docker:openwebui` ist ein Smoke-Test für Kompatibilität auf höherer Ebene: Er startet einen +Die Docker-Runner für Live-Modelle binden außerdem den aktuellen Checkout schreibgeschützt ein und +stagen ihn in ein temporäres Workdir innerhalb des Containers. Dadurch bleibt das Runtime- +Image schlank, während Vitest dennoch gegen deinen exakten lokalen Source/Config läuft. +Der Staging-Schritt überspringt große rein lokale Caches und Build-Ausgaben von Apps wie +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` sowie app-lokale `.build`- oder +Gradle-Ausgabeverzeichnisse, damit Docker-Live-Läufe nicht minutenlang maschinenspezifische +Artefakte kopieren. +Sie setzen außerdem `OPENCLAW_SKIP_CHANNELS=1`, damit Gateway-Live-Probes keine +echten Kanal-Worker für Telegram/Discord/usw. innerhalb des Containers starten. +`test:docker:live-models` führt weiterhin `pnpm test:live` aus; gib daher bei Bedarf auch +`OPENCLAW_LIVE_GATEWAY_*` weiter, wenn du Gateway-Live-Abdeckung in dieser Docker-Lane +eingrenzen oder ausschließen willst. +`test:docker:openwebui` ist ein höherstufiger Kompatibilitäts-Smoke: Er startet einen OpenClaw-Gateway-Container mit aktivierten OpenAI-kompatiblen HTTP-Endpunkten, startet einen angehefteten Open-WebUI-Container gegen dieses Gateway, meldet sich über Open WebUI an, verifiziert, dass `/api/models` `openclaw/default` bereitstellt, und sendet dann eine echte Chat-Anfrage über Open WebUIs Proxy `/api/chat/completions`. -Der erste Lauf kann merklich langsamer sein, weil Docker möglicherweise das -Open-WebUI-Image ziehen muss und Open WebUI eventuell zunächst seinen eigenen Cold-Start abschließen muss. -Diese Lane erwartet einen nutzbaren Live-Modell-Schlüssel, und `OPENCLAW_PROFILE_FILE` -(standardmäßig `~/.profile`) ist der primäre Weg, ihn in Docker-Läufen bereitzustellen. +Der erste Lauf kann deutlich langsamer sein, weil Docker möglicherweise erst das +Open-WebUI-Image ziehen muss und Open WebUI sein eigenes Cold-Start-Setup abschließen muss. +Diese Lane erwartet einen nutzbaren Live-Modell-Key, und `OPENCLAW_PROFILE_FILE` +(standardmäßig `~/.profile`) ist die primäre Methode, ihn in Docker-Läufen bereitzustellen. Erfolgreiche Läufe geben eine kleine JSON-Payload wie `{ "ok": true, "model": "openclaw/default", ... }` aus. -`test:docker:mcp-channels` ist absichtlich deterministisch und benötigt weder ein +`test:docker:mcp-channels` ist absichtlich deterministisch und benötigt kein echtes Telegram-, Discord- oder iMessage-Konto. Es startet einen geseedeten Gateway- Container, startet einen zweiten Container, der `openclaw mcp serve` ausführt, und -verifiziert dann geroutete Konversations-Discovery, Transkript-Lesevorgänge, Attachment-Metadaten, -Verhalten der Live-Ereignisqueue, Routing ausgehender Sendungen und channel- + -berechtigungsbezogene Benachrichtigungen im Claude-Stil über die echte stdio-MCP-Bridge. Die Benachrichtigungsprüfung -untersucht die rohen stdio-MCP-Frames direkt, sodass der Smoke das validiert, was die -Bridge tatsächlich ausgibt, und nicht nur das, was ein bestimmtes Client-SDK zufällig sichtbar macht. +verifiziert dann geroutete Konversationserkennung, Transkript-Lesevorgänge, Attachment-Metadaten, +Verhalten der Live-Event-Queue, Routing ausgehender Sends sowie Kanal- + +Berechtigungsbenachrichtigungen im Claude-Stil über die echte stdio-MCP-Bridge. Die Benachrichtigungsprüfung +untersucht die rohen stdio-MCP-Frames direkt, sodass der Smoke validiert, was die +Bridge tatsächlich aussendet, nicht nur das, was ein bestimmtes Client-SDK zufällig bereitstellt. `test:docker:pi-bundle-mcp-tools` ist deterministisch und benötigt keinen Live- -Modell-Schlüssel. Es baut das Repo-Docker-Image, startet einen echten stdio-MCP-Probe-Server -im Container, materialisiert diesen Server über die eingebettete Pi-Bundle- -MCP-Laufzeit, führt das Tool aus und verifiziert dann, dass `coding` und `messaging` -`bundle-mcp`-Tools behalten, während `minimal` und `tools.deny: ["bundle-mcp"]` sie herausfiltern. +Modell-Key. Es baut das Repo-Docker-Image, startet einen echten stdio-MCP-Probe-Server +innerhalb des Containers, materialisiert diesen Server durch die eingebettete Pi-Bundle- +MCP-Runtime, führt das Tool aus und verifiziert dann, dass `coding` und `messaging` +`bundle-mcp`-Tools beibehalten, während `minimal` und `tools.deny: ["bundle-mcp"]` sie herausfiltern. `test:docker:cron-mcp-cleanup` ist deterministisch und benötigt keinen Live-Modell- -Schlüssel. Es startet ein geseedetes Gateway mit einem echten stdio-MCP-Probe-Server, führt einen -isolierten Cron-Zug und einen `/subagents spawn`-One-Shot-Kindzug aus und verifiziert dann, -dass der MCP-Kindprozess nach jedem Lauf beendet wird. +Key. Es startet ein geseedetes Gateway mit einem echten stdio-MCP-Probe-Server, führt einen +isolierten Cron-Turn und einen One-Shot-Child-Turn mit `/subagents spawn` aus und +verifiziert dann, dass der MCP-Child-Prozess nach jedem Lauf beendet wird. -Manueller ACP-Plain-Language-Thread-Smoke (nicht CI): +Manueller ACP-Thread-Smoke in Klartext (nicht CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Behalten Sie dieses Skript für Regressions-/Debug-Abläufe. Es kann erneut für die Validierung des ACP-Thread-Routings benötigt werden, also löschen Sie es nicht. +- Behalte dieses Skript für Regressions-/Debug-Workflows. Es könnte erneut für die Validierung des ACP-Thread-Routings gebraucht werden, also nicht löschen. -Nützliche Env-Variablen: +Nützliche Umgebungsvariablen: - `OPENCLAW_CONFIG_DIR=...` (Standard: `~/.openclaw`), gemountet nach `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (Standard: `~/.openclaw/workspace`), gemountet nach `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (Standard: `~/.profile`), gemountet nach `/home/node/.profile` und vor dem Ausführen der Tests gesourct -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, um nur Env-Variablen zu verifizieren, die aus `OPENCLAW_PROFILE_FILE` gesourct wurden, unter Verwendung temporärer Config-/Workspace-Verzeichnisse und ohne externe CLI-Auth-Mounts -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (Standard: `~/.cache/openclaw/docker-cli-tools`), gemountet nach `/home/node/.npm-global` für gecachte CLI-Installationen innerhalb von Docker +- `OPENCLAW_PROFILE_FILE=...` (Standard: `~/.profile`), gemountet nach `/home/node/.profile` und vor dem Testlauf gesourced +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, um nur aus `OPENCLAW_PROFILE_FILE` gesourcte Umgebungsvariablen zu verifizieren, mit temporären Config-/Workspace-Verzeichnissen und ohne externe CLI-Auth-Mounts +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (Standard: `~/.cache/openclaw/docker-cli-tools`), gemountet nach `/home/node/.npm-global` für gecachte CLI-Installationen in Docker - Externe CLI-Auth-Verzeichnisse/-Dateien unter `$HOME` werden schreibgeschützt unter `/host-auth...` gemountet und dann vor Testbeginn nach `/home/node/...` kopiert - Standardverzeichnisse: `.minimax` - Standarddateien: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Eingegrenzte Provider-Läufe mounten nur die benötigten Verzeichnisse/Dateien, die aus `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` abgeleitet werden - - Manuelle Überschreibung mit `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` oder einer Komma-Liste wie `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Eingegrenzte Provider-Läufe mounten nur die benötigten Verzeichnisse/Dateien, abgeleitet aus `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Manuell überschreiben mit `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` oder einer Komma-Liste wie `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, um den Lauf einzugrenzen - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, um Provider im Container zu filtern -- `OPENCLAW_SKIP_DOCKER_BUILD=1`, um ein vorhandenes Image `openclaw:local-live` für erneute Läufe zu verwenden, die keinen Neubau benötigen -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um sicherzustellen, dass Anmeldedaten aus dem Profilspeicher kommen (nicht aus Env) +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, um ein vorhandenes Image `openclaw:local-live` für Wiederholungsläufe zu verwenden, die keinen Rebuild brauchen +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um sicherzustellen, dass Credentials aus dem Profile-Store kommen (nicht aus der Umgebung) - `OPENCLAW_OPENWEBUI_MODEL=...`, um das vom Gateway für den Open-WebUI-Smoke bereitgestellte Modell auszuwählen -- `OPENCLAW_OPENWEBUI_PROMPT=...`, um den vom Open-WebUI-Smoke verwendeten Nonce-Prüf-Prompt zu überschreiben +- `OPENCLAW_OPENWEBUI_PROMPT=...`, um den für den Open-WebUI-Smoke verwendeten Prompt zur Nonce-Prüfung zu überschreiben - `OPENWEBUI_IMAGE=...`, um das angeheftete Open-WebUI-Image-Tag zu überschreiben ## Docs-Sanity -Führen Sie nach Bearbeitungen an der Dokumentation die Docs-Prüfungen aus: `pnpm check:docs`. -Führen Sie die vollständige Mintlify-Anchor-Validierung aus, wenn Sie zusätzlich In-Page-Heading-Prüfungen benötigen: `pnpm docs:check-links:anchors`. +Führe nach Änderungen an der Dokumentation die Docs-Checks aus: `pnpm check:docs`. +Führe die vollständige Mintlify-Anker-Validierung aus, wenn du zusätzlich Prüfungen für Überschriften auf der Seite brauchst: `pnpm docs:check-links:anchors`. ## Offline-Regression (CI-sicher) -Dies sind Regressionen in der „echten Pipeline“ ohne echte Provider: +Dies sind Regressionen für „echte Pipelines“ ohne echte Provider: -- Gateway-Tool-Aufrufe (gemocktes OpenAI, echtes Gateway + Agent-Loop): `src/gateway/gateway.test.ts` (Fall: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Gateway-Assistent (WS `wizard.start`/`wizard.next`, schreibt Konfiguration + erzwungene Auth): `src/gateway/gateway.test.ts` (Fall: "runs wizard over ws and writes auth token config") +- Gateway-Tool-Calling (gemocktes OpenAI, echtes Gateway + Agent-Loop): `src/gateway/gateway.test.ts` (Fall: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Gateway-Assistent (WS `wizard.start`/`wizard.next`, erzwingt Schreiben von Config + Auth): `src/gateway/gateway.test.ts` (Fall: "runs wizard over ws and writes auth token config") -## Evaluierungen zur Agent-Zuverlässigkeit (Skills) +## Agent-Zuverlässigkeits-Evals (Skills) -Wir haben bereits einige CI-sichere Tests, die sich wie „Evaluierungen zur Agent-Zuverlässigkeit“ verhalten: +Wir haben bereits einige CI-sichere Tests, die sich wie „Agent-Zuverlässigkeits-Evals“ verhalten: -- Gemockte Tool-Aufrufe durch den echten Gateway- + Agent-Loop (`src/gateway/gateway.test.ts`). -- End-to-End-Abläufe des Assistenten, die Session-Wiring und Konfigurationseffekte validieren (`src/gateway/gateway.test.ts`). +- Gemocktes Tool-Calling durch das echte Gateway + Agent-Loop (`src/gateway/gateway.test.ts`). +- End-to-End-Assistenten-Flows, die Session-Verdrahtung und Konfigurationseffekte validieren (`src/gateway/gateway.test.ts`). Was für Skills noch fehlt (siehe [Skills](/de/tools/skills)): -- **Entscheidungsverhalten:** Wenn Skills im Prompt aufgelistet sind, wählt der Agent die richtige Skill aus (oder vermeidet irrelevante)? -- **Compliance:** Liest der Agent `SKILL.md` vor der Verwendung und befolgt er die erforderlichen Schritte/Args? -- **Workflow-Verträge:** Multi-Turn-Szenarien, die Tool-Reihenfolge, Übernahme des Sitzungsverlaufs und Sandbox-Grenzen validieren. +- **Entscheidungsfindung:** Wählt der Agent, wenn Skills im Prompt aufgeführt sind, den richtigen Skill (oder vermeidet irrelevante)? +- **Compliance:** Liest der Agent `SKILL.md` vor der Verwendung und befolgt erforderliche Schritte/Args? +- **Workflow-Verträge:** Multi-Turn-Szenarien, die Tool-Reihenfolge, Übernahme des Session-Verlaufs und Sandbox-Grenzen prüfen. -Zukünftige Evaluierungen sollten zunächst deterministisch bleiben: +Zukünftige Evals sollten zuerst deterministisch bleiben: -- Ein Szenario-Runner mit Mock-Providern, um Tool-Aufrufe + Reihenfolge, Reads von Skill-Dateien und Session-Wiring zu validieren. -- Eine kleine Suite von skill-fokussierten Szenarien (verwenden vs. vermeiden, Gating, Prompt-Injection). -- Optionale Live-Evaluierungen (Opt-in, per Env gegated) erst, nachdem die CI-sichere Suite vorhanden ist. +- Ein Szenario-Runner mit Mock-Providern, der Tool-Calls + Reihenfolge, Skill-Datei-Lesevorgänge und Session-Verdrahtung prüft. +- Eine kleine Suite skill-fokussierter Szenarien (verwenden vs. vermeiden, Gating, Prompt-Injection). +- Optionale Live-Evals (Opt-in, env-gesteuert) erst, nachdem die CI-sichere Suite vorhanden ist. -## Vertragstests (Plugin- und Kanal-Shape) +## Vertragstests (Plugin- und Kanalform) -Vertragstests verifizieren, dass jedes registrierte Plugin und jeder Kanal seinem -Interface-Vertrag entspricht. Sie iterieren über alle erkannten Plugins und führen eine Suite von -Shape- und Verhaltensvalidierungen aus. Die Standard-Unit-Lane `pnpm test` -überspringt diese gemeinsam genutzten Seam- und Smoke-Dateien absichtlich; führen Sie die Vertragsbefehle explizit aus, -wenn Sie gemeinsame Kanal- oder Provider-Oberflächen berühren. +Vertragstests prüfen, dass jedes registrierte Plugin und jeder Kanal seinem +Schnittstellenvertrag entspricht. Sie iterieren über alle entdeckten Plugins und führen eine Suite von +Assertions zur Form und zum Verhalten aus. Die standardmäßige Unit-Lane `pnpm test` +überspringt diese gemeinsam genutzten Seam- und Smoke-Dateien absichtlich; führe die Vertragsbefehle explizit +aus, wenn du gemeinsame Kanal- oder Provider-Oberflächen änderst. ### Befehle @@ -1076,55 +1079,55 @@ wenn Sie gemeinsame Kanal- oder Provider-Oberflächen berühren. ### Kanalverträge -Befinden sich unter `src/channels/plugins/contracts/*.contract.test.ts`: +Zu finden unter `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Grundlegende Plugin-Shape (ID, Name, Fähigkeiten) +- **plugin** - Grundlegende Plugin-Form (ID, Name, Capabilities) - **setup** - Vertrag des Setup-Assistenten -- **session-binding** - Verhalten der Sitzungsbindung -- **outbound-payload** - Struktur der Nachrichten-Payload +- **session-binding** - Verhalten der Session-Bindung +- **outbound-payload** - Struktur der Message-Payload - **inbound** - Verarbeitung eingehender Nachrichten - **actions** - Handler für Kanalaktionen - **threading** - Umgang mit Thread-IDs -- **directory** - Verzeichnis-/Roster-API -- **group-policy** - Durchsetzung der Gruppenrichtlinie +- **directory** - API für Verzeichnis/Roster +- **group-policy** - Durchsetzung von Gruppenrichtlinien ### Provider-Status-Verträge -Befinden sich unter `src/plugins/contracts/*.contract.test.ts`. +Zu finden unter `src/plugins/contracts/*.contract.test.ts`. - **status** - Kanal-Status-Probes -- **registry** - Shape der Plugin-Registry +- **registry** - Form der Plugin-Registry ### Provider-Verträge -Befinden sich unter `src/plugins/contracts/*.contract.test.ts`: +Zu finden unter `src/plugins/contracts/*.contract.test.ts`: - **auth** - Vertrag des Auth-Flows -- **auth-choice** - Auth-Auswahl/-Selektion +- **auth-choice** - Auswahl/Selektion von Auth - **catalog** - API des Modellkatalogs -- **discovery** - Plugin-Discovery +- **discovery** - Plugin-Erkennung - **loader** - Plugin-Laden -- **runtime** - Provider-Laufzeit -- **shape** - Plugin-Shape/Interface +- **runtime** - Provider-Runtime +- **shape** - Plugin-Form/Schnittstelle - **wizard** - Setup-Assistent ### Wann ausführen -- Nach Änderungen an Plugin-SDK-Exporten oder Subpfaden +- Nach Änderungen an Plugin-SDK-Exporten oder Subpaths - Nach dem Hinzufügen oder Ändern eines Kanal- oder Provider-Plugins -- Nach Refactorings von Plugin-Registrierung oder Discovery +- Nach Refactorings an Plugin-Registrierung oder -Erkennung -Vertragstests laufen in CI und erfordern keine echten API-Schlüssel. +Vertragstests laufen in CI und benötigen keine echten API-Keys. -## Regressionen hinzufügen (Leitfaden) +## Regressionen hinzufügen (Leitlinien) -Wenn Sie ein Provider-/Modellproblem beheben, das in Live entdeckt wurde: +Wenn du ein in Live entdecktes Provider-/Modellproblem behebst: -- Fügen Sie nach Möglichkeit eine CI-sichere Regression hinzu (Mock/Stub-Provider oder die exakte Transformation der Request-Shape erfassen) -- Wenn es inhärent nur live testbar ist (Rate Limits, Auth-Richtlinien), halten Sie den Live-Test eng und per Env-Variablen opt-in -- Bevorzugen Sie die kleinste Ebene, die den Fehler erkennt: - - Fehler bei Provider-Request-Konvertierung/-Replay → Test direkter Modelle - - Fehler in Gateway-Sitzung/Verlauf/Tool-Pipeline → Gateway-Live-Smoke oder CI-sicherer Gateway-Mock-Test -- Guardrail für SecretRef-Traversal: - - `src/secrets/exec-secret-ref-id-parity.test.ts` leitet aus Registry-Metadaten (`listSecretTargetRegistryEntries()`) ein gesampeltes Ziel pro SecretRef-Klasse ab und validiert dann, dass Traversal-Segment-Exec-IDs abgelehnt werden. - - Wenn Sie in `src/secrets/target-registry-data.ts` eine neue SecretRef-Zielfamilie mit `includeInPlan` hinzufügen, aktualisieren Sie `classifyTargetClass` in diesem Test. Der Test schlägt absichtlich bei nicht klassifizierten Ziel-IDs fehl, damit neue Klassen nicht stillschweigend übersprungen werden. +- Füge wenn möglich eine CI-sichere Regression hinzu (Mock/Stub-Provider oder erfasse die exakte Transformation der Request-Form) +- Wenn es von Natur aus nur live auftritt (Rate Limits, Auth-Richtlinien), halte den Live-Test eng eingegrenzt und per Umgebungsvariablen auf Opt-in +- Ziele bevorzugt auf die kleinste Ebene, die den Fehler erkennt: + - Fehler bei Provider-Request-Konvertierung/-Replay → Test für direkte Modelle + - Fehler in Gateway-Session-/Verlauf-/Tool-Pipeline → Gateway-Live-Smoke oder CI-sicherer Gateway-Mock-Test +- Schutzmaßnahme für SecretRef-Traversal: + - `src/secrets/exec-secret-ref-id-parity.test.ts` leitet ein gesampeltes Ziel pro SecretRef-Klasse aus Registry-Metadaten ab (`listSecretTargetRegistryEntries()`) und prüft dann, dass Traversal-Segment-Exec-IDs zurückgewiesen werden. + - Wenn du eine neue SecretRef-Zielfamilie `includeInPlan` in `src/secrets/target-registry-data.ts` hinzufügst, aktualisiere `classifyTargetClass` in diesem Test. Der Test schlägt absichtlich bei nicht klassifizierten Ziel-IDs fehl, damit neue Klassen nicht stillschweigend übersprungen werden können.