diff --git a/docs/de/channels/telegram.md b/docs/de/channels/telegram.md index 09c732427..92b78eb4b 100644 --- a/docs/de/channels/telegram.md +++ b/docs/de/channels/telegram.md @@ -1,42 +1,42 @@ --- read_when: - Arbeiten an Telegram-Funktionen oder Webhooks -summary: Supportstatus, Funktionen und Konfiguration für Telegram-Bots +summary: Supportstatus, Funktionen und Konfiguration für den Telegram-Bot title: Telegram x-i18n: - generated_at: "2026-05-03T21:27:14Z" + generated_at: "2026-05-04T06:41:15Z" model: gpt-5.5 provider: openai - source_hash: 528ace9dae29eda22f98cc1436ec16146eb9d83edc73aa6db1ab8283f4f873c0 + source_hash: c7f49db5f3fe8fd724e53a2ae3d226446f248bf9d021fcc01c1cf816649381d2 source_path: channels/telegram.md workflow: 16 --- -Produktionsreif für Bot-DMs und Gruppen über grammY. Long Polling ist der Standardmodus; Webhook-Modus ist optional. +Produktionsreif für Bot-DMs und Gruppen über grammY. Long Polling ist der Standardmodus; der Webhook-Modus ist optional. - - Die standardmäßige DM-Richtlinie für Telegram ist Kopplung. + + Die Standard-DM-Richtlinie für Telegram ist Pairing. - + Kanalübergreifende Diagnosen und Reparatur-Playbooks. - - Vollständige Kanal-Konfigurationsmuster und Beispiele. + + Vollständige Channel-Konfigurationsmuster und Beispiele. -## Schnelleinrichtung +## Schnelle Einrichtung - - Öffnen Sie Telegram und chatten Sie mit **@BotFather** (bestätigen Sie, dass der Handle exakt `@BotFather` lautet). + + Öffnen Sie Telegram und chatten Sie mit **@BotFather** (stellen Sie sicher, dass der Handle exakt `@BotFather` lautet). - Führen Sie `/newbot` aus, folgen Sie den Aufforderungen und speichern Sie das Token. + Führen Sie `/newbot` aus, folgen Sie den Eingabeaufforderungen und speichern Sie das Token. - + ```json5 { @@ -52,11 +52,11 @@ Produktionsreif für Bot-DMs und Gruppen über grammY. Long Polling ist der Stan ``` Env-Fallback: `TELEGRAM_BOT_TOKEN=...` (nur Standardkonto). - Telegram verwendet **nicht** `openclaw channels login telegram`; konfigurieren Sie das Token in Konfiguration/Env und starten Sie dann den Gateway. + Telegram verwendet **nicht** `openclaw channels login telegram`; konfigurieren Sie das Token in der Konfiguration/Umgebung und starten Sie dann den Gateway. - + ```bash openclaw gateway @@ -64,12 +64,12 @@ openclaw pairing list telegram openclaw pairing approve telegram ``` - Kopplungscodes laufen nach 1 Stunde ab. + Pairing-Codes laufen nach 1 Stunde ab. - - Fügen Sie den Bot zu Ihrer Gruppe hinzu und setzen Sie dann `channels.telegram.groups` und `groupPolicy` passend zu Ihrem Zugriffsmodell. + + Fügen Sie den Bot Ihrer Gruppe hinzu und setzen Sie dann `channels.telegram.groups` und `groupPolicy` passend zu Ihrem Zugriffsmodell. @@ -77,31 +77,31 @@ openclaw pairing approve telegram Die Reihenfolge der Token-Auflösung ist kontobewusst. In der Praxis haben Konfigurationswerte Vorrang vor dem Env-Fallback, und `TELEGRAM_BOT_TOKEN` gilt nur für das Standardkonto. -## Einstellungen auf Telegram-Seite +## Telegram-seitige Einstellungen - - Telegram-Bots verwenden standardmäßig den **Datenschutzmodus**, der einschränkt, welche Gruppennachrichten sie empfangen. + + Telegram-Bots verwenden standardmäßig den **Privatsphäre-Modus**, der begrenzt, welche Gruppennachrichten sie empfangen. - Wenn der Bot alle Gruppennachrichten sehen muss, entweder: + Wenn der Bot alle Gruppennachrichten sehen muss, können Sie entweder: - - deaktivieren Sie den Datenschutzmodus über `/setprivacy`, oder - - machen Sie den Bot zu einem Gruppenadministrator. + - den Privatsphäre-Modus über `/setprivacy` deaktivieren oder + - den Bot zum Gruppenadministrator machen. - Wenn Sie den Datenschutzmodus umschalten, entfernen Sie den Bot in jeder Gruppe und fügen Sie ihn erneut hinzu, damit Telegram die Änderung anwendet. + Wenn Sie den Privatsphäre-Modus umschalten, entfernen Sie den Bot aus jeder Gruppe und fügen Sie ihn erneut hinzu, damit Telegram die Änderung übernimmt. - - Der Administratorstatus wird in den Telegram-Gruppeneinstellungen gesteuert. + + Der Adminstatus wird in den Telegram-Gruppeneinstellungen gesteuert. - Admin-Bots empfangen alle Gruppennachrichten, was für dauerhaft aktives Gruppenverhalten nützlich ist. + Admin-Bots empfangen alle Gruppennachrichten, was für dauerhaft aktive Gruppenfunktionen nützlich ist. - + - - `/setjoingroups`, um das Hinzufügen zu Gruppen zu erlauben/zu verweigern + - `/setjoingroups`, um Gruppenhinzufügungen zu erlauben/zu verweigern - `/setprivacy` für das Verhalten der Gruppensichtbarkeit @@ -110,7 +110,7 @@ Die Reihenfolge der Token-Auflösung ist kontobewusst. In der Praxis haben Konfi ## Zugriffskontrolle und Aktivierung - + `channels.telegram.dmPolicy` steuert den Zugriff auf Direktnachrichten: - `pairing` (Standard) @@ -118,27 +118,27 @@ Die Reihenfolge der Token-Auflösung ist kontobewusst. In der Praxis haben Konfi - `open` (erfordert, dass `allowFrom` `"*"` enthält) - `disabled` - `dmPolicy: "open"` mit `allowFrom: ["*"]` erlaubt jedem Telegram-Konto, das den Bot-Benutzernamen findet oder errät, dem Bot Befehle zu geben. Verwenden Sie dies nur für absichtlich öffentliche Bots mit stark eingeschränkten Tools; Bots mit einem einzigen Besitzer sollten `allowlist` mit numerischen Benutzer-IDs verwenden. + `dmPolicy: "open"` mit `allowFrom: ["*"]` erlaubt jedem Telegram-Konto, das den Bot-Benutzernamen findet oder errät, dem Bot Befehle zu geben. Verwenden Sie dies nur für bewusst öffentliche Bots mit stark eingeschränkten Tools; Bots mit einem einzelnen Besitzer sollten `allowlist` mit numerischen Benutzer-IDs verwenden. `channels.telegram.allowFrom` akzeptiert numerische Telegram-Benutzer-IDs. Präfixe `telegram:` / `tg:` werden akzeptiert und normalisiert. - In Konfigurationen mit mehreren Konten wird ein restriktives `channels.telegram.allowFrom` auf oberster Ebene als Sicherheitsgrenze behandelt: `allowFrom: ["*"]`-Einträge auf Kontoebene machen dieses Konto nicht öffentlich, es sei denn, die effektive Konto-Allowlist enthält nach dem Zusammenführen weiterhin einen expliziten Platzhalter. + In Multi-Konto-Konfigurationen wird ein restriktives `channels.telegram.allowFrom` auf oberster Ebene als Sicherheitsgrenze behandelt: `allowFrom: ["*"]`-Einträge auf Kontoebene machen dieses Konto nicht öffentlich, es sei denn, die effektive Konto-Allowlist enthält nach dem Zusammenführen weiterhin einen expliziten Platzhalter. `dmPolicy: "allowlist"` mit leerem `allowFrom` blockiert alle DMs und wird von der Konfigurationsvalidierung abgelehnt. Die Einrichtung fragt nur nach numerischen Benutzer-IDs. - Wenn Sie ein Upgrade durchgeführt haben und Ihre Konfiguration `@username`-Allowlist-Einträge enthält, führen Sie `openclaw doctor --fix` aus, um sie aufzulösen (Best-Effort; erfordert ein Telegram-Bot-Token). - Wenn Sie sich zuvor auf Allowlist-Dateien im Kopplungsspeicher verlassen haben, kann `openclaw doctor --fix` Einträge in Allowlist-Flows nach `channels.telegram.allowFrom` wiederherstellen (zum Beispiel wenn `dmPolicy: "allowlist"` noch keine expliziten IDs hat). + Wenn Sie ein Upgrade durchgeführt haben und Ihre Konfiguration `@username`-Allowlist-Einträge enthält, führen Sie `openclaw doctor --fix` aus, um sie aufzulösen (nach bestem Bemühen; erfordert ein Telegram-Bot-Token). + Wenn Sie sich zuvor auf Pairing-Store-Allowlist-Dateien verlassen haben, kann `openclaw doctor --fix` Einträge in Allowlist-Flows in `channels.telegram.allowFrom` wiederherstellen (zum Beispiel, wenn `dmPolicy: "allowlist"` noch keine expliziten IDs hat). - Für Bots mit einem einzigen Besitzer sollten Sie `dmPolicy: "allowlist"` mit expliziten numerischen `allowFrom`-IDs bevorzugen, damit die Zugriffsrichtlinie dauerhaft in der Konfiguration liegt (statt von früheren Kopplungsgenehmigungen abzuhängen). + Für Bots mit einem einzelnen Besitzer bevorzugen Sie `dmPolicy: "allowlist"` mit expliziten numerischen `allowFrom`-IDs, damit die Zugriffsrichtlinie dauerhaft in der Konfiguration liegt (statt von früheren Pairing-Genehmigungen abzuhängen). - Häufige Verwirrung: DM-Kopplungsgenehmigung bedeutet nicht „dieser Absender ist überall autorisiert“. - Kopplung gewährt DM-Zugriff. Wenn noch kein Befehlsbesitzer existiert, setzt die erste genehmigte Kopplung außerdem `commands.ownerAllowFrom`, sodass Besitzerbefehle und Exec-Genehmigungen ein explizites Operatorkonto haben. - Die Autorisierung von Gruppenabsendern kommt weiterhin aus expliziten Konfigurations-Allowlists. - Wenn Sie möchten, dass „ich einmal autorisiert bin und sowohl DMs als auch Gruppenbefehle funktionieren“, tragen Sie Ihre numerische Telegram-Benutzer-ID in `channels.telegram.allowFrom` ein; stellen Sie für Besitzerbefehle sicher, dass `commands.ownerAllowFrom` `telegram:` enthält. + Häufige Verwirrung: DM-Pairing-Genehmigung bedeutet nicht „dieser Absender ist überall autorisiert“. + Pairing gewährt DM-Zugriff. Wenn noch kein Befehlsbesitzer existiert, setzt das erste genehmigte Pairing außerdem `commands.ownerAllowFrom`, damit Besitzer-only-Befehle und Ausführungsgenehmigungen ein explizites Operatorkonto haben. + Die Autorisierung von Gruppensendern kommt weiterhin aus expliziten Konfigurations-Allowlists. + Wenn Sie möchten: „Ich bin einmal autorisiert und sowohl DMs als auch Gruppenbefehle funktionieren“, setzen Sie Ihre numerische Telegram-Benutzer-ID in `channels.telegram.allowFrom`; stellen Sie für Besitzer-only-Befehle sicher, dass `commands.ownerAllowFrom` `telegram:` enthält. ### Ihre Telegram-Benutzer-ID finden Sicherer (kein Drittanbieter-Bot): - 1. Senden Sie Ihrem Bot eine DM. + 1. Schreiben Sie Ihrem Bot eine DM. 2. Führen Sie `openclaw logs --follow` aus. 3. Lesen Sie `from.id`. @@ -152,31 +152,31 @@ curl "https://api.telegram.org/bot/getUpdates" - - Zwei Steuerungen gelten gemeinsam: + + Zwei Steuerungen gelten zusammen: 1. **Welche Gruppen erlaubt sind** (`channels.telegram.groups`) - keine `groups`-Konfiguration: - mit `groupPolicy: "open"`: Jede Gruppe kann Gruppen-ID-Prüfungen bestehen - - mit `groupPolicy: "allowlist"` (Standard): Gruppen werden blockiert, bis Sie `groups`-Einträge (oder `"*"`) hinzufügen - - `groups` konfiguriert: fungiert als Allowlist (explizite IDs oder `"*"`) + - mit `groupPolicy: "allowlist"` (Standard): Gruppen werden blockiert, bis Sie `groups`-Einträge hinzufügen (oder `"*"`) + - `groups` konfiguriert: wirkt als Allowlist (explizite IDs oder `"*"`) 2. **Welche Absender in Gruppen erlaubt sind** (`channels.telegram.groupPolicy`) - `open` - `allowlist` (Standard) - `disabled` - `groupAllowFrom` wird für das Filtern von Gruppenabsendern verwendet. Wenn nicht gesetzt, fällt Telegram auf `allowFrom` zurück. + `groupAllowFrom` wird für die Gruppensender-Filterung verwendet. Wenn es nicht gesetzt ist, fällt Telegram auf `allowFrom` zurück. `groupAllowFrom`-Einträge sollten numerische Telegram-Benutzer-IDs sein (Präfixe `telegram:` / `tg:` werden normalisiert). - Tragen Sie keine Telegram-Gruppen- oder Supergruppen-Chat-IDs in `groupAllowFrom` ein. Negative Chat-IDs gehören unter `channels.telegram.groups`. - Nicht numerische Einträge werden für die Absenderautorisierung ignoriert. - Sicherheitsgrenze (`2026.2.25+`): Gruppenabsender-Auth erbt **keine** DM-Genehmigungen aus dem Kopplungsspeicher. - Kopplung bleibt DM-only. Legen Sie für Gruppen `groupAllowFrom` oder `allowFrom` pro Gruppe/pro Thema fest. - Wenn `groupAllowFrom` nicht gesetzt ist, fällt Telegram auf die Konfiguration `allowFrom` zurück, nicht auf den Kopplungsspeicher. - Praktisches Muster für Bots mit einem einzigen Besitzer: Setzen Sie Ihre Benutzer-ID in `channels.telegram.allowFrom`, lassen Sie `groupAllowFrom` nicht gesetzt und erlauben Sie die Zielgruppen unter `channels.telegram.groups`. - Laufzeithinweis: Wenn `channels.telegram` vollständig fehlt, verwendet die Runtime standardmäßig fail-closed `groupPolicy="allowlist"`, sofern `channels.defaults.groupPolicy` nicht explizit gesetzt ist. + Setzen Sie keine Telegram-Gruppen- oder Supergruppen-Chat-IDs in `groupAllowFrom`. Negative Chat-IDs gehören unter `channels.telegram.groups`. + Nicht numerische Einträge werden für die Senderautorisierung ignoriert. + Sicherheitsgrenze (`2026.2.25+`): Gruppensender-Auth erbt **keine** DM-Pairing-Store-Genehmigungen. + Pairing bleibt DM-only. Legen Sie für Gruppen `groupAllowFrom` oder `allowFrom` pro Gruppe/pro Thema fest. + Wenn `groupAllowFrom` nicht gesetzt ist, fällt Telegram auf die Konfiguration `allowFrom` zurück, nicht auf den Pairing-Store. + Praktisches Muster für Bots mit einem einzelnen Besitzer: Setzen Sie Ihre Benutzer-ID in `channels.telegram.allowFrom`, lassen Sie `groupAllowFrom` unset und erlauben Sie die Zielgruppen unter `channels.telegram.groups`. + Laufzeithinweis: Wenn `channels.telegram` vollständig fehlt, verwendet die Laufzeit standardmäßig fail-closed `groupPolicy="allowlist"`, sofern `channels.defaults.groupPolicy` nicht explizit gesetzt ist. - Beispiel: beliebiges Mitglied in einer bestimmten Gruppe erlauben: + Beispiel: Jedes Mitglied in einer bestimmten Gruppe erlauben: ```json5 { @@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Beispiel: nur bestimmte Benutzer innerhalb einer bestimmten Gruppe erlauben: + Beispiel: Nur bestimmte Benutzer innerhalb einer bestimmten Gruppe erlauben: ```json5 { @@ -213,30 +213,30 @@ curl "https://api.telegram.org/bot/getUpdates" Häufiger Fehler: `groupAllowFrom` ist keine Telegram-Gruppen-Allowlist. - - Tragen Sie negative Telegram-Gruppen- oder Supergruppen-Chat-IDs wie `-1001234567890` unter `channels.telegram.groups` ein. - - Tragen Sie Telegram-Benutzer-IDs wie `8734062810` unter `groupAllowFrom` ein, wenn Sie einschränken möchten, welche Personen innerhalb einer erlaubten Gruppe den Bot auslösen können. - - Verwenden Sie `groupAllowFrom: ["*"]` nur, wenn jedes Mitglied einer erlaubten Gruppe mit dem Bot sprechen können soll. + - Setzen Sie negative Telegram-Gruppen- oder Supergruppen-Chat-IDs wie `-1001234567890` unter `channels.telegram.groups`. + - Setzen Sie Telegram-Benutzer-IDs wie `8734062810` unter `groupAllowFrom`, wenn Sie begrenzen möchten, welche Personen innerhalb einer erlaubten Gruppe den Bot auslösen können. + - Verwenden Sie `groupAllowFrom: ["*"]` nur, wenn jedes Mitglied einer erlaubten Gruppe mit dem Bot sprechen dürfen soll. - + Gruppenantworten erfordern standardmäßig eine Erwähnung. Die Erwähnung kann stammen von: - - nativer `@botusername`-Erwähnung, oder + - nativer `@botusername`-Erwähnung oder - Erwähnungsmustern in: - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` - Umschalter für Befehle auf Sitzungsebene: + Befehlsumschaltungen auf Sitzungsebene: - `/activation always` - `/activation mention` - Diese aktualisieren nur den Sitzungszustand. Verwenden Sie Konfiguration für Persistenz. + Diese aktualisieren nur den Sitzungszustand. Verwenden Sie die Konfiguration für Persistenz. Beispiel für persistente Konfiguration: @@ -254,9 +254,9 @@ curl "https://api.telegram.org/bot/getUpdates" Gruppen-Chat-ID abrufen: - - leiten Sie eine Gruppennachricht an `@userinfobot` / `@getidsbot` weiter + - Leiten Sie eine Gruppennachricht an `@userinfobot` / `@getidsbot` weiter - oder lesen Sie `chat.id` aus `openclaw logs --follow` - - oder prüfen Sie Bot-API `getUpdates` + - oder prüfen Sie Bot API `getUpdates` @@ -264,32 +264,32 @@ curl "https://api.telegram.org/bot/getUpdates" ## Laufzeitverhalten - Telegram gehört dem Gateway-Prozess. -- Routing ist deterministisch: Telegram-Eingangsnachrichten werden an Telegram beantwortet (das Modell wählt keine Kanäle aus). -- Eingehende Nachrichten werden in den gemeinsamen Kanalumschlag mit Antwortmetadaten und Medienplatzhaltern normalisiert. -- Gruppensitzungen werden nach Gruppen-ID isoliert. Forumthemen hängen `:topic:` an, damit Themen isoliert bleiben. -- DM-Nachrichten können `message_thread_id` tragen; OpenClaw bewahrt die Thread-ID für Antworten auf, hält DMs aber standardmäßig in der flachen Sitzung. Konfigurieren Sie `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct..threadReplies: "inbound"`, `requireTopic: true` oder eine passende Themenkonfiguration, wenn Sie DM-Themensitzungsisolation absichtlich möchten. -- Long Polling verwendet den grammY-Runner mit Sequenzierung pro Chat/pro Thread. Die allgemeine Runner-Sink-Parallelität verwendet `agents.defaults.maxConcurrent`. -- Long Polling wird innerhalb jedes Gateway-Prozesses geschützt, sodass immer nur ein aktiver Poller ein Bot-Token gleichzeitig verwenden kann. Wenn Sie dennoch `getUpdates`-409-Konflikte sehen, verwendet wahrscheinlich ein anderer OpenClaw-Gateway, ein Skript oder ein externer Poller dasselbe Token. -- Long-Polling-Watchdog-Neustarts werden standardmäßig nach 120 Sekunden ohne abgeschlossene `getUpdates`-Liveness ausgelöst. Erhöhen Sie `channels.telegram.pollingStallThresholdMs` nur, wenn Ihre Bereitstellung während lang laufender Arbeit weiterhin fälschliche Polling-Stall-Neustarts sieht. Der Wert ist in Millisekunden angegeben und von `30000` bis `600000` erlaubt; Überschreibungen pro Konto werden unterstützt. -- Die Telegram Bot API hat keine Unterstützung für Lesebestätigungen (`sendReadReceipts` gilt nicht). +- Routing ist deterministisch: Eingehende Telegram-Antworten gehen zurück an Telegram (das Modell wählt keine Channels). +- Eingehende Nachrichten werden in den gemeinsamen Channel-Umschlag mit Antwortmetadaten und Medienplatzhaltern normalisiert. +- Gruppensitzungen werden nach Gruppen-ID isoliert. Forum-Themen hängen `:topic:` an, um Themen isoliert zu halten. +- DM-Nachrichten können `message_thread_id` enthalten; OpenClaw bewahrt die Thread-ID für Antworten, hält DMs standardmäßig aber in der flachen Sitzung. Konfigurieren Sie `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct..threadReplies: "inbound"`, `requireTopic: true` oder eine passende Themenkonfiguration, wenn Sie absichtlich DM-Themensitzungsisolation möchten. +- Long Polling verwendet grammY runner mit Sequenzierung pro Chat/pro Thread. Die Gesamt-Runner-Sink-Nebenläufigkeit verwendet `agents.defaults.maxConcurrent`. +- Long Polling wird innerhalb jedes Gateway-Prozesses geschützt, sodass jeweils nur ein aktiver Poller ein Bot-Token verwenden kann. Wenn Sie weiterhin `getUpdates`-409-Konflikte sehen, verwendet wahrscheinlich ein anderer OpenClaw-Gateway, ein Skript oder ein externer Poller dasselbe Token. +- Neustarts des Long-Polling-Watchdogs werden standardmäßig nach 120 Sekunden ohne abgeschlossene `getUpdates`-Liveness ausgelöst. Erhöhen Sie `channels.telegram.pollingStallThresholdMs` nur, wenn Ihre Bereitstellung während lang laufender Arbeit weiterhin falsche Polling-Stall-Neustarts sieht. Der Wert ist in Millisekunden und von `30000` bis `600000` erlaubt; Überschreibungen pro Konto werden unterstützt. +- Die Telegram Bot API unterstützt keine Lesebestätigungen (`sendReadReceipts` gilt nicht). ## Funktionsreferenz - + OpenClaw kann Teilantworten in Echtzeit streamen: - - direkte Chats: Vorschaunachricht + `editMessageText` + - Direktchats: Vorschaunachricht + `editMessageText` - Gruppen/Themen: Vorschaunachricht + `editMessageText` - Voraussetzung: + Anforderung: - `channels.telegram.streaming` ist `off | partial | block | progress` (Standard: `partial`) - - `progress` behält einen bearbeitbaren Statusentwurf und aktualisiert ihn mit Tool-Fortschritt bis zur finalen Zustellung - - `streaming.preview.toolProgress` steuert, ob Tool-/Fortschrittsaktualisierungen dieselbe bearbeitete Vorschaunachricht wiederverwenden (Standard: `true`, wenn Vorschau-Streaming aktiv ist) - - veraltete Werte für `channels.telegram.streamMode` und boolesche `streaming`-Werte werden erkannt; führen Sie `openclaw doctor --fix` aus, um sie nach `channels.telegram.streaming.mode` zu migrieren + - `progress` behält einen editierbaren Statusentwurf und aktualisiert ihn mit Tool-Fortschritt bis zur finalen Zustellung + - `streaming.preview.toolProgress` steuert, ob Tool-/Fortschrittsupdates dieselbe bearbeitete Vorschaunachricht wiederverwenden (Standard: `true`, wenn Vorschau-Streaming aktiv ist) + - Legacy-Werte `channels.telegram.streamMode` und boolesche `streaming`-Werte werden erkannt; führen Sie `openclaw doctor --fix` aus, um sie nach `channels.telegram.streaming.mode` zu migrieren - Tool-Fortschritts-Vorschauaktualisierungen sind die kurzen Statuszeilen, die angezeigt werden, während Tools laufen, zum Beispiel Befehlsausführung, Dateilesevorgänge, Planungsaktualisierungen oder Patch-Zusammenfassungen. Telegram lässt diese standardmäßig aktiviert, passend zum veröffentlichten OpenClaw-Verhalten ab `v2026.4.22`. Um die bearbeitete Vorschau für Antworttext beizubehalten, aber Tool-Fortschrittszeilen auszublenden, setzen Sie: + Vorschau-Updates für Tool-Fortschritt sind die kurzen Statuszeilen, die angezeigt werden, während Tools laufen, zum Beispiel Befehlsausführung, Dateilesevorgänge, Planungsupdates oder Patch-Zusammenfassungen. Telegram lässt diese standardmäßig aktiviert, um dem veröffentlichten OpenClaw-Verhalten ab `v2026.4.22` und später zu entsprechen. Um die bearbeitete Vorschau für Antworttext beizubehalten, aber Tool-Fortschrittszeilen auszublenden, setzen Sie: ```json { @@ -306,25 +306,26 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Verwenden Sie `streaming.mode: "off"` nur, wenn Sie ausschließlich die finale Zustellung wünschen: Telegram-Vorschau-Bearbeitungen werden deaktiviert und allgemeines Tool-/Fortschrittsrauschen wird unterdrückt, anstatt als eigenständige Statusmeldungen gesendet zu werden. Genehmigungsaufforderungen, Medien-Payloads und Fehler laufen weiterhin über die normale finale Zustellung. Verwenden Sie `streaming.preview.toolProgress: false`, wenn Sie nur Antwortvorschau-Bearbeitungen beibehalten möchten, während die Tool-Fortschrittsstatuszeilen ausgeblendet werden. + Verwenden Sie `streaming.mode: "off"` nur, wenn Sie ausschließlich finale Auslieferung wünschen: Telegram-Vorschau-Edits werden deaktiviert, und generisches Tool-/Fortschrittsrauschen wird unterdrückt, statt als eigenständige Statusmeldungen gesendet zu werden. Genehmigungsabfragen, Medien-Payloads und Fehler werden weiterhin über die normale finale Auslieferung geleitet. Verwenden Sie `streaming.preview.toolProgress: false`, wenn Sie nur Antwortvorschau-Edits beibehalten und gleichzeitig die Tool-Fortschrittsstatuszeilen ausblenden möchten. - Telegram-Antworten auf ausgewählte Zitate sind die Ausnahme. Wenn `replyToMode` `"first"`, `"all"` oder `"batched"` ist und die eingehende Nachricht ausgewählten Zitattext enthält, sendet OpenClaw die finale Antwort über den nativen Zitat-Antwort-Pfad von Telegram, anstatt die Antwortvorschau zu bearbeiten. Daher kann `streaming.preview.toolProgress` die kurzen Statuszeilen für diesen Durchlauf nicht anzeigen. Antworten auf die aktuelle Nachricht ohne ausgewählten Zitattext behalten das Vorschau-Streaming weiterhin bei. Setzen Sie `replyToMode: "off"`, wenn die Sichtbarkeit des Tool-Fortschritts wichtiger ist als native Zitatantworten, oder setzen Sie `streaming.preview.toolProgress: false`, um den Kompromiss anzuerkennen. + Telegram-Antworten auf ausgewählte Zitate sind die Ausnahme. Wenn `replyToMode` `"first"`, `"all"` oder `"batched"` ist und die eingehende Nachricht ausgewählten Zitattext enthält, sendet OpenClaw die finale Antwort über Telegrams nativen Zitat-Antwortpfad, statt die Antwortvorschau zu bearbeiten. Daher kann `streaming.preview.toolProgress` die kurzen Statuszeilen für diesen Durchlauf nicht anzeigen. Antworten auf aktuelle Nachrichten ohne ausgewählten Zitattext behalten weiterhin Preview Streaming. Setzen Sie `replyToMode: "off"`, wenn die Sichtbarkeit des Tool-Fortschritts wichtiger ist als native Zitatantworten, oder setzen Sie `streaming.preview.toolProgress: false`, um den Kompromiss bewusst zu akzeptieren. Für reine Textantworten: - - kurze DM-/Gruppen-/Themenvorschauen: OpenClaw behält dieselbe Vorschaunachricht bei und führt eine finale Bearbeitung an Ort und Stelle aus, sofern nach dem Erscheinen der Vorschau keine sichtbare Nicht-Vorschau-Nachricht gesendet wurde - - Vorschauen, auf die sichtbare Nicht-Vorschau-Ausgaben folgen: OpenClaw sendet die abgeschlossene Antwort als neue finale Nachricht und räumt die ältere Vorschau auf, sodass die finale Antwort nach der Zwischenausgabe erscheint - - Vorschauen, die älter als etwa eine Minute sind: OpenClaw sendet die abgeschlossene Antwort als neue finale Nachricht und räumt anschließend die Vorschau auf, sodass der sichtbare Zeitstempel von Telegram die Abschlusszeit statt der Erstellungszeit der Vorschau widerspiegelt + - kurze DM-/Gruppen-/Themenvorschauen: OpenClaw behält dieselbe Vorschaunachricht bei und führt eine finale Bearbeitung an Ort und Stelle aus, sofern nach dem Erscheinen der Vorschau keine sichtbare Nicht-Vorschaunachricht gesendet wurde + - Vorschauen, gefolgt von sichtbarer Nicht-Vorschauausgabe: OpenClaw sendet die fertige Antwort als neue finale Nachricht und räumt die ältere Vorschau auf, sodass die finale Antwort nach der Zwischenausgabe erscheint + - Vorschauen, die älter als etwa eine Minute sind: OpenClaw sendet die fertige Antwort als neue finale Nachricht und räumt anschließend die Vorschau auf, sodass Telegrams sichtbarer Zeitstempel die Abschlusszeit statt der Erstellungszeit der Vorschau widerspiegelt - Bei komplexen Antworten (zum Beispiel Medien-Payloads) fällt OpenClaw auf die normale finale Zustellung zurück und räumt anschließend die Vorschaunachricht auf. + Bei komplexen Antworten (zum Beispiel Medien-Payloads) fällt OpenClaw auf die normale finale Auslieferung zurück und räumt anschließend die Vorschaunachricht auf. - Vorschau-Streaming ist vom Block-Streaming getrennt. Wenn Block-Streaming für Telegram explizit aktiviert ist, überspringt OpenClaw den Vorschau-Stream, um doppeltes Streaming zu vermeiden. + Preview Streaming ist getrennt von Block Streaming. Wenn Block Streaming für Telegram ausdrücklich aktiviert ist, überspringt OpenClaw den Vorschaustream, um doppeltes Streaming zu vermeiden. - Nur-Telegram-Reasoning-Stream: + Reiner Telegram-Reasoning-Stream: - `/reasoning stream` sendet Reasoning während der Generierung an die Live-Vorschau + - die Reasoning-Vorschau wird nach der finalen Auslieferung gelöscht; verwenden Sie `/reasoning on`, wenn Reasoning sichtbar bleiben soll - die finale Antwort wird ohne Reasoning-Text gesendet @@ -332,8 +333,8 @@ curl "https://api.telegram.org/bot/getUpdates" Ausgehender Text verwendet Telegram `parse_mode: "HTML"`. - - Markdown-ähnlicher Text wird in Telegram-sicheres HTML gerendert. - - Rohes Modell-HTML wird escaped, um Telegram-Parse-Fehler zu reduzieren. + - Markdown-ähnlicher Text wird zu Telegram-sicherem HTML gerendert. + - Rohes Modell-HTML wird escaped, um Telegram-Parsefehler zu reduzieren. - Wenn Telegram geparstes HTML ablehnt, versucht OpenClaw es erneut als Klartext. Linkvorschauen sind standardmäßig aktiviert und können mit `channels.telegram.linkPreview: false` deaktiviert werden. @@ -341,13 +342,13 @@ curl "https://api.telegram.org/bot/getUpdates" - Die Registrierung des Telegram-Befehlsmenüs wird beim Start mit `setMyCommands` gehandhabt. + Die Registrierung des Telegram-Befehlsmenüs wird beim Start mit `setMyCommands` verarbeitet. Standardwerte für native Befehle: - `commands.native: "auto"` aktiviert native Befehle für Telegram - Benutzerdefinierte Befehlsmenüeinträge hinzufügen: + Fügen Sie benutzerdefinierte Befehlsmenüeinträge hinzu: ```json5 { @@ -364,7 +365,7 @@ curl "https://api.telegram.org/bot/getUpdates" Regeln: - - Namen werden normalisiert (führendes `/` entfernen, Kleinbuchstaben) + - Namen werden normalisiert (führendes `/` entfernen, Kleinschreibung) - gültiges Muster: `a-z`, `0-9`, `_`, Länge `1..32` - benutzerdefinierte Befehle können native Befehle nicht überschreiben - Konflikte/Duplikate werden übersprungen und protokolliert @@ -372,38 +373,38 @@ curl "https://api.telegram.org/bot/getUpdates" Hinweise: - benutzerdefinierte Befehle sind nur Menüeinträge; sie implementieren kein Verhalten automatisch - - Plugin-/Skill-Befehle können beim Eintippen weiterhin funktionieren, auch wenn sie nicht im Telegram-Menü angezeigt werden + - Plugin-/Skills-Befehle können weiterhin funktionieren, wenn sie eingegeben werden, auch wenn sie nicht im Telegram-Menü angezeigt werden - Wenn native Befehle deaktiviert sind, werden integrierte Befehle entfernt. Benutzerdefinierte/Plugin-Befehle können weiterhin registriert werden, wenn sie konfiguriert sind. + Wenn native Befehle deaktiviert sind, werden integrierte Befehle entfernt. Benutzerdefinierte/Plugin-Befehle können sich weiterhin registrieren, wenn sie konfiguriert sind. Häufige Einrichtungsfehler: - - `setMyCommands failed` mit `BOT_COMMANDS_TOO_MUCH` bedeutet, dass das Telegram-Menü nach dem Kürzen immer noch überlaufen ist; reduzieren Sie Plugin-/Skill-/benutzerdefinierte Befehle oder deaktivieren Sie `channels.telegram.commands.native`. - - Wenn `deleteWebhook`, `deleteMyCommands` oder `setMyCommands` mit `404: Not Found` fehlschlagen, während direkte Bot-API-curl-Befehle funktionieren, kann das bedeuten, dass `channels.telegram.apiRoot` auf den vollständigen `/bot`-Endpunkt gesetzt wurde. `apiRoot` darf nur der Bot-API-Stamm sein, und `openclaw doctor --fix` entfernt ein versehentliches abschließendes `/bot`. - - `getMe returned 401` bedeutet, dass Telegram den konfigurierten Bot-Token abgelehnt hat. Aktualisieren Sie `botToken`, `tokenFile` oder `TELEGRAM_BOT_TOKEN` mit dem aktuellen BotFather-Token; OpenClaw stoppt vor dem Polling, sodass dies nicht als Webhook-Aufräumfehler gemeldet wird. - - `setMyCommands failed` mit Netzwerk-/Fetch-Fehlern bedeutet in der Regel, dass ausgehendes DNS/HTTPS zu `api.telegram.org` blockiert ist. + - `setMyCommands failed` mit `BOT_COMMANDS_TOO_MUCH` bedeutet, dass das Telegram-Menü nach dem Kürzen immer noch überlaufen ist; reduzieren Sie Plugin-/Skills-/benutzerdefinierte Befehle oder deaktivieren Sie `channels.telegram.commands.native`. + - Wenn `deleteWebhook`, `deleteMyCommands` oder `setMyCommands` mit `404: Not Found` fehlschlägt, während direkte Bot-API-curl-Befehle funktionieren, kann das bedeuten, dass `channels.telegram.apiRoot` auf den vollständigen `/bot`-Endpunkt gesetzt wurde. `apiRoot` darf nur der Bot-API-Root sein, und `openclaw doctor --fix` entfernt ein versehentlich angehängtes `/bot`. + - `getMe returned 401` bedeutet, dass Telegram das konfigurierte Bot-Token abgelehnt hat. Aktualisieren Sie `botToken`, `tokenFile` oder `TELEGRAM_BOT_TOKEN` mit dem aktuellen BotFather-Token; OpenClaw stoppt vor dem Polling, sodass dies nicht als Webhook-Aufräumfehler gemeldet wird. + - `setMyCommands failed` mit Netzwerk-/Fetch-Fehlern bedeutet normalerweise, dass ausgehendes DNS/HTTPS zu `api.telegram.org` blockiert ist. - ### Befehle zur Gerätekopplung (`device-pair`-Plugin) + ### Gerätekopplungsbefehle (`device-pair`-Plugin) Wenn das `device-pair`-Plugin installiert ist: - 1. `/pair` generiert Einrichtungscode - 2. Code in die iOS-App einfügen + 1. `/pair` erzeugt Einrichtungscode + 2. Code in der iOS-App einfügen 3. `/pair pending` listet ausstehende Anfragen auf (einschließlich Rolle/Scopes) 4. Anfrage genehmigen: - - `/pair approve ` für explizite Genehmigung - - `/pair approve`, wenn nur eine Anfrage aussteht + - `/pair approve ` für ausdrückliche Genehmigung + - `/pair approve`, wenn es nur eine ausstehende Anfrage gibt - `/pair approve latest` für die neueste - Der Einrichtungscode enthält einen kurzlebigen Bootstrap-Token. Die integrierte Bootstrap-Übergabe hält den primären Node-Token bei `scopes: []`; jeder übergebene Operator-Token bleibt auf `operator.approvals`, `operator.read`, `operator.talk.secrets` und `operator.write` begrenzt. Bootstrap-Scope-Prüfungen sind rollenpräfixiert, sodass diese Operator-Allowlist nur Operator-Anfragen erfüllt; Nicht-Operator-Rollen benötigen weiterhin Scopes unter ihrem eigenen Rollenpräfix. + Der Einrichtungscode enthält ein kurzlebiges Bootstrap-Token. Die integrierte Bootstrap-Übergabe hält das primäre Node-Token bei `scopes: []`; jedes übergebene Operator-Token bleibt auf `operator.approvals`, `operator.read`, `operator.talk.secrets` und `operator.write` begrenzt. Bootstrap-Scope-Prüfungen sind rollenpräfixiert, sodass diese Operator-Allowlist nur Operator-Anfragen erfüllt; Nicht-Operator-Rollen benötigen weiterhin Scopes unter ihrem eigenen Rollenpräfix. - Wenn ein Gerät es mit geänderten Auth-Details erneut versucht (zum Beispiel Rolle/Scopes/öffentlicher Schlüssel), wird die vorherige ausstehende Anfrage ersetzt und die neue Anfrage verwendet eine andere `requestId`. Führen Sie `/pair pending` vor der Genehmigung erneut aus. + Wenn ein Gerät es mit geänderten Authentifizierungsdetails erneut versucht (zum Beispiel Rolle/Scopes/öffentlicher Schlüssel), wird die vorherige ausstehende Anfrage ersetzt und die neue Anfrage verwendet eine andere `requestId`. Führen Sie `/pair pending` vor der Genehmigung erneut aus. Weitere Details: [Kopplung](/de/channels/pairing#pair-via-telegram-recommended-for-ios). - + Inline-Tastatur-Scope konfigurieren: ```json5 @@ -444,7 +445,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `all` - `allowlist` (Standard) - Legacy-`capabilities: ["inlineButtons"]` wird `inlineButtons: "all"` zugeordnet. + Veraltetes `capabilities: ["inlineButtons"]` wird auf `inlineButtons: "all"` abgebildet. Beispiel für eine Nachrichtenaktion: @@ -464,7 +465,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Callback-Klicks werden als Text an den Agent weitergegeben: + Callback-Klicks werden als Text an den Agenten übergeben: `callback_data: ` @@ -478,7 +479,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `editMessage` (`chatId`, `messageId`, `content`) - `createForumTopic` (`chatId`, `name`, optional `iconColor`, `iconCustomEmojiId`) - Kanal-Nachrichtenaktionen stellen ergonomische Aliase bereit (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). + Channel-Nachrichtenaktionen stellen ergonomische Aliase bereit (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). Gating-Steuerungen: @@ -488,7 +489,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.actions.sticker` (Standard: deaktiviert) Hinweis: `edit` und `topic-create` sind derzeit standardmäßig aktiviert und haben keine separaten `channels.telegram.actions.*`-Schalter. - Laufzeit-Sendevorgänge verwenden den aktiven Konfigurations-/Secrets-Snapshot (Start/Reload), sodass Aktionspfade keine ad-hoc SecretRef-Neuauflösung pro Sendevorgang durchführen. + Laufzeit-Sendevorgänge verwenden den aktiven Konfigurations-/Secrets-Snapshot (Start/Reload), sodass Aktionspfade keine Ad-hoc-Neuauflösung von SecretRef pro Sendevorgang durchführen. Semantik zum Entfernen von Reaktionen: [/tools/reactions](/de/tools/reactions) @@ -500,35 +501,35 @@ curl "https://api.telegram.org/bot/getUpdates" - `[[reply_to_current]]` antwortet auf die auslösende Nachricht - `[[reply_to:]]` antwortet auf eine bestimmte Telegram-Nachrichten-ID - `channels.telegram.replyToMode` steuert die Behandlung: + `channels.telegram.replyToMode` steuert die Verarbeitung: - `off` (Standard) - `first` - `all` - Wenn Antwort-Threading aktiviert ist und der ursprüngliche Telegram-Text oder die ursprüngliche Beschriftung verfügbar ist, fügt OpenClaw automatisch einen nativen Telegram-Zitatauszug ein. Telegram begrenzt nativen Zitattext auf 1024 UTF-16-Codeeinheiten, sodass längere Nachrichten ab dem Anfang zitiert werden und auf eine einfache Antwort zurückfallen, wenn Telegram das Zitat ablehnt. + Wenn Antwort-Threading aktiviert ist und der ursprüngliche Telegram-Text oder die Beschriftung verfügbar ist, fügt OpenClaw automatisch einen nativen Telegram-Zitatauszug ein. Telegram begrenzt nativen Zitattext auf 1024 UTF-16-Codeeinheiten, sodass längere Nachrichten vom Anfang an zitiert werden und auf eine einfache Antwort zurückfallen, wenn Telegram das Zitat ablehnt. Hinweis: `off` deaktiviert implizites Antwort-Threading. Explizite `[[reply_to_*]]`-Tags werden weiterhin berücksichtigt. - + Forum-Supergruppen: - - Themenschlüssel für Sitzungen hängen `:topic:` an + - Themenschlüssel für Sessions hängen `:topic:` an - Antworten und Tippen zielen auf den Themen-Thread - - Pfad zur Themenkonfiguration: + - Pfad der Themenkonfiguration: `channels.telegram.groups..topics.` Sonderfall allgemeines Thema (`threadId=1`): - - Nachrichtensendungen lassen `message_thread_id` aus (Telegram lehnt `sendMessage(...thread_id=1)` ab) + - Nachrichtensendungen lassen `message_thread_id` weg (Telegram lehnt `sendMessage(...thread_id=1)` ab) - Tippaktionen enthalten weiterhin `message_thread_id` Themenvererbung: Themeneinträge erben Gruppeneinstellungen, sofern sie nicht überschrieben werden (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). - `agentId` ist nur themenspezifisch und erbt nicht von Gruppenstandards. + `agentId` ist themenspezifisch und erbt nicht von Gruppenvorgaben. - **Agent-Routing pro Thema**: Jedes Thema kann durch Setzen von `agentId` in der Themenkonfiguration an einen anderen Agent weitergeleitet werden. Dadurch erhält jedes Thema seinen eigenen isolierten Arbeitsbereich, Speicher und seine eigene Sitzung. Beispiel: + **Agent-Routing pro Thema**: Jedes Thema kann durch Setzen von `agentId` in der Themenkonfiguration an einen anderen Agenten weitergeleitet werden. Dadurch erhält jedes Thema seinen eigenen isolierten Workspace, Speicher und seine eigene Session. Beispiel: ```json5 { @@ -548,13 +549,13 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Jedes Thema hat dann seinen eigenen Sitzungsschlüssel: `agent:zu:telegram:group:-1001234567890:topic:3` + Danach hat jedes Thema seinen eigenen Session-Schlüssel: `agent:zu:telegram:group:-1001234567890:topic:3` - **Persistente ACP-Themenbindung**: Forenthemen können ACP-Harness-Sitzungen über typisierte ACP-Bindings auf oberster Ebene anheften (`bindings[]` mit `type: "acp"` und `match.channel: "telegram"`, `peer.kind: "group"` sowie einer themenqualifizierten ID wie `-1001234567890:topic:42`). Derzeit auf Forenthemen in Gruppen/Supergruppen beschränkt. Siehe [ACP-Agenten](/de/tools/acp-agents). + **Persistente ACP-Themenbindung**: Forumsthemen können ACP-Harness-Sessions über typisierte ACP-Bindings auf oberster Ebene pinnen (`bindings[]` mit `type: "acp"` und `match.channel: "telegram"`, `peer.kind: "group"` sowie einer themenqualifizierten ID wie `-1001234567890:topic:42`). Derzeit auf Forumsthemen in Gruppen/Supergruppen begrenzt. Siehe [ACP-Agenten](/de/tools/acp-agents). - **Thread-gebundener ACP-Spawn aus dem Chat**: `/acp spawn --thread here|auto` bindet das aktuelle Thema an eine neue ACP-Sitzung; Folgebeiträge werden direkt dorthin weitergeleitet. OpenClaw pinnt die Spawn-Bestätigung im Thema. Erfordert, dass `channels.telegram.threadBindings.spawnSessions` aktiviert bleibt (Standard: `true`). + **Thread-gebundener ACP-Spawn aus dem Chat**: `/acp spawn --thread here|auto` bindet das aktuelle Thema an eine neue ACP-Session; Folgeanfragen werden direkt dorthin geleitet. OpenClaw pinnt die Spawn-Bestätigung im Thema. Erfordert, dass `channels.telegram.threadBindings.spawnSessions` aktiviert bleibt (Standard: `true`). - Der Template-Kontext stellt `MessageThreadId` und `IsForum` bereit. DM-Chats mit `message_thread_id` behalten standardmäßig DM-Routing und Antwortmetadaten auf flachen Sitzungen bei; thread-aware Sitzungsschlüssel werden nur verwendet, wenn sie mit `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` oder einer passenden Themenkonfiguration konfiguriert sind. Verwenden Sie `channels.telegram.dm.threadReplies` auf oberster Ebene für den Kontostandard oder `direct..threadReplies` für eine DM. + Der Template-Kontext stellt `MessageThreadId` und `IsForum` bereit. DM-Chats mit `message_thread_id` behalten standardmäßig DM-Routing und Antwortmetadaten auf flachen Sessions; sie verwenden thread-bewusste Session-Schlüssel nur, wenn sie mit `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` oder einer passenden Themenkonfiguration konfiguriert sind. Verwenden Sie `channels.telegram.dm.threadReplies` auf oberster Ebene für die Kontovorgabe oder `direct..threadReplies` für eine einzelne DM. @@ -563,11 +564,11 @@ curl "https://api.telegram.org/bot/getUpdates" Telegram unterscheidet Sprachnotizen von Audiodateien. - - Standard: Audiodatei-Verhalten - - Tag `[[audio_as_voice]]` in der Agent-Antwort, um das Senden als Sprachnotiz zu erzwingen - - eingehende Transkripte von Sprachnotizen werden im Agent-Kontext als maschinell generierter, - nicht vertrauenswürdiger Text gerahmt; die Mention-Erkennung verwendet weiterhin das rohe - Transkript, sodass Mention-gesteuerte Sprachnachrichten weiter funktionieren. + - Standard: Audiodateiverhalten + - Tag `[[audio_as_voice]]` in der Agentenantwort, um das Senden als Sprachnotiz zu erzwingen + - Eingehende Sprachnotiz-Transkripte werden im Agentenkontext als maschinell erzeugter, + nicht vertrauenswürdiger Text gerahmt; Erwähnungserkennung verwendet weiterhin das rohe + Transkript, sodass erwähnungsgesteuerte Sprachnachrichten weiterhin funktionieren. Beispiel für eine Nachrichtenaktion: @@ -583,7 +584,7 @@ curl "https://api.telegram.org/bot/getUpdates" ### Videonachrichten - Telegram unterscheidet zwischen Videodateien und Videonachrichten. + Telegram unterscheidet Videodateien von Videonotizen. Beispiel für eine Nachrichtenaktion: @@ -597,11 +598,11 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Videonachrichten unterstützen keine Beschriftungen; angegebener Nachrichtentext wird separat gesendet. + Videonotizen unterstützen keine Bildunterschriften; bereitgestellter Nachrichtentext wird separat gesendet. ### Sticker - Verarbeitung eingehender Sticker: + Behandlung eingehender Sticker: - statisches WEBP: heruntergeladen und verarbeitet (Platzhalter ``) - animiertes TGS: übersprungen @@ -673,11 +674,11 @@ curl "https://api.telegram.org/bot/getUpdates" Hinweise: - - `own` bedeutet nur Benutzerreaktionen auf vom Bot gesendete Nachrichten (Best Effort über den Cache gesendeter Nachrichten). - - Reaktionsereignisse beachten weiterhin die Telegram-Zugriffskontrollen (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); nicht autorisierte Absender werden verworfen. + - `own` bedeutet nur Benutzerreaktionen auf vom Bot gesendete Nachrichten (Best-Effort über den Cache gesendeter Nachrichten). + - Reaktionsereignisse beachten weiterhin die Telegram-Zugriffssteuerungen (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); nicht autorisierte Absender werden verworfen. - Telegram stellt in Reaktions-Updates keine Thread-IDs bereit. - - Nicht-Forum-Gruppen werden an die Gruppenchat-Sitzung weitergeleitet - - Forum-Gruppen werden an die allgemeine Gruppen-Themensitzung (`:topic:1`) weitergeleitet, nicht an das exakte Ursprungsthema + - Nicht-Forum-Gruppen werden an die Gruppenchat-Sitzung geleitet + - Forum-Gruppen werden an die allgemeine Themen-Sitzung der Gruppe (`:topic:1`) geleitet, nicht an das exakte ursprüngliche Thema `allowed_updates` für Polling/Webhook enthält automatisch `message_reaction`. @@ -691,19 +692,19 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - Fallback auf Emoji der Agentenidentität (`agents.list[].identity.emoji`, andernfalls "👀") + - Fallback auf das Emoji der Agent-Identität (`agents.list[].identity.emoji`, andernfalls "👀") Hinweise: - Telegram erwartet Unicode-Emoji (zum Beispiel "👀"). - - Verwenden Sie `""`, um die Reaktion für einen Channel oder ein Konto zu deaktivieren. + - Verwenden Sie `""`, um die Reaktion für einen Kanal oder ein Konto zu deaktivieren. - Schreibvorgänge für die Channel-Konfiguration sind standardmäßig aktiviert (`configWrites !== false`). + Schreibvorgänge für die Kanal-Konfiguration sind standardmäßig aktiviert (`configWrites !== false`). - Durch Telegram ausgelöste Schreibvorgänge umfassen: + Von Telegram ausgelöste Schreibvorgänge umfassen: - Gruppenmigrationsereignisse (`migrate_to_chat_id`) zum Aktualisieren von `channels.telegram.groups` - `/config set` und `/config unset` (erfordert aktivierte Befehle) @@ -722,30 +723,30 @@ curl "https://api.telegram.org/bot/getUpdates" - - Standard ist Long Polling. Für den Webhook-Modus setzen Sie `channels.telegram.webhookUrl` und `channels.telegram.webhookSecret`; optional `webhookPath`, `webhookHost`, `webhookPort` (Standardwerte `/telegram-webhook`, `127.0.0.1`, `8787`). + + Standard ist Long Polling. Legen Sie für den Webhook-Modus `channels.telegram.webhookUrl` und `channels.telegram.webhookSecret` fest; optional `webhookPath`, `webhookHost`, `webhookPort` (Standardwerte `/telegram-webhook`, `127.0.0.1`, `8787`). - Der lokale Listener bindet an `127.0.0.1:8787`. Für öffentlichen Eingang setzen Sie entweder einen Reverse Proxy vor den lokalen Port oder setzen Sie bewusst `webhookHost: "0.0.0.0"`. + Der lokale Listener bindet an `127.0.0.1:8787`. Für öffentlichen Ingress setzen Sie entweder einen Reverse-Proxy vor den lokalen Port oder legen `webhookHost: "0.0.0.0"` bewusst fest. Der Webhook-Modus validiert Request-Guards, das geheime Telegram-Token und den JSON-Body, bevor `200` an Telegram zurückgegeben wird. - OpenClaw verarbeitet das Update anschließend asynchron über dieselben Bot-Lanes pro Chat/pro Thema wie beim Long Polling, sodass langsame Agentenrunden das Zustellungs-ACK von Telegram nicht blockieren. + OpenClaw verarbeitet das Update dann asynchron über dieselben Bot-Lanes pro Chat/pro Thema wie beim Long Polling, sodass langsame Agent-Durchläufe das Zustellungs-ACK von Telegram nicht blockieren. - `channels.telegram.textChunkLimit` ist standardmäßig 4000. - - `channels.telegram.chunkMode="newline"` bevorzugt Absatzgrenzen (Leerzeilen) vor der Längenaufteilung. + - `channels.telegram.chunkMode="newline"` bevorzugt Absatzgrenzen (Leerzeilen) vor der Aufteilung nach Länge. - `channels.telegram.mediaMaxMb` (Standard 100) begrenzt die Größe eingehender und ausgehender Telegram-Medien. - - `channels.telegram.mediaGroupFlushMs` (Standard 500) steuert, wie lange Telegram-Alben/Mediengruppen gepuffert werden, bevor OpenClaw sie als eine eingehende Nachricht ausliefert. Erhöhen Sie den Wert, wenn Albumteile verspätet eintreffen; verringern Sie ihn, um die Antwortlatenz für Alben zu reduzieren. + - `channels.telegram.mediaGroupFlushMs` (Standard 500) steuert, wie lange Telegram-Alben/Mediengruppen gepuffert werden, bevor OpenClaw sie als eine eingehende Nachricht weitergibt. Erhöhen Sie den Wert, wenn Albumteile spät eintreffen; verringern Sie ihn, um die Antwortlatenz für Alben zu reduzieren. - `channels.telegram.timeoutSeconds` überschreibt das Timeout des Telegram-API-Clients (wenn nicht gesetzt, gilt der grammY-Standard). Bot-Clients begrenzen konfigurierte Werte unterhalb des 60-Sekunden-Request-Guards für ausgehende Text-/Typing-Anfragen, damit grammY die sichtbare Antwortzustellung nicht abbricht, bevor OpenClaws Transport-Guard und Fallback ausgeführt werden können. Long Polling verwendet weiterhin einen 45-Sekunden-Request-Guard für `getUpdates`, damit inaktive Polls nicht unbegrenzt aufgegeben werden. - - `channels.telegram.pollingStallThresholdMs` ist standardmäßig `120000`; stimmen Sie den Wert nur bei falsch positiven Polling-Stall-Neustarts zwischen `30000` und `600000` ab. - - Der Gruppen-Kontextverlauf verwendet `channels.telegram.historyLimit` oder `messages.groupChat.historyLimit` (Standard 50); `0` deaktiviert ihn. - - Zusätzlicher Kontext für Antworten/Zitate/Weiterleitungen wird derzeit unverändert übergeben. - - Telegram-Allowlists steuern hauptsächlich, wer den Agenten auslösen kann, und sind keine vollständige Redaktionsgrenze für ergänzenden Kontext. - - Steuerelemente für den DM-Verlauf: + - `channels.telegram.pollingStallThresholdMs` ist standardmäßig `120000`; passen Sie den Wert nur bei falsch-positiven Polling-Stall-Neustarts zwischen `30000` und `600000` an. + - Der Verlauf des Gruppenkontexts verwendet `channels.telegram.historyLimit` oder `messages.groupChat.historyLimit` (Standard 50); `0` deaktiviert ihn. + - Zusätzlicher Kontext für Antwort/Zitat/Weiterleitung wird derzeit so weitergegeben, wie er empfangen wurde. + - Telegram-Zulassungslisten steuern primär, wer den Agent auslösen kann, nicht eine vollständige Redaktionsgrenze für Zusatzkontext. + - Steuerungen für den DM-Verlauf: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - Die Konfiguration `channels.telegram.retry` gilt für Telegram-Sendehelfer (CLI/Tools/Aktionen) bei wiederherstellbaren ausgehenden API-Fehlern. Die Zustellung der finalen eingehenden Antwort verwendet bei Telegram-Fehlern vor dem Verbindungsaufbau ebenfalls einen begrenzten Safe-Send-Retry, versucht jedoch keine mehrdeutigen Netzwerkhüllen nach dem Senden erneut, die sichtbare Nachrichten duplizieren könnten. + - Die Konfiguration `channels.telegram.retry` gilt für Telegram-Sendehelfer (CLI/Tools/Aktionen) bei behebbaren ausgehenden API-Fehlern. Die Zustellung der endgültigen eingehenden Antwort verwendet ebenfalls eine begrenzte Safe-Send-Wiederholung bei Telegram-Fehlern vor der Verbindung, wiederholt jedoch keine mehrdeutigen Netzwerk-Hüllen nach dem Senden, die sichtbare Nachrichten duplizieren könnten. Das CLI-Sendeziel kann eine numerische Chat-ID oder ein Benutzername sein: @@ -764,7 +765,7 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-duration-seconds 300 --poll-public ``` - Nur für Telegram geltende Poll-Flags: + Nur-Telegram-Poll-Flags: - `--poll-duration-seconds` (5-600) - `--poll-anonymous` @@ -777,15 +778,15 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - `--pin` oder `--delivery '{"pin":true}'`, um angeheftete Zustellung anzufordern, wenn der Bot in diesem Chat anheften kann - `--force-document`, um ausgehende Bilder und GIFs als Dokumente statt als komprimierte Foto- oder animierte Medien-Uploads zu senden - Aktionssteuerung: + Aktions-Gating: - `channels.telegram.actions.sendMessage=false` deaktiviert ausgehende Telegram-Nachrichten, einschließlich Polls - - `channels.telegram.actions.poll=false` deaktiviert die Erstellung von Telegram-Polls, während reguläre Sendevorgänge aktiviert bleiben + - `channels.telegram.actions.poll=false` deaktiviert das Erstellen von Telegram-Polls, während reguläre Sends aktiviert bleiben - Telegram unterstützt Exec-Genehmigungen in Genehmiger-DMs und kann Prompts optional im Ursprungschat oder -thema posten. Genehmiger müssen numerische Telegram-Benutzer-IDs sein. + Telegram unterstützt Exec-Genehmigungen in Genehmiger-DMs und kann Prompts optional im ursprünglichen Chat oder Thema posten. Genehmiger müssen numerische Telegram-Benutzer-IDs sein. Konfigurationspfad: @@ -794,25 +795,25 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - `channels.telegram.execApprovals.target`: `dm` (Standard) | `channel` | `both` - `agentFilter`, `sessionFilter` - `channels.telegram.allowFrom`, `groupAllowFrom` und `defaultTo` steuern, wer mit dem Bot sprechen kann und wohin er normale Antworten sendet. Sie machen niemanden zu einem Exec-Genehmiger. Das erste genehmigte DM-Pairing bootstrapt `commands.ownerAllowFrom`, wenn noch kein Befehlsbesitzer existiert, sodass die Einrichtung mit einem Besitzer weiterhin funktioniert, ohne IDs unter `execApprovals.approvers` zu duplizieren. + `channels.telegram.allowFrom`, `groupAllowFrom` und `defaultTo` steuern, wer mit dem Bot sprechen kann und wohin er normale Antworten sendet. Sie machen niemanden zu einem Exec-Genehmiger. Die erste genehmigte DM-Kopplung bootstrapt `commands.ownerAllowFrom`, wenn noch kein Befehlsbesitzer vorhanden ist, sodass die Einrichtung mit einem Besitzer weiterhin funktioniert, ohne IDs unter `execApprovals.approvers` zu duplizieren. - Channel-Zustellung zeigt den Befehlstext im Chat; aktivieren Sie `channel` oder `both` nur in vertrauenswürdigen Gruppen/Themen. Wenn der Prompt in einem Forum-Thema landet, bewahrt OpenClaw das Thema für den Genehmigungs-Prompt und die Folgeantwort. Exec-Genehmigungen laufen standardmäßig nach 30 Minuten ab. + Die Kanalzustellung zeigt den Befehlstext im Chat; aktivieren Sie `channel` oder `both` nur in vertrauenswürdigen Gruppen/Themen. Wenn der Prompt in einem Forum-Thema landet, bewahrt OpenClaw das Thema für den Genehmigungs-Prompt und die Folgeaktion. Exec-Genehmigungen laufen standardmäßig nach 30 Minuten ab. - Inline-Genehmigungsbuttons erfordern außerdem, dass `channels.telegram.capabilities.inlineButtons` die Zieloberfläche (`dm`, `group` oder `all`) erlaubt. Genehmigungs-IDs mit Präfix `plugin:` werden über Plugin-Genehmigungen aufgelöst; andere werden zuerst über Exec-Genehmigungen aufgelöst. + Inline-Genehmigungsbuttons erfordern außerdem, dass `channels.telegram.capabilities.inlineButtons` die Zieloberfläche (`dm`, `group` oder `all`) erlaubt. Genehmigungs-IDs mit dem Präfix `plugin:` werden über Plugin-Genehmigungen aufgelöst; andere werden zuerst über Exec-Genehmigungen aufgelöst. Siehe [Exec-Genehmigungen](/de/tools/exec-approvals). -## Steuerelemente für Fehlerantworten +## Steuerung von Fehlerantworten -Wenn beim Agenten ein Zustellungs- oder Provider-Fehler auftritt, kann Telegram entweder mit dem Fehlertext antworten oder ihn unterdrücken. Zwei Konfigurationsschlüssel steuern dieses Verhalten: +Wenn der Agent auf einen Zustellungs- oder Provider-Fehler stößt, kann Telegram entweder mit dem Fehlertext antworten oder ihn unterdrücken. Zwei Konfigurationsschlüssel steuern dieses Verhalten: -| Schlüssel | Werte | Standard | Beschreibung | -| ----------------------------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------ | +| Schlüssel | Werte | Standard | Beschreibung | +| ----------------------------------- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------- | | `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` sendet eine freundliche Fehlermeldung an den Chat. `silent` unterdrückt Fehlerantworten vollständig. | -| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Mindestzeit zwischen Fehlerantworten an denselben Chat. Verhindert Fehler-Spam während Ausfällen. | +| `channels.telegram.errorCooldownMs` | Zahl (ms) | `60000` | Mindestzeit zwischen Fehlerantworten an denselben Chat. Verhindert Fehler-Spam während Ausfällen. | Überschreibungen pro Konto, pro Gruppe und pro Thema werden unterstützt (dieselbe Vererbung wie bei anderen Telegram-Konfigurationsschlüsseln). @@ -837,54 +838,54 @@ Wenn beim Agenten ein Zustellungs- oder Provider-Fehler auftritt, kann Telegram - - Wenn `requireMention=false`, muss der Telegram-Privatsphärenmodus vollständige Sichtbarkeit erlauben. - - BotFather: `/setprivacy` -> Disable + - Wenn `requireMention=false`, muss der Telegram-Privatsphäre-Modus vollständige Sichtbarkeit erlauben. + - BotFather: `/setprivacy` -> Deaktivieren - Entfernen Sie den Bot anschließend aus der Gruppe und fügen Sie ihn erneut hinzu - `openclaw channels status` warnt, wenn die Konfiguration Gruppennachrichten ohne Erwähnung erwartet. - - `openclaw channels status --probe` kann explizite numerische Gruppen-IDs prüfen; der Platzhalter `"*"` kann nicht per Mitgliedschaftsprüfung geprüft werden. - - schneller Sitzungstest: `/activation always`. + - `openclaw channels status --probe` kann explizite numerische Gruppen-IDs prüfen; die Wildcard `"*"` kann nicht auf Mitgliedschaft geprüft werden. + - Schneller Sitzungstest: `/activation always`. - - Wenn `channels.telegram.groups` existiert, muss die Gruppe aufgeführt sein (oder `"*"` enthalten) + - Wenn `channels.telegram.groups` vorhanden ist, muss die Gruppe aufgeführt sein (oder `"*"` enthalten) - Bot-Mitgliedschaft in der Gruppe verifizieren - - Logs prüfen: `openclaw logs --follow` für Überspringgründe + - Logs prüfen: `openclaw logs --follow` für Gründe zum Überspringen - - Autorisieren Sie Ihre Absenderidentität (Pairing und/oder numerisches `allowFrom`) + - Autorisieren Sie Ihre Absenderidentität (Kopplung und/oder numerisches `allowFrom`) - Befehlsautorisierung gilt weiterhin, auch wenn die Gruppenrichtlinie `open` ist - `setMyCommands failed` mit `BOT_COMMANDS_TOO_MUCH` bedeutet, dass das native Menü zu viele Einträge hat; reduzieren Sie Plugin-/Skill-/benutzerdefinierte Befehle oder deaktivieren Sie native Menüs - - `deleteMyCommands`-/`setMyCommands`-Startaufrufe und `sendChatAction`-Typing-Aufrufe sind begrenzt und werden bei Request-Timeout einmal über den Transport-Fallback von Telegram erneut versucht. Anhaltende Netzwerk-/Fetch-Fehler deuten in der Regel auf DNS-/HTTPS-Erreichbarkeitsprobleme zu `api.telegram.org` hin + - `deleteMyCommands`- / `setMyCommands`-Startaufrufe und `sendChatAction`-Typing-Aufrufe sind begrenzt und werden bei Request-Timeout einmal über Telegrams Transport-Fallback wiederholt. Anhaltende Netzwerk-/Fetch-Fehler weisen in der Regel auf DNS-/HTTPS-Erreichbarkeitsprobleme zu `api.telegram.org` hin - `getMe returned 401` ist ein Telegram-Authentifizierungsfehler für das konfigurierte Bot-Token. - - Kopieren Sie das Bot-Token in BotFather erneut oder erzeugen Sie es neu, und aktualisieren Sie dann `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` oder `TELEGRAM_BOT_TOKEN` für das Standardkonto. - - `deleteWebhook 401 Unauthorized` während des Starts ist ebenfalls ein Authentifizierungsfehler; dies als „kein Webhook vorhanden“ zu behandeln, würde denselben Fehler durch ein ungültiges Token nur auf spätere API-Aufrufe verschieben. + - Kopieren oder generieren Sie das Bot-Token in BotFather erneut und aktualisieren Sie dann `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` oder `TELEGRAM_BOT_TOKEN` für das Standardkonto. + - `deleteWebhook 401 Unauthorized` beim Start ist ebenfalls ein Authentifizierungsfehler; dies als „kein Webhook vorhanden“ zu behandeln, würde denselben Fehler durch ein ungültiges Token nur auf spätere API-Aufrufe verschieben. - - Node 22+ mit benutzerdefiniertem Fetch/Proxy kann sofortiges Abbruchverhalten auslösen, wenn AbortSignal-Typen nicht übereinstimmen. - - Einige Hosts lösen `api.telegram.org` zuerst zu IPv6 auf; fehlerhafter IPv6-Ausgangsverkehr kann zeitweise Telegram-API-Fehler verursachen. - - Wenn die Logs `TypeError: fetch failed` oder `Network request for 'getUpdates' failed!` enthalten, wiederholt OpenClaw diese jetzt als behebbare Netzwerkfehler. - - Während des Polling-Starts verwendet OpenClaw den erfolgreichen Start-`getMe`-Test erneut für grammY, sodass der Runner vor dem ersten `getUpdates` kein zweites `getMe` benötigt. - - Wenn `deleteWebhook` während des Polling-Starts mit einem vorübergehenden Netzwerkfehler fehlschlägt, fährt OpenClaw mit Long Polling fort, anstatt einen weiteren Control-Plane-Aufruf vor dem Polling auszuführen. Ein weiterhin aktiver Webhook erscheint als `getUpdates`-Konflikt; OpenClaw baut dann den Telegram-Transport neu auf und versucht die Webhook-Bereinigung erneut. - - Wenn Telegram-Sockets in einem kurzen festen Takt erneuert werden, prüfen Sie auf einen niedrigen Wert für `channels.telegram.timeoutSeconds`; Bot-Clients begrenzen konfigurierte Werte unterhalb der Schutzwerte für ausgehende Anfragen und `getUpdates`, aber ältere Releases konnten jeden Poll oder jede Antwort abbrechen, wenn dieser Wert unter diese Schutzwerte gesetzt war. - - Wenn die Logs `Polling stall detected` enthalten, startet OpenClaw standardmäßig das Polling neu und baut den Telegram-Transport nach 120 Sekunden ohne abgeschlossene Long-Poll-Liveness neu auf. + - Node 22+ + benutzerdefiniertes fetch/Proxy kann sofortiges Abbruchverhalten auslösen, wenn AbortSignal-Typen nicht übereinstimmen. + - Einige Hosts lösen `api.telegram.org` zuerst zu IPv6 auf; defekter IPv6-Egress kann zu zeitweiligen Telegram-API-Fehlern führen. + - Wenn Logs `TypeError: fetch failed` oder `Network request for 'getUpdates' failed!` enthalten, wiederholt OpenClaw diese nun als wiederherstellbare Netzwerkfehler. + - Beim Polling-Start verwendet OpenClaw den erfolgreichen Start-`getMe`-Probe für grammY wieder, sodass der Runner vor dem ersten `getUpdates` keinen zweiten `getMe` benötigt. + - Wenn `deleteWebhook` beim Polling-Start mit einem vorübergehenden Netzwerkfehler fehlschlägt, fährt OpenClaw mit Long Polling fort, statt einen weiteren Control-Plane-Aufruf vor dem Polling auszuführen. Ein weiterhin aktiver Webhook erscheint als `getUpdates`-Konflikt; OpenClaw baut dann den Telegram-Transport neu auf und versucht die Webhook-Bereinigung erneut. + - Wenn Telegram-Sockets in einem kurzen festen Takt wiederverwendet werden, prüfen Sie auf einen niedrigen Wert für `channels.telegram.timeoutSeconds`; Bot-Clients begrenzen konfigurierte Werte unterhalb der ausgehenden und `getUpdates`-Request-Guards, ältere Releases konnten jedoch jeden Poll oder jede Antwort abbrechen, wenn dies unter diese Guards gesetzt war. + - Wenn Logs `Polling stall detected` enthalten, startet OpenClaw standardmäßig das Polling neu und baut den Telegram-Transport neu auf, nachdem 120 Sekunden lang keine abgeschlossene Long-Poll-Liveness festgestellt wurde. - `openclaw channels status --probe` und `openclaw doctor` warnen, wenn ein laufendes Polling-Konto nach der Start-Kulanzzeit `getUpdates` nicht abgeschlossen hat, wenn ein laufendes Webhook-Konto nach der Start-Kulanzzeit `setWebhook` nicht abgeschlossen hat oder wenn die letzte erfolgreiche Polling-Transportaktivität veraltet ist. - - Erhöhen Sie `channels.telegram.pollingStallThresholdMs` nur, wenn lang laufende `getUpdates`-Aufrufe fehlerfrei sind, Ihr Host aber weiterhin fälschliche Polling-Stall-Neustarts meldet. Anhaltende Stalls weisen meist auf Proxy-, DNS-, IPv6- oder TLS-Ausgangsprobleme zwischen dem Host und `api.telegram.org` hin. - - Telegram berücksichtigt außerdem Prozess-Proxy-Umgebungsvariablen für den Bot-API-Transport, einschließlich `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` und deren kleingeschriebene Varianten. `NO_PROXY` / `no_proxy` können `api.telegram.org` weiterhin umgehen. + - Erhöhen Sie `channels.telegram.pollingStallThresholdMs` nur, wenn lang laufende `getUpdates`-Aufrufe gesund sind, Ihr Host aber weiterhin fälschliche Polling-Stall-Neustarts meldet. Dauerhafte Stalls deuten in der Regel auf Proxy-, DNS-, IPv6- oder TLS-Egress-Probleme zwischen dem Host und `api.telegram.org` hin. + - Telegram berücksichtigt für den Bot-API-Transport auch Prozess-Proxy-Umgebungsvariablen, einschließlich `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` und deren Kleinschreibungsvarianten. `NO_PROXY` / `no_proxy` kann `api.telegram.org` weiterhin umgehen. - Wenn der von OpenClaw verwaltete Proxy über `OPENCLAW_PROXY_URL` für eine Service-Umgebung konfiguriert ist und keine Standard-Proxy-Umgebungsvariable vorhanden ist, verwendet Telegram diese URL ebenfalls für den Bot-API-Transport. - - Leiten Sie Telegram-API-Aufrufe auf VPS-Hosts mit instabilem direktem Ausgangsverkehr/TLS über `channels.telegram.proxy`: + - Leiten Sie Telegram-API-Aufrufe auf VPS-Hosts mit instabilem direktem Egress/TLS über `channels.telegram.proxy`: ```yaml channels: @@ -892,8 +893,8 @@ channels: proxy: socks5://:@proxy-host:1080 ``` - - Node 22+ verwendet standardmäßig `autoSelectFamily=true` (außer WSL2). Die Reihenfolge der Telegram-DNS-Ergebnisse berücksichtigt zuerst `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, dann `channels.telegram.network.dnsResultOrder`, dann den Prozessstandard wie `NODE_OPTIONS=--dns-result-order=ipv4first`; wenn nichts davon gilt, fällt Node 22+ auf `ipv4first` zurück. - - Wenn Ihr Host WSL2 ist oder ausdrücklich besser mit reinem IPv4-Verhalten funktioniert, erzwingen Sie die Familienauswahl: + - Node 22+ verwendet standardmäßig `autoSelectFamily=true` (außer WSL2). Die Reihenfolge der Telegram-DNS-Ergebnisse berücksichtigt `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, dann `channels.telegram.network.dnsResultOrder`, dann den Prozessstandard wie `NODE_OPTIONS=--dns-result-order=ipv4first`; wenn nichts davon zutrifft, fällt Node 22+ auf `ipv4first` zurück. + - Wenn Ihr Host WSL2 ist oder ausdrücklich besser mit reinem IPv4-Verhalten funktioniert, erzwingen Sie die Family-Auswahl: ```yaml channels: @@ -902,7 +903,7 @@ channels: autoSelectFamily: false ``` - - Antworten aus dem RFC-2544-Benchmark-Bereich (`198.18.0.0/15`) sind bereits standardmäßig für Telegram-Mediendownloads erlaubt. Wenn ein vertrauenswürdiger Fake-IP- oder transparenter Proxy `api.telegram.org` während Mediendownloads auf eine andere private/interne/Special-Use-Adresse umschreibt, können Sie den nur für Telegram geltenden Bypass aktivieren: + - Antworten aus dem RFC-2544-Benchmark-Bereich (`198.18.0.0/15`) sind für Telegram-Mediendownloads standardmäßig bereits erlaubt. Wenn ein vertrauenswürdiger Fake-IP- oder transparenter Proxy `api.telegram.org` während Mediendownloads auf eine andere private/interne/Sondernutzungsadresse umschreibt, können Sie den Telegram-spezifischen Bypass aktivieren: ```yaml channels: @@ -911,18 +912,18 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - Dieselbe Opt-in-Option ist pro Konto unter + - Dasselbe Opt-in ist pro Konto unter `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork` verfügbar. - - Wenn Ihr Proxy Telegram-Medienhosts zu `198.18.x.x` auflöst, lassen Sie das - gefährliche Flag zunächst deaktiviert. Telegram-Medien erlauben den - RFC-2544-Benchmark-Bereich bereits standardmäßig. + - Wenn Ihr Proxy Telegram-Medienhosts nach `198.18.x.x` auflöst, lassen Sie + das gefährliche Flag zunächst deaktiviert. Telegram-Medien erlauben den + RFC-2544-Benchmark-Bereich standardmäßig bereits. - `channels.telegram.network.dangerouslyAllowPrivateNetwork` schwächt die SSRF-Schutzmaßnahmen - für Telegram-Medien. Verwenden Sie es nur für vertrauenswürdige, vom Betreiber kontrollierte Proxy- + `channels.telegram.network.dangerouslyAllowPrivateNetwork` schwächt die Telegram- + Medien-SSRF-Schutzmaßnahmen. Verwenden Sie es nur für vertrauenswürdige, vom Betreiber kontrollierte Proxy- Umgebungen wie Clash-, Mihomo- oder Surge-Fake-IP-Routing, wenn diese - private oder Special-Use-Antworten außerhalb des RFC-2544-Benchmark- - Bereichs erzeugen. Lassen Sie es für normalen öffentlichen Internetzugriff auf Telegram deaktiviert. + private oder Sondernutzungsantworten außerhalb des RFC-2544-Benchmark- + Bereichs synthetisieren. Lassen Sie es für normalen öffentlichen Telegram-Zugriff deaktiviert. - Umgebungsüberschreibungen (temporär): @@ -939,23 +940,23 @@ dig +short api.telegram.org AAAA -Weitere Hilfe: [Kanal-Fehlerbehebung](/de/channels/troubleshooting). +Weitere Hilfe: [Channel-Fehlerbehebung](/de/channels/troubleshooting). ## Konfigurationsreferenz Primäre Referenz: [Konfigurationsreferenz - Telegram](/de/gateway/config-channels#telegram). - + -- Start/Authentifizierung: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` muss auf eine reguläre Datei verweisen; Symlinks werden abgelehnt) +- Start/Authentifizierung: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` muss auf eine reguläre Datei zeigen; Symlinks werden abgelehnt) - Zugriffskontrolle: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` auf oberster Ebene (`type: "acp"`) - Ausführungsgenehmigungen: `execApprovals`, `accounts.*.execApprovals` - Befehl/Menü: `commands.native`, `commands.nativeSkills`, `customCommands` -- Threads/Antworten: `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies` +- Threading/Antworten: `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies` - Streaming: `streaming` (Vorschau), `streaming.preview.toolProgress`, `blockStreaming` - Formatierung/Zustellung: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - Medien/Netzwerk: `mediaMaxMb`, `mediaGroupFlushMs`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` -- Benutzerdefinierte API-Root: `apiRoot` (nur Bot-API-Root; `/bot` nicht einschließen) +- benutzerdefinierte API-Root: `apiRoot` (nur Bot-API-Root; `/bot` nicht einschließen) - Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` - Aktionen/Fähigkeiten: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - Reaktionen: `reactionNotifications`, `reactionLevel` @@ -965,28 +966,28 @@ Primäre Referenz: [Konfigurationsreferenz - Telegram](/de/gateway/config-channe -Priorität bei mehreren Konten: Wenn zwei oder mehr Konto-IDs konfiguriert sind, setzen Sie `channels.telegram.defaultAccount` (oder schließen Sie `channels.telegram.accounts.default` ein), um das Standardrouting explizit zu machen. Andernfalls fällt OpenClaw auf die erste normalisierte Konto-ID zurück und `openclaw doctor` warnt. Benannte Konten erben `channels.telegram.allowFrom` / `groupAllowFrom`, aber keine `accounts.default.*`-Werte. +Priorität bei mehreren Konten: Wenn zwei oder mehr Konto-IDs konfiguriert sind, setzen Sie `channels.telegram.defaultAccount` (oder schließen Sie `channels.telegram.accounts.default` ein), um das Standard-Routing explizit zu machen. Andernfalls fällt OpenClaw auf die erste normalisierte Konto-ID zurück, und `openclaw doctor` warnt. Benannte Konten erben `channels.telegram.allowFrom` / `groupAllowFrom`, jedoch keine Werte von `accounts.default.*`. -## Verwandte Themen +## Verwandt Koppeln Sie einen Telegram-Benutzer mit dem Gateway. - Verhalten von Allowlist für Gruppen und Themen. + Allowlist-Verhalten für Gruppen und Themen. - - Eingehende Nachrichten an Agenten weiterleiten. + + Leiten Sie eingehende Nachrichten an Agenten weiter. Bedrohungsmodell und Härtung. - Gruppen und Themen Agenten zuordnen. + Ordnen Sie Gruppen und Themen Agenten zu. - Kanalübergreifende Diagnose. + Channel-übergreifende Diagnosen. diff --git a/docs/de/ci.md b/docs/de/ci.md index 36d9af41e..dde08efd8 100644 --- a/docs/de/ci.md +++ b/docs/de/ci.md @@ -1,94 +1,94 @@ --- read_when: - - Sie müssen nachvollziehen, warum ein CI-Job ausgeführt wurde oder nicht. - - Sie debuggen eine fehlgeschlagene GitHub-Actions-Prüfung - - Sie koordinieren einen Lauf oder erneuten Lauf der Release-Validierung - - Sie ändern den ClawSweeper-Dispatch oder die Weiterleitung von GitHub-Aktivitäten -summary: CI-Job-Graph, Scope-Gates, Release-Umbrellas und lokale Befehlsäquivalente + - Sie müssen nachvollziehen, warum ein CI-Job ausgeführt wurde oder nicht + - Sie debuggen eine fehlgeschlagene GitHub Actions-Prüfung + - Sie koordinieren einen Durchlauf oder erneuten Durchlauf der Release-Validierung. + - Sie ändern die ClawSweeper-Auslösung oder die Weiterleitung von GitHub-Aktivitäten +summary: CI-Jobgraph, Bereichs-Gates, Release-Dachworkflows und lokale Befehlsäquivalente title: CI-Pipeline x-i18n: - generated_at: "2026-05-03T21:27:44Z" + generated_at: "2026-05-04T06:41:37Z" model: gpt-5.5 provider: openai - source_hash: e07fc44aa844cb66ce529c570cbbbbf502a61bcbcbc3d9488557abb459ef7678 + source_hash: 72959d0feaf1339f01c9da263153fd89cc4727da6f928933819931991222714d source_path: ci.md workflow: 16 --- -OpenClaw-CI läuft bei jedem Push nach `main` und bei jedem Pull Request. Der `preflight`-Job klassifiziert den Diff und schaltet aufwendige Lanes ab, wenn nur nicht zusammenhängende Bereiche geändert wurden. Manuelle `workflow_dispatch`-Läufe umgehen bewusst das intelligente Scoping und fächern für Release-Kandidaten und breite Validierung den vollständigen Graphen auf. Android-Lanes bleiben über `include_android` opt-in. Release-exklusive Plugin-Abdeckung liegt im separaten Workflow [`Plugin Prerelease`](#plugin-prerelease) und läuft nur über [`Full Release Validation`](#full-release-validation) oder einen expliziten manuellen Dispatch. +OpenClaw CI läuft bei jedem Push nach `main` und jedem Pull Request. Der `preflight`-Job klassifiziert den Diff und deaktiviert teure Lanes, wenn sich nur nicht zusammenhängende Bereiche geändert haben. Manuelle `workflow_dispatch`-Läufe umgehen bewusst das intelligente Scoping und fächern den vollständigen Graphen für Release-Kandidaten und breite Validierung auf. Android-Lanes bleiben über `include_android` Opt-in. Release-spezifische Plugin-Abdeckung befindet sich im separaten Workflow [`Plugin-Vorabrelease`](#plugin-prerelease) und läuft nur über [`Vollständige Release-Validierung`](#full-release-validation) oder einen expliziten manuellen Dispatch. ## Pipeline-Übersicht -| Job | Zweck | Wann er läuft | -| -------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | -| `preflight` | Erkennt reine Docs-Änderungen, geänderte Scopes, geänderte Erweiterungen und erstellt das CI-Manifest | 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` | Abhängigkeitsfreier Audit des Produktions-Lockfiles 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 | -| `check-dependencies` | Produktionsbezogener Knip-Durchlauf nur für Abhängigkeiten plus Guard für die Allowlist ungenutzter Dateien | Node-relevante Änderungen | -| `build-artifacts` | Erstellt `dist/`, Control UI, Prüfungen gebauter Artefakte und wiederverwendbare Downstream-Artefakte | Node-relevante Änderungen | -| `checks-fast-core` | Schnelle Linux-Korrektheits-Lanes wie gebündelte/Plugin-Vertrags-/Protokollprüfungen | Node-relevante Änderungen | -| `checks-fast-contracts-channels` | Geshardete Channel-Vertragsprüfungen mit stabilem aggregiertem Prüfergebnis | Node-relevante Änderungen | -| `checks-node-core-test` | Core-Node-Test-Shards, ohne Channel-, gebündelte, Vertrags- und Erweiterungs-Lanes | Node-relevante Änderungen | -| `check` | Gesherdetes Äquivalent zum lokalen Haupt-Gate: Prod-Typen, Lint, Guards, Testtypen und strikter Smoke-Test | Node-relevante Änderungen | -| `check-additional` | Architektur, geshardeter Boundary-/Prompt-Drift, Erweiterungs-Guards, Paket-Boundary und Gateway Watch | Node-relevante Änderungen | -| `build-smoke` | Smoke-Tests für die gebaute CLI und Smoke-Test für den Startspeicher | Node-relevante Änderungen | -| `checks` | Verifier für Channel-Tests gegen gebaute Artefakte | Node-relevante Änderungen | -| `checks-node-compat-node22` | Node-22-Kompatibilitäts-Build und Smoke-Lane | Manueller CI-Dispatch für Releases | -| `check-docs` | Docs-Formatierung, Lint und Broken-Link-Prüfungen | Docs geändert | -| `skills-python` | Ruff + pytest für Python-gestützte Skills | Python-Skill-relevante Änderungen | -| `checks-windows` | Windows-spezifische Prozess-/Pfadtests plus Regressionen gemeinsamer Runtime-Import-Spezifizierer | Windows-relevante Änderungen | -| `macos-node` | macOS-TypeScript-Test-Lane mit den gemeinsam 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 Varianten plus ein Debug-APK-Build | Android-relevante Änderungen | -| `test-performance-agent` | Tägliche Codex-Optimierung langsamer Tests nach vertrauenswürdiger Aktivität | Erfolg der CI auf `main` oder manueller Dispatch | -| `openclaw-performance` | Tägliche/bedarfsbasierte Kova-Runtime-Performanceberichte mit Mock-Provider-, Deep-Profile- und GPT-5.4-Live-Lanes | Geplante und manuelle Dispatches | +| Job | Zweck | Wann er läuft | +| -------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------ | +| `preflight` | Erkennt reine Docs-Änderungen, geänderte Scopes, geänderte Erweiterungen und erstellt das CI-Manifest | Immer bei Nicht-Draft-Pushes und PRs | +| `security-scm-fast` | Erkennung privater Schlüssel und Workflow-Audit über `zizmor` | Immer bei Nicht-Draft-Pushes und PRs | +| `security-dependency-audit` | Produktions-Lockfile-Audit ohne Abhängigkeiten gegen npm-Advisories | Immer bei Nicht-Draft-Pushes und PRs | +| `security-fast` | Erforderliches Aggregat für die schnellen Sicherheits-Jobs | Immer bei Nicht-Draft-Pushes und PRs | +| `check-dependencies` | Produktions-Knip-Durchlauf nur für Abhängigkeiten plus Guard für die Allowlist ungenutzter Dateien | Node-relevante Änderungen | +| `build-artifacts` | Erstellt `dist/`, Control UI, Built-Artifact-Prüfungen und wiederverwendbare Downstream-Artefakte | Node-relevante Änderungen | +| `checks-fast-core` | Schnelle Linux-Korrektheits-Lanes wie gebündelte/Plugin-Vertrags-/Protokollprüfungen | Node-relevante Änderungen | +| `checks-fast-contracts-channels` | Gesplittete Channel-Vertragsprüfungen mit stabilem aggregiertem Prüfergebnis | Node-relevante Änderungen | +| `checks-node-core-test` | Core-Node-Test-Shards, ohne Channel-, gebündelte, Vertrags- und Erweiterungs-Lanes | Node-relevante Änderungen | +| `check` | Gesplittetes Äquivalent zum lokalen Haupt-Gate: Prod-Typen, Lint, Guards, Testtypen und strikter Smoke | Node-relevante Änderungen | +| `check-additional` | Architektur, gesplitteter Boundary-/Prompt-Drift, Erweiterungs-Guards, Paketgrenze und Gateway Watch | Node-relevante Änderungen | +| `build-smoke` | Built-CLI-Smoke-Tests und Startup-Memory-Smoke | Node-relevante Änderungen | +| `checks` | Verifier für Built-Artifact-Channel-Tests | Node-relevante Änderungen | +| `checks-node-compat-node22` | Node-22-Kompatibilitäts-Build und Smoke-Lane | Manueller CI-Dispatch für Releases | +| `check-docs` | Docs-Formatierung, Lint und Prüfungen auf defekte Links | Docs geändert | +| `skills-python` | Ruff + pytest für Python-gestützte Skills | Python-Skill-relevante Änderungen | +| `checks-windows` | Windows-spezifische Prozess-/Pfadtests plus Regressionen bei gemeinsamen Runtime-Import-Spezifizierern | Windows-relevante Änderungen | +| `macos-node` | macOS-TypeScript-Test-Lane mit den gemeinsamen 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 | +| `test-performance-agent` | Tägliche Codex-Optimierung langsamer Tests nach vertrauenswürdiger Aktivität | Main-CI-Erfolg oder manueller Dispatch | +| `openclaw-performance` | Tägliche/bedarfsweise Kova-Runtime-Performance-Berichte mit Mock-Provider-, Deep-Profile- und GPT-5.4-Live-Lanes | Geplanter und manueller Dispatch | ## Fail-Fast-Reihenfolge -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 aufwendigeren Artefakt- und Plattform-Matrix-Jobs zu warten. -3. `build-artifacts` überschneidet sich mit den schnellen Linux-Lanes, damit Downstream-Verbraucher starten können, sobald der gemeinsame Build bereit ist. -4. Aufwendigere Plattform- und Runtime-Lanes fächern danach auf: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` und `android`. +1. `preflight` entscheidet, welche Lanes überhaupt existieren. Die Logik für `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` überschneidet sich mit den schnellen Linux-Lanes, damit Downstream-Consumer starten können, sobald der gemeinsame Build bereit ist. +4. Schwerere Plattform- und Runtime-Lanes fächern danach auf: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` und `android`. -GitHub kann überholte Jobs als `cancelled` markieren, wenn ein neuerer Push auf demselben PR- oder `main`-Ref landet. Behandeln Sie das als CI-Rauschen, sofern nicht auch der neueste Lauf für denselben Ref fehlschlägt. Aggregierte Shard-Prüfungen verwenden `!cancelled() && always()`, damit sie normale Shard-Fehler weiterhin melden, aber nicht mehr eingereiht werden, nachdem der gesamte Workflow bereits überholt wurde. Der automatische CI-Concurrency-Schlüssel ist versioniert (`CI-v7-*`), damit ein Zombie auf GitHub-Seite in einer alten Warteschlangengruppe neuere `main`-Läufe nicht unbegrenzt blockieren kann. Manuelle Full-Suite-Läufe verwenden `CI-manual-v1-*` und brechen laufende Läufe nicht ab. +GitHub kann ersetzte Jobs als `cancelled` markieren, wenn ein neuerer Push auf demselben PR- oder `main`-Ref landet. Behandeln Sie das als CI-Rauschen, sofern nicht auch der neueste Lauf für denselben Ref fehlschlägt. Aggregierte Shard-Prüfungen verwenden `!cancelled() && always()`, sodass sie normale Shard-Fehler weiterhin melden, aber nicht mehr in die Warteschlange gehen, nachdem der gesamte Workflow bereits ersetzt wurde. Der automatische CI-Concurrency-Key ist versioniert (`CI-v7-*`), damit ein GitHub-seitiger Zombie in einer alten Queue-Gruppe neuere Main-Läufe nicht unbegrenzt blockieren kann. Manuelle Läufe der vollständigen Suite verwenden `CI-manual-v1-*` und brechen laufende Läufe nicht ab. ## Scope und Routing -Die Scope-Logik liegt in `scripts/ci-changed-scope.mjs` und ist durch Unit-Tests in `src/scripts/ci-changed-scope.test.ts` abgedeckt. Manueller Dispatch überspringt die Erkennung geänderter Scopes und lässt das Preflight-Manifest so agieren, als hätte sich jeder gescopte Bereich geändert. +Die Scope-Logik befindet sich in `scripts/ci-changed-scope.mjs` und ist durch Unit-Tests in `src/scripts/ci-changed-scope.test.ts` abgedeckt. Manueller Dispatch überspringt die Erkennung geänderter Scopes und lässt das Preflight-Manifest so handeln, als hätte sich jeder gescopte Bereich geändert. -- **CI-Workflow-Änderungen** validieren den Node-CI-Graphen plus Workflow-Linting, erzwingen aber für sich genommen keine nativen Windows-, Android- oder macOS-Builds; diese Plattform-Lanes bleiben auf Plattform-Quelländerungen gescopet. -- **Reine CI-Routing-Änderungen, ausgewählte günstige Core-Test-Fixture-Änderungen und enge Plugin-Vertragshelfer-/Test-Routing-Änderungen** verwenden einen schnellen reinen Node-Manifestpfad: `preflight`, Security und eine einzelne `checks-fast-core`-Aufgabe. Dieser Pfad überspringt Build-Artefakte, Node-22-Kompatibilität, Channel-Verträge, vollständige Core-Shards, gebündelte Plugin-Shards und zusätzliche Guard-Matrizen, wenn die Änderung auf die Routing- oder Hilfsflächen begrenzt ist, die die schnelle Aufgabe direkt ausübt. -- **Windows-Node-Prüfungen** sind auf Windows-spezifische Prozess-/Pfad-Wrapper, npm-/pnpm-/UI-Runner-Helfer, Paketmanager-Konfiguration und die CI-Workflow-Flächen gescopet, die diese Lane ausführen; nicht zusammenhängende Quell-, Plugin-, Install-Smoke- und reine Teständerungen bleiben auf den Linux-Node-Lanes. +- **CI-Workflow-Änderungen** validieren den Node-CI-Graphen plus Workflow-Linting, erzwingen aber für sich genommen keine nativen Windows-, Android- oder macOS-Builds; diese Plattform-Lanes bleiben auf Plattform-Source-Änderungen beschränkt. +- **Reine CI-Routing-Änderungen, ausgewählte günstige Core-Test-Fixture-Änderungen und schmale Plugin-Vertrags-Helper-/Test-Routing-Änderungen** verwenden einen schnellen Node-only-Manifestpfad: `preflight`, Sicherheit und eine einzelne `checks-fast-core`-Aufgabe. Dieser Pfad überspringt Build-Artefakte, Node-22-Kompatibilität, Channel-Verträge, vollständige Core-Shards, Bundled-Plugin-Shards und zusätzliche Guard-Matrizen, wenn die Änderung auf die Routing- oder Helper-Oberflächen beschränkt ist, die die schnelle Aufgabe direkt ausführt. +- **Windows-Node-Prüfungen** sind auf Windows-spezifische Prozess-/Pfad-Wrapper, npm-/pnpm-/UI-Runner-Helper, Paketmanager-Konfiguration und die CI-Workflow-Oberflächen beschränkt, die diese Lane ausführen; nicht zusammenhängende Source-, Plugin-, Install-Smoke- und reine Teständerungen bleiben auf den Linux-Node-Lanes. -Die langsamsten Node-Testfamilien sind aufgeteilt oder ausbalanciert, damit jeder Job klein bleibt, ohne Runner übermäßig zu reservieren: Channel-Verträge laufen als drei gewichtete Shards, schnelle Core-Unit-/Support-Lanes laufen separat, Core-Runtime-Infrastruktur ist zwischen State- und Prozess-/Config-Shards aufgeteilt, Auto-Reply läuft als balancierte Worker (wobei der Reply-Teilbaum in Agent-Runner-, Dispatch- und Commands-/State-Routing-Shards aufgeteilt ist), und agentische Gateway-/Server-Konfigurationen sind über Chat-/Auth-/Model-/HTTP-Plugin-/Runtime-/Startup-Lanes verteilt, statt auf gebaute Artefakte zu warten. Breite Browser-, QA-, Media- und sonstige Plugin-Tests verwenden ihre dedizierten Vitest-Konfigurationen statt des gemeinsamen Plugin-Catch-alls. Include-Pattern-Shards zeichnen Timing-Einträge mit dem CI-Shard-Namen auf, damit `.artifacts/vitest-shard-timings.json` eine ganze Konfiguration von einem gefilterten Shard unterscheiden kann. `check-additional` hält Package-Boundary-Compile-/Canary-Arbeit zusammen und trennt Runtime-Topologie-Architektur von Gateway-Watch-Abdeckung; die Boundary-Guard-Liste ist über vier Matrix-Shards gestreift, wobei jeder ausgewählte unabhängige Guards parallel ausführt und Timing pro Prüfung ausgibt, einschließlich `pnpm prompt:snapshots:check`, damit Prompt-Drift im Codex-Runtime-Happy-Path an den PR gebunden ist, der ihn verursacht hat. Gateway Watch, Channel-Tests und der Core-Support-Boundary-Shard laufen innerhalb von `build-artifacts` parallel, nachdem `dist/` und `dist-runtime/` bereits gebaut wurden. +Die langsamsten Node-Testfamilien sind aufgeteilt oder ausbalanciert, damit jeder Job klein bleibt, ohne Runner übermäßig zu reservieren: Channel-Verträge laufen als drei gewichtete Shards, Core-Unit-Fast-/Support-Lanes laufen separat, Core-Runtime-Infrastruktur ist zwischen State- und Process-/Config-Shards aufgeteilt, Auto-Reply läuft als ausbalancierte Worker (mit dem Reply-Teilbaum aufgeteilt in Agent-Runner-, Dispatch- und Commands-/State-Routing-Shards), und agentische Gateway-/Server-Konfigurationen sind über Chat-/Auth-/Model-/HTTP-Plugin-/Runtime-/Startup-Lanes aufgeteilt, statt auf Built Artifacts zu warten. Breite Browser-, QA-, Medien- und sonstige Plugin-Tests verwenden ihre dedizierten Vitest-Konfigurationen statt des gemeinsamen Plugin-Catch-all. Include-Pattern-Shards erfassen Timing-Einträge mit dem CI-Shard-Namen, sodass `.artifacts/vitest-shard-timings.json` eine ganze Konfiguration von einem gefilterten Shard unterscheiden kann. `check-additional` hält Compile-/Canary-Arbeit zur Paketgrenze zusammen und trennt Runtime-Topologie-Architektur von Gateway-Watch-Abdeckung; die Boundary-Guard-Liste ist über vier Matrix-Shards gestreift, von denen jeder ausgewählte unabhängige Guards parallel ausführt und Timings pro Prüfung ausgibt, einschließlich `pnpm prompt:snapshots:check`, damit Prompt-Drift im Happy Path der Codex-Runtime dem PR zugeordnet bleibt, der sie verursacht hat. Gateway Watch, Channel-Tests und der Core-Support-Boundary-Shard laufen innerhalb von `build-artifacts` parallel, nachdem `dist/` und `dist-runtime/` bereits gebaut sind. -Android-CI führt sowohl `testPlayDebugUnitTest` als auch `testThirdPartyDebugUnitTest` aus und baut anschließend das Play-Debug-APK. Die Third-Party-Variante hat kein separates Source-Set oder Manifest; ihre Unit-Test-Lane kompiliert die Variante weiterhin mit den SMS-/Call-Log-`BuildConfig`-Flags, vermeidet aber einen doppelten Debug-APK-Packaging-Job bei jedem Android-relevanten Push. +Android CI führt sowohl `testPlayDebugUnitTest` als auch `testThirdPartyDebugUnitTest` aus und erstellt anschließend das Play-Debug-APK. Der Third-Party-Flavor hat kein separates Source Set oder Manifest; seine Unit-Test-Lane kompiliert den Flavor weiterhin mit den SMS-/Anrufprotokoll-BuildConfig-Flags, vermeidet aber bei jedem Android-relevanten Push einen doppelten Debug-APK-Paketierungsjob. -Der Shard `check-dependencies` führt `pnpm deadcode:dependencies` aus (einen produktionsbezogenen Knip-Durchlauf nur für Abhängigkeiten, fixiert auf die neueste Knip-Version, wobei pnpm's Mindestfreigabealter für die `dlx`-Installation deaktiviert ist) sowie `pnpm deadcode:unused-files`, das Knips produktionsbezogene Funde ungenutzter Dateien mit `scripts/deadcode-unused-files.allowlist.mjs` vergleicht. Der Guard für ungenutzte Dateien schlägt fehl, wenn ein PR eine neue, nicht geprüfte ungenutzte Datei hinzufügt oder einen veralteten Allowlist-Eintrag zurücklässt, während absichtliche dynamische Plugin-, generierte, Build-, Live-Test- und Paket-Bridge-Flächen erhalten bleiben, die Knip statisch nicht auflösen kann. +Der `check-dependencies`-Shard führt `pnpm deadcode:dependencies` (einen Produktions-Knip-Durchlauf nur für Abhängigkeiten, fixiert auf die neueste Knip-Version, wobei pnpm's Mindest-Release-Alter für die `dlx`-Installation deaktiviert ist) und `pnpm deadcode:unused-files` aus, das Knips Produktionsfunde ungenutzter Dateien mit `scripts/deadcode-unused-files.allowlist.mjs` vergleicht. Der Guard für ungenutzte Dateien schlägt fehl, wenn ein PR eine neue, nicht geprüfte ungenutzte Datei hinzufügt oder einen veralteten Allowlist-Eintrag zurücklässt, während absichtlich dynamische Plugin-, generierte, Build-, Live-Test- und Paket-Bridge-Oberflächen erhalten bleiben, die Knip statisch nicht auflösen kann. -## Weiterleitung von ClawSweeper-Aktivität +## ClawSweeper-Aktivitätsweiterleitung -`.github/workflows/clawsweeper-dispatch.yml` ist die zielseitige Brücke von OpenClaw-Repository-Aktivität zu ClawSweeper. Sie checkt keinen nicht vertrauenswürdigen Pull-Request-Code aus und führt ihn nicht aus. Der Workflow erstellt aus `CLAWSWEEPER_APP_PRIVATE_KEY` ein GitHub-App-Token und sendet dann kompakte `repository_dispatch`-Payloads an `openclaw/clawsweeper`. +`.github/workflows/clawsweeper-dispatch.yml` ist die zielseitige Bridge von OpenClaw-Repository-Aktivität zu ClawSweeper. Sie checkt keinen nicht vertrauenswürdigen Pull-Request-Code aus und führt ihn nicht aus. Der Workflow erstellt aus `CLAWSWEEPER_APP_PRIVATE_KEY` ein GitHub-App-Token und dispatcht dann kompakte `repository_dispatch`-Payloads an `openclaw/clawsweeper`. Der Workflow hat vier Lanes: -- `clawsweeper_item` für exakte Issue- und Pull-Request-Review-Anfragen; +- `clawsweeper_item` für exakte Review-Anfragen zu Issues und Pull Requests; - `clawsweeper_comment` für explizite ClawSweeper-Befehle in Issue-Kommentaren; - `clawsweeper_commit_review` für Review-Anfragen auf Commit-Ebene bei `main`-Pushes; - `github_activity` für allgemeine GitHub-Aktivität, die der ClawSweeper-Agent inspizieren kann. -Die Lane `github_activity` leitet nur normalisierte Metadaten weiter: Ereignistyp, Aktion, Actor, Repository, Item-Nummer, URL, Titel, Status und kurze Auszüge für Kommentare oder Reviews, sofern vorhanden. Sie vermeidet bewusst die Weiterleitung des vollständigen Webhook-Bodys. Der empfangende Workflow in `openclaw/clawsweeper` ist `.github/workflows/github-activity.yml`; er sendet das normalisierte Ereignis an den OpenClaw-Gateway-Hook für den ClawSweeper-Agent. +Die `github_activity`-Lane leitet nur normalisierte Metadaten weiter: Ereignistyp, Aktion, Akteur, Repository, Item-Nummer, URL, Titel, Status und kurze Auszüge für Kommentare oder Reviews, sofern vorhanden. Sie vermeidet bewusst die Weiterleitung des vollständigen Webhook-Bodys. Der empfangende Workflow in `openclaw/clawsweeper` ist `.github/workflows/github-activity.yml`, der das normalisierte Ereignis an den OpenClaw-Gateway-Hook für den ClawSweeper-Agent postet. -Allgemeine Aktivität ist Beobachtung, nicht standardmäßige Zustellung. Der ClawSweeper-Agent erhält das Discord-Ziel in seinem Prompt und sollte nur dann an `#clawsweeper` posten, wenn das Ereignis überraschend, handlungsrelevant, riskant oder betrieblich nützlich ist. Routinemäßiges Öffnen, Bearbeitungen, Bot-Aktivität, doppeltes Webhook-Rauschen und normaler Review-Verkehr sollten zu `NO_REPLY` führen. +Allgemeine Aktivität ist Beobachtung, nicht standardmäßige Zustellung. Der ClawSweeper-Agent erhält das Discord-Ziel in seinem Prompt und sollte nur dann in `#clawsweeper` posten, wenn das Ereignis überraschend, handlungsrelevant, riskant oder betrieblich nützlich ist. Routinemäßige Opens, Edits, Bot-Aktivität, doppeltes Webhook-Rauschen und normaler Review-Verkehr sollten zu `NO_REPLY` führen. -Behandeln Sie GitHub-Titel, Kommentare, Bodys, Review-Text, Branch-Namen und Commit-Nachrichten in diesem gesamten Pfad als nicht vertrauenswürdige Daten. Sie sind Eingaben für Zusammenfassung und Triage, keine Anweisungen für den Workflow oder die Agent-Runtime. +Behandeln Sie GitHub-Titel, Kommentare, Bodies, Review-Text, Branch-Namen und Commit-Nachrichten in diesem gesamten Pfad als nicht vertrauenswürdige Daten. Sie sind Eingaben für Zusammenfassung und Triage, keine Anweisungen für den Workflow oder die Agent-Runtime. ## Manuelle Dispatches -Manuelle CI-Dispatches führen denselben Job-Graphen wie die normale CI aus, erzwingen aber jede nicht auf Android beschränkte Lane: Linux-Node-Shards, Shards für gebündelte Plugins, Channel-Verträge, Node-22-Kompatibilität, `check`, `check-additional`, Build-Smoke, Docs-Prüfungen, Python-Skills, Windows, macOS und Control-UI-i18n. Eigenständige manuelle CI-Dispatches führen Android nur mit `include_android=true` aus; der vollständige Release-Umbrella aktiviert Android, indem `include_android=true` übergeben wird. Statische Plugin-Prerelease-Prüfungen, der nur für Releases vorgesehene `agentic-plugins`-Shard, der vollständige Extension-Batch-Sweep und Plugin-Prerelease-Docker-Lanes sind von der CI ausgeschlossen. Die Docker-Prerelease-Suite läuft nur, wenn `Full Release Validation` den separaten `Plugin Prerelease`-Workflow mit aktivierter Release-Validation-Gate dispatcht. +Manuelle CI-Dispatches führen denselben Job-Graphen wie die normale CI aus, erzwingen jedoch jede nicht auf Android begrenzte Lane: Linux Node-Shards, gebündelte Plugin-Shards, Channel-Verträge, Node-22-Kompatibilität, `check`, `check-additional`, Build-Smoke, Dokumentationsprüfungen, Python-Skills, Windows, macOS und Control UI i18n. Eigenständige manuelle CI-Dispatches führen Android nur mit `include_android=true` aus; der vollständige Release-Umbrella aktiviert Android durch Übergabe von `include_android=true`. Statische Plugin-Prerelease-Prüfungen, der nur für Releases vorgesehene `agentic-plugins`-Shard, die vollständige Erweiterungs-Batch-Prüfung und Docker-Lanes für Plugin-Prereleases sind von der CI ausgeschlossen. Die Docker-Prerelease-Suite wird nur ausgeführt, wenn `Full Release Validation` den separaten `Plugin Prerelease`-Workflow mit aktiviertem Release-Validation-Gate dispatcht. -Manuelle Läufe verwenden eine eindeutige Concurrency-Gruppe, sodass eine vollständige Suite für einen Release-Kandidaten nicht durch einen anderen Push- oder PR-Lauf auf demselben Ref abgebrochen wird. Die optionale Eingabe `target_ref` ermöglicht einem vertrauenswürdigen Aufrufer, diesen Graphen gegen einen Branch, Tag oder vollständigen Commit-SHA auszuführen, während die Workflow-Datei aus dem ausgewählten Dispatch-Ref verwendet wird. +Manuelle Läufe verwenden eine eindeutige Concurrency-Gruppe, damit eine vollständige Suite für einen Release-Kandidaten nicht durch einen anderen Push- oder PR-Lauf auf demselben Ref abgebrochen wird. Die optionale Eingabe `target_ref` ermöglicht einem vertrauenswürdigen Aufrufer, diesen Graphen gegen einen Branch, ein Tag oder eine vollständige Commit-SHA auszuführen, während die Workflow-Datei aus dem ausgewählten Dispatch-Ref verwendet wird. ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -98,15 +98,15 @@ gh workflow run full-release-validation.yml --ref main -f ref= ## Runner -| Runner | Jobs | -| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`, schnelle Security-Jobs und Aggregate (`security-scm-fast`, `security-dependency-audit`, `security-fast`), schnelle Protokoll-/Vertrags-/gebündelte Prüfungen, geshardete Channel-Vertragsprüfungen, `check`-Shards außer Lint, `check-additional`-Shards und Aggregate, Verifizierer für Node-Testaggregate, Docs-Prüfungen, Python-Skills, workflow-sanity, labeler, auto-response; install-smoke preflight verwendet ebenfalls GitHub-gehostetes Ubuntu, damit die Blacksmith-Matrix früher in die Warteschlange gestellt werden kann | -| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, leichtere Extension-Shards, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` und `check-test-types` | -| `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` (CPU-sensitiv genug, dass 8 vCPU mehr gekostet haben, als sie gespart haben); install-smoke-Docker-Builds (32-vCPU-Warteschlangenzeit hat mehr gekostet, als sie gespart 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 Security-Jobs und Aggregationen (`security-scm-fast`, `security-dependency-audit`, `security-fast`), schnelle Protokoll-/Vertrags-/gebündelte Prüfungen, geshardete Channel-Vertragsprüfungen, `check`-Shards außer Lint, `check-additional`-Shards und Aggregationen, Aggregat-Prüfer für Node-Tests, Dokumentationsprüfungen, Python-Skills, workflow-sanity, labeler, auto-response; install-smoke preflight verwendet ebenfalls GitHub-gehostetes Ubuntu, damit die Blacksmith-Matrix früher eingereiht werden kann | +| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, weniger gewichtige Erweiterungs-Shards, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` und `check-test-types` | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, Linux Node-Test-Shards, gebündelte Plugin-Test-Shards, `android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (CPU-sensitiv genug, dass 8 vCPU mehr kosteten, als sie einsparten); install-smoke-Docker-Builds (32-vCPU-Warteschlangenzeit kostete mehr, als sie einsparte) | +| `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 Entsprechungen @@ -137,7 +137,7 @@ pnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.jso ## OpenClaw Performance -`OpenClaw Performance` ist der Performance-Workflow für Produkt und Runtime. Er läuft täglich auf `main` und kann manuell dispatcht werden: +`OpenClaw Performance` ist der Produkt-/Runtime-Performance-Workflow. Er läuft täglich auf `main` und kann manuell dispatcht werden: ```bash gh workflow run openclaw-performance.yml --ref main -f profile=diagnostic -f repeat=3 @@ -145,25 +145,32 @@ gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1 gh workflow run openclaw-performance.yml --ref main -f target_ref=v2026.5.2 -f profile=diagnostic -f repeat=3 ``` -Ein manueller Dispatch benchmarkt normalerweise den Workflow-Ref. Setzen Sie `target_ref`, um einen Release-Tag oder einen anderen Branch mit der aktuellen Workflow-Implementierung zu benchmarken. Veröffentlichte Berichtspfade und Latest-Zeiger werden nach dem getesteten Ref verschlüsselt, und jede `index.md` zeichnet den getesteten Ref/SHA, Workflow-Ref/SHA, Kova-Ref, Profil, Lane-Auth-Modus, Modell, Wiederholungsanzahl und Szenariofilter auf. +Ein manueller Dispatch benchmarkt normalerweise den Workflow-Ref. Setzen Sie `target_ref`, um ein Release-Tag oder einen anderen Branch mit der aktuellen Workflow-Implementierung zu benchmarken. Veröffentlichte Berichtspfade und latest-Zeiger werden nach dem getesteten Ref geschlüsselt, und jede `index.md` erfasst den getesteten Ref/SHA, Workflow-Ref/SHA, Kova-Ref, Profil, Lane-Auth-Modus, Modell, Wiederholungsanzahl und Szenariofilter. Der Workflow installiert OCM aus einem gepinnten Release und Kova aus `openclaw/Kova` mit der gepinnten Eingabe `kova_ref` und führt dann drei Lanes aus: - `mock-provider`: Kova-Diagnoseszenarien gegen eine lokal gebaute Runtime mit deterministischer gefälschter OpenAI-kompatibler Authentifizierung. -- `mock-deep-profile`: CPU-/Heap-/Trace-Profiling für Startup-, Gateway- und Agent-Turn-Hotspots. +- `mock-deep-profile`: CPU-/Heap-/Trace-Profiling für Start-, Gateway- und Agent-Turn-Hotspots. - `live-gpt54`: ein echter OpenAI-`openai/gpt-5.4`-Agent-Turn, der übersprungen wird, wenn `OPENAI_API_KEY` nicht verfügbar ist. -Die mock-provider-Lane führt nach dem Kova-Durchlauf auch OpenClaw-native Quellprobes aus: Gateway-Boot-Timing und Speicher über Standard-, Hook- und 50-Plugin-Startup-Fälle hinweg; wiederholte Mock-OpenAI-`channel-chat-baseline`-Hello-Schleifen; und CLI-Startup-Befehle gegen das gebootete Gateway. Die Markdown-Zusammenfassung der Quellprobe liegt unter `source/index.md` im Berichtsbündel, mit rohem JSON daneben. +Die mock-provider-Lane führt nach dem Kova-Durchlauf außerdem OpenClaw-native Source-Probes aus: Gateway-Start-Timing und Speicher über Standard-, Hook- und 50-Plugin-Startfälle hinweg; wiederholte mock-OpenAI-`channel-chat-baseline`-Hello-Loops; und CLI-Startbefehle gegen das gestartete Gateway. Die Markdown-Zusammenfassung der Source-Probe liegt unter `source/index.md` im Berichtsbundle, mit Roh-JSON daneben. -Jede Lane lädt GitHub-Artefakte hoch. Wenn `CLAWGRIT_REPORTS_TOKEN` konfiguriert ist, committet der Workflow außerdem `report.json`, `report.md`, Bündel, `index.md` und Quellprobe-Artefakte nach `openclaw/clawgrit-reports` unter `openclaw-performance//-//`. Der aktuelle tested-ref-Zeiger wird als `openclaw-performance//latest-.json` geschrieben. +Jede Lane lädt GitHub-Artefakte hoch. Wenn `CLAWGRIT_REPORTS_TOKEN` konfiguriert ist, committet der Workflow außerdem `report.json`, `report.md`, Bundles, `index.md` und Source-Probe-Artefakte in `openclaw/clawgrit-reports` unter `openclaw-performance//-//`. Der aktuelle tested-ref-Zeiger wird als `openclaw-performance//latest-.json` geschrieben. ## Vollständige Release-Validierung -`Full Release Validation` ist der manuelle Umbrella-Workflow für „alles vor dem Release ausführen“. Er akzeptiert einen Branch, Tag oder vollständigen Commit-SHA, dispatcht den manuellen `CI`-Workflow mit diesem Ziel, dispatcht `Plugin Prerelease` für nur für Releases vorgesehene Plugin-/Paket-/statische/Docker-Nachweise und dispatcht `OpenClaw Release Checks` für Install-Smoke, Paketakzeptanz, Docker-Release-Pfad-Suites, Live/E2E, OpenWebUI, QA-Lab-Parität, Matrix- und Telegram-Lanes. Mit `rerun_group=all` und `release_profile=full` führt er außerdem `NPM Telegram Beta E2E` gegen das Artefakt `release-package-under-test` aus Release-Prüfungen aus. Übergeben Sie nach der Veröffentlichung `npm_telegram_package_spec`, um dieselbe Telegram-Paket-Lane gegen das veröffentlichte npm-Paket erneut auszuführen. +`Full Release Validation` ist der manuelle Umbrella-Workflow für „alles vor dem Release ausführen“. Er akzeptiert einen Branch, ein Tag oder eine vollständige Commit-SHA, dispatcht den manuellen `CI`-Workflow mit diesem Ziel, dispatcht `Plugin Prerelease` für nur für Releases vorgesehene Plugin-/Paket-/statische/Docker-Nachweise und dispatcht `OpenClaw Release Checks` für Install-Smoke, Paketakzeptanz, Docker-Release-Pfad-Suites, Live/E2E, OpenWebUI, QA-Lab-Parität, Matrix und Telegram-Lanes. Mit `rerun_group=all` und `release_profile=full` führt er außerdem `NPM Telegram Beta E2E` gegen das Artefakt `release-package-under-test` aus den Release-Prüfungen aus. Nach der Veröffentlichung übergeben Sie `npm_telegram_package_spec`, um dieselbe Telegram-Paket-Lane gegen das veröffentlichte npm-Paket erneut auszuführen. -Siehe [Vollständige Release-Validierung](/de/reference/full-release-validation) für die Stage-Matrix, exakte Workflow-Jobnamen, Profilunterschiede, Artefakte und fokussierte Rerun-Handles. +Siehe [Vollständige Release-Validierung](/de/reference/full-release-validation) für die +Stage-Matrix, exakten Workflow-Jobnamen, Profilunterschiede, Artefakte und +gezielte Rerun-Handles. -`OpenClaw Release Publish` ist der manuelle mutierende Release-Workflow. Dispatchen Sie ihn von `release/YYYY.M.D` oder `main`, nachdem der Release-Tag existiert und nachdem der OpenClaw-npm-Preflight erfolgreich war. Er verifiziert `pnpm plugins:sync:check`, dispatcht `Plugin NPM Release` für alle veröffentlichbaren Plugin-Pakete, dispatcht `Plugin ClawHub Release` für denselben Release-SHA und dispatcht erst dann `OpenClaw NPM Release` mit der gespeicherten `preflight_run_id`. +`OpenClaw Release Publish` ist der manuelle mutierende Release-Workflow. Dispatchen Sie ihn +von `release/YYYY.M.D` oder `main`, nachdem das Release-Tag existiert und nachdem der +OpenClaw-npm-Preflight erfolgreich war. Er verifiziert `pnpm plugins:sync:check`, +dispatcht `Plugin NPM Release` für alle veröffentlichbaren Plugin-Pakete, dispatcht +`Plugin ClawHub Release` für dieselbe Release-SHA und dispatcht erst dann +`OpenClaw NPM Release` mit der gespeicherten `preflight_run_id`. ```bash gh workflow run openclaw-release-publish.yml \ @@ -173,37 +180,44 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -Für gepinnten Commit-Nachweis auf einem sich schnell bewegenden Branch verwenden Sie den Helper statt `gh workflow run ... --ref main -f ref=`: +Für einen gepinnten Commit-Nachweis auf einem sich schnell bewegenden Branch verwenden Sie den Helper anstelle von +`gh workflow run ... --ref main -f ref=`: ```bash pnpm ci:full-release --sha ``` -GitHub-Workflow-Dispatch-Refs müssen Branches oder Tags sein, keine rohen Commit-SHAs. Der Helper pusht einen temporären Branch `release-ci/-...` am Ziel-SHA, dispatcht `Full Release Validation` von diesem gepinnten Ref, verifiziert, dass jeder untergeordnete Workflow-`headSha` mit dem Ziel übereinstimmt, und löscht den temporären Branch, wenn der Lauf abgeschlossen ist. Der Umbrella-Verifizierer schlägt außerdem fehl, wenn irgendein untergeordneter Workflow mit einem anderen SHA lief. +GitHub-Workflow-Dispatch-Refs müssen Branches oder Tags sein, keine rohen Commit-SHAs. Der +Helper pusht einen temporären Branch `release-ci/-...` auf der Ziel-SHA, +dispatcht `Full Release Validation` von diesem gepinnten Ref, verifiziert, dass jede untergeordnete +Workflow-`headSha` dem Ziel entspricht, und löscht den temporären Branch, wenn der +Lauf abgeschlossen ist. Der Umbrella-Verifizierer schlägt außerdem fehl, wenn ein untergeordneter Workflow mit einer +anderen SHA lief. `release_profile` steuert die Live-/Provider-Breite, die an Release-Prüfungen übergeben wird. Die manuellen Release-Workflows verwenden standardmäßig `stable`; verwenden Sie `full` nur, wenn Sie bewusst die breite beratende Provider-/Medienmatrix ausführen möchten. -- `minimum` behält die schnellsten OpenAI-/Core-Release-kritischen Lanes bei. -- `stable` ergänzt das stabile Provider-/Backend-Set. +- `minimum` behält die schnellsten OpenAI-/Core-Lanes bei, die für Releases kritisch sind. +- `stable` fügt das stabile Provider-/Backend-Set hinzu. - `full` führt die breite beratende Provider-/Medienmatrix aus. -Der Umbrella zeichnet die IDs der gestarteten Child-Runs auf, und der abschließende Job `Verify full validation` prüft die aktuellen Ergebnisse der Child-Runs erneut und hängt Tabellen der langsamsten Jobs für jeden Child-Run an. Wenn ein Child-Workflow erneut ausgeführt wird und grün wird, führen Sie nur den Parent-Verifier-Job erneut aus, um das Umbrella-Ergebnis und die Timing-Zusammenfassung zu aktualisieren. +Der Umbrella zeichnet die IDs der gestarteten Child-Runs auf, und der abschließende Job `Verify full validation` prüft die aktuellen Ergebnisse der Child-Runs erneut und hängt Tabellen mit den langsamsten Jobs für jeden Child-Run an. Wenn ein Child-Workflow erneut ausgeführt wird und grün wird, führen Sie nur den Parent-Verifier-Job erneut aus, um das Umbrella-Ergebnis und die Timing-Zusammenfassung zu aktualisieren. -Für die Wiederherstellung akzeptieren sowohl `Full Release Validation` als auch `OpenClaw Release Checks` `rerun_group`. Verwenden Sie `all` für einen Release-Kandidaten, `ci` nur für das normale vollständige CI-Child, `plugin-prerelease` nur für das Plugin-Prerelease-Child, `release-checks` für jedes Release-Child oder eine engere Gruppe: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` oder `npm-telegram` auf dem Umbrella. So bleibt eine erneute Ausführung einer fehlgeschlagenen Release-Box nach einem gezielten Fix begrenzt. +Für die Wiederherstellung akzeptieren sowohl `Full Release Validation` als auch `OpenClaw Release Checks` `rerun_group`. Verwenden Sie `all` für einen Release-Kandidaten, `ci` nur für das normale vollständige CI-Child, `plugin-prerelease` nur für das Plugin-Prerelease-Child, `release-checks` für jedes Release-Child oder eine engere Gruppe: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` oder `npm-telegram` auf dem Umbrella. Dadurch bleibt die erneute Ausführung einer fehlgeschlagenen Release-Box nach einer gezielten Korrektur begrenzt. -`OpenClaw Release Checks` verwendet den vertrauenswürdigen Workflow-Ref, um den ausgewählten Ref einmalig in einen `release-package-under-test`-Tarball aufzulösen, und übergibt dieses Artefakt dann sowohl an den Live-/E2E-Release-Pfad-Docker-Workflow als auch an den Package-Acceptance-Shard. Dadurch bleiben die Paketbytes über Release-Boxen hinweg konsistent, und derselbe Kandidat muss nicht in mehreren Child-Jobs neu gepackt werden. +`OpenClaw Release Checks` verwendet die vertrauenswürdige Workflow-Referenz, um die ausgewählte Referenz einmal in ein `release-package-under-test`-Tarball aufzulösen, und übergibt dieses Artefakt dann sowohl an den Docker-Workflow für den Live-/E2E-Release-Pfad als auch an den Package-Acceptance-Shard. Dadurch bleiben die Paketbytes über Release-Boxen hinweg konsistent, und derselbe Kandidat muss nicht in mehreren Child-Jobs neu gepackt werden. Doppelte `Full Release Validation`-Runs für `ref=main` und `rerun_group=all` -ersetzen den älteren Umbrella. Der Parent-Monitor bricht jeden Child-Workflow ab, den er -bereits gestartet hat, wenn der Parent abgebrochen wird, sodass neuere Main-Validierungen -nicht hinter einem veralteten zweistündigen Release-Check-Run warten. Release-Branch-/Tag- -Validierungen und gezielte Rerun-Gruppen behalten `cancel-in-progress: false`. +ersetzen den älteren Umbrella. Der Parent-Monitor bricht jeden Child-Workflow ab, +den er bereits gestartet hat, wenn der Parent abgebrochen wird, sodass eine neuere +Main-Validierung nicht hinter einem veralteten zweistündigen Release-Check-Run +wartet. Die Validierung von Release-Branches/-Tags und gezielte Rerun-Gruppen +behalten `cancel-in-progress: false` bei. ## Live- und E2E-Shards -Das Release-Live-/E2E-Child behält eine breite native `pnpm test:live`-Abdeckung bei, führt sie aber über `scripts/test-live-shard.mjs` als benannte Shards aus statt als einen seriellen Job: +Das Release-Live-/E2E-Child behält die breite native Abdeckung durch `pnpm test:live` bei, führt sie aber über `scripts/test-live-shard.mjs` als benannte Shards aus statt als einen seriellen Job: - `native-live-src-agents` - `native-live-src-gateway-core` @@ -217,31 +231,31 @@ Das Release-Live-/E2E-Child behält eine breite native `pnpm test:live`-Abdeckun - `native-live-extensions-xai` - aufgeteilte Medien-Audio-/Video-Shards und Provider-gefilterte Musik-Shards -Damit bleibt dieselbe Dateiabdeckung erhalten, während langsame Live-Provider-Fehler leichter erneut ausgeführt und diagnostiziert werden können. Die aggregierten Shard-Namen `native-live-extensions-o-z`, `native-live-extensions-media` und `native-live-extensions-media-music` bleiben für manuelle einmalige Reruns gültig. +Das behält dieselbe Dateiabdeckung bei und macht langsame Live-Provider-Fehler leichter erneut ausführbar und diagnostizierbar. Die aggregierten Shard-Namen `native-live-extensions-o-z`, `native-live-extensions-media` und `native-live-extensions-media-music` bleiben für manuelle Einmal-Reruns gültig. -Die nativen Live-Medien-Shards laufen in `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, das vom Workflow `Live Media Runner Image` gebaut wird. Dieses Image installiert `ffmpeg` und `ffprobe` vor; Medienjobs prüfen die Binärdateien nur vor dem Setup. Belassen Sie Docker-gestützte Live-Suites auf normalen Blacksmith-Runnern — Container-Jobs sind der falsche Ort, um verschachtelte Docker-Tests zu starten. +Die nativen Live-Medien-Shards laufen in `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, gebaut vom Workflow `Live Media Runner Image`. Dieses Image installiert `ffmpeg` und `ffprobe` vor; Medien-Jobs verifizieren nur die Binärdateien vor dem Setup. Belassen Sie Docker-gestützte Live-Suites auf normalen Blacksmith-Runnern — Container-Jobs sind der falsche Ort, um verschachtelte Docker-Tests zu starten. -Docker-gestützte Live-Modell-/Backend-Shards verwenden ein separates gemeinsames Image `ghcr.io/openclaw/openclaw-live-test:` pro ausgewähltem Commit. Der Live-Release-Workflow baut und pusht dieses Image einmal, danach laufen die Docker-Live-Modell-, Provider-geshardeten Gateway-, CLI-Backend-, ACP-Bind- und Codex-Harness-Shards mit `OPENCLAW_SKIP_DOCKER_BUILD=1`. Gateway-Docker-Shards enthalten explizite Time-out-Grenzen auf Skriptebene unterhalb des Workflow-Job-Time-outs, sodass ein hängender Container oder Cleanup-Pfad schnell fehlschlägt, statt das gesamte Release-Check-Budget zu verbrauchen. Wenn diese Shards das vollständige Source-Docker-Target unabhängig neu bauen, ist der Release-Run falsch konfiguriert und verschwendet Laufzeit durch doppelte Image-Builds. +Docker-gestützte Live-Modell-/Backend-Shards verwenden ein separates gemeinsames Image `ghcr.io/openclaw/openclaw-live-test:` pro ausgewähltem Commit. Der Live-Release-Workflow baut und pusht dieses Image einmal; anschließend laufen die Docker-Live-Modell-, Provider-geshardeten Gateway-, CLI-Backend-, ACP-Bind- und Codex-Harness-Shards mit `OPENCLAW_SKIP_DOCKER_BUILD=1`. Gateway-Docker-Shards tragen explizite Timeout-Obergrenzen auf Skriptebene unterhalb des Workflow-Job-Timeouts, damit ein hängender Container oder Cleanup-Pfad schnell fehlschlägt, statt das gesamte Release-Check-Budget zu verbrauchen. Wenn diese Shards das vollständige Source-Docker-Target unabhängig neu bauen, ist der Release-Run falsch konfiguriert und verschwendet Laufzeit durch doppelte Image-Builds. -## Paketakzeptanz +## Paketabnahme -Verwenden Sie `Package Acceptance`, wenn die Frage lautet: „Funktioniert dieses installierbare OpenClaw-Paket als Produkt?“ Sie unterscheidet sich von normaler CI: Normale CI validiert den Source-Tree, während die Paketakzeptanz einen einzelnen Tarball über dasselbe Docker-E2E-Harness validiert, das Benutzer nach Installation oder Update ausführen. +Verwenden Sie `Package Acceptance`, wenn die Frage lautet: „Funktioniert dieses installierbare OpenClaw-Paket als Produkt?“ Sie unterscheidet sich von normalem CI: Normales CI validiert den Quellbaum, während Package Acceptance ein einzelnes Tarball über denselben Docker-E2E-Harness validiert, den Benutzer nach Installation oder Update ausführen. ### Jobs -1. `resolve_package` checkt `workflow_ref` aus, löst einen Paketkandidaten auf, schreibt `.artifacts/docker-e2e-package/openclaw-current.tgz`, schreibt `.artifacts/docker-e2e-package/package-candidate.json`, lädt beide als Artefakt `package-under-test` hoch und gibt Quelle, Workflow-Ref, Paket-Ref, Version, SHA-256 und Profil in der GitHub-Step-Zusammenfassung aus. +1. `resolve_package` checkt `workflow_ref` aus, löst einen Paketkandidaten auf, schreibt `.artifacts/docker-e2e-package/openclaw-current.tgz`, schreibt `.artifacts/docker-e2e-package/package-candidate.json`, lädt beide als Artefakt `package-under-test` hoch und gibt Quelle, Workflow-Referenz, Paket-Referenz, Version, SHA-256 und Profil in der GitHub-Step-Zusammenfassung aus. 2. `docker_acceptance` ruft `openclaw-live-and-e2e-checks-reusable.yml` mit `ref=workflow_ref` und `package_artifact_name=package-under-test` auf. Der wiederverwendbare Workflow lädt dieses Artefakt herunter, validiert das Tarball-Inventar, bereitet bei Bedarf Package-Digest-Docker-Images vor und führt die ausgewählten Docker-Lanes gegen dieses Paket aus, statt den Workflow-Checkout zu packen. Wenn ein Profil mehrere gezielte `docker_lanes` auswählt, bereitet der wiederverwendbare Workflow das Paket und die gemeinsamen Images einmal vor und fächert diese Lanes dann als parallele gezielte Docker-Jobs mit eindeutigen Artefakten auf. 3. `package_telegram` ruft optional `NPM Telegram Beta E2E` auf. Es läuft, wenn `telegram_mode` nicht `none` ist, und installiert dasselbe Artefakt `package-under-test`, wenn Package Acceptance eines aufgelöst hat; ein eigenständiger Telegram-Dispatch kann weiterhin eine veröffentlichte npm-Spezifikation installieren. -4. `summary` lässt den Workflow fehlschlagen, wenn die Paketauflösung, Docker-Akzeptanz oder die optionale Telegram-Lane fehlgeschlagen ist. +4. `summary` lässt den Workflow fehlschlagen, wenn die Paketauflösung, Docker Acceptance oder die optionale Telegram-Lane fehlgeschlagen ist. ### Kandidatenquellen -- `source=npm` akzeptiert nur `openclaw@beta`, `openclaw@latest` oder eine exakte OpenClaw-Release-Version wie `openclaw@2026.4.27-beta.2`. Verwenden Sie dies für die Akzeptanz veröffentlichter Prerelease-/Stable-Versionen. -- `source=ref` packt einen vertrauenswürdigen `package_ref`-Branch, ein Tag oder eine vollständige Commit-SHA. Der Resolver ruft OpenClaw-Branches/-Tags ab, prüft, ob der ausgewählte Commit aus der Repository-Branch-Historie oder einem Release-Tag erreichbar ist, installiert Abhängigkeiten in einem losgelösten Worktree und packt ihn mit `scripts/package-openclaw-for-docker.mjs`. -- `source=url` lädt eine HTTPS-`.tgz` herunter; `package_sha256` ist erforderlich. -- `source=artifact` lädt eine `.tgz` aus `artifact_run_id` und `artifact_name` herunter; `package_sha256` ist optional, sollte aber für extern geteilte Artefakte angegeben werden. +- `source=npm` akzeptiert nur `openclaw@beta`, `openclaw@latest` oder eine exakte OpenClaw-Release-Version wie `openclaw@2026.4.27-beta.2`. Verwenden Sie dies für die Abnahme veröffentlichter Prerelease-/Stable-Versionen. +- `source=ref` packt einen vertrauenswürdigen `package_ref`-Branch, -Tag oder vollständigen Commit-SHA. Der Resolver ruft OpenClaw-Branches/-Tags ab, verifiziert, dass der ausgewählte Commit aus der Repository-Branch-Historie oder einem Release-Tag erreichbar ist, installiert Abhängigkeiten in einem detached Worktree und packt ihn mit `scripts/package-openclaw-for-docker.mjs`. +- `source=url` lädt ein HTTPS-`.tgz` herunter; `package_sha256` ist erforderlich. +- `source=artifact` lädt ein `.tgz` aus `artifact_run_id` und `artifact_name` herunter; `package_sha256` ist optional, sollte aber für extern geteilte Artefakte angegeben werden. -Halten Sie `workflow_ref` und `package_ref` getrennt. `workflow_ref` ist der vertrauenswürdige Workflow-/Harness-Code, der den Test ausführt. `package_ref` ist der Source-Commit, der gepackt wird, wenn `source=ref` ist. Dadurch kann das aktuelle Test-Harness ältere vertrauenswürdige Source-Commits validieren, ohne alte Workflow-Logik auszuführen. +Halten Sie `workflow_ref` und `package_ref` getrennt. `workflow_ref` ist der vertrauenswürdige Workflow-/Harness-Code, der den Test ausführt. `package_ref` ist der Source-Commit, der gepackt wird, wenn `source=ref` verwendet wird. Dadurch kann der aktuelle Test-Harness ältere vertrauenswürdige Source-Commits validieren, ohne alte Workflow-Logik auszuführen. ### Suite-Profile @@ -253,23 +267,23 @@ Halten Sie `workflow_ref` und `package_ref` getrennt. `workflow_ref` ist der ver Das Profil `package` verwendet Offline-Plugin-Abdeckung, sodass die Validierung veröffentlichter Pakete nicht von der Live-Verfügbarkeit von ClawHub abhängt. Die optionale Telegram-Lane verwendet das Artefakt `package-under-test` in `NPM Telegram Beta E2E` wieder; der Pfad für veröffentlichte npm-Spezifikationen bleibt für eigenständige Dispatches erhalten. -Für die dedizierte Update- und Plugin-Testrichtlinie, einschließlich lokaler Befehle, +Für die dedizierte Update- und Plugin-Test-Richtlinie, einschließlich lokaler Befehle, Docker-Lanes, Package-Acceptance-Eingaben, Release-Standards und Fehlertriage, siehe [Updates und Plugins testen](/de/help/testing-updates-plugins). -Release-Prüfungen rufen Package Acceptance mit `source=artifact`, dem vorbereiteten Release-Paketartefakt, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`, `published_upgrade_survivor_baselines=all-since-2026.4.23`, `published_upgrade_survivor_scenarios=reported-issues` und `telegram_mode=mock-openai` auf. Dadurch bleiben Paketmigration, Update, Bereinigung veralteter Plugin-Abhängigkeiten, Reparatur der Installation konfigurierter Plugins, Offline-Plugin-, Plugin-Update- und Telegram-Nachweis auf demselben aufgelösten Paket-Tarball. Setzen Sie `package_acceptance_package_spec` bei Full Release Validation oder OpenClaw Release Checks, um dieselbe Matrix gegen ein ausgeliefertes npm-Paket statt gegen das aus der SHA gebaute Artefakt auszuführen. Cross-OS-Release-Prüfungen decken weiterhin betriebssystemspezifisches Onboarding, Installer- und Plattformverhalten ab; Paket-/Update-Produktvalidierung sollte mit Package Acceptance beginnen. Die Docker-Lane `published-upgrade-survivor` validiert pro Run eine veröffentlichte Paket-Baseline. In Package Acceptance ist der aufgelöste Tarball `package-under-test` immer der Kandidat, und `published_upgrade_survivor_baseline` wählt die veröffentlichte Fallback-Baseline aus, standardmäßig `openclaw@latest`; Rerun-Befehle für fehlgeschlagene Lanes behalten diese Baseline bei. Setzen Sie `published_upgrade_survivor_baselines=all-since-2026.4.23`, um Full Release CI über jedes stabile npm-Release von `2026.4.23` bis `latest` zu erweitern; `release-history` bleibt für manuelles breiteres Sampling mit dem älteren Vor-Datum-Anker verfügbar. Setzen Sie `published_upgrade_survivor_scenarios=reported-issues`, um dieselben Baselines über issue-förmige Fixtures für Feishu-Konfiguration, beibehaltene Bootstrap-/Persona-Dateien, konfigurierte OpenClaw-Plugin-Installationen, Tilde-Logpfade und veraltete Legacy-Plugin-Abhängigkeitswurzeln zu erweitern. Der separate Workflow `Update Migration` verwendet die Docker-Lane `update-migration` mit `all-since-2026.4.23` und `plugin-deps-cleanup`, wenn es um vollständige Bereinigung veröffentlichter Updates geht, nicht um normale Full-Release-CI-Breite. Lokale aggregierte Runs können exakte Paketspezifikationen mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` übergeben, mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` eine einzelne Lane behalten, etwa `openclaw@2026.4.15`, oder `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` für die Szenariomatrix setzen. Die veröffentlichte Lane konfiguriert die Baseline mit einem eingebetteten `openclaw config set`-Befehlsrezept, zeichnet Rezeptschritte in `summary.json` auf und prüft nach dem Gateway-Start `/healthz`, `/readyz` sowie den RPC-Status. Die Windows-Paket- und Installer-Fresh-Lanes prüfen außerdem, ob ein installiertes Paket einen Browser-Control-Override aus einem rohen absoluten Windows-Pfad importieren kann. Der OpenAI-Cross-OS-Agent-Turn-Smoke verwendet standardmäßig `OPENCLAW_CROSS_OS_OPENAI_MODEL`, wenn gesetzt, andernfalls `openai/gpt-5.4`, sodass der Installations- und Gateway-Nachweis auf einem GPT-5-Testmodell bleibt und GPT-4.x-Standards vermieden werden. +Release-Prüfungen rufen Package Acceptance mit `source=artifact`, dem vorbereiteten Release-Paketartefakt, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`, `published_upgrade_survivor_baselines=all-since-2026.4.23`, `published_upgrade_survivor_scenarios=reported-issues` und `telegram_mode=mock-openai` auf. Dadurch bleiben Paketmigration, Update, Bereinigung veralteter Plugin-Abhängigkeiten, Reparatur der Installation konfigurierter Plugins, Offline-Plugin, Plugin-Update und Telegram-Nachweis auf demselben aufgelösten Paket-Tarball. Setzen Sie `package_acceptance_package_spec` in Full Release Validation oder OpenClaw Release Checks, um dieselbe Matrix gegen ein ausgeliefertes npm-Paket statt gegen das SHA-gebaute Artefakt auszuführen. Cross-OS-Release-Prüfungen decken weiterhin betriebssystemspezifisches Onboarding-, Installer- und Plattformverhalten ab; Produktvalidierung für Paket/Update sollte mit Package Acceptance beginnen. Die Docker-Lane `published-upgrade-survivor` validiert pro Run eine veröffentlichte Paketbaseline. In Package Acceptance ist das aufgelöste Tarball `package-under-test` immer der Kandidat, und `published_upgrade_survivor_baseline` wählt die veröffentlichte Fallback-Baseline aus, standardmäßig `openclaw@latest`; Rerun-Befehle für fehlgeschlagene Lanes bewahren diese Baseline. Setzen Sie `published_upgrade_survivor_baselines=all-since-2026.4.23`, um Full Release CI auf jedes stabile npm-Release von `2026.4.23` bis `latest` auszuweiten; `release-history` bleibt für manuelles breiteres Sampling mit dem älteren Vor-Datum-Anker verfügbar. Setzen Sie `published_upgrade_survivor_scenarios=reported-issues`, um dieselben Baselines auf issue-geformte Fixtures für Feishu-Konfiguration, bewahrte Bootstrap-/Persona-Dateien, konfigurierte OpenClaw-Plugin-Installationen, Tilde-Logpfade und veraltete Legacy-Plugin-Abhängigkeitsroots auszuweiten. Der separate Workflow `Update Migration` verwendet die Docker-Lane `update-migration` mit `all-since-2026.4.23` und `plugin-deps-cleanup`, wenn die Frage umfassende Bereinigung veröffentlichter Updates ist, nicht die normale Breite von Full Release CI. Lokale Aggregat-Runs können exakte Paketspezifikationen mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` übergeben, eine einzelne Lane mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` wie `openclaw@2026.4.15` behalten oder `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` für die Szenariomatrix setzen. Die veröffentlichte Lane konfiguriert die Baseline mit einem eingebetteten `openclaw config set`-Befehlsrezept, zeichnet Rezeptschritte in `summary.json` auf und prüft `/healthz`, `/readyz` sowie den RPC-Status nach dem Gateway-Start. Die Windows-Packaged- und Installer-Fresh-Lanes verifizieren außerdem, dass ein installiertes Paket einen Browser-Control-Override aus einem rohen absoluten Windows-Pfad importieren kann. Der OpenAI-Cross-OS-Agent-Turn-Smoke verwendet standardmäßig `OPENCLAW_CROSS_OS_OPENAI_MODEL`, wenn gesetzt, andernfalls `openai/gpt-5.4`, sodass der Installations- und Gateway-Nachweis auf einem GPT-5-Testmodell bleibt und GPT-4.x-Standards vermieden werden. ### Legacy-Kompatibilitätsfenster -Package Acceptance hat begrenzte Legacy-Kompatibilitätsfenster für bereits veröffentlichte Pakete. Pakete bis einschließlich `2026.4.25`, einschließlich `2026.4.25-beta.*`, können den Kompatibilitätspfad verwenden: +Package Acceptance hat begrenzte Legacy-Kompatibilitätsfenster für bereits veröffentlichte Pakete. Pakete bis einschließlich `2026.4.25`, einschließlich `2026.4.25-beta.*`, dürfen den Kompatibilitätspfad verwenden: -- bekannte private QA-Einträge in `dist/postinstall-inventory.json` können auf Dateien verweisen, die im Tarball ausgelassen wurden; -- `doctor-switch` kann den Unterfall zur Persistenz von `gateway install --wrapper` überspringen, wenn das Paket dieses Flag nicht bereitstellt; -- `update-channel-switch` kann fehlende `pnpm.patchedDependencies` aus dem vom Tarball abgeleiteten Fake-Git-Fixture entfernen und fehlendes persistiertes `update.channel` protokollieren; -- Plugin-Smokes können Legacy-Install-Record-Speicherorte lesen oder fehlende Marketplace-Install-Record-Persistenz akzeptieren; -- `plugin-update` kann die Migration von Konfigurationsmetadaten zulassen, während weiterhin erforderlich ist, dass Install-Record und No-Reinstall-Verhalten unverändert bleiben. +- bekannte private QA-Einträge in `dist/postinstall-inventory.json` dürfen auf Dateien verweisen, die im Tarball ausgelassen wurden; +- `doctor-switch` darf den Unterfall für die Persistenz von `gateway install --wrapper` überspringen, wenn das Paket dieses Flag nicht bereitstellt; +- `update-channel-switch` darf fehlende `pnpm.patchedDependencies` aus dem aus dem Tarball abgeleiteten Fake-Git-Fixture entfernen und darf fehlendes persistiertes `update.channel` protokollieren; +- Plugin-Smokes dürfen Legacy-Install-Record-Speicherorte lesen oder fehlende Persistenz des Marketplace-Install-Records akzeptieren; +- `plugin-update` darf die Migration von Konfigurationsmetadaten zulassen, muss aber weiterhin verlangen, dass Install-Record und No-Reinstall-Verhalten unverändert bleiben. -Das veröffentlichte Paket `2026.4.26` kann außerdem Warnungen für lokale Build-Metadaten-Stempeldateien ausgeben, die bereits ausgeliefert wurden. Spätere Pakete müssen die modernen Verträge erfüllen; dieselben Bedingungen schlagen dann fehl, statt zu warnen oder übersprungen zu werden. +Das veröffentlichte Paket `2026.4.26` darf außerdem Warnungen für lokale Build-Metadaten-Stempeldateien ausgeben, die bereits ausgeliefert wurden. Spätere Pakete müssen die modernen Verträge erfüllen; dieselben Bedingungen schlagen dann fehl, statt zu warnen oder zu überspringen. ### Beispiele @@ -312,60 +326,60 @@ gh workflow run package-acceptance.yml \ -f docker_lanes='install-e2e plugin-update' ``` -Beginnen Sie beim Debuggen eines fehlgeschlagenen Package-Acceptance-Laufs mit der Zusammenfassung `resolve_package`, um Paketquelle, Version und SHA-256 zu bestätigen. Prüfen Sie anschließend den untergeordneten Lauf `docker_acceptance` und seine Docker-Artefakte: `.artifacts/docker-tests/**/summary.json`, `failures.json`, Lane-Protokolle, Phasen-Timings und Befehle für erneute Läufe. Führen Sie bevorzugt das fehlgeschlagene Paketprofil oder die exakten Docker-Lanes erneut aus, statt die vollständige Release-Validierung erneut zu starten. +Wenn Sie einen fehlgeschlagenen Package-Acceptance-Lauf debuggen, beginnen Sie bei der Zusammenfassung `resolve_package`, um Paketquelle, Version und SHA-256 zu bestätigen. Prüfen Sie anschließend den untergeordneten Lauf `docker_acceptance` und dessen Docker-Artefakte: `.artifacts/docker-tests/**/summary.json`, `failures.json`, Lane-Logs, Phasen-Timings und Befehle für erneute Läufe. Führen Sie bevorzugt das fehlgeschlagene Paketprofil oder die exakten Docker-Lanes erneut aus, statt die vollständige Release-Validierung erneut auszuführen. ## Installations-Smoke-Test Der separate Workflow `Install Smoke` verwendet dasselbe Scope-Skript über seinen eigenen Job `preflight` wieder. Er teilt die Smoke-Abdeckung in `run_fast_install_smoke` und `run_full_install_smoke` auf. -- **Schneller Pfad** läuft für Pull Requests, die Docker-/Paket-Oberflächen, Änderungen an gebündelten Plugin-Paketen/-Manifesten oder Core-Plugin-/Channel-/Gateway-/Plugin SDK-Oberflächen berühren, die von den Docker-Smoke-Jobs ausgeführt werden. Reine Quelländerungen an gebündelten Plugins, reine Teständerungen und reine Dokumentationsänderungen reservieren keine Docker-Worker. Der schnelle Pfad baut das Root-Dockerfile-Image einmal, prüft die CLI, führt den CLI-Smoke-Test zum Löschen von Agents in einem gemeinsam genutzten Workspace aus, führt den Container-Gateway-Netzwerk-E2E-Test aus, verifiziert ein Build-Argument für eine gebündelte Extension und führt das begrenzte Docker-Profil für gebündelte Plugins unter einem aggregierten Befehls-Timeout von 240 Sekunden aus (jeder Docker-Lauf pro Szenario ist separat begrenzt). -- **Vollständiger Pfad** behält QR-Paketinstallation sowie Installer-Docker-/Update-Abdeckung für nächtlich geplante Läufe, manuelle Auslösungen, Workflow-Call-Release-Prüfungen und Pull Requests bei, die tatsächlich Installer-/Paket-/Docker-Oberflächen berühren. Im vollständigen Modus bereitet Install-Smoke ein GHCR-Root-Dockerfile-Smoke-Image für die Ziel-SHA vor oder verwendet es wieder und führt dann QR-Paketinstallation, Root-Dockerfile-/Gateway-Smoke-Tests, Installer-/Update-Smoke-Tests und den schnellen Docker-E2E-Test für gebündelte Plugins als separate Jobs aus, damit Installer-Arbeit nicht hinter den Root-Image-Smoke-Tests warten muss. +- **Schneller Pfad** läuft für Pull Requests, die Docker-/Paket-Oberflächen, Änderungen an Paket/Manifest gebündelter Plugins oder Core-Plugin-/Channel-/Gateway-/Plugin-SDK-Oberflächen berühren, die von den Docker-Smoke-Jobs geprüft werden. Reine Quelländerungen an gebündelten Plugins, reine Teständerungen und reine Dokumentationsänderungen reservieren keine Docker-Worker. Der schnelle Pfad baut das Root-Dockerfile-Image einmal, prüft die CLI, führt den CLI-Smoke-Test zum Löschen von Agents im gemeinsam genutzten Arbeitsbereich aus, führt den Container-Gateway-Netzwerk-E2E aus, verifiziert ein Build-Argument für eine gebündelte Erweiterung und führt das begrenzte Docker-Profil für gebündelte Plugins mit einem aggregierten Befehls-Timeout von 240 Sekunden aus (jeder Docker-Lauf eines Szenarios ist separat begrenzt). +- **Vollständiger Pfad** behält die QR-Paketinstallation sowie Installer-Docker-/Update-Abdeckung für nächtliche geplante Läufe, manuelle Dispatches, Release-Prüfungen per Workflow-Call und Pull Requests bei, die tatsächlich Installer-/Paket-/Docker-Oberflächen berühren. Im vollständigen Modus bereitet install-smoke ein GHCR-Root-Dockerfile-Smoke-Image für den Ziel-SHA vor oder verwendet es wieder und führt dann QR-Paketinstallation, Root-Dockerfile-/Gateway-Smoke-Tests, Installer-/Update-Smoke-Tests und den schnellen Docker-E2E für gebündelte Plugins als separate Jobs aus, damit Installer-Arbeit nicht hinter den Root-Image-Smoke-Tests warten muss. -`main`-Pushes (einschließlich Merge-Commits) erzwingen nicht den vollständigen Pfad; wenn die Changed-Scope-Logik bei einem Push vollständige Abdeckung anfordern würde, behält der Workflow den schnellen Docker-Smoke-Test bei und überlässt den vollständigen Install-Smoke-Test der nächtlichen oder Release-Validierung. +`main`-Pushes (einschließlich Merge-Commits) erzwingen nicht den vollständigen Pfad; wenn die Changed-Scope-Logik bei einem Push vollständige Abdeckung anfordern würde, behält der Workflow den schnellen Docker-Smoke-Test bei und überlässt den vollständigen Installations-Smoke-Test der nächtlichen oder Release-Validierung. -Der langsame Bun-Global-Install-Image-Provider-Smoke-Test wird separat über `run_bun_global_install_smoke` gesteuert. Er läuft nach dem nächtlichen Zeitplan und aus dem Release-Checks-Workflow, und manuelle `Install Smoke`-Auslösungen können ihn aktivieren, Pull Requests und `main`-Pushes jedoch nicht. QR- und Installer-Docker-Tests behalten ihre eigenen install-fokussierten Dockerfiles. +Der langsame Bun-Global-Install-Image-Provider-Smoke-Test wird separat durch `run_bun_global_install_smoke` gesteuert. Er läuft im nächtlichen Zeitplan und aus dem Workflow für Release-Prüfungen heraus; manuelle `Install Smoke`-Dispatches können ihn aktivieren, Pull Requests und `main`-Pushes jedoch nicht. QR- und Installer-Docker-Tests behalten ihre eigenen installationsfokussierten Dockerfiles. -## Lokaler Docker-E2E-Test +## Lokaler Docker-E2E -`pnpm test:docker:all` baut ein gemeinsam genutztes Live-Test-Image vor, paketiert OpenClaw einmal als npm-Tarball und baut zwei gemeinsam genutzte `scripts/e2e/Dockerfile`-Images: +`pnpm test:docker:all` baut ein gemeinsam genutztes Live-Test-Image vor, packt OpenClaw einmal als npm-Tarball und baut zwei gemeinsam genutzte `scripts/e2e/Dockerfile`-Images: - einen schlanken Node-/Git-Runner für Installer-/Update-/Plugin-Abhängigkeits-Lanes; - ein funktionales Image, das denselben Tarball für normale Funktionalitäts-Lanes in `/app` installiert. -Docker-Lane-Definitionen befinden sich in `scripts/lib/docker-e2e-scenarios.mjs`, die Planner-Logik befindet sich in `scripts/lib/docker-e2e-plan.mjs`, und der Runner führt nur den ausgewählten Plan aus. Der Scheduler wählt das Image pro Lane mit `OPENCLAW_DOCKER_E2E_BARE_IMAGE` und `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` aus und führt die Lanes dann mit `OPENCLAW_SKIP_DOCKER_BUILD=1` aus. +Docker-Lane-Definitionen befinden sich in `scripts/lib/docker-e2e-scenarios.mjs`, die Planerlogik befindet sich in `scripts/lib/docker-e2e-plan.mjs`, und der Runner führt nur den ausgewählten Plan aus. Der Scheduler wählt das Image pro Lane mit `OPENCLAW_DOCKER_E2E_BARE_IMAGE` und `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` aus und führt dann Lanes mit `OPENCLAW_SKIP_DOCKER_BUILD=1` aus. ### Einstellbare Parameter -| Variable | Standardwert | Zweck | -| -------------------------------------- | ------------ | --------------------------------------------------------------------------------------------- | -| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Slot-Anzahl im Haupt-Pool für normale Lanes. | -| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Provider-sensible Slot-Anzahl im Tail-Pool. | -| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Limit für gleichzeitige Live-Lanes, damit Provider nicht drosseln. | -| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Limit für gleichzeitige npm-Install-Lanes. | -| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Limit für gleichzeitige Multi-Service-Lanes. | -| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Staffelung zwischen Lane-Starts, um Create-Stürme des Docker-Daemons zu vermeiden; setzen Sie `0`, um keine Staffelung zu verwenden. | -| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Fallback-Timeout pro Lane (120 Minuten); ausgewählte Live-/Tail-Lanes verwenden engere Limits. | -| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` gibt den Scheduler-Plan aus, ohne Lanes auszuführen. | -| `OPENCLAW_DOCKER_ALL_LANES` | unset | Kommagetrennte exakte Lane-Liste; überspringt Cleanup-Smoke, damit Agents eine fehlgeschlagene Lane reproduzieren können. | +| Variable | Standard | Zweck | +| -------------------------------------- | -------- | -------------------------------------------------------------------------------------------------- | +| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Slot-Anzahl des Haupt-Pools für normale Lanes. | +| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Slot-Anzahl des Provider-sensitiven Tail-Pools. | +| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Limit für gleichzeitige Live-Lanes, damit Provider nicht drosseln. | +| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Limit für gleichzeitige npm-Installations-Lanes. | +| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Limit für gleichzeitige Multi-Service-Lanes. | +| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Versatz zwischen Lane-Starts, um Docker-Daemon-Create-Spitzen zu vermeiden; `0` deaktiviert ihn. | +| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Fallback-Timeout pro Lane (120 Minuten); ausgewählte Live-/Tail-Lanes verwenden engere Grenzen. | +| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` gibt den Scheduler-Plan aus, ohne Lanes auszuführen. | +| `OPENCLAW_DOCKER_ALL_LANES` | unset | Kommagetrennte exakte Lane-Liste; überspringt Cleanup-Smoke, damit Agents eine fehlgeschlagene Lane reproduzieren können. | -Eine Lane, die schwerer ist als ihr effektives Limit, kann trotzdem aus einem leeren Pool starten und läuft dann allein, bis sie Kapazität freigibt. Die lokalen aggregierten Vorprüfungen prüfen Docker, entfernen veraltete OpenClaw-E2E-Container, geben den Status aktiver Lanes aus, speichern Lane-Timings für die Longest-First-Sortierung und planen standardmäßig nach dem ersten Fehler keine neuen gepoolten Lanes mehr. +Eine Lane, die schwerer als ihre effektive Grenze ist, kann trotzdem aus einem leeren Pool starten und läuft dann allein, bis sie Kapazität freigibt. Die lokale Aggregation prüft Docker vorab, entfernt veraltete OpenClaw-E2E-Container, gibt den Status aktiver Lanes aus, persistiert Lane-Timings für eine längste-zuerst-Sortierung und stoppt standardmäßig die Planung neuer gepoolter Lanes nach dem ersten Fehler. ### Wiederverwendbarer Live-/E2E-Workflow -Der wiederverwendbare Live-/E2E-Workflow fragt `scripts/test-docker-all.mjs --plan-json`, welches Paket, welche Image-Art, welches Live-Image, welche Lane und welche Credential-Abdeckung erforderlich sind. `scripts/docker-e2e.mjs` wandelt diesen Plan anschließend in GitHub-Ausgaben und Zusammenfassungen um. Er paketiert OpenClaw entweder über `scripts/package-openclaw-for-docker.mjs`, lädt ein Paketartefakt des aktuellen Laufs herunter oder lädt ein Paketartefakt aus `package_artifact_run_id` herunter; validiert das Tarball-Inventar; baut und pusht paket-digest-getaggte Bare-/Functional-GHCR-Docker-E2E-Images über Blacksmiths Docker-Layer-Cache, wenn der Plan paketinstallierte Lanes benötigt; und verwendet bereitgestellte Eingaben `docker_e2e_bare_image`/`docker_e2e_functional_image` oder vorhandene Paket-Digest-Images wieder, statt neu zu bauen. Docker-Image-Pulls werden mit einem begrenzten Timeout von 180 Sekunden pro Versuch erneut versucht, damit ein hängender Registry-/Cache-Stream schnell neu versucht wird, statt den Großteil des kritischen CI-Pfads zu verbrauchen. +Der wiederverwendbare Live-/E2E-Workflow fragt `scripts/test-docker-all.mjs --plan-json`, welche Paket-, Image-Typ-, Live-Image-, Lane- und Credential-Abdeckung erforderlich ist. `scripts/docker-e2e.mjs` wandelt diesen Plan anschließend in GitHub-Ausgaben und Zusammenfassungen um. Er packt OpenClaw entweder über `scripts/package-openclaw-for-docker.mjs`, lädt ein Paket-Artefakt des aktuellen Laufs herunter oder lädt ein Paket-Artefakt aus `package_artifact_run_id`; validiert das Tarball-Inventar; baut und pusht paket-digest-getaggte Bare-/Functional-GHCR-Docker-E2E-Images über Blacksmiths Docker-Layer-Cache, wenn der Plan Lanes mit installiertem Paket benötigt; und verwendet bereitgestellte Eingaben `docker_e2e_bare_image`/`docker_e2e_functional_image` oder vorhandene Package-Digest-Images wieder, statt neu zu bauen. Docker-Image-Pulls werden mit einem begrenzten Timeout von 180 Sekunden pro Versuch erneut versucht, sodass ein festhängender Registry-/Cache-Stream schnell wiederholt wird, statt den Großteil des kritischen CI-Pfads zu verbrauchen. ### Release-Pfad-Chunks -Release-Docker-Abdeckung läuft in kleineren Chunk-Jobs mit `OPENCLAW_SKIP_DOCKER_BUILD=1`, sodass jeder Chunk nur die benötigte Image-Art pullt und mehrere Lanes über denselben gewichteten Scheduler ausführt: +Release-Docker-Abdeckung läuft in kleineren, aufgeteilten Jobs mit `OPENCLAW_SKIP_DOCKER_BUILD=1`, sodass jeder Chunk nur den benötigten Image-Typ zieht und mehrere Lanes über denselben gewichteten Scheduler ausführt: - `OPENCLAW_DOCKER_ALL_PROFILE=release-path` - `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h` -Aktuelle Release-Docker-Chunks sind `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services` und `plugins-runtime-install-a` bis `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` und `plugins-integrations` bleiben aggregierte Plugin-/Runtime-Aliase. Der Lane-Alias `install-e2e` bleibt der aggregierte manuelle Rerun-Alias für beide Provider-Installer-Lanes. +Aktuelle Release-Docker-Chunks sind `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services` und `plugins-runtime-install-a` bis `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` und `plugins-integrations` bleiben aggregierte Plugin-/Runtime-Aliasse. Der Lane-Alias `install-e2e` bleibt der aggregierte manuelle Rerun-Alias für beide Provider-Installer-Lanes. -OpenWebUI wird in `plugins-runtime-services` aufgenommen, wenn vollständige Release-Pfad-Abdeckung es anfordert, und behält nur für OpenWebUI-only-Auslösungen einen eigenständigen Chunk `openwebui`. Update-Lanes für gebündelte Channels wiederholen bei vorübergehenden npm-Netzwerkfehlern einmal. +OpenWebUI wird in `plugins-runtime-services` integriert, wenn vollständige Release-Pfad-Abdeckung dies anfordert, und behält nur für reine OpenWebUI-Dispatches einen eigenständigen Chunk `openwebui`. Update-Lanes für gebündelte Channels wiederholen bei vorübergehenden npm-Netzwerkfehlern einmal. -Jeder Chunk lädt `.artifacts/docker-tests/` mit Lane-Protokollen, Timings, `summary.json`, `failures.json`, Phasen-Timings, Scheduler-Plan-JSON, Tabellen langsamer Lanes und Rerun-Befehlen pro Lane hoch. Die Workflow-Eingabe `docker_lanes` führt ausgewählte Lanes gegen die vorbereiteten Images aus, statt die Chunk-Jobs zu verwenden. Dadurch bleibt das Debugging fehlgeschlagener Lanes auf einen gezielten Docker-Job begrenzt, und das Paketartefakt für diesen Lauf wird vorbereitet, heruntergeladen oder wiederverwendet; wenn eine ausgewählte Lane eine Live-Docker-Lane ist, baut der gezielte Job das Live-Test-Image lokal für diesen erneuten Lauf. Generierte GitHub-Rerun-Befehle pro Lane enthalten `package_artifact_run_id`, `package_artifact_name` und vorbereitete Image-Eingaben, wenn diese Werte vorhanden sind, sodass eine fehlgeschlagene Lane exakt dasselbe Paket und dieselben Images aus dem fehlgeschlagenen Lauf wiederverwenden kann. +Jeder Chunk lädt `.artifacts/docker-tests/` mit Lane-Logs, Timings, `summary.json`, `failures.json`, Phasen-Timings, Scheduler-Plan-JSON, Tabellen langsamer Lanes und Befehlen für erneute Läufe pro Lane hoch. Die Workflow-Eingabe `docker_lanes` führt ausgewählte Lanes gegen die vorbereiteten Images aus, statt die Chunk-Jobs zu verwenden. Dadurch bleibt das Debugging fehlgeschlagener Lanes auf einen gezielten Docker-Job begrenzt und das Paket-Artefakt für diesen Lauf wird vorbereitet, heruntergeladen oder wiederverwendet; wenn eine ausgewählte Lane eine Live-Docker-Lane ist, baut der gezielte Job das Live-Test-Image lokal für diesen erneuten Lauf. Generierte GitHub-Rerun-Befehle pro Lane enthalten `package_artifact_run_id`, `package_artifact_name` und vorbereitete Image-Eingaben, sofern diese Werte vorhanden sind, sodass eine fehlgeschlagene Lane exakt dasselbe Paket und dieselben Images aus dem fehlgeschlagenen Lauf wiederverwenden kann. ```bash pnpm test:docker:rerun # download Docker artifacts and print combined/per-lane targeted rerun commands @@ -374,89 +388,89 @@ pnpm test:docker:timings # slow-lane and phase critical-path summari Der geplante Live-/E2E-Workflow führt die vollständige Release-Pfad-Docker-Suite täglich aus. -## Plugin-Prerelease +## Plugin Prerelease -`Plugin Prerelease` ist teurere Produkt-/Paket-Abdeckung und daher ein separater Workflow, der von `Full Release Validation` oder durch einen expliziten Operator ausgelöst wird. Normale Pull Requests, `main`-Pushes und eigenständige manuelle CI-Auslösungen lassen diese Suite deaktiviert. Er verteilt Tests gebündelter Plugins auf acht Extension-Worker; diese Extension-Shard-Jobs führen bis zu zwei Plugin-Konfigurationsgruppen gleichzeitig mit einem Vitest-Worker pro Gruppe und einem größeren Node-Heap aus, damit importlastige Plugin-Batches keine zusätzlichen CI-Jobs erzeugen. Der nur für Releases verwendete Docker-Prerelease-Pfad bündelt gezielte Docker-Lanes in kleinen Gruppen, um nicht Dutzende Runner für ein- bis dreiminütige Jobs zu reservieren. +`Plugin Prerelease` ist eine aufwendigere Produkt-/Paket-Abdeckung und daher ein separater Workflow, der von `Full Release Validation` oder einem expliziten Operator ausgelöst wird. Normale Pull Requests, `main`-Pushes und eigenständige manuelle CI-Dispatches lassen diese Suite deaktiviert. Er balanciert Tests gebündelter Plugins über acht Erweiterungs-Worker; diese Erweiterungs-Shard-Jobs führen bis zu zwei Plugin-Konfigurationsgruppen gleichzeitig mit einem Vitest-Worker pro Gruppe und einem größeren Node-Heap aus, damit importlastige Plugin-Batches keine zusätzlichen CI-Jobs erzeugen. Der nur für Releases vorgesehene Docker-Prerelease-Pfad bündelt gezielte Docker-Lanes in kleinen Gruppen, um nicht Dutzende Runner für ein- bis dreiminütige Jobs zu reservieren. -## QA-Lab +## QA Lab -QA-Lab verfügt über dedizierte CI-Lanes außerhalb des zentralen smart gescopten Workflows. Agentische Parität ist unter den breiten QA- und Release-Harnessen verschachtelt, kein eigenständiger PR-Workflow. Verwenden Sie `Full Release Validation` mit `rerun_group=qa-parity`, wenn Parität zusammen mit einem breiten Validierungslauf laufen soll. +QA Lab verfügt über dedizierte CI-Lanes außerhalb des hauptsächlichen Smart-Scoped-Workflows. Agentische Parität ist unter den breiten QA- und Release-Harnessen verschachtelt, nicht als eigenständiger PR-Workflow. Verwenden Sie `Full Release Validation` mit `rerun_group=qa-parity`, wenn Parität mit einem breiten Validierungslauf mitlaufen soll. -- Der Workflow `QA-Lab - All Lanes` läuft nächtlich auf `main` und bei manueller Auslösung; er fächert die Mock-Parity-Lane, die Live-Matrix-Lane sowie die Live-Telegram- und Discord-Lanes als parallele Jobs auf. Live-Jobs verwenden die Umgebung `qa-live-shared`, und Telegram/Discord verwenden Convex-Leases. +- Der Workflow `QA-Lab - All Lanes` läuft nächtlich auf `main` und bei manuellem Dispatch; er fächert die Mock-Paritäts-Lane, die Live-Matrix-Lane sowie die Live-Telegram- und Live-Discord-Lanes als parallele Jobs auf. Live-Jobs verwenden die Umgebung `qa-live-shared`, und Telegram/Discord verwenden Convex-Leases. -Release-Prüfungen führen Matrix- und Telegram-Live-Transport-Lanes mit dem deterministischen Mock-Provider und mock-qualifizierten Modellen (`mock-openai/gpt-5.5` und `mock-openai/gpt-5.5-alt`) aus, sodass der Channel-Vertrag von Live-Modell-Latenz und normalem Provider-Plugin-Start isoliert ist. Das Live-Transport-Gateway deaktiviert Memory-Suche, weil QA-Parität das Memory-Verhalten separat abdeckt; Provider-Konnektivität wird durch die separaten Suiten für Live-Modelle, native Provider und Docker-Provider abgedeckt. +Release-Prüfungen führen Matrix- und Telegram-Live-Transport-Lanes mit dem deterministischen Mock-Provider und mock-qualifizierten Modellen (`mock-openai/gpt-5.5` und `mock-openai/gpt-5.5-alt`) aus, sodass der Channel-Vertrag von Live-Modelllatenz und normalem Provider-Plugin-Start isoliert ist. Das Live-Transport-Gateway deaktiviert die Speichersuche, weil QA-Parität das Speicherverhalten separat abdeckt; Provider-Konnektivität wird durch die separaten Live-Modell-, nativen Provider- und Docker-Provider-Suites abgedeckt. -Matrix verwendet `--profile fast` für geplante und Release-Gates und ergänzt `--fail-fast` nur, wenn die ausgecheckte CLI es unterstützt. Der CLI-Standard und die manuelle Workflow-Eingabe bleiben `all`; eine manuelle Auslösung mit `matrix_profile=all` shardet die vollständige Matrix-Abdeckung immer in die Jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` und `e2ee-cli`. +Matrix verwendet `--profile fast` für geplante und Release-Gates und fügt `--fail-fast` nur hinzu, wenn die ausgecheckte CLI dies unterstützt. Der CLI-Standardwert und die manuelle Workflow-Eingabe bleiben `all`; manueller Dispatch mit `matrix_profile=all` shardet die vollständige Matrix-Abdeckung immer in die Jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` und `e2ee-cli`. -`OpenClaw Release Checks` führt außerdem die release-kritischen QA-Lab-Lanes vor der Release-Freigabe aus; sein QA-Parity-Gate führt die Candidate- und Baseline-Pakete als parallele Lane-Jobs aus und lädt anschließend beide Artefakte in einen kleinen Report-Job für den finalen Paritätsvergleich herunter. +`OpenClaw Release Checks` führt außerdem die release-kritischen QA-Lab-Lanes vor der Release-Genehmigung aus; sein QA-Paritäts-Gate führt Kandidaten- und Baseline-Pakete als parallele Lane-Jobs aus und lädt anschließend beide Artefakte in einen kleinen Berichtsjob für den abschließenden Paritätsvergleich herunter. -Für normale PRs folgen Sie gescopten CI-/Prüfnachweisen, statt Parität als erforderlichen Status zu behandeln. +Für normale PRs folgen Sie gescopter CI-/Check-Evidenz, statt Parität als erforderlichen Status zu behandeln. ## CodeQL -Der `CodeQL`-Workflow ist bewusst als schlanker Security-Scanner für den ersten Durchlauf angelegt, nicht als vollständiger Repository-Sweep. Tägliche, manuelle und nicht als Draft markierte Pull-Request-Guard-Läufe scannen Actions-Workflow-Code sowie die JavaScript/TypeScript-Oberflächen mit dem höchsten Risiko, mit Security-Abfragen mit hoher Konfidenz, gefiltert auf hohe/kritische `security-severity`. +Der `CodeQL`-Workflow ist bewusst ein schmaler Sicherheits-Scan im ersten Durchlauf, nicht der vollständige Repository-Durchlauf. Tägliche, manuelle und nicht als Entwurf markierte Pull-Request-Guard-Läufe scannen Actions-Workflow-Code plus die JavaScript-/TypeScript-Oberflächen mit dem höchsten Risiko mit hochzuverlässigen Sicherheitsabfragen, gefiltert auf hohe/kritische `security-severity`. -Der Pull-Request-Guard bleibt leichtgewichtig: Er startet nur bei Änderungen unter `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` oder `src` und führt dieselbe Security-Matrix mit hoher Konfidenz aus wie der geplante Workflow. Android- und macOS-CodeQL bleiben außerhalb der PR-Standards. +Der Pull-Request-Guard bleibt schlank: Er startet nur bei Änderungen unter `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` oder `src`, und er führt dieselbe hochzuverlässige Sicherheitsmatrix aus wie der geplante Workflow. Android- und macOS-CodeQL bleiben außerhalb der PR-Standardeinstellungen. -### Security-Kategorien +### Sicherheitskategorien -| Kategorie | Oberfläche | -| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -| `/codeql-security-high/core-auth-secrets` | Authentifizierung, Secrets, Sandbox, Cron und Gateway-Basis | -| `/codeql-security-high/channel-runtime-boundary` | Implementierungsverträge des Kern-Channel sowie Channel-Plugin-Runtime, Gateway, Plugin SDK, Secrets und Audit-Berührungspunkte | -| `/codeql-security-high/network-ssrf-boundary` | Core-SSRF, IP-Parsing, Network Guard, Web-Fetch und SSRF-Policy-Oberflächen des Plugin SDK | -| `/codeql-security-high/mcp-process-tool-boundary` | MCP-Server, Hilfsfunktionen für Prozessausführung, ausgehende Zustellung und Agent-Gates für Tool-Ausführung | -| `/codeql-security-high/plugin-trust-boundary` | Plugin-Installation, Loader, Manifest, Registry, Package-Manager-Installation, Source-Loading und Vertrauensoberflächen des Plugin-SDK-Package-Vertrags | +| Kategorie | Oberfläche | +| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `/codeql-security-high/core-auth-secrets` | Authentifizierung, Secrets, Sandbox, Cron und Gateway-Baseline | +| `/codeql-security-high/channel-runtime-boundary` | Implementierungsverträge des Core-Kanals plus Channel-Plugin-Laufzeit, Gateway, Plugin SDK, Secrets, Audit-Berührungspunkte | +| `/codeql-security-high/network-ssrf-boundary` | Core-SSRF, IP-Parsing, Netzwerk-Guard, Web-Fetch und SSRF-Richtlinienoberflächen des Plugin SDK | +| `/codeql-security-high/mcp-process-tool-boundary` | MCP-Server, Hilfsfunktionen zur Prozessausführung, ausgehende Zustellung und Gates für die Tool-Ausführung von Agenten | +| `/codeql-security-high/plugin-trust-boundary` | Plugin-Installation, Loader, Manifest, Registry, Package-Manager-Installation, Source-Loading und Vertrauensoberflächen des Plugin-SDK-Paketvertrags | -### Plattformspezifische Security-Shards +### Plattformspezifische Sicherheits-Shards -- `CodeQL Android Critical Security` — geplanter Android-Security-Shard. Baut die Android-App manuell für CodeQL auf dem kleinsten Blacksmith-Linux-Runner, der von der Workflow-Sanity akzeptiert wird. Lädt unter `/codeql-critical-security/android` hoch. -- `CodeQL macOS Critical Security` — wöchentlicher/manueller macOS-Security-Shard. Baut die macOS-App manuell für CodeQL auf Blacksmith macOS, filtert Build-Ergebnisse von Abhängigkeiten aus hochgeladenem SARIF heraus und lädt unter `/codeql-critical-security/macos` hoch. Bleibt außerhalb der täglichen Standards, weil der macOS-Build die Laufzeit selbst bei sauberen Ergebnissen dominiert. +- `CodeQL Android Critical Security` — geplanter Android-Sicherheits-Shard. Baut die Android-App manuell für CodeQL auf dem kleinsten Blacksmith-Linux-Runner, der von der Workflow-Sanity-Prüfung akzeptiert wird. Lädt unter `/codeql-critical-security/android` hoch. +- `CodeQL macOS Critical Security` — wöchentlicher/manueller macOS-Sicherheits-Shard. Baut die macOS-App manuell für CodeQL auf Blacksmith macOS, filtert Build-Ergebnisse von Abhängigkeiten aus der hochgeladenen SARIF-Datei heraus und lädt unter `/codeql-critical-security/macos` hoch. Bleibt außerhalb der täglichen Standardeinstellungen, weil der macOS-Build die Laufzeit auch im sauberen Zustand dominiert. ### Critical-Quality-Kategorien -`CodeQL Critical Quality` ist der entsprechende Nicht-Security-Shard. Er führt nur JavaScript/TypeScript-Quality-Abfragen mit Error-Schweregrad und ohne Security-Bezug über schlanke, hochwertige Oberflächen auf dem kleineren Blacksmith-Linux-Runner aus. Sein Pull-Request-Guard ist bewusst kleiner als das geplante Profil: Nicht als Draft markierte PRs führen nur die passenden Shards `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` und `plugin-sdk-reply-runtime` aus, wenn sich Code für Agent-Befehl-/Modell-/Tool-Ausführung und Antwort-Dispatch, Config-Schema/Migration/IO, Authentifizierung/Secrets/Sandbox/Security, Kern-Channel und gebündelte Channel-Plugin-Runtime, Gateway-Protokoll/Servermethode, Memory-Runtime/SDK-Verknüpfung, MCP/Prozess/ausgehende Zustellung, Provider-Runtime/Modellkatalog, Sitzungsdiagnostik/Zustellwarteschlangen, Plugin-Loader, Plugin-SDK/Package-Vertrag oder Plugin-SDK-Antwort-Runtime ändert. CodeQL-Config- und Quality-Workflow-Änderungen führen alle zwölf PR-Quality-Shards aus. +`CodeQL Critical Quality` ist der passende nicht sicherheitsbezogene Shard. Er führt nur JavaScript-/TypeScript-Qualitätsabfragen mit Error-Schweregrad und ohne Sicherheitsbezug über schmale, hochwertige Oberflächen auf dem kleineren Blacksmith-Linux-Runner aus. Sein Pull-Request-Guard ist bewusst kleiner als das geplante Profil: Nicht als Entwurf markierte PRs führen nur die passenden Shards `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` und `plugin-sdk-reply-runtime` für Änderungen an Agent-Befehls-/Modell-/Tool-Ausführung und Antwort-Dispatch-Code, Konfigurationsschema-/Migrations-/IO-Code, Authentifizierungs-/Secrets-/Sandbox-/Sicherheitscode, Core-Kanal- und gebündelter Channel-Plugin-Laufzeit, Gateway-Protokoll-/Server-Methoden, Memory-Laufzeit-/SDK-Verbindungscode, MCP-/Prozess-/ausgehender Zustellung, Provider-Laufzeit-/Modellkatalog, Sitzungsdiagnose-/Zustellungswarteschlangen, Plugin-Loader, Plugin-SDK-/Paketvertrag oder Plugin-SDK-Antwortlaufzeit aus. Änderungen an CodeQL-Konfiguration und Qualitäts-Workflow führen alle zwölf PR-Quality-Shards aus. -Manuelle Ausführung akzeptiert: +Manueller Dispatch akzeptiert: ``` profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary ``` -Die schlanken Profile sind Lehr- und Iterations-Hooks, um einen Quality-Shard isoliert auszuführen. +Die schmalen Profile sind Lehr-/Iterations-Hooks, um einen Qualitäts-Shard isoliert auszuführen. -| Kategorie | Oberfläche | -| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `/codeql-critical-quality/core-auth-secrets` | Code für Authentifizierung, Secrets, Sandbox, Cron und Gateway-Security-Grenzen | -| `/codeql-critical-quality/config-boundary` | Config-Schema, Migration, Normalisierung und IO-Verträge | -| `/codeql-critical-quality/gateway-runtime-boundary` | Gateway-Protokollschemas und Servermethodenverträge | -| `/codeql-critical-quality/channel-runtime-boundary` | Implementierungsverträge des Kern-Channel und gebündelter Channel-Plugins | -| `/codeql-critical-quality/agent-runtime-boundary` | Befehlsausführung, Modell-/Provider-Dispatch, Auto-Reply-Dispatch und Warteschlangen sowie ACP-Control-Plane-Runtime-Verträge | -| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP-Server und Tool-Bridges, Hilfsfunktionen zur Prozessüberwachung und Verträge für ausgehende Zustellung | -| `/codeql-critical-quality/memory-runtime-boundary` | Memory-Host-SDK, Memory-Runtime-Fassaden, Memory-Plugin-SDK-Aliasse, Verknüpfung zur Memory-Runtime-Aktivierung und Memory-Doctor-Befehle | -| `/codeql-critical-quality/session-diagnostics-boundary` | Interna der Antwortwarteschlange, Sitzungszustellwarteschlangen, Hilfsfunktionen für ausgehende Sitzungsbindung/-zustellung, Diagnoseereignis-/Log-Bundle-Oberflächen und CLI-Verträge des Sitzungs-Doctors | -| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Inbound-Reply-Dispatch des Plugin SDK, Hilfsfunktionen für Reply-Payload/Chunking/Runtime, Channel-Antwortoptionen, Zustellwarteschlangen und Hilfsfunktionen für Session-/Thread-Bindung | -| `/codeql-critical-quality/provider-runtime-boundary` | Modellkatalog-Normalisierung, Provider-Authentifizierung und -Discovery, Provider-Runtime-Registrierung, Provider-Standards/-Kataloge sowie Web-/Search-/Fetch-/Embedding-Registries | -| `/codeql-critical-quality/ui-control-plane` | Control-UI-Bootstrap, lokale Persistenz, Gateway-Control-Flows und Task-Control-Plane-Runtime-Verträge | -| `/codeql-critical-quality/web-media-runtime-boundary` | Core-Web-Fetch/Search, Media-IO, Medienverständnis, Image-Generation und Media-Generation-Runtime-Verträge | -| `/codeql-critical-quality/plugin-boundary` | Loader-, Registry-, Public-Surface- und Plugin-SDK-Entrypoint-Verträge | -| `/codeql-critical-quality/plugin-sdk-package-contract` | Veröffentlichter Package-seitiger Plugin-SDK-Quellcode und Hilfsfunktionen für Plugin-Package-Verträge | +| Kategorie | Oberfläche | +| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `/codeql-critical-quality/core-auth-secrets` | Authentifizierung, Secrets, Sandbox, Cron und Code der Gateway-Sicherheitsgrenze | +| `/codeql-critical-quality/config-boundary` | Konfigurationsschema, Migration, Normalisierung und IO-Verträge | +| `/codeql-critical-quality/gateway-runtime-boundary` | Gateway-Protokollschemata und Server-Methodenverträge | +| `/codeql-critical-quality/channel-runtime-boundary` | Implementierungsverträge für Core-Kanal und gebündeltes Channel-Plugin | +| `/codeql-critical-quality/agent-runtime-boundary` | Befehlsausführung, Modell-/Provider-Dispatch, Auto-Reply-Dispatch und Warteschlangen sowie ACP-Control-Plane-Laufzeitverträge | +| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP-Server und Tool-Bridges, Hilfsfunktionen zur Prozessüberwachung und Verträge für ausgehende Zustellung | +| `/codeql-critical-quality/memory-runtime-boundary` | Memory Host SDK, Memory-Laufzeitfassaden, Memory-Plugin-SDK-Aliasse, Verbindungscode zur Aktivierung der Memory-Laufzeit und Memory-Doctor-Befehle | +| `/codeql-critical-quality/session-diagnostics-boundary` | Interna der Antwortwarteschlange, Sitzungszustellungswarteschlangen, Hilfsfunktionen für ausgehende Sitzungsbindung/-zustellung, Diagnoseereignis-/Log-Bundle-Oberflächen und CLI-Verträge des Sitzungs-Doctor | +| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Eingehender Antwort-Dispatch des Plugin SDK, Antwort-Payload-/Chunking-/Laufzeit-Hilfsfunktionen, Channel-Antwortoptionen, Zustellungswarteschlangen und Hilfsfunktionen zur Sitzungs-/Thread-Bindung | +| `/codeql-critical-quality/provider-runtime-boundary` | Normalisierung des Modellkatalogs, Provider-Authentifizierung und -Discovery, Provider-Laufzeitregistrierung, Provider-Standardeinstellungen/-Kataloge sowie Web-/Search-/Fetch-/Embedding-Registries | +| `/codeql-critical-quality/ui-control-plane` | Bootstrap der Control UI, lokale Persistenz, Gateway-Control-Flows und Task-Control-Plane-Laufzeitverträge | +| `/codeql-critical-quality/web-media-runtime-boundary` | Core-Web-Fetch/Search, Medien-IO, Medienverständnis, Bildgenerierung und Laufzeitverträge für Mediengenerierung | +| `/codeql-critical-quality/plugin-boundary` | Loader-, Registry-, Public-Surface- und Plugin-SDK-Entrypoint-Verträge | +| `/codeql-critical-quality/plugin-sdk-package-contract` | Veröffentlichter paketbasierter Plugin-SDK-Quellcode und Hilfsfunktionen für Plugin-Paketverträge | -Quality bleibt von Security getrennt, damit Quality-Findings geplant, gemessen, deaktiviert oder erweitert werden können, ohne das Security-Signal zu verdecken. Swift-, Python- und gebündelte-Plugin-CodeQL-Erweiterung sollte erst dann als gescopter oder geshardeter Follow-up wieder hinzugefügt werden, wenn die schlanken Profile stabile Laufzeit und stabiles Signal haben. +Quality bleibt von Security getrennt, damit Quality-Befunde geplant, gemessen, deaktiviert oder erweitert werden können, ohne das Security-Signal zu verdecken. Die Erweiterung von CodeQL für Swift, Python und gebündelte Plugins sollte erst wieder als eingegrenzte oder geshardete Folgearbeit hinzugefügt werden, nachdem die schmalen Profile stabile Laufzeit und stabile Signale haben. ## Wartungs-Workflows ### Docs Agent -Der `Docs Agent`-Workflow ist eine ereignisgesteuerte Codex-Wartungsspur, um bestehende Dokumentation mit kürzlich gelandeten Änderungen abzugleichen. Er hat keinen reinen Zeitplan: Ein erfolgreicher Nicht-Bot-Push-CI-Lauf auf `main` kann ihn auslösen, und eine manuelle Ausführung kann ihn direkt starten. Workflow-Run-Aufrufe werden übersprungen, wenn `main` weitergezogen ist oder wenn in der letzten Stunde bereits ein anderer nicht übersprungener Docs-Agent-Lauf erstellt wurde. Wenn er ausgeführt wird, prüft er den Commit-Bereich vom vorherigen nicht übersprungenen Docs-Agent-Quell-SHA bis zum aktuellen `main`, sodass ein stündlicher Lauf alle Main-Änderungen abdecken kann, die seit dem letzten Dokumentationsdurchlauf angefallen sind. +Der `Docs Agent`-Workflow ist eine ereignisgesteuerte Codex-Wartungsspur, um bestehende Dokumentation mit kürzlich gelandeten Änderungen abzugleichen. Er hat keinen reinen Zeitplan: Ein erfolgreicher nicht von Bots stammender Push-CI-Lauf auf `main` kann ihn auslösen, und manueller Dispatch kann ihn direkt ausführen. Workflow-Run-Aufrufe werden übersprungen, wenn `main` weitergewandert ist oder wenn in der letzten Stunde ein anderer nicht übersprungener Docs-Agent-Lauf erstellt wurde. Wenn er läuft, überprüft er den Commit-Bereich von der vorherigen nicht übersprungenen Docs-Agent-Quell-SHA bis zum aktuellen `main`, sodass ein stündlicher Lauf alle seit dem letzten Dokumentationsdurchlauf angesammelten Main-Änderungen abdecken kann. ### Test Performance Agent -Der `Test Performance Agent`-Workflow ist eine ereignisgesteuerte Codex-Wartungsspur für langsame Tests. Er hat keinen reinen Zeitplan: Ein erfolgreicher Nicht-Bot-Push-CI-Lauf auf `main` kann ihn auslösen, aber er wird übersprungen, wenn am selben UTC-Tag bereits ein anderer Workflow-Run-Aufruf gelaufen ist oder läuft. Manuelle Ausführung umgeht dieses tägliche Aktivitäts-Gate. Die Spur erstellt einen gruppierten Vitest-Performance-Bericht für die vollständige Suite, lässt Codex nur kleine, coverage-erhaltende Test-Performance-Korrekturen statt breiter Refactorings vornehmen, führt anschließend den Bericht für die vollständige Suite erneut aus und verwirft Änderungen, die die Baseline-Anzahl bestandener Tests reduzieren. Wenn die Baseline fehlgeschlagene Tests enthält, darf Codex nur offensichtliche Fehler beheben, und der Full-Suite-Bericht nach dem Agent muss bestehen, bevor etwas committed wird. Wenn `main` vor dem Bot-Push weiterläuft, rebased die Spur den validierten Patch, führt `pnpm check:changed` erneut aus und versucht den Push erneut; konfliktbehaftete veraltete Patches werden übersprungen. Sie verwendet GitHub-gehostetes Ubuntu, damit die Codex-Action dieselbe Drop-Sudo-Sicherheitsposition wie der Docs Agent beibehalten kann. +Der `Test Performance Agent`-Workflow ist eine ereignisgesteuerte Codex-Wartungsspur für langsame Tests. Er hat keinen reinen Zeitplan: Ein erfolgreicher nicht von Bots stammender Push-CI-Lauf auf `main` kann ihn auslösen, aber er wird übersprungen, wenn an diesem UTC-Tag bereits ein anderer Workflow-Run-Aufruf gelaufen ist oder gerade läuft. Manueller Dispatch umgeht dieses tägliche Aktivitäts-Gate. Die Spur erstellt einen gruppierten Vitest-Performance-Bericht für die vollständige Suite, lässt Codex nur kleine, die Abdeckung erhaltende Test-Performance-Fixes statt breiter Refactorings vornehmen, führt anschließend den Bericht für die vollständige Suite erneut aus und verwirft Änderungen, die die Baseline-Anzahl bestandener Tests verringern. Wenn die Baseline fehlschlagende Tests enthält, darf Codex nur offensichtliche Fehler beheben, und der Full-Suite-Bericht nach dem Agenten muss bestehen, bevor etwas committet wird. Wenn `main` vor dem Bot-Push weiterläuft, rebaset die Spur den validierten Patch, führt `pnpm check:changed` erneut aus und versucht den Push erneut; kollidierende veraltete Patches werden übersprungen. Sie verwendet GitHub-gehostetes Ubuntu, damit die Codex-Action dieselbe Drop-Sudo-Sicherheitshaltung wie der Docs Agent beibehalten kann. -### Doppelte PRs nach Merge +### Duplicate PRs After Merge -Der `Duplicate PRs After Merge`-Workflow ist ein manueller Maintainer-Workflow für die Duplikatbereinigung nach dem Landen. Er ist standardmäßig ein Dry-Run und schließt nur explizit aufgelistete PRs, wenn `apply=true` gesetzt ist. Vor dem Ändern von GitHub prüft er, dass der gelandete PR gemerged wurde und dass jedes Duplikat entweder ein gemeinsam referenziertes Issue oder überlappende geänderte Hunks hat. +Der `Duplicate PRs After Merge`-Workflow ist ein manueller Maintainer-Workflow für die Bereinigung von Duplikaten nach dem Landen. Er verwendet standardmäßig Dry-Run und schließt nur explizit aufgelistete PRs, wenn `apply=true` gesetzt ist. Vor Änderungen an GitHub überprüft er, dass der gelandete PR gemergt ist und dass jedes Duplikat entweder ein gemeinsam referenziertes Issue oder überlappende geänderte Hunks hat. ```bash gh workflow run duplicate-after-merge.yml \ @@ -467,38 +481,115 @@ gh workflow run duplicate-after-merge.yml \ ## Lokale Check-Gates und Changed-Routing -Die lokale Changed-Lane-Logik befindet sich in `scripts/changed-lanes.mjs` und wird von `scripts/check-changed.mjs` ausgeführt. Dieses lokale Check-Gate ist bei Architekturgrenzen strenger als der breite CI-Plattform-Scope: +Die lokale Changed-Lane-Logik liegt in `scripts/changed-lanes.mjs` und wird von `scripts/check-changed.mjs` ausgeführt. Dieses lokale Check-Gate ist bei Architekturgrenzen strenger als der breite CI-Plattformumfang: -- Änderungen an Core-Produktionscode führen Core-Prod- und Core-Test-Typecheck sowie Core-Lint/Guards aus; -- reine Änderungen an Core-Tests führen nur Core-Test-Typecheck plus Core-Lint aus; +- Änderungen an Core-Produktionscode führen Core-Prod- und Core-Test-Typecheck plus Core-Lint/-Guards aus; +- Änderungen nur an Core-Tests führen nur Core-Test-Typecheck plus Core-Lint aus; - Änderungen an Extension-Produktionscode führen Extension-Prod- und Extension-Test-Typecheck plus Extension-Lint aus; -- reine Änderungen an Extension-Tests führen Extension-Test-Typecheck plus Extension-Lint aus; -- Änderungen am öffentlichen Plugin SDK oder am Plugin-Vertrag erweitern auf Extension-Typecheck, weil Extensions von diesen Core-Verträgen abhängen (Vitest-Extension-Sweeps bleiben explizite Testarbeit); -- reine Versionsbump-Änderungen an Release-Metadaten führen gezielte Versions-/Config-/Root-Abhängigkeitsprüfungen aus; -- unbekannte Root-/Config-Änderungen fallen sicherheitshalber auf alle Check-Lanes zurück. +- Änderungen nur an Extension-Tests führen Extension-Test-Typecheck plus Extension-Lint aus; +- Änderungen am öffentlichen Plugin SDK oder an Plugin-Contracts erweitern auf Extension-Typecheck, weil Extensions von diesen Core-Verträgen abhängen (Vitest-Extension-Sweeps bleiben explizite Testarbeit); +- Release-Metadaten-only-Version-Bumps führen gezielte Versions-/Konfigurations-/Root-Abhängigkeitsprüfungen aus; +- unbekannte Root-/Konfigurationsänderungen fallen sicherheitshalber auf alle Check-Lanes zurück. -Das lokale Changed-Test-Routing befindet sich in `scripts/test-projects.test-support.mjs` und ist bewusst günstiger als `check:changed`: Direkte Teständerungen führen sich selbst aus, Quellcodeänderungen bevorzugen explizite Zuordnungen, danach Geschwistertests und Import-Graph-Abhängige. Gemeinsame Group-Room-Delivery-Config ist eine der expliziten Zuordnungen: Änderungen an der für die Gruppe sichtbaren Reply-Config, am Source-Reply-Delivery-Modus oder am System-Prompt des Message-Tools laufen über die Core-Reply-Tests plus Discord- und Slack-Delivery-Regressionen, damit eine gemeinsame Standardänderung vor dem ersten PR-Push fehlschlägt. Verwenden Sie `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` nur, wenn die Änderung harness-weit genug ist, dass der günstige zugeordnete Satz kein vertrauenswürdiger Proxy ist. +Das lokale Changed-Test-Routing liegt in `scripts/test-projects.test-support.mjs` und ist bewusst günstiger als `check:changed`: Direkte Teständerungen führen sich selbst aus, Quellcodeänderungen bevorzugen explizite Mappings, danach gleichgeordnete Tests und Import-Graph-Abhängige. Die gemeinsame Group-Room-Zustellungskonfiguration ist eines der expliziten Mappings: Änderungen an der für Gruppen sichtbaren Antwortkonfiguration, am Quell-Antwortzustellungsmodus oder am System-Prompt des Message-Tools laufen über die Core-Antworttests plus Discord- und Slack-Zustellungsregressionen, damit eine gemeinsame Standardänderung vor dem ersten PR-Push fehlschlägt. Verwenden Sie `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` nur, wenn die Änderung so harness-weit ist, dass die günstige gemappte Menge kein vertrauenswürdiger Proxy ist. ## Testbox-Validierung -Führen Sie Testbox aus dem Repo-Root aus und bevorzugen Sie eine frisch vorgewärmte Box für umfassenden Nachweis. Bevor Sie ein langsames Gate auf eine Box verwenden, die wiederverwendet wurde, abgelaufen ist oder gerade einen unerwartet großen Sync gemeldet hat, führen Sie zuerst `pnpm testbox:sanity` in der Box aus. +Führen Sie Testbox aus dem Repo-Root aus und bevorzugen Sie für breiten Nachweis eine frisch vorgewärmte Box. Bevor Sie eine langsame Gate-Prüfung auf einer Box ausführen, die wiederverwendet wurde, abgelaufen ist oder gerade eine unerwartet große Synchronisierung gemeldet hat, führen Sie zuerst `pnpm testbox:sanity` in der Box aus. -Der Sanity-Check schlägt schnell fehl, wenn erforderliche Root-Dateien wie `pnpm-lock.yaml` verschwunden sind oder wenn `git status --short` mindestens 200 nachverfolgte Löschungen anzeigt. Das bedeutet normalerweise, dass der Remote-Sync-Status keine vertrauenswürdige Kopie des PR ist; stoppen Sie diese Box und wärmen Sie stattdessen eine frische vor, anstatt den Produkttestfehler zu debuggen. Setzen Sie für beabsichtigte PRs mit vielen Löschungen `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` für diesen Sanity-Lauf. +Die Sanity-Prüfung schlägt schnell fehl, wenn erforderliche Root-Dateien wie `pnpm-lock.yaml` verschwunden sind oder wenn `git status --short` mindestens 200 nachverfolgte Löschungen anzeigt. Das bedeutet normalerweise, dass der Remote-Sync-Zustand keine vertrauenswürdige Kopie des PR ist; stoppen Sie diese Box und wärmen Sie stattdessen eine frische vor, anstatt den Produkttestfehler zu debuggen. Für absichtliche PRs mit vielen Löschungen setzen Sie für diesen Sanity-Lauf `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1`. -`pnpm testbox:run` beendet außerdem einen lokalen Blacksmith CLI-Aufruf, der länger als fünf Minuten in der Sync-Phase bleibt, ohne Ausgabe nach dem Sync zu liefern. Setzen Sie `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, um diese Schutzmaßnahme zu deaktivieren, oder verwenden Sie einen größeren Millisekundenwert für ungewöhnlich große lokale Diffs. +`pnpm testbox:run` beendet außerdem einen lokalen Blacksmith-CLI-Aufruf, der länger als fünf Minuten ohne Ausgabe nach der Synchronisierung in der Sync-Phase bleibt. Setzen Sie `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, um diesen Schutz zu deaktivieren, oder verwenden Sie einen größeren Millisekundenwert für ungewöhnlich große lokale Diffs. -Crabbox ist der repo-eigene zweite Remote-Box-Pfad für Linux-Nachweis, wenn Blacksmith nicht verfügbar ist oder wenn eigene Cloud-Kapazität vorzuziehen ist. Wärmen Sie eine Box vor, hydratisieren Sie sie über den Projekt-Workflow und führen Sie dann Befehle über die Crabbox CLI aus: +Crabbox ist der repo-eigene Remote-Box-Wrapper für Linux-Nachweise durch Maintainer. Verwenden Sie ihn, wenn eine Prüfung zu breit für einen lokalen Bearbeitungs-Loop ist, wenn CI-Parität wichtig ist oder wenn der Nachweis Secrets, Docker, Paket-Lanes, wiederverwendbare Boxen oder Remote-Logs benötigt. Das normale OpenClaw-Backend ist `blacksmith-testbox`; eigene AWS/Hetzner-Kapazität ist ein Fallback für Blacksmith-Ausfälle, Quotenprobleme oder explizite Tests mit eigener Kapazität. + +Prüfen Sie vor einem ersten Lauf den Wrapper aus dem Repo-Root: ```bash -pnpm crabbox:warmup -- --idle-timeout 90m -pnpm crabbox:hydrate -- --id -pnpm crabbox:run -- --id --shell "OPENCLAW_TESTBOX=1 pnpm check:changed" -pnpm crabbox:stop -- +pnpm crabbox:run -- --help | sed -n '1,120p' ``` -`.crabbox.yaml` verwaltet die Standardwerte für Provider, Sync und GitHub Actions-Hydration. Sie schließt das lokale `.git` aus, damit der hydratisierte Actions-Checkout seine eigenen Remote-Git-Metadaten behält, anstatt maintainer-lokale Remotes und Objektspeicher zu synchronisieren, und sie schließt lokale Laufzeit-/Build-Artefakte aus, die niemals übertragen werden sollten. `.github/workflows/crabbox-hydrate.yml` verwaltet Checkout, Node-/pnpm-Einrichtung, `origin/main`-Fetch und die nicht geheimen Umgebungswerte, die spätere `crabbox run --id `-Befehle einlesen. +Der Repo-Wrapper verweigert eine veraltete Crabbox-Binärdatei, die `blacksmith-testbox` nicht ausweist. Geben Sie den Provider explizit an, obwohl `.crabbox.yaml` Standardwerte für die eigene Cloud enthält. -## Zugehörig +Changed-Gate: + +```bash +pnpm crabbox:run -- --provider blacksmith-testbox \ + --blacksmith-org openclaw \ + --blacksmith-workflow .github/workflows/ci-check-testbox.yml \ + --blacksmith-job check \ + --blacksmith-ref main \ + --idle-timeout 90m \ + --ttl 240m \ + --timing-json \ + --shell -- \ + "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed" +``` + +Fokussierte Testwiederholung: + +```bash +pnpm crabbox:run -- --provider blacksmith-testbox \ + --blacksmith-org openclaw \ + --blacksmith-workflow .github/workflows/ci-check-testbox.yml \ + --blacksmith-job check \ + --blacksmith-ref main \ + --idle-timeout 90m \ + --ttl 240m \ + --timing-json \ + --shell -- \ + "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test " +``` + +Vollständige Suite: + +```bash +pnpm crabbox:run -- --provider blacksmith-testbox \ + --blacksmith-org openclaw \ + --blacksmith-workflow .github/workflows/ci-check-testbox.yml \ + --blacksmith-job check \ + --blacksmith-ref main \ + --idle-timeout 90m \ + --ttl 240m \ + --timing-json \ + --shell -- \ + "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test" +``` + +Lesen Sie die abschließende JSON-Zusammenfassung. Die nützlichen Felder sind `provider`, `leaseId`, `syncDelegated`, `exitCode`, `commandMs` und `totalMs`. Einmalige Blacksmith-gestützte Crabbox-Läufe sollten die Testbox automatisch stoppen; wenn ein Lauf unterbrochen wurde oder die Bereinigung unklar ist, prüfen Sie die Live-Boxen und stoppen Sie nur die Boxen, die Sie erstellt haben: + +```bash +blacksmith testbox list +blacksmith testbox stop --id +``` + +Verwenden Sie Wiederverwendung nur, wenn Sie absichtlich mehrere Befehle auf derselben hydratisierten Box benötigen: + +```bash +pnpm crabbox:run -- --provider blacksmith-testbox --id --no-sync --timing-json --shell -- "pnpm test " +pnpm crabbox:stop -- +``` + +Wenn Crabbox die defekte Schicht ist, Blacksmith selbst aber funktioniert, verwenden Sie direktes Blacksmith als engen Fallback: + +```bash +blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90 +blacksmith testbox run --id "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed" +blacksmith testbox stop --id +``` + +Eskalieren Sie nur dann auf eigene Crabbox-Kapazität, wenn Blacksmith ausgefallen, durch Quoten begrenzt oder ohne die benötigte Umgebung ist oder wenn eigene Kapazität explizit das Ziel ist: + +```bash +pnpm crabbox:warmup -- --provider aws --class beast --market on-demand --idle-timeout 90m +pnpm crabbox:hydrate -- --id +pnpm crabbox:run -- --id --timing-json --shell -- "env NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed" +pnpm crabbox:stop -- +``` + +`.crabbox.yaml` verwaltet die Standardwerte für Provider, Synchronisierung und GitHub-Actions-Hydratisierung für eigene Cloud-Lanes. Sie schließt lokales `.git` aus, damit der hydratisierte Actions-Checkout seine eigenen Remote-Git-Metadaten behält, anstatt maintainer-lokale Remotes und Objektspeicher zu synchronisieren, und sie schließt lokale Laufzeit-/Build-Artefakte aus, die niemals übertragen werden sollten. `.github/workflows/crabbox-hydrate.yml` verwaltet Checkout, Node-/pnpm-Einrichtung, `origin/main`-Fetch und die nicht geheime Umgebungsübergabe für eigene Cloud-Befehle vom Typ `crabbox run --id `. + +## Verwandt - [Installationsübersicht](/de/install) - [Entwicklungskanäle](/de/install/development-channels) diff --git a/docs/de/cli/plugins.md b/docs/de/cli/plugins.md index d5b419ff8..765218735 100644 --- a/docs/de/cli/plugins.md +++ b/docs/de/cli/plugins.md @@ -6,31 +6,31 @@ sidebarTitle: Plugins summary: CLI-Referenz für `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor) title: Plugins x-i18n: - generated_at: "2026-05-03T21:29:21Z" + generated_at: "2026-05-04T06:41:24Z" model: gpt-5.5 provider: openai - source_hash: d854d052b0a012a86f9c775775676a9a8fe8ae86b2c38a18118f1abf0732174c + source_hash: 36ae7edb12986ead7e126f25e0761bf312b2644b35017181b674082105886776 source_path: cli/plugins.md workflow: 16 --- -Gateway-Plugins, Hook-Packs und kompatible Bundles verwalten. +Verwalten Sie Gateway-Plugins, Hook-Packs und kompatible Bundles. Leitfaden für Endbenutzer zum Installieren, Aktivieren und Beheben von Problemen mit Plugins. - Kurze Beispiele für Installation, Auflistung, Aktualisierung, Deinstallation und Veröffentlichung. + Kurze Beispiele für Installation, Auflisten, Aktualisierung, Deinstallation und Veröffentlichung. - Kompatibilitätsmodell für Bundles. + Bundle-Kompatibilitätsmodell. - Manifestfelder und Konfigurationsschema. + Manifest-Felder und Konfigurationsschema. - Sicherheitshärtung für Plugin-Installationen. + Sicherheits-Härtung für Plugin-Installationen. @@ -62,16 +62,14 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -Für die Untersuchung langsamer Installations-, Inspect-, Deinstallations- oder Registry-Aktualisierungsvorgänge führen Sie den -Befehl mit `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` aus. Der Trace schreibt Phasen-Timings -nach stderr und hält JSON-Ausgaben weiterhin parsebar. Siehe [Debugging](/de/help/debugging#plugin-lifecycle-trace). +Führen Sie zur Untersuchung langsamer Installations-, Inspektions-, Deinstallations- oder Registry-Aktualisierungsvorgänge den Befehl mit `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` aus. Der Trace schreibt Phasen-Timings nach stderr und hält die JSON-Ausgabe parsebar. Siehe [Debugging](/de/help/debugging#plugin-lifecycle-trace). Gebündelte Plugins werden mit OpenClaw ausgeliefert. Einige sind standardmäßig aktiviert (zum Beispiel gebündelte Modell-Provider, gebündelte Sprach-Provider und das gebündelte Browser-Plugin); andere erfordern `plugins enable`. -Native OpenClaw-Plugins müssen `openclaw.plugin.json` mit einem eingebetteten JSON Schema (`configSchema`, auch wenn leer) ausliefern. Kompatible Bundles verwenden stattdessen ihre eigenen Bundle-Manifeste. +Native OpenClaw-Plugins müssen `openclaw.plugin.json` mit einem Inline-JSON-Schema (`configSchema`, auch wenn leer) ausliefern. Kompatible Bundles verwenden stattdessen ihre eigenen Bundle-Manifeste. -`plugins list` zeigt `Format: openclaw` oder `Format: bundle`. Ausführliche list-/info-Ausgaben zeigen außerdem den Bundle-Untertyp (`codex`, `claude` oder `cursor`) sowie erkannte Bundle-Fähigkeiten. +`plugins list` zeigt `Format: openclaw` oder `Format: bundle`. Die ausführliche Listen-/Info-Ausgabe zeigt außerdem den Bundle-Untertyp (`codex`, `claude` oder `cursor`) sowie erkannte Bundle-Fähigkeiten. ### Installieren @@ -93,65 +91,57 @@ openclaw plugins install --marketplace https://github.com// -Bloße Paketnamen werden während der Launch-Umstellung standardmäßig von npm installiert. Verwenden Sie `clawhub:` für ClawHub. Behandeln Sie Plugin-Installationen wie das Ausführen von Code. Bevorzugen Sie angeheftete Versionen. +Bloße Paketnamen installieren während der Launch-Umstellung standardmäßig aus npm. Verwenden Sie `clawhub:` für ClawHub. Behandeln Sie Plugin-Installationen wie das Ausführen von Code. Bevorzugen Sie angeheftete Versionen. -`plugins search` fragt ClawHub nach installierbaren Plugin-Paketen ab und gibt -installationsbereite Paketnamen aus. Es durchsucht Code-Plugin- und Bundle-Plugin-Pakete, -nicht Skills. Verwenden Sie `openclaw skills search` für ClawHub-Skills. +`plugins search` fragt ClawHub nach installierbaren Plugin-Paketen ab und gibt installierbare Paketnamen aus. Es sucht Code-Plugin- und Bundle-Plugin-Pakete, keine Skills. Verwenden Sie `openclaw skills search` für ClawHub-Skills. -ClawHub ist die primäre Oberfläche für Verteilung und Auffindbarkeit der meisten Plugins. Npm -bleibt ein unterstützter Fallback und direkter Installationspfad. OpenClaw-eigene -`@openclaw/*`-Plugin-Pakete werden wieder auf npm veröffentlicht; die aktuelle Liste finden Sie -auf [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) oder im -[Plugin-Inventar](/de/plugins/plugin-inventory). Stabile Installationen verwenden `latest`. -Installationen und Updates im Beta-Kanal bevorzugen das npm-`beta`-Dist-Tag, wenn dieses Tag -verfügbar ist, und fallen dann auf `latest` zurück. +ClawHub ist die primäre Distributions- und Discovery-Oberfläche für die meisten Plugins. Npm bleibt ein unterstützter Fallback und Direktinstallationspfad. OpenClaw-eigene `@openclaw/*`-Plugin-Pakete werden wieder auf npm veröffentlicht; die aktuelle Liste finden Sie auf [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) oder im [Plugin-Inventar](/de/plugins/plugin-inventory). Stabile Installationen verwenden `latest`. Installationen und Aktualisierungen im Beta-Kanal bevorzugen das npm-`beta`-Dist-Tag, wenn dieses Tag verfügbar ist, und fallen anschließend auf `latest` zurück. - Wenn Ihr `plugins`-Abschnitt durch ein Single-File-`$include` gestützt wird, schreiben `plugins install/update/enable/disable/uninstall` in diese eingebundene Datei durch und lassen `openclaw.json` unverändert. Root-Includes, Include-Arrays und Includes mit überschreibenden Geschwistern schlagen geschlossen fehl, statt abgeflacht zu werden. Siehe [Konfigurations-Includes](/de/gateway/configuration) für die unterstützten Formen. + Wenn Ihr Abschnitt `plugins` durch ein einzeldateibasiertes `$include` gestützt wird, schreiben `plugins install/update/enable/disable/uninstall` in diese eingebundene Datei durch und lassen `openclaw.json` unverändert. Root-Includes, Include-Arrays und Includes mit benachbarten Overrides schlagen geschlossen fehl, statt flach zusammengeführt zu werden. Siehe [Konfigurations-Includes](/de/gateway/configuration) für die unterstützten Formen. - Wenn die Konfiguration während der Installation ungültig ist, schlägt `plugins install` normalerweise geschlossen fehl und fordert Sie auf, zuerst `openclaw doctor --fix` auszuführen. Während des Gateway-Starts und Hot Reloads schlägt eine ungültige Plugin-Konfiguration geschlossen fehl wie jede andere ungültige Konfiguration; `openclaw doctor --fix` kann den ungültigen Plugin-Eintrag unter Quarantäne stellen. Die einzige dokumentierte Ausnahme zur Installationszeit ist ein enger Wiederherstellungspfad für gebündelte Plugins, die sich ausdrücklich für `openclaw.install.allowInvalidConfigRecovery` entscheiden. + Wenn die Konfiguration während der Installation ungültig ist, schlägt `plugins install` normalerweise geschlossen fehl und weist Sie an, zuerst `openclaw doctor --fix` auszuführen. Beim Gateway-Start und Hot Reload schlägt ungültige Plugin-Konfiguration wie jede andere ungültige Konfiguration geschlossen fehl; `openclaw doctor --fix` kann den ungültigen Plugin-Eintrag quarantänisieren. Die einzige dokumentierte Ausnahme zur Installationszeit ist ein enger Wiederherstellungspfad für gebündelte Plugins, die sich ausdrücklich für `openclaw.install.allowInvalidConfigRecovery` entscheiden. - - `--force` verwendet das vorhandene Installationsziel erneut und überschreibt ein bereits installiertes Plugin oder Hook-Pack an Ort und Stelle. Verwenden Sie es, wenn Sie bewusst dieselbe ID aus einem neuen lokalen Pfad, Archiv, ClawHub-Paket oder npm-Artefakt neu installieren. Für routinemäßige Upgrades eines bereits nachverfolgten npm-Plugins bevorzugen Sie `openclaw plugins update `. + + `--force` verwendet das vorhandene Installationsziel wieder und überschreibt ein bereits installiertes Plugin oder Hook-Pack direkt. Verwenden Sie es, wenn Sie absichtlich dieselbe ID aus einem neuen lokalen Pfad, Archiv, ClawHub-Paket oder npm-Artefakt neu installieren. Für routinemäßige Upgrades eines bereits nachverfolgten npm-Plugins bevorzugen Sie `openclaw plugins update `. - Wenn Sie `plugins install` für eine bereits installierte Plugin-ID ausführen, stoppt OpenClaw und verweist Sie für ein normales Upgrade auf `plugins update ` oder auf `plugins install --force`, wenn Sie die aktuelle Installation wirklich aus einer anderen Quelle überschreiben möchten. + Wenn Sie `plugins install` für eine Plugin-ID ausführen, die bereits installiert ist, stoppt OpenClaw und verweist Sie für ein normales Upgrade auf `plugins update ` oder auf `plugins install --force`, wenn Sie die aktuelle Installation wirklich aus einer anderen Quelle überschreiben möchten. - - `--pin` gilt nur für npm-Installationen. Es wird bei `git:`-Installationen nicht unterstützt; verwenden Sie eine explizite Git-Referenz wie `git:github.com/acme/plugin@v1.2.3`, wenn Sie eine angeheftete Quelle möchten. Es wird nicht mit `--marketplace` unterstützt, weil Marketplace-Installationen Marketplace-Quellmetadaten statt einer npm-Spezifikation persistieren. + + `--pin` gilt nur für npm-Installationen. Es wird bei `git:`-Installationen nicht unterstützt; verwenden Sie eine explizite Git-Referenz wie `git:github.com/acme/plugin@v1.2.3`, wenn Sie eine angeheftete Quelle möchten. Es wird bei `--marketplace` nicht unterstützt, weil Marketplace-Installationen Marketplace-Quellmetadaten statt einer npm-Spezifikation speichern. - `--dangerously-force-unsafe-install` ist eine Notfalloption für Fehlalarme im integrierten Scanner für gefährlichen Code. Sie erlaubt der Installation fortzufahren, selbst wenn der integrierte Scanner `critical`-Befunde meldet, umgeht aber **nicht** Policy-Blocks von Plugin-`before_install`-Hooks und umgeht **nicht** Scanfehler. + `--dangerously-force-unsafe-install` ist eine Break-Glass-Option für False Positives im integrierten Dangerous-Code-Scanner. Sie lässt die Installation fortfahren, auch wenn der integrierte Scanner `critical`-Funde meldet, umgeht aber **nicht** Richtlinienblöcke von Plugin-`before_install`-Hooks und umgeht **nicht** Scan-Fehler. - Dieses CLI-Flag gilt für Plugin-Installations- und Update-Flows. Gateway-gestützte Installationen von Skill-Abhängigkeiten verwenden das entsprechende Request-Override `dangerouslyForceUnsafeInstall`, während `openclaw skills install` ein separater ClawHub-Flow zum Herunterladen und Installieren von Skills bleibt. + Dieses CLI-Flag gilt für Plugin-Installations-/Aktualisierungsabläufe. Gateway-gestützte Skill-Abhängigkeitsinstallationen verwenden den passenden Request-Override `dangerouslyForceUnsafeInstall`, während `openclaw skills install` ein separater ClawHub-Skill-Download-/Installationsablauf bleibt. - Wenn ein von Ihnen auf ClawHub veröffentlichtes Plugin durch einen Registry-Scan blockiert wird, verwenden Sie die Publisher-Schritte in [ClawHub](/de/tools/clawhub). + Wenn ein von Ihnen auf ClawHub veröffentlichtes Plugin durch einen Registry-Scan blockiert wird, verwenden Sie die Publisher-Schritte unter [ClawHub](/de/tools/clawhub). - `plugins install` ist auch die Installationsoberfläche für Hook-Packs, die `openclaw.hooks` in `package.json` bereitstellen. Verwenden Sie `openclaw hooks` für gefilterte Hook-Sichtbarkeit und Aktivierung einzelner Hooks, nicht für die Paketinstallation. + `plugins install` ist auch die Installationsoberfläche für Hook-Packs, die `openclaw.hooks` in `package.json` bereitstellen. Verwenden Sie `openclaw hooks` für gefilterte Hook-Sichtbarkeit und Aktivierung pro Hook, nicht für die Paketinstallation. - Npm-Spezifikationen sind **nur registrybasiert** (Paketname plus optionale **exakte Version** oder **Dist-Tag**). Git-/URL-/Datei-Spezifikationen und Semver-Bereiche werden abgelehnt. Abhängigkeitsinstallationen laufen aus Sicherheitsgründen projektlokal mit `--ignore-scripts`, selbst wenn Ihre Shell globale npm-Installationseinstellungen hat. + Npm-Spezifikationen sind **nur Registry** (Paketname + optionale **exakte Version** oder **Dist-Tag**). Git-/URL-/Datei-Spezifikationen und Semver-Bereiche werden abgelehnt. Abhängigkeitsinstallationen laufen aus Sicherheitsgründen projektlokal mit `--ignore-scripts`, selbst wenn Ihre Shell globale npm-Installationseinstellungen hat. - Verwenden Sie `npm:`, wenn Sie die npm-Auflösung explizit machen möchten. Bloße Paketspezifikationen installieren während der Launch-Umstellung ebenfalls direkt von npm. + Verwenden Sie `npm:`, wenn Sie die npm-Auflösung explizit machen möchten. Bloße Paketspezifikationen installieren während der Launch-Umstellung ebenfalls direkt aus npm. - Bloße Spezifikationen und `@latest` bleiben auf dem stabilen Track. Wenn npm eine dieser Varianten auf eine Vorabversion auflöst, stoppt OpenClaw und fordert Sie auf, sich explizit mit einem Vorabversions-Tag wie `@beta`/`@rc` oder einer exakten Vorabversion wie `@1.2.3-beta.4` dafür zu entscheiden. + Bloße Spezifikationen und `@latest` bleiben auf dem stabilen Track. OpenClaw-datumsstempelte Korrekturversionen wie `2026.5.3-1` sind für diese Prüfung stabile Releases. Wenn npm eine davon zu einem Prerelease auflöst, stoppt OpenClaw und fordert Sie auf, sich ausdrücklich mit einem Prerelease-Tag wie `@beta`/`@rc` oder einer exakten Prerelease-Version wie `@1.2.3-beta.4` dafür zu entscheiden. - Wenn eine bloße Installationsspezifikation einer offiziellen Plugin-ID entspricht (zum Beispiel `diffs`), installiert OpenClaw den Katalogeintrag direkt. Um ein npm-Paket mit demselben Namen zu installieren, verwenden Sie eine explizite scoped Spezifikation (zum Beispiel `@scope/diffs`). + Wenn eine bloße Installationsspezifikation mit einer offiziellen Plugin-ID übereinstimmt (zum Beispiel `diffs`), installiert OpenClaw den Katalogeintrag direkt. Um ein npm-Paket mit demselben Namen zu installieren, verwenden Sie eine explizite scoped Spezifikation (zum Beispiel `@scope/diffs`). - - Verwenden Sie `git:`, um direkt aus einem Git-Repository zu installieren. Unterstützte Formen umfassen `git:github.com/owner/repo`, `git:owner/repo`, vollständige Clone-URLs mit `https://`, `ssh://`, `git://`, `file://` und `git@host:owner/repo.git`. Fügen Sie `@` oder `#` hinzu, um vor der Installation einen Branch, ein Tag oder einen Commit auszuchecken. + + Verwenden Sie `git:`, um direkt aus einem Git-Repository zu installieren. Unterstützte Formen umfassen `git:github.com/owner/repo`, `git:owner/repo`, vollständige `https://`-, `ssh://`-, `git://`-, `file://`- und `git@host:owner/repo.git`-Clone-URLs. Fügen Sie `@` oder `#` hinzu, um vor der Installation einen Branch, ein Tag oder einen Commit auszuchecken. - Git-Installationen klonen in ein temporäres Verzeichnis, checken die angeforderte Referenz aus, wenn vorhanden, und verwenden dann den normalen Installer für Plugin-Verzeichnisse. Das bedeutet, Manifestvalidierung, Scannen auf gefährlichen Code, Installationsarbeiten des Paketmanagers und Installationsdatensätze verhalten sich wie bei npm-Installationen. Aufgezeichnete Git-Installationen enthalten die Quell-URL/-Referenz plus den aufgelösten Commit, damit `openclaw plugins update` die Quelle später erneut auflösen kann. + Git-Installationen klonen in ein temporäres Verzeichnis, checken die angeforderte Referenz aus, wenn vorhanden, und verwenden dann den normalen Plugin-Verzeichnis-Installer. Das bedeutet, dass Manifest-Validierung, Dangerous-Code-Scanning, Paketmanager-Installationsarbeit und Installationsdatensätze sich wie bei npm-Installationen verhalten. Aufgezeichnete Git-Installationen enthalten die Quell-URL/-Referenz sowie den aufgelösten Commit, damit `openclaw plugins update` die Quelle später erneut auflösen kann. - Nach der Installation aus Git verwenden Sie `openclaw plugins inspect --runtime --json`, um Runtime-Registrierungen wie Gateway-Methoden und CLI-Befehle zu verifizieren. Wenn das Plugin mit `api.registerCli` einen CLI-Root registriert hat, führen Sie diesen Befehl direkt über die OpenClaw-Root-CLI aus, zum Beispiel `openclaw demo-plugin ping`. + Verwenden Sie nach der Installation aus Git `openclaw plugins inspect --runtime --json`, um Runtime-Registrierungen wie Gateway-Methoden und CLI-Befehle zu prüfen. Wenn das Plugin mit `api.registerCli` einen CLI-Root registriert hat, führen Sie diesen Befehl direkt über die OpenClaw-Root-CLI aus, zum Beispiel `openclaw demo-plugin ping`. @@ -169,25 +159,25 @@ openclaw plugins install clawhub:openclaw-codex-app-server openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3 ``` -Bloße npm-sichere Plugin-Spezifikationen installieren während der Launch-Umstellung standardmäßig von npm: +Bloße npm-sichere Plugin-Spezifikationen installieren während der Launch-Umstellung standardmäßig aus npm: ```bash openclaw plugins install openclaw-codex-app-server ``` -Verwenden Sie `npm:`, um eine reine npm-Auflösung explizit zu machen: +Verwenden Sie `npm:`, um die reine npm-Auflösung explizit zu machen: ```bash openclaw plugins install npm:openclaw-codex-app-server openclaw plugins install npm:@scope/plugin-name@1.0.1 ``` -OpenClaw prüft die beworbene Plugin-API- / Mindest-Gateway-Kompatibilität vor der Installation. Wenn die ausgewählte ClawHub-Version ein ClawPack-Artefakt veröffentlicht, lädt OpenClaw das versionierte npm-pack-`.tgz` herunter, verifiziert den ClawHub-Digest-Header und den Artefakt-Digest und installiert es dann über den normalen Archivpfad. Ältere ClawHub-Versionen ohne ClawPack-Metadaten werden weiterhin über den Legacy-Paketarchiv-Verifizierungspfad installiert. Aufgezeichnete Installationen behalten ihre ClawHub-Quellmetadaten, Artefaktart, npm-Integrität, npm-shasum, Tarball-Name und ClawPack-Digest-Fakten für spätere Updates. +OpenClaw prüft vor der Installation die beworbene Plugin-API-/Mindest-Gateway-Kompatibilität. Wenn die ausgewählte ClawHub-Version ein ClawPack-Artefakt veröffentlicht, lädt OpenClaw das versionierte npm-Pack-`.tgz` herunter, verifiziert den ClawHub-Digest-Header und den Artefakt-Digest und installiert es dann über den normalen Archivpfad. Ältere ClawHub-Versionen ohne ClawPack-Metadaten installieren weiterhin über den Legacy-Paketarchiv-Verifizierungspfad. Aufgezeichnete Installationen behalten ihre ClawHub-Quellmetadaten, Artefaktart, npm-Integrität, npm-Shasum, Tarball-Namen und ClawPack-Digest-Fakten für spätere Aktualisierungen. Unversionierte ClawHub-Installationen behalten eine unversionierte aufgezeichnete Spezifikation, damit `openclaw plugins update` neueren ClawHub-Releases folgen kann; explizite Versions- oder Tag-Selektoren wie `clawhub:pkg@1.2.3` und `clawhub:pkg@beta` bleiben an diesen Selektor angeheftet. -#### Marketplace-Kurzschreibweise +#### Marketplace-Kurzform -Verwenden Sie die Kurzschreibweise `plugin@marketplace`, wenn der Marketplace-Name in Claudes lokalem Registry-Cache unter `~/.claude/plugins/known_marketplaces.json` vorhanden ist: +Verwenden Sie die Kurzform `plugin@marketplace`, wenn der Marketplace-Name in Claudes lokalem Registry-Cache unter `~/.claude/plugins/known_marketplaces.json` existiert: ```bash openclaw plugins marketplace list @@ -205,27 +195,27 @@ openclaw plugins install --marketplace ./my-marketplace - - ein Claude bekannter Marketplace-Name aus `~/.claude/plugins/known_marketplaces.json` - - ein lokaler Marketplace-Stamm oder `marketplace.json`-Pfad + - ein Claude-bekannter Marketplace-Name aus `~/.claude/plugins/known_marketplaces.json` + - ein lokaler Marketplace-Root oder `marketplace.json`-Pfad - eine GitHub-Repo-Kurzform wie `owner/repo` - eine GitHub-Repo-URL wie `https://github.com/owner/repo` - eine Git-URL - Für Remote-Marketplaces, die aus GitHub oder Git geladen werden, müssen Plugin-Einträge innerhalb des geklonten Marketplace-Repos bleiben. OpenClaw akzeptiert relative Pfadequellen aus diesem Repo und lehnt HTTP(S), absolute Pfade, Git, GitHub und andere Nicht-Pfad-Plugin-Quellen aus Remote-Manifesten ab. + Für Remote-Marketplaces, die von GitHub oder Git geladen werden, müssen Plugin-Einträge innerhalb des geklonten Marketplace-Repos bleiben. OpenClaw akzeptiert relative Pfadquellen aus diesem Repo und lehnt HTTP(S)-, absolute Pfad-, Git-, GitHub- und andere Nicht-Pfad-Plugin-Quellen aus Remote-Manifesten ab. Für lokale Pfade und Archive erkennt OpenClaw automatisch: -- native OpenClaw Plugins (`openclaw.plugin.json`) +- native OpenClaw-Plugins (`openclaw.plugin.json`) - Codex-kompatible Bundles (`.codex-plugin/plugin.json`) - Claude-kompatible Bundles (`.claude-plugin/plugin.json` oder das standardmäßige Claude-Komponentenlayout) - Cursor-kompatible Bundles (`.cursor-plugin/plugin.json`) -Kompatible Bundles werden im normalen Plugin-Stamm installiert und nehmen am selben Ablauf für Auflisten/Info/Aktivieren/Deaktivieren teil. Heute werden Bundle-Skills, Claude-Befehls-Skills, Claude-`settings.json`-Vorgaben, Claude-`.lsp.json`-/manifestdeklarierte `lspServers`-Vorgaben, Cursor-Befehls-Skills und kompatible Codex-Hook-Verzeichnisse unterstützt; andere erkannte Bundle-Fähigkeiten werden in Diagnose/Info angezeigt, sind aber noch nicht in die Laufzeitausführung eingebunden. +Kompatible Bundles werden im normalen Plugin-Root installiert und nehmen am selben Ablauf für Auflisten/Info/Aktivieren/Deaktivieren teil. Derzeit werden Bundle-Skills, Claude-Befehl-Skills, Claude-`settings.json`-Standards, Claude-`.lsp.json`- / manifestdeklarierte `lspServers`-Standards, Cursor-Befehl-Skills und kompatible Codex-Hook-Verzeichnisse unterstützt; andere erkannte Bundle-Fähigkeiten werden in Diagnose/Info angezeigt, sind aber noch nicht in die Runtime-Ausführung eingebunden. ### Auflisten @@ -244,52 +234,57 @@ openclaw plugins search --json Nur aktivierte Plugins anzeigen. - Von der Tabellenansicht zu Detailzeilen pro Plugin mit Quell-/Ursprungs-/Versions-/Aktivierungsmetadaten wechseln. + Von der Tabellenansicht zu Detailzeilen pro Plugin mit Quellen-/Ursprungs-/Versions-/Aktivierungsmetadaten wechseln. - Maschinenlesbares Inventar plus Registry-Diagnose und Installationsstatus der Paketabhängigkeiten. + Maschinenlesbares Inventar plus Registry-Diagnosen und Installationsstatus der Paketabhängigkeiten. -`plugins list` liest zuerst die persistierte lokale Plugin-Registry, mit einem nur aus Manifesten abgeleiteten Fallback, wenn die Registry fehlt oder ungültig ist. Dies ist nützlich, um zu prüfen, ob ein Plugin installiert, aktiviert und für die Planung eines Kaltstarts sichtbar ist, aber es ist keine Live-Laufzeitprüfung eines bereits laufenden Gateway-Prozesses. Nachdem Sie Plugin-Code, Aktivierung, Hook-Richtlinie oder `plugins.load.paths` geändert haben, starten Sie das Gateway neu, das den Kanal bedient, bevor Sie erwarten, dass neuer `register(api)`-Code oder Hooks ausgeführt werden. Prüfen Sie bei Remote-/Container-Bereitstellungen, dass Sie den tatsächlichen `openclaw gateway run`-Kindprozess neu starten, nicht nur einen Wrapper-Prozess. +`plugins list` liest zuerst die persistierte lokale Plugin-Registry, mit einem nur aus Manifesten abgeleiteten Fallback, wenn die Registry fehlt oder ungültig ist. Das ist nützlich, um zu prüfen, ob ein Plugin installiert, aktiviert und für die Kaltstartplanung sichtbar ist, aber es ist kein Live-Runtime-Test eines bereits laufenden Gateway-Prozesses. Nachdem Sie Plugin-Code, Aktivierung, Hook-Richtlinie oder `plugins.load.paths` geändert haben, starten Sie das Gateway neu, das den Kanal bedient, bevor Sie erwarten, dass neuer `register(api)`-Code oder Hooks ausgeführt werden. Prüfen Sie bei Remote-/Container-Deployments, dass Sie den tatsächlichen `openclaw gateway run`-Kindprozess neu starten, nicht nur einen Wrapper-Prozess. -`plugins list --json` enthält für jedes Plugin dessen `dependencyStatus` aus `package.json` -`dependencies` und `optionalDependencies`. OpenClaw prüft, ob diese Paketnamen entlang des normalen Node-`node_modules`-Suchpfads des Plugins vorhanden sind; es importiert keinen Plugin-Laufzeitcode, führt keinen Paketmanager aus und repariert keine fehlenden Abhängigkeiten. +`plugins list --json` enthält für jedes Plugin den `dependencyStatus` aus den `package.json`- +`dependencies` und `optionalDependencies`. OpenClaw prüft, ob diese Paketnamen +entlang des normalen Node-`node_modules`-Suchpfads des Plugins vorhanden sind; es +importiert keinen Plugin-Runtime-Code, führt keinen Paketmanager aus und repariert +keine fehlenden Abhängigkeiten. -`plugins search` ist eine Remote-ClawHub-Katalogsuche. Es prüft keinen lokalen -Status, ändert keine Konfiguration, installiert keine Pakete und lädt keinen Plugin-Laufzeitcode. Suchergebnisse enthalten den ClawHub-Paketnamen, die Familie, den Kanal, die Version, die Zusammenfassung und -einen Installationshinweis wie `openclaw plugins install clawhub:`. +`plugins search` ist eine Remote-ClawHub-Katalogsuche. Sie prüft keinen lokalen +Status, verändert keine Konfiguration, installiert keine Pakete und lädt keinen +Plugin-Runtime-Code. Suchergebnisse enthalten den ClawHub-Paketnamen, die Familie, +den Kanal, die Version, Zusammenfassung und einen Installationshinweis wie +`openclaw plugins install clawhub:`. -Für Arbeiten an gebündelten Plugins innerhalb eines paketierten Docker-Images binden Sie das Plugin- -Quellverzeichnis per Bind-Mount über den passenden paketierten Quellpfad ein, zum Beispiel -`/app/extensions/synology-chat`. OpenClaw erkennt dieses eingehängte Quell- +Für die Arbeit an gebündelten Plugins innerhalb eines paketierten Docker-Images mounten Sie das Plugin- +Quellverzeichnis per Bind-Mount über den passenden paketierten Quellpfad, zum Beispiel +`/app/extensions/synology-chat`. OpenClaw erkennt dieses gemountete Quell- Overlay vor `/app/dist/extensions/synology-chat`; ein einfach kopiertes Quell- verzeichnis bleibt inaktiv, sodass normale paketierte Installationen weiterhin die kompilierte Dist verwenden. -Für das Debugging von Laufzeit-Hooks: +Für Runtime-Hook-Debugging: -- `openclaw plugins inspect --runtime --json` zeigt registrierte Hooks und Diagnosen aus einem Inspektionsdurchlauf mit geladenem Modul. Die Laufzeitinspektion installiert niemals Abhängigkeiten; verwenden Sie `openclaw doctor --fix`, um alten Abhängigkeitsstatus zu bereinigen oder fehlende konfigurierte herunterladbare Plugins zu installieren. -- `openclaw gateway status --deep --require-rpc` bestätigt das erreichbare Gateway, Dienst-/Prozesshinweise, den Konfigurationspfad und den RPC-Zustand. +- `openclaw plugins inspect --runtime --json` zeigt registrierte Hooks und Diagnosen aus einem Inspektionsdurchlauf mit geladenem Modul. Runtime-Inspektion installiert niemals Abhängigkeiten; verwenden Sie `openclaw doctor --fix`, um Legacy-Abhängigkeitsstatus zu bereinigen oder fehlende konfigurierte herunterladbare Plugins zu installieren. +- `openclaw gateway status --deep --require-rpc` bestätigt das erreichbare Gateway, Dienst-/Prozesshinweise, Konfigurationspfad und RPC-Zustand. - Nicht gebündelte Konversations-Hooks (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) erfordern `plugins.entries..hooks.allowConversationAccess=true`. -Verwenden Sie `--link`, um das Kopieren eines lokalen Verzeichnisses zu vermeiden (fügt es zu `plugins.load.paths` hinzu): +Verwenden Sie `--link`, um das Kopieren eines lokalen Verzeichnisses zu vermeiden (fügt zu `plugins.load.paths` hinzu): ```bash openclaw plugins install -l ./my-plugin ``` -`--force` wird mit `--link` nicht unterstützt, weil verknüpfte Installationen den Quellpfad wiederverwenden, statt über ein verwaltetes Installationsziel zu kopieren. +`--force` wird mit `--link` nicht unterstützt, weil verlinkte Installationen den Quellpfad wiederverwenden, statt über ein verwaltetes Installationsziel zu kopieren. Verwenden Sie `--pin` bei npm-Installationen, um die aufgelöste exakte Spezifikation (`name@version`) im verwalteten Plugin-Index zu speichern, während das Standardverhalten ungepinnt bleibt. ### Plugin-Index -Plugin-Installationsmetadaten sind maschinenverwalteter Status, keine Benutzerkonfiguration. Installationen und Aktualisierungen schreiben sie unter dem aktiven OpenClaw-Statusverzeichnis nach `plugins/installs.json`. Die oberste `installRecords`-Map ist die dauerhafte Quelle der Installationsmetadaten, einschließlich Datensätzen für defekte oder fehlende Plugin-Manifeste. Das `plugins`-Array ist der aus Manifesten abgeleitete Cache der Kalt-Registry. Die Datei enthält eine Nicht-bearbeiten-Warnung und wird von `openclaw plugins update`, Deinstallation, Diagnose und der kalten Plugin-Registry verwendet. +Plugin-Installationsmetadaten sind maschinenverwalteter Status, keine Benutzerkonfiguration. Installationen und Updates schreiben sie nach `plugins/installs.json` unterhalb des aktiven OpenClaw-State-Verzeichnisses. Die oberste `installRecords`-Map ist die dauerhafte Quelle für Installationsmetadaten, einschließlich Einträgen für beschädigte oder fehlende Plugin-Manifeste. Das `plugins`-Array ist der aus Manifesten abgeleitete Kalt-Registry-Cache. Die Datei enthält eine Nicht-bearbeiten-Warnung und wird von `openclaw plugins update`, Deinstallation, Diagnosen und der Kalt-Plugin-Registry verwendet. -Wenn OpenClaw ausgelieferte alte `plugins.installs`-Datensätze in der Konfiguration sieht, verschiebt es sie in den Plugin-Index und entfernt den Konfigurationsschlüssel; wenn einer der Schreibvorgänge fehlschlägt, bleiben die Konfigurationsdatensätze erhalten, damit die Installationsmetadaten nicht verloren gehen. +Wenn OpenClaw ausgelieferte Legacy-`plugins.installs`-Einträge in der Konfiguration sieht, verschiebt es sie in den Plugin-Index und entfernt den Konfigurationsschlüssel; wenn einer der Schreibvorgänge fehlschlägt, bleiben die Konfigurationseinträge erhalten, damit die Installationsmetadaten nicht verloren gehen. ### Deinstallieren @@ -299,7 +294,7 @@ openclaw plugins uninstall --dry-run openclaw plugins uninstall --keep-files ``` -`uninstall` entfernt Plugin-Datensätze aus `plugins.entries`, dem persistierten Plugin-Index, Plugin-Zulassungs-/Sperrlisteneinträgen und verknüpften `plugins.load.paths`-Einträgen, sofern zutreffend. Sofern `--keep-files` nicht gesetzt ist, entfernt die Deinstallation auch das nachverfolgte verwaltete Installationsverzeichnis, wenn es sich innerhalb des Plugin-Erweiterungsstamms von OpenClaw befindet. Bei Active-Memory-Plugins wird der Speicher-Slot auf `memory-core` zurückgesetzt. +`uninstall` entfernt Plugin-Einträge aus `plugins.entries`, dem persistierten Plugin-Index, Plugin-Allow-/Deny-List-Einträgen und verlinkten `plugins.load.paths`-Einträgen, sofern zutreffend. Sofern `--keep-files` nicht gesetzt ist, entfernt die Deinstallation auch das nachverfolgte verwaltete Installationsverzeichnis, wenn es sich innerhalb des OpenClaw-Plugin-Erweiterungsroots befindet. Bei Active-Memory-Plugins wird der Memory-Slot auf `memory-core` zurückgesetzt. `--keep-config` wird als veralteter Alias für `--keep-files` unterstützt. @@ -315,29 +310,29 @@ openclaw plugins update @openclaw/voice-call openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install ``` -Aktualisierungen gelten für nachverfolgte Plugin-Installationen im verwalteten Plugin-Index und nachverfolgte Hook-Pack-Installationen in `hooks.internal.installs`. +Updates gelten für nachverfolgte Plugin-Installationen im verwalteten Plugin-Index und nachverfolgte Hook-Pack-Installationen in `hooks.internal.installs`. - - Wenn Sie eine Plugin-ID übergeben, verwendet OpenClaw die für dieses Plugin aufgezeichnete Installationsspezifikation wieder. Das bedeutet, dass zuvor gespeicherte Dist-Tags wie `@beta` und exakt gepinnte Versionen bei späteren `update `-Läufen weiterverwendet werden. + + Wenn Sie eine Plugin-ID übergeben, verwendet OpenClaw die aufgezeichnete Installationsspezifikation für dieses Plugin erneut. Das bedeutet, dass zuvor gespeicherte Dist-Tags wie `@beta` und exakt gepinnte Versionen bei späteren `update `-Läufen weiterhin verwendet werden. - Für npm-Installationen können Sie auch eine explizite npm-Paketspezifikation mit einem Dist-Tag oder einer exakten Version übergeben. OpenClaw löst diesen Paketnamen zurück auf den nachverfolgten Plugin-Datensatz auf, aktualisiert dieses installierte Plugin und zeichnet die neue npm-Spezifikation für zukünftige ID-basierte Aktualisierungen auf. + Für npm-Installationen können Sie auch eine explizite npm-Paketspezifikation mit Dist-Tag oder exakter Version übergeben. OpenClaw löst diesen Paketnamen zurück auf den nachverfolgten Plugin-Eintrag auf, aktualisiert dieses installierte Plugin und zeichnet die neue npm-Spezifikation für zukünftige ID-basierte Updates auf. - Wenn Sie den npm-Paketnamen ohne Version oder Tag übergeben, wird er ebenfalls zurück auf den nachverfolgten Plugin-Datensatz aufgelöst. Verwenden Sie dies, wenn ein Plugin auf eine exakte Version gepinnt war und Sie es zurück auf die Standard-Release-Linie der Registry verschieben möchten. + Das Übergeben des npm-Paketnamens ohne Version oder Tag wird ebenfalls zurück auf den nachverfolgten Plugin-Eintrag aufgelöst. Verwenden Sie dies, wenn ein Plugin auf eine exakte Version gepinnt war und Sie es zurück auf die Standard-Release-Linie der Registry verschieben möchten. - - `openclaw plugins update` verwendet die nachverfolgte Plugin-Spezifikation wieder, sofern Sie keine neue Spezifikation übergeben. `openclaw update` kennt zusätzlich den aktiven OpenClaw-Aktualisierungskanal: Im Beta-Kanal versuchen npm- und ClawHub-Plugin-Datensätze der Standardlinie zuerst `@beta` und fallen dann auf die aufgezeichnete Standard-/Latest-Spezifikation zurück, wenn keine Plugin-Beta-Veröffentlichung existiert. Exakte Versionen und explizite Tags bleiben an diesen Selektor gepinnt. + + `openclaw plugins update` verwendet die nachverfolgte Plugin-Spezifikation erneut, sofern Sie keine neue Spezifikation übergeben. `openclaw update` kennt zusätzlich den aktiven OpenClaw-Update-Kanal: Im Beta-Kanal versuchen npm- und ClawHub-Plugin-Einträge der Standardlinie zuerst `@beta` und fallen dann auf die aufgezeichnete Standard-/Latest-Spezifikation zurück, wenn kein Plugin-Beta-Release existiert. Exakte Versionen und explizite Tags bleiben an diesen Selektor gepinnt. - Vor einer Live-npm-Aktualisierung prüft OpenClaw die installierte Paketversion gegen die npm-Registry-Metadaten. Wenn die installierte Version und die aufgezeichnete Artefaktidentität bereits mit dem aufgelösten Ziel übereinstimmen, wird die Aktualisierung ohne Download, Neuinstallation oder Neuschreiben von `openclaw.json` übersprungen. + Vor einem Live-npm-Update prüft OpenClaw die installierte Paketversion gegen die npm-Registry-Metadaten. Wenn die installierte Version und die aufgezeichnete Artefaktidentität bereits mit dem aufgelösten Ziel übereinstimmen, wird das Update ohne Herunterladen, Neuinstallieren oder Neuschreiben von `openclaw.json` übersprungen. - Wenn ein gespeicherter Integritäts-Hash existiert und sich der Hash des abgerufenen Artefakts ändert, behandelt OpenClaw dies als npm-Artefaktdrift. Der interaktive Befehl `openclaw plugins update` gibt die erwarteten und tatsächlichen Hashes aus und fragt vor dem Fortfahren nach Bestätigung. Nicht interaktive Aktualisierungshelfer schlagen geschlossen fehl, sofern der Aufrufer keine explizite Fortsetzungsrichtlinie bereitstellt. + Wenn ein gespeicherter Integritäts-Hash existiert und sich der Hash des abgerufenen Artefakts ändert, behandelt OpenClaw dies als npm-Artefaktdrift. Der interaktive Befehl `openclaw plugins update` gibt die erwarteten und tatsächlichen Hashes aus und fragt vor dem Fortfahren nach Bestätigung. Nicht interaktive Update-Helfer schlagen geschlossen fehl, sofern der Aufrufer keine explizite Fortsetzungsrichtlinie bereitstellt. - - `--dangerously-force-unsafe-install` ist auch bei `plugins update` als Break-Glass-Override für Fehlalarme des integrierten Dangerous-Code-Scans während Plugin-Aktualisierungen verfügbar. Es umgeht weiterhin keine Plugin-`before_install`-Richtliniensperren oder Blockierungen durch Scan-Fehler und gilt nur für Plugin-Aktualisierungen, nicht für Hook-Pack-Aktualisierungen. + + `--dangerously-force-unsafe-install` ist auch bei `plugins update` als Break-Glass-Override für False Positives des integrierten Dangerous-Code-Scans während Plugin-Updates verfügbar. Es umgeht weiterhin keine Plugin-`before_install`-Richtlinienblöcke oder Blockierungen durch Scan-Fehler, und es gilt nur für Plugin-Updates, nicht für Hook-Pack-Updates. @@ -349,11 +344,11 @@ openclaw plugins inspect --runtime openclaw plugins inspect --json ``` -Inspect zeigt Identität, Ladestatus, Quelle, Manifestfähigkeiten, Richtlinien-Flags, Diagnosen, Installationsmetadaten, Bundle-Fähigkeiten und erkannte MCP- oder LSP-Server-Unterstützung, ohne standardmäßig Plugin-Laufzeit zu importieren. Fügen Sie `--runtime` hinzu, um das Plugin-Modul zu laden und registrierte Hooks, Tools, Befehle, Dienste, Gateway-Methoden und HTTP-Routen einzuschließen. Die Laufzeitinspektion meldet fehlende Plugin-Abhängigkeiten direkt; Installationen und Reparaturen bleiben in `openclaw plugins install`, `openclaw plugins update` und `openclaw doctor --fix`. +Inspect zeigt Identität, Ladestatus, Quelle, Manifest-Fähigkeiten, Richtlinien-Flags, Diagnosen, Installationsmetadaten, Bundle-Fähigkeiten und jegliche erkannte MCP- oder LSP-Server-Unterstützung, ohne standardmäßig Plugin-Runtime zu importieren. Fügen Sie `--runtime` hinzu, um das Plugin-Modul zu laden und registrierte Hooks, Tools, Befehle, Dienste, Gateway-Methoden und HTTP-Routen einzubeziehen. Runtime-Inspektion meldet fehlende Plugin-Abhängigkeiten direkt; Installationen und Reparaturen bleiben in `openclaw plugins install`, `openclaw plugins update` und `openclaw doctor --fix`. Plugin-eigene CLI-Befehle werden als Root-`openclaw`-Befehlsgruppen installiert. Nachdem `inspect --runtime` einen Befehl unter `cliCommands` anzeigt, führen Sie ihn als `openclaw ...` aus; zum Beispiel kann ein Plugin, das `demo-git` registriert, mit `openclaw demo-git ping` geprüft werden. -Jedes Plugin wird danach klassifiziert, was es zur Laufzeit tatsächlich registriert: +Jedes Plugin wird danach klassifiziert, was es zur Runtime tatsächlich registriert: - **plain-capability** — ein Fähigkeitstyp (z. B. ein reines Provider-Plugin) - **hybrid-capability** — mehrere Fähigkeitstypen (z. B. Text + Sprache + Bilder) @@ -363,7 +358,7 @@ Jedes Plugin wird danach klassifiziert, was es zur Laufzeit tatsächlich registr Weitere Informationen zum Fähigkeitsmodell finden Sie unter [Plugin-Formen](/de/plugins/architecture#plugin-shapes). -Das Flag `--json` gibt einen maschinenlesbaren Bericht aus, der sich für Skripting und Audits eignet. `inspect --all` rendert eine flottenweite Tabelle mit Spalten für Form, Fähigkeitsarten, Kompatibilitätshinweise, Bundle-Fähigkeiten und Hook-Zusammenfassung. `info` ist ein Alias für `inspect`. +Das Flag `--json` gibt einen maschinenlesbaren Bericht aus, der für Skripting und Auditing geeignet ist. `inspect --all` rendert eine flotteweite Tabelle mit Spalten für Form, Fähigkeitstypen, Kompatibilitätshinweise, Bundle-Fähigkeiten und Hook-Zusammenfassung. `info` ist ein Alias für `inspect`. ### Doctor @@ -374,9 +369,9 @@ openclaw plugins doctor `doctor` meldet Plugin-Ladefehler, Manifest-/Discovery-Diagnosen und Kompatibilitätshinweise. Wenn alles sauber ist, gibt es `No plugin issues detected.` aus. -Wenn ein konfiguriertes Plugin auf der Festplatte vorhanden ist, aber durch die Pfadsicherheitsprüfungen des Loaders blockiert wird, behält die Konfigurationsvalidierung den Plugin-Eintrag bei und meldet ihn als `present but blocked`. Beheben Sie die vorhergehende Diagnose zum blockierten Plugin, etwa Pfadbesitz oder weltbeschreibbare Berechtigungen, statt die Konfiguration `plugins.entries.` oder `plugins.allow` zu entfernen. +Wenn ein konfiguriertes Plugin auf dem Datenträger vorhanden ist, aber durch die Pfadsicherheitsprüfungen des Loaders blockiert wird, behält die Konfigurationsvalidierung den Plugin-Eintrag bei und meldet ihn als `present but blocked`. Beheben Sie die vorangehende Diagnose zum blockierten Plugin, etwa Pfadeigentum oder world-writable-Berechtigungen, statt die Konfiguration `plugins.entries.` oder `plugins.allow` zu entfernen. -Bei Modulform-Fehlern wie fehlenden `register`-/`activate`-Exports führen Sie den Befehl erneut mit `OPENCLAW_PLUGIN_LOAD_DEBUG=1` aus, um eine kompakte Exportform-Zusammenfassung in die Diagnoseausgabe aufzunehmen. +Bei Modulform-Fehlern wie fehlenden `register`-/`activate`-Exports führen Sie erneut mit `OPENCLAW_PLUGIN_LOAD_DEBUG=1` aus, um eine kompakte Exportform-Zusammenfassung in die Diagnoseausgabe aufzunehmen. ### Registry @@ -386,12 +381,12 @@ openclaw plugins registry --refresh openclaw plugins registry --json ``` -Die lokale Plugin-Registry ist das persistierte kalte Lesemodell von OpenClaw für installierte Plugin-Identität, Aktivierung, Quellmetadaten und Beitragsbesitz. Normaler Start, Provider-Owner-Lookup, Klassifizierung der Kanaleinrichtung und Plugin-Inventar können sie lesen, ohne Plugin-Laufzeitmodule zu importieren. +Die lokale Plugin-Registry ist OpenClaws persistiertes Kalt-Lesemodell für installierte Plugin-Identität, Aktivierung, Quellenmetadaten und Beitrags-Eigentümerschaft. Normaler Start, Provider-Owner-Lookup, Klassifizierung der Kanal-Einrichtung und Plugin-Inventar können sie lesen, ohne Plugin-Runtime-Module zu importieren. -Verwenden Sie `plugins registry`, um zu prüfen, ob die persistierte Registry vorhanden, aktuell oder veraltet ist. Verwenden Sie `--refresh`, um sie aus dem persistierten Plugin-Index, der Konfigurationsrichtlinie und den Manifest-/Paketmetadaten neu zu erstellen. Dies ist ein Reparaturpfad, kein Pfad zur Laufzeitaktivierung. +Verwenden Sie `plugins registry`, um zu prüfen, ob die persistierte Registry vorhanden, aktuell oder veraltet ist. Verwenden Sie `--refresh`, um sie aus dem persistierten Plugin-Index, der Konfigurationsrichtlinie und Manifest-/Paketmetadaten neu aufzubauen. Dies ist ein Reparaturpfad, kein Pfad zur Laufzeitaktivierung. -`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` ist ein veralteter Notfall-Kompatibilitätsschalter für Registry-Lesefehler. Bevorzugen Sie `plugins registry --refresh` oder `openclaw doctor --fix`; der Umgebungsvariablen-Fallback ist nur für die Notfallwiederherstellung beim Start gedacht, während die Migration ausgerollt wird. +`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` ist ein veralteter Notfall-Kompatibilitätsschalter für Registry-Lesefehler. Bevorzugen Sie `plugins registry --refresh` oder `openclaw doctor --fix`; der Env-Fallback ist nur für die Wiederherstellung des Starts im Notfall gedacht, während die Migration ausgerollt wird. ### Marktplatz @@ -401,7 +396,7 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -Die Marktplatzliste akzeptiert einen lokalen Marktplatzpfad, einen `marketplace.json`-Pfad, eine GitHub-Kurzform wie `owner/repo`, eine GitHub-Repo-URL oder eine Git-URL. `--json` gibt das aufgelöste Quelllabel sowie das geparste Marktplatzmanifest und die Plugin-Einträge aus. +Die Marktplatzliste akzeptiert einen lokalen Marktplatzpfad, einen `marketplace.json`-Pfad, eine GitHub-Kurzform wie `owner/repo`, eine GitHub-Repo-URL oder eine Git-URL. `--json` gibt die aufgelöste Quellbezeichnung sowie das geparste Marktplatz-Manifest und die Plugin-Einträge aus. ## Verwandte Themen diff --git a/docs/de/cli/proxy.md b/docs/de/cli/proxy.md index 61356aa6e..6b62153a4 100644 --- a/docs/de/cli/proxy.md +++ b/docs/de/cli/proxy.md @@ -1,28 +1,28 @@ --- read_when: - Sie müssen das vom Betreiber verwaltete Proxy-Routing vor der Bereitstellung validieren - - Sie müssen OpenClaw-Transportdatenverkehr lokal zur Fehlerbehebung erfassen - - Sie möchten Debug-Proxy-Sitzungen, Blobs oder integrierte Abfragevorgaben untersuchen -summary: CLI-Referenz für `openclaw proxy`, einschließlich der betreiberverwalteten Proxy-Validierung und des Inspektors für Mitschnitte des lokalen Debug-Proxys + - Sie müssen den OpenClaw-Transportdatenverkehr lokal zur Fehlersuche erfassen + - Sie möchten Debug-Proxy-Sitzungen, Blobs oder integrierte Abfragevoreinstellungen prüfen +summary: CLI-Referenz für `openclaw proxy`, einschließlich der betreiberverwalteten Proxy-Validierung und der lokalen Prüfansicht für Debug-Proxy-Erfassungen title: Proxy x-i18n: - generated_at: "2026-05-01T06:41:08Z" + generated_at: "2026-05-04T06:41:36Z" model: gpt-5.5 provider: openai - source_hash: e0820de861bfe1ec14e0c1624d636d6474b5fedd317e3ba1baaa61f6530e06e9 + source_hash: 9589bedafb97c31bcb6536a04307cd0c6550e1f307693bd4401785d79f34a1eb source_path: cli/proxy.md workflow: 16 --- # `openclaw proxy` -Validieren Sie vom Operator verwaltetes Proxy-Routing, oder führen Sie den lokalen expliziten Debug-Proxy aus -und prüfen Sie den erfassten Traffic. +Validieren Sie vom Betreiber verwaltetes Proxy-Routing oder führen Sie den lokalen expliziten Debug-Proxy aus +und prüfen Sie erfassten Traffic. -Verwenden Sie `validate`, um einen vom Operator verwalteten Forward-Proxy vor der Aktivierung von -OpenClaw Proxy-Routing vorab zu prüfen. Die anderen Befehle sind Debugging-Werkzeuge für +Verwenden Sie `validate`, um einen vom Betreiber verwalteten Forward-Proxy vor dem Aktivieren des +OpenClaw-Proxy-Routings vorab zu prüfen. Die anderen Befehle sind Debugging-Werkzeuge für Untersuchungen auf Transportebene: Sie können einen lokalen Proxy starten, einen untergeordneten Befehl -mit aktivierter Erfassung ausführen, Erfassungssitzungen auflisten, gängige Traffic-Muster abfragen, erfasste +mit aktivierter Erfassung ausführen, Erfassungssitzungen auflisten, häufige Traffic-Muster abfragen, erfasste Blobs lesen und lokale Erfassungsdaten löschen. ## Befehle @@ -40,24 +40,25 @@ openclaw proxy purge ## Validieren -`openclaw proxy validate` prüft die effektive vom Operator verwaltete Proxy-URL aus -`--proxy-url`, der Konfiguration oder `OPENCLAW_PROXY_URL`. Der Befehl meldet ein Konfigurationsproblem, wenn +`openclaw proxy validate` prüft die effektive vom Betreiber verwaltete Proxy-URL aus +`--proxy-url`, der Konfiguration oder `OPENCLAW_PROXY_URL`. Es meldet ein Konfigurationsproblem, wenn kein Proxy aktiviert und konfiguriert ist; verwenden Sie `--proxy-url` für eine einmalige Vorabprüfung, -bevor Sie die Konfiguration ändern. Standardmäßig wird verifiziert, dass ein öffentliches Ziel -über den Proxy erfolgreich erreicht wird und dass der Proxy keinen temporären local loopback-Canary erreichen kann. -Benutzerdefinierte verweigerte Ziele sind fail-closed: HTTP-Antworten und mehrdeutige -Transportfehler schlagen beide fehl, sofern Sie kein bereitstellungsspezifisches Verweigerungssignal +bevor Sie die Konfiguration ändern. Standardmäßig wird geprüft, ob ein öffentliches Ziel +über den Proxy erfolgreich erreicht wird und ob der Proxy keinen temporären Loopback-Canary erreichen kann. +Benutzerdefinierte abgelehnte Ziele sind fail-closed: HTTP-Antworten und mehrdeutige +Transportfehler schlagen beide fehl, sofern Sie kein bereitstellungsspezifisches Ablehnungssignal separat verifizieren können. Optionen: -- `--json`: gibt maschinenlesbares JSON aus. -- `--proxy-url `: validiert diese Proxy-URL statt Konfiguration oder Env. -- `--allowed-url `: fügt ein Ziel hinzu, das über den Proxy erfolgreich erreichbar sein soll. Wiederholen Sie die Option, um mehrere Ziele zu prüfen. -- `--denied-url `: fügt ein Ziel hinzu, das vom Proxy blockiert werden soll. Wiederholen Sie die Option, um mehrere Ziele zu prüfen. +- `--json`: Maschinenlesbares JSON ausgeben. +- `--proxy-url `: Diese Proxy-URL statt Konfiguration oder env validieren. +- `--allowed-url `: Ein Ziel hinzufügen, das über den Proxy erfolgreich sein soll. Wiederholen, um mehrere Ziele zu prüfen. +- `--denied-url `: Ein Ziel hinzufügen, das vom Proxy blockiert werden soll. Wiederholen, um mehrere Ziele zu prüfen. - `--timeout-ms `: Zeitlimit pro Anfrage in Millisekunden. -Siehe [Network Proxy](/de/security/network-proxy) für Bereitstellungshinweise und Verweigerungssemantik. +Siehe [Netzwerk-Proxy](/de/security/network-proxy) für Hinweise zur Bereitstellung und +Ablehnungssemantik. ## Abfrage-Presets @@ -73,12 +74,13 @@ Siehe [Network Proxy](/de/security/network-proxy) für Bereitstellungshinweise u ## Hinweise - `start` verwendet standardmäßig `127.0.0.1`, sofern `--host` nicht gesetzt ist. -- `run` startet einen lokalen Debug-Proxy und führt danach den Befehl nach `--` aus. -- `validate` beendet sich mit Code 1, wenn Proxy-Konfiguration oder Zielprüfungen fehlschlagen. +- `run` startet einen lokalen Debug-Proxy und führt anschließend den Befehl nach `--` aus. +- Das direkte Upstream-Forwarding des Debug-Proxys öffnet Upstream-Sockets für Diagnosen. Wenn der von OpenClaw verwaltete Proxy-Modus aktiv ist, ist direktes Forwarding für Proxy-Anfragen und CONNECT-Tunnel standardmäßig deaktiviert; setzen Sie `OPENCLAW_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1` nur für genehmigte lokale Diagnosen. +- `validate` wird mit Code 1 beendet, wenn die Proxy-Konfiguration oder Zielprüfungen fehlschlagen. - Erfassungen sind lokale Debugging-Daten; verwenden Sie `openclaw proxy purge`, wenn Sie fertig sind. ## Verwandte Themen - [CLI-Referenz](/de/cli) -- [Network Proxy](/de/security/network-proxy) -- [Trusted proxy auth](/de/gateway/trusted-proxy-auth) +- [Netzwerk-Proxy](/de/security/network-proxy) +- [Authentifizierung für vertrauenswürdige Proxys](/de/gateway/trusted-proxy-auth) diff --git a/docs/de/cli/sessions.md b/docs/de/cli/sessions.md index 71a2bf0d2..02be87199 100644 --- a/docs/de/cli/sessions.md +++ b/docs/de/cli/sessions.md @@ -1,13 +1,13 @@ --- read_when: - - Sie möchten gespeicherte Sitzungen auflisten und die jüngsten Aktivitäten einsehen + - Sie möchten gespeicherte Sitzungen auflisten und aktuelle Aktivitäten anzeigen summary: CLI-Referenz für `openclaw sessions` (gespeicherte Sitzungen auflisten + Nutzung) title: Sitzungen x-i18n: - generated_at: "2026-05-02T20:44:18Z" + generated_at: "2026-05-04T06:41:15Z" model: gpt-5.5 provider: openai - source_hash: 5c9ec3ca55f7c5b6217b481e9da62f5416df73e69405a0dc15e77d2afeac723f + source_hash: 8dc90344f40c53513bd6db3696bc709279155f26e7c3b6ea27e81a07a2f9f15e source_path: cli/sessions.md workflow: 16 --- @@ -16,12 +16,9 @@ x-i18n: Gespeicherte Konversationssitzungen auflisten. -Sitzungslisten sind keine Liveness-Prüfungen für Kanäle/Provider. Sie zeigen persistierte -Konversationszeilen aus Sitzungs-Stores. Ein ruhiger Discord-, Slack-, Telegram- oder -anderer Kanal kann erfolgreich erneut verbunden werden, ohne eine neue Sitzungszeile -zu erstellen, bis eine Nachricht verarbeitet wird. Verwenden Sie `openclaw channels status --probe`, -`openclaw status --deep` oder `openclaw health --verbose`, wenn Sie Live- -Kanalverbindungen benötigen. +Sitzungslisten sind keine Liveness-Prüfungen für Kanäle/Provider. Sie zeigen persistierte Konversationszeilen aus Sitzungsspeichern. Ein inaktiver Discord-, Slack-, Telegram- oder anderer Kanal kann sich erfolgreich neu verbinden, ohne eine neue Sitzungszeile zu erstellen, bis eine Nachricht verarbeitet wird. Verwenden Sie `openclaw channels status --probe`, `openclaw status --deep` oder `openclaw health --verbose`, wenn Sie Live-Kanalkonnektivität benötigen. + +Gateway-`sessions.list`-Antworten sind standardmäßig begrenzt, damit große, langlebige Speicher die Gateway-Ereignisschleife nicht monopolisieren können. Übergeben Sie von RPC-Clients ein explizites positives `limit`, wenn ein anderes Ergebnisfenster benötigt wird; Antworten enthalten `totalCount`, `limitApplied` und `hasMore`, wenn Aufrufer anzeigen müssen, dass weitere Zeilen vorhanden sind. ```bash openclaw sessions @@ -34,11 +31,11 @@ openclaw sessions --json Bereichsauswahl: -- Standard: konfigurierter Standard-Agent-Store +- Standard: konfigurierter Speicher des Standard-Agents - `--verbose`: ausführliche Protokollierung -- `--agent `: ein konfigurierter Agent-Store -- `--all-agents`: alle konfigurierten Agent-Stores aggregieren -- `--store `: expliziter Store-Pfad (kann nicht mit `--agent` oder `--all-agents` kombiniert werden) +- `--agent `: ein konfigurierter Agent-Speicher +- `--all-agents`: alle konfigurierten Agent-Speicher aggregieren +- `--store `: expliziter Speicherpfad (kann nicht mit `--agent` oder `--all-agents` kombiniert werden) Ein Trajectory-Bundle für eine gespeicherte Sitzung exportieren: @@ -47,15 +44,9 @@ openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:12 openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json ``` -Dies ist der Befehlspfad, den der Slash-Befehl `/export-trajectory` verwendet, nachdem -der Owner die Exec-Anfrage genehmigt hat. Das Ausgabeverzeichnis wird immer -innerhalb von `.openclaw/trajectory-exports/` im ausgewählten Workspace aufgelöst. +Dies ist der Befehlspfad, der vom Slash-Befehl `/export-trajectory` verwendet wird, nachdem der Owner die Exec-Anforderung genehmigt hat. Das Ausgabeverzeichnis wird immer innerhalb von `.openclaw/trajectory-exports/` unter dem ausgewählten Workspace aufgelöst. -`openclaw sessions --all-agents` liest konfigurierte Agent-Stores. Die Sitzungsfindung -für Gateway und ACP ist breiter: Sie umfasst auch reine Disk-Stores, die unterhalb -des standardmäßigen `agents/`-Stammverzeichnisses oder eines templatisierten `session.store`-Stammverzeichnisses gefunden werden. Diese -gefundenen Stores müssen zu regulären `sessions.json`-Dateien innerhalb des -Agent-Stammverzeichnisses aufgelöst werden; Symlinks und Pfade außerhalb des Stammverzeichnisses werden übersprungen. +`openclaw sessions --all-agents` liest konfigurierte Agent-Speicher. Die Sitzungserkennung von Gateway und ACP ist breiter: Sie schließt auch reine Datenträgerspeicher ein, die unter dem standardmäßigen `agents/`-Root oder einem vorlagenbasierten `session.store`-Root gefunden werden. Diese erkannten Speicher müssen zu regulären `sessions.json`-Dateien innerhalb des Agent-Roots aufgelöst werden; Symlinks und Pfade außerhalb des Roots werden übersprungen. JSON-Beispiele: @@ -78,9 +69,9 @@ JSON-Beispiele: } ``` -## Bereinigungswartung +## Cleanup-Wartung -Wartung jetzt ausführen (anstatt auf den nächsten Schreibzyklus zu warten): +Wartung jetzt ausführen (statt auf den nächsten Schreibzyklus zu warten): ```bash openclaw sessions cleanup --dry-run @@ -91,23 +82,21 @@ openclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123 openclaw sessions cleanup --json ``` -`openclaw sessions cleanup` verwendet `session.maintenance`-Einstellungen aus der Konfiguration: +`openclaw sessions cleanup` verwendet die `session.maintenance`-Einstellungen aus der Konfiguration: -- Bereichshinweis: `openclaw sessions cleanup` wartet Sitzungs-Stores, Transkripte und Trajectory-Sidecars. Es bereinigt keine Cron-Ausführungsprotokolle (`cron/runs/.jsonl`), die über `cron.runLog.maxBytes` und `cron.runLog.keepLines` in der [Cron-Konfiguration](/de/automation/cron-jobs#configuration) verwaltet und in der [Cron-Wartung](/de/automation/cron-jobs#maintenance) erklärt werden. +- Bereichshinweis: `openclaw sessions cleanup` wartet Sitzungsspeicher, Transkripte und Trajectory-Sidecars. Es bereinigt keine Cron-Ausführungsprotokolle (`cron/runs/.jsonl`); diese werden durch `cron.runLog.maxBytes` und `cron.runLog.keepLines` in der [Cron-Konfiguration](/de/automation/cron-jobs#configuration) verwaltet und in der [Cron-Wartung](/de/automation/cron-jobs#maintenance) erläutert. - `--dry-run`: Vorschau, wie viele Einträge ohne Schreiben bereinigt/begrenzt würden. - - Im Textmodus gibt der Dry-Run eine Aktionstabelle pro Sitzung aus (`Action`, `Key`, `Age`, `Model`, `Flags`), damit Sie sehen können, was behalten oder entfernt würde. + - Im Textmodus gibt der Probelauf eine Aktionstabelle pro Sitzung aus (`Action`, `Key`, `Age`, `Model`, `Flags`), damit Sie sehen können, was beibehalten oder entfernt würde. - `--enforce`: Wartung anwenden, auch wenn `session.maintenance.mode` auf `warn` gesetzt ist. - `--fix-missing`: Einträge entfernen, deren Transkriptdateien fehlen, selbst wenn sie normalerweise noch nicht aufgrund von Alter/Anzahl entfernt würden. -- `--active-key `: einen bestimmten aktiven Schlüssel vor der Verdrängung durch das Disk-Budget schützen. Dauerhafte externe Konversationszeiger, wie Gruppensitzungen und Thread-bezogene Chat-Sitzungen, werden ebenfalls von der Wartung nach Alter/Anzahl/Disk-Budget beibehalten. -- `--agent `: Bereinigung für einen konfigurierten Agent-Store ausführen. -- `--all-agents`: Bereinigung für alle konfigurierten Agent-Stores ausführen. +- `--active-key `: einen bestimmten aktiven Schlüssel vor der Entfernung aufgrund des Datenträgerbudgets schützen. Dauerhafte externe Konversationszeiger, wie Gruppensitzungen und threadbezogene Chat-Sitzungen, werden ebenfalls durch Wartung nach Alter/Anzahl/Datenträgerbudget beibehalten. +- `--agent `: Cleanup für einen konfigurierten Agent-Speicher ausführen. +- `--all-agents`: Cleanup für alle konfigurierten Agent-Speicher ausführen. - `--store `: gegen eine bestimmte `sessions.json`-Datei ausführen. -- `--json`: eine JSON-Zusammenfassung ausgeben. Mit `--all-agents` enthält die Ausgabe eine Zusammenfassung pro Store. +- `--json`: eine JSON-Zusammenfassung ausgeben. Mit `--all-agents` enthält die Ausgabe eine Zusammenfassung pro Speicher. -Wenn ein Gateway erreichbar ist, wird eine nicht als Dry-Run ausgeführte Bereinigung für konfigurierte Agent-Stores -über das Gateway gesendet, damit sie denselben Sitzungs-Store-Writer wie Laufzeit- -Traffic nutzt. Verwenden Sie `--store ` für die explizite Offline-Reparatur einer Store-Datei. +Wenn ein Gateway erreichbar ist, wird Cleanup ohne Probelauf für konfigurierte Agent-Speicher über das Gateway gesendet, damit derselbe Sitzungsspeicher-Writer wie beim Laufzeitverkehr verwendet wird. Verwenden Sie `--store ` für die explizite Offline-Reparatur einer Speicherdatei. `openclaw sessions cleanup --all-agents --dry-run --json`: @@ -141,7 +130,7 @@ Verwandt: - Sitzungskonfiguration: [Konfigurationsreferenz](/de/gateway/config-agents#session) -## Verwandte Themen +## Verwandt - [CLI-Referenz](/de/cli) - [Sitzungsverwaltung](/de/concepts/session) diff --git a/docs/de/concepts/mantis.md b/docs/de/concepts/mantis.md index 2c2b50d54..16aa5997b 100644 --- a/docs/de/concepts/mantis.md +++ b/docs/de/concepts/mantis.md @@ -1,73 +1,73 @@ --- read_when: - - Live-Visual-QA für OpenClaw-Fehler erstellen oder ausführen + - Visuelle Live-QA für OpenClaw-Fehler erstellen oder ausführen - Vorher- und Nachher-Verifizierung für einen Pull Request hinzufügen - Hinzufügen von Discord-, Slack-, WhatsApp- oder anderen Live-Transport-Szenarien - - Debugging von QA-Läufen, die Screenshots, Browserautomatisierung oder VNC-Zugriff erfordern -summary: Mantis ist das visuelle End-to-End-Verifizierungssystem, mit dem OpenClaw-Fehler auf Live-Transporten reproduziert, Vorher- und Nachher-Nachweise erfasst und Artefakte an PRs angehängt werden. -title: Mantis + - Debuggen von QA-Läufen, die Screenshots, Browser-Automatisierung oder VNC-Zugriff erfordern +summary: Mantis ist das visuelle End-to-End-Verifizierungssystem zum Reproduzieren von OpenClaw-Fehlern auf Live-Transporten, Erfassen von Vorher- und Nachher-Nachweisen und Anhängen von Artefakten an PRs. +title: Fangschrecke x-i18n: - generated_at: "2026-05-04T02:23:15Z" + generated_at: "2026-05-04T06:41:35Z" model: gpt-5.5 provider: openai - source_hash: 5a86ab4bc876d1c53ada1c30580034165f028194a072f559eb54a898a369211d + source_hash: 9d3f3fa3db111b1b5c85f8efeccd749fbd5885cee6b7843ca4c8d049acfd9164 source_path: concepts/mantis.md workflow: 16 --- -Mantis ist das End-to-End-Verifikationssystem von OpenClaw für Bugs, die eine echte -Runtime, einen echten Transport und sichtbare Nachweise benötigen. Es führt ein Szenario gegen eine bekannte -fehlerhafte Ref aus, erfasst Nachweise, führt dasselbe Szenario gegen eine Kandidaten-Ref aus und -veröffentlicht den Vergleich als Artefakte, die ein Maintainer aus einem PR oder +Mantis ist das End-to-End-Verifizierungssystem von OpenClaw für Bugs, die eine echte +Runtime, einen echten Transport und sichtbare Nachweise erfordern. Es führt ein Szenario gegen einen bekannten +fehlerhaften Ref aus, erfasst Nachweise, führt dasselbe Szenario gegen einen Kandidaten-Ref aus und +veröffentlicht den Vergleich als Artefakte, die ein Maintainer von einem PR oder über einen lokalen Befehl prüfen kann. -Mantis beginnt mit Discord, weil Discord uns eine hochwertige erste Lane bietet: +Mantis beginnt mit Discord, weil Discord uns eine besonders wertvolle erste Lane bietet: echte Bot-Authentifizierung, echte Guild-Kanäle, Reaktionen, Threads, native Befehle und eine Browser-UI, in der Menschen visuell bestätigen können, was der Transport gezeigt hat. ## Ziele -- Einen Bug aus einem GitHub-Issue oder PR mit derselben Transportform reproduzieren, die Benutzer +- Einen Bug aus einem GitHub-Issue oder -PR mit derselben Transportform reproduzieren, die Benutzer sehen. -- Ein **Vorher**-Artefakt auf der Baseline-Ref erfassen, bevor der Fix angewendet wird. -- Ein **Nachher**-Artefakt auf der Kandidaten-Ref erfassen, nachdem der Fix angewendet wurde. -- Wann immer möglich ein deterministisches Oracle verwenden, etwa einen Discord-REST-Reaktions- - Read oder eine Channel-Transkriptprüfung. +- Ein **Vorher**-Artefakt auf dem Baseline-Ref erfassen, bevor der Fix angewendet wird. +- Ein **Nachher**-Artefakt auf dem Kandidaten-Ref erfassen, nachdem der Fix angewendet wurde. +- Wann immer möglich ein deterministisches Orakel verwenden, etwa einen Discord-REST-Reaktions- + Abruf oder eine Prüfung des Kanaltranskripts. - Screenshots erfassen, wenn der Bug eine sichtbare UI-Oberfläche hat. - Lokal über eine agentengesteuerte CLI und remote über GitHub ausführen. -- Genug Maschinenzustand für VNC-Rettung bewahren, wenn Login, Browser-Automatisierung oder +- Genügend Maschinenzustand für eine VNC-Rettung bewahren, wenn Login, Browser-Automatisierung oder Provider-Authentifizierung hängen bleiben. -- Einen knappen Status an einen Operator-Discord-Kanal senden, wenn der Lauf blockiert ist, +- Einen knappen Status in einen Operator-Discord-Kanal posten, wenn der Lauf blockiert ist, manuelle VNC-Hilfe benötigt oder abgeschlossen ist. ## Nichtziele -- Mantis ist kein Ersatz für Unit-Tests. Ein Mantis-Lauf sollte nach dem Verständnis des Fixes normalerweise zu - einem kleineren Regressionstest werden. -- Mantis ist nicht das normale schnelle CI-Gate. Es ist langsamer, verwendet Live-Anmeldedaten und - ist für Bugs reserviert, bei denen die Live-Umgebung wichtig ist. -- Mantis sollte im normalen Betrieb keinen Menschen erfordern. Manuelles VNC ist ein Rettungsweg, - nicht der Standardpfad. +- Mantis ist kein Ersatz für Unit-Tests. Ein Mantis-Lauf sollte nach dem Verstehen des Fixes normalerweise + in einen kleineren Regressionstest überführt werden. +- Mantis ist nicht das normale schnelle CI-Gate. Es ist langsamer, verwendet Live-Zugangsdaten und + ist für Bugs reserviert, bei denen die Live-Umgebung relevant ist. +- Mantis sollte im Normalbetrieb keinen Menschen erfordern. Manuelles VNC ist ein Rettungspfad, + nicht der Normalfall. - Mantis speichert keine Roh-Secrets in Artefakten, Logs, Screenshots, Markdown- Berichten oder PR-Kommentaren. ## Ownership -Mantis befindet sich im OpenClaw-QA-Stack. +Mantis lebt im OpenClaw-QA-Stack. -- OpenClaw besitzt die Szenario-Runtime, Transportadapter, das Nachweisschema und die +- OpenClaw besitzt die Szenario-Runtime, Transport-Adapter, das Nachweisschema und die lokale CLI unter `pnpm openclaw qa mantis`. - QA Lab besitzt die Live-Transport-Harness-Teile, Browser-Erfassungshelfer und Artefakt-Writer. - Crabbox besitzt vorgewärmte Linux-Maschinen, wenn eine Remote-VM benötigt wird. -- GitHub Actions besitzt den Remote-Workflow-Einstiegspunkt und die Artefaktaufbewahrung. -- ClawSweeper besitzt das GitHub-Kommentarrouting: Maintainer-Befehle parsen, - den Workflow auslösen und den finalen PR-Kommentar posten. +- GitHub Actions besitzt den Einstiegspunkt für den Remote-Workflow und die Artefaktaufbewahrung. +- ClawSweeper besitzt das GitHub-Kommentarrouting: Parsen von Maintainer-Befehlen, + Dispatchen des Workflows und Posten des finalen PR-Kommentars. - OpenClaw-Agenten steuern Mantis über Codex, wenn ein Szenario agentisches Setup, - Debugging oder Berichte über festhängende Zustände benötigt. + Debugging oder Meldungen über festhängende Zustände benötigt. -Diese Grenze hält Transportwissen in OpenClaw, Maschinenplanung in -Crabbox und Maintainer-Workflow-Klebstoff in ClawSweeper. +Diese Grenze hält Transportwissen in OpenClaw, Maschinenscheduling in +Crabbox und Maintainer-Workflow-Klebelogik in ClawSweeper. ## Befehlsform @@ -79,7 +79,7 @@ pnpm openclaw qa mantis discord-smoke \ --output-dir .artifacts/qa-e2e/mantis/discord-smoke ``` -Der lokale Vorher/Nachher-Runner akzeptiert diese Form: +Der lokale Vorher- und Nachher-Runner akzeptiert diese Form: ```bash pnpm openclaw qa mantis run \ @@ -90,59 +90,104 @@ pnpm openclaw qa mantis run \ --output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions ``` -Der Runner erstellt getrennte Baseline- und Kandidaten-Worktrees unter dem Ausgabe- -verzeichnis, installiert Abhängigkeiten, baut jede Ref, führt das Szenario mit -`--allow-failures` aus und schreibt dann `baseline/`, `candidate/`, `comparison.json` -und `mantis-report.md`. Für das erste Discord-Szenario bedeutet eine erfolgreiche Verifikation, +Der Runner erstellt getrennte Baseline- und Kandidaten-Worktrees unterhalb des Ausgabe- +verzeichnisses, installiert Abhängigkeiten, baut jeden Ref, führt das Szenario mit +`--allow-failures` aus und schreibt anschließend `baseline/`, `candidate/`, `comparison.json` +und `mantis-report.md`. Für das erste Discord-Szenario bedeutet eine erfolgreiche Verifizierung, dass der Baseline-Status `fail` und der Kandidaten-Status `pass` ist. -Das erste VM/Browser-Primitive ist der Desktop-Smoke: +Das erste VM-/Browser-Primitiv ist der Desktop-Smoke: ```bash pnpm openclaw qa mantis desktop-browser-smoke \ --output-dir .artifacts/qa-e2e/mantis/desktop-browser ``` -Es least eine Crabbox-Desktop-Maschine oder verwendet sie erneut, startet einen sichtbaren Browser innerhalb der +Es least oder verwendet eine Crabbox-Desktop-Maschine wieder, startet einen sichtbaren Browser innerhalb der VNC-Sitzung, erfasst den Desktop, zieht Artefakte zurück in das lokale Ausgabe- -verzeichnis und schreibt den Wiederverbindungsbefehl in den Bericht. Der Befehl verwendet standardmäßig -den Hetzner-Provider, weil er der erste Provider mit funktionierender Desktop/VNC- +verzeichnis und schreibt den Reconnect-Befehl in den Bericht. Der Befehl verwendet standardmäßig +den Hetzner-Provider, weil er der erste Provider mit funktionierender Desktop-/VNC- Abdeckung in der Mantis-Lane ist. Überschreiben Sie ihn mit `--provider`, `--crabbox-bin` oder `OPENCLAW_MANTIS_CRABBOX_PROVIDER`, wenn Sie gegen eine andere Crabbox-Flotte ausführen. Nützliche Desktop-Smoke-Flags: -- `--lease-id ` oder `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` verwendet einen vorgewärmten Desktop erneut. +- `--lease-id ` oder `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` verwendet einen vorgewärmten Desktop wieder. - `--browser-url ` ändert die Seite, die im sichtbaren Browser geöffnet wird. -- `--html-file ` rendert ein repo-lokales HTML-Artefakt im sichtbaren Browser. Mantis verwendet dies, um die generierte Discord-Statusreaktions-Timeline über einen echten Crabbox-Desktop zu erfassen. -- `--keep-lease` oder `OPENCLAW_MANTIS_KEEP_VM=1` hält eine neu erstellte erfolgreiche Lease für die VNC-Prüfung offen. Fehlgeschlagene Läufe halten die Lease standardmäßig offen, wenn eine erstellt wurde, damit ein Operator sich erneut verbinden kann. -- `--class`, `--idle-timeout` und `--ttl` stimmen Maschinengröße und Lease-Lebensdauer ab. +- `--html-file ` rendert ein repo-lokales HTML-Artefakt im sichtbaren Browser. Mantis verwendet dies, um die generierte Discord-Status-Reaktions-Timeline über einen echten Crabbox-Desktop zu erfassen. +- `--keep-lease` oder `OPENCLAW_MANTIS_KEEP_VM=1` hält eine neu erstellte, bestandene Lease für VNC-Inspektion offen. Fehlgeschlagene Läufe behalten die Lease standardmäßig, wenn eine erstellt wurde, damit ein Operator erneut verbinden kann. +- `--class`, `--idle-timeout` und `--ttl` steuern Maschinengröße und Lease-Lebensdauer. -Der GitHub-Smoke-Workflow ist `Mantis Discord Smoke`. Der Vorher/Nachher-GitHub- +Das erste vollständige Desktop-Transport-Primitiv ist der Slack-Desktop-Smoke: + +```bash +pnpm openclaw qa mantis slack-desktop-smoke \ + --output-dir .artifacts/qa-e2e/mantis/slack-desktop \ + --gateway-setup \ + --scenario slack-canary \ + --keep-lease +``` + +Es least oder verwendet eine Crabbox-Desktop-Maschine wieder, synchronisiert den aktuellen Checkout in +die VM, führt `pnpm openclaw qa slack` innerhalb dieser VM aus, öffnet Slack Web im VNC- +Browser, erfasst den sichtbaren Desktop und kopiert sowohl die Slack-QA-Artefakte als auch +den VNC-Screenshot zurück in das lokale Ausgabeverzeichnis. Dies ist die erste Mantis- +Form, bei der der SUT OpenClaw Gateway und der Browser beide in derselben +Linux-Desktop-VM leben. + +Mit `--gateway-setup` bereitet der Befehl ein persistentes, wegwerfbares OpenClaw- +Home unter `$HOME/.openclaw-mantis/slack-openclaw` vor, patcht die Slack-Socket-Mode- +Konfiguration für den ausgewählten Kanal, startet `openclaw gateway run` auf Port +`38973` und lässt Chrome in der VNC-Sitzung weiterlaufen. Dies ist der Modus „geben Sie mir einen +Linux-Desktop mit Slack und einer laufenden claw“; die Bot-zu-Bot-Slack-QA-Lane +bleibt der Standard, wenn `--gateway-setup` weggelassen wird. + +Erforderliche Eingaben für `--credential-source env`: + +- `OPENCLAW_QA_SLACK_CHANNEL_ID` +- `OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN` +- `OPENCLAW_QA_SLACK_SUT_BOT_TOKEN` +- `OPENCLAW_QA_SLACK_SUT_APP_TOKEN` +- `OPENCLAW_LIVE_OPENAI_KEY` für die Remote-Model-Lane. Wenn lokal nur + `OPENAI_API_KEY` gesetzt ist, ordnet Mantis ihn `OPENCLAW_LIVE_OPENAI_KEY` + zu, bevor Crabbox aufgerufen wird, damit Crabboxs `OPENCLAW_*`-Env-Weiterleitung ihn + in die VM tragen kann. + +Nützliche Slack-Desktop-Flags: + +- `--lease-id ` führt erneut gegen eine Maschine aus, auf der ein Operator sich bereits per VNC bei Slack Web angemeldet hat. +- `--gateway-setup` startet einen persistenten OpenClaw-Slack-Gateway in der VM, statt nur die Bot-zu-Bot-QA-Lane auszuführen. +- `--slack-url ` öffnet eine bestimmte Slack-Web-URL. Ohne diese leitet Mantis `https://app.slack.com/client//` aus Slack `auth.test` ab, wenn das SUT-Bot-Token verfügbar ist. +- `--slack-channel-id ` steuert die Slack-Kanal-Allowlist, die vom Gateway-Setup verwendet wird. +- `OPENCLAW_MANTIS_SLACK_BROWSER_PROFILE_DIR` steuert das persistente Chrome-Profil innerhalb der VM. Standard ist `$HOME/.config/openclaw-mantis/slack-chrome-profile`, sodass ein manueller Slack-Web-Login erneute Läufe auf derselben Lease überlebt. +- `--credential-source convex --credential-role ci` verwendet den gemeinsamen Zugangsdatenpool statt direkter Slack-Env-Tokens. +- `--provider-mode`, `--model`, `--alt-model` und `--fast` werden an die Slack-Live-Lane weitergereicht. + +Der GitHub-Smoke-Workflow ist `Mantis Discord Smoke`. Der Vorher- und Nachher-GitHub- Workflow für das erste echte Szenario ist `Mantis Discord Status Reactions`. Er akzeptiert: -- `baseline_ref`: die Ref, von der erwartet wird, dass sie das reine Warteschlangenverhalten reproduziert. -- `candidate_ref`: die Ref, von der erwartet wird, dass sie `queued -> thinking -> done` zeigt. +- `baseline_ref`: der Ref, von dem erwartet wird, dass er das Nur-queued-Verhalten reproduziert. +- `candidate_ref`: der Ref, von dem erwartet wird, dass er `queued -> thinking -> done` zeigt. -Er checkt die Workflow-Harness-Ref aus, baut separate Baseline- und Kandidaten- +Er checkt den Workflow-Harness-Ref aus, baut separate Baseline- und Kandidaten- Worktrees, führt `discord-status-reactions-tool-only` gegen jeden Worktree aus und lädt `baseline/`, `candidate/`, `comparison.json` und `mantis-report.md` als -Actions-Artefakte hoch. Er rendert außerdem die Timeline-HTML jeder Lane in einem Crabbox- +Actions-Artefakte hoch. Außerdem rendert er die Timeline-HTML jeder Lane in einem Crabbox- Desktop-Browser und veröffentlicht diese VNC-Screenshots neben den deterministischen Timeline-PNGs im PR-Kommentar. Der Workflow baut die Crabbox-CLI aus -`openclaw/crabbox` main, damit er die aktuellen Desktop/Browser-Lease-Flags verwenden kann, -bevor das nächste Crabbox-Binary-Release erstellt wird. +`openclaw/crabbox` main, damit er die aktuellen Desktop-/Browser-Lease-Flags verwenden kann, +bevor das nächste Crabbox-Binary-Release geschnitten wird. -Sie können den Statusreaktionslauf auch direkt über einen PR-Kommentar auslösen: +Sie können den Status-Reactions-Lauf auch direkt über einen PR-Kommentar auslösen: ```text @Mantis discord status reactions ``` Der Kommentar-Trigger ist absichtlich eng gefasst. Er läuft nur bei Pull-Request- -Kommentaren von Benutzern mit Schreib-, Maintainer- oder Admin-Zugriff, und er erkennt nur -Discord-Statusreaktionsanfragen. Standardmäßig verwendet er die bekannte fehlerhafte Baseline-Ref +Kommentaren von Benutzern mit write-, maintain- oder admin-Zugriff, und er erkennt nur +Discord-Status-Reaction-Anfragen. Standardmäßig verwendet er den bekannten fehlerhaften Baseline-Ref und den aktuellen PR-Head-SHA als Kandidaten. Maintainer können beide Refs überschreiben: @@ -159,31 +204,31 @@ ClawSweeper-Befehlsbeispiele: Der erste Befehl ist explizit und szenariofokussiert. Der zweite kann später einen PR oder ein Issue anhand von Labels, geänderten Dateien und -ClawSweeper-Review-Ergebnissen empfohlenen Mantis-Szenarien zuordnen. +ClawSweeper-Review-Befunden auf empfohlene Mantis-Szenarien abbilden. -## Lauflebenszyklus +## Lauf-Lebenszyklus -1. Anmeldedaten abrufen. -2. Eine VM zuweisen oder erneut verwenden. -3. Das Desktop/Browser-Profil vorbereiten, wenn das Szenario UI-Nachweise benötigt. -4. Einen sauberen Checkout für die Baseline-Ref vorbereiten. -5. Abhängigkeiten installieren und nur das bauen, was das Szenario benötigt. -6. Ein untergeordnetes OpenClaw Gateway mit einem isolierten Zustandsverzeichnis starten. -7. Live-Transport, Provider, Modell und Browserprofil konfigurieren. +1. Zugangsdaten beschaffen. +2. Eine VM zuweisen oder wiederverwenden. +3. Das Desktop-/Browser-Profil vorbereiten, wenn das Szenario UI-Nachweise benötigt. +4. Einen sauberen Checkout für den Baseline-Ref vorbereiten. +5. Abhängigkeiten installieren und nur bauen, was das Szenario benötigt. +6. Einen untergeordneten OpenClaw Gateway mit einem isolierten Zustandsverzeichnis starten. +7. Live-Transport, Provider, Model und Browser-Profil konfigurieren. 8. Das Szenario ausführen und Baseline-Nachweise erfassen. -9. Das Gateway stoppen und Logs bewahren. -10. Die Kandidaten-Ref in derselben VM vorbereiten. +9. Den Gateway stoppen und Logs bewahren. +10. Den Kandidaten-Ref in derselben VM vorbereiten. 11. Dasselbe Szenario ausführen und Kandidaten-Nachweise erfassen. -12. Oracle-Ergebnisse und visuelle Nachweise vergleichen. +12. Orakel-Ergebnisse und visuelle Nachweise vergleichen. 13. Markdown, JSON, Logs, Screenshots und optionale Trace-Artefakte schreiben. 14. GitHub-Actions-Artefakte hochladen. -15. Eine knappe PR- oder Discord-Statusnachricht posten. +15. Eine knappe PR- oder Discord-Statusmeldung posten. -Das Szenario sollte auf zwei unterschiedliche Arten fehlschlagen können: +Das Szenario sollte auf zwei verschiedene Arten fehlschlagen können: - **Bug reproduziert**: Baseline ist auf die erwartete Weise fehlgeschlagen. -- **Harness-Fehler**: Umgebungssetup, Anmeldedaten, Discord-API, Browser oder - Provider sind fehlgeschlagen, bevor das Bug-Oracle aussagekräftig war. +- **Harness-Fehler**: Umgebungssetup, Zugangsdaten, Discord-API, Browser oder + Provider sind fehlgeschlagen, bevor das Bug-Orakel aussagekräftig war. Der finale Bericht muss diese Fälle trennen, damit Maintainer eine instabile Umgebung nicht mit Produktverhalten verwechseln. @@ -191,14 +236,14 @@ Umgebung nicht mit Produktverhalten verwechseln. ## Discord-MVP Das erste Szenario sollte Discord-Statusreaktionen in Guild-Kanälen anvisieren, in denen -der Antwortzustellmodus der Quelle `message_tool_only` ist. +der Zustellmodus der Quellantwort `message_tool_only` ist. -Warum es ein guter Mantis-Seed ist: +Warum es ein guter Mantis-Startpunkt ist: - Es ist in Discord als Reaktionen auf die auslösende Nachricht sichtbar. -- Es hat ein starkes REST-Oracle über den Discord-Nachrichtenreaktionszustand. -- Es übt ein echtes OpenClaw Gateway, Discord-Bot-Authentifizierung, Nachrichtenversand, - Quellantwort-Zustellmodus, Statusreaktionszustand und Modell-Turn-Lebenszyklus aus. +- Es hat ein starkes REST-Orakel über den Reaktionszustand von Discord-Nachrichten. +- Es übt einen echten OpenClaw Gateway, Discord-Bot-Authentifizierung, Nachrichtenversand, + Zustellmodus der Quellantwort, Statusreaktionszustand und Model-Turn-Lebenszyklus aus. - Es ist eng genug, um die erste Implementierung ehrlich zu halten. Erwartete Szenarioform: @@ -232,12 +277,12 @@ evidence: screenshotMessageRow: true ``` -Baseline-Nachweise sollten die Warteschlangen-Bestätigungsreaktion zeigen, aber keinen -Lebenszyklusübergang im Tool-only-Modus. Kandidaten-Nachweise sollten zeigen, dass Lebenszyklus- +Baseline-Nachweise sollten die queued-Bestätigungsreaktion zeigen, aber keinen +Lebenszyklusübergang im tool-only-Modus. Kandidaten-Nachweise sollten zeigen, dass Lebenszyklus- Statusreaktionen ausgeführt werden, wenn `messages.statusReactions.enabled` explizit -true ist. +`true` ist. -Der ausführbare erste Abschnitt ist das Opt-in-Discord-Live-QA-Szenario: +Der ausführbare erste Slice ist das opt-in Discord-Live-QA-Szenario: ```bash pnpm openclaw qa discord \ @@ -249,30 +294,30 @@ pnpm openclaw qa discord \ --output-dir .artifacts/qa-e2e/mantis/discord-status-reactions-candidate ``` -Es konfiguriert das SUT mit immer aktivierter Guild-Verarbeitung, `visibleReplies: -"message_tool"`, `ackReaction: "👀"` und expliziten Statusreaktionen. Das Oracle -pollt die echte auslösende Discord-Nachricht und erwartet die beobachtete Sequenz -`👀 -> 🤔 -> 👍`. Artefakte enthalten `discord-qa-reaction-timelines.json`, +Es konfiguriert das SUT mit dauerhaft aktivierter Guild-Verarbeitung, `visibleReplies: +"message_tool"`, `ackReaction: "👀"` und expliziten Status-Reaktionen. Das Oracle +fragt die echte auslösende Discord-Nachricht ab und erwartet die beobachtete Sequenz +`👀 -> 🤔 -> 👍`. Artefakte umfassen `discord-qa-reaction-timelines.json`, `discord-status-reactions-tool-only-timeline.html` und `discord-status-reactions-tool-only-timeline.png`. -## Bestehende QA-Teile +## Vorhandene QA-Bausteine -Mantis sollte auf dem bestehenden privaten QA-Stack aufbauen, statt bei -null zu beginnen: +Mantis sollte auf dem vorhandenen privaten QA-Stack aufbauen, statt bei null +anzufangen: - `pnpm openclaw qa discord` führt bereits eine Live-Discord-Lane mit Driver- und SUT-Bots aus. -- Der Live-Transport-Runner schreibt bereits Berichte und beobachtete Nachrichten- - Artefakte unter `.artifacts/qa-e2e/`. -- Convex-Anmeldedaten-Leases bieten bereits exklusiven Zugriff auf gemeinsam genutzte Live- - Transport-Anmeldedaten. -- Der Browsersteuerungsdienst unterstützt bereits Screenshots, Snapshots, - headless verwaltete Profile und Remote-CDP-Profile. -- QA Lab hat bereits eine Debugger-UI und einen Bus für transportförmige Tests. +- Der Live-Transport-Runner schreibt bereits Berichte und Artefakte zu beobachteten + Nachrichten unter `.artifacts/qa-e2e/`. +- Convex-Zugangsdaten-Leases bieten bereits exklusiven Zugriff auf gemeinsam genutzte + Live-Transport-Zugangsdaten. +- Der Browser-Control-Dienst unterstützt bereits Screenshots, Snapshots, + verwaltete Headless-Profile und Remote-CDP-Profile. +- QA Lab verfügt bereits über eine Debugger-UI und einen Bus für transportförmige Tests. -Die erste Mantis-Implementierung kann ein dünner Vorher/Nachher-Runner über diesen -Teilen sein, plus eine Ebene für visuelle Nachweise. +Die erste Mantis-Implementierung kann ein schlanker Vorher/Nachher-Runner über +diesen Bausteinen plus einer Ebene für visuelle Nachweise sein. ## Nachweismodell @@ -297,68 +342,76 @@ Jeder Lauf schreibt ein stabiles Artefaktverzeichnis: ``` `mantis-summary.json` sollte die maschinenlesbare maßgebliche Quelle sein. Der -Markdown-Bericht ist für PR-Kommentare und menschliche Prüfung. +Markdown-Bericht ist für PR-Kommentare und menschliche Prüfung gedacht. Die Zusammenfassung muss enthalten: - getestete Refs und SHAs - Transport und Szenario-ID -- Maschinen-Provider und Maschinen-ID oder Lease-ID -- Quelle der Anmeldedaten ohne Secret-Werte +- Machine-Provider und Machine-ID oder Lease-ID +- Quelle der Zugangsdaten ohne geheime Werte - Baseline-Ergebnis -- Kandidatenergebnis -- ob der Bug auf der Baseline reproduziert wurde -- ob der Kandidat ihn behoben hat +- Candidate-Ergebnis +- ob der Fehler auf der Baseline reproduziert wurde +- ob der Candidate ihn behoben hat - Artefaktpfade - bereinigte Setup- oder Cleanup-Probleme -Screenshots sind Nachweise, keine Secrets. Sie benötigen trotzdem Redaktionsdisziplin: -private Kanalnamen, Benutzernamen oder Nachrichteninhalte können erscheinen. Für öffentliche PRs -sollten GitHub-Actions-Artefaktlinks gegenüber Inline-Bildern bevorzugt werden, bis die Redaktionsgeschichte -stärker ist. +Screenshots sind Nachweise, keine Geheimnisse. Trotzdem ist sorgfältige Schwärzung +erforderlich: private Kanalnamen, Benutzernamen oder Nachrichteninhalte können +sichtbar sein. Für öffentliche PRs sollten GitHub-Actions-Artefaktlinks gegenüber +Inline-Bildern bevorzugt werden, bis die Schwärzungsstrategie robuster ist. ## Browser und VNC Die Browser-Lane hat zwei Modi: -- **Headless-Automatisierung**: Standard für CI. Chrome läuft mit aktiviertem CDP, und - Playwright oder die OpenClaw-Browsersteuerung erfasst Screenshots. -- **VNC-Rettung**: auf derselben VM aktiviert, wenn Login, MFA, Discord-Anti-Automatisierung - oder visuelles Debugging einen Menschen benötigt. +- **Headless-Automatisierung**: Standard für CI. Chrome läuft mit aktiviertem CDP, + und Playwright oder OpenClaw Browser Control erfasst Screenshots. +- **VNC-Rettung**: auf derselben VM aktiviert, wenn Anmeldung, MFA, Discord-Anti-Automatisierung + oder visuelles Debugging einen Menschen erfordern. -Das Discord-Observer-Browserprofil sollte persistent genug sein, um nicht bei jedem Lauf eine Anmeldung zu erfordern, aber vom persönlichen Browserzustand isoliert sein. Ein Profil gehört zum Mantis-Maschinenpool, nicht zu einem Entwickler-Laptop. +Das Discord-Observer-Browserprofil sollte persistent genug sein, um nicht bei jedem +Lauf eine Anmeldung zu benötigen, aber von persönlichem Browserstatus isoliert sein. +Ein Profil gehört zum Mantis-Machine-Pool, nicht zu einem Entwickler-Laptop. -Wenn Mantis hängen bleibt, postet es eine Discord-Statusmeldung mit: +Wenn Mantis feststeckt, postet es eine Discord-Statusnachricht mit: - Lauf-ID - Szenario-ID -- Maschinen-Provider +- Machine-Provider - Artefaktverzeichnis - VNC- oder noVNC-Verbindungsanweisungen, falls verfügbar - kurzem Blocker-Text -Die erste private Bereitstellung kann diese Nachrichten im bestehenden Operator-Kanal posten und später in einen dedizierten Mantis-Kanal wechseln. +Die erste private Bereitstellung kann diese Nachrichten im vorhandenen Operator-Kanal +posten und später in einen dedizierten Mantis-Kanal wechseln. -## Maschinen +## Machines -Mantis sollte für die erste Remote-Implementierung AWS über Crabbox bevorzugen. Crabbox gibt uns vorgewärmte Maschinen, Lease-Tracking, Hydration, Logs, Ergebnisse und Bereinigung. Wenn AWS-Kapazität zu langsam oder nicht verfügbar ist, fügen Sie hinter derselben Maschinenschnittstelle einen Hetzner-Provider hinzu. +Mantis sollte für die erste Remote-Implementierung AWS über Crabbox bevorzugen. +Crabbox bietet uns vorgewärmte Machines, Lease-Tracking, Hydration, Logs, Ergebnisse +und Cleanup. Wenn AWS-Kapazität zu langsam oder nicht verfügbar ist, fügen Sie einen +Hetzner-Provider hinter derselben Machine-Schnittstelle hinzu. Mindestanforderungen an die VM: -- Linux mit einer desktopfähigen Chrome- oder Chromium-Installation -- CDP-Zugriff für Browserautomatisierung -- VNC oder noVNC für Rettungszugriff +- Linux mit desktopfähiger Chrome- oder Chromium-Installation +- CDP-Zugriff für Browser-Automatisierung +- VNC oder noVNC für Rettung - Node 22 und pnpm - OpenClaw-Checkout und Dependency-Cache -- Playwright-Chromium-Browsercache, wenn Playwright verwendet wird -- genügend CPU und Arbeitsspeicher für ein OpenClaw Gateway, einen Browser und einen Modelllauf -- ausgehender Zugriff auf Discord, GitHub, Modell-Provider und den Credential Broker +- Playwright-Chromium-Browser-Cache, wenn Playwright verwendet wird +- ausreichend CPU und Arbeitsspeicher für einen OpenClaw Gateway, einen Browser und einen Modelllauf +- ausgehender Zugriff auf Discord, GitHub, Modell-Provider und den Zugangsdaten-Broker -Die VM sollte keine langlebigen Roh-Secrets außerhalb der erwarteten Credential- oder Browserprofilspeicher aufbewahren. +Die VM sollte keine langlebigen Roh-Geheimnisse außerhalb der erwarteten Speicher +für Zugangsdaten oder Browserprofile behalten. -## Secrets +## Geheimnisse -Secrets befinden sich in GitHub-Organisations- oder Repository-Secrets für Remote-Läufe und in einer lokalen, vom Operator kontrollierten Secret-Datei für lokale Läufe. +Geheimnisse liegen für Remote-Läufe in GitHub-Organisations- oder Repository-Secrets +und für lokale Läufe in einer lokal vom Operator kontrollierten Secret-Datei. Empfohlene Secret-Namen: @@ -374,26 +427,46 @@ Empfohlene Secret-Namen: - `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR` - `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR_TOKEN` -Langfristig sollte der Convex-Credential-Pool die normale Quelle für Live-Transport-Credentials bleiben. GitHub-Secrets bootstrappen den Broker und Fallback-Lanes. Der Discord-Status-Reactions-Workflow ordnet die Mantis-Crabbox-Secrets wieder den Umgebungsvariablen `CRABBOX_COORDINATOR` und `CRABBOX_COORDINATOR_TOKEN` zu, die die Crabbox-CLI erwartet. Die einfachen GitHub-Secret-Namen `CRABBOX_*` bleiben als Kompatibilitäts-Fallback akzeptiert. +Langfristig sollte der Convex-Zugangsdaten-Pool die normale Quelle für +Live-Transport-Zugangsdaten bleiben. GitHub-Secrets bootstrappen den Broker und +Fallback-Lanes. Der Discord-Status-Reactions-Workflow ordnet die Mantis-Crabbox-Secrets +wieder den Umgebungsvariablen `CRABBOX_COORDINATOR` und +`CRABBOX_COORDINATOR_TOKEN` zu, die die Crabbox-CLI erwartet. Die einfachen +GitHub-Secret-Namen `CRABBOX_*` bleiben als Kompatibilitäts-Fallback akzeptiert. -Der Mantis-Runner darf niemals Folgendes ausgeben: +Der Mantis-Runner darf niemals ausgeben: - Discord-Bot-Tokens - Provider-API-Schlüssel - Browser-Cookies - Inhalte von Auth-Profilen - VNC-Passwörter -- rohe Credential-Payloads +- rohe Zugangsdaten-Payloads -Öffentliche Artefakt-Uploads sollten außerdem Discord-Zielmetadaten wie Bot-, Guild-, Kanal- und Nachrichten-IDs schwärzen. Der GitHub-Smoke-Workflow aktiviert aus diesem Grund `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1`. +Öffentliche Artefakt-Uploads sollten außerdem Discord-Zielmetadaten wie Bot-, +Guild-, Kanal- und Nachrichten-IDs schwärzen. Der GitHub-Smoke-Workflow aktiviert +aus diesem Grund `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1`. -Wenn ein Token versehentlich in ein Issue, einen PR, einen Chat oder ein Log eingefügt wird, rotieren Sie es, nachdem das neue Secret gespeichert wurde. +Wenn ein Token versehentlich in ein Issue, einen PR, einen Chat oder ein Log eingefügt +wird, rotieren Sie ihn, nachdem das neue Secret gespeichert wurde. ## GitHub-Artefakte und PR-Kommentare -Mantis-Workflows sollten das vollständige Evidenzpaket als kurzlebiges Actions-Artefakt hochladen. Wenn der Workflow für einen Bug-Report oder Fix-PR ausgeführt wird, sollte er außerdem die geschwärzten PNG-Screenshots im Branch `qa-artifacts` veröffentlichen und einen Kommentar in diesem Bug- oder Fix-PR mit eingebetteten Vorher/Nachher-Screenshots upserten. Posten Sie den primären Nachweis nicht nur in einem generischen QA-Automatisierungs-PR. Rohe Logs, beobachtete Nachrichten und andere umfangreiche Evidenz bleiben im Actions-Artefakt. +Mantis-Workflows sollten das vollständige Nachweispaket als kurzlebiges Actions-Artefakt +hochladen. Wenn der Workflow für einen Fehlerbericht oder Fix-PR ausgeführt wird, +sollte er außerdem die geschwärzten PNG-Screenshots im Branch `qa-artifacts` +veröffentlichen und einen Kommentar zu diesem Fehler oder Fix-PR mit Inline-Vorher/Nachher-Screenshots +einfügen oder aktualisieren. Posten Sie den primären Nachweis nicht nur in einem +generischen QA-Automation-PR. Roh-Logs, beobachtete Nachrichten und andere umfangreiche +Nachweise bleiben im Actions-Artefakt. -Produktions-Workflows sollten diese Kommentare mit der Mantis-GitHub-App posten, nicht mit `github-actions[bot]`. Speichern Sie die App-ID und den privaten Schlüssel als GitHub-Actions-Secrets `MANTIS_GITHUB_APP_ID` und `MANTIS_GITHUB_APP_PRIVATE_KEY`. Der Workflow verwendet einen versteckten Marker als Upsert-Schlüssel, aktualisiert diesen Kommentar, wenn das Token ihn bearbeiten kann, und erstellt einen neuen Mantis-eigenen Kommentar, wenn ein älterer bot-eigener Marker nicht bearbeitet werden kann. +Produktions-Workflows sollten diese Kommentare mit der Mantis-GitHub-App posten, +nicht mit `github-actions[bot]`. Speichern Sie App-ID und privaten Schlüssel als +GitHub-Actions-Secrets `MANTIS_GITHUB_APP_ID` und `MANTIS_GITHUB_APP_PRIVATE_KEY`. +Der Workflow verwendet einen versteckten Marker als Upsert-Schlüssel, aktualisiert +diesen Kommentar, wenn das Token ihn bearbeiten kann, und erstellt einen neuen +Mantis-eigenen Kommentar, wenn ein älterer bot-eigener Marker nicht bearbeitet +werden kann. Der PR-Kommentar sollte kurz und visuell sein: @@ -415,60 +488,76 @@ candidate showed the expected queued -> thinking -> done sequence. | | | ``` -Wenn der Lauf fehlschlägt, weil das Harness fehlgeschlagen ist, muss der Kommentar das entsprechend sagen, statt anzudeuten, dass der Candidate fehlgeschlagen ist. +Wenn der Lauf fehlschlägt, weil das Harness fehlgeschlagen ist, muss der Kommentar +das entsprechend sagen, statt anzudeuten, dass der Candidate fehlgeschlagen ist. -## Hinweise zur privaten Bereitstellung +## Private Bereitstellungshinweise -Eine private Bereitstellung hat möglicherweise bereits eine Mantis-Discord-Anwendung. Verwenden Sie diese Anwendung erneut, statt eine weitere App zu erstellen, wenn sie die richtigen Bot-Berechtigungen hat und sicher rotiert werden kann. +Eine private Bereitstellung hat möglicherweise bereits eine Mantis-Discord-Anwendung. +Verwenden Sie diese Anwendung wieder, statt eine weitere App zu erstellen, wenn sie +die richtigen Bot-Berechtigungen hat und sicher rotiert werden kann. -Legen Sie den anfänglichen Operator-Benachrichtigungskanal über Secrets oder Bereitstellungskonfiguration fest. Er kann zunächst auf einen bestehenden Maintainer- oder Betriebskanal zeigen und später in einen dedizierten Mantis-Kanal wechseln, sobald einer existiert. +Legen Sie den anfänglichen Operator-Benachrichtigungskanal über Secrets oder +Bereitstellungskonfiguration fest. Er kann zunächst auf einen vorhandenen Maintainer- +oder Betriebskanal zeigen und später in einen dedizierten Mantis-Kanal wechseln, +sobald einer existiert. -Speichern Sie keine Guild-IDs, Kanal-IDs, Bot-Tokens, Browser-Cookies oder VNC-Passwörter in diesem Dokument. Speichern Sie sie in GitHub-Secrets, im Credential Broker oder im lokalen Secret-Speicher des Operators. +Nehmen Sie keine Guild-IDs, Kanal-IDs, Bot-Tokens, Browser-Cookies oder VNC-Passwörter +in dieses Dokument auf. Speichern Sie sie in GitHub-Secrets, im Zugangsdaten-Broker +oder im lokalen Secret-Speicher des Operators. ## Ein Szenario hinzufügen -Ein Mantis-Szenario sollte Folgendes deklarieren: +Ein Mantis-Szenario sollte deklarieren: - ID und Titel - Transport -- erforderliche Credentials +- erforderliche Zugangsdaten - Baseline-Ref-Richtlinie - Candidate-Ref-Richtlinie -- OpenClaw-Konfigurationspatch +- OpenClaw-Konfigurations-Patch - Setup-Schritte - Stimulus -- erwartetes Baseline-Orakel -- erwartetes Candidate-Orakel +- erwartetes Baseline-Oracle +- erwartetes Candidate-Oracle - Ziele für visuelle Erfassung - Timeout-Budget -- Bereinigungsschritte +- Cleanup-Schritte -Szenarien sollten kleine, typisierte Orakel bevorzugen: +Szenarien sollten kleine, typisierte Oracles bevorzugen: -- Discord-Reaktionszustand für Reaktions-Bugs -- Discord-Nachrichtenreferenzen für Threading-Bugs -- Slack-Thread-ts und Reaktions-API-Zustand für Slack-Bugs -- E-Mail-Nachrichten-IDs und Header für E-Mail-Bugs -- Browser-Screenshots, wenn die UI die einzige zuverlässige beobachtbare Größe ist +- Discord-Reaktionsstatus für Reaktionsfehler +- Discord-Nachrichtenreferenzen für Threading-Fehler +- Slack-Thread-TS und Reaction-API-Status für Slack-Fehler +- E-Mail-Nachrichten-IDs und Header für E-Mail-Fehler +- Browser-Screenshots, wenn die UI das einzige zuverlässige Beobachtbare ist -Vision-Prüfungen sollten additiv sein. Wenn eine Plattform-API den Bug beweisen kann, verwenden Sie die API als Pass/Fail-Orakel und behalten Sie Screenshots für menschliches Vertrauen bei. +Vision-Prüfungen sollten additiv sein. Wenn eine Plattform-API den Fehler nachweisen +kann, verwenden Sie die API als Pass/Fail-Oracle und behalten Sie Screenshots für +menschliches Vertrauen bei. ## Provider-Erweiterung Nach Discord kann derselbe Runner Folgendes hinzufügen: - Slack: Reaktionen, Threads, App-Erwähnungen, Modals, Datei-Uploads. -- E-Mail: Gmail-Auth und Nachrichten-Threading mit `gog`, wenn Connectors nicht ausreichen. -- WhatsApp: QR-Login, Re-Identifikation, Nachrichtenzustellung, Medien, Reaktionen. -- Telegram: Gruppenerwähnungs-Gating, Befehle, Reaktionen, wo verfügbar. -- Matrix: verschlüsselte Räume, Thread- oder Antwortbeziehungen, Wiederaufnahme nach Neustart. +- E-Mail: Gmail-Auth und Nachrichten-Threading mit `gog`, wenn Connectors nicht + ausreichen. +- WhatsApp: QR-Anmeldung, Wiedererkennung, Nachrichtenübermittlung, Medien, Reaktionen. +- Telegram: Gruppen-Erwähnungs-Gating, Befehle, Reaktionen, wo verfügbar. +- Matrix: verschlüsselte Räume, Thread- oder Antwortbeziehungen, Fortsetzung nach Neustart. -Jeder Transport sollte ein günstiges Smoke-Szenario und ein oder mehrere Bugklassen-Szenarien haben. Teure visuelle Szenarien sollten opt-in bleiben. +Jeder Transport sollte ein günstiges Smoke-Szenario und ein oder mehrere +Fehlerklassen-Szenarien haben. Teure visuelle Szenarien sollten optional bleiben. ## Offene Fragen -- Welcher Discord-Bot sollte der Driver sein und welcher das SUT, wenn der bestehende Mantis-Bot wiederverwendet wird? -- Sollte die Observer-Browser-Anmeldung für die erste Phase ein menschliches Discord-Konto, ein Testkonto oder nur bot-lesbare REST-Evidenz verwenden? +- Welcher Discord-Bot sollte der Driver sein und welcher das SUT, wenn der vorhandene + Mantis-Bot wiederverwendet wird? +- Sollte die Observer-Browser-Anmeldung in der ersten Phase ein menschliches + Discord-Konto, ein Testkonto oder nur botlesbare REST-Nachweise verwenden? - Wie lange sollte GitHub Mantis-Artefakte für PRs aufbewahren? -- Wann sollte ClawSweeper Mantis automatisch empfehlen, statt auf einen Maintainer-Befehl zu warten? -- Sollten Screenshots vor dem Upload für öffentliche PRs geschwärzt oder zugeschnitten werden? +- Wann sollte ClawSweeper automatisch Mantis empfehlen, statt auf einen + Maintainer-Befehl zu warten? +- Sollten Screenshots vor dem Upload für öffentliche PRs geschwärzt oder zugeschnitten + werden? diff --git a/docs/de/concepts/messages.md b/docs/de/concepts/messages.md index 2fb16bb64..3d5cc850b 100644 --- a/docs/de/concepts/messages.md +++ b/docs/de/concepts/messages.md @@ -1,22 +1,22 @@ --- read_when: - Erläutern, wie eingehende Nachrichten zu Antworten werden - - Sitzungen, Warteschlangenmodi oder Streaming-Verhalten klären - - Dokumentation der Sichtbarkeit von Schlussfolgerungen und der Auswirkungen auf die Nutzung + - Klärung von Sitzungen, Warteschlangenmodi oder Streaming-Verhalten + - Dokumentation der Sichtbarkeit von Denkprozessen und der Auswirkungen auf die Nutzung summary: Nachrichtenfluss, Sitzungen, Warteschlangen und Sichtbarkeit des Denkprozesses title: Nachrichten x-i18n: - generated_at: "2026-04-30T16:27:59Z" + generated_at: "2026-05-04T06:41:34Z" model: gpt-5.5 provider: openai - source_hash: fdeee014d92767a725501691fbe0c4ee6b631acc9a2ab5cbbcf321bfee9679b9 + source_hash: 15242e21fd17a9f2013561003e108d197204d834caf51bbcdc53ffb3f118b14f source_path: concepts/messages.md workflow: 16 --- -OpenClaw verarbeitet eingehende Nachrichten über eine Pipeline aus Sitzungsauflösung, Warteschlangenbildung, Streaming, Tool-Ausführung und Sichtbarkeit des Reasonings. Diese Seite zeigt den Weg von der eingehenden Nachricht bis zur Antwort. +OpenClaw verarbeitet eingehende Nachrichten über eine Pipeline aus Sitzungsauflösung, Queueing, Streaming, Tool-Ausführung und Reasoning-Sichtbarkeit. Diese Seite zeigt den Weg von der eingehenden Nachricht bis zur Antwort. -## Nachrichtenfluss (Übersicht) +## Nachrichtenfluss (allgemein) ``` Inbound message @@ -28,21 +28,25 @@ Inbound message Wichtige Stellschrauben befinden sich in der Konfiguration: -- `messages.*` für Präfixe, Warteschlangenbildung und Gruppenverhalten. -- `agents.defaults.*` für Standardwerte für Block-Streaming und Chunking. -- Channel-Overrides (`channels.whatsapp.*`, `channels.telegram.*` usw.) für Limits und Streaming-Schalter. +- `messages.*` für Präfixe, Queueing und Gruppenverhalten. +- `agents.defaults.*` für Block-Streaming und Standardwerte für Chunking. +- Kanal-Overrides (`channels.whatsapp.*`, `channels.telegram.*` usw.) für Obergrenzen und Streaming-Umschalter. -Siehe [Konfiguration](/de/gateway/configuration) für das vollständige Schema. +Das vollständige Schema finden Sie unter [Konfiguration](/de/gateway/configuration). ## Deduplizierung eingehender Nachrichten -Channels können dieselbe Nachricht nach erneuten Verbindungen erneut zustellen. OpenClaw hält einen kurzlebigen Cache, der nach Channel/Konto/Peer/Sitzung/Nachrichten-ID verschlüsselt ist, damit doppelte Zustellungen keinen weiteren Agentenlauf auslösen. +Kanäle können dieselbe Nachricht nach Wiederverbindungen erneut zustellen. OpenClaw hält einen +kurzlebigen Cache vor, der nach Kanal/Konto/Peer/Sitzung/Nachrichten-ID indiziert ist, damit doppelte +Zustellungen keinen weiteren Agentenlauf auslösen. -## Entprellung eingehender Nachrichten +## Debouncing eingehender Nachrichten -Schnell aufeinanderfolgende Nachrichten vom **gleichen Absender** können über `messages.inbound` zu einem einzelnen Agenten-Turn zusammengefasst werden. Die Entprellung ist pro Channel und Unterhaltung begrenzt und verwendet die neueste Nachricht für Antwort-Threading/IDs. +Schnelle aufeinanderfolgende Nachrichten vom **gleichen Absender** können über `messages.inbound` zu einem einzigen +Agenten-Turn gebündelt werden. Debouncing ist pro Kanal + Unterhaltung begrenzt +und verwendet die neueste Nachricht für Antwort-Threading/IDs. -Konfiguration (globaler Standardwert + Overrides pro Channel): +Konfiguration (globaler Standard + Overrides pro Kanal): ```json5 { @@ -61,119 +65,155 @@ Konfiguration (globaler Standardwert + Overrides pro Channel): Hinweise: -- Die Entprellung gilt für reine **Textnachrichten**; Medien/Anhänge werden sofort weitergegeben. -- Steuerbefehle umgehen die Entprellung, damit sie eigenständig bleiben – **außer** ein Channel entscheidet sich ausdrücklich für die Zusammenführung von Direktnachrichten desselben Absenders (z. B. [BlueBubbles `coalesceSameSenderDms`](/de/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)); dann warten DM-Befehle innerhalb des Entprellungsfensters, damit eine aufgeteilte Send-Nutzlast demselben Agenten-Turn beitreten kann. +- Debounce gilt für **reine Textnachrichten**; Medien/Anhänge werden sofort geleert. +- Steuerbefehle umgehen Debouncing, damit sie eigenständig bleiben — **außer** wenn ein Kanal sich ausdrücklich für das Zusammenführen von DMs desselben Absenders entscheidet (z. B. [BlueBubbles `coalesceSameSenderDms`](/de/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)); dort warten DM-Befehle innerhalb des Debounce-Fensters, damit eine per Split-Send gesendete Nutzlast demselben Agenten-Turn beitreten kann. ## Sitzungen und Geräte Sitzungen gehören dem Gateway, nicht den Clients. -- Direktchats werden auf den Hauptsitzungsschlüssel des Agenten reduziert. -- Gruppen/Channels erhalten eigene Sitzungsschlüssel. -- Der Sitzungsspeicher und die Transkripte liegen auf dem Gateway-Host. +- Direkte Chats werden auf den Hauptsitzungsschlüssel des Agenten zusammengeführt. +- Gruppen/Kanäle erhalten eigene Sitzungsschlüssel. +- Der Sitzungsspeicher und Transkripte liegen auf dem Gateway-Host. -Mehrere Geräte/Channels können derselben Sitzung zugeordnet werden, aber der Verlauf wird nicht vollständig an jeden Client zurücksynchronisiert. Empfehlung: Verwenden Sie für lange Unterhaltungen ein primäres Gerät, um divergierenden Kontext zu vermeiden. Die Control UI und TUI zeigen immer das Gateway-gestützte Sitzungstranskript an und sind daher die Quelle der Wahrheit. +Mehrere Geräte/Kanäle können derselben Sitzung zugeordnet werden, aber der Verlauf wird nicht vollständig +an jeden Client zurücksynchronisiert. Empfehlung: Verwenden Sie für lange +Unterhaltungen ein primäres Gerät, um abweichenden Kontext zu vermeiden. Die Control UI und TUI zeigen immer das +Gateway-gestützte Sitzungstranskript und sind daher die maßgebliche Quelle. Details: [Sitzungsverwaltung](/de/concepts/session). ## Metadaten von Tool-Ergebnissen -`content` eines Tool-Ergebnisses ist das für das Modell sichtbare Ergebnis. `details` eines Tool-Ergebnisses sind Laufzeitmetadaten für UI-Rendering, Diagnosen, Medienzustellung und Plugins. +`content` eines Tool-Ergebnisses ist das für das Modell sichtbare Ergebnis. `details` eines Tool-Ergebnisses sind +Laufzeitmetadaten für UI-Rendering, Diagnose, Medienzustellung und Plugins. OpenClaw hält diese Grenze explizit: - `toolResult.details` wird vor Provider-Replay und Compaction-Eingabe entfernt. -- Persistierte Sitzungstranskripte behalten nur begrenzte `details`; übergroße Metadaten werden durch eine kompakte Zusammenfassung ersetzt, die mit `persistedDetailsTruncated: true` markiert ist. -- Plugins und Tools sollten Text, den das Modell lesen muss, in `content` ablegen, nicht nur in `details`. +- Persistierte Sitzungstranskripte behalten nur begrenzte `details`; übergroße Metadaten + werden durch eine kompakte Zusammenfassung mit der Markierung `persistedDetailsTruncated: true` ersetzt. +- Plugins und Tools sollten Text, den das Modell lesen muss, in `content` ablegen, nicht nur + in `details`. -## Eingehende Bodys und Verlaufskontext +## Eingehende Inhalte und Verlaufskontext -OpenClaw trennt den **Prompt-Body** vom **Befehls-Body**: +OpenClaw trennt den **Prompt-Text** vom **Befehlstext**: -- `BodyForAgent`: Primärer modellseitiger Text für die aktuelle Nachricht. Channel-Plugins sollten diesen auf den aktuellen prompttragenden Text des Absenders fokussieren. -- `Body`: Legacy-Fallback für Prompts. Dies kann Channel-Umschläge und optionale Verlaufshüllen enthalten, aktuelle Channels sollten sich aber nicht darauf als primäre Modelleingabe verlassen, wenn `BodyForAgent` verfügbar ist. -- `CommandBody`: Rohtext des Benutzers für Direktiven-/Befehlsparsing. +- `BodyForAgent`: primärer, modellorientierter Text für die aktuelle Nachricht. Kanal- + Plugins sollten dies auf den aktuellen prompttragenden Text des Absenders fokussieren. +- `Body`: Legacy-Prompt-Fallback. Dies kann Kanal-Umschläge und + optionale Verlaufs-Wrapper enthalten, aber aktuelle Kanäle sollten sich nicht darauf als + primäre Modelleingabe verlassen, wenn `BodyForAgent` verfügbar ist. +- `CommandBody`: roher Benutzertext für Direktiven-/Befehlsparsing. - `RawBody`: Legacy-Alias für `CommandBody` (aus Kompatibilitätsgründen beibehalten). -Wenn ein Channel Verlauf bereitstellt, verwendet er eine gemeinsame Hülle: +Wenn ein Kanal Verlauf bereitstellt, verwendet er einen gemeinsamen Wrapper: -- `[Chatnachrichten seit Ihrer letzten Antwort – als Kontext]` -- `[Aktuelle Nachricht – darauf antworten]` +- `[Chat messages since your last reply - for context]` +- `[Current message - respond to this]` -Für **Nicht-Direktchats** (Gruppen/Channels/Räume) wird dem **aktuellen Nachrichtentext** das Absenderlabel vorangestellt (im selben Stil wie bei Verlaufseinträgen). Dadurch bleiben Echtzeit- und Warteschlangen-/Verlaufsnachrichten im Agenten-Prompt konsistent. +Bei **nicht direkten Chats** (Gruppen/Kanälen/Räumen) wird der **aktuelle Nachrichtentext** mit dem +Absenderlabel vorangestellt (derselbe Stil wie bei Verlaufseinträgen). So bleiben Echtzeit- und Queue-/Verlaufs- +Nachrichten im Agenten-Prompt konsistent. -Verlaufspuffer sind **nur ausstehend**: Sie enthalten Gruppennachrichten, die _keinen_ Lauf ausgelöst haben (zum Beispiel erwähnungsgesteuerte Nachrichten), und **schließen** Nachrichten aus, die bereits im Sitzungstranskript enthalten sind. +Verlaufspuffer sind **nur ausstehend**: Sie enthalten Gruppennachrichten, die _keinen_ +Lauf ausgelöst haben (z. B. durch Erwähnungen gesteuerte Nachrichten), und **schließen** Nachrichten aus, +die bereits im Sitzungstranskript vorhanden sind. -Das Entfernen von Direktiven gilt nur für den Abschnitt der **aktuellen Nachricht**, damit der Verlauf intakt bleibt. Channels, die Verlauf umschließen, sollten `CommandBody` (oder `RawBody`) auf den ursprünglichen Nachrichtentext setzen und `Body` als kombinierten Prompt beibehalten. Strukturierter Verlauf sowie Antwort-, weitergeleitete und Channel-Metadaten werden beim Prompt-Aufbau als nicht vertrauenswürdige Kontextblöcke mit Benutzerrolle gerendert. -Verlaufspuffer sind über `messages.groupChat.historyLimit` (globaler Standardwert) und Overrides pro Channel wie `channels.slack.historyLimit` oder `channels.telegram.accounts..historyLimit` konfigurierbar (auf `0` setzen, um sie zu deaktivieren). +Das Entfernen von Direktiven gilt nur für den Abschnitt der **aktuellen Nachricht**, damit der Verlauf +intakt bleibt. Kanäle, die Verlauf umschließen, sollten `CommandBody` (oder +`RawBody`) auf den ursprünglichen Nachrichtentext setzen und `Body` als kombinierten Prompt beibehalten. +Strukturierte Verlaufs-, Antwort-, Weiterleitungs- und Kanalmetadaten werden während der Prompt-Zusammenstellung als +nicht vertrauenswürdige Kontextblöcke mit Benutzerrolle gerendert. +Verlaufspuffer sind über `messages.groupChat.historyLimit` (globaler +Standard) und Overrides pro Kanal wie `channels.slack.historyLimit` oder +`channels.telegram.accounts..historyLimit` konfigurierbar (setzen Sie `0`, um sie zu deaktivieren). -## Warteschlangen und Follow-ups +## Queueing und Follow-ups -Wenn bereits ein Lauf aktiv ist, können eingehende Nachrichten in die Warteschlange gestellt, in den aktuellen Lauf gelenkt oder für einen Follow-up-Turn gesammelt werden. +Wenn bereits ein Lauf aktiv ist, können eingehende Nachrichten in die Queue gestellt, in den +aktuellen Lauf gesteuert oder für einen Follow-up-Turn gesammelt werden. -- Konfigurieren über `messages.queue` (und `messages.queue.byChannel`). -- Der Standardmodus ist `steer`, mit einer Follow-up-Entprellung von 500 ms, wenn Steering auf Warteschlangen-Follow-up-Zustellung zurückfällt. -- Modi: `steer`, `followup`, `collect`, `steer-backlog`, `interrupt` und der Legacy-Modus `queue` mit jeweils einer Nachricht auf einmal. +- Konfigurieren Sie dies über `messages.queue` (und `messages.queue.byChannel`). +- Der Standardmodus ist `steer`, mit einem Follow-up-Debounce von 500 ms, wenn Steering auf + Queue-basierte Follow-up-Zustellung zurückfällt. +- Modi: `steer`, `followup`, `collect`, `steer-backlog`, `interrupt` und der + Legacy-Modus `queue`, der jeweils nur eine Nachricht verarbeitet. -Details: [Befehlswarteschlange](/de/concepts/queue) und [Steering-Warteschlange](/de/concepts/queue-steering). +Details: [Befehls-Queue](/de/concepts/queue) und [Steering-Queue](/de/concepts/queue-steering). -## Besitz von Channel-Läufen +## Laufverantwortung des Kanals -Channel-Plugins können Reihenfolge bewahren, Eingaben entprellen und Transport-Backpressure anwenden, bevor eine Nachricht in die Sitzungswarteschlange gelangt. Sie sollten keinen separaten Timeout um den Agenten-Turn selbst erzwingen. Sobald eine Nachricht an eine Sitzung geroutet wurde, wird langlaufende Arbeit durch die Lebenszyklen von Sitzung, Tool und Laufzeit gesteuert, damit alle Channels langsame Turns konsistent melden und sich davon erholen. +Kanal-Plugins können die Reihenfolge beibehalten, Eingaben debouncen und Transport- +Backpressure anwenden, bevor eine Nachricht in die Sitzungs-Queue gelangt. Sie sollten keinen +separaten Timeout um den Agenten-Turn selbst erzwingen. Sobald eine Nachricht an eine +Sitzung geroutet wurde, wird lang laufende Arbeit durch den Sitzungs-, Tool- und Laufzeit- +Lebenszyklus gesteuert, damit alle Kanäle langsame Turns konsistent melden und sich davon erholen. ## Streaming, Chunking und Batching -Block-Streaming sendet Teilantworten, während das Modell Textblöcke erzeugt. Chunking berücksichtigt Channel-Textlimits und vermeidet das Aufteilen von umzäunten Codeblöcken. +Block-Streaming sendet Teilantworten, während das Modell Textblöcke erzeugt. +Chunking respektiert Textlimits von Kanälen und vermeidet das Aufteilen von Code-Fences. Wichtige Einstellungen: -- `agents.defaults.blockStreamingDefault` (`on|off`, standardmäßig aus) +- `agents.defaults.blockStreamingDefault` (`on|off`, Standard: aus) - `agents.defaults.blockStreamingBreak` (`text_end|message_end`) - `agents.defaults.blockStreamingChunk` (`minChars|maxChars|breakPreference`) -- `agents.defaults.blockStreamingCoalesce` (leerlaufbasiertes Batching) -- `agents.defaults.humanDelay` (menschenähnliche Pause zwischen Blockantworten) -- Channel-Overrides: `*.blockStreaming` und `*.blockStreamingCoalesce` (Nicht-Telegram-Channels erfordern explizit `*.blockStreaming: true`) +- `agents.defaults.blockStreamingCoalesce` (idle-basiertes Batching) +- `agents.defaults.humanDelay` (menschlich wirkende Pause zwischen Blockantworten) +- Kanal-Overrides: `*.blockStreaming` und `*.blockStreamingCoalesce` (Nicht-Telegram-Kanäle erfordern explizit `*.blockStreaming: true`) Details: [Streaming + Chunking](/de/concepts/streaming). -## Reasoning-Sichtbarkeit und Tokens +## Reasoning-Sichtbarkeit und Token OpenClaw kann Modell-Reasoning anzeigen oder ausblenden: - `/reasoning on|off|stream` steuert die Sichtbarkeit. - Reasoning-Inhalte zählen weiterhin zur Token-Nutzung, wenn sie vom Modell erzeugt werden. -- Telegram unterstützt Reasoning-Stream in die Entwurfsblase. +- Telegram unterstützt Reasoning-Streaming in eine vorübergehende Entwurfsblase, die nach der finalen Zustellung gelöscht wird; verwenden Sie `/reasoning on` für persistente Reasoning-Ausgabe. Details: [Thinking- und Reasoning-Direktiven](/de/tools/thinking) und [Token-Nutzung](/de/reference/token-use). ## Präfixe, Threading und Antworten -Die Formatierung ausgehender Nachrichten ist in `messages` zentralisiert: +Die Formatierung ausgehender Nachrichten ist zentral in `messages` gebündelt: -- `messages.responsePrefix`, `channels..responsePrefix` und `channels..accounts..responsePrefix` (Kaskade ausgehender Präfixe) sowie `channels.whatsapp.messagePrefix` (eingehendes WhatsApp-Präfix) -- Antwort-Threading über `replyToMode` und Standardwerte pro Channel +- `messages.responsePrefix`, `channels..responsePrefix` und `channels..accounts..responsePrefix` (Kaskade für ausgehende Präfixe), plus `channels.whatsapp.messagePrefix` (eingehendes WhatsApp-Präfix) +- Antwort-Threading über `replyToMode` und kanalbezogene Standardwerte -Details: [Konfiguration](/de/gateway/config-agents#messages) und Channel-Dokumentation. +Details: [Konfiguration](/de/gateway/config-agents#messages) und Kanaldokumentation. ## Stille Antworten -Das exakte stille Token `NO_REPLY` / `no_reply` bedeutet: „keine für den Benutzer sichtbare Antwort zustellen“. -Wenn ein Turn außerdem ausstehende Tool-Medien enthält, etwa generierte TTS-Audiodaten, entfernt OpenClaw den stillen Text, liefert aber weiterhin den Medienanhang aus. +Das exakte stille Token `NO_REPLY` / `no_reply` bedeutet „keine für Benutzer sichtbare Antwort zustellen“. +Wenn ein Turn außerdem ausstehende Tool-Medien hat, wie etwa erzeugtes TTS-Audio, entfernt OpenClaw +den stillen Text, stellt den Medienanhang aber weiterhin zu. OpenClaw löst dieses Verhalten nach Unterhaltungstyp auf: -- Direkte Unterhaltungen erlauben Stille standardmäßig nicht und schreiben eine bloße stille Antwort in einen kurzen sichtbaren Fallback um. -- Gruppen/Channels erlauben Stille standardmäßig. +- Direkte Unterhaltungen lassen Stille standardmäßig nicht zu und schreiben eine reine stille + Antwort in einen kurzen sichtbaren Fallback um. +- Gruppen/Kanäle erlauben Stille standardmäßig. - Interne Orchestrierung erlaubt Stille standardmäßig. -OpenClaw verwendet stille Antworten auch für interne Runner-Fehler, die vor einer Assistant-Antwort in Nicht-Direktchats auftreten, damit Gruppen/Channels keinen Gateway-Fehlertext sehen. Direktchats zeigen standardmäßig einen kompakten Fehlertext; rohe Runner-Details werden nur angezeigt, wenn `/verbose` auf `on` oder `full` steht. +OpenClaw verwendet stille Antworten auch für interne Runner-Fehler, die +vor jeder Assistentenantwort in nicht direkten Chats auftreten, damit Gruppen/Kanäle keine +Gateway-Fehlerfloskeln sehen. Direkte Chats zeigen standardmäßig einen kompakten Fehlertext; +rohe Runner-Details werden nur angezeigt, wenn `/verbose` auf `on` oder `full` steht. -Standardwerte befinden sich unter `agents.defaults.silentReply` und `agents.defaults.silentReplyRewrite`; `surfaces..silentReply` und `surfaces..silentReplyRewrite` können sie pro Oberfläche überschreiben. +Standardwerte befinden sich unter `agents.defaults.silentReply` und +`agents.defaults.silentReplyRewrite`; `surfaces..silentReply` und +`surfaces..silentReplyRewrite` können sie pro Oberfläche überschreiben. -Wenn die übergeordnete Sitzung einen oder mehrere ausstehende erzeugte Subagent-Läufe hat, werden bloße stille Antworten auf allen Oberflächen verworfen, statt umgeschrieben zu werden, damit die übergeordnete Sitzung still bleibt, bis das Abschlussereignis des Kindes die eigentliche Antwort liefert. +Wenn die übergeordnete Sitzung einen oder mehrere ausstehende gestartete Subagentenläufe hat, werden reine +stille Antworten auf allen Oberflächen verworfen, statt umgeschrieben zu werden, damit die +übergeordnete Sitzung still bleibt, bis das Abschlussereignis des Kinds die eigentliche Antwort zustellt. ## Verwandte Themen -- [Streaming](/de/concepts/streaming) – Nachrichtenzustellung in Echtzeit -- [Retry](/de/concepts/retry) – Wiederholungsverhalten bei der Nachrichtenzustellung -- [Warteschlange](/de/concepts/queue) – Warteschlange für die Nachrichtenverarbeitung -- [Channels](/de/channels) – Integrationen für Messaging-Plattformen +- [Streaming](/de/concepts/streaming) — Echtzeit-Nachrichtenzustellung +- [Wiederholung](/de/concepts/retry) — Wiederholungsverhalten bei der Nachrichtenzustellung +- [Queue](/de/concepts/queue) — Queue für die Nachrichtenverarbeitung +- [Kanäle](/de/channels) — Integrationen für Messaging-Plattformen diff --git a/docs/de/concepts/progress-drafts.md b/docs/de/concepts/progress-drafts.md index de130df7b..9c979e0be 100644 --- a/docs/de/concepts/progress-drafts.md +++ b/docs/de/concepts/progress-drafts.md @@ -1,23 +1,23 @@ --- read_when: - - Sichtbare Fortschrittsmeldungen für lang laufende Chat-Interaktionen konfigurieren - - Auswahl zwischen partiellen, blockweisen und fortschrittsbezogenen Streaming-Modi - - Erklärung, wie OpenClaw eine Kanalnachricht aktualisiert, während die Arbeit läuft - - Problembehebung bei Fortschrittsentwürfen, eigenständigen Fortschrittsmeldungen oder Finalisierungs-Fallback -summary: 'Fortschrittsentwürfe: eine sichtbare Zwischenstandsnachricht, die aktualisiert wird, während ein Agent ausgeführt wird' -title: Fortschrittsentwürfe + - Sichtbare Fortschrittsmeldungen für lang laufende Chat-Durchläufe konfigurieren + - Auswahl zwischen partiellem, Block- und Fortschritts-Streaming-Modus + - Erläuterung, wie OpenClaw eine Kanalnachricht aktualisiert, während die Arbeit läuft + - Fehlerbehebung bei Fortschrittsentwürfen, eigenständigen Fortschrittsmeldungen oder dem Fallback bei der Finalisierung +summary: 'Fortschrittsentwürfe: eine sichtbare Nachricht zum aktuellen Arbeitsstand, die aktualisiert wird, während ein Agent läuft' +title: Entwürfe voranbringen x-i18n: - generated_at: "2026-05-04T02:23:19Z" + generated_at: "2026-05-04T06:41:43Z" model: gpt-5.5 provider: openai - source_hash: 8ce19262800f1c3c3e505a3cf1d41ed5c3dffcbca168ad7b7afabdce62eee8fe + source_hash: f78c07866cd7f613012a80a40413e5866c1dd2edd477088f9fc141347f5f3788 source_path: concepts/progress-drafts.md workflow: 16 --- -Fortschrittsentwürfe lassen lang laufende Agent-Durchläufe im Chat lebendig wirken, ohne die Unterhaltung in einen Stapel temporärer Statusantworten zu verwandeln. +Fortschrittsentwürfe lassen lang laufende Agent-Ausführungen im Chat lebendig wirken, ohne die Unterhaltung in einen Stapel temporärer Statusantworten zu verwandeln. -Wenn Fortschrittsentwürfe aktiviert sind, erstellt OpenClaw erst dann eine sichtbare In-Arbeit-Nachricht, nachdem der Durchlauf zeigt, dass er echte Arbeit erledigt, aktualisiert sie, während der Agent liest, plant, Tools aufruft oder auf Genehmigung wartet, und wandelt diesen Entwurf anschließend in die endgültige Antwort um, wenn der Kanal das sicher unterstützen kann. +Wenn Fortschrittsentwürfe aktiviert sind, erstellt OpenClaw erst dann eine sichtbare Work-in-Progress-Nachricht, wenn sich zeigt, dass die Ausführung wirklich arbeitet. OpenClaw aktualisiert sie, während der Agent liest, plant, Tools aufruft oder auf Genehmigung wartet, und wandelt diesen Entwurf anschließend in die endgültige Antwort um, wenn der Channel das sicher unterstützt. ```text Shelling... @@ -26,11 +26,11 @@ Shelling... 🛠️ Exec: run tests ``` -Verwenden Sie Fortschrittsentwürfe, wenn Sie während toolintensiver Arbeit eine aufgeräumte Statusnachricht und nach Abschluss des Durchlaufs die endgültige Antwort wünschen. +Verwenden Sie Fortschrittsentwürfe, wenn Sie während tool-intensiver Arbeit eine aufgeräumte Statusnachricht und nach Abschluss der Ausführung die endgültige Antwort wünschen. ## Schnellstart -Aktivieren Sie Fortschrittsentwürfe pro Kanal mit `streaming.mode: "progress"`: +Aktivieren Sie Fortschrittsentwürfe pro Channel mit `streaming.mode: "progress"`: ```json5 { @@ -44,43 +44,42 @@ Aktivieren Sie Fortschrittsentwürfe pro Kanal mit `streaming.mode: "progress"`: } ``` -Das reicht normalerweise aus. OpenClaw wählt automatisch ein einwortiges Label, wartet, bis die Arbeit mindestens fünf Sekunden dauert oder ein zweites Arbeitsereignis ausgibt, fügt kompakte Fortschrittszeilen hinzu, während sinnvolle Arbeit geschieht, und unterdrückt doppelte eigenständige Fortschrittsmeldungen für diesen Durchlauf. +Das reicht normalerweise aus. OpenClaw wählt automatisch ein Ein-Wort-Label, wartet, bis die Arbeit mindestens fünf Sekunden dauert oder ein zweites Arbeitsereignis ausgibt, fügt kompakte Fortschrittszeilen hinzu, während nützliche Arbeit geschieht, und unterdrückt doppelte eigenständige Fortschrittsmeldungen für diese Ausführung. ## Was Benutzer sehen Ein Fortschrittsentwurf besteht aus zwei Teilen: -| Teil | Zweck | -| ------------------ | -------------------------------------------------------------------------------------- | -| Label | Ein kurzer Titel wie `Thinking...` oder `Shelling...`. | -| Fortschrittszeilen | Kompakte Laufaktualisierungen mit denselben Tool-Labels und Symbolen wie die ausführliche Ausgabe. | +| Teil | Zweck | +| ------------------- | --------------------------------------------------------------------------------------------- | +| Label | Ein kurzer Titel wie `Thinking...` oder `Shelling...`. | +| Fortschrittszeilen | Kompakte Laufzeit-Updates mit denselben Tool-Labels und Symbolen wie in der ausführlichen Ausgabe. | -Das Label erscheint, nachdem der Agent sinnvolle Arbeit beginnt und entweder fünf Sekunden lang beschäftigt bleibt oder ein zweites Arbeitsereignis ausgibt. Reine Textantworten zeigen keinen Fortschrittsentwurf. Fortschrittszeilen werden nur hinzugefügt, wenn der Agent nützliche Arbeitsaktualisierungen ausgibt, zum Beispiel `🛠️ Exec`, `🔎 Web Search` oder `✍️ Write: to /tmp/file`. -Standardmäßig verwenden sie denselben kompakten Erklärmodus wie `/verbose`; setzen Sie `agents.defaults.toolProgressDetail: "raw"`, wenn Sie debuggen und zusätzlich rohe Befehle/Details angehängt haben möchten. -Die endgültige Antwort ersetzt den Entwurf, wenn möglich; andernfalls sendet OpenClaw die endgültige Antwort normal und bereinigt den Entwurf oder beendet dessen Aktualisierung gemäß dem Transport des Kanals. +Das Label erscheint, nachdem der Agent sinnvolle Arbeit beginnt und entweder fünf Sekunden lang beschäftigt bleibt oder ein zweites Arbeitsereignis ausgibt. Reine Textantworten zeigen keinen Fortschrittsentwurf. Fortschrittszeilen werden nur hinzugefügt, wenn der Agent nützliche Arbeitsupdates ausgibt, zum Beispiel `🛠️ Exec`, `🔎 Web Search` oder `✍️ Write: to /tmp/file`. Standardmäßig verwenden sie denselben kompakten Erklärmodus wie `/verbose`; setzen Sie beim Debuggen `agents.defaults.toolProgressDetail: "raw"`, wenn Sie zusätzlich Rohbefehle oder Details anhängen möchten. +Die endgültige Antwort ersetzt den Entwurf, wenn möglich; andernfalls sendet OpenClaw die endgültige Antwort normal und bereinigt den Entwurf oder stoppt dessen Aktualisierung entsprechend dem Transport des Channels. -## Modus wählen +## Modus auswählen -`channels..streaming.mode` steuert das sichtbare In-Arbeit-Verhalten: +`channels..streaming.mode` steuert das sichtbare In-Progress-Verhalten: -| Modus | Am besten für | Was im Chat erscheint | -| ---------- | ---------------------------------------- | ------------------------------------------------------ | -| `off` | Ruhige Kanäle | Nur die endgültige Antwort. | -| `partial` | Zusehen, wie Antworttext erscheint | Ein Entwurf, der mit dem neuesten Antworttext bearbeitet wird. | -| `block` | Größere Antwortvorschau-Abschnitte | Eine Vorschau, die in größeren Abschnitten aktualisiert oder ergänzt wird. | -| `progress` | Toolintensive oder lang laufende Durchläufe | Ein Statusentwurf, dann die endgültige Antwort. | +| Modus | Am besten für | Was im Chat erscheint | +| ---------- | ------------------------------------------ | ------------------------------------------------------ | +| `off` | Ruhige Channels | Nur die endgültige Antwort. | +| `partial` | Das Erscheinen des Antworttexts beobachten | Ein Entwurf, der mit dem neuesten Antworttext bearbeitet wird. | +| `block` | Größere Antwortvorschau-Blöcke | Eine Vorschau, die in größeren Blöcken aktualisiert oder ergänzt wird. | +| `progress` | Tool-intensive oder lang laufende Ausführungen | Ein Statusentwurf, dann die endgültige Antwort. | -Wählen Sie `progress`, wenn Benutzer mehr daran interessiert sind, „was passiert“, als den Antworttext Token für Token einlaufen zu sehen. +Wählen Sie `progress`, wenn Benutzern „was gerade passiert“ wichtiger ist, als den Antworttext Token für Token zu streamen. Wählen Sie `partial`, wenn die Antwort selbst das Fortschrittssignal ist. -Wählen Sie `block`, wenn Sie Entwurfs-Vorschauaktualisierungen in größeren Textabschnitten möchten. Auf Discord und Telegram ist `streaming.mode: "block"` weiterhin Vorschau-Streaming, keine normale Blockzustellung. Verwenden Sie `streaming.block.enabled` oder das ältere `blockStreaming`, wenn Sie normale Blockantworten möchten. +Wählen Sie `block`, wenn Sie Entwurfs-Vorschauupdates in größeren Textblöcken möchten. Auf Discord und Telegram ist `streaming.mode: "block"` weiterhin Vorschau-Streaming, nicht normale Blockzustellung. Verwenden Sie `streaming.block.enabled` oder das ältere `blockStreaming`, wenn Sie normale Blockantworten möchten. ## Labels konfigurieren Fortschrittslabels befinden sich unter `channels..streaming.progress`. -Das Standardlabel ist `auto`, wodurch aus dem integrierten Label-Pool von OpenClaw mit einzelnen Wörtern und Auslassungspunkten gewählt wird: +Das Standardlabel ist `auto`; es wählt aus dem integrierten Label-Pool von OpenClaw mit Einzelwörtern und Auslassungszeichen: ```text Thinking... @@ -159,7 +158,7 @@ Blenden Sie das Label aus und zeigen Sie nur Fortschrittszeilen an: ## Fortschrittszeilen steuern -Fortschrittszeilen sind im Fortschrittsmodus standardmäßig aktiviert. Sie stammen aus echten Laufereignissen: Tool-Starts, Elementaktualisierungen, Aufgabenplänen, Genehmigungen, Befehlsausgabe, Patch-Zusammenfassungen und ähnlicher Agent-Aktivität. +Fortschrittszeilen sind im Fortschrittsmodus standardmäßig aktiviert. Sie stammen aus echten Laufereignissen: Tool-Starts, Element-Updates, Aufgabenpläne, Genehmigungen, Befehlsausgaben, Patch-Zusammenfassungen und ähnliche Agent-Aktivität. OpenClaw verwendet denselben Formatierer für Fortschrittsentwürfe und `/verbose`: @@ -173,13 +172,13 @@ OpenClaw verwendet denselben Formatierer für Fortschrittsentwürfe und `/verbos } ``` -`"explain"` ist die Voreinstellung und hält Entwürfe mit prägnanten Labels wie `🛠️ Exec: check JS syntax for /tmp/app.js` stabil. `"raw"` hängt den zugrunde liegenden Befehl bzw. das Detail an, wenn verfügbar; das ist beim Debuggen hilfreich, aber im Chat lauter. +`"explain"` ist die Standardeinstellung und hält Entwürfe mit knappen Labels wie `🛠️ Exec: check JS syntax for /tmp/app.js` stabil. `"raw"` hängt, sofern verfügbar, den zugrunde liegenden Befehl oder das Detail an. Das ist beim Debuggen nützlich, aber im Chat lauter. Zum Beispiel erscheint derselbe Befehl je nach Detailmodus unterschiedlich: | Modus | Fortschrittszeile | | --------- | ------------------------------------------------------------------- | -| `explain` | `🛠️ Exec: check JS syntax for /tmp/app.js` | +| `explain` | `🛠️ Exec: check JS syntax for /tmp/app.js` | | `raw` | `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js` | Begrenzen Sie, wie viele Zeilen sichtbar bleiben: @@ -199,6 +198,29 @@ Begrenzen Sie, wie viele Zeilen sichtbar bleiben: } ``` +Fortschrittszeilen werden automatisch verdichtet, um das Umfließen von Chat-Blasen zu reduzieren, während der Entwurf bearbeitet wird. + +OpenClaw kürzt lange Fortschrittszeilen standardmäßig, damit wiederholte Entwurfsbearbeitungen nicht bei jedem Update anders umbrechen. Das Präfix bleibt lesbar, und lange Details wie Pfade oder Rohbefehle werden mit Auslassungszeichen gekürzt. + +Slack kann Fortschrittszeilen als strukturierte Block-Kit-Felder statt als einzelnen Textkörper rendern: + +```json5 +{ + channels: { + slack: { + streaming: { + mode: "progress", + progress: { + render: "rich", + }, + }, + }, + }, +} +``` + +Rich-Rendering behält denselben Plain-Text-Fallback bei, sodass Channels und Clients ohne Unterstützung für die reichhaltigere Form weiterhin den kompakten Fortschrittstext anzeigen können. + Behalten Sie den einzelnen Fortschrittsentwurf bei, blenden Sie aber Tool- und Aufgabenzeilen aus: ```json5 @@ -216,60 +238,60 @@ Behalten Sie den einzelnen Fortschrittsentwurf bei, blenden Sie aber Tool- und A } ``` -Mit `toolProgress: false` unterdrückt OpenClaw weiterhin die älteren eigenständigen Tool-Fortschrittsnachrichten für diesen Durchlauf. Der Kanal bleibt bis zur endgültigen Antwort optisch ruhig, abgesehen vom Label, falls eines konfiguriert ist. +Mit `toolProgress: false` unterdrückt OpenClaw weiterhin die älteren eigenständigen Tool-Fortschrittsmeldungen für diese Ausführung. Der Channel bleibt bis zur endgültigen Antwort visuell ruhig, abgesehen vom Label, falls eines konfiguriert ist. -## Kanalverhalten +## Channel-Verhalten -Jeder Kanal verwendet den saubersten Transport, den er unterstützt: +Jeder Channel verwendet den saubersten Transport, den er unterstützt: -| Kanal | Fortschrittstransport | Hinweise | -| --------------- | -------------------------------------- | ---------------------------------------------------------------------- | -| Discord | Eine Nachricht senden, dann bearbeiten. | Endgültiger Text wird direkt bearbeitet, wenn er in eine sichere Vorschaunachricht passt. | -| Matrix | Ein Ereignis senden, dann bearbeiten. | Streaming-Konfiguration auf Kontoebene steuert Entwürfe auf Kontoebene. | -| Microsoft Teams | Nativer Teams-Stream in persönlichen Chats. | `streaming.mode: "block"` wird Teams-Blockzustellung zugeordnet. | +| Channel | Fortschrittstransport | Hinweise | +| --------------- | ------------------------------------- | --------------------------------------------------------------------- | +| Discord | Eine Nachricht senden und dann bearbeiten. | Endgültiger Text wird direkt bearbeitet, wenn er in eine sichere Vorschaunachricht passt. | +| Matrix | Ein Ereignis senden und dann bearbeiten. | Streaming-Konfiguration auf Kontoebene steuert Entwürfe auf Kontoebene. | +| Microsoft Teams | Nativer Teams-Stream in persönlichen Chats. | `streaming.mode: "block"` wird Teams-Blockzustellung zugeordnet. | | Slack | Nativer Stream oder bearbeitbarer Entwurfsbeitrag. | Thread-Verfügbarkeit beeinflusst, ob natives Streaming verwendet werden kann. | -| Telegram | Eine Nachricht senden, dann bearbeiten. | Ältere sichtbare Entwürfe können ersetzt werden, damit endgültige Zeitstempel nützlich bleiben. | -| Mattermost | Bearbeitbarer Entwurfsbeitrag. | Tool-Aktivität wird in denselben entwurfsartigen Beitrag integriert. | +| Telegram | Eine Nachricht senden und dann bearbeiten. | Ältere sichtbare Entwürfe können ersetzt werden, damit endgültige Zeitstempel nützlich bleiben. | +| Mattermost | Bearbeitbarer Entwurfsbeitrag. | Tool-Aktivität wird in denselben entwurfsartigen Beitrag integriert. | -Kanäle ohne sichere Bearbeitungsunterstützung fallen normalerweise auf Tippindikatoren oder reine Endzustellung zurück. +Channels ohne sichere Bearbeitungsunterstützung greifen normalerweise auf Tippindikatoren oder reine endgültige Zustellung zurück. -## Abschluss +## Finalisierung Wenn die endgültige Antwort bereit ist, versucht OpenClaw, den Chat sauber zu halten: - Wenn der Entwurf sicher zur endgültigen Antwort werden kann, bearbeitet OpenClaw ihn direkt. -- Wenn der Kanal natives Fortschritts-Streaming verwendet, schließt OpenClaw diesen Stream ab, wenn der native Transport den endgültigen Text akzeptiert. -- Wenn die endgültige Antwort Medien, eine Genehmigungsaufforderung, ein explizites Antwortziel, zu viele Abschnitte oder einen fehlgeschlagenen Bearbeitungs-/Sendevorgang enthält, sendet OpenClaw die endgültige Antwort über den normalen Zustellpfad des Kanals. +- Wenn der Channel natives Fortschrittsstreaming verwendet, finalisiert OpenClaw diesen Stream, sobald der native Transport den endgültigen Text akzeptiert. +- Wenn die endgültige Antwort Medien, eine Genehmigungsaufforderung, ein explizites Antwortziel, zu viele Blöcke oder eine fehlgeschlagene Bearbeitung bzw. Sendung enthält, sendet OpenClaw die endgültige Antwort über den normalen Zustellpfad des Channels. -Der Fallback-Pfad ist beabsichtigt. Es ist besser, eine neue endgültige Antwort zu senden, als Text zu verlieren, eine Antwort falsch in einen Thread einzuordnen oder einen Entwurf mit einer Nutzlast zu überschreiben, die der Kanal nicht sicher darstellen kann. +Der Fallback-Pfad ist absichtlich so gestaltet. Es ist besser, eine frische endgültige Antwort zu senden, als Text zu verlieren, eine Antwort falsch in einen Thread einzuordnen oder einen Entwurf mit einer Nutzlast zu überschreiben, die der Channel nicht sicher darstellen kann. ## Fehlerbehebung **Ich sehe nur die endgültige Antwort.** -Prüfen Sie, ob `channels..streaming.mode` für das Konto oder den Kanal, der die Nachricht verarbeitet hat, auf `progress` gesetzt ist. Einige Gruppen- oder Zitatantwort-Pfade können Entwurfsvorschauen für einen Durchlauf deaktivieren, wenn der Kanal die richtige Nachricht nicht sicher bearbeiten kann. +Prüfen Sie, ob `channels..streaming.mode` für das Konto oder den Channel, der die Nachricht verarbeitet hat, auf `progress` gesetzt ist. Manche Gruppen- oder Zitatantwortpfade können Entwurfsvorschauen für eine Ausführung deaktivieren, wenn der Channel die richtige Nachricht nicht sicher bearbeiten kann. **Ich sehe das Label, aber keine Tool-Zeilen.** -Prüfen Sie `streaming.progress.toolProgress`. Wenn es `false` ist, behält OpenClaw das Verhalten mit einem einzelnen Entwurf bei, blendet aber Tool- und Aufgaben-Fortschrittszeilen aus. +Prüfen Sie `streaming.progress.toolProgress`. Wenn es `false` ist, behält OpenClaw das Verhalten mit einem einzelnen Entwurf bei, blendet aber Tool- und Aufgabenfortschrittszeilen aus. **Ich sehe eine neue endgültige Nachricht statt eines bearbeiteten Entwurfs.** Das ist ein Sicherheits-Fallback. Er kann bei Medienantworten, langen Antworten, expliziten Antwortzielen, alten Telegram-Entwürfen, fehlenden Slack-Thread-Zielen, gelöschten Vorschaunachrichten oder fehlgeschlagener nativer Stream-Finalisierung auftreten. -**Ich sehe weiterhin eigenständige Fortschrittsnachrichten.** +**Ich sehe weiterhin eigenständige Fortschrittsmeldungen.** -Der Fortschrittsmodus unterdrückt standardmäßige eigenständige Tool-Fortschrittsnachrichten, wenn ein Entwurf aktiv ist. Wenn weiterhin eigenständige Nachrichten erscheinen, prüfen Sie, ob der Durchlauf tatsächlich den Fortschrittsmodus verwendet und nicht `streaming.mode: "off"` oder einen Kanalpfad, der für diese Nachricht keinen Entwurf erstellen kann. +Der Fortschrittsmodus unterdrückt standardmäßige eigenständige Tool-Fortschrittsmeldungen, wenn ein Entwurf aktiv ist. Wenn weiterhin eigenständige Nachrichten erscheinen, prüfen Sie, ob die Ausführung tatsächlich den Fortschrittsmodus verwendet und nicht `streaming.mode: "off"` oder einen Channel-Pfad, der für diese Nachricht keinen Entwurf erstellen kann. **Teams verhält sich anders als Discord oder Telegram.** -Microsoft Teams verwendet in persönlichen Chats einen nativen Stream statt des generischen Senden-und-Bearbeiten-Vorschautransports. Teams behandelt außerdem `streaming.mode: "block"` als Teams-Blockzustellung, weil es nicht denselben Entwurfsvorschau-Blockmodus hat, der von Discord und Telegram verwendet wird. +Microsoft Teams verwendet in persönlichen Chats einen nativen Stream statt des generischen Vorschau-Transports aus Senden und Bearbeiten. Teams behandelt außerdem `streaming.mode: "block"` als Teams-Blockzustellung, weil es nicht denselben Entwurfsvorschau-Blockmodus besitzt, den Discord und Telegram verwenden. ## Verwandte Themen - [Streaming und Chunking](/de/concepts/streaming) - [Nachrichten](/de/concepts/messages) -- [Kanalkonfiguration](/de/gateway/config-channels) +- [Channel-Konfiguration](/de/gateway/config-channels) - [Discord](/de/channels/discord) - [Matrix](/de/channels/matrix) - [Microsoft Teams](/de/channels/msteams) diff --git a/docs/de/concepts/qa-e2e-automation.md b/docs/de/concepts/qa-e2e-automation.md index ef65cd296..2622858ac 100644 --- a/docs/de/concepts/qa-e2e-automation.md +++ b/docs/de/concepts/qa-e2e-automation.md @@ -1,82 +1,82 @@ --- read_when: - - Verstehen, wie der QA-Stack ineinandergreift + - Verstehen, wie der QA-Stack zusammenhängt - qa-lab, qa-channel oder einen Transportadapter erweitern - - Repository-gestützte QA-Szenarien hinzufügen - - Aufbau realitätsnäherer QA-Automatisierung rund um das Gateway-Dashboard -summary: 'Übersicht über den QA-Stack: qa-lab, qa-channel, repositorygestützte Szenarien, Live-Transport-Lanes, Transportadapter und Berichterstellung.' + - Repo-gestützte QA-Szenarien hinzufügen + - Aufbau realistischerer QA-Automatisierung rund um das Gateway-Dashboard +summary: 'Überblick über den QA-Stack: qa-lab, qa-channel, repositorygestützte Szenarien, Live-Transport-Lanes, Transportadapter und Berichterstellung.' title: QA-Übersicht x-i18n: - generated_at: "2026-05-04T02:23:26Z" + generated_at: "2026-05-04T06:42:07Z" model: gpt-5.5 provider: openai - source_hash: 0b376767b967a51cc8a45ca5ce420f78067b52e6368d2abe921ffed533f6f9ba + source_hash: 067f5aa0831724659ae36d548ef2e7bd28b40aad9cef45f325a01a2748003b29 source_path: concepts/qa-e2e-automation.md workflow: 16 --- Der private QA-Stack soll OpenClaw auf realistischere, -kanalähnliche Weise ausüben, als es ein einzelner Unit-Test kann. +channel-ähnliche Weise testen, als es ein einzelner Unit-Test kann. -Aktuelle Bestandteile: +Aktuelle Komponenten: - `extensions/qa-channel`: synthetischer Nachrichtenkanal mit DM-, Kanal-, Thread-, - Reaktions-, Bearbeitungs- und Löschoberflächen. + Reaktions-, Bearbeitungs- und Löschflächen. - `extensions/qa-lab`: Debugger-UI und QA-Bus zum Beobachten des Transkripts, Einspeisen eingehender Nachrichten und Exportieren eines Markdown-Berichts. -- `extensions/qa-matrix`, zukünftige Runner-Plugins: Live-Transport-Adapter, die - einen echten Kanal innerhalb eines untergeordneten QA-Gateways steuern. -- `qa/`: repo-gestützte Seed-Assets für die Kickoff-Aufgabe und grundlegende QA- +- `extensions/qa-matrix`, künftige Runner-Plugins: Live-Transport-Adapter, die + einen echten Kanal innerhalb eines untergeordneten QA-Gateway steuern. +- `qa/`: repository-gestützte Seed-Assets für die Kickoff-Aufgabe und Baseline-QA- Szenarien. - [Mantis](/de/concepts/mantis): Vorher- und Nachher-Live-Verifizierung für Bugs, die - echte Transporte, Browser-Screenshots, VM-Zustand und PR-Nachweise benötigen. + echte Transporte, Browser-Screenshots, VM-Status und PR-Nachweise benötigen. ## Befehlsoberfläche Jeder QA-Flow läuft unter `pnpm openclaw qa `. Viele haben `pnpm qa:*`- -Skriptaliase; beide Formen werden unterstützt. +Skript-Aliase; beide Formen werden unterstützt. -| Befehl | Zweck | -| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `qa run` | Gebündelter QA-Selbstcheck; schreibt einen Markdown-Bericht. | -| `qa suite` | Führt repo-gestützte Szenarien gegen die QA-Gateway-Lane aus. Aliase: `pnpm openclaw qa suite --runner multipass` für eine kurzlebige Linux-VM. | -| `qa coverage` | Gibt das Markdown-Inventar der Szenarioabdeckung aus (`--json` für maschinenlesbare Ausgabe). | -| `qa parity-report` | Vergleicht zwei `qa-suite-summary.json`-Dateien und schreibt den agentischen Paritätsbericht. | -| `qa character-eval` | Führt das Character-QA-Szenario über mehrere Live-Modelle hinweg mit einem beurteilten Bericht aus. Siehe [Berichterstattung](#reporting). | -| `qa manual` | Führt einen einmaligen Prompt gegen die ausgewählte Provider-/Modell-Lane aus. | -| `qa ui` | Startet die QA-Debugger-UI und den lokalen QA-Bus (Alias: `pnpm qa:lab:ui`). | -| `qa docker-build-image` | Erstellt das vorgefertigte QA-Docker-Image. | -| `qa docker-scaffold` | Schreibt ein docker-compose-Gerüst für das QA-Dashboard und die Gateway-Lane. | -| `qa up` | Erstellt die QA-Site, startet den Docker-gestützten Stack und gibt die URL aus (Alias: `pnpm qa:lab:up`; die Variante `:fast` fügt `--use-prebuilt-image --bind-ui-dist --skip-ui-build` hinzu). | -| `qa aimock` | Startet nur den AIMock-Provider-Server. | -| `qa mock-openai` | Startet nur den szenariobewussten `mock-openai`-Provider-Server. | -| `qa credentials doctor` / `add` / `list` / `remove` | Verwaltet den gemeinsam genutzten Convex-Credential-Pool. | -| `qa matrix` | Live-Transport-Lane gegen einen kurzlebigen Tuwunel-Homeserver. Siehe [Matrix-QA](/de/concepts/qa-matrix). | -| `qa telegram` | Live-Transport-Lane gegen eine echte private Telegram-Gruppe. | -| `qa discord` | Live-Transport-Lane gegen einen echten privaten Discord-Guild-Kanal. | -| `qa slack` | Live-Transport-Lane gegen einen echten privaten Slack-Kanal. | -| `qa mantis` | Vorher- und Nachher-Verifizierungs-Runner für Live-Transport-Bugs, mit Discord-Statusreaktionsnachweis und einem Crabbox-Desktop-/Browser-Smoke. Siehe [Mantis](/de/concepts/mantis). | +| Befehl | Zweck | +| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `qa run` | Gebündelter QA-Selbsttest; schreibt einen Markdown-Bericht. | +| `qa suite` | Führt repository-gestützte Szenarien gegen die QA-Gateway-Lane aus. Aliase: `pnpm openclaw qa suite --runner multipass` für eine kurzlebige Linux-VM. | +| `qa coverage` | Gibt das Markdown-Inventar der Szenarioabdeckung aus (`--json` für maschinenlesbare Ausgabe). | +| `qa parity-report` | Vergleicht zwei `qa-suite-summary.json`-Dateien und schreibt den agentischen Paritätsbericht. | +| `qa character-eval` | Führt das Charakter-QA-Szenario über mehrere Live-Modelle hinweg mit bewertetem Bericht aus. Siehe [Berichterstattung](#reporting). | +| `qa manual` | Führt einen einmaligen Prompt gegen die ausgewählte Provider-/Modell-Lane aus. | +| `qa ui` | Startet die QA-Debugger-UI und den lokalen QA-Bus (Alias: `pnpm qa:lab:ui`). | +| `qa docker-build-image` | Baut das vorgefertigte QA-Docker-Image. | +| `qa docker-scaffold` | Schreibt ein docker-compose-Gerüst für das QA-Dashboard und die Gateway-Lane. | +| `qa up` | Baut die QA-Site, startet den Docker-gestützten Stack und gibt die URL aus (Alias: `pnpm qa:lab:up`; die Variante `:fast` ergänzt `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). | +| `qa aimock` | Startet nur den AIMock-Provider-Server. | +| `qa mock-openai` | Startet nur den szenariobewussten `mock-openai`-Provider-Server. | +| `qa credentials doctor` / `add` / `list` / `remove` | Verwaltet den gemeinsam genutzten Convex-Anmeldedatenpool. | +| `qa matrix` | Live-Transport-Lane gegen einen kurzlebigen Tuwunel-Homeserver. Siehe [Matrix-QA](/de/concepts/qa-matrix). | +| `qa telegram` | Live-Transport-Lane gegen eine echte private Telegram-Gruppe. | +| `qa discord` | Live-Transport-Lane gegen einen echten privaten Discord-Guild-Kanal. | +| `qa slack` | Live-Transport-Lane gegen einen echten privaten Slack-Kanal. | +| `qa mantis` | Vorher- und Nachher-Verifizierungs-Runner für Live-Transport-Bugs, mit Discord-Statusreaktionsnachweisen, Crabbox-Desktop-/Browser-Smoke und Slack-in-VNC-Smoke. Siehe [Mantis](/de/concepts/mantis). | ## Operator-Flow Der aktuelle QA-Operator-Flow ist eine zweigeteilte QA-Site: - Links: Gateway-Dashboard (Control UI) mit dem Agenten. -- Rechts: QA Lab mit dem Slack-ähnlichen Transkript und Szenarioplan. +- Rechts: QA Lab, mit dem Slack-artigen Transkript und dem Szenarioplan. -Starten Sie ihn mit: +Führen Sie ihn aus mit: ```bash pnpm qa:lab:up ``` -Das erstellt die QA-Site, startet die Docker-gestützte Gateway-Lane und stellt die +Das baut die QA-Site, startet die Docker-gestützte Gateway-Lane und stellt die QA-Lab-Seite bereit, auf der ein Operator oder eine Automatisierungsschleife dem Agenten eine QA-Mission geben, echtes Kanalverhalten beobachten und aufzeichnen kann, was funktioniert hat, fehlgeschlagen ist oder blockiert blieb. Für schnellere QA-Lab-UI-Iteration ohne jedes Mal das Docker-Image neu zu bauen, -starten Sie den Stack mit einem bind-gemounteten QA-Lab-Bundle: +starten Sie den Stack mit einem per Bind-Mount eingebundenen QA-Lab-Bundle: ```bash pnpm openclaw qa docker-build-image @@ -87,38 +87,38 @@ pnpm qa:lab:watch `qa:lab:up:fast` hält die Docker-Dienste auf einem vorgefertigten Image und bind-mountet `extensions/qa-lab/web/dist` in den `qa-lab`-Container. `qa:lab:watch` -erstellt dieses Bundle bei Änderungen neu, und der Browser lädt automatisch neu, -wenn sich der QA-Lab-Asset-Hash ändert. +baut dieses Bundle bei Änderungen neu, und der Browser lädt automatisch neu, wenn sich der +Asset-Hash von QA Lab ändert. -Für einen lokalen OpenTelemetry-Trace-Smoke führen Sie aus: +Für einen lokalen OpenTelemetry-Trace-Smoke führen Sie Folgendes aus: ```bash pnpm qa:otel:smoke ``` -Dieses Skript startet einen lokalen OTLP/HTTP-Trace-Receiver, führt das -`otel-trace-smoke`-QA-Szenario mit aktiviertem `diagnostics-otel`-Plugin aus, -dekodiert dann die exportierten Protobuf-Spans und prüft die releasekritische -Struktur: `openclaw.run`, `openclaw.harness.run`, `openclaw.model.call`, +Dieses Skript startet einen lokalen OTLP/HTTP-Trace-Empfänger, führt das +QA-Szenario `otel-trace-smoke` mit aktiviertem Plugin `diagnostics-otel` aus, +dekodiert anschließend die exportierten Protobuf-Spans und prüft die release-kritische Form: +`openclaw.run`, `openclaw.harness.run`, `openclaw.model.call`, `openclaw.context.assembled` und `openclaw.message.delivery` müssen vorhanden sein; -Modellaufrufe dürfen bei erfolgreichen Turns kein `StreamAbandoned` exportieren; -Rohdiagnose-IDs und Attribute vom Typ `openclaw.content.*` müssen aus dem Trace -herausbleiben. Es schreibt `otel-smoke-summary.json` neben die QA-Suite-Artefakte. +Modellaufrufe dürfen bei erfolgreichen Turns kein `StreamAbandoned` exportieren; rohe Diagnose-IDs und +`openclaw.content.*`-Attribute müssen aus dem Trace herausbleiben. Es schreibt +`otel-smoke-summary.json` neben die QA-Suite-Artefakte. -Observability-QA bleibt nur für Source-Checkouts vorgesehen. Der npm-Tarball lässt -QA Lab absichtlich aus, sodass Package-Docker-Release-Lanes keine `qa`-Befehle -ausführen. Verwenden Sie `pnpm qa:otel:smoke` aus einem gebauten Source-Checkout, -wenn Sie die Diagnoseinstrumentierung ändern. +Observability-QA bleibt nur für Source-Checkouts verfügbar. Der npm-Tarball lässt +QA Lab absichtlich aus, daher führen Docker-Package-Release-Lanes keine `qa`-Befehle aus. Verwenden Sie +`pnpm qa:otel:smoke` aus einem gebauten Source-Checkout heraus, wenn Sie die Diagnose- +Instrumentierung ändern. -Für eine transportechte Matrix-Smoke-Lane führen Sie aus: +Für eine transport-echte Matrix-Smoke-Lane führen Sie Folgendes aus: ```bash pnpm openclaw qa matrix --profile fast --fail-fast ``` -Die vollständige CLI-Referenz, der Profil-/Szenariokatalog, Umgebungsvariablen und das Artefaktlayout für diese Lane befinden sich in [Matrix-QA](/de/concepts/qa-matrix). Kurz gesagt: Sie stellt einen kurzlebigen Tuwunel-Homeserver in Docker bereit, registriert temporäre Driver-/SUT-/Observer-Benutzer, führt das echte Matrix-Plugin innerhalb eines untergeordneten QA-Gateways aus, das auf diesen Transport beschränkt ist (kein `qa-channel`), und schreibt anschließend einen Markdown-Bericht, eine JSON-Zusammenfassung, ein Artefakt mit beobachteten Ereignissen und ein kombiniertes Ausgabelog unter `.artifacts/qa-e2e/matrix-/`. +Die vollständige CLI-Referenz, der Profil-/Szenariokatalog, die Env-Vars und das Artefaktlayout für diese Lane befinden sich in [Matrix-QA](/de/concepts/qa-matrix). Kurzüberblick: Sie stellt einen kurzlebigen Tuwunel-Homeserver in Docker bereit, registriert temporäre Driver-/SUT-/Observer-Benutzer, führt das echte Matrix-Plugin innerhalb eines untergeordneten QA-Gateway aus, das auf diesen Transport beschränkt ist (kein `qa-channel`), und schreibt anschließend einen Markdown-Bericht, eine JSON-Zusammenfassung, ein Artefakt mit beobachteten Ereignissen und ein kombiniertes Ausgabelog unter `.artifacts/qa-e2e/matrix-/`. -Für transportechte Telegram-, Discord- und Slack-Smoke-Lanes: +Für transport-echte Telegram-, Discord- und Slack-Smoke-Lanes: ```bash pnpm openclaw qa telegram @@ -126,73 +126,90 @@ pnpm openclaw qa discord pnpm openclaw qa slack ``` -Sie zielen auf einen bereits vorhandenen echten Kanal mit zwei Bots (Driver + SUT). Erforderliche Umgebungsvariablen, Szenariolisten, Ausgabeartefakte und der Convex-Credential-Pool sind unten in der [Telegram-, Discord- und Slack-QA-Referenz](#telegram-discord-and-slack-qa-reference) dokumentiert. +Sie zielen auf einen bereits vorhandenen echten Kanal mit zwei Bots (Driver + SUT). Erforderliche Env-Vars, Szenariolisten, Ausgabeartefakte und der Convex-Anmeldedatenpool sind unten in der [QA-Referenz für Telegram, Discord und Slack](#telegram-discord-and-slack-qa-reference) dokumentiert. -Bevor Sie gepoolte Live-Credentials verwenden, führen Sie aus: +Für einen vollständigen Slack-Desktop-VM-Lauf mit VNC-Rettung führen Sie Folgendes aus: + +```bash +pnpm openclaw qa mantis slack-desktop-smoke \ + --gateway-setup \ + --scenario slack-canary \ + --keep-lease +``` + +Dieser Befehl least eine Crabbox-Desktop-/Browser-Maschine, führt die Slack-Live-Lane +innerhalb der VM aus, öffnet Slack Web im VNC-Browser, erfasst den Desktop und +kopiert `slack-qa/` sowie `slack-desktop-smoke.png` zurück in das Mantis-Artefakt- +verzeichnis. Verwenden Sie `--lease-id ` erneut, nachdem Sie sich manuell +über VNC bei Slack Web angemeldet haben. Mit `--gateway-setup` lässt Mantis ein +persistentes OpenClaw-Slack-Gateway innerhalb der VM auf Port `38973` laufen; ohne diese Option führt der Befehl die +normale Bot-zu-Bot-Slack-QA-Lane aus und beendet sich nach der Artefakterfassung. + +Bevor Sie gepoolte Live-Anmeldedaten verwenden, führen Sie Folgendes aus: ```bash pnpm openclaw qa credentials doctor ``` -Der Doctor prüft die Convex-Broker-Umgebung, validiert Endpoint-Einstellungen und verifiziert die Erreichbarkeit von Admin/List, wenn das Maintainer-Secret vorhanden ist. Er meldet für Secrets nur den Status gesetzt/fehlend. +Der Doctor prüft die Convex-Broker-Umgebung, validiert Endpoint-Einstellungen und verifiziert die Erreichbarkeit von Admin/List, wenn das Maintainer-Secret vorhanden ist. Für Secrets meldet er nur den Status gesetzt/fehlend. ## Live-Transport-Abdeckung -Live-Transport-Lanes teilen sich einen Vertrag, anstatt dass jede ihre eigene Form der Szenarioliste erfindet. `qa-channel` ist die breite synthetische Suite für Produktverhalten und ist nicht Teil der Live-Transport-Abdeckungsmatrix. +Live-Transport-Lanes teilen sich einen Vertrag, statt dass jede ihre eigene Form für Szenariolisten erfindet. `qa-channel` ist die breite synthetische Suite für Produktverhalten und gehört nicht zur Live-Transport-Abdeckungsmatrix. -| Lane | Canary | Mention-Gating | Bot-zu-Bot | Allowlist-Block | Antwort auf oberster Ebene | Neustart-Fortsetzung | Thread-Follow-up | Thread-Isolation | Reaktionsbeobachtung | Hilfebefehl | Native Befehlsregistrierung | +| Lane | Canary | Mention-Gating | Bot-zu-Bot | Allowlist-Block | Top-Level-Antwort | Neustart-Fortsetzung | Thread-Follow-up | Thread-Isolation | Reaktionsbeobachtung | Hilfebefehl | Native Befehlsregistrierung | | -------- | ------ | -------------- | ---------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | --------------------------- | | Matrix | x | x | x | x | x | x | x | x | x | | | | Telegram | x | x | x | | | | | | | x | | | Discord | x | x | x | | | | | | | | x | | Slack | x | x | x | | | | | | | | | -Dies behält `qa-channel` als breite Suite für Produktverhalten bei, während Matrix, -Telegram und zukünftige Live-Transporte eine explizite Transportvertrags- -Checkliste teilen. +So bleibt `qa-channel` die breite Suite für Produktverhalten, während Matrix, +Telegram und künftige Live-Transporte eine gemeinsame explizite Checkliste für den Transportvertrag +teilen. -Für eine kurzlebige Linux-VM-Lane, ohne Docker in den QA-Pfad einzubeziehen, führen Sie aus: +Für eine kurzlebige Linux-VM-Lane ohne Docker in den QA-Pfad einzubeziehen, führen Sie Folgendes aus: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -Dies bootet einen frischen Multipass-Gast, installiert Abhängigkeiten, erstellt OpenClaw +Dies startet einen frischen Multipass-Gast, installiert Abhängigkeiten, baut OpenClaw im Gast, führt `qa suite` aus und kopiert dann den normalen QA-Bericht und die Zusammenfassung zurück nach `.artifacts/qa-e2e/...` auf dem Host. -Es verwendet dasselbe Verhalten zur Szenarioauswahl wie `qa suite` auf dem Host. +Es verwendet dasselbe Verhalten für die Szenarioauswahl wie `qa suite` auf dem Host. Host- und Multipass-Suite-Läufe führen standardmäßig mehrere ausgewählte Szenarien parallel -mit isolierten Gateway-Workern aus. `qa-channel` verwendet standardmäßig Parallelität -4, begrenzt durch die Anzahl der ausgewählten Szenarien. Verwenden Sie `--concurrency `, um -die Worker-Anzahl anzupassen, oder `--concurrency 1` für serielle Ausführung. -Der Befehl beendet mit einem Nicht-Null-Code, wenn ein Szenario fehlschlägt. Verwenden Sie `--allow-failures`, wenn -Sie Artefakte ohne fehlschlagenden Exit-Code möchten. -Live-Läufe leiten die unterstützten QA-Auth-Eingaben weiter, die für den -Gast praktikabel sind: umgebungsbasierte Provider-Schlüssel, den QA-Live-Provider-Konfigurationspfad und -`CODEX_HOME`, wenn vorhanden. Halten Sie `--output-dir` unterhalb der Repo-Wurzel, damit der Gast -durch den gemounteten Workspace zurückschreiben kann. +mit isolierten Gateway-Workern aus. `qa-channel` verwendet standardmäßig eine Nebenläufigkeit +von 4, begrenzt durch die Anzahl der ausgewählten Szenarien. Verwenden Sie `--concurrency `, +um die Anzahl der Worker anzupassen, oder `--concurrency 1` für serielle Ausführung. +Der Befehl beendet sich mit einem Nicht-Null-Code, wenn ein Szenario fehlschlägt. Verwenden Sie +`--allow-failures`, wenn Sie Artefakte ohne fehlschlagenden Exit-Code erhalten möchten. +Live-Läufe leiten die unterstützten QA-Authentifizierungseingaben weiter, die für den +Gast praktikabel sind: env-basierte Provider-Schlüssel, den Pfad zur QA-Live-Provider-Konfiguration und +`CODEX_HOME`, wenn vorhanden. Belassen Sie `--output-dir` unterhalb des Repo-Roots, damit der Gast +über den eingehängten Arbeitsbereich zurückschreiben kann. -## Telegram-, Discord- und Slack-QA-Referenz +## Referenz für Telegram-, Discord- und Slack-QA -Matrix hat wegen seiner Szenarioanzahl und der Docker-gestützten Homeserver-Bereitstellung eine [eigene Seite](/de/concepts/qa-matrix). Telegram, Discord und Slack sind kleiner — jeweils eine Handvoll Szenarien, kein Profilsystem, gegen bereits vorhandene echte Kanäle — daher befindet sich ihre Referenz hier. +Matrix hat wegen seiner Szenarioanzahl und der Docker-gestützten Homeserver-Bereitstellung eine [eigene Seite](/de/concepts/qa-matrix). Telegram, Discord und Slack sind kleiner: jeweils eine Handvoll Szenarien, kein Profilsystem, gegen bereits vorhandene echte Kanäle. Daher befindet sich ihre Referenz hier. ### Gemeinsame CLI-Flags Diese Lanes registrieren sich über `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` und akzeptieren dieselben Flags: -| Flag | Standardwert | Beschreibung | -| ------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -| `--scenario ` | — | Nur dieses Szenario ausführen. Wiederholbar. | -| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord,slack}-` | Ort, an den Berichte/Zusammenfassung/beobachtete Nachrichten und das Ausgabeprotokoll geschrieben werden. Relative Pfade werden gegen `--repo-root` aufgelöst. | -| `--repo-root ` | `process.cwd()` | Repository-Root beim Aufruf aus einem neutralen cwd. | -| `--sut-account ` | `sut` | Temporäre Konto-ID innerhalb der QA-Gateway-Konfiguration. | -| `--provider-mode ` | `live-frontier` | `mock-openai` oder `live-frontier` (das ältere `live-openai` funktioniert weiterhin). | -| `--model ` / `--alt-model ` | Provider-Standardwert | Referenzen für primäres/alternatives Modell. | -| `--fast` | aus | Schneller Provider-Modus, sofern unterstützt. | -| `--credential-source ` | `env` | Siehe [Convex-Anmeldeinformationspool](#convex-credential-pool). | -| `--credential-role ` | `ci` in CI, sonst `maintainer` | Rolle, die bei `--credential-source convex` verwendet wird. | +| Flag | Standard | Beschreibung | +| ------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | +| `--scenario ` | — | Nur dieses Szenario ausführen. Wiederholbar. | +| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord,slack}-` | Ort, an den Berichte/Zusammenfassung/beobachtete Nachrichten und das Ausgabelog geschrieben werden. Relative Pfade werden relativ zu `--repo-root` aufgelöst. | +| `--repo-root ` | `process.cwd()` | Repository-Root beim Aufruf aus einem neutralen Arbeitsverzeichnis. | +| `--sut-account ` | `sut` | Temporäre Konto-ID innerhalb der QA-Gateway-Konfiguration. | +| `--provider-mode ` | `live-frontier` | `mock-openai` oder `live-frontier` (das ältere `live-openai` funktioniert weiterhin). | +| `--model ` / `--alt-model ` | Provider-Standard | Primäre/alternative Modell-Refs. | +| `--fast` | aus | Schneller Provider-Modus, sofern unterstützt. | +| `--credential-source ` | `env` | Siehe [Convex-Anmeldeinformationspool](#convex-credential-pool). | +| `--credential-role ` | `ci` in CI, andernfalls `maintainer` | Rolle, die bei `--credential-source convex` verwendet wird. | -Jede Lane beendet sich mit einem von null verschiedenen Exit-Code, wenn ein Szenario fehlschlägt. `--allow-failures` schreibt Artefakte, ohne einen fehlerhaften Exit-Code zu setzen. +Jede Lane beendet sich bei einem fehlgeschlagenen Szenario mit einem Nicht-Null-Code. `--allow-failures` schreibt Artefakte, ohne einen fehlschlagenden Exit-Code zu setzen. ### Telegram-QA @@ -200,9 +217,9 @@ Jede Lane beendet sich mit einem von null verschiedenen Exit-Code, wenn ein Szen pnpm openclaw qa telegram ``` -Zielt auf eine echte private Telegram-Gruppe mit zwei unterschiedlichen Bots (Driver + SUT). Der SUT-Bot muss einen Telegram-Benutzernamen haben; Bot-zu-Bot-Beobachtung funktioniert am besten, wenn bei beiden Bots der **Bot-to-Bot Communication Mode** in `@BotFather` aktiviert ist. +Zielt auf eine echte private Telegram-Gruppe mit zwei unterschiedlichen Bots (Treiber + SUT). Der SUT-Bot muss einen Telegram-Benutzernamen haben; Bot-zu-Bot-Beobachtung funktioniert am besten, wenn beide Bots in `@BotFather` den **Bot-to-Bot Communication Mode** aktiviert haben. -Erforderliche Umgebungsvariablen bei `--credential-source env`: +Erforderliche env bei `--credential-source env`: - `OPENCLAW_QA_TELEGRAM_GROUP_ID` — numerische Chat-ID (String). - `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` @@ -210,7 +227,7 @@ Erforderliche Umgebungsvariablen bei `--credential-source env`: Optional: -- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` behält Nachrichtentexte in Artefakten mit beobachteten Nachrichten bei (standardmäßig redigiert). +- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` behält Nachrichtentexte in Artefakten mit beobachteten Nachrichten bei (standardmäßig geschwärzt). Szenarien (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts:44`): @@ -226,8 +243,8 @@ Szenarien (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime Ausgabeartefakte: - `telegram-qa-report.md` -- `telegram-qa-summary.json` — enthält RTT pro Antwort (Driver-Senden → beobachtete SUT-Antwort), beginnend mit dem Canary. -- `telegram-qa-observed-messages.json` — Nachrichtentexte redigiert, außer `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`. +- `telegram-qa-summary.json` — enthält RTT pro Antwort (Treibersendung → beobachtete SUT-Antwort), beginnend mit dem Canary. +- `telegram-qa-observed-messages.json` — Texte geschwärzt, außer `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`. ### Discord-QA @@ -235,15 +252,15 @@ Ausgabeartefakte: pnpm openclaw qa discord ``` -Zielt auf einen echten privaten Discord-Guild-Channel mit zwei Bots: einen vom Harness gesteuerten Driver-Bot und einen SUT-Bot, der vom untergeordneten OpenClaw-Gateway über das gebündelte Discord-Plugin gestartet wird. Verifiziert die Verarbeitung von Channel-Erwähnungen, dass der SUT-Bot den nativen `/help`-Befehl bei Discord registriert hat, sowie Opt-in-Mantis-Evidenzszenarien. +Zielt auf einen echten privaten Discord-Guild-Kanal mit zwei Bots: einen vom Harness gesteuerten Treiber-Bot und einen SUT-Bot, der vom untergeordneten OpenClaw-Gateway über das gebündelte Discord-Plugin gestartet wird. Prüft die Verarbeitung von Kanal-Erwähnungen, dass der SUT-Bot den nativen `/help`-Befehl bei Discord registriert hat, sowie optionale Mantis-Beweisszenarien. -Erforderliche Umgebungsvariablen bei `--credential-source env`: +Erforderliche env bei `--credential-source env`: - `OPENCLAW_QA_DISCORD_GUILD_ID` - `OPENCLAW_QA_DISCORD_CHANNEL_ID` - `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN` - `OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN` -- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — muss mit der von Discord zurückgegebenen SUT-Bot-Benutzer-ID übereinstimmen (andernfalls schlägt die Lane sofort fehl). +- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — muss mit der von Discord zurückgegebenen Benutzer-ID des SUT-Bots übereinstimmen (andernfalls schlägt die Lane früh fehl). Optional: @@ -254,9 +271,9 @@ Szenarien (`extensions/qa-lab/src/live-transports/discord/discord-live.runtime.t - `discord-canary` - `discord-mention-gating` - `discord-native-help-command-registration` -- `discord-status-reactions-tool-only` — Opt-in-Mantis-Szenario. Wird eigenständig ausgeführt, weil es den SUT auf durchgehend aktive, rein toolbasierte Guild-Antworten mit `messages.statusReactions.enabled=true` umstellt und anschließend eine REST-Reaktionszeitleiste sowie ein visuelles HTML/PNG-Artefakt erfasst. +- `discord-status-reactions-tool-only` — optionales Mantis-Szenario. Läuft für sich allein, weil es den SUT auf immer aktive, reine Tool-Guild-Antworten mit `messages.statusReactions.enabled=true` umschaltet und dann eine REST-Reaktions-Timeline plus ein visuelles HTML/PNG-Artefakt erfasst. -Das Mantis-Statusreaktionsszenario explizit ausführen: +Führen Sie das Mantis-Statusreaktionsszenario explizit aus: ```bash pnpm openclaw qa discord \ @@ -271,8 +288,8 @@ Ausgabeartefakte: - `discord-qa-report.md` - `discord-qa-summary.json` -- `discord-qa-observed-messages.json` — Nachrichtentexte redigiert, außer `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1`. -- `discord-qa-reaction-timelines.json` und `discord-status-reactions-tool-only-timeline.png`, wenn das Statusreaktionsszenario ausgeführt wird. +- `discord-qa-observed-messages.json` — Texte geschwärzt, außer `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1`. +- `discord-qa-reaction-timelines.json` und `discord-status-reactions-tool-only-timeline.png`, wenn das Statusreaktionsszenario läuft. ### Slack-QA @@ -280,9 +297,9 @@ Ausgabeartefakte: pnpm openclaw qa slack ``` -Zielt auf einen echten privaten Slack-Channel mit zwei unterschiedlichen Bots: einen vom Harness gesteuerten Driver-Bot und einen SUT-Bot, der vom untergeordneten OpenClaw-Gateway über das gebündelte Slack-Plugin gestartet wird. +Zielt auf einen echten privaten Slack-Kanal mit zwei unterschiedlichen Bots: einen vom Harness gesteuerten Treiber-Bot und einen SUT-Bot, der vom untergeordneten OpenClaw-Gateway über das gebündelte Slack-Plugin gestartet wird. -Erforderliche Umgebungsvariablen bei `--credential-source env`: +Erforderliche env bei `--credential-source env`: - `OPENCLAW_QA_SLACK_CHANNEL_ID` - `OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN` @@ -302,120 +319,132 @@ Ausgabeartefakte: - `slack-qa-report.md` - `slack-qa-summary.json` -- `slack-qa-observed-messages.json` — Nachrichtentexte redigiert, außer `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1`. +- `slack-qa-observed-messages.json` — Texte geschwärzt, außer `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1`. ### Convex-Anmeldeinformationspool -Telegram-, Discord- und Slack-Lanes können Anmeldeinformationen aus einem gemeinsamen Convex-Pool leasen, statt die oben genannten Umgebungsvariablen zu lesen. Übergeben Sie `--credential-source convex` (oder setzen Sie `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`); QA Lab erwirbt ein exklusives Lease, sendet dafür während der Ausführung Heartbeats und gibt es beim Herunterfahren frei. Pool-Arten sind `"telegram"`, `"discord"` und `"slack"`. +Telegram-, Discord- und Slack-Lanes können Anmeldeinformationen aus einem gemeinsamen Convex-Pool leasen, statt die obigen env vars zu lesen. Übergeben Sie `--credential-source convex` (oder setzen Sie `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`); QA Lab erwirbt einen exklusiven Lease, sendet während des Laufs Heartbeats dafür und gibt ihn beim Herunterfahren frei. Pool-Arten sind `"telegram"`, `"discord"` und `"slack"`. Payload-Formen, die der Broker bei `admin/add` validiert: - Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` muss ein numerischer Chat-ID-String sein. - Discord (`kind: "discord"`): `{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }`. -Operative Umgebungsvariablen und der Vertrag für den Convex-Broker-Endpunkt befinden sich in [Testing → Gemeinsame Telegram-Anmeldeinformationen über Convex](/de/help/testing#shared-telegram-credentials-via-convex-v1) (der Abschnittsname stammt aus der Zeit vor der Discord-Unterstützung; die Broker-Semantik ist für beide Arten identisch). +Betriebliche env vars und der Vertrag des Convex-Broker-Endpunkts befinden sich unter [Testing → Gemeinsame Telegram-Anmeldeinformationen über Convex](/de/help/testing#shared-telegram-credentials-via-convex-v1) (der Abschnittsname stammt aus der Zeit vor der Discord-Unterstützung; die Broker-Semantik ist für beide Arten identisch). -## Repository-gestützte Seeds +## Repo-gestützte Seeds -Seed-Assets liegen in `qa/`: +Seed-Assets befinden sich in `qa/`: - `qa/scenarios/index.md` - `qa/scenarios//*.md` -Diese befinden sich absichtlich in Git, damit der QA-Plan sowohl für Menschen als auch für den Agent sichtbar ist. +Diese liegen absichtlich in Git, damit der QA-Plan sowohl für Menschen als auch für den +Agent sichtbar ist. -`qa-lab` sollte ein generischer Markdown-Runner bleiben. Jede Szenario-Markdown-Datei ist die maßgebliche Quelle für einen Testlauf und sollte Folgendes definieren: +`qa-lab` sollte ein generischer Markdown-Runner bleiben. Jede Szenario-Markdown-Datei ist +die Quelle der Wahrheit für einen Testlauf und sollte Folgendes definieren: -- Szenariometadaten -- optionale Metadaten zu Kategorie, Fähigkeit, Lane und Risiko -- Dokumentations- und Code-Referenzen +- Szenario-Metadaten +- optionale Kategorie-, Capability-, Lane- und Risikometadaten +- Docs- und Code-Refs - optionale Plugin-Anforderungen - optionaler Gateway-Konfigurationspatch - den ausführbaren `qa-flow` -Die wiederverwendbare Runtime-Oberfläche, die `qa-flow` zugrunde liegt, darf generisch und bereichsübergreifend bleiben. Markdown-Szenarien können zum Beispiel transportseitige Hilfsfunktionen mit browserseitigen Hilfsfunktionen kombinieren, die die eingebettete Control UI über die Gateway-`browser.request`-Seam steuern, ohne einen speziellen Runner hinzuzufügen. +Die wiederverwendbare Laufzeitoberfläche, die `qa-flow` unterstützt, darf generisch +und querschnittlich bleiben. Beispielsweise können Markdown-Szenarien transportseitige +Hilfsfunktionen mit browserseitigen Hilfsfunktionen kombinieren, die die eingebettete Control UI über den +Gateway-`browser.request`-Seam steuern, ohne einen Sonderfall-Runner hinzuzufügen. -Szenariodateien sollten nach Produktfähigkeit statt nach Quellbaumordner gruppiert werden. Halten Sie Szenario-IDs stabil, wenn Dateien verschoben werden; verwenden Sie `docsRefs` und `codeRefs` für die Nachverfolgbarkeit der Implementierung. +Szenariodateien sollten nach Produkt-Capability gruppiert werden, nicht nach Source-Tree-Ordner. Halten Sie Szenario-IDs stabil, wenn Dateien verschoben werden; verwenden Sie `docsRefs` und `codeRefs` für Implementierungsnachverfolgbarkeit. Die Baseline-Liste sollte breit genug bleiben, um Folgendes abzudecken: -- DM- und Channel-Chat +- DM- und Kanal-Chat - Thread-Verhalten - Lebenszyklus von Nachrichtenaktionen - Cron-Callbacks - Speicherabruf - Modellwechsel - Subagent-Übergabe -- Repository-Lesen und Dokumentationslesen +- Repo-Lesen und Docs-Lesen - eine kleine Build-Aufgabe wie Lobster Invaders ## Provider-Mock-Lanes `qa suite` hat zwei lokale Provider-Mock-Lanes: -- `mock-openai` ist der szenariobewusste OpenClaw-Mock. Er bleibt die standardmäßige deterministische Mock-Lane für repository-gestützte QA und Paritäts-Gates. -- `aimock` startet einen AIMock-gestützten Provider-Server für experimentelle Protokoll-, Fixture-, Record/Replay- und Chaos-Abdeckung. Er ist additiv und ersetzt den `mock-openai`-Szenario-Dispatcher nicht. +- `mock-openai` ist der szenariobewusste OpenClaw-Mock. Er bleibt die standardmäßige + deterministische Mock-Lane für repo-gestützte QA und Parity-Gates. +- `aimock` startet einen AIMock-gestützten Provider-Server für experimentelle Protokoll-, + Fixture-, Record/Replay- und Chaos-Abdeckung. Er ist additiv und ersetzt nicht + den `mock-openai`-Szenario-Dispatcher. -Die Provider-Lane-Implementierung liegt unter `extensions/qa-lab/src/providers/`. Jeder Provider besitzt seine Standardwerte, den Start des lokalen Servers, die Gateway-Modellkonfiguration, Staging-Anforderungen für Auth-Profile und Live/Mock-Fähigkeitsflags. Gemeinsamer Suite- und Gateway-Code sollte über die Provider-Registry routen, statt nach Provider-Namen zu verzweigen. +Die Implementierung der Provider-Lanes befindet sich unter `extensions/qa-lab/src/providers/`. +Jeder Provider besitzt seine Defaults, den Start des lokalen Servers, die Gateway-Modellkonfiguration, +Staging-Anforderungen für Authentifizierungsprofile und Live-/Mock-Capability-Flags. Gemeinsamer Suite- und +Gateway-Code sollte über die Provider-Registry routen, statt nach +Provider-Namen zu verzweigen. ## Transportadapter -`qa-lab` besitzt eine generische Transport-Seam für Markdown-QA-Szenarien. `qa-channel` ist der erste Adapter auf dieser Seam, aber das Designziel ist breiter: Zukünftige echte oder synthetische Channels sollten in denselben Suite-Runner eingesteckt werden, statt einen transportspezifischen QA-Runner hinzuzufügen. +`qa-lab` besitzt einen generischen Transport-Seam für Markdown-QA-Szenarien. `qa-channel` ist der erste Adapter an diesem Seam, aber das Entwurfsziel ist breiter: Künftige echte oder synthetische Kanäle sollten sich in denselben Suite-Runner einklinken, statt einen transportspezifischen QA-Runner hinzuzufügen. Auf Architekturebene ist die Aufteilung: -- `qa-lab` besitzt generische Szenarioausführung, Worker-Parallelität, Artefaktschreiben und Reporting. +- `qa-lab` besitzt generische Szenarioausführung, Worker-Nebenläufigkeit, Artefaktschreiben und Reporting. - Der Transportadapter besitzt Gateway-Konfiguration, Bereitschaft, eingehende und ausgehende Beobachtung, Transportaktionen und normalisierten Transportzustand. -- Markdown-Szenariodateien unter `qa/scenarios/` definieren den Testlauf; `qa-lab` stellt die wiederverwendbare Runtime-Oberfläche bereit, die sie ausführt. +- Markdown-Szenariodateien unter `qa/scenarios/` definieren den Testlauf; `qa-lab` stellt die wiederverwendbare Laufzeitoberfläche bereit, die sie ausführt. -### Einen Channel hinzufügen +### Einen Kanal hinzufügen -Das Hinzufügen eines Channels zum Markdown-QA-System erfordert genau zwei Dinge: +Das Hinzufügen eines Kanals zum Markdown-QA-System erfordert genau zwei Dinge: -1. Einen Transportadapter für den Channel. -2. Ein Szenariopaket, das den Channel-Vertrag ausübt. +1. Einen Transportadapter für den Kanal. +2. Ein Szenariopaket, das den Kanalvertrag ausübt. -Fügen Sie keinen neuen Top-Level-QA-Befehlsstamm hinzu, wenn der gemeinsame `qa-lab`-Host den Ablauf besitzen kann. +Fügen Sie keinen neuen Top-Level-QA-Befehls-Root hinzu, wenn der gemeinsame `qa-lab`-Host den Flow besitzen kann. -`qa-lab` besitzt die gemeinsamen Host-Mechaniken: +`qa-lab` ist für die gemeinsamen Host-Mechaniken zuständig: -- den `openclaw qa`-Befehlsstamm -- Suite-Start und -Teardown +- die Befehlswurzel `openclaw qa` +- Start und Teardown der Suite - Worker-Parallelität -- Artefaktschreiben -- Berichtsgenerierung +- Schreiben von Artefakten +- Berichtserstellung - Szenarioausführung -- Kompatibilitätsaliase für ältere `qa-channel`-Szenarien +- Kompatibilitätsaliasse für ältere `qa-channel`-Szenarien -Runner-Plugins besitzen den Transportvertrag: +Runner-Plugins sind für den Transportvertrag zuständig: -- wie `openclaw qa ` unterhalb des gemeinsamen `qa`-Stamms eingehängt wird -- wie das Gateway für diesen Transport konfiguriert wird -- wie die Bereitschaft geprüft wird -- wie eingehende Ereignisse injiziert werden +- wie `openclaw qa ` unterhalb der gemeinsamen `qa`-Wurzel eingebunden wird +- wie der Gateway für diesen Transport konfiguriert wird +- wie Bereitschaft geprüft wird +- wie eingehende Events injiziert werden - wie ausgehende Nachrichten beobachtet werden - wie Transkripte und normalisierter Transportzustand offengelegt werden - wie transportgestützte Aktionen ausgeführt werden -- wie transportspezifisches Zurücksetzen oder Aufräumen gehandhabt wird +- wie transportspezifisches Zurücksetzen oder Bereinigen behandelt wird -Die Mindestanforderung für die Einführung eines neuen Channels: +Die Mindestanforderungen für die Einführung eines neuen Kanals: -1. Behalten Sie `qa-lab` als Owner der gemeinsamen `qa`-Root bei. -2. Implementieren Sie den Transport-Runner auf der gemeinsamen Host-Schnittstelle von `qa-lab`. -3. Belassen Sie transportspezifische Mechaniken im Runner-Plugin oder Channel-Harness. +1. Behalten Sie `qa-lab` als Owner der gemeinsamen `qa`-Wurzel bei. +2. Implementieren Sie den Transport-Runner auf der gemeinsamen Host-Naht von `qa-lab`. +3. Behalten Sie transportspezifische Mechaniken im Runner-Plugin oder Channel-Harness. 4. Binden Sie 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 `qaRunnerCliRegistrations`-Array aus `runtime-api.ts` exportieren. Halten Sie `runtime-api.ts` schlank; Lazy-CLI und Runner-Ausführung sollten hinter separaten Einstiegspunkten bleiben. -5. Erstellen oder adaptieren Sie Markdown-Szenarien in den thematischen `qa/scenarios/`-Verzeichnissen. -6. Verwenden Sie die generischen Szenariohelfer für neue Szenarien. -7. Halten Sie vorhandene Kompatibilitätsaliase funktionsfähig, sofern das Repo keine absichtliche Migration durchführt. +5. Erstellen oder adaptieren Sie Markdown-Szenarien unter den thematisch gegliederten `qa/scenarios/`-Verzeichnissen. +6. Verwenden Sie die generischen Szenario-Helfer für neue Szenarien. +7. Halten Sie vorhandene Kompatibilitätsaliasse funktionsfähig, sofern das Repo keine absichtliche Migration durchführt. Die Entscheidungsregel ist strikt: -- Wenn Verhalten einmal in `qa-lab` ausgedrückt werden kann, legen Sie es in `qa-lab` ab. -- Wenn Verhalten von einem Kanaltransport abhängt, belassen Sie es in diesem Runner-Plugin oder Plugin-Harness. -- Wenn ein Szenario eine neue Fähigkeit benötigt, die mehr als ein Kanal verwenden kann, fügen Sie einen generischen Helfer hinzu, statt eine kanalspezifische Verzweigung in `suite.ts` einzubauen. -- Wenn ein Verhalten nur für einen Transport sinnvoll ist, halten Sie das Szenario transportspezifisch und machen Sie dies im Szenariovertrag explizit. +- Wenn Verhalten einmalig in `qa-lab` ausgedrückt werden kann, platzieren Sie es in `qa-lab`. +- Wenn Verhalten von einem Channel-Transport abhängt, behalten Sie es in diesem Runner-Plugin oder Plugin-Harness. +- Wenn ein Szenario eine neue Fähigkeit benötigt, die mehr als ein Channel verwenden kann, fügen Sie einen generischen Helfer hinzu statt eines channelspezifischen 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 explizit. -### Namen der Szenariohelfer +### Namen von Szenario-Helfern Bevorzugte generische Helfer für neue Szenarien: @@ -432,21 +461,21 @@ Bevorzugte generische Helfer für neue Szenarien: - `formatTransportTranscript` - `resetTransport` -Kompatibilitätsaliase bleiben für bestehende Szenarien verfügbar — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — aber neue Szenarien sollten die generischen Namen verwenden. Die Aliase existieren, um eine Flag-Day-Migration zu vermeiden, nicht als künftiges Modell. +Kompatibilitätsaliasse bleiben für vorhandene Szenarien verfügbar — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — aber neue Szenarien sollten die generischen Namen verwenden. Die Aliasse existieren, um eine Flag-Day-Migration zu vermeiden, nicht als Modell für die Zukunft. -## Berichterstellung +## Berichterstattung -`qa-lab` exportiert einen Markdown-Protokollbericht aus der beobachteten Bus-Zeitachse. +`qa-lab` exportiert einen Markdown-Protokollbericht aus der beobachteten Bus-Zeitleiste. Der Bericht sollte beantworten: - Was funktioniert hat - Was fehlgeschlagen ist -- Was blockiert blieb -- Welche Follow-up-Szenarien es wert sind, hinzugefügt zu werden +- Was blockiert geblieben ist +- Welche Folgeszenarien ergänzt werden sollten -Für das Inventar verfügbarer Szenarien — nützlich beim Dimensionieren von Follow-up-Arbeiten oder beim Verdrahten eines neuen Transports — führen Sie `pnpm openclaw qa coverage` aus (fügen Sie `--json` für maschinenlesbare Ausgabe hinzu). +Für das Inventar der verfügbaren Szenarien — nützlich beim Dimensionieren von Folgearbeiten oder beim Verdrahten eines neuen Transports — führen Sie `pnpm openclaw qa coverage` aus (fügen Sie `--json` für maschinenlesbare Ausgabe hinzu). -Führen Sie für Zeichen- und Stilprüfungen dasselbe Szenario über mehrere Live-Modell-Refs hinweg aus und schreiben Sie einen beurteilten Markdown-Bericht: +Für Zeichen- und Stilprüfungen führen Sie dasselbe Szenario über mehrere Live-Modell-Refs aus und schreiben einen bewerteten Markdown-Bericht: ```bash pnpm openclaw qa character-eval \ @@ -465,21 +494,17 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -Der Befehl führt lokale QA-Gateway-Kindprozesse aus, nicht Docker. Character-Eval-Szenarien sollten die Persona über `SOUL.md` festlegen und dann gewöhnliche Benutzer-Turns ausführen, etwa Chat, Workspace-Hilfe und kleine Datei-Aufgaben. Dem Kandidatenmodell sollte nicht mitgeteilt werden, dass es evaluiert wird. Der Befehl bewahrt jedes vollständige Transkript auf, erfasst grundlegende Laufstatistiken und bittet dann die Judge-Modelle im schnellen Modus mit `xhigh`-Reasoning, wo unterstützt, die Läufe nach Natürlichkeit, Vibe und Humor zu rangieren. -Verwenden Sie `--blind-judge-models`, wenn Sie Provider vergleichen: Der Judge-Prompt erhält weiterhin jedes Transkript und jeden Laufstatus, aber Kandidaten-Refs werden durch neutrale Bezeichnungen wie `candidate-01` ersetzt; der Bericht ordnet Ranglisten nach dem Parsen wieder den echten Refs zu. -Kandidatenläufe verwenden standardmäßig `high`-Thinking, mit `medium` für GPT-5.5 und `xhigh` für ältere OpenAI-Eval-Refs, die dies unterstützen. Überschreiben Sie einen bestimmten Kandidaten inline mit `--model provider/model,thinking=`. `--thinking ` legt weiterhin einen globalen Fallback fest, und die ältere Form `--model-thinking ` bleibt aus Kompatibilitätsgründen erhalten. -OpenAI-Kandidaten-Refs verwenden standardmäßig den schnellen Modus, damit Priority Processing genutzt wird, sofern der Provider es unterstützt. Fügen Sie inline `,fast`, `,no-fast` oder `,fast=false` hinzu, wenn ein einzelner Kandidat oder Judge eine Überschreibung benötigt. Übergeben Sie `--fast` nur, wenn Sie den schnellen Modus für jedes Kandidatenmodell erzwingen möchten. Kandidaten- und Judge-Dauern werden für Benchmark-Analysen im Bericht erfasst, aber Judge-Prompts sagen ausdrücklich, nicht nach Geschwindigkeit zu rangieren. -Kandidaten- und Judge-Modellläufe verwenden beide standardmäßig eine Parallelität von 16. Senken Sie `--concurrency` oder `--judge-concurrency`, wenn Provider-Limits oder lokaler Gateway-Druck einen Lauf zu verrauscht machen. -Wenn kein Kandidaten-`--model` übergeben wird, verwendet Character Eval standardmäßig `openai/gpt-5.5`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, -`moonshot/kimi-k2.5` und -`google/gemini-3.1-pro-preview`, wenn kein `--model` übergeben wird. -Wenn kein `--judge-model` übergeben wird, verwenden die Judges standardmäßig -`openai/gpt-5.5,thinking=xhigh,fast` und -`anthropic/claude-opus-4-6,thinking=high`. +Der Befehl führt lokale QA-Gateway-Child-Prozesse aus, nicht Docker. Character-Eval-Szenarien sollten die Persona über `SOUL.md` setzen und dann normale Benutzer-Turns ausführen, etwa Chat, Workspace-Hilfe und kleine Dateiaufgaben. Dem Kandidatenmodell sollte nicht mitgeteilt werden, dass es evaluiert wird. Der Befehl bewahrt jedes vollständige Transkript auf, zeichnet grundlegende Laufstatistiken auf und bittet dann die Judge-Modelle im schnellen Modus mit `xhigh`-Reasoning, soweit unterstützt, die Läufe nach Natürlichkeit, Vibe und Humor zu bewerten. +Verwenden Sie `--blind-judge-models`, wenn Sie Provider vergleichen: Der Judge-Prompt erhält weiterhin jedes Transkript und jeden Laufstatus, aber Kandidaten-Refs werden durch neutrale Labels wie `candidate-01` ersetzt; der Bericht ordnet die Rankings nach dem Parsen wieder den echten Refs zu. +Kandidatenläufe verwenden standardmäßig `high`-Thinking, mit `medium` für GPT-5.5 und `xhigh` für ältere OpenAI-Eval-Refs, die es unterstützen. Überschreiben Sie einen bestimmten Kandidaten inline mit `--model provider/model,thinking=`. `--thinking ` setzt weiterhin einen globalen Fallback, und die ältere Form `--model-thinking ` bleibt aus Kompatibilitätsgründen erhalten. +OpenAI-Kandidaten-Refs verwenden standardmäßig den schnellen Modus, damit Priority Processing genutzt wird, sofern der Provider es unterstützt. Fügen Sie inline `,fast`, `,no-fast` oder `,fast=false` hinzu, wenn ein einzelner Kandidat oder Judge eine Überschreibung benötigt. Übergeben Sie `--fast` nur, wenn Sie den schnellen Modus für jedes Kandidatenmodell erzwingen möchten. Kandidaten- und Judge-Dauern werden im Bericht für Benchmark-Analysen aufgezeichnet, aber Judge-Prompts sagen ausdrücklich, nicht nach Geschwindigkeit zu ranken. +Kandidaten- und Judge-Modellläufe verwenden beide standardmäßig Parallelität 16. Senken Sie `--concurrency` oder `--judge-concurrency`, wenn Provider-Limits oder lokaler Gateway-Druck einen Lauf zu verrauscht machen. +Wenn kein Kandidat `--model` übergeben wird, verwendet die Character-Eval standardmäßig `openai/gpt-5.5`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, `moonshot/kimi-k2.5` und `google/gemini-3.1-pro-preview`, wenn kein `--model` übergeben wird. +Wenn kein `--judge-model` übergeben wird, verwenden die Judges standardmäßig `openai/gpt-5.5,thinking=xhigh,fast` und `anthropic/claude-opus-4-6,thinking=high`. ## Zugehörige Dokumentation - [Matrix-QA](/de/concepts/qa-matrix) -- [QA-Kanal](/de/channels/qa-channel) +- [QA Channel](/de/channels/qa-channel) - [Testen](/de/help/testing) - [Dashboard](/de/web/dashboard) diff --git a/docs/de/concepts/streaming.md b/docs/de/concepts/streaming.md index 15998f7e1..cca268743 100644 --- a/docs/de/concepts/streaming.md +++ b/docs/de/concepts/streaming.md @@ -1,29 +1,29 @@ --- read_when: - - Erklärung, wie Streaming oder Chunking in Kanälen funktioniert - - Ändern des Block-Streamings oder des Verhaltens beim Aufteilen von Kanalinhalten in Chunks - - Debugging doppelter/früher Blockantworten oder des Kanalvorschau-Streamings -summary: Streaming + Chunking-Verhalten (Blockantworten, Streaming der Kanalvorschau, Moduszuordnung) -title: Streaming und Aufteilung in Datenblöcke + - Erklären, wie Streaming oder Chunking in Kanälen funktioniert + - Block-Streaming oder Channel-Chunking-Verhalten ändern + - Fehlersuche bei doppelten/verfrühten Blockantworten oder beim Streaming der Kanalvorschau +summary: Streaming- und Chunking-Verhalten (Block-Antworten, Kanalvorschau-Streaming, Moduszuordnung) +title: Streaming und Chunking x-i18n: - generated_at: "2026-05-03T21:31:08Z" + generated_at: "2026-05-04T06:42:24Z" model: gpt-5.5 provider: openai - source_hash: 1335f4f5532060bd8bf839683a2b1fbab38f38887c5583135652b4753e0f6a50 + source_hash: fcb41ceb5602ab42c3fd41a59de62cc965ea61fdbc058c052fb93689a9c5299b source_path: concepts/streaming.md workflow: 16 --- -OpenClaw hat zwei separate Streaming-Ebenen: +OpenClaw hat zwei getrennte Streaming-Ebenen: -- **Block-Streaming (Kanäle):** gibt abgeschlossene **Blöcke** aus, während der Assistent schreibt. Dies sind normale Kanalnachrichten (keine Token-Deltas). +- **Block-Streaming (Kanäle):** gibt abgeschlossene **Blöcke** aus, während der Assistent schreibt. Das sind normale Kanalnachrichten (keine Token-Deltas). - **Vorschau-Streaming (Telegram/Discord/Slack):** aktualisiert während der Generierung eine temporäre **Vorschaunachricht**. -Heute gibt es **kein echtes Token-Delta-Streaming** zu Kanalnachrichten. Vorschau-Streaming ist nachrichtenbasiert (Senden + Bearbeitungen/Anhänge). +Aktuell gibt es **kein echtes Token-Delta-Streaming** in Kanalnachrichten. Vorschau-Streaming ist nachrichtenbasiert (Senden + Bearbeitungen/Anhänge). ## Block-Streaming (Kanalnachrichten) -Block-Streaming sendet Assistentenausgabe in groben Abschnitten, sobald sie verfügbar wird. +Block-Streaming sendet Assistentenausgaben in groben Teilstücken, sobald sie verfügbar werden. ``` Model output @@ -38,24 +38,24 @@ Model output Legende: - `text_delta/events`: Modell-Stream-Ereignisse (können bei nicht streamenden Modellen spärlich sein). -- `chunker`: `EmbeddedBlockChunker`, der Mindest-/Höchstgrenzen + bevorzugte Umbruchart anwendet. -- `channel send`: tatsächliche ausgehende Nachrichten (Blockantworten). +- `chunker`: `EmbeddedBlockChunker`, der Mindest-/Höchstgrenzen + Umbruchpräferenz anwendet. +- `channel send`: tatsächliche ausgehende Nachrichten (Block-Antworten). **Steuerungen:** - `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (standardmäßig aus). -- Kanal-Overrides: `*.blockStreaming` (und kontospezifische Varianten), um pro Kanal `"on"`/`"off"` zu erzwingen. +- Kanal-Overrides: `*.blockStreaming` (und kontoabhängige Varianten), um pro Kanal `"on"`/`"off"` zu erzwingen. - `agents.defaults.blockStreamingBreak`: `"text_end"` oder `"message_end"`. - `agents.defaults.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }`. -- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (gestreamte Blöcke vor dem Senden zusammenführen). +- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (streamende Blöcke vor dem Senden zusammenführen). - Harte Kanalgrenze: `*.textChunkLimit` (z. B. `channels.whatsapp.textChunkLimit`). -- Kanal-Chunk-Modus: `*.chunkMode` (`length` als Standard, `newline` teilt vor dem Längen-Chunking an Leerzeilen (Absatzgrenzen)). -- Discord-Softlimit: `channels.discord.maxLinesPerMessage` (Standard 17) teilt hohe Antworten, um Abschneiden in der UI zu vermeiden. +- Kanal-Chunk-Modus: `*.chunkMode` (`length` standardmäßig, `newline` trennt vor dem Längen-Chunking an Leerzeilen (Absatzgrenzen)). +- Discord-Softlimit: `channels.discord.maxLinesPerMessage` (standardmäßig 17) teilt hohe Antworten auf, um UI-Clipping zu vermeiden. **Grenzsemantik:** - `text_end`: Blöcke streamen, sobald der Chunker sie ausgibt; bei jedem `text_end` leeren. -- `message_end`: warten, bis die Assistentennachricht abgeschlossen ist, dann gepufferte Ausgabe leeren. +- `message_end`: warten, bis die Assistentennachricht abgeschlossen ist, dann die gepufferte Ausgabe leeren. `message_end` verwendet weiterhin den Chunker, wenn der gepufferte Text `maxChars` überschreitet, sodass am Ende mehrere Chunks ausgegeben werden können. @@ -63,64 +63,64 @@ Legende: `MEDIA:`-Direktiven sind normale Zustellungsmetadaten. Wenn Block-Streaming einen Medienblock früh sendet, merkt sich OpenClaw diese Zustellung für den Turn. Wenn die finale -Assistentennutzlast dieselbe Medien-URL wiederholt, entfernt die finale Zustellung die -doppelten Medien, statt den Anhang erneut zu senden. +Assistenten-Nutzlast dieselbe Medien-URL wiederholt, entfernt die finale Zustellung das +duplizierte Medium, statt den Anhang erneut zu senden. -Exakte doppelte finale Nutzlasten werden unterdrückt. Wenn die finale Nutzlast -eigenständigen Text um Medien ergänzt, die bereits gestreamt wurden, sendet OpenClaw weiterhin den -neuen Text, während die Medien nur einmal zugestellt werden. Dies verhindert doppelte Sprachnachrichten -oder Dateien auf Kanälen wie Telegram, wenn ein Agent während -des Streamings `MEDIA:` ausgibt und der Provider es auch in der abgeschlossenen Antwort enthält. +Exakt duplizierte finale Nutzlasten werden unterdrückt. Wenn die finale Nutzlast +eindeutigen Text um Medien ergänzt, die bereits gestreamt wurden, sendet OpenClaw weiterhin den +neuen Text und stellt das Medium dabei nur einmal zu. Das verhindert doppelte Sprachnotizen +oder Dateien in Kanälen wie Telegram, wenn ein Agent während des Streamings `MEDIA:` ausgibt +und der Provider es auch in der abgeschlossenen Antwort enthält. -## Chunking-Algorithmus (untere/obere Grenzen) +## Chunking-Algorithmus (niedrige/hohe Grenzen) -Block-Chunking wird durch `EmbeddedBlockChunker` implementiert: +Block-Chunking wird von `EmbeddedBlockChunker` implementiert: -- **Untere Grenze:** nicht ausgeben, bis der Puffer >= `minChars` ist (außer bei Erzwingung). -- **Obere Grenze:** Splits vor `maxChars` bevorzugen; bei Erzwingung bei `maxChars` teilen. +- **Niedrige Grenze:** erst ausgeben, wenn Puffer >= `minChars` ist (außer erzwungen). +- **Hohe Grenze:** Trennungen vor `maxChars` bevorzugen; wenn erzwungen, bei `maxChars` trennen. - **Umbruchpräferenz:** `paragraph` → `newline` → `sentence` → `whitespace` → harter Umbruch. -- **Code-Fences:** niemals innerhalb von Fences teilen; bei Erzwingung bei `maxChars` den Fence schließen + neu öffnen, damit Markdown gültig bleibt. +- **Code-Fences:** niemals innerhalb von Fences trennen; wenn bei `maxChars` erzwungen wird, den Fence schließen + erneut öffnen, damit Markdown gültig bleibt. -`maxChars` wird auf das Kanal-`textChunkLimit` begrenzt, sodass Sie kanalspezifische Grenzen nicht überschreiten können. +`maxChars` wird auf das Kanal-`textChunkLimit` begrenzt, sodass Sie kanalbezogene Grenzen nicht überschreiten können. -## Zusammenführung (gestreamte Blöcke zusammenführen) +## Zusammenführen (streamende Blöcke zusammenführen) Wenn Block-Streaming aktiviert ist, kann OpenClaw **aufeinanderfolgende Block-Chunks zusammenführen**, -bevor sie gesendet werden. Dies reduziert „Einzeilen-Spam“ und bietet dennoch -fortlaufende Ausgabe. +bevor sie gesendet werden. Das reduziert „Einzeilen-Spam“ und liefert trotzdem +fortlaufende Ausgaben. -- Die Zusammenführung wartet vor dem Leeren auf **Leerlaufpausen** (`idleMs`). -- Puffer werden durch `maxChars` begrenzt und geleert, wenn sie diese Grenze überschreiten. -- `minChars` verhindert, dass winzige Fragmente gesendet werden, bis genügend Text angesammelt wurde +- Das Zusammenführen wartet vor dem Leeren auf **Leerlaufpausen** (`idleMs`). +- Puffer werden durch `maxChars` begrenzt und werden geleert, wenn sie diese Grenze überschreiten. +- `minChars` verhindert, dass winzige Fragmente gesendet werden, bevor genug Text angesammelt ist (das finale Leeren sendet immer den verbleibenden Text). - Der Joiner wird aus `blockStreamingChunk.breakPreference` abgeleitet (`paragraph` → `\n\n`, `newline` → `\n`, `sentence` → Leerzeichen). -- Kanal-Overrides sind über `*.blockStreamingCoalesce` verfügbar (einschließlich kontospezifischer Konfigurationen). +- Kanal-Overrides sind über `*.blockStreamingCoalesce` verfügbar (einschließlich kontoabhängiger Konfigurationen). - Der standardmäßige Zusammenführungswert `minChars` wird für Signal/Slack/Discord auf 1500 angehoben, sofern er nicht überschrieben wird. ## Menschlich wirkende Pausen zwischen Blöcken Wenn Block-Streaming aktiviert ist, können Sie zwischen -Blockantworten (nach dem ersten Block) eine **randomisierte Pause** hinzufügen. Dadurch wirken Antworten mit mehreren Sprechblasen +Block-Antworten (nach dem ersten Block) eine **zufällige Pause** hinzufügen. Dadurch wirken Antworten mit mehreren Sprechblasen natürlicher. - Konfiguration: `agents.defaults.humanDelay` (pro Agent über `agents.list[].humanDelay` überschreiben). -- Modi: `off` (Standard), `natural` (800–2500 ms), `custom` (`minMs`/`maxMs`). -- Gilt nur für **Blockantworten**, nicht für finale Antworten oder Tool-Zusammenfassungen. +- Modi: `off` (Standard), `natural` (800-2500 ms), `custom` (`minMs`/`maxMs`). +- Gilt nur für **Block-Antworten**, nicht für finale Antworten oder Tool-Zusammenfassungen. -## „Chunks oder alles streamen“ +## „Chunks streamen oder alles“ Dies entspricht: -- **Chunks streamen:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (während der Ausgabe senden). Nicht-Telegram-Kanäle benötigen außerdem `*.blockStreaming: true`. -- **Alles am Ende streamen:** `blockStreamingBreak: "message_end"` (einmal leeren, bei sehr langer Ausgabe möglicherweise mehrere Chunks). +- **Chunks streamen:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (ausgeben, während generiert wird). Nicht-Telegram-Kanäle benötigen außerdem `*.blockStreaming: true`. +- **Alles am Ende streamen:** `blockStreamingBreak: "message_end"` (einmal leeren, bei sehr langen Antworten ggf. in mehreren Chunks). - **Kein Block-Streaming:** `blockStreamingDefault: "off"` (nur finale Antwort). -**Kanalhinweis:** Block-Streaming ist **aus, außer** -`*.blockStreaming` ist explizit auf `true` gesetzt. Kanäle können eine Live-Vorschau streamen -(`channels..streaming`), ohne Blockantworten zu senden. +**Kanalhinweis:** Block-Streaming ist **aus, sofern nicht** +`*.blockStreaming` explizit auf `true` gesetzt ist. Kanäle können eine Live-Vorschau +(`channels..streaming`) ohne Block-Antworten streamen. -Hinweis zum Konfigurationsort: Die `blockStreaming*`-Standards befinden sich unter +Konfigurationshinweis: Die `blockStreaming*`-Standardwerte befinden sich unter `agents.defaults`, nicht in der Root-Konfiguration. ## Vorschau-Streaming-Modi @@ -131,85 +131,85 @@ Modi: - `off`: Vorschau-Streaming deaktivieren. - `partial`: einzelne Vorschau, die durch den neuesten Text ersetzt wird. -- `block`: Vorschau wird in chunkweisen/angehängten Schritten aktualisiert. +- `block`: Vorschau wird in gestückelten/angehängten Schritten aktualisiert. - `progress`: Fortschritts-/Statusvorschau während der Generierung, finale Antwort bei Abschluss. -`streaming.mode: "block"` ist ein Vorschau-Streaming-Modus für bearbeitungsfähige Kanäle -wie Discord und Telegram. Er aktiviert dort keine Kanal-Blockzustellung. -Verwenden Sie `streaming.block.enabled` oder den Legacy-Kanalschlüssel `blockStreaming`, wenn -Sie normale Blockantworten wünschen. Microsoft Teams ist die Ausnahme: Es hat keinen -Blocktransport für Entwurfsvorschauen, daher wird `streaming.mode: "block"` auf Teams-Blockzustellung -statt auf natives Partial-/Fortschrittsstreaming abgebildet. +`streaming.mode: "block"` ist ein Vorschau-Streaming-Modus für Kanäle mit Bearbeitungsfunktion +wie Discord und Telegram. Er aktiviert dort keine Block-Zustellung im Kanal. +Verwenden Sie `streaming.block.enabled` oder den alten Kanal-Schlüssel `blockStreaming`, wenn +Sie normale Block-Antworten möchten. Microsoft Teams ist die Ausnahme: Es hat keinen +Block-Transport für Entwurfsvorschauen, daher wird `streaming.mode: "block"` auf die Teams-Block-Zustellung +statt auf natives Partial-/Fortschritts-Streaming abgebildet. ### Kanalzuordnung -| Kanal | `off` | `partial` | `block` | `progress` | -| ---------- | ----- | --------- | ------- | -------------------------- | +| Kanal | `off` | `partial` | `block` | `progress` | +| ---------- | ----- | --------- | ------- | ---------------------------- | | Telegram | ✅ | ✅ | ✅ | bearbeitbarer Fortschrittsentwurf | | Discord | ✅ | ✅ | ✅ | bearbeitbarer Fortschrittsentwurf | -| Slack | ✅ | ✅ | ✅ | ✅ | -| Mattermost | ✅ | ✅ | ✅ | ✅ | -| MS Teams | ✅ | ✅ | ✅ | nativer Fortschrittsstream | +| Slack | ✅ | ✅ | ✅ | ✅ | +| Mattermost | ✅ | ✅ | ✅ | ✅ | +| MS Teams | ✅ | ✅ | ✅ | nativer Fortschrittsstream | Nur Slack: -- `channels.slack.streaming.nativeTransport` schaltet native Slack-Streaming-API-Aufrufe um, wenn `channels.slack.streaming.mode="partial"` (Standard: `true`). -- Slack-natives Streaming und der Status des Slack-Assistenten-Threads benötigen ein Antwort-Thread-Ziel. DMs auf oberster Ebene zeigen diese Thread-artige Vorschau nicht an, können aber weiterhin Slack-Entwurfsvorschau-Beiträge und Bearbeitungen verwenden. +- `channels.slack.streaming.nativeTransport` schaltet native Slack-Streaming-API-Aufrufe um, wenn `channels.slack.streaming.mode="partial"` ist (Standard: `true`). +- Natives Slack-Streaming und der Slack-Assistenten-Threadstatus erfordern ein Antwort-Thread-Ziel. Top-Level-DMs zeigen diese Thread-artige Vorschau nicht an, können aber weiterhin Slack-Entwurfsvorschau-Beiträge und -Bearbeitungen verwenden. -Migration von Legacy-Schlüsseln: +Migration alter Schlüssel: -- Telegram: Legacy-Werte `streamMode` und skalare/boolesche `streaming`-Werte werden erkannt und durch Doctor-/Konfigurationskompatibilitätspfade zu `streaming.mode` migriert. -- Discord: `streamMode` + boolesches `streaming` werden automatisch zum `streaming`-Enum migriert. -- Slack: `streamMode` wird automatisch zu `streaming.mode` migriert; boolesches `streaming` wird automatisch zu `streaming.mode` plus `streaming.nativeTransport` migriert; Legacy-`nativeStreaming` wird automatisch zu `streaming.nativeTransport` migriert. +- Telegram: alte `streamMode`- und skalare/boolesche `streaming`-Werte werden erkannt und durch Doctor-/Konfigurationskompatibilitätspfade zu `streaming.mode` migriert. +- Discord: `streamMode` + boolesches `streaming` migrieren automatisch zum `streaming`-Enum. +- Slack: `streamMode` migriert automatisch zu `streaming.mode`; boolesches `streaming` migriert automatisch zu `streaming.mode` plus `streaming.nativeTransport`; altes `nativeStreaming` migriert automatisch zu `streaming.nativeTransport`. ### Laufzeitverhalten Telegram: - Verwendet `sendMessage` + `editMessageText` für Vorschauaktualisierungen über DMs und Gruppen/Themen hinweg. -- Sendet statt einer Bearbeitung an Ort und Stelle eine neue finale Nachricht, wenn eine Vorschau etwa eine Minute sichtbar war, und räumt dann die Vorschau auf, sodass der Telegram-Zeitstempel den Abschluss der Antwort widerspiegelt. +- Sendet eine neue finale Nachricht, statt sie an Ort und Stelle zu bearbeiten, wenn eine Vorschau ungefähr eine Minute sichtbar war, und räumt anschließend die Vorschau auf, damit der Telegram-Zeitstempel den Abschluss der Antwort widerspiegelt. - Vorschau-Streaming wird übersprungen, wenn Telegram-Block-Streaming explizit aktiviert ist (um doppeltes Streaming zu vermeiden). -- `/reasoning stream` kann Reasoning in die Vorschau schreiben. +- `/reasoning stream` kann Reasoning in eine temporäre Vorschau schreiben, die nach der finalen Zustellung gelöscht wird. Discord: - Verwendet Senden + Bearbeiten von Vorschaunachrichten. -- Der Modus `block` verwendet Entwurfs-Chunking (`draftChunk`). +- Der `block`-Modus verwendet Entwurfs-Chunking (`draftChunk`). - Vorschau-Streaming wird übersprungen, wenn Discord-Block-Streaming explizit aktiviert ist. -- Finale Medien-, Fehler- und explizite Antwortnutzlasten brechen ausstehende Vorschauen ab, ohne einen neuen Entwurf zu leeren, und verwenden dann die normale Zustellung. +- Finale Medien-, Fehler- und explizite Antwort-Nutzlasten brechen ausstehende Vorschauen ab, ohne einen neuen Entwurf zu leeren, und verwenden dann die normale Zustellung. Slack: - `partial` kann natives Slack-Streaming (`chat.startStream`/`append`/`stop`) verwenden, wenn verfügbar. -- `block` verwendet Entwurfsvorschauen im Anhänge-Stil. -- `progress` verwendet Statusvorschautext, danach die finale Antwort. -- DMs auf oberster Ebene ohne Antwort-Thread verwenden Entwurfsvorschau-Beiträge und Bearbeitungen statt Slack-nativem Streaming. -- Native und Entwurfsvorschau-Streams unterdrücken Blockantworten für diesen Turn, sodass eine Slack-Antwort nur über einen Zustellungspfad gestreamt wird. -- Finale Medien-/Fehlernutzlasten und Fortschrittsfinale erstellen keine Wegwerf-Entwurfsnachrichten; nur Text-/Blockfinale, die die Vorschau bearbeiten können, leeren ausstehenden Entwurfstext. +- `block` verwendet angehängte Entwurfsvorschauen. +- `progress` verwendet Statustext als Vorschau und danach die finale Antwort. +- Top-Level-DMs ohne Antwort-Thread verwenden Entwurfsvorschau-Beiträge und -Bearbeitungen statt nativem Slack-Streaming. +- Natives Streaming und Entwurfsvorschau-Streaming unterdrücken Block-Antworten für diesen Turn, sodass eine Slack-Antwort nur über einen Zustellungspfad gestreamt wird. +- Finale Medien-/Fehler-Nutzlasten und Fortschrittsfinale erzeugen keine Wegwerf-Entwurfsnachrichten; nur Text-/Block-Finale, die die Vorschau bearbeiten können, leeren ausstehenden Entwurfstext. Mattermost: -- Streamt Denken, Tool-Aktivität und partiellen Antworttext in einen einzelnen Entwurfsvorschau-Beitrag, der an Ort und Stelle finalisiert wird, wenn die finale Antwort sicher gesendet werden kann. -- Fällt auf das Senden eines neuen finalen Beitrags zurück, wenn der Vorschaubeitrag zum Finalisierungszeitpunkt gelöscht wurde oder anderweitig nicht verfügbar ist. -- Finale Medien-/Fehlernutzlasten brechen ausstehende Vorschauaktualisierungen vor der normalen Zustellung ab, statt einen temporären Vorschaubeitrag zu leeren. +- Streamt Denken, Tool-Aktivität und teilweisen Antworttext in einen einzelnen Entwurfsvorschau-Beitrag, der an Ort und Stelle finalisiert wird, wenn die finale Antwort sicher gesendet werden kann. +- Fällt auf das Senden eines neuen finalen Beitrags zurück, wenn der Vorschaubeitrag gelöscht wurde oder zum Finalisierungszeitpunkt anderweitig nicht verfügbar ist. +- Finale Medien-/Fehler-Nutzlasten brechen ausstehende Vorschauaktualisierungen vor der normalen Zustellung ab, statt einen temporären Vorschaubeitrag zu leeren. Matrix: - Entwurfsvorschauen werden an Ort und Stelle finalisiert, wenn der finale Text das Vorschauereignis wiederverwenden kann. -- Medien-only-, Fehler- und Antwortziel-Nichtübereinstimmungs-Finale brechen ausstehende Vorschauaktualisierungen vor der normalen Zustellung ab; eine bereits sichtbare veraltete Vorschau wird redigiert. +- Reine Medien-, Fehler- und Antwortzielkonflikt-Finale brechen ausstehende Vorschauaktualisierungen vor der normalen Zustellung ab; eine bereits sichtbare veraltete Vorschau wird redigiert. -### Tool-Fortschrittsvorschau-Aktualisierungen +### Vorschauaktualisierungen für Tool-Fortschritt -Vorschau-Streaming kann auch **Tool-Fortschritts**-Aktualisierungen enthalten — kurze Statuszeilen wie „das Web durchsuchen“, „Datei lesen“ oder „Tool aufrufen“ —, die in derselben Vorschaunachricht erscheinen, während Tools laufen, noch vor der finalen Antwort. Dadurch bleiben mehrstufige Tool-Turns visuell aktiv, statt zwischen der ersten Denkvorschau und der finalen Antwort stumm zu bleiben. +Vorschau-Streaming kann auch **Tool-Fortschritts**-Aktualisierungen enthalten — kurze Statuszeilen wie „Web wird durchsucht“, „Datei wird gelesen“ oder „Tool wird aufgerufen“ —, die in derselben Vorschaunachricht erscheinen, während Tools ausgeführt werden, noch vor der finalen Antwort. Dadurch bleiben mehrstufige Tool-Turns visuell aktiv, statt zwischen der ersten Denk-Vorschau und der finalen Antwort still zu sein. Unterstützte Oberflächen: -- **Discord**, **Slack**, **Telegram** und **Matrix** streamen Tool-Fortschritt standardmäßig in die Live-Vorschaubearbeitung, wenn Vorschau-Streaming aktiv ist. Microsoft Teams verwendet in persönlichen Chats seinen nativen Fortschrittsstream. -- Telegram wird seit `v2026.4.22` mit aktivierten Tool-Fortschrittsvorschau-Aktualisierungen ausgeliefert; deren Aktivierung beizubehalten, erhält dieses veröffentlichte Verhalten. +- **Discord**, **Slack**, **Telegram** und **Matrix** streamen Tool-Fortschritt standardmäßig in die Live-Vorschau-Bearbeitung, wenn Vorschau-Streaming aktiv ist. Microsoft Teams verwendet in persönlichen Chats seinen nativen Fortschrittsstream. +- Telegram wird seit `v2026.4.22` mit aktivierten Tool-Fortschritts-Vorschauaktualisierungen ausgeliefert; sie aktiviert zu lassen, bewahrt dieses veröffentlichte Verhalten. - **Mattermost** integriert Tool-Aktivität bereits in seinen einzelnen Entwurfsvorschau-Beitrag (siehe oben). -- Tool-Fortschrittsbearbeitungen folgen dem aktiven Vorschau-Streaming-Modus; sie werden übersprungen, wenn Vorschau-Streaming `off` ist oder wenn Block-Streaming die Nachricht übernommen hat. Bei Telegram ist `streaming.mode: "off"` final-only: allgemeines Fortschrittsrauschen wird ebenfalls unterdrückt, statt als eigenständige Statusnachrichten zugestellt zu werden, während Genehmigungsaufforderungen, Mediennutzlasten und Fehler weiterhin normal geroutet werden. +- Tool-Fortschritts-Bearbeitungen folgen dem aktiven Vorschau-Streaming-Modus; sie werden übersprungen, wenn Vorschau-Streaming `off` ist oder wenn Block-Streaming die Nachricht übernommen hat. Bei Telegram ist `streaming.mode: "off"` final-only: allgemeines Fortschrittsgerede wird ebenfalls unterdrückt, statt als eigenständige Statusnachrichten zugestellt zu werden, während Genehmigungsaufforderungen, Medien-Nutzlasten und Fehler weiterhin normal geroutet werden. - Um Vorschau-Streaming beizubehalten, aber Tool-Fortschrittszeilen auszublenden, setzen Sie `streaming.preview.toolProgress` für diesen Kanal auf `false`. Um Vorschaubearbeitungen vollständig zu deaktivieren, setzen Sie `streaming.mode` auf `off`. -- Ausgewählte Telegram-Zitatantworten sind eine Ausnahme: Wenn `replyToMode` nicht `"off"` ist und ausgewählter Zitattext vorhanden ist, überspringt OpenClaw den Antwortvorschau-Stream für diesen Turn, sodass Tool-Fortschrittsvorschau-Zeilen nicht gerendert werden können. Antworten auf die aktuelle Nachricht ohne ausgewählten Zitattext behalten Vorschau-Streaming weiterhin bei. Details finden Sie in der [Telegram-Kanaldokumentation](/de/channels/telegram). +- Ausgewählte Telegram-Zitatantworten sind eine Ausnahme: Wenn `replyToMode` nicht `"off"` ist und ausgewählter Zitattext vorhanden ist, überspringt OpenClaw den Antwortvorschau-Stream für diesen Turn, sodass Tool-Fortschritts-Vorschauzeilen nicht gerendert werden können. Aktuelle-Nachricht-Antworten ohne ausgewählten Zitattext behalten weiterhin Vorschau-Streaming bei. Details finden Sie in der [Telegram-Kanaldokumentation](/de/channels/telegram). Beispiel: @@ -228,9 +228,9 @@ Beispiel: } ``` -## Verwandte Themen +## Verwandt -- [Fortschrittsentwürfe](/de/concepts/progress-drafts) — sichtbare Nachrichten zu laufenden Arbeiten, die während langer Turns aktualisiert werden +- [Fortschrittsentwürfe](/de/concepts/progress-drafts) — sichtbare Nachrichten zum Bearbeitungsfortschritt, die während langer Durchläufe aktualisiert werden - [Nachrichten](/de/concepts/messages) — Nachrichtenlebenszyklus und Zustellung -- [Wiederholen](/de/concepts/retry) — Wiederholungsverhalten bei Zustellungsfehlern -- [Kanäle](/de/channels) — kanalspezifische Streaming-Unterstützung +- [Erneuter Versuch](/de/concepts/retry) — Verhalten bei erneuten Zustellversuchen nach Zustellungsfehlern +- [Kanäle](/de/channels) — Streaming-Unterstützung pro Kanal diff --git a/docs/de/help/testing.md b/docs/de/help/testing.md index 61a6eba88..95e1d57c8 100644 --- a/docs/de/help/testing.md +++ b/docs/de/help/testing.md @@ -2,34 +2,34 @@ read_when: - Tests lokal oder in CI ausführen - Regressionstests für Modell-/Provider-Fehler hinzufügen - - Fehlersuche für Gateway- und Agent-Verhalten -summary: 'Testkit: Unit-, E2E- und Live-Suites, Docker-Runner und was jeder Test abdeckt' -title: Testen + - Debugging von Gateway- und Agentenverhalten +summary: 'Testkit: Unit-/E2E-/Live-Suiten, Docker-Runner und welche Bereiche jeder Test abdeckt' +title: Tests x-i18n: - generated_at: "2026-05-03T21:35:11Z" + generated_at: "2026-05-04T06:42:38Z" model: gpt-5.5 provider: openai - source_hash: e7fb57bee958c4e6243f02193a657d7b19ca633c7a27f70eac6b590931390671 + source_hash: ad724e3879d1d4dec21c4ea97e2fd5724c47269c1084c558a09f51bd72afc6a4 source_path: help/testing.md workflow: 16 --- -OpenClaw hat drei Vitest-Suites (Unit/Integration, E2E, Live) und eine kleine Gruppe +OpenClaw verfügt über drei Vitest-Suites (Unit/Integration, E2E, Live) und eine kleine Auswahl von Docker-Runnern. 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 Workflows ausführen sollten (lokal, vor dem Push, Debugging). -- Wie Live-Tests Zugangsdaten finden und Modelle/Provider auswählen. -- Wie Sie Regressionen für reale Modell-/Provider-Probleme hinzufügen. +- Wie Live-Tests Zugangsdaten ermitteln und Modelle/Provider auswählen. +- Wie Sie Regressionstests für reale Modell-/Provider-Probleme hinzufügen. **QA-Stack (qa-lab, qa-channel, Live-Transport-Lanes)** ist separat dokumentiert: - [QA-Überblick](/de/concepts/qa-e2e-automation) — Architektur, Befehlsoberfläche, Szenarioerstellung. - [Matrix-QA](/de/concepts/qa-matrix) — Referenz für `pnpm openclaw qa matrix`. -- [QA-Kanal](/de/channels/qa-channel) — das synthetische Transport-Plugin, das von repo-gestützten Szenarien verwendet wird. +- [QA-Kanal](/de/channels/qa-channel) — das synthetische Transport-Plugin, das von repository-gestützten Szenarien verwendet wird. -Diese Seite behandelt das Ausführen der regulären Test-Suites und Docker-/Parallels-Runner. Der QA-spezifische Runner-Abschnitt unten ([QA-spezifische Runner](#qa-specific-runners)) listet die konkreten `qa`-Aufrufe auf und verweist zurück auf die obigen Referenzen. +Diese Seite behandelt das Ausführen der regulären Test-Suites und Docker-/Parallels-Runner. Der QA-spezifische Runner-Abschnitt unten ([QA-spezifische Runner](#qa-specific-runners)) listet die konkreten `qa`-Aufrufe auf und verweist auf die oben genannten Referenzen. ## Schnellstart @@ -37,190 +37,186 @@ Diese Seite behandelt das Ausführen der regulären Test-Suites und Docker-/Para An den meisten Tagen: - Vollständiges Gate (vor dem Push erwartet): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- Schnellerer lokaler Lauf der vollständigen Suite auf einem großzügig ausgestatteten Rechner: `pnpm test:max` +- Schnellerer lokaler Lauf der vollständigen Suite auf einer großzügig ausgestatteten Maschine: `pnpm test:max` - Direkte Vitest-Watch-Schleife: `pnpm test:watch` -- Direktes Datei-Targeting leitet jetzt auch Extension-/Kanal-Pfade 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. +- Direkte Dateiauswahl leitet jetzt auch Erweiterungs-/Kanalpfade weiter: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Bevorzugen Sie zunächst gezielte Läufe, wenn Sie an einem einzelnen Fehler iterieren. - 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 ändern oder zusätzliche Sicherheit wünschen: +Wenn Sie Tests berühren oder zusätzliche Sicherheit möchten: - Coverage-Gate: `pnpm test:coverage` - E2E-Suite: `pnpm test:e2e` -Wenn Sie reale Provider/Modelle debuggen (erfordert echte Zugangsdaten): +Beim Debuggen realer Provider/Modelle (erfordert echte Zugangsdaten): -- Live-Suite (Modelle + Gateway-Tool-/Image-Probes): `pnpm test:live` +- Live-Suite (Modelle + Gateway-Tool-/Bildprüfungen): `pnpm test:live` - Eine Live-Datei gezielt und leise ausführen: `pnpm test:live -- src/agents/models.profiles.live.test.ts` - Laufzeit-Performance-Berichte: dispatchen Sie `OpenClaw Performance` mit - `live_gpt54=true` für einen echten Agent-Turn mit `openai/gpt-5.4` oder - `deep_profile=true` für Kova-CPU-/Heap-/Trace-Artefakte. Tägliche geplante Läufe + `live_gpt54=true` für einen echten `openai/gpt-5.4`-Agent-Turn oder + `deep_profile=true` für Kova-CPU-/Heap-/Trace-Artefakte. Täglich geplante Läufe veröffentlichen Mock-Provider-, Deep-Profile- und GPT-5.4-Lane-Artefakte in `openclaw/clawgrit-reports`, wenn `CLAWGRIT_REPORTS_TOKEN` konfiguriert ist. Der - Mock-Provider-Bericht enthält außerdem Zahlen zu Source-Level-Gateway-Start, Speicher, - Plugin-Pressure, wiederholter Fake-Model-Hello-Schleife und CLI-Start. + Mock-Provider-Bericht enthält außerdem Zahlen zu Gateway-Boot auf Source-Ebene, Speicher, + Plugin-Druck, wiederholten Fake-Model-Hello-Loops und CLI-Start. - Docker-Live-Modell-Sweep: `pnpm test:docker:live-models` - - Jedes ausgewählte Modell führt jetzt einen Text-Turn plus eine kleine File-Read-artige Probe aus. - Modelle, deren Metadaten `image`-Eingabe ausweisen, führen außerdem einen kleinen Image-Turn aus. - Deaktivieren Sie die zusätzlichen Probes mit `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` oder + - Jedes ausgewählte Modell führt jetzt einen Text-Turn plus eine kleine Prüfung im Stil eines Datei-Lesezugriffs aus. + Modelle, deren Metadaten `image`-Eingabe ausweisen, führen außerdem einen kleinen Bild-Turn aus. + Deaktivieren Sie die zusätzlichen Prüfungen mit `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` oder `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0`, wenn Sie Provider-Fehler isolieren. - - CI-Abdeckung: Die täglichen `OpenClaw Scheduled Live And E2E Checks` und manuellen + - CI-Abdeckung: Tägliche `OpenClaw Scheduled Live And E2E Checks` und manuelle `OpenClaw Release Checks` rufen beide den wiederverwendbaren Live-/E2E-Workflow mit - `include_live_suites: true` auf, der separate Docker-Live-Modell- - Matrix-Jobs enthält, die nach Provider geshardet sind. - - Für fokussierte CI-Wiederholungen dispatchen Sie `OpenClaw Live And E2E Checks (Reusable)` + `include_live_suites: true` auf, der separate Docker-Live-Modell-Matrix-Jobs enthält, + die nach Provider geshardet sind. + - Für fokussierte CI-Neuläufe dispatchen Sie `OpenClaw Live And E2E Checks (Reusable)` mit `include_live_suites: true` und `live_models_only: true`. - - Fügen Sie neue, aussagekräftige Provider-Secrets zu `scripts/ci-hydrate-live-auth.sh` - sowie `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` und deren - Scheduled-/Release-Aufrufern hinzu. -- Nativer Codex Bound-Chat-Smoke: `pnpm test:docker:live-codex-bind` + - Fügen Sie neue aussagekräftige Provider-Secrets zu `scripts/ci-hydrate-live-auth.sh` + sowie `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` und seinen + geplanten/Release-Aufrufern hinzu. +- Nativer Codex-Bound-Chat-Smoke-Test: `pnpm test:docker:live-codex-bind` - Führt eine Docker-Live-Lane gegen den Codex-App-Server-Pfad aus, bindet eine synthetische Slack-DM mit `/codex bind`, übt `/codex fast` und - `/codex permissions` aus und verifiziert dann, dass eine einfache Antwort und ein Image-Anhang - über das native Plugin-Binding statt über ACP geleitet werden. -- Codex-App-Server-Harness-Smoke: `pnpm test:docker:live-codex-harness` + `/codex permissions` aus und verifiziert anschließend, dass eine einfache Antwort und ein Bildanhang + über die native Plugin-Bindung statt über ACP geroutet werden. +- Codex-App-Server-Harness-Smoke-Test: `pnpm test:docker:live-codex-harness` - Führt Gateway-Agent-Turns durch das Plugin-eigene Codex-App-Server-Harness aus, - verifiziert `/codex status` und `/codex models` und übt standardmäßig Image-, - Cron-MCP-, Sub-Agent- und Guardian-Probes aus. Deaktivieren Sie die Sub-Agent-Probe mit + verifiziert `/codex status` und `/codex models` und übt standardmäßig Bild-, + Cron-MCP-, Sub-Agent- und Guardian-Prüfungen aus. Deaktivieren Sie die Sub-Agent-Prüfung mit `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0`, wenn Sie andere Codex- - App-Server-Fehler isolieren. Für eine fokussierte Sub-Agent-Prüfung deaktivieren Sie die anderen Probes: + App-Server-Fehler isolieren. Für eine fokussierte Sub-Agent-Prüfung deaktivieren Sie die anderen Prüfungen: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness`. - Dies beendet nach der Sub-Agent-Probe, sofern - `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0` nicht gesetzt ist. -- Crestodian-Rettungsbefehl-Smoke: `pnpm test:live:crestodian-rescue-channel` - - Opt-in-Prüfung mit zusätzlicher Absicherung für die Message-Channel-Rettungsbefehlsoberfläche. + Dies beendet den Lauf nach der Sub-Agent-Prüfung, sofern nicht + `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0` gesetzt ist. +- Crestodian-Rettungsbefehl-Smoke-Test: `pnpm test:live:crestodian-rescue-channel` + - Opt-in-Prüfung mit doppelter Absicherung für die Rettungsbefehlsoberfläche des Nachrichtenkanals. Sie übt `/crestodian status` aus, stellt eine persistente Modelländerung in die Warteschlange, - antwortet mit `/crestodian yes` und verifiziert den Audit-/Config-Schreibpfad. -- Crestodian-Planner-Docker-Smoke: `pnpm test:docker:crestodian-planner` - - Führt Crestodian in einem configlosen Container mit einer Fake-Claude-CLI auf `PATH` + antwortet mit `/crestodian yes` und verifiziert den Audit-/Konfigurations-Schreibpfad. +- Crestodian-Planner-Docker-Smoke-Test: `pnpm test:docker:crestodian-planner` + - Führt Crestodian in einem konfigurationslosen Container mit einer gefälschten Claude-CLI auf `PATH` aus und verifiziert, dass der Fuzzy-Planner-Fallback in einen auditierten typisierten - Config-Schreibvorgang übersetzt wird. -- Crestodian-Erstlauf-Docker-Smoke: `pnpm test:docker:crestodian-first-run` - - Startet aus einem leeren OpenClaw-State-Verzeichnis, leitet bloßes `openclaw` an - Crestodian weiter, wendet Setup-/Modell-/Agent-/Discord-Plugin- + SecretRef-Schreibvorgänge an, - validiert die Config und verifiziert Audit-Einträge. Derselbe Ring-0-Setup-Pfad wird + Konfigurationsschreibvorgang übersetzt wird. +- Crestodian-Erstlauf-Docker-Smoke-Test: `pnpm test:docker:crestodian-first-run` + - Startet aus einem leeren OpenClaw-State-Verzeichnis, routet ein nacktes `openclaw` zu + Crestodian, wendet Setup-/Modell-/Agent-/Discord-Plugin- und SecretRef-Schreibvorgänge an, + validiert die Konfiguration und verifiziert Audit-Einträge. Derselbe Ring-0-Setup-Pfad wird auch in QA Lab durch `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup` abgedeckt. -- Moonshot-/Kimi-Kosten-Smoke: Führen Sie bei gesetztem `MOONSHOT_API_KEY` - `openclaw models list --provider moonshot --json` aus und führen Sie dann einen isolierten +- Moonshot-/Kimi-Kosten-Smoke-Test: Führen Sie bei gesetztem `MOONSHOT_API_KEY` + `openclaw models list --provider moonshot --json` aus und anschließend einen isolierten `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` - gegen `moonshot/kimi-k2.6` aus. Verifizieren Sie, dass das JSON Moonshot/K2.6 meldet und das - Assistant-Transkript normalisierte `usage.cost` speichert. + gegen `moonshot/kimi-k2.6`. Verifizieren Sie, dass das JSON Moonshot/K2.6 meldet und das + Assistenten-Transkript normalisierte `usage.cost` speichert. -Wenn Sie nur einen fehlschlagenden Fall benötigen, sollten Sie Live-Tests bevorzugt über die unten beschriebenen Allowlist-Env-Vars eingrenzen. +Wenn Sie nur einen fehlschlagenden Fall benötigen, bevorzugen Sie das Eingrenzen von Live-Tests über die unten beschriebenen Allowlist-Umgebungsvariablen. ## QA-spezifische Runner Diese Befehle stehen neben den Haupt-Test-Suites, wenn Sie QA-Lab-Realismus benötigen: -CI führt QA Lab in dedizierten Workflows aus. Agentic-Parität ist unter -`QA-Lab - All Lanes` und Release-Validierung verschachtelt, nicht als eigenständiger PR-Workflow. +CI führt QA Lab in dedizierten Workflows aus. Agentische Parität ist unter +`QA-Lab - All Lanes` und Release-Validierung verschachtelt, nicht in einem eigenständigen PR-Workflow. Breite Validierung sollte `Full Release Validation` mit `rerun_group=qa-parity` oder die QA-Gruppe der Release-Checks verwenden. `QA-Lab - All Lanes` -läuft nächtlich auf `main` und per manuellem Dispatch mit der Mock-Parity-Lane, Live- -Matrix-Lane, Convex-verwalteten Live-Telegram-Lane und Convex-verwalteten Live-Discord- +läuft nächtlich auf `main` und per manuellem Dispatch mit der Mock-Parity-Lane, der Live- +Matrix-Lane, der Convex-verwalteten Live-Telegram-Lane und der Convex-verwalteten Live-Discord- Lane als parallele Jobs. Geplante QA- und Release-Checks übergeben Matrix -`--profile fast` explizit, während die Standardeinstellung der Matrix-CLI und der manuellen Workflow-Eingabe -`all` bleibt; manueller Dispatch kann `all` in `transport`, +`--profile fast` explizit, während die Matrix-CLI und die manuelle Workflow-Eingabe +standardmäßig `all` bleiben; manueller Dispatch kann `all` in `transport`, `media`, `e2ee-smoke`, `e2ee-deep` und `e2ee-cli`-Jobs sharden. `OpenClaw Release -Checks` führt vor der Release-Freigabe Parität plus die schnellen Matrix- und Telegram-Lanes aus +Checks` führt vor der Release-Freigabe Parität plus die Fast-Matrix- und Telegram-Lanes aus und verwendet `mock-openai/gpt-5.5` für Release-Transport-Checks, damit sie -deterministisch bleiben und den normalen Provider-Plugin-Start vermeiden. Diese Live-Transport- -Gateways deaktivieren Memory-Suche; Memory-Verhalten bleibt durch die QA-Parity- +deterministisch bleiben und den normalen Start des Provider-Plugins vermeiden. Diese Live-Transport- +Gateways deaktivieren die Memory-Suche; Memory-Verhalten bleibt durch die QA-Parity- Suites abgedeckt. -Full-Release-Live-Media-Shards verwenden +Vollständige Release-Live-Media-Shards verwenden `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, das bereits -`ffmpeg` und `ffprobe` enthält. Docker-Live-Modell-/Backend-Shards verwenden das gemeinsame +`ffmpeg` und `ffprobe` enthält. Docker-Live-Modell-/Backend-Shards verwenden das gemeinsam genutzte `ghcr.io/openclaw/openclaw-live-test:`-Image, das einmal pro ausgewähltem Commit gebaut wird, und ziehen es dann mit `OPENCLAW_SKIP_DOCKER_BUILD=1`, statt es -innerhalb jedes Shards neu zu bauen. +in jedem Shard neu zu bauen. - `pnpm openclaw qa suite` - Führt repo-gestützte QA-Szenarien direkt auf dem Host aus. - - Führt mehrere ausgewählte Szenarien standardmäßig parallel mit isolierten - Gateway-Workern aus. `qa-channel` verwendet standardmäßig Parallelität 4 - (begrenzt durch die Anzahl der ausgewählten Szenarien). Verwenden Sie - `--concurrency `, um die Worker-Anzahl 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. + - Führt standardmäßig mehrere ausgewählte Szenarien parallel mit isolierten + Gateway-Workern aus. `qa-channel` verwendet standardmäßig Parallelität 4 (begrenzt durch die + Anzahl der ausgewählten Szenarien). Verwenden Sie `--concurrency `, um die Anzahl der + Worker anzupassen, oder `--concurrency 1` für den älteren seriellen Prüflauf. + - Beendet sich mit einem Fehlercode ungleich null, wenn ein Szenario fehlschlägt. Verwenden Sie `--allow-failures`, wenn Sie + Artefakte ohne fehlschlagenden Exit-Code möchten. - 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. + `aimock` startet einen lokalen AIMock-gestützten Provider-Server für experimentelle + Fixture- und Protocol-Mock-Abdeckung, ohne den szenariobewussten + `mock-openai`-Prüflauf zu ersetzen. - `pnpm test:gateway:cpu-scenarios` - - Führt den Gateway-Start-Benchmark plus ein kleines Mock-QA-Lab-Szenariopaket - aus (`channel-chat-baseline`, `memory-failure-fallback`, - `gateway-restart-inflight-run`) und schreibt eine kombinierte CPU-Beobachtungszusammenfassung + - Führt die Gateway-Start-Benchmark plus ein kleines Mock-QA-Lab-Szenariopaket aus + (`channel-chat-baseline`, `memory-failure-fallback`, + `gateway-restart-inflight-run`) und schreibt eine zusammengefasste CPU-Beobachtungsübersicht unter `.artifacts/gateway-cpu-scenarios/`. - - Markiert standardmäßig nur anhaltende heiße CPU-Beobachtungen - (`--cpu-core-warn` plus `--hot-wall-warn-ms`), sodass kurze Startspitzen als - Metriken erfasst werden, ohne wie die minutenlange Gateway-Peg-Regression zu - wirken. - - Verwendet gebaute `dist`-Artefakte; führen Sie zuerst einen Build aus, wenn - der Checkout noch keine frische Laufzeitausgabe hat. + - Markiert standardmäßig nur dauerhaft heiße CPU-Beobachtungen (`--cpu-core-warn` + plus `--hot-wall-warn-ms`), sodass kurze Startspitzen als Metriken erfasst werden, + ohne wie die minutenlange Gateway-Auslastungsregression zu wirken. + - Verwendet gebaute `dist`-Artefakte; führen Sie zuerst einen Build aus, wenn der Checkout noch keine + frische Laufzeitausgabe enthält. - `pnpm openclaw qa suite --runner multipass` - - Führt dieselbe QA-Suite innerhalb einer wegwerfbaren Multipass-Linux-VM aus. + - Führt dieselbe QA-Suite in einer wegwerfbaren 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: env-basierte Provider-Schlüssel, den QA-Live-Provider-Konfigurationspfad - und `CODEX_HOME`, wenn vorhanden. - - Ausgabeverzeichnisse müssen unter dem Repo-Root bleiben, damit der Gast über - den gemounteten Workspace zurückschreiben kann. - - Schreibt den normalen QA-Bericht plus Zusammenfassung sowie Multipass-Logs - unter `.artifacts/qa-e2e/...`. + - Live-Ausführungen leiten die unterstützten QA-Authentifizierungseingaben weiter, die für den Guest praktikabel sind: + env-basierte Provider-Schlüssel, den Pfad zur QA-Live-Provider-Konfiguration und `CODEX_HOME`, + wenn vorhanden. + - Ausgabeverzeichnisse müssen unter dem Repo-Root bleiben, damit der Guest über den + gemounteten Workspace zurückschreiben kann. + - Schreibt den normalen QA-Bericht und die Zusammenfassung plus Multipass-Protokolle unter + `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Startet die Docker-gestützte QA-Site für operatorartige QA-Arbeit. + - Startet die Docker-gestützte QA-Site für operatorähnliche QA-Arbeit. - `pnpm test:docker:npm-onboard-channel-agent` - Baut einen npm-Tarball aus dem aktuellen Checkout, installiert ihn global in - Docker, führt nicht-interaktives OpenAI-API-Key-Onboarding aus, konfiguriert - standardmäßig Telegram, verifiziert, dass die paketierte Plugin-Laufzeit ohne - Startzeit-Abhängigkeitsreparatur lädt, führt doctor aus und führt einen - lokalen Agent-Turn gegen einen gemockten OpenAI-Endpunkt aus. - - Verwenden Sie `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, um dieselbe - Paketinstallations-Lane mit Discord auszuführen. + Docker, führt nicht interaktives OpenAI-API-Schlüssel-Onboarding aus, konfiguriert standardmäßig Telegram, + verifiziert, dass die paketierte Plugin-Laufzeit ohne Startreparatur für Abhängigkeiten geladen wird, + führt doctor aus und führt einen lokalen Agent-Durchlauf gegen einen + gemockten OpenAI-Endpunkt aus. + - Verwenden Sie `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, um denselben Prüflauf für paketierte Installationen + mit Discord auszuführen. - `pnpm test:docker:session-runtime-context` - - Führt einen deterministischen Built-App-Docker-Smoke für eingebettete - Laufzeitkontext-Transkripte aus. Er verifiziert, dass verborgener - OpenClaw-Laufzeitkontext als nicht anzuzeigende benutzerdefinierte Nachricht - persistiert wird, statt in den sichtbaren Benutzer-Turn zu leaken, seeded - dann eine betroffene defekte Session-JSONL und verifiziert, dass - `openclaw doctor --fix` sie mit Backup auf den aktiven Branch umschreibt. + - Führt einen deterministischen Docker-Smoke-Test der gebauten App für eingebettete Laufzeitkontext- + Transkripte aus. Er verifiziert, dass verborgener OpenClaw-Laufzeitkontext als + nicht angezeigte benutzerdefinierte Nachricht persistiert wird, statt in den sichtbaren Benutzer-Turn zu gelangen, + seedet anschließend eine betroffene defekte Sitzungs-JSONL und verifiziert, + dass `openclaw doctor --fix` sie mit einem Backup auf den aktiven Branch umschreibt. - `pnpm test:docker:npm-telegram-live` - - Installiert einen OpenClaw-Paketkandidaten in Docker, führt - Installed-Package-Onboarding aus, konfiguriert Telegram über die installierte - CLI und verwendet dann die Live-Telegram-QA-Lane mit diesem installierten - Paket als SUT-Gateway wieder. - - Standardwert ist `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`; setzen - Sie `OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` oder - `OPENCLAW_CURRENT_PACKAGE_TGZ`, um stattdessen einen aufgelösten lokalen - Tarball zu testen, statt aus der Registry zu installieren. - - Verwendet dieselben Telegram-Env-Anmeldedaten oder dieselbe - Convex-Anmeldedatenquelle wie `pnpm openclaw qa telegram`. Für CI-/Release-Automatisierung - setzen Sie `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` plus + - Installiert einen OpenClaw-Paketkandidaten in Docker, führt Onboarding für das installierte Paket aus, + konfiguriert Telegram über die installierte CLI und verwendet dann den + Live-Telegram-QA-Prüflauf mit diesem installierten Paket als SUT-Gateway wieder. + - Standard ist `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`; setzen Sie + `OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` oder + `OPENCLAW_CURRENT_PACKAGE_TGZ`, um stattdessen einen aufgelösten lokalen Tarball zu testen, statt + aus der Registry zu installieren. + - Verwendet dieselben Telegram-env-Anmeldedaten oder dieselbe Convex-Anmeldedatenquelle wie + `pnpm openclaw qa telegram`. Für CI-/Release-Automatisierung setzen Sie + `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` plus `OPENCLAW_QA_CONVEX_SITE_URL` und das Rollen-Secret. Wenn - `OPENCLAW_QA_CONVEX_SITE_URL` und ein Convex-Rollen-Secret in CI vorhanden - sind, wählt der Docker-Wrapper Convex automatisch aus. - - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` überschreibt die - gemeinsame `OPENCLAW_QA_CREDENTIAL_ROLE` nur für diese Lane. - - GitHub Actions stellt diese Lane auch als manuellen Maintainer-Workflow - `NPM Telegram Beta E2E` bereit. Er läuft nicht bei Merge. Der Workflow - verwendet die Umgebung `qa-live-shared` und Convex-CI-Anmeldedaten-Leases. -- GitHub Actions stellt außerdem `Package Acceptance` für seitlich ausgeführte - Produktnachweise gegen ein Kandidatenpaket bereit. Es akzeptiert eine - vertrauenswürdige Ref, eine veröffentlichte npm-Spezifikation, eine - HTTPS-Tarball-URL plus SHA-256 oder ein Tarball-Artefakt aus einem anderen - Lauf, lädt das normalisierte `openclaw-current.tgz` als `package-under-test` - hoch und führt dann den bestehenden Docker-E2E-Scheduler mit Smoke-, Paket-, - Produkt-, vollständigen oder benutzerdefinierten Lane-Profilen aus. Setzen Sie - `telegram_mode=mock-openai` oder `live-frontier`, um den Telegram-QA-Workflow - gegen dasselbe `package-under-test`-Artefakt auszuführen. + `OPENCLAW_QA_CONVEX_SITE_URL` und ein Convex-Rollen-Secret in CI vorhanden sind, + wählt der Docker-Wrapper Convex automatisch aus. + - Der Wrapper validiert Telegram- oder Convex-Anmeldedaten-env auf dem Host, bevor + Docker-Build-/Installationsarbeit beginnt. Setzen Sie `OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1` + nur, wenn Sie bewusst die Einrichtung vor den Anmeldedaten debuggen. + - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` überschreibt die gemeinsame + `OPENCLAW_QA_CREDENTIAL_ROLE` nur für diesen Prüflauf. + - GitHub Actions stellt diesen Prüflauf als manuellen Maintainer-Workflow + `NPM Telegram Beta E2E` bereit. Er läuft nicht bei einem Merge. Der Workflow verwendet die + `qa-live-shared`-Umgebung und Convex-CI-Anmeldedaten-Leases. +- GitHub Actions stellt außerdem `Package Acceptance` für seitlich ausgeführte Produktnachweise + gegen ein Kandidatenpaket bereit. Es akzeptiert einen vertrauenswürdigen Ref, eine veröffentlichte npm-Spezifikation, + eine HTTPS-Tarball-URL plus SHA-256 oder ein Tarball-Artefakt aus einem anderen Lauf, lädt + das normalisierte `openclaw-current.tgz` als `package-under-test` hoch und führt dann den + vorhandenen Docker-E2E-Scheduler mit Smoke-, Paket-, Produkt-, Full- oder benutzerdefinierten + Prüflaufprofilen aus. Setzen Sie `telegram_mode=mock-openai` oder `live-frontier`, um den + Telegram-QA-Workflow gegen dasselbe `package-under-test`-Artefakt auszuführen. - Neuester Beta-Produktnachweis: ```bash @@ -231,7 +227,7 @@ gh workflow run package-acceptance.yml --ref main \ -f telegram_mode=mock-openai ``` -- Nachweis einer exakten Tarball-URL erfordert einen Digest: +- Nachweis mit genauer Tarball-URL erfordert einen Digest: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -252,83 +248,79 @@ gh workflow run package-acceptance.yml --ref main \ ``` - `pnpm test:docker:plugins` - - Packt und installiert den aktuellen OpenClaw-Build in Docker, startet den - Gateway mit konfiguriertem OpenAI und aktiviert dann gebündelte - Channel/Plugins über Konfigurationsänderungen. - - Verifiziert, dass die Setup-Discovery unkonfigurierte herunterladbare - Plugins abwesend lässt, die erste konfigurierte Doctor-Reparatur jedes - fehlende herunterladbare Plugin explizit installiert und ein zweiter - Neustart keine verborgene Abhängigkeitsreparatur ausführt. - - Installiert außerdem eine bekannte ältere npm-Baseline, aktiviert Telegram - vor der Ausführung von `openclaw update --tag ` und verifiziert, - dass der Post-Update-Doctor des Kandidaten Altlasten von Plugin-Abhängigkeiten - ohne harness-seitige Postinstall-Reparatur bereinigt. + - Packt und installiert den aktuellen OpenClaw-Build in Docker, startet das Gateway + mit konfiguriertem OpenAI und aktiviert dann gebündelte Kanäle/Plugins über Konfigurationsänderungen. + - Verifiziert, dass die Einrichtungserkennung nicht konfigurierte herunterladbare Plugins auslässt, + die erste konfigurierte doctor-Reparatur jedes fehlende herunterladbare + Plugin explizit installiert und ein zweiter Neustart keine verborgene + Abhängigkeitsreparatur ausführt. + - Installiert außerdem eine bekannte ältere npm-Baseline, aktiviert Telegram vor dem Ausführen von + `openclaw update --tag ` und verifiziert, dass der + post-update doctor des Kandidaten Altlasten von Plugin-Abhängigkeiten ohne eine + postinstall-Reparatur auf Harness-Seite bereinigt. - `pnpm test:parallels:npm-update` - - Führt den nativen Paketinstallations-Update-Smoke über Parallels-Gäste aus. - Jede ausgewählte Plattform installiert zuerst das angeforderte Baseline-Paket, - führt dann den installierten Befehl `openclaw update` im selben Gast aus und - verifiziert die installierte Version, den Update-Status, die Gateway-Bereitschaft - und einen lokalen Agent-Turn. - - Verwenden Sie `--platform macos`, `--platform windows` oder `--platform linux`, - während Sie an einem Gast iterieren. Verwenden Sie `--json` für den Pfad zum - Zusammenfassungsartefakt und den Status pro Lane. - - Die OpenAI-Lane verwendet standardmäßig `openai/gpt-5.5` für den Live-Agent-Turn-Nachweis. + - Führt den nativen Smoke-Test für paketierte Installationsupdates über Parallels-Guests hinweg aus. Jede + ausgewählte Plattform installiert zuerst das angeforderte Baseline-Paket, führt dann den + installierten Befehl `openclaw update` im selben Guest aus und verifiziert die + installierte Version, den Update-Status, die Gateway-Bereitschaft und einen lokalen Agent-Durchlauf. + - Verwenden Sie `--platform macos`, `--platform windows` oder `--platform linux`, während Sie + an einem Guest iterieren. Verwenden Sie `--json` für den Pfad zum Zusammenfassungsartefakt und + den Status pro Prüflauf. + - Der OpenAI-Prüflauf verwendet standardmäßig `openai/gpt-5.5` für den Live-Agent-Durchlaufnachweis. Übergeben Sie `--model ` oder setzen Sie - `OPENCLAW_PARALLELS_OPENAI_MODEL`, wenn Sie bewusst ein anderes OpenAI-Modell - validieren. - - Umschließen Sie lange lokale Läufe mit einem Host-Timeout, damit Parallels-Transport-Hänger - nicht den Rest des Testfensters verbrauchen: + `OPENCLAW_PARALLELS_OPENAI_MODEL`, wenn Sie bewusst ein anderes + OpenAI-Modell validieren. + - Umhüllen Sie lange lokale Läufe mit einem Host-Timeout, damit Parallels-Transport-Hänger nicht + den Rest des Testfensters verbrauchen können: ```bash timeout --foreground 150m pnpm test:parallels:npm-update -- --json timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json ``` - - Das Skript schreibt verschachtelte Lane-Logs unter `/tmp/openclaw-parallels-npm-update.*`. + - Das Skript schreibt verschachtelte Prüflaufprotokolle unter `/tmp/openclaw-parallels-npm-update.*`. Prüfen Sie `windows-update.log`, `macos-update.log` oder `linux-update.log`, bevor Sie annehmen, dass der äußere Wrapper hängt. - - Das Windows-Update kann auf einem kalten Gast 10 bis 15 Minuten in - Post-Update-Doctor- und Paketupdate-Arbeit verbringen; das ist weiterhin - gesund, wenn das verschachtelte npm-Debug-Log fortschreitet. - - Führen Sie diesen aggregierten Wrapper nicht parallel zu einzelnen - Parallels-Smoke-Lanes für macOS, Windows oder Linux aus. Sie teilen sich - VM-Zustand und können bei Snapshot-Wiederherstellung, Paketbereitstellung - oder Gateway-Zustand des Gasts kollidieren. - - Der Post-Update-Nachweis führt die normale gebündelte Plugin-Oberfläche aus, - weil Capability-Fassaden wie Sprache, Bildgenerierung und Medienverständnis - über gebündelte Laufzeit-APIs geladen werden, selbst wenn der Agent-Turn + - Windows-Updates können auf einem kalten Guest 10 bis 15 Minuten mit post-update doctor und Paket- + Update-Arbeit verbringen; das ist weiterhin gesund, wenn das verschachtelte npm- + Debug-Protokoll voranschreitet. + - Führen Sie diesen aggregierten Wrapper nicht parallel zu einzelnen Parallels- + macOS-, Windows- oder Linux-Smoke-Prüfläufen aus. Sie teilen VM-Zustand und können bei + Snapshot-Wiederherstellung, Paketbereitstellung oder Guest-Gateway-Zustand kollidieren. + - Der post-update-Nachweis führt die normale gebündelte Plugin-Oberfläche aus, weil + Capability-Fassaden wie Sprache, Bilderzeugung und Medienverständnis + über gebündelte Laufzeit-APIs geladen werden, selbst wenn der Agent-Durchlauf selbst nur eine einfache Textantwort prüft. - `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 Protocol-Smoke- + Tests. - `pnpm openclaw qa matrix` - - Führt die Matrix-Live-QA-Lane gegen einen wegwerfbaren Docker-gestützten Tuwunel-Homeserver aus. Nur Source-Checkout — paketierte Installationen liefern `qa-lab` nicht mit. - - Vollständige CLI, Profil-/Szenariokatalog, Env-Vars und Artefaktlayout: [Matrix-QA](/de/concepts/qa-matrix). + - Führt den Matrix-Live-QA-Prüflauf gegen einen wegwerfbaren Docker-gestützten Tuwunel-Homeserver aus. Nur Source-Checkout — paketierte Installationen liefern `qa-lab` nicht mit. + - Vollständige CLI, Profil-/Szenariokatalog, env vars und Artefaktlayout: [Matrix-QA](/de/concepts/qa-matrix). - `pnpm openclaw qa telegram` - - Führt die Telegram-Live-QA-Lane gegen eine echte private Gruppe mit den Driver- und SUT-Bot-Tokens aus der Env aus. + - Führt den Telegram-Live-QA-Prüflauf gegen eine echte private Gruppe mit den Driver- und SUT-Bot-Token aus env aus. - 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 gepoolte Leases zu nutzen. - - 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 unterschiedliche Bots in derselben privaten Gruppe, wobei der SUT-Bot einen Telegram-Benutzernamen offenlegt. - - Aktivieren Sie für stabile Bot-zu-Bot-Beobachtung den Bot-to-Bot Communication Mode in `@BotFather` für beide Bots und stellen Sie sicher, dass der Driver-Bot Gruppen-Bot-Traffic beobachten kann. - - Schreibt einen Telegram-QA-Bericht, eine Zusammenfassung und ein Artefakt mit beobachteten Nachrichten unter `.artifacts/qa-e2e/...`. Antwortszenarien enthalten RTT vom Sende-Request des Drivers bis zur beobachteten SUT-Antwort. + - 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 gepoolte Leases zu verwenden. + - Beendet sich mit einem Fehlercode ungleich null, wenn ein Szenario fehlschlägt. Verwenden Sie `--allow-failures`, wenn Sie + Artefakte ohne fehlschlagenden Exit-Code möchten. + - Erfordert zwei unterschiedliche Bots in derselben privaten Gruppe, wobei der SUT-Bot einen Telegram-Benutzernamen bereitstellt. + - Für stabile Bot-zu-Bot-Beobachtung aktivieren Sie den Bot-to-Bot Communication Mode in `@BotFather` für beide Bots und stellen Sie sicher, dass der Driver-Bot Gruppen-Bot-Datenverkehr beobachten kann. + - Schreibt einen Telegram-QA-Bericht, eine Zusammenfassung und ein observed-messages-Artefakt unter `.artifacts/qa-e2e/...`. Antwortszenarien enthalten die RTT von der Sendeanforderung des Drivers bis zur beobachteten SUT-Antwort. -Live-Transport-Lanes teilen sich einen Standardvertrag, damit neue Transporte nicht abdriften; die Abdeckungsmatrix pro Lane befindet sich in [QA-Überblick → Live-Transport-Abdeckung](/de/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` ist die breite synthetische Suite und nicht Teil dieser Matrix. +Live-Transport-Prüfläufe teilen einen Standardvertrag, damit neue Transporte nicht abweichen; die Abdeckungsmatrix pro Prüflauf befindet sich in [QA-Übersicht → Live-Transport-Abdeckung](/de/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` ist die breite synthetische Suite und nicht Teil dieser Matrix. ### Gemeinsame Telegram-Anmeldedaten über Convex (v1) Wenn `--credential-source convex` (oder `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) für -`openclaw qa telegram` aktiviert ist, erwirbt QA lab eine exklusive Lease aus einem Convex-gestützten Pool, heartbeated -diese Lease, während die Lane läuft, und gibt die Lease beim Herunterfahren frei. +`openclaw qa telegram` aktiviert ist, erwirbt QA Lab eine exklusive Lease aus einem Convex-gestützten Pool, sendet Heartbeats +für diese Lease, während der Prüflauf läuft, und gibt die Lease beim Herunterfahren frei. -Referenz-Convex-Projektscaffold: +Referenzgerüst für das Convex-Projekt: - `qa/convex-credential-broker/` -Erforderliche Env-Vars: +Erforderliche env vars: - `OPENCLAW_QA_CONVEX_SITE_URL` (zum Beispiel `https://your-deployment.convex.site`) - Ein Secret für die ausgewählte Rolle: @@ -336,9 +328,9 @@ Erforderliche Env-Vars: - `OPENCLAW_QA_CONVEX_SECRET_CI` für `ci` - Auswahl der Anmeldedatenrolle: - CLI: `--credential-role maintainer|ci` - - Env-Standard: `OPENCLAW_QA_CREDENTIAL_ROLE` (standardmäßig `ci` in CI, andernfalls `maintainer`) + - env-Standard: `OPENCLAW_QA_CREDENTIAL_ROLE` (standardmäßig `ci` in CI, andernfalls `maintainer`) -Optionale Env-Vars: +Optionale env vars: - `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (Standard `1200000`) - `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (Standard `30000`) @@ -346,14 +338,14 @@ Optionale Env-Vars: - `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 local loopback `http://`-Convex-URLs für rein lokale Entwicklung. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` erlaubt local loopback-`http://`-Convex-URLs für ausschließlich lokale Entwicklung. -`OPENCLAW_QA_CONVEX_SITE_URL` sollte im Normalbetrieb `https://` verwenden. +`OPENCLAW_QA_CONVEX_SITE_URL` sollte im normalen Betrieb `https://` verwenden. Maintainer-Admin-Befehle (Pool hinzufügen/entfernen/auflisten) erfordern speziell `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -CLI-Helfer für Maintainer: +CLI-Hilfsbefehle für Maintainer: ```bash pnpm openclaw qa credentials doctor @@ -362,10 +354,10 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Verwenden Sie `doctor` vor Live-Läufen, um die Convex-Site-URL, Broker-Secrets, -den Endpunktpräfix, HTTP-Timeout und Admin-/Listen-Erreichbarkeit zu prüfen, -ohne Secret-Werte auszugeben. Verwenden Sie `--json` für maschinenlesbare Ausgabe -in Skripten und CI-Dienstprogrammen. +Verwenden Sie `doctor` vor Live-Läufen, um die URL der Convex-Site, Broker-Secrets, +Endpunktpräfix, HTTP-Timeout und Erreichbarkeit von Admin/List zu prüfen, ohne +Secret-Werte auszugeben. Verwenden Sie `--json` für maschinenlesbare Ausgabe in Skripten und CI +Hilfsprogrammen. Standard-Endpunktvertrag (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): @@ -390,81 +382,80 @@ Standard-Endpunktvertrag (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - Anfrage: `{ kind?, status?, includePayload?, limit? }` - Erfolg: `{ status: "ok", credentials, count }` -Payload-Struktur für Telegram-kind: +Payload-Form für Telegram-Kind: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` muss eine numerische Telegram-Chat-ID als Zeichenfolge sein. -- `admin/add` validiert diese Struktur für `kind: "telegram"` und lehnt fehlerhafte Payloads ab. +- `groupId` muss eine numerische Telegram-Chat-ID-Zeichenfolge sein. +- `admin/add` validiert diese Form für `kind: "telegram"` und weist fehlerhafte Payloads zurück. ### Einen Kanal zu QA hinzufügen -Die Architektur und die Szenario-Helper-Namen für neue Kanaladapter stehen in [QA-Überblick → Einen Kanal hinzufügen](/de/concepts/qa-e2e-automation#adding-a-channel). Die Mindestanforderung: Implementieren Sie den Transport-Runner über die gemeinsame `qa-lab`-Host-Schnittstelle, deklarieren Sie `qaRunners` im Plugin-Manifest, mounten Sie ihn als `openclaw qa `, und erstellen Sie Szenarien unter `qa/scenarios/`. +Die Architektur und Namen der Szenario-Helfer für neue Kanaladapter finden Sie in [QA-Überblick → Einen Kanal hinzufügen](/de/concepts/qa-e2e-automation#adding-a-channel). Die Mindestanforderung: Implementieren Sie den Transport-Runner auf der gemeinsamen `qa-lab`-Host-Nahtstelle, deklarieren Sie `qaRunners` im Plugin-Manifest, mounten Sie ihn als `openclaw qa ` und erstellen Sie Szenarien unter `qa/scenarios/`. -## Testsuites (was wo läuft) +## Testsuiten (was wo läuft) -Betrachten Sie die Suites als „zunehmenden Realismus“ (und zunehmende Flakiness/Kosten): +Betrachten Sie die Suiten als „zunehmenden Realismus“ (und zunehmende Instabilität/Kosten): ### Unit / Integration (Standard) - Befehl: `pnpm test` -- Konfiguration: Läufe ohne Ziel verwenden den `vitest.full-*.config.ts`-Shard-Satz und können Multi-Project-Shards für die parallele Planung in projektbezogene Konfigurationen aufteilen +- Konfiguration: Nicht zielgerichtete Läufe verwenden das `vitest.full-*.config.ts`-Shard-Set und können Multi-Projekt-Shards für parallele Planung in projektbezogene Konfigurationen erweitern - Dateien: Core-/Unit-Inventare unter `src/**/*.test.ts`, `packages/**/*.test.ts` und `test/**/*.test.ts`; UI-Unit-Tests laufen im dedizierten `unit-ui`-Shard - Umfang: - Reine Unit-Tests - - In-Process-Integrationstests (Gateway-Auth, Routing, Tooling, Parsing, Konfiguration) + - In-Process-Integrationstests (Gateway-Authentifizierung, Routing, Werkzeuge, Parsing, Konfiguration) - Deterministische Regressionen für bekannte Fehler - Erwartungen: - Läuft in CI - Keine echten Schlüssel erforderlich - Sollte schnell und stabil sein - - Resolver- und Public-Surface-Loader-Tests müssen das breite `api.js`- und - `runtime-api.js`-Fallback-Verhalten mit generierten kleinen Plugin-Fixtures nachweisen, nicht mit - echten gebündelten Plugin-Quell-APIs. Echte Plugin-API-Ladevorgänge gehören in - Plugin-eigene Contract-/Integrationssuites. + - Resolver- und Public-Surface-Loader-Tests müssen breites Fallback-Verhalten von `api.js` und + `runtime-api.js` mit generierten kleinen Plugin-Fixtures nachweisen, nicht mit + echten APIs aus gebündeltem Plugin-Quellcode. Echte Plugin-API-Ladevorgänge gehören in + Plugin-eigene Contract-/Integrationssuiten. - - `pnpm test` ohne Ziel führt zwölf kleinere Shard-Konfigurationen (`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 einzigen großen nativen Root-Project-Prozesses aus. Das senkt die Spitzen-RSS auf ausgelasteten Maschinen und verhindert, dass Auto-Reply-/Plugin-Arbeit unabhängige Suites ausbremst. - - `pnpm test --watch` verwendet weiterhin den nativen Root-`vitest.config.ts`-Projektgraphen, weil eine Multi-Shard-Watch-Schleife nicht praktikabel ist. - - `pnpm test`, `pnpm test:watch` und `pnpm test:perf:imports` leiten explizite Datei-/Verzeichnisziele zuerst über bereichsbezogene Lanes, sodass `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` nicht die kompletten Startkosten des Root-Projekts tragen muss. - - `pnpm test:changed` erweitert geänderte Git-Pfade standardmäßig zu günstigen bereichsbezogenen Lanes: direkte Teständerungen, benachbarte `*.test.ts`-Dateien, explizite Quellzuordnungen und lokale Importgraph-Abhängige. Konfigurations-, Setup- und Paketänderungen führen Tests nicht breit aus, sofern Sie nicht explizit `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` verwenden. - - `pnpm check:changed` ist das normale smarte lokale Check-Gate für eng begrenzte Arbeit. Es klassifiziert den Diff in Core, Core-Tests, Plugins, Plugin-Tests, Apps, Docs, Release-Metadaten, Live-Docker-Tooling und Tooling und führt dann die passenden Typecheck-, Lint- und Guard-Befehle aus. Es führt keine Vitest-Tests aus; verwenden Sie `pnpm test:changed` oder explizit `pnpm test ` als Testnachweis. Nur Release-Metadaten betreffende Versions-Bumps führen gezielte Versions-/Konfigurations-/Root-Dependency-Checks aus, mit einem Guard, der Paketänderungen außerhalb des Top-Level-Versionsfelds ablehnt. - - Änderungen am Live-Docker-ACP-Harness führen fokussierte Checks aus: Shell-Syntax für die Live-Docker-Auth-Skripte und einen Live-Docker-Scheduler-Dry-Run. `package.json`-Änderungen werden nur einbezogen, wenn der Diff auf `scripts["test:docker:live-*"]` beschränkt ist; Dependency-, Export-, Versions- und andere Package-Surface-Änderungen verwenden weiterhin die breiteren Guards. - - Import-leichte Unit-Tests aus Agents, Befehlen, Plugins, Auto-Reply-Helpern, `plugin-sdk` und ähnlichen reinen Utility-Bereichen laufen über die `unit-fast`-Lane, die `test/setup-openclaw-runtime.ts` überspringt; zustandsbehaftete/runtime-lastige Dateien bleiben auf den bestehenden Lanes. - - Ausgewählte `plugin-sdk`- und `commands`-Helper-Quelldateien ordnen Läufe im Changed-Modus außerdem expliziten benachbarten Tests in diesen leichten Lanes zu, sodass Helper-Änderungen nicht die komplette schwere Suite für dieses Verzeichnis erneut ausführen. - - `auto-reply` hat dedizierte Buckets für Top-Level-Core-Helper, Top-Level-`reply.*`-Integrationstests und den `src/auto-reply/reply/**`-Teilbaum. CI teilt den Reply-Teilbaum zusätzlich in Agent-Runner-, Dispatch- und Commands/State-Routing-Shards auf, damit ein import-lastiger Bucket nicht den gesamten Node-Ausläufer übernimmt. - - Normale PR-/Main-CI überspringt absichtlich den Plugin-Batch-Sweep und den nur für Releases vorgesehenen `agentic-plugins`-Shard. Full Release Validation dispatcht den separaten untergeordneten Workflow `Plugin Prerelease` für diese Plugin-lastigen Suites auf Release-Kandidaten. + - Nicht zielgerichtetes `pnpm test` führt zwölf kleinere Shard-Konfigurationen (`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 einzigen riesigen nativen Root-Projektprozesses aus. Das senkt die maximale RSS auf ausgelasteten Maschinen und verhindert, dass Auto-Reply-/Extension-Arbeit unabhängige Suiten ausbremst. + - `pnpm test --watch` verwendet weiterhin den nativen Root-Projektgraphen `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 zuerst durch bereichsbezogene Lanes, sodass `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` nicht die volle Startlast des Root-Projekts bezahlen muss. + - `pnpm test:changed` erweitert geänderte Git-Pfade standardmäßig zu günstigen bereichsbezogenen Lanes: direkte Teständerungen, benachbarte `*.test.ts`-Dateien, explizite Quellzuordnungen und lokale Importgraph-Abhängige. Konfigurations-/Setup-/Paketänderungen führen Tests nicht breit aus, es sei denn, Sie verwenden explizit `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`. + - `pnpm check:changed` ist das normale intelligente lokale Prüfgate für eng begrenzte Arbeit. Es klassifiziert das Diff in Core, Core-Tests, Extensions, Extension-Tests, Apps, Dokumentation, Release-Metadaten, Live-Docker-Werkzeuge und Werkzeuge und führt dann die passenden Typecheck-, Lint- und Guard-Befehle aus. Es führt keine Vitest-Tests aus; rufen Sie `pnpm test:changed` oder explizit `pnpm test ` für Testnachweise auf. Versionsanhebungen nur für Release-Metadaten führen gezielte Versions-/Konfigurations-/Root-Abhängigkeitsprüfungen aus, mit einem Guard, der Paketänderungen außerhalb des obersten Versionsfelds ablehnt. + - Änderungen am Live-Docker-ACP-Harness führen fokussierte Prüfungen aus: Shell-Syntax für die Live-Docker-Auth-Skripte und einen Live-Docker-Scheduler-Probelauf. `package.json`-Änderungen werden nur einbezogen, wenn das Diff auf `scripts["test:docker:live-*"]` begrenzt ist; Abhängigkeits-, Export-, Versions- und andere Paketoberflächenänderungen verwenden weiterhin die breiteren Guards. + - Importleichte Unit-Tests aus Agents, Befehlen, Plugins, Auto-Reply-Helfern, `plugin-sdk` und ähnlichen reinen Hilfsbereichen laufen durch die `unit-fast`-Lane, die `test/setup-openclaw-runtime.ts` überspringt; zustandsbehaftete/laufzeitlastige Dateien bleiben auf den bestehenden Lanes. + - Ausgewählte `plugin-sdk`- und `commands`-Helfer-Quelldateien ordnen Changed-Mode-Läufe außerdem expliziten benachbarten Tests in diesen leichten Lanes zu, sodass Helferänderungen nicht die gesamte schwere Suite dieses Verzeichnisses erneut ausführen. + - `auto-reply` hat dedizierte Buckets für Top-Level-Core-Helfer, Top-Level-`reply.*`-Integrationstests und den Teilbaum `src/auto-reply/reply/**`. CI teilt den Reply-Teilbaum zusätzlich in Agent-Runner-, Dispatch- und Commands/State-Routing-Shards auf, sodass ein importlastiger Bucket nicht den gesamten Node-Auslauf besitzt. + - Normale PR-/Main-CI überspringt absichtlich den Extension-Batch-Sweep und den release-exklusiven Shard `agentic-plugins`. Full Release Validation startet für diese plugin-/extension-lastigen Suiten auf Release-Kandidaten den separaten untergeordneten Workflow `Plugin Prerelease`. - + - - Wenn Sie Discovery-Eingaben für Message-Tools oder Compaction-Runtime- - Kontext ändern, behalten Sie beide Abdeckungsebenen bei. - - Fügen Sie fokussierte Helper-Regressionen für reine Routing- und Normalisierungs- - Grenzen hinzu. - - Halten Sie die Integration-Suites für eingebettete Runner intakt: + - Wenn Sie Eingaben für die Message-Tool-Erkennung oder den Compaction-Laufzeitkontext ändern, + behalten Sie beide Abdeckungsebenen bei. + - Fügen Sie fokussierte Helfer-Regressionen für reine Routing- und Normalisierungsgrenzen hinzu. + - Halten Sie die Integrationssuiten des eingebetteten Runners stabil: `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 Suites prüfen, dass bereichsbezogene IDs und Compaction-Verhalten weiterhin - durch die echten `run.ts`-/`compact.ts`-Pfade fließen; reine Helper-Tests sind + - Diese Suiten verifizieren, dass bereichsbezogene IDs und Compaction-Verhalten weiterhin + durch die echten `run.ts`- / `compact.ts`-Pfade fließen; reine Helfertests sind kein ausreichender Ersatz für diese Integrationspfade. - + - Die Basis-Vitest-Konfiguration verwendet standardmäßig `threads`. - - Die gemeinsame Vitest-Konfiguration setzt `isolate: false` und verwendet den - nicht isolierten Runner über die Root-Projekte, E2E- und Live-Konfigurationen hinweg. - - Die Root-UI-Lane behält ihr `jsdom`-Setup und den Optimizer bei, läuft aber ebenfalls auf dem + - Die gemeinsame Vitest-Konfiguration setzt `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 aber ebenfalls auf dem gemeinsamen nicht isolierten Runner. - Jeder `pnpm test`-Shard erbt dieselben `threads`- + `isolate: false`- Standards aus der gemeinsamen Vitest-Konfiguration. - - `scripts/run-vitest.mjs` fügt Vitest-Child-Node- - Prozessen standardmäßig `--no-maglev` hinzu, um V8-Kompilierungsaufwand bei großen lokalen Läufen zu reduzieren. + - `scripts/run-vitest.mjs` fügt standardmäßig `--no-maglev` für untergeordnete Vitest-Node- + Prozesse hinzu, um V8-Kompilierungsaufwand bei großen lokalen Läufen zu reduzieren. Setzen Sie `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, um mit dem Standardverhalten von V8 zu vergleichen. @@ -473,51 +464,51 @@ Betrachten Sie die Suites als „zunehmenden Realismus“ (und zunehmende Flakin - `pnpm changed:lanes` zeigt, welche Architektur-Lanes ein Diff auslöst. - - Der Pre-Commit-Hook führt nur Formatierung aus. Er staged formatierte Dateien erneut und - führt weder Lint noch Typecheck oder Tests aus. - - Führen Sie `pnpm check:changed` vor der Übergabe oder dem Push explizit aus, wenn Sie - das smarte lokale Check-Gate benötigen. - - `pnpm test:changed` läuft standardmäßig über günstige bereichsbezogene Lanes. Verwenden Sie + - Der Pre-Commit-Hook ist nur für Formatierung zuständig. Er staged formatierte Dateien erneut und + führt weder Linting, Typecheck noch Tests aus. + - Führen Sie `pnpm check:changed` explizit vor Übergabe oder Push aus, wenn Sie + das intelligente lokale Prüfgate benötigen. + - `pnpm test:changed` leitet standardmäßig durch günstige bereichsbezogene Lanes. Verwenden Sie `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` nur, wenn der Agent entscheidet, dass eine Harness-, Konfigurations-, Paket- oder Contract-Änderung wirklich breitere Vitest-Abdeckung benötigt. - `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 absichtlich konservativ und reduziert sich, - wenn die Host-Load-Average bereits hoch ist, sodass mehrere gleichzeitige - Vitest-Läufe standardmäßig weniger Schaden anrichten. + - Die lokale automatische Worker-Skalierung ist absichtlich konservativ und reduziert die Last, + wenn der Load Average des Hosts bereits hoch ist, sodass mehrere gleichzeitige + Vitest-Läufe standardmäßig weniger Schaden verursachen. - Die Basis-Vitest-Konfiguration markiert die Projekte/Konfigurationsdateien als - `forceRerunTriggers`, damit Wiederholungen im Changed-Modus korrekt bleiben, wenn sich die Test- - Verkabelung ändert. + `forceRerunTriggers`, sodass Changed-Mode-Neuläufe korrekt bleiben, wenn sich die Test- + Verdrahtung ä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. + einen expliziten Cache-Speicherort für direktes Profiling möchten. - + - - `pnpm test:perf:imports` aktiviert Vitest-Importdauer-Reporting plus + - `pnpm test:perf:imports` aktiviert Vitest-Importdauerberichte plus Import-Breakdown-Ausgabe. - - `pnpm test:perf:imports:changed` begrenzt dieselbe Profiling-Ansicht auf - Dateien, die seit `origin/main` geändert wurden. + - `pnpm test:perf:imports:changed` beschränkt dieselbe Profiling-Ansicht auf + seit `origin/main` geänderte Dateien. - Shard-Timing-Daten werden nach `.artifacts/vitest-shard-timings.json` geschrieben. - Whole-Config-Läufe verwenden den Konfigurationspfad als Schlüssel; Include-Pattern-CI- + Läufe über ganze Konfigurationen verwenden den Konfigurationspfad als Schlüssel; Include-Pattern-CI- Shards hängen den Shard-Namen an, damit gefilterte Shards separat verfolgt werden können. - - Wenn ein heißer Test weiterhin den Großteil seiner Zeit in Startup-Imports verbringt, - halten Sie schwere Dependencies hinter einer schmalen lokalen `*.runtime.ts`-Schnittstelle und - mocken Sie diese Schnittstelle direkt, statt Runtime-Helper per Deep-Import nur einzubinden, - um sie durch `vi.mock(...)` zu reichen. - - `pnpm test:perf:changed:bench -- --ref ` vergleicht das geroutete - `test:changed` mit dem nativen Root-Project-Pfad für diesen committeten - Diff und gibt Wall-Time plus macOS-Max-RSS aus. + - Wenn ein heißer Test weiterhin die meiste Zeit in Start-Imports verbringt, + halten Sie schwere Abhängigkeiten hinter einer schmalen lokalen `*.runtime.ts`-Nahtstelle und + mocken Sie diese Nahtstelle direkt, statt Laufzeithelfer tief zu importieren, nur + um sie durch `vi.mock(...)` zu schleusen. + - `pnpm test:perf:changed:bench -- --ref ` vergleicht geroutetes + `test:changed` mit dem nativen Root-Projektpfad für dieses commitete + Diff und gibt Laufzeit plus macOS-Max-RSS aus. - `pnpm test:perf:changed:bench -- --worktree` benchmarked den aktuellen - dirty Tree, indem die geänderte Dateiliste durch + dirty 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 Main-Thread-CPU-Profil für - Vitest-/Vite-Startup- und Transform-Overhead. - - `pnpm test:perf:profile:runner` schreibt Runner-CPU- und Heap-Profile für die + Vitest-/Vite-Start und Transform-Overhead. + - `pnpm test:perf:profile:runner` schreibt Runner-CPU+Heap-Profile für die Unit-Suite mit deaktivierter Dateiparallelität. @@ -528,50 +519,50 @@ Betrachten Sie die Suites als „zunehmenden Realismus“ (und zunehmende Flakin - Befehl: `pnpm test:stability:gateway` - Konfiguration: `vitest.gateway.config.ts`, auf einen Worker erzwungen - Umfang: - - Startet ein echtes Loopback-Gateway mit standardmäßig aktivierter Diagnose - - Treibt synthetische Gateway-Nachrichten-, Memory- und Large-Payload-Last über den Diagnose-Event-Pfad - - Fragt `diagnostics.stability` über das Gateway-WS-RPC ab - - Deckt Persistenz-Helper für Diagnose-Stabilitäts-Bundles ab - - Stellt sicher, dass der Recorder begrenzt bleibt, synthetische RSS-Samples unter dem Pressure-Budget bleiben und Queue-Tiefen pro Sitzung wieder auf null ablaufen + - Startet standardmäßig ein echtes local loopback-Gateway mit aktivierter Diagnose + - Treibt synthetische Gateway-Nachrichten-, Speicher- und Large-Payload-Last durch den Diagnoseereignispfad + - Fragt `diagnostics.stability` über den Gateway-WS-RPC ab + - Deckt Persistenzhelfer für Diagnose-Stabilitätsbundles ab + - Stellt sicher, dass der Recorder begrenzt bleibt, synthetische RSS-Samples unter dem Druckbudget bleiben und Queue-Tiefen pro Sitzung wieder auf null ablaufen - Erwartungen: - CI-sicher und ohne Schlüssel - - Enge Lane für Nachverfolgung von Stabilitätsregressionen, kein Ersatz für die vollständige Gateway-Suite + - Enge Lane für Stabilitätsregressions-Nachverfolgung, 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/` -- Runtime-Standards: - - Verwendet Vitest-`threads` mit `isolate: false`, passend zum restlichen Repo. +- Runtime-Standardeinstellungen: + - Verwendet Vitest-`threads` mit `isolate: false`, passend zum Rest des Repositorys. - 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 Overrides: + - Läuft standardmäßig im stillen Modus, um den Aufwand für Konsolen-I/O zu reduzieren. +- Nützliche Überschreibungen: - `OPENCLAW_E2E_WORKERS=`, um die Worker-Anzahl zu erzwingen (auf 16 begrenzt). - - `OPENCLAW_E2E_VERBOSE=1`, um ausführliche Konsolenausgaben wieder zu aktivieren. + - `OPENCLAW_E2E_VERBOSE=1`, um ausführliche Konsolenausgabe wieder zu aktivieren. - Umfang: - - End-to-End-Verhalten mehrerer Gateway-Instanzen - - WebSocket-/HTTP-Oberflächen, Node-Pairing und schwereres Networking + - End-to-End-Verhalten des Multi-Instanz-Gateway + - WebSocket-/HTTP-Oberflächen, Node-Kopplung und aufwendigere Netzwerkfunktionen - Erwartungen: - Läuft in CI (wenn in der Pipeline aktiviert) - Keine echten Schlüssel erforderlich - Mehr bewegliche Teile als Unit-Tests (kann langsamer sein) -### E2E: OpenShell-Backend-Smoke +### E2E: OpenShell-Backend-Smoke-Test - 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 - - Testet das OpenClaw-OpenShell-Backend über echtes `sandbox ssh-config` + SSH-Ausführung + - Testet das OpenShell-Backend von OpenClaw über echtes `sandbox ssh-config` + SSH-Ausführung - Verifiziert remote-kanonisches Dateisystemverhalten über die Sandbox-fs-Bridge - Erwartungen: - - Nur nach expliziter Aktivierung; nicht Teil des standardmäßigen `pnpm test:e2e`-Laufs + - Nur Opt-in; nicht Teil des standardmäßigen `pnpm test:e2e`-Laufs - Erfordert eine lokale `openshell`-CLI plus einen funktionierenden Docker-Daemon - - Verwendet isoliertes `HOME` / `XDG_CONFIG_HOME` und zerstört danach das Test-Gateway und die Sandbox + - Verwendet isolierte `HOME` / `XDG_CONFIG_HOME`, zerstört danach das Test-Gateway und die Sandbox - Nützliche Überschreibungen: - - `OPENCLAW_E2E_OPENSHELL=1`, um den Test zu aktivieren, wenn die breitere E2E-Suite manuell ausgeführt wird + - `OPENCLAW_E2E_OPENSHELL=1`, um den Test beim manuellen Ausführen der breiteren E2E-Suite zu aktivieren - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, um auf ein nicht standardmäßiges CLI-Binary oder Wrapper-Skript zu verweisen ### Live (echte Provider + echte Modelle) @@ -582,18 +573,18 @@ Betrachten Sie die Suites als „zunehmenden Realismus“ (und zunehmende Flakin - Standard: durch `pnpm test:live` **aktiviert** (setzt `OPENCLAW_LIVE_TEST=1`) - Umfang: - „Funktioniert dieser Provider/dieses Modell _heute_ tatsächlich mit echten Zugangsdaten?“ - - Erfasst Formatänderungen von Providern, Besonderheiten bei Tool-Aufrufen, Authentifizierungsprobleme und Verhalten bei Ratenbegrenzungen + - Erkennt Provider-Formatänderungen, Besonderheiten beim Tool-Aufruf, Auth-Probleme und Rate-Limit-Verhalten - Erwartungen: - Absichtlich nicht CI-stabil (echte Netzwerke, echte Provider-Richtlinien, Kontingente, Ausfälle) - - Kostet Geld / nutzt Ratenlimits - - Bevorzugen Sie eingegrenzte Teilmengen statt „alles“ -- Live-Läufe sourcen `~/.profile`, um fehlende API-Schlüssel zu übernehmen. -- Standardmäßig isolieren Live-Läufe weiterhin `HOME` und kopieren Konfigurations-/Authentifizierungsmaterial in ein temporäres Test-Home, damit Unit-Fixtures Ihr echtes `~/.openclaw` nicht verändern können. + - Kostet Geld / nutzt Rate Limits + - Führen Sie vorzugsweise eingeschränkte Teilmengen statt „alles“ aus +- Live-Läufe sourcen `~/.profile`, um fehlende API-Schlüssel zu laden. +- Standardmäßig isolieren Live-Läufe weiterhin `HOME` und kopieren Konfigurations-/Auth-Material in ein temporäres Test-Home, damit Unit-Fixtures Ihr echtes `~/.openclaw` nicht verändern können. - Setzen Sie `OPENCLAW_LIVE_USE_REAL_HOME=1` nur, wenn Live-Tests absichtlich Ihr echtes Home-Verzeichnis verwenden sollen. -- `pnpm test:live` nutzt jetzt standardmäßig einen ruhigeren Modus: Die `[live] ...`-Fortschrittsausgabe bleibt erhalten, aber der zusätzliche `~/.profile`-Hinweis wird unterdrückt und Gateway-Bootstrap-Logs/Bonjour-Ausgaben werden stummgeschaltet. Setzen Sie `OPENCLAW_LIVE_TEST_QUIET=0`, wenn Sie die vollständigen Startprotokolle zurückhaben möchten. -- API-Schlüsselrotation (Provider-spezifisch): Setzen Sie `*_API_KEYS` im Komma-/Semikolonformat oder `*_API_KEY_1`, `*_API_KEY_2` (zum Beispiel `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) oder eine Live-spezifische Überschreibung über `OPENCLAW_LIVE_*_KEY`; Tests versuchen es bei Ratenlimit-Antworten erneut. +- `pnpm test:live` verwendet jetzt standardmäßig einen ruhigeren Modus: Die `[live] ...`-Fortschrittsausgabe bleibt erhalten, aber der zusätzliche `~/.profile`-Hinweis wird unterdrückt und Gateway-Bootstrap-Logs/Bonjour-Meldungen werden stummgeschaltet. Setzen Sie `OPENCLAW_LIVE_TEST_QUIET=0`, wenn Sie die vollständigen Startlogs zurückhaben möchten. +- API-Schlüssel-Rotation (Provider-spezifisch): Setzen Sie `*_API_KEYS` im Komma-/Semikolonformat 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 es bei Rate-Limit-Antworten erneut. - Fortschritts-/Heartbeat-Ausgabe: - - Live-Suites geben jetzt Fortschrittszeilen auf stderr aus, damit lange Provider-Aufrufe sichtbar aktiv sind, auch wenn die Vitest-Konsolenerfassung ruhig ist. + - Live-Suites geben jetzt Fortschrittszeilen an stderr aus, damit lange Provider-Aufrufe sichtbar aktiv bleiben, auch wenn die Vitest-Konsolenerfassung ruhig ist. - `vitest.live.config.ts` deaktiviert die Vitest-Konsolenabfangung, damit Provider-/Gateway-Fortschrittszeilen während Live-Läufen sofort gestreamt werden. - Stimmen Sie Direct-Model-Heartbeats mit `OPENCLAW_LIVE_HEARTBEAT_MS` ab. - Stimmen Sie Gateway-/Probe-Heartbeats mit `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` ab. @@ -603,236 +594,240 @@ Betrachten Sie die Suites als „zunehmenden Realismus“ (und zunehmende Flakin Verwenden Sie diese Entscheidungstabelle: - Logik/Tests bearbeiten: Führen Sie `pnpm test` aus (und `pnpm test:coverage`, wenn Sie viel geändert haben) -- Gateway-Netzwerk / WS-Protokoll / Pairing berühren: Fügen Sie `pnpm test:e2e` hinzu -- „Mein Bot ist ausgefallen“ / Provider-spezifische Fehler / Tool-Aufrufe debuggen: Führen Sie ein eingegrenztes `pnpm test:live` aus +- Gateway-Netzwerk / WS-Protokoll / Kopplung berühren: Fügen Sie `pnpm test:e2e` hinzu +- „Mein Bot ist offline“ / Provider-spezifische Fehler / Tool-Aufrufe debuggen: Führen Sie ein eingeschränktes `pnpm test:live` aus ## Live-Tests (mit Netzwerkzugriff) -Für die Live-Modellmatrix, CLI-Backend-Smokes, ACP-Smokes, Codex-App-Server-Harness und alle Live-Tests für Medien-Provider (Deepgram, BytePlus, ComfyUI, Bild, Musik, Video, Medien-Harness) sowie den Umgang mit Zugangsdaten für Live-Läufe siehe [Live-Suites testen](/de/help/testing-live). Die dedizierte Checkliste für Updates und Plugin-Validierung finden Sie unter [Updates und Plugins testen](/de/help/testing-updates-plugins). +Informationen zur Live-Modellmatrix, zu CLI-Backend-Smoke-Tests, ACP-Smoke-Tests, zum Codex-App-Server- +Harness und zu allen Live-Tests für Medien-Provider (Deepgram, BytePlus, ComfyUI, Bild, +Musik, Video, Medien-Harness) — plus Umgang mit Zugangsdaten für Live-Läufe — finden Sie unter +[Live-Suites testen](/de/help/testing-live). Die dedizierte Checkliste für Update- und +Plugin-Validierung finden Sie unter +[Updates und Plugins testen](/de/help/testing-updates-plugins). ## Docker-Runner (optionale „funktioniert unter Linux“-Prüfungen) -Diese Docker-Runner sind in zwei Kategorien aufgeteilt: +Diese Docker-Runner sind in zwei Bereiche aufgeteilt: -- Live-Modell-Runner: `test:docker:live-models` und `test:docker:live-gateway` führen nur ihre passende Live-Datei mit Profilschlüssel innerhalb des Repo-Docker-Images aus (`src/agents/models.profiles.live.test.ts` und `src/gateway/gateway-models.profiles.live.test.ts`), mounten Ihr lokales Konfigurationsverzeichnis und den Workspace (und sourcen `~/.profile`, falls gemountet). Die passenden lokalen Einstiegspunkte sind `test:live:models-profiles` und `test:live:gateway-profiles`. +- Live-Modell-Runner: `test:docker:live-models` und `test:docker:live-gateway` führen nur ihre passende Live-Datei mit Profilschlüssel im Repository-Docker-Image aus (`src/agents/models.profiles.live.test.ts` und `src/gateway/gateway-models.profiles.live.test.ts`), mounten Ihr lokales Konfigurationsverzeichnis und Ihren Workspace (und sourcen `~/.profile`, falls gemountet). Die passenden lokalen Einstiegspunkte 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-Durchlauf 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-Vars, 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`, packt OpenClaw einmal als npm-Tarball über `scripts/package-openclaw-for-docker.mjs` und baut/verwendet dann zwei `scripts/e2e/Dockerfile`-Images. Das Bare-Image ist nur der Node/Git-Runner für Installations-, Update- und Plugin-Abhängigkeits-Lanes; diese Lanes mounten den vorgebauten Tarball. Das funktionale Image installiert denselben Tarball in `/app` für Lanes mit Built-App-Funktionalität. Docker-Lane-Definitionen liegen in `scripts/lib/docker-e2e-scenarios.mjs`; Planerlogik liegt in `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` führt den ausgewählten Plan aus. Das Aggregat verwendet einen gewichteten lokalen Scheduler: `OPENCLAW_DOCKER_ALL_PARALLELISM` steuert Prozess-Slots, während Ressourcenobergrenzen verhindern, dass schwere Live-, npm-Installations- und Multi-Service-Lanes alle gleichzeitig starten. Wenn eine einzelne Lane schwerer als die aktiven Obergrenzen ist, kann der Scheduler sie trotzdem starten, wenn der Pool leer ist, und sie dann allein weiterlaufen lassen, bis wieder Kapazität verfügbar ist. Standardwerte sind 10 Slots, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` und `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; passen Sie `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` oder `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` nur an, wenn der Docker-Host mehr Spielraum hat. Der Runner führt standardmäßig einen Docker-Preflight aus, entfernt veraltete OpenClaw-E2E-Container, gibt alle 30 Sekunden Status aus, speichert erfolgreiche Lane-Laufzeiten in `.artifacts/docker-tests/lane-timings.json` und nutzt diese Zeiten, um bei späteren Läufen längere Lanes zuerst zu starten. Verwenden Sie `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, um das gewichtete Lane-Manifest ohne Docker-Build oder -Ausführung auszugeben, oder `node scripts/test-docker-all.mjs --plan-json`, um den CI-Plan für ausgewählte Lanes, Paket-/Image-Anforderungen und Zugangsdaten auszugeben. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Überschreiben Sie diese Umgebungsvariablen, wenn Sie + ausdrücklich den größeren vollständigen Scan möchten. +- `test:docker:all` baut das Live-Docker-Image einmal über `test:docker:live-build`, packt OpenClaw einmal als npm-Tarball über `scripts/package-openclaw-for-docker.mjs` und baut/verwendet dann zwei `scripts/e2e/Dockerfile`-Images wieder. Das Bare-Image ist nur der Node-/Git-Runner für Installations-/Update-/Plugin-Abhängigkeits-Lanes; diese Lanes mounten den vorab gebauten Tarball. Das funktionale Image installiert denselben Tarball nach `/app` für Lanes mit Built-App-Funktionalität. Docker-Lane-Definitionen befinden sich in `scripts/lib/docker-e2e-scenarios.mjs`; Planerlogik befindet sich in `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` führt den ausgewählten Plan aus. Das Aggregat verwendet einen gewichteten lokalen Scheduler: `OPENCLAW_DOCKER_ALL_PARALLELISM` steuert Prozess-Slots, während Ressourcenobergrenzen verhindern, dass schwere Live-, npm-Installations- und Multi-Service-Lanes alle gleichzeitig starten. Wenn eine einzelne Lane schwerer als die aktiven Obergrenzen ist, kann der Scheduler sie trotzdem starten, wenn der Pool leer ist, und lässt sie dann allein laufen, bis wieder Kapazität verfügbar ist. Standards sind 10 Slots, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` und `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; stimmen Sie `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` oder `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` nur ab, wenn der Docker-Host mehr Spielraum hat. Der Runner führt standardmäßig einen Docker-Preflight aus, entfernt veraltete OpenClaw-E2E-Container, gibt alle 30 Sekunden Status aus, speichert erfolgreiche Lane-Zeiten in `.artifacts/docker-tests/lane-timings.json` und verwendet diese Zeiten, um bei späteren Läufen längere Lanes zuerst zu starten. Verwenden Sie `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, um das gewichtete Lane-Manifest ohne Bauen oder Ausführen von Docker auszugeben, oder `node scripts/test-docker-all.mjs --plan-json`, um den CI-Plan für ausgewählte Lanes, Paket-/Image-Anforderungen und Zugangsdaten auszugeben. - `Package Acceptance` ist das GitHub-native Paket-Gate für „funktioniert dieser installierbare Tarball als Produkt?“ Es löst ein Kandidatenpaket aus `source=npm`, `source=ref`, `source=url` oder `source=artifact` auf, lädt es als `package-under-test` hoch und führt dann die wiederverwendbaren Docker-E2E-Lanes gegen genau diesen Tarball aus, statt die ausgewählte Ref neu zu packen. Profile sind nach Breite geordnet: `smoke`, `package`, `product` und `full`. Siehe [Updates und Plugins testen](/de/help/testing-updates-plugins) für den Paket-/Update-/Plugin-Vertrag, die Survivor-Matrix für veröffentlichte Upgrades, Release-Standards und Fehlertriage. -- Build- und Release-Prüfungen führen `scripts/check-cli-bootstrap-imports.mjs` nach tsdown aus. Der Guard durchläuft den statischen gebauten Graphen aus `dist/entry.js` und `dist/cli/run-main.js` und schlägt fehl, wenn Pre-Dispatch-Startup Paketabhängigkeiten wie Commander, Prompt-UI, undici oder Logging vor dem Command-Dispatch importiert; außerdem hält er den gebündelten Gateway-Run-Chunk unter dem Budget und lehnt statische Importe bekannter kalter Gateway-Pfade ab. Der verpackte CLI-Smoke deckt außerdem Root-Hilfe, Onboard-Hilfe, Doctor-Hilfe, Status, Konfigurationsschema und einen Modelllistenbefehl ab. -- Die Legacy-Kompatibilität von Package Acceptance ist auf `2026.4.25` begrenzt (`2026.4.25-beta.*` eingeschlossen). Bis zu diesem Stichtag toleriert der Harness nur Metadatenlücken ausgelieferter Pakete: ausgelassene private QA-Inventareinträge, fehlendes `gateway install --wrapper`, fehlende Patch-Dateien in der aus dem Tarball abgeleiteten Git-Fixture, fehlendes persistiertes `update.channel`, Legacy-Speicherorte für Plugin-Installationsdatensätze, fehlende Persistenz von Marketplace-Installationsdatensätzen und Konfigurationsmetadatenmigration während `plugins update`. Für Pakete nach `2026.4.25` sind diese Pfade strikte Fehler. -- Container-Smoke-Runner: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:update-channel-switch`, `test:docker:upgrade-survivor`, `test:docker:published-upgrade-survivor`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:browser-cdp-snapshot`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update`, `test:docker:plugin-lifecycle-matrix` und `test:docker:config-reload` starten einen oder mehrere echte Container und verifizieren übergeordnete Integrationspfade. +- Build- und Release-Prüfungen führen `scripts/check-cli-bootstrap-imports.mjs` nach tsdown aus. Der Guard läuft den statisch gebauten Graphen von `dist/entry.js` und `dist/cli/run-main.js` ab und schlägt fehl, wenn Pre-Dispatch-Startimporte Paketabhängigkeiten wie Commander, Prompt-UI, undici oder Logging vor dem Command Dispatch importieren; außerdem hält er den gebündelten Gateway-Run-Chunk unter Budget und weist statische Importe bekannter kalter Gateway-Pfade zurück. Der Paket-CLI-Smoke-Test deckt außerdem Root-Hilfe, Onboard-Hilfe, Doctor-Hilfe, Status, Konfigurationsschema und einen Modelllistenbefehl ab. +- Die Legacy-Kompatibilität von Package Acceptance ist auf `2026.4.25` begrenzt (`2026.4.25-beta.*` eingeschlossen). Bis zu diesem Stichtag toleriert der Harness nur Metadatenlücken ausgelieferter Pakete: ausgelassene private QA-Inventareinträge, fehlendes `gateway install --wrapper`, fehlende Patch-Dateien im aus dem Tarball abgeleiteten Git-Fixture, fehlendes persistiertes `update.channel`, Legacy-Speicherorte für Plugin-Installationsdatensätze, fehlende Marketplace-Installationsdatensatz-Persistenz und Konfigurationsmetadatenmigration während `plugins update`. Für Pakete nach `2026.4.25` sind diese Pfade strikte Fehler. +- Container-Smoke-Runner: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:update-channel-switch`, `test:docker:upgrade-survivor`, `test:docker:published-upgrade-survivor`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:browser-cdp-snapshot`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update`, `test:docker:plugin-lifecycle-matrix` 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 CLIs Tokens aktualisieren kann, ohne den Auth-Speicher des Hosts zu verändern: +Die Live-Modell-Docker-Runner binden außerdem nur die benötigten CLI-Auth-Homes ein (oder alle unterstützten, wenn der Lauf nicht eingeschränkt ist) und kopieren sie dann vor dem Lauf in das Container-Home, damit externe CLI-OAuth Token aktualisieren kann, ohne den Auth-Speicher des Hosts 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`; deckt standardmäßig Claude, Codex und Gemini ab, mit strikter Droid-/OpenCode-Abdeckung über `pnpm test:docker:live-acp-bind:droid` und `pnpm test:docker:live-acp-bind:opencode`) +- ACP-Bind-Smoke: `pnpm test:docker:live-acp-bind` (Skript: `scripts/test-live-acp-bind-docker.sh`; deckt standardmäßig Claude, Codex und Gemini ab, mit strenger Droid/OpenCode-Abdeckung über `pnpm test:docker:live-acp-bind:droid` und `pnpm test:docker:live-acp-bind:opencode`) - CLI-Backend-Smoke: `pnpm test:docker:live-cli-backend` (Skript: `scripts/test-live-cli-backend-docker.sh`) - Codex-App-Server-Harness-Smoke: `pnpm test:docker:live-codex-harness` (Skript: `scripts/test-live-codex-harness-docker.sh`) -- Gateway + Dev-Agent: `pnpm test:docker:live-gateway` (Skript: `scripts/test-live-gateway-models-docker.sh`) -- Observability-Smoke: `pnpm qa:otel:smoke` ist eine private QA-Lane für Source-Checkouts. Sie ist absichtlich nicht Teil der Docker-Release-Lanes für Pakete, weil der npm-Tarball QA Lab auslässt. +- Gateway + Entwicklungsagent: `pnpm test:docker:live-gateway` (Skript: `scripts/test-live-gateway-models-docker.sh`) +- Observability-Smoke: `pnpm qa:otel:smoke` ist eine private QA-Lane für Source-Checkouts. Sie ist absichtlich nicht Teil der Docker-Release-Lanes für Pakete, da der npm-Tarball QA Lab auslässt. - 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-/Channel-/Agent-Smoke: `pnpm test:docker:npm-onboard-channel-agent` installiert den gepackten OpenClaw-Tarball global in Docker, konfiguriert OpenAI per Env-Ref-Onboarding sowie standardmäßig Telegram, führt Doctor aus und führt einen gemockten OpenAI-Agent-Turn aus. Verwenden Sie einen vorgebauten Tarball mit `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz` wieder, überspringen Sie den Host-Rebuild mit `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0`, oder wechseln Sie den Channel mit `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Update-Channel-Switch-Smoke: `pnpm test:docker:update-channel-switch` installiert den gepackten OpenClaw-Tarball global in Docker, wechselt vom Paket `stable` zu Git `dev`, verifiziert den persistierten Channel und die Plugin-Funktion nach dem Update, wechselt anschließend zurück zum Paket `stable` und prüft den Update-Status. -- Upgrade-Survivor-Smoke: `pnpm test:docker:upgrade-survivor` installiert den gepackten OpenClaw-Tarball über ein schmutziges Old-User-Fixture mit Agents, Channel-Konfiguration, Plugin-Allowlists, veraltetem Plugin-Abhängigkeitszustand und vorhandenen Workspace-/Session-Dateien. Es führt ein Paket-Update plus nicht-interaktiven Doctor ohne Live-Provider- oder Channel-Schlüssel aus, startet anschließend ein Loopback-Gateway und prüft die Beibehaltung von Konfiguration/Zustand sowie Startup-/Status-Budgets. -- Published-Upgrade-Survivor-Smoke: `pnpm test:docker:published-upgrade-survivor` installiert standardmäßig `openclaw@latest`, legt realistische Existing-User-Dateien an, konfiguriert diese Baseline mit einem eingebetteten Command-Rezept, validiert die resultierende Konfiguration, aktualisiert diese veröffentlichte Installation auf den Kandidaten-Tarball, führt einen nicht-interaktiven Doctor aus, schreibt `.artifacts/upgrade-survivor/summary.json`, startet anschließend ein Loopback-Gateway und prüft konfigurierte Intents, Zustandserhalt, Startup, `/healthz`, `/readyz` und RPC-Status-Budgets. Überschreiben Sie eine Baseline mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, lassen Sie den Aggregat-Scheduler exakte Baselines mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` wie `all-since-2026.4.23` erweitern, und erweitern Sie issue-artige Fixtures mit `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` wie `reported-issues`; die Menge `reported-issues` enthält `configured-plugin-installs` für die automatische Reparatur externer OpenClaw-Plugin-Installationen. Package Acceptance stellt diese als `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines` und `published_upgrade_survivor_scenarios` bereit. -- Session-Runtime-Context-Smoke: `pnpm test:docker:session-runtime-context` verifiziert die Persistenz versteckter Runtime-Context-Transkripte plus Doctor-Reparatur betroffener duplizierter Prompt-Rewrite-Branches. -- Bun-Global-Install-Smoke: `bash scripts/e2e/bun-global-install-smoke.sh` packt den aktuellen Tree, installiert ihn mit `bun install -g` in einem isolierten Home und verifiziert, dass `openclaw infer image providers --json` gebündelte Image-Provider zurückgibt, statt hängen zu bleiben. Verwenden Sie einen vorgebauten Tarball mit `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz` wieder, überspringen Sie den Host-Build mit `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0`, oder kopieren Sie `dist/` aus einem gebauten Docker-Image mit `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. -- Installer-Docker-Smoke: `bash scripts/test-install-sh-docker.sh` teilt einen npm-Cache über seine Root-, Update- und Direct-npm-Container hinweg. Der Update-Smoke verwendet standardmäßig npm `latest` als stabile Baseline, bevor auf den Kandidaten-Tarball aktualisiert wird. Überschreiben Sie dies lokal mit `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` oder auf GitHub mit der Eingabe `update_baseline_version` des Install-Smoke-Workflows. Nicht-Root-Installer-Prüfungen behalten einen isolierten npm-Cache, damit root-eigene Cache-Einträge das user-lokale Installationsverhalten nicht verdecken. Setzen Sie `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, um den Root-/Update-/Direct-npm-Cache über lokale Wiederholungen hinweg wiederzuverwenden. -- Install-Smoke-CI überspringt das doppelte globale Direct-npm-Update mit `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; führen Sie das Skript lokal ohne diese Env aus, wenn direkte `npm install -g`-Abdeckung benötigt wird. -- Agents-Delete-Shared-Workspace-CLI-Smoke: `pnpm test:docker:agents-delete-shared-workspace` (Skript: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) baut standardmäßig das Root-Dockerfile-Image, legt zwei Agents mit einem Workspace in einem isolierten Container-Home an, führt `agents delete --json` aus und verifiziert gültiges JSON plus Verhalten mit beibehaltenem Workspace. Verwenden Sie das Install-Smoke-Image wieder mit `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`. -- Gateway-Networking (zwei Container, WS-Auth + Health): `pnpm test:docker:gateway-network` (Skript: `scripts/e2e/gateway-network-docker.sh`) -- Browser-CDP-Snapshot-Smoke: `pnpm test:docker:browser-cdp-snapshot` (Skript: `scripts/e2e/browser-cdp-snapshot-docker.sh`) baut das Source-E2E-Image plus eine Chromium-Schicht, startet Chromium mit rohem CDP, führt `browser doctor --deep` aus und verifiziert, dass CDP-Rollen-Snapshots Link-URLs, cursor-promoted Clickables, Iframe-Refs und Frame-Metadaten abdecken. -- OpenAI-Responses-`web_search`-Regression mit minimalem Reasoning: `pnpm test:docker:openai-web-search-minimal` (Skript: `scripts/e2e/openai-web-search-minimal-docker.sh`) führt einen gemockten OpenAI-Server über Gateway aus, verifiziert, dass `web_search` `reasoning.effort` von `minimal` auf `low` anhebt, erzwingt anschließend die Ablehnung durch das Provider-Schema und prüft, dass das Rohdetail in den Gateway-Logs erscheint. -- MCP-Channel-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-Profile-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-Child-Teardown nach isolierten Cron- und einmaligen Subagent-Läufen): `pnpm test:docker:cron-mcp-cleanup` (Skript: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (Install-/Update-Smoke für lokalen Pfad, `file:`, npm-Registry mit gehobenen Abhängigkeiten, bewegliche Git-Refs, ClawHub-Kitchen-Sink, Marketplace-Updates und Claude-Bundle-Enable/Inspect): `pnpm test:docker:plugins` (Skript: `scripts/e2e/plugins-docker.sh`) - Setzen Sie `OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, um den ClawHub-Block zu überspringen, oder überschreiben Sie das standardmäßige Kitchen-Sink-Paket-/Runtime-Paar mit `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` und `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. Ohne `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL` verwendet der Test einen hermetischen lokalen ClawHub-Fixture-Server. -- Plugin-Update-Unchanged-Smoke: `pnpm test:docker:plugin-update` (Skript: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Plugin-Lifecycle-Matrix-Smoke: `pnpm test:docker:plugin-lifecycle-matrix` installiert den gepackten OpenClaw-Tarball in einem leeren Container, installiert ein npm-Plugin, schaltet Enable/Disable um, führt Upgrades und Downgrades über eine lokale npm-Registry durch, löscht den installierten Code und verifiziert anschließend, dass Uninstall weiterhin veralteten Zustand entfernt, während RSS-/CPU-Metriken für jede Lifecycle-Phase protokolliert werden. -- Config-Reload-Metadata-Smoke: `pnpm test:docker:config-reload` (Skript: `scripts/e2e/config-reload-source-docker.sh`) -- Plugins: `pnpm test:docker:plugins` deckt Install-/Update-Smoke für lokalen Pfad, `file:`, npm-Registry mit gehobenen Abhängigkeiten, bewegliche Git-Refs, ClawHub-Fixtures, Marketplace-Updates und Claude-Bundle-Enable/Inspect ab. `pnpm test:docker:plugin-update` deckt unverändertes Update-Verhalten für installierte Plugins ab. `pnpm test:docker:plugin-lifecycle-matrix` deckt ressourcenverfolgte npm-Plugin-Installation, Enable, Disable, Upgrade, Downgrade und Uninstall bei fehlendem Code ab. +- Npm-Tarball-Onboarding/Channel/Agent-Smoke: `pnpm test:docker:npm-onboard-channel-agent` installiert den gepackten OpenClaw-Tarball global in Docker, konfiguriert standardmäßig OpenAI per Env-Ref-Onboarding plus Telegram, führt doctor aus und führt einen gemockten OpenAI-Agent-Turn aus. Verwenden Sie einen vorab gebauten Tarball mit `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz` wieder, überspringen Sie den Host-Neubau mit `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0`, oder wechseln Sie den Channel mit `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Smoke für Wechsel des Update-Channels: `pnpm test:docker:update-channel-switch` installiert den gepackten OpenClaw-Tarball global in Docker, wechselt von Paket `stable` zu Git `dev`, verifiziert den persistierten Channel und die Plugin-Funktion nach dem Update, wechselt anschließend zurück zu Paket `stable` und prüft den Update-Status. +- Upgrade-Survivor-Smoke: `pnpm test:docker:upgrade-survivor` installiert den gepackten OpenClaw-Tarball über ein verunreinigtes Fixture eines alten Benutzers mit Agenten, Channel-Konfiguration, Plugin-Allowlists, veraltetem Plugin-Abhängigkeitszustand und vorhandenen Workspace-/Session-Dateien. Es führt Paket-Update plus nicht interaktiven doctor ohne Live-Provider- oder Channel-Schlüssel aus, startet anschließend ein loopback-Gateway und prüft die Beibehaltung von Konfiguration/Zustand sowie Start-/Status-Budgets. +- Veröffentlichter Upgrade-Survivor-Smoke: `pnpm test:docker:published-upgrade-survivor` installiert standardmäßig `openclaw@latest`, legt realistische Dateien bestehender Benutzer an, konfiguriert diese Baseline mit einem eingebauten Befehlsrezept, validiert die resultierende Konfiguration, aktualisiert diese veröffentlichte Installation auf den Kandidaten-Tarball, führt nicht interaktiven doctor aus, schreibt `.artifacts/upgrade-survivor/summary.json`, startet anschließend ein loopback-Gateway und prüft konfigurierte Intents, Zustandsbeibehaltung, Start, `/healthz`, `/readyz` und RPC-Status-Budgets. Überschreiben Sie eine Baseline mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, lassen Sie den Aggregat-Scheduler exakte Baselines mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` wie `all-since-2026.4.23` erweitern, und erweitern Sie issue-förmige Fixtures mit `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` wie `reported-issues`; die Menge `reported-issues` enthält `configured-plugin-installs` für automatische Reparatur externer OpenClaw-Plugin-Installationen. Package Acceptance stellt diese als `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines` und `published_upgrade_survivor_scenarios` bereit. +- Session-Runtime-Kontext-Smoke: `pnpm test:docker:session-runtime-context` verifiziert die Persistenz verborgener Runtime-Kontext-Transkripte plus doctor-Reparatur betroffener duplizierter Prompt-Rewrite-Branches. +- Bun-Globalinstallations-Smoke: `bash scripts/e2e/bun-global-install-smoke.sh` packt den aktuellen Tree, installiert ihn mit `bun install -g` in einem isolierten Home und verifiziert, dass `openclaw infer image providers --json` gebündelte Image-Provider zurückgibt, statt hängen zu bleiben. Verwenden Sie einen vorab gebauten Tarball mit `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz` wieder, überspringen Sie den Host-Build mit `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0`, oder kopieren Sie `dist/` aus einem gebauten Docker-Image mit `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. +- Installer-Docker-Smoke: `bash scripts/test-install-sh-docker.sh` teilt einen npm-Cache zwischen seinen Root-, Update- und Direct-npm-Containern. Der Update-Smoke verwendet standardmäßig npm `latest` als stabile Baseline, bevor auf den Kandidaten-Tarball aktualisiert wird. Überschreiben Sie dies lokal mit `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` oder mit der Eingabe `update_baseline_version` des Install Smoke-Workflows auf GitHub. Nicht-Root-Installer-Prüfungen behalten einen isolierten npm-Cache, damit root-eigene Cache-Einträge das benutzerlokale Installationsverhalten nicht verdecken. Setzen Sie `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, um den Root-/Update-/Direct-npm-Cache über lokale Wiederholungen hinweg wiederzuverwenden. +- Install Smoke CI überspringt das doppelte direkte globale npm-Update mit `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; führen Sie das Skript lokal ohne diese Env aus, wenn direkte `npm install -g`-Abdeckung benötigt wird. +- Agents-delete-shared-workspace-CLI-Smoke: `pnpm test:docker:agents-delete-shared-workspace` (Skript: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) baut standardmäßig das Root-Dockerfile-Image, legt zwei Agenten mit einem Workspace in einem isolierten Container-Home an, führt `agents delete --json` aus und verifiziert gültiges JSON plus Verhalten zum Beibehalten des Workspace. Verwenden Sie das install-smoke-Image mit `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1` wieder. +- Gateway-Netzwerk (zwei Container, WS-Auth + Health): `pnpm test:docker:gateway-network` (Skript: `scripts/e2e/gateway-network-docker.sh`) +- Browser-CDP-Snapshot-Smoke: `pnpm test:docker:browser-cdp-snapshot` (Skript: `scripts/e2e/browser-cdp-snapshot-docker.sh`) baut das Source-E2E-Image plus eine Chromium-Schicht, startet Chromium mit rohem CDP, führt `browser doctor --deep` aus und verifiziert, dass CDP-Rollensnapshots Link-URLs, zu Klickzielen hochgestufte Cursor-Elemente, iframe-Refs und Frame-Metadaten abdecken. +- OpenAI Responses web_search-Regression für minimales Reasoning: `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 anschließend die Provider-Schema-Ablehnung und prüft, dass das Rohdetail in Gateway-Logs erscheint. +- MCP-Channel-Bridge (vorgefülltes 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 + stdio-MCP-Child-Teardown nach isoliertem Cron und einmaligen Subagent-Läufen): `pnpm test:docker:cron-mcp-cleanup` (Skript: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugins (Installations-/Update-Smoke für lokalen Pfad, `file:`, npm-Registry mit gehoisteten Abhängigkeiten, Git-Moving-Refs, ClawHub-Kitchen-Sink, Marketplace-Updates und Claude-Bundle-Aktivieren/Prüfen): `pnpm test:docker:plugins` (Skript: `scripts/e2e/plugins-docker.sh`) + Setzen Sie `OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, um den ClawHub-Block zu überspringen, oder überschreiben Sie das standardmäßige Kitchen-Sink-Paket/Runtime-Paar mit `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` und `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. Ohne `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL` verwendet der Test einen hermetischen lokalen ClawHub-Fixture-Server. +- Plugin-update-unchanged-Smoke: `pnpm test:docker:plugin-update` (Skript: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- Plugin-Lifecycle-Matrix-Smoke: `pnpm test:docker:plugin-lifecycle-matrix` installiert den gepackten OpenClaw-Tarball in einem leeren Container, installiert ein npm-Plugin, schaltet enable/disable um, aktualisiert es über eine lokale npm-Registry und stuft es herab, löscht den installierten Code und verifiziert anschließend, dass uninstall weiterhin veralteten Zustand entfernt, während RSS-/CPU-Metriken für jede Lifecycle-Phase protokolliert werden. +- Config-reload-metadata-Smoke: `pnpm test:docker:config-reload` (Skript: `scripts/e2e/config-reload-source-docker.sh`) +- Plugins: `pnpm test:docker:plugins` deckt Installations-/Update-Smoke für lokalen Pfad, `file:`, npm-Registry mit gehoisteten Abhängigkeiten, Git-Moving-Refs, ClawHub-Fixtures, Marketplace-Updates und Claude-Bundle-Aktivieren/Prüfen ab. `pnpm test:docker:plugin-update` deckt unverändertes Update-Verhalten für installierte Plugins ab. `pnpm test:docker:plugin-lifecycle-matrix` deckt ressourcenverfolgte npm-Plugin-Installation, Aktivieren, Deaktivieren, Upgrade, Downgrade und Deinstallation bei fehlendem Code ab. -So bauen Sie das gemeinsame funktionale Image manuell vor und verwenden es wieder: +Um das gemeinsam genutzte funktionale Image manuell vorzubauen und wiederzuverwenden: ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional: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 Built-App-Runtime 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 gemeinsam genutztes 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 gemeinsam genutzten Built-App-Runtime validieren. -Die Live-Modell-Docker-Runner binden außerdem den aktuellen Checkout schreibgeschützt ein und -stagen ihn in ein temporäres Arbeitsverzeichnis innerhalb des Containers. Dadurch bleibt das Runtime- -Image schlank, während Vitest weiterhin gegen Ihre exakte lokale Source-/Konfigurationsbasis läuft. -Der Staging-Schritt überspringt große, nur lokal relevante Caches und App-Build-Ausgaben wie +Die Live-Modell-Docker-Runner binden außerdem den aktuellen Checkout schreibgeschützt per Bind-Mount ein und +stellen ihn in einem temporären Arbeitsverzeichnis im Container bereit. Dadurch bleibt das Runtime- +Image schlank, während Vitest trotzdem gegen Ihren exakten lokalen Quellcode/Ihre lokale Konfiguration ausgeführt wird. +Der Bereitstellungsschritt überspringt große, nur lokal verwendete Caches und App-Build-Ausgaben 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 Telegram-/Discord-/usw.-Channel-Worker im Container starten. +echten Telegram-/Discord-/usw.-Kanal-Worker im Container starten. `test:docker:live-models` führt weiterhin `pnpm test:live` aus; reichen Sie daher auch -`OPENCLAW_LIVE_GATEWAY_*` durch, wenn Sie die Gateway- -Live-Abdeckung in dieser Docker-Lane eingrenzen oder ausschließen müssen. -`test:docker:openwebui` ist ein höherwertiger Kompatibilitäts-Smoke: Er startet einen +`OPENCLAW_LIVE_GATEWAY_*` durch, wenn Sie Live-Gateway-Abdeckung in dieser +Docker-Lane eingrenzen oder ausschließen müssen. +`test:docker:openwebui` ist ein höherstufiger Kompatibilitäts-Smoke-Test: Er startet einen OpenClaw-Gateway-Container mit aktivierten OpenAI-kompatiblen HTTP-Endpunkten, -startet einen gepinnten Open-WebUI-Container gegen dieses Gateway, meldet sich über -Open WebUI an, überprüft, dass `/api/models` `openclaw/default` bereitstellt, und sendet dann eine -echte Chat-Anfrage über den `/api/chat/completions`-Proxy von Open WebUI. +startet einen gepinnten Open WebUI-Container gegen dieses Gateway, meldet sich über +Open WebUI an, prüft, dass `/api/models` `openclaw/default` bereitstellt, und sendet dann eine +echte Chat-Anfrage über Open WebUIs Proxy `/api/chat/completions`. Der erste Lauf kann spürbar langsamer sein, weil Docker möglicherweise das -Open-WebUI-Image ziehen muss und Open WebUI seine eigene Cold-Start-Einrichtung abschließen muss. -Diese Lane erwartet einen nutzbaren Live-Modellschlüssel, und `OPENCLAW_PROFILE_FILE` -(standardmäßig `~/.profile`) ist der primäre Weg, ihn in Dockerisierten Läufen bereitzustellen. +Open WebUI-Image laden muss und Open WebUI möglicherweise seine eigene Cold-Start-Einrichtung abschließen muss. +Diese Lane erwartet einen nutzbaren Live-Modell-Key, und `OPENCLAW_PROFILE_FILE` +(standardmäßig `~/.profile`) ist der primäre Weg, ihn in Docker-basierten Läufen bereitzustellen. Erfolgreiche Läufe geben eine kleine JSON-Nutzlast wie `{ "ok": true, "model": "openclaw/default", ... }` aus. `test:docker:mcp-channels` ist absichtlich deterministisch und benötigt kein -echtes Telegram-, Discord- oder iMessage-Konto. Es bootet einen vorbefüllten Gateway- +echtes Telegram-, Discord- oder iMessage-Konto. Es startet einen vorbefüllten Gateway- Container, startet einen zweiten Container, der `openclaw mcp serve` spawnt, und -überprüft dann geroutete Konversationserkennung, Transkript-Lesezugriffe, Anhangsmetadaten, -Live-Event-Queue-Verhalten, Routing für ausgehenden Versand sowie Claude-artige Channel- und -Berechtigungsbenachrichtigungen über die echte stdio-MCP-Bridge. Die Benachrichtigungsprüfung -inspiziert die rohen stdio-MCP-Frames direkt, sodass der Smoke validiert, was die -Bridge tatsächlich ausgibt, und nicht nur, was ein bestimmtes Client-SDK zufällig sichtbar macht. +prüft dann geroutete Konversationserkennung, Transkript-Lesezugriffe, Anhangsmetadaten, +Verhalten der Live-Ereignisqueue, Routing ausgehender Sendungen sowie Kanal- und +Berechtigungsbenachrichtigungen im Claude-Stil über die echte stdio-MCP-Bridge. Die Benachrichtigungsprüfung +inspiziert die rohen stdio-MCP-Frames direkt, sodass der Smoke-Test validiert, was die +Bridge tatsächlich ausgibt, nicht nur das, was ein bestimmtes Client-SDK zufällig sichtbar macht. `test:docker:pi-bundle-mcp-tools` ist deterministisch und benötigt keinen Live- -Modellschlüssel. Es baut das Repo-Docker-Image, startet einen echten stdio-MCP-Probe-Server +Modell-Key. Es baut das Repo-Docker-Image, startet einen echten stdio-MCP-Probe-Server im Container, materialisiert diesen Server über die eingebettete Pi-Bundle- -MCP-Runtime, führt das Tool aus und überprüft anschließend, dass `coding` und `messaging` +MCP-Runtime, führt das Tool aus und prüft dann, dass `coding` und `messaging` `bundle-mcp`-Tools behalten, während `minimal` und `tools.deny: ["bundle-mcp"]` sie herausfiltern. -`test:docker:cron-mcp-cleanup` ist deterministisch und benötigt keinen Live-Modellschlüssel. -Es startet ein vorbefülltes Gateway mit einem echten stdio-MCP-Probe-Server, führt einen -isolierten Cron-Turn und einen `/subagents spawn`-One-Shot-Child-Turn aus und überprüft dann, +`test:docker:cron-mcp-cleanup` ist deterministisch und benötigt keinen Live-Modell- +Key. Es startet ein vorbefülltes Gateway mit einem echten stdio-MCP-Probe-Server, führt einen +isolierten Cron-Turn und einen `/subagents spawn`-One-Shot-Child-Turn aus und prüft dann, dass der MCP-Child-Prozess nach jedem Lauf beendet wird. -Manueller ACP-Plain-Language-Thread-Smoke (nicht CI): +Manueller ACP-Plain-Language-Thread-Smoke-Test (nicht CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Behalten Sie dieses Skript für Regression-/Debug-Workflows. Es kann erneut für die Validierung des ACP-Thread-Routings benötigt werden, löschen Sie es daher nicht. +- Behalten Sie dieses Skript für Regressions-/Debug-Workflows. Es kann für die Validierung des ACP-Thread-Routings erneut benötigt werden; löschen Sie es daher nicht. -Nützliche Env Vars: +Nützliche Umgebungsvariablen: -- `OPENCLAW_CONFIG_DIR=...` (Standard: `~/.openclaw`), eingebunden nach `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...` (Standard: `~/.openclaw/workspace`), eingebunden nach `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (Standard: `~/.profile`), eingebunden nach `/home/node/.profile` und vor der Testausführung gesourct -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, um nur Env Vars zu überprüfen, die aus `OPENCLAW_PROFILE_FILE` gesourct wurden, mit temporären Konfigurations-/Workspace-Verzeichnissen und ohne externe CLI-Auth-Mounts -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (Standard: `~/.cache/openclaw/docker-cli-tools`), eingebunden nach `/home/node/.npm-global` für gecachte CLI-Installationen innerhalb von Docker -- Externe CLI-Auth-Verzeichnisse/-Dateien unter `$HOME` werden schreibgeschützt unter `/host-auth...` eingebunden und anschließend vor Testbeginn nach `/home/node/...` kopiert +- `OPENCLAW_CONFIG_DIR=...` (Standard: `~/.openclaw`) wird nach `/home/node/.openclaw` gemountet +- `OPENCLAW_WORKSPACE_DIR=...` (Standard: `~/.openclaw/workspace`) wird nach `/home/node/.openclaw/workspace` gemountet +- `OPENCLAW_PROFILE_FILE=...` (Standard: `~/.profile`) wird nach `/home/node/.profile` gemountet und vor dem Ausführen von Tests gesourct +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, um nur Umgebungsvariablen zu prüfen, die aus `OPENCLAW_PROFILE_FILE` gesourct wurden, mit temporären Konfigurations-/Workspace-Verzeichnissen und ohne externe CLI-Auth-Mounts +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (Standard: `~/.cache/openclaw/docker-cli-tools`) wird für gecachte CLI-Installationen innerhalb von Docker nach `/home/node/.npm-global` gemountet +- 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 - Manuell überschreiben mit `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` oder einer kommagetrennten 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 `openclaw:local-live`-Image für Wiederholungsläufe wiederzuverwenden, die keinen Neubau benötigen -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um sicherzustellen, dass Credentials aus dem Profilspeicher stammen (nicht aus Env) -- `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-Check-Prompt zu überschreiben -- `OPENWEBUI_IMAGE=...`, um das gepinnte Open-WebUI-Image-Tag zu überschreiben +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, um ein vorhandenes `openclaw:local-live`-Image für erneute Läufe wiederzuverwenden, die keinen Neubau benötigen +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um sicherzustellen, dass Zugangsdaten aus dem Profil-Store (nicht aus der Umgebung) stammen +- `OPENCLAW_OPENWEBUI_MODEL=...`, um das Modell auszuwählen, das das Gateway für den Open WebUI-Smoke-Test bereitstellt +- `OPENCLAW_OPENWEBUI_PROMPT=...`, um den vom Open WebUI-Smoke-Test verwendeten Nonce-Prüf-Prompt zu überschreiben +- `OPENWEBUI_IMAGE=...`, um das gepinnte Open WebUI-Image-Tag zu überschreiben -## Docs-Plausibilitätsprüfung +## Docs-Sanity Führen Sie nach Docs-Änderungen Docs-Prüfungen aus: `pnpm check:docs`. -Führen Sie die vollständige Mintlify-Anker-Validierung aus, wenn Sie auch In-Page-Heading-Prüfungen benötigen: `pnpm docs:check-links:anchors`. +Führen Sie die vollständige Mintlify-Ankervalidierung aus, wenn Sie auch In-Page-Heading-Prüfungen benötigen: `pnpm docs:check-links:anchors`. ## Offline-Regression (CI-sicher) -Dies sind Regressionen der „echten Pipeline“ ohne echte Provider: +Dies sind „echte Pipeline“-Regressionen ohne echte Provider: -- Gateway-Tool-Calling (Mock 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-Tool-Aufrufe (Mock-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-Wizard (WS `wizard.start`/`wizard.next`, schreibt Konfiguration + Auth erzwungen): `src/gateway/gateway.test.ts` (Fall: "runs wizard over ws and writes auth token config") ## Agent-Zuverlässigkeits-Evals (Skills) Wir haben bereits einige CI-sichere Tests, die sich wie „Agent-Zuverlässigkeits-Evals“ verhalten: -- Mock-Tool-Calling über das echte Gateway + Agent-Loop (`src/gateway/gateway.test.ts`). -- End-to-End-Wizard-Flows, die Session-Verkabelung und Konfigurationsauswirkungen validieren (`src/gateway/gateway.test.ts`). +- Mock-Tool-Aufrufe über das echte Gateway + Agent-Loop (`src/gateway/gateway.test.ts`). +- End-to-End-Wizard-Flows, die Session-Verdrahtung und Konfigurationseffekte validieren (`src/gateway/gateway.test.ts`). Was für Skills noch fehlt (siehe [Skills](/de/tools/skills)): -- **Entscheidungsfindung:** Wenn Skills im Prompt aufgelistet sind, wählt der Agent die richtige Skill aus (oder vermeidet irrelevante)? +- **Entscheidungslogik:** Wenn Skills im Prompt aufgeführt sind, wählt der Agent den richtigen Skill (oder vermeidet irrelevante)? - **Compliance:** Liest der Agent `SKILL.md` vor der Verwendung und befolgt erforderliche Schritte/Argumente? -- **Workflow-Verträge:** Mehrturn-Szenarien, die Tool-Reihenfolge, Übernahme der Sitzungshistorie und Sandbox-Grenzen prüfen. +- **Workflow-Verträge:** Mehrstufige Szenarien, die Tool-Reihenfolge, Übernahme des Sitzungsverlaufs und Sandbox-Grenzen prüfen. Zukünftige Evals sollten zuerst deterministisch bleiben: -- Ein Szenario-Runner mit Mock-Providern, der Tool-Aufrufe + Reihenfolge, Skill-Dateilesezugriffe und Session-Verkabelung prüft. -- Eine kleine Suite skill-fokussierter Szenarien (verwenden vs. vermeiden, Gating, Prompt Injection). +- Ein Szenario-Runner mit Mock-Providern, um Tool-Aufrufe + Reihenfolge, Skill-Dateilesezugriffe und Session-Verdrahtung zu prüfen. +- Eine kleine Suite Skill-fokussierter Szenarien (verwenden vs. vermeiden, Gating, Prompt Injection). - Optionale Live-Evals (Opt-in, env-gated) erst, nachdem die CI-sichere Suite vorhanden ist. -## Contract-Tests (Plugin- und Channel-Form) +## Vertragstests (Plugin- und Kanalform) -Contract-Tests überprüfen, dass jedes registrierte Plugin und jeder Channel seinem -Interface-Vertrag entspricht. Sie iterieren über alle gefundenen Plugins und führen eine Suite von -Form- und Verhaltensassertions aus. Die standardmäßige `pnpm test`-Unit-Lane überspringt diese -gemeinsamen Seam- und Smoke-Dateien absichtlich; führen Sie die Contract-Befehle explizit aus, -wenn Sie gemeinsame Channel- oder Provider-Oberflächen berühren. +Vertragstests prüfen, dass jedes registrierte Plugin und jeder registrierte Kanal seinem +Schnittstellenvertrag entspricht. Sie iterieren über alle entdeckten Plugins und führen eine Suite von +Form- und Verhaltensassertions aus. Die standardmäßige `pnpm test`-Unit-Lane überspringt diese gemeinsam genutzten Seam- und Smoke-Dateien absichtlich; führen Sie die Vertragsbefehle explizit aus, +wenn Sie gemeinsam genutzte Kanal- oder Provider-Oberflächen berühren. ### Befehle -- Alle Contracts: `pnpm test:contracts` -- Nur Channel-Contracts: `pnpm test:contracts:channels` -- Nur Provider-Contracts: `pnpm test:contracts:plugins` +- Alle Verträge: `pnpm test:contracts` +- Nur Kanalverträge: `pnpm test:contracts:channels` +- Nur Provider-Verträge: `pnpm test:contracts:plugins` -### Channel-Contracts +### Kanalverträge -Befindet sich in `src/channels/plugins/contracts/*.contract.test.ts`: +Zu finden in `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Grundlegende Plugin-Form (ID, Name, Capabilities) +- **plugin** - Grundlegende Plugin-Form (ID, Name, Fähigkeiten) - **setup** - Setup-Wizard-Vertrag - **session-binding** - Session-Binding-Verhalten -- **outbound-payload** - Nachrichten-Payload-Struktur -- **inbound** - Eingehende Nachrichtenverarbeitung -- **actions** - Channel-Action-Handler +- **outbound-payload** - Struktur der Nachrichten-Nutzlast +- **inbound** - Verarbeitung eingehender Nachrichten +- **actions** - Kanal-Aktionshandler - **threading** - Thread-ID-Verarbeitung - **directory** - Directory-/Roster-API - **group-policy** - Durchsetzung von Gruppenrichtlinien -### Provider-Status-Contracts +### Provider-Statusverträge -Befindet sich in `src/plugins/contracts/*.contract.test.ts`. +Zu finden in `src/plugins/contracts/*.contract.test.ts`. -- **status** - Channel-Status-Probes +- **status** - Kanalstatus-Probes - **registry** - Plugin-Registry-Form -### Provider-Contracts +### Provider-Verträge -Befindet sich in `src/plugins/contracts/*.contract.test.ts`: +Zu finden in `src/plugins/contracts/*.contract.test.ts`: - **auth** - Auth-Flow-Vertrag - **auth-choice** - Auth-Auswahl/Selektion - **catalog** - Modellkatalog-API -- **discovery** - Plugin-Discovery +- **discovery** - Plugin-Erkennung - **loader** - Plugin-Laden - **runtime** - Provider-Runtime -- **shape** - Plugin-Form/-Interface +- **shape** - Plugin-Form/Schnittstelle - **wizard** - Setup-Wizard ### Wann ausführen - Nach Änderungen an plugin-sdk-Exports oder Subpaths -- Nach dem Hinzufügen oder Ändern eines Channel- oder Provider-Plugins -- Nach Refactorings an Plugin-Registrierung oder Discovery +- Nach dem Hinzufügen oder Ändern eines Kanal- oder Provider-Plugins +- Nach Refactorings der Plugin-Registrierung oder -Erkennung -Contract-Tests laufen in CI und benötigen keine echten API-Schlüssel. +Vertragstests laufen in CI und benötigen keine echten API-Keys. -## Regressionen hinzufügen (Leitlinien) +## Regressionen hinzufügen (Anleitung) Wenn Sie ein Provider-/Modellproblem beheben, das live entdeckt wurde: -- Fügen Sie nach Möglichkeit eine CI-sichere Regression hinzu (Mock-/Stub-Provider oder Erfassen der exakten Request-Shape-Transformation) -- Wenn es inhärent nur live testbar ist (Rate Limits, Auth-Richtlinien), halten Sie den Live-Test eng begrenzt und per Env Vars opt-in -- Zielen Sie bevorzugt auf die kleinste Schicht, die den Bug abfängt: - - Bug bei Provider-Request-Konvertierung/-Replay → direkter Modelltest - - Bug in Gateway-Session-/History-/Tool-Pipeline → Gateway-Live-Smoke oder CI-sicherer Gateway-Mock-Test +- Fügen Sie nach Möglichkeit eine CI-sichere Regression hinzu (Mock-/Stub-Provider oder die exakte Request-Shape-Transformation erfassen) +- Wenn es grundsätzlich nur live prüfbar ist (Rate Limits, Auth-Richtlinien), halten Sie den Live-Test eng und per Umgebungsvariablen Opt-in +- Zielen Sie bevorzugt auf die kleinste Schicht, die den Fehler erfasst: + - Fehler in Provider-Request-Konvertierung/-Replay → direkter Modelltest + - Fehler in Gateway-Session-/History-/Tool-Pipeline → Gateway-Live-Smoke oder CI-sicherer Gateway-Mock-Test - SecretRef-Traversal-Guardrail: - - `src/secrets/exec-secret-ref-id-parity.test.ts` leitet pro SecretRef-Klasse ein gesampeltes Ziel aus Registry-Metadaten (`listSecretTargetRegistryEntries()`) ab und assertet dann, dass Exec-IDs mit Traversal-Segmenten abgelehnt werden. + - `src/secrets/exec-secret-ref-id-parity.test.ts` leitet ein gesampeltes Ziel pro SecretRef-Klasse aus Registry-Metadaten (`listSecretTargetRegistryEntries()`) ab und stellt dann sicher, dass Exec-IDs mit Traversal-Segmenten abgelehnt werden. - Wenn Sie eine neue `includeInPlan`-SecretRef-Zielfamilie in `src/secrets/target-registry-data.ts` 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 können. ## Verwandt diff --git a/docs/de/install/updating.md b/docs/de/install/updating.md index 8f8380617..394f52153 100644 --- a/docs/de/install/updating.md +++ b/docs/de/install/updating.md @@ -2,28 +2,28 @@ read_when: - OpenClaw aktualisieren - Nach einem Update funktioniert etwas nicht mehr -summary: OpenClaw sicher aktualisieren (globale Installation oder Quellcode), plus Rollback-Strategie +summary: OpenClaw sicher aktualisieren (globale Installation oder Quellcode) sowie Rollback-Strategie title: Aktualisieren x-i18n: - generated_at: "2026-05-03T21:35:13Z" + generated_at: "2026-05-04T06:42:31Z" model: gpt-5.5 provider: openai - source_hash: f9e26ea71748dfd1573cdca01126bf29ebc56be56eac604e2b6a009b463820d1 + source_hash: 3c9ff1d70d74f45efea3c148718e5cbc74001ce3d924b760edc4d68622d23714 source_path: install/updating.md workflow: 16 --- -Halten Sie OpenClaw aktuell. +Halten Sie OpenClaw auf dem neuesten Stand. ## Empfohlen: `openclaw update` -Der schnellste Weg zum Aktualisieren. Der Befehl erkennt Ihren Installationstyp (npm oder git), ruft die neueste Version ab, führt `openclaw doctor` aus und startet den Gateway neu. +Der schnellste Weg zum Aktualisieren. Es erkennt Ihren Installationstyp (npm oder git), ruft die neueste Version ab, führt `openclaw doctor` aus und startet den Gateway neu. ```bash openclaw update ``` -So wechseln Sie Kanäle oder zielen auf eine bestimmte Version ab: +So wechseln Sie Kanäle oder wählen eine bestimmte Version aus: ```bash openclaw update --channel beta @@ -32,22 +32,22 @@ openclaw update --tag main openclaw update --dry-run # preview without applying ``` -`openclaw update` akzeptiert kein `--verbose`. Für Aktualisierungsdiagnosen verwenden Sie +`openclaw update` akzeptiert `--verbose` nicht. Verwenden Sie für Aktualisierungsdiagnosen `--dry-run`, um die geplanten Aktionen vorab anzuzeigen, `--json` für strukturierte Ergebnisse oder `openclaw update status --json`, um den Kanal- und Verfügbarkeitsstatus zu prüfen. Der Installer hat ein eigenes `--verbose`-Flag, aber dieses Flag ist nicht Teil von `openclaw update`. -`--channel beta` bevorzugt Beta, aber die Laufzeitumgebung fällt auf Stable/Latest zurück, wenn -das Beta-Tag fehlt oder älter als das neueste stabile Release ist. Verwenden Sie `--tag beta`, -wenn Sie das rohe npm-Beta-dist-tag für eine einmalige Paketaktualisierung möchten. +`--channel beta` bevorzugt Beta, aber die Runtime fällt auf Stable/Latest zurück, wenn +der Beta-Tag fehlt oder älter als das neueste stabile Release ist. Verwenden Sie `--tag beta`, +wenn Sie den rohen npm-Beta-`dist-tag` für eine einmalige Paketaktualisierung möchten. -Siehe [Entwicklungskanäle](/de/install/development-channels) für Kanal-Semantik. +Siehe [Entwicklungskanäle](/de/install/development-channels) für die Kanalsemantik. ## Zwischen npm- und git-Installationen wechseln Verwenden Sie Kanäle, wenn Sie den Installationstyp ändern möchten. Der Updater behält Ihren -Status, Ihre Konfiguration, Zugangsdaten und den Workspace in `~/.openclaw` bei; er ändert nur, +Status, Ihre Konfiguration, Anmeldedaten und Ihren Arbeitsbereich in `~/.openclaw`; er ändert nur, welche OpenClaw-Codeinstallation die CLI und der Gateway verwenden. ```bash @@ -58,16 +58,16 @@ openclaw update --channel dev openclaw update --channel stable ``` -Führen Sie den Befehl zuerst mit `--dry-run` aus, um den genauen Wechsel des Installationsmodus vorab anzuzeigen: +Führen Sie zuerst `--dry-run` aus, um den exakten Wechsel des Installationsmodus vorab anzuzeigen: ```bash openclaw update --channel dev --dry-run openclaw update --channel stable --dry-run ``` -Der Kanal `dev` stellt einen git-Checkout sicher, baut ihn und installiert die globale CLI +Der `dev`-Kanal stellt ein git-Checkout sicher, baut es und installiert die globale CLI aus diesem Checkout. Die Kanäle `stable` und `beta` verwenden Paketinstallationen. Wenn der -Gateway bereits installiert ist, aktualisiert `openclaw update` die Service-Metadaten +Gateway bereits installiert ist, aktualisiert `openclaw update` die Servicemetadaten und startet ihn neu, sofern Sie nicht `--no-restart` übergeben. ## Alternative: Installer erneut ausführen @@ -76,19 +76,19 @@ und startet ihn neu, sofern Sie nicht `--no-restart` übergeben. curl -fsSL https://openclaw.ai/install.sh | bash ``` -Fügen Sie `--no-onboard` hinzu, um das Onboarding zu überspringen. Um über den -Installer einen bestimmten Installationstyp zu erzwingen, übergeben Sie `--install-method git --no-onboard` oder +Fügen Sie `--no-onboard` hinzu, um das Onboarding zu überspringen. Um einen bestimmten Installationstyp über +den Installer zu erzwingen, übergeben Sie `--install-method git --no-onboard` oder `--install-method npm --no-onboard`. -Wenn `openclaw update` nach der Phase der npm-Paketinstallation fehlschlägt, führen Sie den -Installer erneut aus. Der Installer ruft nicht den alten Updater auf; er führt die globale +Wenn `openclaw update` nach der npm-Paketinstallationsphase fehlschlägt, führen Sie den +Installer erneut aus. Der Installer ruft den alten Updater nicht auf; er führt die globale Paketinstallation direkt aus und kann eine teilweise aktualisierte npm-Installation wiederherstellen. ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm ``` -Um die Wiederherstellung auf eine bestimmte Version oder ein dist-tag festzulegen, fügen Sie `--version` hinzu: +Um die Wiederherstellung auf eine bestimmte Version oder einen bestimmten dist-tag festzulegen, fügen Sie `--version` hinzu: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version @@ -100,9 +100,14 @@ curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --ve npm i -g openclaw@latest ``` -Wenn `openclaw update` eine globale npm-Installation verwaltet, installiert es das Ziel zuerst in -ein temporäres npm-Präfix, prüft das paketierte `dist`-Inventar und tauscht dann -den sauberen Paketbaum in das echte globale Präfix ein. Dadurch wird vermieden, dass npm ein +Bevorzugen Sie `openclaw update` für beaufsichtigte Installationen, da es den +Paketwechsel mit dem laufenden Gateway-Service koordinieren kann. Wenn Sie manuell aktualisieren, während ein +verwalteter Gateway läuft, starten Sie den Gateway direkt nach Abschluss des Paketmanagers neu, +damit der alte Prozess nicht weiter aus ersetzten Paketdateien bereitstellt. + +Wenn `openclaw update` eine globale npm-Installation verwaltet, installiert es das Ziel zunächst in +ein temporäres npm-Präfix, prüft das gepackte `dist`-Inventar und tauscht dann +den sauberen Paketbaum in das echte globale Präfix. Dadurch wird vermieden, dass npm ein neues Paket über veraltete Dateien aus dem alten Paket legt. Wenn der Installationsbefehl fehlschlägt, versucht OpenClaw es einmal erneut mit `--omit=optional`. Dieser erneute Versuch hilft Hosts, auf denen native optionale Abhängigkeiten nicht kompiliert werden können, während der ursprüngliche Fehler sichtbar bleibt, @@ -116,25 +121,25 @@ pnpm add -g openclaw@latest bun add -g openclaw@latest ``` -### Fortgeschrittene npm-Installationsthemen +### Erweiterte Themen zur npm-Installation - OpenClaw behandelt paketierte globale Installationen zur Laufzeit als schreibgeschützt, selbst wenn das globale Paketverzeichnis für den aktuellen Benutzer beschreibbar ist. Plugin-Paketinstallationen liegen in OpenClaw-eigenen npm/git-Wurzeln unter dem Benutzerkonfigurationsverzeichnis, und der Gateway-Start verändert den OpenClaw-Paketbaum nicht. + OpenClaw behandelt gepackte globale Installationen zur Laufzeit als schreibgeschützt, selbst wenn das globale Paketverzeichnis für den aktuellen Benutzer beschreibbar ist. Plugin-Paketinstallationen liegen in OpenClaw-eigenen npm/git-Wurzeln unter dem Benutzerkonfigurationsverzeichnis, und der Gateway-Start verändert den OpenClaw-Paketbaum nicht. - Einige Linux-npm-Setups installieren globale Pakete unter root-eigenen Verzeichnissen wie `/usr/lib/node_modules/openclaw`. OpenClaw unterstützt dieses Layout, weil Befehle zum Installieren/Aktualisieren von Plugins außerhalb dieses globalen Paketverzeichnisses schreiben. + Einige Linux-npm-Setups installieren globale Pakete unter root-eigenen Verzeichnissen wie `/usr/lib/node_modules/openclaw`. OpenClaw unterstützt dieses Layout, da Befehle zum Installieren/Aktualisieren von Plugins außerhalb dieses globalen Paketverzeichnisses schreiben. - Gewähren Sie OpenClaw Schreibzugriff auf seine Konfigurations-/Status-Wurzeln, damit explizite Plugin-Installationen, Plugin-Aktualisierungen und Doctor-Bereinigungen ihre Änderungen dauerhaft speichern können: + Geben Sie OpenClaw Schreibzugriff auf seine Konfigurations-/Status-Wurzeln, damit explizite Plugin-Installationen, Plugin-Aktualisierungen und Doctor-Bereinigungen ihre Änderungen speichern können: ```ini ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp ``` - - Vor Paketaktualisierungen und expliziten Plugin-Installationen versucht OpenClaw eine bestmögliche Speicherplatzprüfung für das Zielvolume. Wenig Speicherplatz erzeugt eine Warnung mit dem geprüften Pfad, blockiert die Aktualisierung aber nicht, weil Dateisystemkontingente, Snapshots und Netzwerkvolumes sich nach der Prüfung ändern können. Die tatsächliche Paketmanager-Installation und die Nachinstallationsprüfung bleiben maßgeblich. + + Vor Paketaktualisierungen und expliziten Plugin-Installationen versucht OpenClaw eine bestmögliche Speicherplatzprüfung für das Zielvolume. Wenig Speicherplatz erzeugt eine Warnung mit dem geprüften Pfad, blockiert die Aktualisierung aber nicht, da sich Dateisystemquotas, Snapshots und Netzwerkvolumes nach der Prüfung ändern können. Die tatsächliche Paketmanager-Installation und die Nachinstallationsprüfung bleiben maßgeblich. @@ -156,23 +161,23 @@ Der Auto-Updater ist standardmäßig deaktiviert. Aktivieren Sie ihn in `~/.open } ``` -| Kanal | Verhalten | -| -------- | ------------------------------------------------------------------------------------------------------------------ | +| Kanal | Verhalten | +| -------- | ----------------------------------------------------------------------------------------------------------------------- | | `stable` | Wartet `stableDelayHours` und wendet dann mit deterministischem Jitter über `stableJitterHours` an (gestaffelter Rollout). | -| `beta` | Prüft alle `betaCheckIntervalHours` (Standard: stündlich) und wendet sofort an. | -| `dev` | Keine automatische Anwendung. Verwenden Sie `openclaw update` manuell. | +| `beta` | Prüft alle `betaCheckIntervalHours` (Standard: stündlich) und wendet sofort an. | +| `dev` | Keine automatische Anwendung. Verwenden Sie `openclaw update` manuell. | Der Gateway protokolliert beim Start außerdem einen Aktualisierungshinweis (deaktivieren mit `update.checkOnStart: false`). -Für Downgrade oder Wiederherstellung nach einem Vorfall setzen Sie `OPENCLAW_NO_AUTO_UPDATE=1` in der Gateway-Umgebung, um automatische Anwendungen auch dann zu blockieren, wenn `update.auto.enabled` konfiguriert ist. Aktualisierungshinweise beim Start können weiterhin ausgeführt werden, sofern `update.checkOnStart` nicht ebenfalls deaktiviert ist. +Für Downgrades oder Wiederherstellung nach Vorfällen setzen Sie `OPENCLAW_NO_AUTO_UPDATE=1` in der Gateway-Umgebung, um automatische Anwendungen auch dann zu blockieren, wenn `update.auto.enabled` konfiguriert ist. Aktualisierungshinweise beim Start können weiterhin ausgeführt werden, sofern `update.checkOnStart` nicht ebenfalls deaktiviert ist. Paketmanager-Aktualisierungen, die über den Live-Gateway-Control-Plane-Handler angefordert werden, -erzwingen nach dem Pakettausch einen nicht aufgeschobenen Aktualisierungsneustart ohne Cooldown. Dadurch -bleibt kein alter In-Memory-Prozess lange genug bestehen, um Chunks verzögert aus einem -Paketbaum zu laden, der bereits ersetzt wurde. Shell-`openclaw update` -bleibt der bevorzugte Pfad für überwachte Installationen, weil es den Service rund um die Aktualisierung stoppen und +erzwingen nach dem Paketwechsel einen nicht aufgeschobenen Aktualisierungsneustart ohne Cooldown. Dadurch +wird vermieden, dass ein alter In-Memory-Prozess lange genug bestehen bleibt, um Chunks verzögert +aus einem Paketbaum zu laden, der bereits ersetzt wurde. Shell-`openclaw update` +bleibt der bevorzugte Pfad für beaufsichtigte Installationen, da es den Service rund um die Aktualisierung stoppen und neu starten kann. -## Nach dem Aktualisieren +## Nach der Aktualisierung @@ -182,7 +187,7 @@ neu starten kann. openclaw doctor ``` -Migriert die Konfiguration, prüft DM-Richtlinien und prüft den Zustand des Gateway. Details: [Doctor](/de/gateway/doctor) +Migriert Konfiguration, prüft DM-Richtlinien und kontrolliert den Gateway-Zustand. Details: [Doctor](/de/gateway/doctor) ### Gateway neu starten @@ -212,7 +217,7 @@ openclaw gateway restart `npm view openclaw version` zeigt die aktuell veröffentlichte Version. -### Commit festlegen (Quelle) +### Commit festlegen (Quellcode) ```bash git fetch origin @@ -226,7 +231,7 @@ Zurück zur neuesten Version: `git checkout main && git pull`. ## Wenn Sie feststecken - Führen Sie `openclaw doctor` erneut aus und lesen Sie die Ausgabe sorgfältig. -- Bei `openclaw update --channel dev` auf Quellcode-Checkouts bootstrapt der Updater `pnpm` bei Bedarf automatisch. Wenn Sie einen pnpm/corepack-Bootstrap-Fehler sehen, installieren Sie `pnpm` manuell (oder aktivieren Sie `corepack` erneut) und führen Sie die Aktualisierung erneut aus. +- Bei `openclaw update --channel dev` auf Quellcode-Checkouts bootstrapt der Updater `pnpm` bei Bedarf automatisch. Wenn Sie einen pnpm/corepack-Bootstrap-Fehler sehen, installieren Sie `pnpm` manuell (oder aktivieren Sie `corepack` wieder) und führen Sie die Aktualisierung erneut aus. - Prüfen: [Fehlerbehebung](/de/gateway/troubleshooting) - Fragen Sie in Discord: [https://discord.gg/clawd](https://discord.gg/clawd) diff --git a/docs/de/plugins/google-meet.md b/docs/de/plugins/google-meet.md index c09ca54c4..7f59f3177 100644 --- a/docs/de/plugins/google-meet.md +++ b/docs/de/plugins/google-meet.md @@ -2,53 +2,54 @@ read_when: - Sie möchten, dass ein OpenClaw-Agent an einem Google Meet-Anruf teilnimmt - Sie möchten, dass ein OpenClaw-Agent einen neuen Google Meet-Anruf erstellt - - Sie konfigurieren Chrome, Chrome-Node oder Twilio als Google Meet-Transport -summary: 'Google Meet-Plugin: expliziten Meet-URLs über Chrome oder Twilio mit Echtzeit-Sprachvorgaben beitreten' -title: Google Meet Plugin + - Sie konfigurieren Chrome, Chrome Node oder Twilio als Google Meet-Transport +summary: 'Google Meet Plugin: Expliziten Meet-URLs über Chrome oder Twilio mit Standardeinstellungen für Agent-Talkback beitreten' +title: Google Meet-Plugin x-i18n: - generated_at: "2026-05-04T02:24:51Z" + generated_at: "2026-05-04T06:43:10Z" model: gpt-5.5 provider: openai - source_hash: 77ab70d27d47bcc037144c7c6cfad6f93f307355b6ebcf3ee75c85b96a24af2f + source_hash: 4268ad895bbf83d649b9571c0888c27eb982ad9710dfb408f22f7818cdc5dbcb source_path: plugins/google-meet.md workflow: 16 --- -Google Meet-Teilnehmerunterstützung für OpenClaw — das Plugin ist bewusst explizit gestaltet: +Google Meet-Teilnehmerunterstützung für OpenClaw — das Plugin ist absichtlich explizit gestaltet: - Es tritt nur einer expliziten `https://meet.google.com/...`-URL bei. - Es kann über die Google Meet API einen neuen Meet-Raum erstellen und dann der zurückgegebenen URL beitreten. -- `realtime`-Sprache ist der Standardmodus. -- Realtime-Sprache kann bei Bedarf für tieferes Reasoning oder Tools an den vollständigen - OpenClaw-Agenten zurückrufen. -- Agenten wählen das Beitrittsverhalten mit `mode`: Verwenden Sie `realtime` für live - Zuhören/Rücksprechen oder `transcribe`, um dem Browser beizutreten/ihn zu steuern, ohne die - Realtime-Sprachbrücke. +- `agent` ist der Standard-Rücksprechmodus: Die Echtzeittranskription hört zu, der + konfigurierte OpenClaw-Agent antwortet, und reguläres OpenClaw TTS spricht in Meet. +- `bidi` bleibt als Fallback-Modus für das direkte Echtzeit-Sprachmodell verfügbar. +- Agenten wählen das Beitrittsverhalten mit `mode`: Verwenden Sie `agent` für + Live-Zuhören/Rücksprechen, `bidi` als direkten Echtzeit-Sprach-Fallback oder `transcribe`, + um den Browser ohne Rücksprechbrücke beizutreten/zu steuern. - Auth startet als persönliches Google OAuth oder als bereits angemeldetes Chrome-Profil. -- Es gibt keine automatische Zustimmungshinweis-Ansage. +- Es gibt keine automatische Einwilligungsankündigung. - Das Standard-Audio-Backend von Chrome ist `BlackHole 2ch`. - Chrome kann lokal oder auf einem gekoppelten Node-Host ausgeführt werden. - Twilio akzeptiert eine Einwahlnummer plus optionale PIN oder DTMF-Sequenz; es - kann keine Meet-URL direkt anwählen. -- Der CLI-Befehl ist `googlemeet`; `meet` ist für umfassendere Agent- - Telekonferenz-Workflows reserviert. + kann eine Meet-URL nicht direkt wählen. +- Der CLI-Befehl ist `googlemeet`; `meet` ist für umfassendere + Agent-Telekonferenz-Workflows reserviert. ## Schnellstart -Installieren Sie die lokalen Audio-Abhängigkeiten und konfigurieren Sie einen Backend-Realtime-Sprach- -Provider. OpenAI ist der Standard; Google Gemini Live funktioniert ebenfalls mit -`realtime.provider: "google"`: +Installieren Sie die lokalen Audio-Abhängigkeiten und konfigurieren Sie einen +Echtzeittranskriptions-Provider plus reguläres OpenClaw TTS. OpenAI ist der +Standard-Transkriptions-Provider; Google Gemini Live funktioniert ebenfalls als +separater `bidi`-Sprach-Fallback mit `realtime.voiceProvider: "google"`: ```bash brew install blackhole-2ch sox export OPENAI_API_KEY=sk-... -# or +# only needed when realtime.voiceProvider is "google" for bidi mode export GEMINI_API_KEY=... ``` -`blackhole-2ch` installiert das virtuelle Audiogerät `BlackHole 2ch`. Der Installer von Homebrew -erfordert einen Neustart, bevor macOS das Gerät bereitstellt: +`blackhole-2ch` installiert das virtuelle Audiogerät `BlackHole 2ch`. Der +Homebrew-Installer erfordert einen Neustart, bevor macOS das Gerät bereitstellt: ```bash sudo reboot @@ -82,33 +83,35 @@ Prüfen Sie die Einrichtung: openclaw googlemeet setup ``` -Die Setup-Ausgabe ist so gedacht, dass sie für Agenten lesbar und modusbewusst ist. Sie meldet Chrome- -Profil, Node-Pinning und, für Realtime-Chrome-Beitritte, die BlackHole/SoX-Audio- -Brücke sowie verzögerte Prüfungen der Realtime-Einführung. Für Nur-Beobachten-Beitritte prüfen Sie denselben -Transport mit `--mode transcribe`; dieser Modus überspringt Realtime-Audio-Voraussetzungen, -weil er weder über die Brücke zuhört noch darüber spricht: +Die Setup-Ausgabe ist darauf ausgelegt, für Agenten lesbar und modusabhängig zu sein. +Sie meldet Chrome-Profil, Node-Fixierung und bei Echtzeit-Chrome-Beitritten die +BlackHole/SoX-Audiobrücke sowie verzögerte Prüfungen der Echtzeit-Einführung. Für +Beitritte nur zur Beobachtung prüfen Sie denselben Transport mit `--mode transcribe`; +dieser Modus überspringt Echtzeit-Audio-Voraussetzungen, weil er weder über die +Brücke zuhört noch über sie spricht: ```bash openclaw googlemeet setup --transport chrome-node --mode transcribe ``` -Wenn Twilio-Delegation konfiguriert ist, meldet Setup außerdem, ob das -`voice-call`-Plugin, die Twilio-Anmeldedaten und die öffentliche Webhook-Erreichbarkeit bereit sind. -Behandeln Sie jede Prüfung mit `ok: false` als Blocker für den geprüften Transport und Modus, -bevor Sie einen Agenten bitten beizutreten. Verwenden Sie `openclaw googlemeet setup --json` für -Skripte oder maschinenlesbare Ausgabe. Verwenden Sie `--transport chrome`, -`--transport chrome-node` oder `--transport twilio`, um einen bestimmten -Transport vorab zu prüfen, bevor ein Agent ihn versucht. +Wenn Twilio-Delegierung konfiguriert ist, meldet das Setup auch, ob das +`voice-call`-Plugin, die Twilio-Anmeldedaten und die öffentliche Webhook-Erreichbarkeit +bereit sind. Behandeln Sie jede Prüfung mit `ok: false` als Blocker für den +geprüften Transport und Modus, bevor Sie einen Agenten zum Beitritt auffordern. +Verwenden Sie `openclaw googlemeet setup --json` für Skripte oder maschinenlesbare +Ausgabe. Verwenden Sie `--transport chrome`, `--transport chrome-node` oder +`--transport twilio`, um einen bestimmten Transport vorab zu prüfen, bevor ein +Agent ihn ausprobiert. -Für Twilio sollten Sie den Transport immer explizit vorab prüfen, wenn der Standardtransport -Chrome ist: +Für Twilio sollten Sie den Transport immer explizit vorab prüfen, wenn der +Standardtransport Chrome ist: ```bash openclaw googlemeet setup --transport twilio ``` -Das erkennt fehlende `voice-call`-Verdrahtung, Twilio-Anmeldedaten oder nicht erreichbare -Webhook-Erreichbarkeit, bevor der Agent versucht, das Meeting anzuwählen. +Das erkennt fehlende `voice-call`-Verdrahtung, Twilio-Anmeldedaten oder nicht +erreichbare Webhook-Veröffentlichung, bevor der Agent versucht, das Meeting anzuwählen. Einem Meeting beitreten: @@ -127,36 +130,37 @@ Oder lassen Sie einen Agenten über das `google_meet`-Tool beitreten: } ``` -Das agentenseitige `google_meet`-Tool bleibt auf Nicht-macOS-Hosts für -Artefakt-, Kalender-, Setup-, Transcribe-, Twilio- und `chrome-node`-Flows verfügbar. Lokale -Chrome-Rücksprech-Aktionen werden dort blockiert, weil der gebündelte Chrome-Audiopfad +Das agentenseitige `google_meet`-Tool bleibt auf Nicht-macOS-Hosts für Artefakt-, +Kalender-, Setup-, Transcribe-, Twilio- und `chrome-node`-Flows verfügbar. Lokale +Chrome-Rücksprechaktionen werden dort blockiert, weil der gebündelte Chrome-Audiopfad derzeit von macOS `BlackHole 2ch` abhängt. Verwenden Sie unter Linux `mode: "transcribe"`, -Twilio-Einwahl oder einen macOS-`chrome-node`-Host für Chrome-Rücksprech- -Teilnahme. +Twilio-Einwahl oder einen macOS-`chrome-node`-Host für Chrome-Rücksprech-Teilnahme. -Ein neues Meeting erstellen und ihm beitreten: +Ein neues Meeting erstellen und beitreten: ```bash -openclaw googlemeet create --transport chrome-node --mode realtime +openclaw googlemeet create --transport chrome-node --mode agent ``` -Verwenden Sie für per API erstellte Räume Google Meet `SpaceConfig.accessType`, wenn Sie möchten, -dass die Ohne-Anklopfen-Richtlinie des Raums explizit ist, statt von den Google- -Kontostandards geerbt zu werden: +Verwenden Sie für per API erstellte Räume Google Meet `SpaceConfig.accessType`, +wenn die No-Knock-Richtlinie des Raums explizit sein soll, statt von den +Standardeinstellungen des Google-Kontos geerbt zu werden: ```bash -openclaw googlemeet create --access-type OPEN --transport chrome-node --mode realtime +openclaw googlemeet create --access-type OPEN --transport chrome-node --mode agent ``` -`OPEN` lässt alle Personen mit der Meet-URL ohne Anklopfen beitreten. `TRUSTED` lässt die -vertrauenswürdigen Benutzer der Host-Organisation, eingeladene externe Benutzer und Einwahlbenutzer -ohne Anklopfen beitreten. `RESTRICTED` beschränkt den Eintritt ohne Anklopfen auf Eingeladene. Diese -Einstellungen gelten nur für den offiziellen Erstellungspfad der Google Meet API, daher müssen OAuth- -Anmeldedaten konfiguriert sein. +`OPEN` lässt alle Personen mit der Meet-URL ohne Anklopfen beitreten. `TRUSTED` +lässt vertrauenswürdige Benutzer der Host-Organisation, eingeladene externe +Benutzer und Einwahlbenutzer ohne Anklopfen beitreten. `RESTRICTED` beschränkt +den Eintritt ohne Anklopfen auf Eingeladene. Diese Einstellungen gelten nur für +den offiziellen Erstellungspfad der Google Meet API, daher müssen OAuth-Anmeldedaten +konfiguriert sein. -Wenn Sie Google Meet authentifiziert haben, bevor diese Option verfügbar war, führen Sie -`openclaw googlemeet auth login --json` erneut aus, nachdem Sie den -Scope `meetings.space.settings` zu Ihrem Google OAuth-Zustimmungsbildschirm hinzugefügt haben. +Wenn Sie Google Meet authentifiziert haben, bevor diese Option verfügbar war, +führen Sie `openclaw googlemeet auth login --json` erneut aus, nachdem Sie den +Scope `meetings.space.settings` zu Ihrem Google OAuth-Zustimmungsbildschirm +hinzugefügt haben. Nur die URL erstellen, ohne beizutreten: @@ -166,84 +170,94 @@ openclaw googlemeet create --no-join `googlemeet create` hat zwei Pfade: -- API-Erstellung: wird verwendet, wenn Google Meet OAuth-Anmeldedaten konfiguriert sind. Dies ist - der deterministischste Pfad und hängt nicht vom Browser-UI-Zustand ab. -- Browser-Fallback: wird verwendet, wenn OAuth-Anmeldedaten fehlen. OpenClaw verwendet den - gepinnten Chrome-Node, öffnet `https://meet.google.com/new`, wartet darauf, dass Google auf - eine echte Meeting-Code-URL weiterleitet, und gibt dann diese URL zurück. Dieser Pfad erfordert, - dass das OpenClaw-Chrome-Profil auf dem Node bereits bei Google angemeldet ist. - Die Browser-Automatisierung verarbeitet Meets eigene Mikrofonaufforderung beim ersten Start; diese Aufforderung - wird nicht als Google-Anmeldefehler behandelt. - Beitritts- und Erstellungs-Flows versuchen außerdem, einen vorhandenen Meet-Tab wiederzuverwenden, bevor sie einen - neuen öffnen. Der Abgleich ignoriert harmlose URL-Abfragezeichenfolgen wie `authuser`, sodass ein - erneuter Agentenversuch das bereits geöffnete Meeting fokussieren sollte, statt einen zweiten - Chrome-Tab zu erstellen. +- API-Erstellung: Wird verwendet, wenn Google Meet OAuth-Anmeldedaten konfiguriert + sind. Dies ist der deterministischste Pfad und hängt nicht vom Zustand der + Browseroberfläche ab. +- Browser-Fallback: Wird verwendet, wenn OAuth-Anmeldedaten fehlen. OpenClaw + verwendet den fixierten Chrome-Node, öffnet `https://meet.google.com/new`, wartet, + bis Google zu einer echten Meeting-Code-URL weiterleitet, und gibt dann diese URL + zurück. Dieser Pfad erfordert, dass das OpenClaw-Chrome-Profil auf dem Node bereits + bei Google angemeldet ist. Die Browserautomatisierung verarbeitet die eigene + Mikrofon-Erstaufforderung von Meet; diese Aufforderung wird nicht als Google-Loginfehler + behandelt. + Beitritts- und Erstellungsflows versuchen außerdem, einen vorhandenen Meet-Tab + wiederzuverwenden, bevor sie einen neuen öffnen. Der Abgleich ignoriert harmlose + URL-Abfragezeichenfolgen wie `authuser`, sodass ein Agenten-Wiederholungsversuch + das bereits geöffnete Meeting fokussieren sollte, statt einen zweiten Chrome-Tab + zu erstellen. -Die Befehls-/Tool-Ausgabe enthält ein Feld `source` (`api` oder `browser`), damit Agenten -erklären können, welcher Pfad verwendet wurde. `create` tritt dem neuen Meeting standardmäßig bei und -gibt `joined: true` plus die Beitrittssitzung zurück. Um nur die URL zu prägen, verwenden Sie -`create --no-join` in der CLI oder übergeben Sie `"join": false` an das Tool. +Die Befehls-/Tool-Ausgabe enthält ein `source`-Feld (`api` oder `browser`), damit +Agenten erklären können, welcher Pfad verwendet wurde. `create` tritt dem neuen +Meeting standardmäßig bei und gibt `joined: true` plus die Beitrittssitzung zurück. +Um nur die URL zu erzeugen, verwenden Sie `create --no-join` in der CLI oder +übergeben Sie `"join": false` an das Tool. -Oder sagen Sie einem Agenten: „Erstellen Sie ein Google Meet, treten Sie ihm mit Realtime-Sprache bei und senden -Sie mir den Link.“ Der Agent sollte `google_meet` mit `action: "create"` aufrufen und -anschließend die zurückgegebene `meetingUri` teilen. +Oder sagen Sie einem Agenten: „Erstellen Sie ein Google Meet, treten Sie mit dem +Agent-Rücksprechmodus bei und senden Sie mir den Link.“ Der Agent sollte +`google_meet` mit `action: "create"` aufrufen und dann die zurückgegebene +`meetingUri` teilen. ```json { "action": "create", "transport": "chrome-node", - "mode": "realtime" + "mode": "agent" } ``` -Für einen Nur-Beobachten-/Browsersteuerungs-Beitritt setzen Sie `"mode": "transcribe"`. Dadurch wird -die Duplex-Realtime-Sprachbrücke nicht gestartet, BlackHole oder SoX werden nicht benötigt, -und es wird nicht in das Meeting zurückgesprochen. Chrome-Beitritte in diesem Modus vermeiden außerdem -OpenClaws Mikrofon-/Kameraberechtigungserteilung und vermeiden den Meet-Pfad **Mikrofon verwenden**. -Wenn Meet eine Audioauswahl-Zwischenseite anzeigt, versucht die Automatisierung -den Pfad ohne Mikrofon und meldet andernfalls eine manuelle Aktion, statt -das lokale Mikrofon zu öffnen. Im Transcribe-Modus installieren verwaltete Chrome-Transporte außerdem -einen Best-Effort-Meet-Untertitelbeobachter. `googlemeet status --json` und -`googlemeet doctor` zeigen `captioning`, `captionsEnabledAttempted`, -`transcriptLines`, `lastCaptionAt`, `lastCaptionSpeaker`, `lastCaptionText` -und einen kurzen `recentTranscript`-Rest an, damit Betreiber erkennen können, ob der Browser -dem Anruf beigetreten ist und ob Meet-Untertitel Text erzeugen. -Verwenden Sie `openclaw googlemeet test-listen --transport chrome-node`, wenn -Sie eine Ja/Nein-Prüfung benötigen: Es tritt im Transcribe-Modus bei, wartet auf frische Untertitel- oder -Transkriptbewegung und gibt `listenVerified`, `listenTimedOut`, Felder für manuelle -Aktionen und den neuesten Untertitelzustand zurück. +Für einen Beitritt nur zur Beobachtung/Browsersteuerung setzen Sie `"mode": "transcribe"`. +Das startet nicht die Duplex-Echtzeit-Sprachbrücke, erfordert weder BlackHole noch +SoX und spricht nicht zurück in das Meeting. Chrome-Beitritte in diesem Modus vermeiden +auch OpenClaws Mikrofon-/Kameraberechtigungserteilung und den Meet-Pfad **Mikrofon +verwenden**. Wenn Meet einen Audioauswahl-Zwischenschritt zeigt, versucht die +Automatisierung den Pfad ohne Mikrofon und meldet andernfalls eine manuelle Aktion, +statt das lokale Mikrofon zu öffnen. Im Transcribe-Modus installieren verwaltete +Chrome-Transporte außerdem einen Best-Effort-Meet-Untertitelbeobachter. +`googlemeet status --json` und `googlemeet doctor` zeigen `captioning`, +`captionsEnabledAttempted`, `transcriptLines`, `lastCaptionAt`, `lastCaptionSpeaker`, +`lastCaptionText` und einen kurzen `recentTranscript`-Nachlauf an, damit Operatoren +erkennen können, ob der Browser dem Anruf beigetreten ist und ob Meet-Untertitel +Text erzeugen. +Verwenden Sie `openclaw googlemeet test-listen --transport chrome-node`, +wenn Sie eine Ja/Nein-Prüfung benötigen: Sie tritt im Transcribe-Modus bei, wartet +auf frische Untertitel- oder Transkriptbewegung und gibt `listenVerified`, +`listenTimedOut`, Felder für manuelle Aktionen und den aktuellen Untertitelstatus +zurück. -Während Realtime-Sitzungen enthält der `google_meet`-Status den Browser- und Audio-Brücken- -Zustand wie `inCall`, `manualActionRequired`, `providerConnected`, -`realtimeReady`, `audioInputActive`, `audioOutputActive`, letzte Ein-/Ausgabe- -Zeitstempel, Byte-Zähler und den geschlossenen Zustand der Brücke. Wenn eine sichere Meet-Seitenaufforderung -erscheint, verarbeitet die Browser-Automatisierung sie, wenn sie kann. Login, Host-Zulassung und -Browser-/OS-Berechtigungsaufforderungen werden als manuelle Aktion mit Grund und -Nachricht gemeldet, die der Agent weitergeben kann. Verwaltete Chrome-Sitzungen geben die Einführung oder -Testphrase erst aus, nachdem der Browserzustand `inCall: true` meldet; andernfalls meldet der Status -`speechReady: false` und der Sprechversuch wird blockiert, statt vorzugeben, der -Agent habe ins Meeting gesprochen. +Während Echtzeitsitzungen enthält der `google_meet`-Status Browser- und +Audiobrücken-Health-Daten wie `inCall`, `manualActionRequired`, `providerConnected`, +`realtimeReady`, `audioInputActive`, `audioOutputActive`, Zeitstempel der letzten +Ein-/Ausgabe, Byte-Zähler und den geschlossenen Brückenzustand. Wenn eine sichere +Meet-Seitenaufforderung erscheint, verarbeitet die Browserautomatisierung sie, wenn +sie kann. Login-, Host-Zulassungs- und Browser-/OS-Berechtigungsaufforderungen werden +als manuelle Aktion mit Grund und Nachricht gemeldet, damit der Agent sie weitergeben +kann. Verwaltete Chrome-Sitzungen geben die Einführungs- oder Testphrase erst aus, +nachdem der Browser-Health-Status `inCall: true` meldet; andernfalls meldet der +Status `speechReady: false` und der Sprachversuch wird blockiert, statt vorzugeben, +der Agent habe in das Meeting gesprochen. -Lokale Chrome-Beitritte erfolgen über das angemeldete OpenClaw-Browserprofil. Der Realtime-Modus -erfordert `BlackHole 2ch` für den Mikrofon-/Lautsprecherpfad, den OpenClaw verwendet. Für -sauberes Duplex-Audio verwenden Sie separate virtuelle Geräte oder einen Loopback-artigen Graphen; ein -einzelnes BlackHole-Gerät reicht für einen ersten Smoke-Test, kann aber ein Echo erzeugen. +Lokale Chrome-Beitritte erfolgen über das angemeldete OpenClaw-Browserprofil. +Echtzeitmodus erfordert `BlackHole 2ch` für den von OpenClaw verwendeten +Mikrofon-/Lautsprecherpfad. Für sauberes Duplex-Audio verwenden Sie getrennte +virtuelle Geräte oder einen Loopback-ähnlichen Graphen; ein einzelnes BlackHole-Gerät +reicht für einen ersten Smoke-Test aus, kann aber Echo erzeugen. -### Lokaler Gateway + Parallels Chrome +### Lokales Gateway + Parallels Chrome -Sie benötigen **keinen** vollständigen OpenClaw Gateway oder Modell-API-Schlüssel in einer macOS-VM, -nur damit die VM Chrome besitzt. Führen Sie Gateway und Agent lokal aus und führen Sie dann einen -Node-Host in der VM aus. Aktivieren Sie das gebündelte Plugin einmal in der VM, damit der Node -den Chrome-Befehl annonciert: +Sie benötigen **kein** vollständiges OpenClaw Gateway und keinen Modell-API-Schlüssel +innerhalb einer macOS-VM, nur damit die VM Chrome besitzt. Führen Sie das Gateway +und den Agenten lokal aus und führen Sie dann einen Node-Host in der VM aus. +Aktivieren Sie das gebündelte Plugin einmal in der VM, damit der Node den +Chrome-Befehl ankündigt: Was wo läuft: -- Gateway-Host: OpenClaw Gateway, Agenten-Workspace, Modell-/API-Schlüssel, Realtime- - Provider und die Google Meet-Plugin-Konfiguration. +- Gateway-Host: OpenClaw Gateway, Agent-Arbeitsbereich, Modell-/API-Schlüssel, + Echtzeit-Provider und die Google Meet-Plugin-Konfiguration. - Parallels-macOS-VM: OpenClaw CLI/Node-Host, Google Chrome, SoX, BlackHole 2ch und ein bei Google angemeldetes Chrome-Profil. -- Nicht in der VM benötigt: Gateway-Dienst, Agentenkonfiguration, OpenAI/GPT-Schlüssel oder Modell- - Provider-Einrichtung. +- In der VM nicht erforderlich: Gateway-Dienst, Agent-Konfiguration, OpenAI/GPT-Schlüssel + oder Modell-Provider-Einrichtung. Installieren Sie die VM-Abhängigkeiten: @@ -251,20 +265,22 @@ Installieren Sie die VM-Abhängigkeiten: brew install blackhole-2ch sox ``` -Starten Sie die VM nach der Installation von BlackHole neu, damit macOS `BlackHole 2ch` bereitstellt: +Starten Sie die VM nach der Installation von BlackHole neu, damit macOS +`BlackHole 2ch` bereitstellt: ```bash sudo reboot ``` -Prüfen Sie nach dem Neustart, dass die VM das Audiogerät und die SoX-Befehle sehen kann: +Prüfen Sie nach dem Neustart, ob die VM das Audiogerät und die SoX-Befehle sieht: ```bash system_profiler SPAudioDataType | grep -i BlackHole command -v sox ``` -Installieren oder aktualisieren Sie OpenClaw in der VM und aktivieren Sie dort anschließend das gebündelte Plugin: +Installieren oder aktualisieren Sie OpenClaw in der VM und aktivieren Sie dort +anschließend das gebündelte Plugin: ```bash openclaw plugins enable google-meet @@ -276,15 +292,17 @@ Starten Sie den Node-Host in der VM: openclaw node run --host --port 18789 --display-name parallels-macos ``` -Wenn `` eine LAN-IP ist und Sie kein TLS verwenden, verweigert der Node das -Plaintext-WebSocket, sofern Sie sich nicht explizit für dieses vertrauenswürdige private Netzwerk entscheiden: +Wenn `` eine LAN-IP ist und Sie kein TLS verwenden, verweigert der +Node den Klartext-WebSocket, sofern Sie sich nicht explizit für dieses vertrauenswürdige +private Netzwerk entscheiden: ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --port 18789 --display-name parallels-macos ``` -Verwenden Sie dieselbe Umgebungsvariable, wenn Sie den Node als LaunchAgent installieren: +Verwenden Sie dieselbe Umgebungsvariable, wenn Sie den Node als LaunchAgent +installieren: ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ @@ -293,8 +311,8 @@ openclaw node restart ``` `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` ist eine Prozessumgebung, keine -`openclaw.json`-Einstellung. `openclaw node install` speichert sie in der LaunchAgent- -Umgebung, wenn sie beim Installationsbefehl vorhanden ist. +`openclaw.json`-Einstellung. `openclaw node install` speichert sie in der +LaunchAgent-Umgebung, wenn sie beim Installationsbefehl vorhanden ist. Genehmigen Sie den Node vom Gateway-Host aus: @@ -303,8 +321,8 @@ openclaw devices list openclaw devices approve ``` -Bestätigen Sie, dass der Gateway den Node sieht und dass er sowohl `googlemeet.chrome` -als auch Browser-Fähigkeit/`browser.proxy` annonciert: +Bestätigen Sie, dass das Gateway den Node sieht und dass er sowohl `googlemeet.chrome` +als auch Browserfähigkeit/`browser.proxy` ankündigt: ```bash openclaw nodes status @@ -346,29 +364,30 @@ Treten Sie nun wie gewohnt vom Gateway-Host aus bei: openclaw googlemeet join https://meet.google.com/abc-defg-hij ``` -oder bitten Sie den Agenten, das `google_meet`-Tool mit `transport: "chrome-node"` zu verwenden. +oder bitten Sie den Agenten, das `google_meet`-Tool mit `transport: "chrome-node"` +zu verwenden. -Für einen Ein-Befehl-Smoke-Test, der eine Sitzung erstellt oder wiederverwendet, eine bekannte -Phrase spricht und den Sitzungszustand ausgibt: +Für einen Smoke-Test mit einem Befehl, der eine Sitzung erstellt oder wiederverwendet, +eine bekannte Phrase spricht und den Sitzungszustand ausgibt: ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij ``` -Während des Echtzeit-Beitritts füllt die OpenClaw-Browser-Automatisierung den Gastnamen aus, klickt auf -Beitreten/Beitritt anfragen und akzeptiert Meets Erstausführungs-Auswahl „Mikrofon verwenden“, wenn diese -Aufforderung angezeigt wird. Beim beobachtenden Beitritt oder bei der reinen Browser-Erstellung eines Meetings +Beim Realtime-Beitritt füllt die OpenClaw-Browserautomatisierung den Gastnamen aus, klickt auf +Teilnehmen/Teilnahmeanfrage stellen und akzeptiert Meets erstmalige Auswahl „Mikrofon verwenden“, wenn diese +Aufforderung erscheint. Beim Beitritt im Nur-Beobachten-Modus oder bei der reinen Browser-Erstellung eines Meetings fährt sie bei derselben Aufforderung ohne Mikrofon fort, wenn diese Auswahl verfügbar ist. -Wenn das Browser-Profil nicht angemeldet ist, Meet auf die Zulassung durch den Host wartet, -Chrome für einen Echtzeit-Beitritt Mikrofon-/Kameraberechtigung benötigt oder Meet bei einer -Aufforderung festhängt, die die Automatisierung nicht auflösen konnte, meldet das Ergebnis von join/test-speech +Wenn das Browserprofil nicht angemeldet ist, Meet auf die Zulassung durch den Host wartet, +Chrome für einen Realtime-Beitritt die Mikrofon-/Kameraberechtigung benötigt oder Meet bei einer +Aufforderung hängen bleibt, die die Automatisierung nicht auflösen konnte, meldet das Ergebnis von join/test-speech `manualActionRequired: true` mit `manualActionReason` und -`manualActionMessage`. Agents sollten den Beitrittsversuch nicht weiter wiederholen, genau diese -Meldung sowie die aktuellen Werte für `browserUrl`/`browserTitle` melden und erst erneut versuchen, -nachdem die manuelle Browser-Aktion abgeschlossen ist. +`manualActionMessage`. Agents sollten weitere Beitrittsversuche stoppen, genau diese +Meldung plus die aktuelle `browserUrl`/`browserTitle` melden und erst erneut versuchen, nachdem die +manuelle Browseraktion abgeschlossen ist. Wenn `chromeNode.node` weggelassen wird, wählt OpenClaw nur dann automatisch aus, wenn genau ein -verbundener Node sowohl `googlemeet.chrome` als auch Browser-Steuerung meldet. Wenn +verbundener Node sowohl `googlemeet.chrome` als auch Browsersteuerung ankündigt. Wenn mehrere geeignete Nodes verbunden sind, setzen Sie `chromeNode.node` auf die Node-ID, den Anzeigenamen oder die Remote-IP. @@ -377,52 +396,52 @@ Häufige Fehlerprüfungen: - `Configured Google Meet node ... is not usable: offline`: Der festgelegte Node ist dem Gateway bekannt, aber nicht verfügbar. Agents sollten diesen Node als Diagnosezustand behandeln, nicht als verwendbaren Chrome-Host, und den Setup-Blocker - melden, statt auf einen anderen Transport zurückzufallen, sofern der Benutzer dies nicht verlangt hat. + melden, anstatt auf einen anderen Transport zurückzufallen, sofern der Benutzer dies nicht angefordert hat. - `No connected Google Meet-capable node`: Starten Sie `openclaw node run` in der VM, - genehmigen Sie die Kopplung und stellen Sie sicher, dass `openclaw plugins enable google-meet` und + genehmigen Sie das Pairing und stellen Sie sicher, dass `openclaw plugins enable google-meet` und `openclaw plugins enable browser` in der VM ausgeführt wurden. Bestätigen Sie außerdem, dass der Gateway-Host beide Node-Befehle mit - `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]` erlaubt. + `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]` zulässt. - `BlackHole 2ch audio device not found`: Installieren Sie `blackhole-2ch` auf dem geprüften Host - und starten Sie neu, bevor Sie lokales Chrome-Audio verwenden. + und starten Sie ihn neu, bevor Sie lokales Chrome-Audio verwenden. - `BlackHole 2ch audio device not found on the node`: Installieren Sie `blackhole-2ch` in der VM und starten Sie die VM neu. -- Chrome öffnet sich, kann aber nicht beitreten: Melden Sie sich im Browser-Profil innerhalb der VM an oder +- Chrome wird geöffnet, kann aber nicht beitreten: Melden Sie sich im Browserprofil innerhalb der VM an, oder lassen Sie `chrome.guestName` für den Gastbeitritt gesetzt. Der automatische Gastbeitritt nutzt die OpenClaw- - Browser-Automatisierung über den Node-Browser-Proxy; stellen Sie sicher, dass die Node-Browser- - Konfiguration auf das gewünschte Profil verweist, zum Beispiel - `browser.defaultProfile: "user"` oder ein benanntes existing-session-Profil. + Browserautomatisierung über den Node-Browserproxy; stellen Sie sicher, dass die Node-Browserkonfiguration + auf das gewünschte Profil zeigt, zum Beispiel + `browser.defaultProfile: "user"` oder ein benanntes Existing-Session-Profil. - Doppelte Meet-Tabs: Lassen Sie `chrome.reuseExistingTab: true` aktiviert. OpenClaw - aktiviert einen bestehenden Tab für dieselbe Meet-URL, bevor ein neuer geöffnet wird, und - die Browser-Meeting-Erstellung verwendet einen laufenden `https://meet.google.com/new` - oder Google-Konto-Aufforderungs-Tab wieder, bevor ein weiterer geöffnet wird. -- Kein Audio: Leiten Sie in Meet Mikrofon-/Lautsprecher-Audio über den von OpenClaw verwendeten - Pfad des virtuellen Audiogeräts; verwenden Sie separate virtuelle Geräte oder Routing im Loopback-Stil + aktiviert einen vorhandenen Tab für dieselbe Meet-URL, bevor ein neuer geöffnet wird, und + die Browser-Meeting-Erstellung verwendet einen laufenden `https://meet.google.com/new`- + oder Google-Konto-Aufforderungs-Tab erneut, bevor ein weiterer geöffnet wird. +- Kein Audio: Leiten Sie in Meet Mikrofon-/Lautsprecheraudio über den von OpenClaw verwendeten + Pfad des virtuellen Audiogeräts; verwenden Sie getrennte virtuelle Geräte oder Loopback-artiges Routing für sauberes Duplex-Audio. ## Installationshinweise -Der Chrome-Talkback-Standard verwendet zwei externe Werkzeuge: +Der Standard für Chrome Talk-Back verwendet zwei externe Tools: -- `sox`: Befehlszeilen-Audio-Dienstprogramm. Das Plugin verwendet explizite CoreAudio- +- `sox`: Befehlszeilen-Audiowerkzeug. Das Plugin verwendet explizite CoreAudio- Gerätebefehle für die standardmäßige 24-kHz-PCM16-Audiobrücke. - `blackhole-2ch`: virtueller macOS-Audiotreiber. Er erstellt das Audiogerät `BlackHole 2ch`, - über das Chrome/Meet geroutet werden kann. + über das Chrome/Meet routen kann. -OpenClaw bündelt oder vertreibt keines der beiden Pakete. Die Dokumentation fordert Benutzer auf, -sie als Host-Abhängigkeiten über Homebrew zu installieren. SoX ist lizenziert als -`LGPL-2.0-only AND GPL-2.0-only`; BlackHole ist GPL-3.0. Wenn Sie ein -Installationsprogramm oder Appliance-Image erstellen, das BlackHole mit OpenClaw bündelt, prüfen Sie die +OpenClaw bündelt oder vertreibt keines der beiden Pakete. Die Dokumentation weist Benutzer an, +sie als Host-Abhängigkeiten über Homebrew zu installieren. SoX ist als +`LGPL-2.0-only AND GPL-2.0-only` lizenziert; BlackHole ist GPL-3.0. Wenn Sie einen +Installer oder eine Appliance erstellen, die BlackHole mit OpenClaw bündelt, prüfen Sie die Upstream-Lizenzbedingungen von BlackHole oder beziehen Sie eine separate Lizenz von Existential Audio. ## Transporte ### Chrome -Der Chrome-Transport öffnet die Meet-URL über die OpenClaw-Browser-Steuerung und tritt -als angemeldetes OpenClaw-Browser-Profil bei. Unter macOS prüft das Plugin vor dem Start auf -`BlackHole 2ch`. Wenn konfiguriert, führt es außerdem vor dem Öffnen von Chrome einen Health-Befehl -und einen Startbefehl für die Audiobrücke aus. Verwenden Sie `chrome`, wenn +Der Chrome-Transport öffnet die Meet-URL über die OpenClaw-Browsersteuerung und tritt +als das angemeldete OpenClaw-Browserprofil bei. Unter macOS prüft das Plugin vor dem Start auf +`BlackHole 2ch`. Falls konfiguriert, führt es außerdem einen Health-Befehl für die Audiobrücke +und einen Startbefehl aus, bevor Chrome geöffnet wird. Verwenden Sie `chrome`, wenn Chrome/Audio auf dem Gateway-Host laufen; verwenden Sie `chrome-node`, wenn Chrome/Audio auf einem gekoppelten Node wie einer Parallels-macOS-VM laufen. Wählen Sie für lokales Chrome das Profil mit `browser.defaultProfile`; `chrome.browserProfile` wird an @@ -433,25 +452,25 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome-node ``` -Leiten Sie Chrome-Mikrofon- und Lautsprecher-Audio durch die lokale OpenClaw-Audiobrücke. +Leiten Sie Chrome-Mikrofon- und Lautsprecheraudio über die lokale OpenClaw-Audiobrücke. Wenn `BlackHole 2ch` nicht installiert ist, schlägt der Beitritt mit einem Setup-Fehler fehl, -anstatt still ohne Audiopfad beizutreten. +anstatt stillschweigend ohne Audiopfad beizutreten. ### Twilio -Der Twilio-Transport ist ein strikter Wählplan, der an das Voice Call-Plugin delegiert wird. Er -parst Meet-Seiten nicht nach Telefonnummern. +Der Twilio-Transport ist ein strikter Wählplan, der an das Voice Call Plugin delegiert wird. Er +parst keine Meet-Seiten nach Telefonnummern. -Verwenden Sie dies, wenn die Chrome-Teilnahme nicht verfügbar ist oder Sie einen Telefon-Einwahl- -Fallback wünschen. Google Meet muss eine Telefon-Einwahlnummer und PIN für das -Meeting bereitstellen; OpenClaw ermittelt diese nicht aus der Meet-Seite. +Verwenden Sie dies, wenn Chrome-Teilnahme nicht verfügbar ist oder Sie einen Telefon-Dial-in- +Fallback wünschen. Google Meet muss für das Meeting eine Telefon-Einwahlnummer und PIN +bereitstellen; OpenClaw ermittelt diese nicht aus der Meet-Seite. -Aktivieren Sie das Voice Call-Plugin auf dem Gateway-Host, nicht auf dem Chrome-Node: +Aktivieren Sie das Voice Call Plugin auf dem Gateway-Host, nicht auf dem Chrome-Node: ```json5 { plugins: { - allow: ["google-meet", "voice-call"], + allow: ["google-meet", "voice-call", "google"], entries: { "google-meet": { enabled: true, @@ -464,24 +483,44 @@ Aktivieren Sie das Voice Call-Plugin auf dem Gateway-Host, nicht auf dem Chrome- enabled: true, config: { provider: "twilio", + inboundPolicy: "allowlist", + realtime: { + enabled: true, + provider: "google", + instructions: "Join this Google Meet as an OpenClaw agent. Be brief.", + toolPolicy: "safe-read-only", + providers: { + google: { + silenceDurationMs: 500, + startSensitivity: "high", + }, + }, + }, }, }, + google: { + enabled: true, + }, }, }, } ``` Stellen Sie Twilio-Anmeldedaten über Umgebung oder Konfiguration bereit. Die Umgebung hält -Secrets aus `openclaw.json` heraus: +Geheimnisse aus `openclaw.json` heraus: ```bash export TWILIO_ACCOUNT_SID=AC... export TWILIO_AUTH_TOKEN=... export TWILIO_FROM_NUMBER=+15550001234 +export GEMINI_API_KEY=... ``` -Starten Sie das Gateway neu oder laden Sie es neu, nachdem Sie `voice-call` aktiviert haben; Plugin-Konfigurationsänderungen -erscheinen in einem bereits laufenden Gateway-Prozess erst, nachdem er neu geladen wurde. +Verwenden Sie stattdessen `realtime.provider: "openai"` mit dem OpenAI-Provider-Plugin und +`OPENAI_API_KEY`, wenn dies Ihr Realtime-Voice-Provider ist. + +Starten oder laden Sie das Gateway nach dem Aktivieren von `voice-call` neu; Plugin-Konfigurationsänderungen +erscheinen in einem bereits laufenden Gateway-Prozess erst nach dem Neuladen. Prüfen Sie anschließend: @@ -491,7 +530,7 @@ openclaw plugins list | grep -E 'google-meet|voice-call' openclaw googlemeet setup ``` -Wenn die Twilio-Delegation verdrahtet ist, enthält `googlemeet setup` erfolgreiche +Wenn die Twilio-Delegierung verdrahtet ist, enthält `googlemeet setup` erfolgreiche Prüfungen für `twilio-voice-call-plugin`, `twilio-voice-call-credentials` und `twilio-voice-call-webhook`. @@ -511,34 +550,34 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --dtmf-sequence ww123456# ``` -## OAuth und Vorabprüfung +## OAuth und Preflight -OAuth ist zum Erstellen eines Meet-Links optional, da `googlemeet create` auf -Browser-Automatisierung zurückfallen kann. Konfigurieren Sie OAuth, wenn Sie offizielle API-Erstellung, -Space-Auflösung oder Meet Media API-Vorabprüfungen möchten. +OAuth ist für das Erstellen eines Meet-Links optional, da `googlemeet create` auf +Browserautomatisierung zurückfallen kann. Konfigurieren Sie OAuth, wenn Sie offizielle API-Erstellung, +Space-Auflösung oder Preflight-Prüfungen der Meet Media API wünschen. -Google Meet-API-Zugriff verwendet Benutzer-OAuth: Erstellen Sie einen Google Cloud-OAuth-Client, -fordern Sie die erforderlichen Scopes an, autorisieren Sie ein Google-Konto und speichern Sie anschließend das -resultierende Refresh Token in der Google Meet-Plugin-Konfiguration oder stellen Sie die +Der Zugriff auf die Google Meet API verwendet Benutzer-OAuth: Erstellen Sie einen Google Cloud-OAuth-Client, +fordern Sie die erforderlichen Scopes an, autorisieren Sie ein Google-Konto und speichern Sie dann das +resultierende Refresh-Token in der Google Meet Plugin-Konfiguration oder stellen Sie die Umgebungsvariablen `OPENCLAW_GOOGLE_MEET_*` bereit. OAuth ersetzt den Chrome-Beitrittspfad nicht. Chrome- und Chrome-node-Transporte treten weiterhin über ein angemeldetes Chrome-Profil, BlackHole/SoX und einen verbundenen -Node bei, wenn Sie Browser-Teilnahme verwenden. OAuth ist nur für den offiziellen Google -Meet-API-Pfad vorgesehen: Meeting-Spaces erstellen, Spaces auflösen und Meet Media API- -Vorabprüfungen ausführen. +Node bei, wenn Sie Browserteilnahme verwenden. OAuth ist nur für den offiziellen Google +Meet API-Pfad vorgesehen: Meeting Spaces erstellen, Spaces auflösen und Preflight-Prüfungen +der Meet Media API ausführen. ### Google-Anmeldedaten erstellen In der Google Cloud Console: -1. Erstellen oder wählen Sie ein Google Cloud-Projekt. +1. Erstellen oder wählen Sie ein Google Cloud-Projekt aus. 2. Aktivieren Sie **Google Meet REST API** für dieses Projekt. 3. Konfigurieren Sie den OAuth-Zustimmungsbildschirm. - **Intern** ist für eine Google Workspace-Organisation am einfachsten. - - **Extern** funktioniert für persönliche/Test-Setups; solange die App im Testmodus ist, - fügen Sie jedes Google-Konto, das die App autorisieren soll, als Testbenutzer hinzu. -4. Fügen Sie die Scopes hinzu, die OpenClaw anfordert: + - **Extern** funktioniert für private/Test-Setups; solange sich die App im Testmodus befindet, + fügen Sie jedes Google-Konto, das die App autorisieren wird, als Testbenutzer hinzu. +4. Fügen Sie die von OpenClaw angeforderten Scopes hinzu: - `https://www.googleapis.com/auth/meetings.space.created` - `https://www.googleapis.com/auth/meetings.space.readonly` - `https://www.googleapis.com/auth/meetings.space.settings` @@ -556,12 +595,12 @@ In der Google Cloud Console: `meetings.space.created` wird von Google Meet `spaces.create` benötigt. `meetings.space.readonly` ermöglicht OpenClaw, Meet-URLs/-Codes zu Spaces aufzulösen. `meetings.space.settings` ermöglicht OpenClaw, `SpaceConfig`-Einstellungen wie -`accessType` bei der API-Raumerstellung zu übergeben. -`meetings.conference.media.readonly` ist für Meet Media API-Vorabprüfungen und Medienarbeit -vorgesehen; Google kann für die tatsächliche Media API-Nutzung eine Developer Preview-Registrierung verlangen. +`accessType` während der API-Raumerstellung zu übergeben. +`meetings.conference.media.readonly` ist für Preflight und Medienarbeit mit der Meet Media API vorgesehen; +Google kann für die tatsächliche Nutzung der Media API eine Developer-Preview-Registrierung verlangen. Wenn Sie nur browserbasierte Chrome-Beitritte benötigen, überspringen Sie OAuth vollständig. -### Refresh Token erzeugen +### Refresh-Token ausstellen Konfigurieren Sie `oauth.clientId` und optional `oauth.clientSecret`, oder übergeben Sie sie als Umgebungsvariablen, und führen Sie dann aus: @@ -570,9 +609,9 @@ Umgebungsvariablen, und führen Sie dann aus: openclaw googlemeet auth login --json ``` -Der Befehl gibt einen `oauth`-Konfigurationsblock mit einem Refresh Token aus. Er verwendet PKCE, -einen localhost-Callback auf `http://localhost:8085/oauth2callback` und einen manuellen -Kopieren/Einfügen-Flow mit `--manual`. +Der Befehl gibt einen `oauth`-Konfigurationsblock mit einem Refresh-Token aus. Er verwendet PKCE, +einen localhost-Callback auf `http://localhost:8085/oauth2callback` und mit `--manual` +einen manuellen Kopieren/Einfügen-Ablauf. Beispiele: @@ -605,7 +644,7 @@ Die JSON-Ausgabe enthält: } ``` -Speichern Sie das `oauth`-Objekt unter der Google Meet-Plugin-Konfiguration: +Speichern Sie das `oauth`-Objekt unter der Google Meet Plugin-Konfiguration: ```json5 { @@ -626,40 +665,40 @@ Speichern Sie das `oauth`-Objekt unter der Google Meet-Plugin-Konfiguration: } ``` -Bevorzugen Sie Umgebungsvariablen, wenn Sie das Refresh Token nicht in der Konfiguration haben möchten. +Bevorzugen Sie Umgebungsvariablen, wenn Sie das Refresh-Token nicht in der Konfiguration haben möchten. Wenn sowohl Konfigurations- als auch Umgebungswerte vorhanden sind, löst das Plugin zuerst die Konfiguration -und danach den Umgebungs-Fallback auf. +auf und verwendet dann die Umgebung als Fallback. -Die OAuth-Zustimmung umfasst Meet-Space-Erstellung, Meet-Space-Lesezugriff und Meet- -Konferenzmedien-Lesezugriff. Wenn Sie sich authentifiziert haben, bevor Unterstützung für die Meeting-Erstellung -existierte, führen Sie `openclaw googlemeet auth login --json` erneut aus, damit das Refresh +Die OAuth-Zustimmung umfasst Meet-Space-Erstellung, Lesezugriff auf Meet-Spaces und +Lesezugriff auf Meet-Konferenzmedien. Wenn Sie sich authentifiziert haben, bevor Unterstützung für die Meeting-Erstellung +existierte, führen Sie `openclaw googlemeet auth login --json` erneut aus, damit das Refresh- Token den Scope `meetings.space.created` hat. -### OAuth mit doctor prüfen +### OAuth mit Doctor prüfen -Führen Sie den OAuth-doctor aus, wenn Sie eine schnelle, geheimnisfreie Health-Prüfung möchten: +Führen Sie den OAuth-Doctor aus, wenn Sie eine schnelle, geheimnisfreie Integritätsprüfung wünschen: ```bash openclaw googlemeet doctor --oauth --json ``` -Dies lädt nicht die Chrome-Laufzeit und erfordert keinen verbundenen Chrome-Node. Es -prüft, ob eine OAuth-Konfiguration existiert und ob das Refresh Token ein Access Token -erzeugen kann. Der JSON-Bericht enthält nur Statusfelder wie `ok`, `configured`, -`tokenSource`, `expiresAt` und Prüfnachrichten; er gibt weder das Access -Token noch Refresh Token oder Client-Secret aus. +Dies lädt die Chrome-Laufzeit nicht und erfordert keinen verbundenen Chrome-Node. Es +prüft, ob die OAuth-Konfiguration vorhanden ist und ob das Refresh-Token ein Access- +Token ausstellen kann. Der JSON-Bericht enthält nur Statusfelder wie `ok`, `configured`, +`tokenSource`, `expiresAt` und Prüfmeldungen; er gibt weder Access- +Token, Refresh-Token noch Client-Secret aus. Häufige Ergebnisse: -| Prüfung | Bedeutung | -| -------------------- | ---------------------------------------------------------------------------------------- | -| `oauth-config` | `oauth.clientId` plus `oauth.refreshToken` oder ein zwischengespeichertes Access Token ist vorhanden. | -| `oauth-token` | Das zwischengespeicherte Access Token ist noch gültig, oder das Refresh Token hat ein neues Access Token erzeugt. | -| `meet-spaces-get` | Optionale `--meeting`-Prüfung hat einen bestehenden Meet-Space aufgelöst. | -| `meet-spaces-create` | Optionale `--create-space`-Prüfung hat einen neuen Meet-Space erstellt. | +| Prüfung | Bedeutung | +| -------------------- | --------------------------------------------------------------------------------------- | +| `oauth-config` | `oauth.clientId` plus `oauth.refreshToken` oder ein zwischengespeichertes Zugriffstoken ist vorhanden. | +| `oauth-token` | Das zwischengespeicherte Zugriffstoken ist noch gültig, oder das Refresh-Token hat ein neues Zugriffstoken erzeugt. | +| `meet-spaces-get` | Optionale `--meeting`-Prüfung hat einen vorhandenen Meet-Space aufgelöst. | +| `meet-spaces-create` | Optionale `--create-space`-Prüfung hat einen neuen Meet-Space erstellt. | -Um auch die Google Meet API-Aktivierung und den Scope `spaces.create` nachzuweisen, führen Sie die -Seiteneffekt-behaftete Erstellungsprüfung aus: +Um auch die Aktivierung der Google Meet API und den `spaces.create`-Scope nachzuweisen, führen Sie die +erstellende Prüfung mit Seiteneffekt aus: ```bash openclaw googlemeet doctor --oauth --create-space --json @@ -667,10 +706,10 @@ openclaw googlemeet create --no-join --json ``` `--create-space` erstellt eine temporäre Meet-URL. Verwenden Sie es, wenn Sie bestätigen müssen, -dass im Google Cloud-Projekt die Meet API aktiviert ist und das autorisierte +dass für das Google Cloud-Projekt die Meet API aktiviert ist und dass das autorisierte Konto den Scope `meetings.space.created` hat. -So weisen Sie Lesezugriff auf einen vorhandenen Meeting-Space nach: +Um Lesezugriff für einen vorhandenen Meeting-Space nachzuweisen: ```bash openclaw googlemeet doctor --oauth --meeting https://meet.google.com/abc-defg-hij --json @@ -679,9 +718,9 @@ openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij `doctor --oauth --meeting` und `resolve-space` weisen Lesezugriff auf einen vorhandenen Space nach, auf den das autorisierte Google-Konto zugreifen kann. Ein `403` aus diesen Prüfungen -bedeutet normalerweise, dass die Google Meet REST API deaktiviert ist, dem zugestimmten Refresh Token -der erforderliche Scope fehlt oder das Google-Konto nicht auf diesen Meet- -Space zugreifen kann. Ein Refresh-Token-Fehler bedeutet, dass Sie `openclaw googlemeet auth login +bedeutet üblicherweise, dass die Google Meet REST API deaktiviert ist, dem zugestimmten Refresh-Token +der erforderliche Scope fehlt oder das Google-Konto nicht auf diesen Meet-Space +zugreifen kann. Ein Refresh-Token-Fehler bedeutet, dass Sie `openclaw googlemeet auth login --json` erneut ausführen und den neuen `oauth`-Block speichern müssen. Für den Browser-Fallback sind keine OAuth-Anmeldedaten erforderlich. In diesem Modus stammt die Google- @@ -705,7 +744,7 @@ Lösen Sie eine Meet-URL, einen Code oder `spaces/{id}` über `spaces.get` auf: openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij ``` -Führen Sie vor Medienarbeiten den Preflight aus: +Führen Sie vor Medienarbeiten eine Vorabprüfung aus: ```bash openclaw googlemeet preflight --meeting https://meet.google.com/abc-defg-hij @@ -736,8 +775,8 @@ openclaw googlemeet attendance --today --format csv --output attendance.csv `--today` durchsucht den heutigen `primary`-Kalender nach einem Calendar-Ereignis mit einem Google Meet-Link. Verwenden Sie `--event `, um passenden Ereignistext zu durchsuchen, und `--calendar ` für einen nicht primären Kalender. Die Kalendersuche erfordert eine frische -OAuth-Anmeldung, die den readonly-Scope für Calendar-Ereignisse enthält. -`calendar-events` zeigt die passenden Meet-Ereignisse in der Vorschau und markiert das Ereignis, das +OAuth-Anmeldung, die den schreibgeschützten Scope für Calendar-Ereignisse enthält. +`calendar-events` zeigt eine Vorschau der passenden Meet-Ereignisse und markiert das Ereignis, das `latest`, `artifacts`, `attendance` oder `export` auswählen wird. Wenn Sie die Konferenzdatensatz-ID bereits kennen, adressieren Sie sie direkt: @@ -757,9 +796,9 @@ openclaw googlemeet end-active-conference https://meet.google.com/abc-defg-hij Dies ruft Google Meet `spaces.endActiveConference` auf und erfordert OAuth mit dem Scope `meetings.space.created` für einen Space, den das autorisierte Konto verwalten kann. -OpenClaw akzeptiert eine Meet-URL, einen Meeting-Code oder eine `spaces/{id}`-Eingabe und löst sie -zur API-Space-Ressource auf, bevor die aktive Konferenz beendet wird. -Dies ist von `googlemeet leave` getrennt: `leave` stoppt die lokale/Sitzungs- +OpenClaw akzeptiert eine Meet-URL, einen Meeting-Code oder `spaces/{id}` als Eingabe und löst sie +in die API-Space-Ressource auf, bevor die aktive Konferenz beendet wird. +Dies ist getrennt von `googlemeet leave`: `leave` beendet die lokale/Sitzungs- Teilnahme von OpenClaw, während `end-active-conference` Google Meet auffordert, die aktive Konferenz für den Space zu beenden. @@ -779,30 +818,30 @@ openclaw googlemeet export --conference-record conferenceRecords/abc123 \ ``` `artifacts` gibt Metadaten zum Konferenzdatensatz sowie Metadaten zu Teilnehmern, Aufzeichnungen, -Transkripten, strukturierten Transkripteintrags- und Smart-Note-Ressourcen zurück, wenn -Google sie für das Meeting bereitstellt. Verwenden Sie `--no-transcript-entries`, um bei großen Meetings -die Eintragssuche zu überspringen. `attendance` erweitert Teilnehmer zu -Teilnehmer-Sitzungszeilen mit Zeiten für erstes/letztes Erscheinen, gesamter Sitzungsdauer, -Flags für Verspätung/frühes Verlassen und nach angemeldetem Benutzer oder Anzeigenamen zusammengeführten -doppelten Teilnehmerressourcen. Übergeben Sie `--no-merge-duplicates`, um unverarbeitete Teilnehmer- -Ressourcen getrennt zu halten, `--late-after-minutes`, um die Erkennung von Verspätungen anzupassen, und -`--early-before-minutes`, um die Erkennung von frühem Verlassen anzupassen. +Transkripten, strukturierten Transkript-Einträgen und Smart-Note-Ressourcen zurück, wenn +Google sie für das Meeting bereitstellt. Verwenden Sie `--no-transcript-entries`, um die +Eintragssuche bei großen Meetings zu überspringen. `attendance` erweitert Teilnehmer zu +Teilnehmersitzungszeilen mit erstem/letztem Sichtungszeitpunkt, Gesamtdauer der Sitzung, +Kennzeichnungen für Verspätung/frühes Verlassen und zusammengeführten doppelten Teilnehmerressourcen nach angemeldetem +Benutzer oder Anzeigenamen. Übergeben Sie `--no-merge-duplicates`, um rohe Teilnehmer- +ressourcen getrennt zu halten, `--late-after-minutes`, um die Verspätungserkennung anzupassen, und +`--early-before-minutes`, um die Erkennung für frühes Verlassen anzupassen. `export` schreibt einen Ordner mit `summary.md`, `attendance.csv`, `transcript.md`, `artifacts.json`, `attendance.json` und `manifest.json`. -`manifest.json` protokolliert die gewählte Eingabe, Exportoptionen, Konferenzdatensätze, +`manifest.json` zeichnet die gewählte Eingabe, Exportoptionen, Konferenzdatensätze, Ausgabedateien, Zählwerte, Token-Quelle, das Calendar-Ereignis, wenn eines verwendet wurde, und alle -Warnungen zu teilweisen Abrufen. Übergeben Sie `--zip`, um zusätzlich ein portables Archiv neben -dem Ordner zu schreiben. Übergeben Sie `--include-doc-bodies`, um verknüpften Transkript- und -Smart-Note-Text aus Google Docs über Google Drive `files.export` zu exportieren; dies erfordert eine -frische OAuth-Anmeldung, die den readonly-Scope für Drive Meet enthält. Ohne +Warnungen zu teilweisem Abruf auf. Übergeben Sie `--zip`, um zusätzlich ein portables Archiv neben +dem Ordner zu schreiben. Übergeben Sie `--include-doc-bodies`, um verknüpfte Transkript- und +Smart-Note-Google-Docs-Texte über Google Drive `files.export` zu exportieren; dies erfordert eine +frische OAuth-Anmeldung, die den schreibgeschützten Drive Meet-Scope enthält. Ohne `--include-doc-bodies` enthalten Exporte nur Meet-Metadaten und strukturierte Transkript- -Einträge. Wenn Google einen teilweisen Artefaktfehler zurückgibt, etwa einen Fehler beim Auflisten von Smart Notes, -bei Transkripteinträgen oder beim Drive-Dokumentinhalt, behalten Zusammenfassung und -Manifest die Warnung, anstatt den gesamten Export fehlschlagen zu lassen. +Einträge. Wenn Google einen teilweisen Artefaktfehler zurückgibt, etwa einen Smart-Note- +Listing-, Transkript-Eintrags- oder Drive-Dokumenttext-Fehler, behalten Zusammenfassung und +Manifest die Warnung bei, statt den gesamten Export fehlschlagen zu lassen. Verwenden Sie `--dry-run`, um dieselben Artefakt-/Anwesenheitsdaten abzurufen und das -Manifest-JSON auszugeben, ohne den Ordner oder die ZIP-Datei zu erstellen. Das ist nützlich, bevor Sie -einen großen Export schreiben oder wenn ein Agent nur Zählwerte, ausgewählte Datensätze und +Manifest-JSON auszugeben, ohne den Ordner oder die ZIP-Datei zu erstellen. Das ist nützlich, bevor +Sie einen großen Export schreiben oder wenn ein Agent nur Zählwerte, ausgewählte Datensätze und Warnungen benötigt. Agenten können dasselbe Bundle auch über das `google_meet`-Tool erstellen: @@ -825,7 +864,7 @@ Agenten können auch einen API-gestützten Raum mit einer expliziten Zugriffsric { "action": "create", "transport": "chrome-node", - "mode": "realtime", + "mode": "agent", "accessType": "OPEN" } ``` @@ -839,7 +878,7 @@ Und sie können die aktive Konferenz für einen bekannten Raum beenden: } ``` -Für eine Validierung mit Zuhören zuerst sollten Agenten `test_listen` verwenden, bevor sie behaupten, dass das +Für eine Listen-zuerst-Validierung sollten Agenten `test_listen` verwenden, bevor sie behaupten, dass das Meeting nützlich ist: ```json @@ -859,8 +898,8 @@ OPENCLAW_GOOGLE_MEET_LIVE_MEETING=https://meet.google.com/abc-defg-hij \ pnpm test:live -- extensions/google-meet/google-meet.live.test.ts ``` -Führen Sie die Live-Browserprüfung mit Zuhören zuerst gegen ein Meeting aus, in dem jemand -sprechen wird und Meet-Untertitel verfügbar sind: +Führen Sie die Live-Browserprobe mit Listen-zuerst gegen ein Meeting aus, in dem jemand +spricht und Meet-Untertitel verfügbar sind: ```bash openclaw googlemeet setup --transport chrome-node --mode transcribe @@ -875,7 +914,7 @@ Live-Smoke-Umgebung: - `OPENCLAW_GOOGLE_MEET_CLIENT_ID` oder `GOOGLE_MEET_CLIENT_ID` stellt die OAuth- Client-ID bereit. - `OPENCLAW_GOOGLE_MEET_REFRESH_TOKEN` oder `GOOGLE_MEET_REFRESH_TOKEN` stellt - das Refresh Token bereit. + das Refresh-Token bereit. - Optional: `OPENCLAW_GOOGLE_MEET_CLIENT_SECRET`, `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN` und `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` verwenden dieselben Fallback-Namen @@ -885,7 +924,7 @@ Der Basis-Live-Smoke für Artefakte/Anwesenheit benötigt `https://www.googleapis.com/auth/meetings.space.readonly` und `https://www.googleapis.com/auth/meetings.conference.media.readonly`. Die Kalendersuche benötigt `https://www.googleapis.com/auth/calendar.events.readonly`. Der Export von Drive- -Dokumentinhalten benötigt +Dokumenttexten benötigt `https://www.googleapis.com/auth/drive.meet.readonly`. Erstellen Sie einen frischen Meet-Space: @@ -896,9 +935,9 @@ openclaw googlemeet create Der Befehl gibt die neue `meeting uri`, die Quelle und die Beitrittssitzung aus. Mit OAuth- Anmeldedaten verwendet er die offizielle Google Meet API. Ohne OAuth-Anmeldedaten verwendet er -als Fallback das angemeldete Browserprofil des gepinnten Chrome-Node. Agenten können +das angemeldete Browserprofil des angehefteten Chrome-Node als Fallback. Agenten können das `google_meet`-Tool mit `action: "create"` verwenden, um in einem Schritt zu erstellen und beizutreten. -Für eine reine URL-Erstellung übergeben Sie `"join": false`. +Für reine URL-Erstellung übergeben Sie `"join": false`. Beispiel-JSON-Ausgabe aus dem Browser-Fallback: @@ -920,7 +959,7 @@ Beispiel-JSON-Ausgabe aus dem Browser-Fallback: } ``` -Wenn der Browser-Fallback auf eine Google-Anmeldung oder eine Meet-Berechtigungssperre trifft, bevor er +Wenn der Browser-Fallback auf eine Google-Anmeldung oder einen Meet-Berechtigungsblocker stößt, bevor er die URL erstellen kann, gibt die Gateway-Methode eine fehlgeschlagene Antwort zurück und das `google_meet`-Tool gibt strukturierte Details statt einer einfachen Zeichenfolge zurück: @@ -942,7 +981,7 @@ die URL erstellen kann, gibt die Gateway-Methode eine fehlgeschlagene Antwort zu Wenn ein Agent `manualActionRequired: true` sieht, sollte er die `manualActionMessage` plus den Browser-Node-/Tab-Kontext melden und keine neuen -Meet-Tabs mehr öffnen, bis der Operator den Browserschritt abgeschlossen hat. +Meet-Tabs öffnen, bis der Operator den Browser-Schritt abgeschlossen hat. Beispiel-JSON-Ausgabe aus der API-Erstellung: @@ -965,22 +1004,13 @@ Beispiel-JSON-Ausgabe aus der API-Erstellung: } ``` -Das Erstellen eines Meet tritt standardmäßig bei. Der Chrome- oder Chrome-Node-Transport benötigt weiterhin -ein angemeldetes Google Chrome-Profil, um über den Browser beizutreten. Wenn das -Profil abgemeldet ist, meldet OpenClaw `manualActionRequired: true` oder einen -Browser-Fallback-Fehler und fordert den Operator auf, die Google-Anmeldung abzuschließen, bevor -erneut versucht wird. +Beim Erstellen eines Meet wird standardmäßig beigetreten. Der Chrome- oder Chrome-node-Transport benötigt weiterhin ein angemeldetes Google Chrome-Profil, um über den Browser beizutreten. Wenn das Profil abgemeldet ist, meldet OpenClaw `manualActionRequired: true` oder einen Browser-Fallback-Fehler und fordert den Operator auf, die Google-Anmeldung abzuschließen, bevor er es erneut versucht. -Setzen Sie `preview.enrollmentAcknowledged: true` nur, nachdem Sie bestätigt haben, dass Ihr Cloud- -Projekt, der OAuth-Prinzipal und die Meeting-Teilnehmer im Google -Workspace Developer Preview Program für Meet Media APIs registriert sind. +Setzen Sie `preview.enrollmentAcknowledged: true` erst, nachdem Sie bestätigt haben, dass Ihr Cloud-Projekt, OAuth-Prinzipal und die Besprechungsteilnehmer beim Google Workspace Developer Preview Program für Meet-Medien-APIs registriert sind. ## Konfiguration -Der gemeinsame Chrome-Agent-Pfad benötigt nur ein aktiviertes Plugin, BlackHole, SoX, einen -Schlüssel für einen Realtime-Transkriptions-Provider und einen konfigurierten OpenClaw-TTS-Provider. -OpenAI ist der standardmäßige Transkriptions-Provider; setzen Sie `realtime.provider: "google"`, -um Google Gemini Live für den `bidi`-Modus zu verwenden: +Der gemeinsame Chrome-Agent-Pfad benötigt nur ein aktiviertes Plugin, BlackHole, SoX, einen Schlüssel für einen Realtime-Transkriptions-Provider und einen konfigurierten OpenClaw-TTS-Provider. OpenAI ist der Standard-Transkriptions-Provider; setzen Sie `realtime.voiceProvider` auf `"google"` und `realtime.model`, um Google Gemini Live für den `bidi`-Modus zu verwenden, ohne den Standard-Transkriptions-Provider des Agent-Modus zu ändern: ```bash brew install blackhole-2ch sox @@ -1007,51 +1037,31 @@ Legen Sie die Plugin-Konfiguration unter `plugins.entries.google-meet.config` fe Standardwerte: - `defaultTransport: "chrome"` -- `defaultMode: "agent"` (`"realtime"` wird als Kompatibilitätsalias für - `"agent"` akzeptiert) -- `chromeNode.node`: optionale Node-ID, optionaler Node-Name oder optionale IP für `chrome-node` +- `defaultMode: "agent"` (`"realtime"` wird nur als Legacy-Kompatibilitätsalias für `"agent"` akzeptiert; neue Tool-Aufrufe sollten `"agent"` verwenden) +- `chromeNode.node`: optionale Node-ID, optionaler Name oder optionale IP für `chrome-node` - `chrome.audioBackend: "blackhole-2ch"` - `chrome.guestName: "OpenClaw Agent"`: Name, der auf dem Meet-Gastbildschirm im abgemeldeten Zustand verwendet wird -- `chrome.autoJoin: true`: bestmögliches Ausfüllen des Gastnamens und Klicken auf „Jetzt teilnehmen“ - über OpenClaw-Browserautomatisierung auf `chrome-node` -- `chrome.reuseExistingTab: true`: einen vorhandenen Meet-Tab aktivieren, statt - Duplikate zu öffnen -- `chrome.waitForInCallMs: 20000`: warten, bis der Meet-Tab meldet, dass er sich im Anruf befindet, - bevor die Echtzeit-Einführung ausgelöst wird -- `chrome.audioFormat: "pcm16-24khz"`: Audioformat für das Befehlspaar. Verwenden Sie - `"g711-ulaw-8khz"` nur für ältere oder benutzerdefinierte Befehlspaare, die noch - Telefonie-Audio ausgeben. -- `chrome.audioInputCommand`: SoX-Befehl, der aus CoreAudio `BlackHole 2ch` - liest und Audio in `chrome.audioFormat` schreibt -- `chrome.audioOutputCommand`: SoX-Befehl, der Audio in `chrome.audioFormat` - liest und nach CoreAudio `BlackHole 2ch` schreibt -- `chrome.bargeInInputCommand`: optionaler lokaler Mikrofonbefehl, der - vorzeichenbehaftetes 16-Bit-Little-Endian-Mono-PCM für die Erkennung menschlicher Unterbrechungen schreibt, - während die Assistentenwiedergabe aktiv ist. Dies gilt derzeit für die vom Gateway gehostete - `chrome`-Befehlspaar-Brücke. -- `chrome.bargeInRmsThreshold: 650`: RMS-Pegel, der als menschliche - Unterbrechung auf `chrome.bargeInInputCommand` zählt -- `chrome.bargeInPeakThreshold: 2500`: Spitzenpegel, der als menschliche - Unterbrechung auf `chrome.bargeInInputCommand` zählt -- `chrome.bargeInCooldownMs: 900`: Mindestverzögerung zwischen wiederholten - Löschungen menschlicher Unterbrechungen -- `mode: "agent"`: Standardmodus für Rücksprache. Sprache von Teilnehmern wird vom - konfigurierten Echtzeit-Transkriptions-Provider transkribiert, an den konfigurierten - OpenClaw-Agenten in einer Sub-Agent-Sitzung pro Meeting gesendet und über die - normale OpenClaw-TTS-Laufzeitumgebung zurückgesprochen. -- `mode: "bidi"`: Fallback-Modus für ein direktes bidirektionales Echtzeitmodell. Der - Echtzeit-Sprach-Provider beantwortet Teilnehmersprache direkt und kann - `openclaw_agent_consult` für tiefere, toolgestützte Antworten aufrufen. -- `mode: "transcribe"`: reiner Beobachtungsmodus ohne Rücksprache-Brücke. -- `realtime.provider: "openai"`: Provider-ID, die vom Modus `agent` für Echtzeit- - Transkription und vom Modus `bidi` für Echtzeit-Sprache verwendet wird. +- `chrome.autoJoin: true`: Best-Effort-Ausfüllen des Gastnamens und Klick auf „Jetzt teilnehmen“ über die OpenClaw-Browserautomatisierung auf `chrome-node` +- `chrome.reuseExistingTab: true`: einen vorhandenen Meet-Tab aktivieren, statt Duplikate zu öffnen +- `chrome.waitForInCallMs: 20000`: warten, bis der Meet-Tab meldet, dass er sich im Anruf befindet, bevor die Talkback-Einführung ausgelöst wird +- `chrome.audioFormat: "pcm16-24khz"`: Audioformat für Befehlspaare. Verwenden Sie `"g711-ulaw-8khz"` nur für Legacy- oder benutzerdefinierte Befehlspaare, die weiterhin Telefonie-Audio ausgeben. +- `chrome.audioBufferBytes: 4096`: SoX-Verarbeitungspuffer für generierte Chrome-Audiobefehle von Befehlspaaren. Dies ist die Hälfte des standardmäßigen 8192-Byte-Puffers von SoX, wodurch die Standard-Pipe-Latenz reduziert wird, während Spielraum bleibt, ihn auf ausgelasteten Hosts zu erhöhen. Werte unter dem SoX-Minimum werden auf 17 Byte begrenzt. +- `chrome.audioInputCommand`: SoX-Befehl, der von CoreAudio `BlackHole 2ch` liest und Audio in `chrome.audioFormat` schreibt +- `chrome.audioOutputCommand`: SoX-Befehl, der Audio in `chrome.audioFormat` liest und nach CoreAudio `BlackHole 2ch` schreibt +- `chrome.bargeInInputCommand`: optionaler lokaler Mikrofonbefehl, der vorzeichenbehaftetes 16-Bit-Little-Endian-Mono-PCM für die Erkennung menschlicher Unterbrechungen schreibt, während die Assistentenwiedergabe aktiv ist. Dies gilt derzeit für die vom Gateway gehostete `chrome`-Befehlspaar-Bridge. +- `chrome.bargeInRmsThreshold: 650`: RMS-Pegel, der bei `chrome.bargeInInputCommand` als menschliche Unterbrechung zählt +- `chrome.bargeInPeakThreshold: 2500`: Spitzenpegel, der bei `chrome.bargeInInputCommand` als menschliche Unterbrechung zählt +- `chrome.bargeInCooldownMs: 900`: Mindestverzögerung zwischen wiederholtem Aufheben menschlicher Unterbrechungen +- `mode: "agent"`: Standard-Talkback-Modus. Teilnehmersprache wird vom konfigurierten Realtime-Transkriptions-Provider transkribiert, in einer besprechungsspezifischen Sub-Agent-Sitzung an den konfigurierten OpenClaw-Agent gesendet und über die normale OpenClaw-TTS-Laufzeit zurückgesprochen. +- `mode: "bidi"`: Fallback-Modus für ein direktes bidirektionales Realtime-Modell. Der Realtime-Sprach-Provider beantwortet Teilnehmersprache direkt und kann `openclaw_agent_consult` für tiefere oder toolgestützte Antworten aufrufen. +- `mode: "transcribe"`: reiner Beobachtungsmodus ohne Talkback-Bridge. +- `realtime.provider: "openai"`: Kompatibilitäts-Fallback, der verwendet wird, wenn die unten stehenden bereichsbezogenen Provider-Felder nicht gesetzt sind. +- `realtime.transcriptionProvider: "openai"`: Provider-ID, die vom `agent`-Modus für Realtime-Transkription verwendet wird. +- `realtime.voiceProvider`: Provider-ID, die vom `bidi`-Modus für direkte Realtime-Sprache verwendet wird. Setzen Sie dies auf `"google"`, um Gemini Live zu verwenden, während die Transkription im Agent-Modus auf OpenAI bleibt. - `realtime.toolPolicy: "safe-read-only"` -- `realtime.instructions`: kurze gesprochene Antworten, mit - `openclaw_agent_consult` für tiefere Antworten -- `realtime.introMessage`: kurze gesprochene Bereitschaftsprüfung, wenn die Echtzeit-Brücke - eine Verbindung herstellt; setzen Sie dies auf `""`, um still beizutreten -- `realtime.agentId`: optionale OpenClaw-Agent-ID für - `openclaw_agent_consult`; Standardwert ist `main` +- `realtime.instructions`: kurze gesprochene Antworten, mit `openclaw_agent_consult` für tiefere Antworten +- `realtime.introMessage`: kurze gesprochene Bereitschaftsprüfung, wenn die Realtime-Bridge verbunden wird; setzen Sie dies auf `""`, um lautlos beizutreten +- `realtime.agentId`: optionale OpenClaw-Agent-ID für `openclaw_agent_consult`; Standardwert ist `main` Optionale Überschreibungen: @@ -1090,13 +1100,15 @@ Optionale Überschreibungen: }, defaultMode: "agent", realtime: { - provider: "google", + provider: "openai", + transcriptionProvider: "openai", + voiceProvider: "google", + model: "gemini-2.5-flash-native-audio-preview-12-2025", agentId: "jay", toolPolicy: "owner", introMessage: "Say exactly: I'm here.", providers: { google: { - model: "gemini-2.5-flash-native-audio-preview-12-2025", voice: "Kore", }, }, @@ -1104,6 +1116,45 @@ Optionale Überschreibungen: } ``` +ElevenLabs für Hören und Sprechen im Agent-Modus: + +```json5 +{ + messages: { + tts: { + provider: "elevenlabs", + providers: { + elevenlabs: { + modelId: "eleven_v3", + voiceId: "pMsXgVXv3BLzUgSXRplE", + }, + }, + }, + }, + plugins: { + entries: { + "google-meet": { + config: { + realtime: { + transcriptionProvider: "elevenlabs", + providers: { + elevenlabs: { + modelId: "scribe_v2_realtime", + audioFormat: "ulaw_8000", + sampleRate: 8000, + commitStrategy: "vad", + }, + }, + }, + }, + }, + }, + }, +} +``` + +Die persistente Meet-Stimme stammt aus `messages.tts.providers.elevenlabs.voiceId`. Agent-Antworten können außerdem antwortbezogene `[[tts:voiceId=... model=eleven_v3]]`-Direktiven verwenden, wenn TTS-Modellüberschreibungen aktiviert sind, aber die Konfiguration ist der deterministische Standard für Besprechungen. Beim Beitritt sollten die Logs `transcriptionProvider=elevenlabs` anzeigen, und jede gesprochene Antwort sollte `provider=elevenlabs model=eleven_v3 voice=` protokollieren. + Nur-Twilio-Konfiguration: ```json5 @@ -1119,16 +1170,11 @@ Nur-Twilio-Konfiguration: } ``` -`voiceCall.enabled` ist standardmäßig `true`; mit Twilio-Transport delegiert es den -eigentlichen PSTN-Anruf, DTMF und die Begrüßung an das Voice Call-Plugin. Voice Call -spielt die DTMF-Sequenz ab, bevor der Echtzeit-Medienstrom geöffnet wird, und verwendet dann den -gespeicherten Einführungstext als erste Echtzeit-Begrüßung. Wenn `voice-call` nicht -aktiviert ist, kann Google Meet den Wählplan weiterhin validieren und aufzeichnen, aber den -Twilio-Anruf nicht platzieren. +`voiceCall.enabled` ist standardmäßig `true`; mit Twilio-Transport delegiert es den eigentlichen PSTN-Anruf, DTMF und die Einführungsbegrüßung an das Voice Call-Plugin. Voice Call spielt die DTMF-Sequenz ab, bevor der Realtime-Medienstrom geöffnet wird, und verwendet dann den gespeicherten Einführungstext als erste Realtime-Begrüßung. Wenn `voice-call` nicht aktiviert ist, kann Google Meet den Wählplan weiterhin validieren und aufzeichnen, den Twilio-Anruf jedoch nicht platzieren. -## Werkzeug +## Tool -Agenten können das Tool `google_meet` verwenden: +Agenten können das `google_meet`-Tool verwenden: ```json { @@ -1139,43 +1185,20 @@ Agenten können das Tool `google_meet` verwenden: } ``` -Verwenden Sie `transport: "chrome"`, wenn Chrome auf dem Gateway-Host ausgeführt wird. Verwenden Sie -`transport: "chrome-node"`, wenn Chrome auf einer gekoppelten Node wie einer Parallels- -VM ausgeführt wird. In beiden Fällen laufen die Modell-Provider und `openclaw_agent_consult` auf dem -Gateway-Host, sodass Modell-Zugangsdaten dort verbleiben. Mit dem standardmäßigen `mode: "agent"` -übernimmt der Echtzeit-Transkriptions-Provider das Zuhören, der konfigurierte OpenClaw- -Agent erzeugt die Antwort, und reguläres OpenClaw-TTS spricht sie in Meet. Verwenden Sie -`mode: "bidi"`, wenn das Echtzeit-Sprachmodell direkt antworten soll. -`mode: "realtime"` wird weiterhin als Kompatibilitätsalias für -`mode: "agent"` akzeptiert. +Verwenden Sie `transport: "chrome"`, wenn Chrome auf dem Gateway-Host läuft. Verwenden Sie `transport: "chrome-node"`, wenn Chrome auf einer gekoppelten Node wie einer Parallels-VM läuft. In beiden Fällen laufen die Modell-Provider und `openclaw_agent_consult` auf dem Gateway-Host, sodass Modell-Anmeldedaten dort bleiben. Mit dem standardmäßigen `mode: "agent"` übernimmt der Realtime-Transkriptions-Provider das Zuhören, der konfigurierte OpenClaw-Agent erzeugt die Antwort, und reguläres OpenClaw-TTS spricht sie in Meet. Verwenden Sie `mode: "bidi"`, wenn das Realtime-Sprachmodell direkt antworten soll. Der rohe Wert `mode: "realtime"` wird weiterhin als Legacy-Kompatibilitätsalias für `mode: "agent"` akzeptiert, aber im Agent-Tool-Schema nicht mehr beworben. Logs im Agent-Modus enthalten beim Bridge-Start den aufgelösten Transkriptions-Provider und das Modell sowie nach jeder synthetisierten Antwort den TTS-Provider, das Modell, die Stimme, das Ausgabeformat und die Abtastrate. -Verwenden Sie `action: "status"`, um aktive Sitzungen aufzulisten oder eine Sitzungs-ID zu prüfen. Verwenden Sie -`action: "speak"` mit `sessionId` und `message`, damit der Echtzeit-Agent -sofort spricht. Verwenden Sie `action: "test_speech"`, um die Sitzung zu erstellen oder wiederzuverwenden, -eine bekannte Phrase auszulösen und den Zustand `inCall` zurückzugeben, wenn der Chrome-Host ihn -melden kann. `test_speech` erzwingt immer `mode: "agent"` und schlägt fehl, wenn es aufgefordert wird, -in `mode: "transcribe"` zu laufen, da reine Beobachtungssitzungen absichtlich keine -Sprache ausgeben können. Das Ergebnis `speechOutputVerified` basiert darauf, dass die Echtzeit-Audioausgabe- -Bytes während dieses Testaufrufs zunehmen, sodass eine wiederverwendete Sitzung mit älterem Audio -nicht als frische erfolgreiche Sprachprüfung zählt. Verwenden Sie `action: "leave"`, um -eine Sitzung als beendet zu markieren. +Verwenden Sie `action: "status"`, um aktive Sitzungen aufzulisten oder eine Sitzungs-ID zu prüfen. Verwenden Sie `action: "speak"` mit `sessionId` und `message`, damit der Realtime-Agent sofort spricht. Verwenden Sie `action: "test_speech"`, um die Sitzung zu erstellen oder wiederzuverwenden, eine bekannte Phrase auszulösen und den `inCall`-Zustand zurückzugeben, wenn der Chrome-Host ihn melden kann. `test_speech` erzwingt immer `mode: "agent"` und schlägt fehl, wenn die Ausführung in `mode: "transcribe"` angefordert wird, da reine Beobachtungssitzungen absichtlich keine Sprache ausgeben können. Das Ergebnis `speechOutputVerified` basiert darauf, dass die Realtime-Audioausgabebytes während dieses Testaufrufs zunehmen; daher zählt eine wiederverwendete Sitzung mit älterem Audio nicht als neue erfolgreiche Sprachprüfung. Verwenden Sie `action: "leave"`, um eine Sitzung als beendet zu markieren. -`status` enthält Chrome-Zustand, wenn verfügbar: +`status` enthält Chrome-Zustandsdaten, wenn verfügbar: -- `inCall`: Chrome scheint sich innerhalb des Meet-Anrufs zu befinden -- `micMuted`: bestmöglicher Meet-Mikrofonstatus -- `manualActionRequired` / `manualActionReason` / `manualActionMessage`: das - Browserprofil benötigt manuelle Anmeldung, Meet-Host-Zulassung, Berechtigungen oder - Browsersteuerungsreparatur, bevor Sprache funktionieren kann -- `speechReady` / `speechBlockedReason` / `speechBlockedMessage`: ob - verwaltete Chrome-Sprache jetzt erlaubt ist. `speechReady: false` bedeutet, dass OpenClaw - die Einführungs- oder Testphrase nicht in die Audio-Brücke gesendet hat. -- `providerConnected` / `realtimeReady`: Zustand der Echtzeit-Sprachbrücke -- `lastInputAt` / `lastOutputAt`: zuletzt von der Brücke gesehenes oder an sie gesendetes Audio -- `audioOutputRouted` / `audioOutputDeviceLabel`: ob die Medienausgabe des Meet-Tabs - aktiv an das von der Brücke verwendete BlackHole-Gerät geleitet wurde -- `lastSuppressedInputAt` / `suppressedInputBytes`: local loopback-Eingabe, die ignoriert wurde, während - Assistentenwiedergabe aktiv ist +- `inCall`: Chrome scheint sich im Meet-Anruf zu befinden +- `micMuted`: Best-Effort-Zustand des Meet-Mikrofons +- `manualActionRequired` / `manualActionReason` / `manualActionMessage`: das Browserprofil benötigt eine manuelle Anmeldung, Zulassung durch den Meet-Host, Berechtigungen oder eine Browsersteuerungsreparatur, bevor Sprache funktionieren kann +- `speechReady` / `speechBlockedReason` / `speechBlockedMessage`: ob verwaltete Chrome-Sprache jetzt erlaubt ist. `speechReady: false` bedeutet, dass OpenClaw die Einführungs- oder Testphrase nicht in die Audio-Bridge gesendet hat. +- `providerConnected` / `realtimeReady`: Zustand der Realtime-Sprach-Bridge +- `lastInputAt` / `lastOutputAt`: zuletzt von der Bridge gesehenes oder an sie gesendetes Audio +- `audioOutputRouted` / `audioOutputDeviceLabel`: ob die Medienausgabe des Meet-Tabs aktiv an das von der Bridge verwendete BlackHole-Gerät geleitet wurde +- `lastSuppressedInputAt` / `suppressedInputBytes`: local loopback-Eingabe, die ignoriert wurde, während die Assistentenwiedergabe aktiv ist ```json { @@ -1187,37 +1210,41 @@ eine Sitzung als beendet zu markieren. ## Agent- und Bidi-Modi -Der Chrome-Modus `agent` ist für das Verhalten „mein Agent ist im Meeting“ optimiert. Der -Echtzeit-Transkriptions-Provider hört das Meeting-Audio, finale Teilnehmer- -Transkripte werden an den konfigurierten OpenClaw-Agenten weitergeleitet, und die Antwort wird -über die normale OpenClaw-TTS-Laufzeitumgebung gesprochen. Setzen Sie `mode: "bidi"`, wenn -das Echtzeit-Sprachmodell direkt antworten soll. -Nahe beieinanderliegende finale Transkriptfragmente werden vor der Konsultation zusammengeführt, damit eine gesprochene -Äußerung nicht mehrere veraltete Teilantworten erzeugt. Echtzeit-Eingabe wird außerdem -unterdrückt, während in die Warteschlange gestelltes Assistenten-Audio noch abgespielt wird, -und kürzliche assistentenähnliche Transkript-Echos werden vor der Agentenkonsultation ignoriert, -damit der BlackHole-local loopback den Agenten nicht seine eigene Sprache beantworten lässt. +Der Chrome-`agent`-Modus ist für das Verhalten „mein Agent ist in der Besprechung“ optimiert. Der Realtime-Transkriptions-Provider hört das Besprechungsaudio, finale Teilnehmertranskripte werden durch den konfigurierten OpenClaw-Agent geleitet, und die Antwort wird über die normale OpenClaw-TTS-Laufzeit gesprochen. Setzen Sie `mode: "bidi"`, wenn das Realtime-Sprachmodell direkt antworten soll. Nahe beieinanderliegende finale Transkriptfragmente werden vor der Konsultation zusammengeführt, damit ein gesprochener Turn nicht mehrere veraltete Teilantworten erzeugt. Realtime-Eingabe wird außerdem unterdrückt, während in die Warteschlange gestelltes Assistentenaudio noch abgespielt wird, und kürzliche assistentenähnliche Transkript-Echos werden vor der Agent-Konsultation ignoriert, damit BlackHole-local loopback nicht dazu führt, dass der Agent auf seine eigene Sprache antwortet. -| Modus | Wer die Antwort entscheidet | Sprachausgabepfad | Verwenden Sie dies, wenn | -| ------- | --------------------------------- | ------------------------------------- | --------------------------------------------------------- | -| `agent` | Der konfigurierte OpenClaw-Agent | Normale OpenClaw-TTS-Laufzeitumgebung | Sie Verhalten wie „mein Agent ist im Meeting“ möchten | -| `bidi` | Das Echtzeit-Sprachmodell | Audioantwort des Echtzeit-Sprach-Providers | Sie die Gesprächsschleife mit der niedrigsten Latenz möchten | +| Modus | Wer die Antwort bestimmt | Sprachausgabepfad | Verwendung, wenn | +| ------- | ----------------------------- | ------------------------------------- | ----------------------------------------------------- | +| `agent` | Der konfigurierte OpenClaw-Agent | Normale OpenClaw-TTS-Laufzeit | Sie das Verhalten „mein Agent ist in der Besprechung“ wünschen | +| `bidi` | Das Realtime-Sprachmodell | Audioantwort des Realtime-Sprach-Providers | Sie die Sprach-Konversationsschleife mit der niedrigsten Latenz wünschen | -Im `bidi`-Modus kann das Echtzeitmodell `openclaw_agent_consult` aufrufen, wenn es tiefergehendes Reasoning, aktuelle Informationen oder normale OpenClaw-Tools benötigt. +Im `bidi`-Modus kann das Realtime-Modell `openclaw_agent_consult` aufrufen, wenn es tieferes Reasoning, aktuelle Informationen oder normale OpenClaw-Tools benötigt. -Das Consult-Tool führt im Hintergrund den regulären OpenClaw-Agenten mit aktuellem Meeting-Transkriptkontext aus und gibt eine knappe gesprochene Antwort zurück. Im `agent`-Modus sendet OpenClaw diese Antwort direkt an die TTS-Runtime; im `bidi`-Modus kann das Echtzeit-Sprachmodell das Consult-Ergebnis zurück in das Meeting sprechen. Es verwendet dieselbe gemeinsame Consult-Mechanik wie Voice Call. +Das Consult-Tool führt im Hintergrund den regulären OpenClaw-Agent mit dem aktuellen Kontext des +Meeting-Transkripts aus und gibt eine prägnante gesprochene Antwort zurück. Im Modus `agent` +sendet OpenClaw diese Antwort direkt an die TTS-Laufzeit; im Modus `bidi` kann das +Realtime-Sprachmodell das Consult-Ergebnis in das Meeting zurücksprechen. Es verwendet +dieselbe gemeinsame Consult-Mechanik wie Voice Call. -Standardmäßig werden Consult-Aufrufe gegen den `main`-Agenten ausgeführt. Setzen Sie `realtime.agentId`, wenn eine Meet-Lane einen dedizierten OpenClaw-Agent-Workspace, Modellstandards, Tool-Richtlinie, Memory und Sitzungsverlauf verwenden soll. +Standardmäßig werden Consults mit dem Agent `main` ausgeführt. Legen Sie `realtime.agentId` fest, wenn eine +Meet-Lane einen dedizierten OpenClaw-Agent-Workspace, Modellvorgaben, +Tool-Richtlinie, Speicher und Sitzungsverlauf verwenden soll. -Consult-Aufrufe im Agent-Modus verwenden einen sitzungsbezogenen Sitzungsschlüssel `agent::subagent:google-meet:`, damit Folgefragen den Meeting-Kontext behalten und gleichzeitig die normale Agent-Richtlinie vom konfigurierten Agenten übernehmen. +Consults im Agent-Modus verwenden einen sitzungsspezifischen Schlüssel +`agent::subagent:google-meet:` pro Meeting, sodass Folgefragen den +Meeting-Kontext beibehalten und zugleich die normale Agent-Richtlinie vom konfigurierten +Agent übernehmen. `realtime.toolPolicy` steuert den Consult-Lauf: -- `safe-read-only`: Das Consult-Tool bereitstellen und den regulären Agenten auf `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` und `memory_get` beschränken. -- `owner`: Das Consult-Tool bereitstellen und dem regulären Agenten die normale Agent-Tool-Richtlinie erlauben. -- `none`: Das Consult-Tool dem Echtzeit-Sprachmodell nicht bereitstellen. +- `safe-read-only`: stellt das Consult-Tool bereit und beschränkt den regulären Agent auf + `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` und + `memory_get`. +- `owner`: stellt das Consult-Tool bereit und erlaubt dem regulären Agent, die normale + Agent-Tool-Richtlinie zu verwenden. +- `none`: stellt dem Realtime-Sprachmodell das Consult-Tool nicht bereit. -Der Consult-Sitzungsschlüssel ist pro Meet-Sitzung begrenzt, sodass nachfolgende Consult-Aufrufe während desselben Meetings vorherigen Consult-Kontext wiederverwenden können. +Der Consult-Sitzungsschlüssel ist pro Meet-Sitzung abgegrenzt, sodass nachfolgende Consult-Aufrufe +während desselben Meetings den vorherigen Consult-Kontext wiederverwenden können. Um eine gesprochene Bereitschaftsprüfung zu erzwingen, nachdem Chrome dem Anruf vollständig beigetreten ist: @@ -1225,7 +1252,7 @@ Um eine gesprochene Bereitschaftsprüfung zu erzwingen, nachdem Chrome dem Anruf openclaw googlemeet speak meet_... "Say exactly: I'm here and listening." ``` -Für den vollständigen Join-and-Speak-Smoke: +Für den vollständigen Beitreten-und-Sprechen-Smoke: ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ @@ -1235,7 +1262,7 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ ## Live-Test-Checkliste -Verwenden Sie diese Sequenz, bevor Sie ein Meeting an einen unbeaufsichtigten Agenten übergeben: +Verwenden Sie diese Abfolge, bevor Sie ein Meeting an einen unbeaufsichtigten Agent übergeben: ```bash openclaw googlemeet setup @@ -1245,15 +1272,18 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ --message "Say exactly: Google Meet speech test complete." ``` -Erwarteter Chrome-Node-Status: +Erwarteter Chrome-node-Zustand: - `googlemeet setup` ist vollständig grün. -- `googlemeet setup` enthält `chrome-node-connected`, wenn Chrome-node der Standardtransport ist oder eine Node festgelegt ist. -- `nodes status` zeigt, dass die ausgewählte Node verbunden ist. -- Die ausgewählte Node bewirbt sowohl `googlemeet.chrome` als auch `browser.proxy`. -- Der Meet-Tab tritt dem Anruf bei, und `test-speech` gibt Chrome-Health mit `inCall: true` zurück. +- `googlemeet setup` enthält `chrome-node-connected`, wenn Chrome-node der + Standard-Transport ist oder ein Node festgelegt wurde. +- `nodes status` zeigt den ausgewählten Node als verbunden an. +- Der ausgewählte Node gibt sowohl `googlemeet.chrome` als auch `browser.proxy` bekannt. +- Der Meet-Tab tritt dem Anruf bei und `test-speech` gibt den Chrome-Zustand mit + `inCall: true` zurück. -Für einen Remote-Chrome-Host wie eine Parallels-macOS-VM ist dies die kürzeste sichere Prüfung nach dem Aktualisieren des Gateway oder der VM: +Für einen Remote-Chrome-Host wie eine Parallels-macOS-VM ist dies die kürzeste +sichere Prüfung nach dem Aktualisieren des Gateway oder der VM: ```bash openclaw googlemeet setup @@ -1264,9 +1294,11 @@ openclaw nodes invoke \ --params '{"action":"setup"}' ``` -Das belegt, dass das Gateway-Plugin geladen ist, die VM-Node mit dem aktuellen Token verbunden ist und die Meet-Audio-Bridge verfügbar ist, bevor ein Agent einen echten Meeting-Tab öffnet. +Das weist nach, dass das Gateway-Plugin geladen ist, der VM-Node mit dem +aktuellen Token verbunden ist und die Meet-Audio-Bridge verfügbar ist, bevor ein Agent einen +echten Meeting-Tab öffnet. -Für einen Twilio-Smoke verwenden Sie ein Meeting, das Telefoneinwahldaten bereitstellt: +Verwenden Sie für einen Twilio-Smoke ein Meeting, das Telefoneinwahldaten bereitstellt: ```bash openclaw googlemeet setup @@ -1276,19 +1308,19 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --pin 123456 ``` -Erwarteter Twilio-Status: +Erwarteter Twilio-Zustand: - `googlemeet setup` enthält grüne Prüfungen für `twilio-voice-call-plugin`, `twilio-voice-call-credentials` und `twilio-voice-call-webhook`. -- `voicecall` ist nach dem Neuladen des Gateway in der CLI verfügbar. +- `voicecall` ist nach dem Gateway-Neuladen in der CLI verfügbar. - Die zurückgegebene Sitzung hat `transport: "twilio"` und eine `twilio.voiceCallId`. -- `openclaw logs --follow` zeigt, dass DTMF-TwiML vor Echtzeit-TwiML bereitgestellt wurde, danach eine - Echtzeit-Bridge mit der eingereihten ersten Begrüßung. +- `openclaw logs --follow` zeigt, dass DTMF-TwiML vor Realtime-TwiML bereitgestellt wurde, anschließend eine + Realtime-Bridge mit eingereihter erster Begrüßung. - `googlemeet leave ` legt den delegierten Sprachanruf auf. ## Fehlerbehebung -### Agent kann das Google Meet-Tool nicht sehen +### Agent kann das Google-Meet-Tool nicht sehen Bestätigen Sie, dass das Plugin in der Gateway-Konfiguration aktiviert ist, und laden Sie das Gateway neu: @@ -1301,15 +1333,15 @@ Wenn Sie gerade `plugins.entries.google-meet` bearbeitet haben, starten oder lad Der laufende Agent sieht nur Plugin-Tools, die vom aktuellen Gateway-Prozess registriert wurden. -Auf nicht-macOS-Gateway-Hosts bleibt das agentenseitige Tool `google_meet` sichtbar, -aber lokale Chrome-Rücksprechaktionen werden blockiert, bevor sie die Audio-Bridge erreichen. -Lokales Chrome-Rücksprech-Audio hängt derzeit von macOS `BlackHole 2ch` ab. Daher -sollten Linux-Agenten `mode: "transcribe"`, Twilio-Einwahl oder stattdessen einen macOS- +Auf Nicht-macOS-Gateway-Hosts bleibt das agentseitige Tool `google_meet` sichtbar, +aber lokale Chrome-Talkback-Aktionen werden blockiert, bevor sie die Audio-Bridge erreichen. +Lokales Chrome-Talkback-Audio hängt derzeit von macOS `BlackHole 2ch` ab, daher +sollten Linux-Agents `mode: "transcribe"`, Twilio-Einwahl oder einen macOS- `chrome-node`-Host anstelle des standardmäßigen lokalen Chrome-Agent-Pfads verwenden. -### Kein verbundener Google Meet-fähiger Node +### Kein verbundener Google-Meet-fähiger Node -Führen Sie auf dem Node-Host aus: +Führen Sie auf dem Node-Host Folgendes aus: ```bash openclaw plugins enable google-meet @@ -1327,7 +1359,7 @@ openclaw nodes status ``` Der Node muss verbunden sein und `googlemeet.chrome` sowie `browser.proxy` auflisten. -Die Gateway-Konfiguration muss diese Node-Befehle erlauben: +Die Gateway-Konfiguration muss diese Node-Befehle zulassen: ```json5 { @@ -1339,7 +1371,7 @@ Die Gateway-Konfiguration muss diese Node-Befehle erlauben: } ``` -Wenn `googlemeet setup` bei `chrome-node-connected` fehlschlägt oder das Gateway-Protokoll +Wenn `googlemeet setup` bei `chrome-node-connected` fehlschlägt oder das Gateway-Log `gateway token mismatch` meldet, installieren oder starten Sie den Node mit dem aktuellen Gateway- Token neu. Für ein LAN-Gateway bedeutet das normalerweise: @@ -1359,98 +1391,99 @@ openclaw googlemeet setup openclaw nodes status --connected ``` -### Browser wird geöffnet, aber Agent kann nicht beitreten +### Browser öffnet sich, aber Agent kann nicht beitreten -Führen Sie `googlemeet test-listen` für reine Beobachtungsbeitritte oder `googlemeet test-speech` -für Echtzeitbeitritte aus, und prüfen Sie anschließend die zurückgegebene Chrome-Zustandsprüfung. Wenn eine der beiden Prüfungen +Führen Sie `googlemeet test-listen` für reine Beobachterbeitritte oder `googlemeet test-speech` +für Realtime-Beitritte aus und prüfen Sie anschließend den zurückgegebenen Chrome-Zustand. Wenn eine der Prüfungen `manualActionRequired: true` meldet, zeigen Sie dem Bediener `manualActionMessage` -an und beenden Sie Wiederholungen, bis die Browseraktion abgeschlossen ist. +an und beenden Sie Wiederholungen, bis die Browser-Aktion abgeschlossen ist. Häufige manuelle Aktionen: -- Beim Chrome-Profil anmelden. -- Den Gast über das Meet-Hostkonto zulassen. -- Chrome-Mikrofon-/Kameraberechtigungen erteilen, wenn die native Berechtigungsabfrage - von Chrome erscheint. -- Einen hängenden Meet-Berechtigungsdialog schließen oder reparieren. +- Melden Sie sich im Chrome-Profil an. +- Lassen Sie den Gast über das Meet-Host-Konto zu. +- Gewähren Sie Chrome Mikrofon-/Kameraberechtigungen, wenn die native Berechtigungsabfrage + von Chrome angezeigt wird. +- Schließen oder reparieren Sie einen festhängenden Meet-Berechtigungsdialog. Melden Sie nicht „nicht angemeldet“, nur weil Meet „Do you want people to -hear you in the meeting?“ anzeigt. Das ist Meets Zwischenschritt zur Audioauswahl; OpenClaw -klickt **Use microphone** per Browserautomatisierung, wenn verfügbar, und wartet weiter -auf den tatsächlichen Meeting-Status. Für den Browser-Fallback nur zur Erstellung kann OpenClaw -**Continue without microphone** klicken, weil das Erstellen der URL den Echtzeit-Audiopfad nicht benötigt. +hear you in the meeting?“ anzeigt. Das ist der Meet-Zwischenschritt zur Audioauswahl; OpenClaw +klickt per Browser-Automatisierung auf **Use microphone**, sofern verfügbar, und wartet weiter +auf den echten Meeting-Zustand. Beim reinen Erstellungs-Browser-Fallback kann OpenClaw +auf **Continue without microphone** klicken, weil das Erstellen der URL den +Realtime-Audiopfad nicht benötigt. ### Meeting-Erstellung schlägt fehl -`googlemeet create` verwendet zuerst den Google Meet API-Endpunkt `spaces.create`, +`googlemeet create` verwendet zuerst den Google-Meet-API-Endpunkt `spaces.create`, wenn OAuth-Anmeldedaten konfiguriert sind. Ohne OAuth-Anmeldedaten fällt es -auf den angehefteten Chrome-Node-Browser zurück. Bestätigen Sie: +auf den festgelegten Chrome-Node-Browser zurück. Bestätigen Sie: - Für API-Erstellung: `oauth.clientId` und `oauth.refreshToken` sind konfiguriert, oder passende Umgebungsvariablen `OPENCLAW_GOOGLE_MEET_*` sind vorhanden. -- Für API-Erstellung: Das Refresh-Token wurde erstellt, nachdem Erstellungsunterstützung - hinzugefügt wurde. Ältere Tokens enthalten möglicherweise nicht den Scope `meetings.space.created`; führen Sie +- Für API-Erstellung: Das Refresh-Token wurde erstellt, nachdem Unterstützung für Erstellung + hinzugefügt wurde. Älteren Tokens fehlt möglicherweise der Scope `meetings.space.created`; führen Sie `openclaw googlemeet auth login --json` erneut aus und aktualisieren Sie die Plugin-Konfiguration. - Für Browser-Fallback: `defaultTransport: "chrome-node"` und `chromeNode.node` zeigen auf einen verbundenen Node mit `browser.proxy` und `googlemeet.chrome`. -- Für Browser-Fallback: Das OpenClaw-Chrome-Profil auf diesem Node ist bei Google angemeldet - und kann `https://meet.google.com/new` öffnen. -- Für Browser-Fallback: Wiederholungen verwenden einen vorhandenen `https://meet.google.com/new`- - oder Google-Konto-Aufforderungs-Tab erneut, bevor ein neuer Tab geöffnet wird. Wenn ein Agent eine Zeitüberschreitung erreicht, +- Für Browser-Fallback: Das OpenClaw-Chrome-Profil auf diesem Node ist bei + Google angemeldet und kann `https://meet.google.com/new` öffnen. +- Für Browser-Fallback: Wiederholungen verwenden einen bestehenden Tab + `https://meet.google.com/new` oder einen Google-Konto-Abfragetab wieder, bevor ein neuer Tab geöffnet wird. Wenn ein Agent ein Timeout erreicht, wiederholen Sie den Tool-Aufruf, statt manuell einen weiteren Meet-Tab zu öffnen. - Für Browser-Fallback: Wenn das Tool `manualActionRequired: true` zurückgibt, verwenden Sie die zurückgegebenen Werte `browser.nodeId`, `browser.targetId`, `browserUrl` und `manualActionMessage`, um den Bediener anzuleiten. Wiederholen Sie nicht in einer Schleife, bis diese Aktion abgeschlossen ist. - Für Browser-Fallback: Wenn Meet „Do you want people to hear you in the - meeting?“ anzeigt, lassen Sie den Tab geöffnet. OpenClaw sollte per Browserautomatisierung - **Use microphone** oder, beim Fallback nur zur Erstellung, **Continue without microphone** - klicken und weiter auf die generierte Meet-URL warten. Wenn das nicht möglich ist, sollte der - Fehler `meet-audio-choice-required` erwähnen, nicht `google-login-required`. + meeting?“ anzeigt, lassen Sie den Tab geöffnet. OpenClaw sollte per Browser- + Automatisierung auf **Use microphone** oder, beim reinen Erstellungs-Fallback, auf **Continue without microphone** + klicken und weiter auf die generierte Meet-URL warten. Wenn das nicht gelingt, sollte der + Fehler `meet-audio-choice-required` und nicht `google-login-required` erwähnen. ### Agent tritt bei, spricht aber nicht -Prüfen Sie den Echtzeitpfad: +Prüfen Sie den Realtime-Pfad: ```bash openclaw googlemeet setup openclaw googlemeet doctor ``` -Verwenden Sie `mode: "agent"` für den normalen Pfad STT -> OpenClaw-Agent -> TTS-Rücksprache -oder `mode: "bidi"` für den direkten Echtzeit-Sprach-Fallback. `mode: "transcribe"` -startet die Rücksprech-Bridge absichtlich nicht. Für reine Beobachtungsdiagnosen -führen Sie `openclaw googlemeet status --json ` aus, nachdem Teilnehmende gesprochen haben, +Verwenden Sie `mode: "agent"` für den normalen Pfad STT -> OpenClaw-Agent -> TTS-Talkback +oder `mode: "bidi"` für den direkten Realtime-Sprach-Fallback. `mode: "transcribe"` +startet die Talkback-Bridge absichtlich nicht. Führen Sie für reine Beobachter-Debugs +`openclaw googlemeet status --json ` aus, nachdem Teilnehmende gesprochen haben, und prüfen Sie `captioning`, `transcriptLines` und `lastCaptionText`. Wenn `inCall` -true ist, aber `transcriptLines` bei `0` bleibt, sind Meet-Untertitel möglicherweise deaktiviert, niemand -hat gesprochen, seit der Beobachter installiert wurde, die Meet-Benutzeroberfläche hat sich geändert, oder Live- -Untertitel sind für die Meetingsprache bzw. das Konto nicht verfügbar. +true ist, aber `transcriptLines` bei `0` bleibt, sind Meet-Untertitel möglicherweise deaktiviert, seit der +Beobachter installiert wurde hat niemand gesprochen, die Meet-Oberfläche hat sich geändert oder Live- +Untertitel sind für die Meeting-Sprache/das Konto nicht verfügbar. -`googlemeet test-speech` prüft immer den Echtzeitpfad und meldet, ob -Bridge-Ausgabebytes für diesen Aufruf beobachtet wurden. Wenn `speechOutputVerified` false und -`speechOutputTimedOut` true ist, hat der Echtzeit-Provider die -Äußerung möglicherweise akzeptiert, aber OpenClaw hat keine neuen Ausgabebytes gesehen, die die Chrome-Audio- -Bridge erreichen. +`googlemeet test-speech` prüft immer den Realtime-Pfad und meldet, ob +Bridge-Ausgabebytes für diesen Aufruf beobachtet wurden. Wenn `speechOutputVerified` false ist und +`speechOutputTimedOut` true ist, hat der Realtime-Provider die +Äußerung möglicherweise angenommen, aber OpenClaw hat keine neuen Ausgabebytes zur Chrome-Audio- +Bridge gelangen sehen. Überprüfen Sie außerdem: -- Auf dem Gateway-Host ist ein Echtzeit-Provider-Schlüssel verfügbar, etwa +- Ein Realtime-Provider-Schlüssel ist auf dem Gateway-Host verfügbar, etwa `OPENAI_API_KEY` oder `GEMINI_API_KEY`. - `BlackHole 2ch` ist auf dem Chrome-Host sichtbar. - `sox` ist auf dem Chrome-Host vorhanden. -- Meet-Mikrofon und -Lautsprecher werden über den von OpenClaw verwendeten virtuellen Audiopfad - geleitet. `doctor` sollte für lokale Chrome-Echtzeitbeitritte `meet output routed: yes` anzeigen. +- Meet-Mikrofon und -Lautsprecher sind über den von OpenClaw verwendeten virtuellen Audiopfad geroutet. + `doctor` sollte bei lokalen Chrome-Realtime-Beitritten `meet output routed: yes` anzeigen. -`googlemeet doctor [session-id]` gibt Sitzung, Node, Anrufstatus, -Grund für manuelle Aktion, Echtzeit-Provider-Verbindung, `realtimeReady`, Audio- -Eingabe-/Ausgabeaktivität, letzte Audio-Zeitstempel, Bytezähler und Browser-URL aus. +`googlemeet doctor [session-id]` gibt Sitzung, Node, In-Call-Zustand, +Grund für manuelle Aktion, Realtime-Provider-Verbindung, `realtimeReady`, Audio- +Ein-/Ausgabeaktivität, letzte Audio-Zeitstempel, Byte-Zähler und Browser-URL aus. Verwenden Sie `googlemeet status [session-id] --json`, wenn Sie das rohe JSON benötigen. Verwenden Sie -`googlemeet doctor --oauth`, wenn Sie die Google Meet-OAuth-Aktualisierung -ohne Offenlegung von Tokens überprüfen müssen; fügen Sie `--meeting` oder `--create-space` hinzu, wenn Sie außerdem einen -Google Meet API-Nachweis benötigen. +`googlemeet doctor --oauth`, wenn Sie die Google-Meet-OAuth-Aktualisierung prüfen müssen, +ohne Tokens offenzulegen; fügen Sie `--meeting` oder `--create-space` hinzu, wenn Sie außerdem einen +Google-Meet-API-Nachweis benötigen. -Wenn ein Agent eine Zeitüberschreitung erreicht hat und Sie bereits einen geöffneten Meet-Tab sehen, prüfen Sie diesen Tab, +Wenn ein Agent ein Timeout erreicht hat und Sie sehen können, dass bereits ein Meet-Tab geöffnet ist, prüfen Sie diesen Tab, ohne einen weiteren zu öffnen: ```bash @@ -1459,21 +1492,21 @@ openclaw googlemeet recover-tab https://meet.google.com/abc-defg-hij ``` Die entsprechende Tool-Aktion ist `recover_current_tab`. Sie fokussiert und prüft einen -vorhandenen Meet-Tab für den ausgewählten Transport. Mit `chrome` verwendet sie lokale +bestehenden Meet-Tab für den ausgewählten Transport. Mit `chrome` verwendet sie lokale Browsersteuerung über das Gateway; mit `chrome-node` verwendet sie den konfigurierten Chrome-Node. Sie öffnet keinen neuen Tab und erstellt keine neue Sitzung; sie meldet den -aktuellen Blocker, etwa Anmeldung, Zulassung, Berechtigungen oder Audioauswahlstatus. +aktuellen Blocker, etwa Anmeldung, Zulassung, Berechtigungen oder Audioauswahlzustand. Der CLI-Befehl spricht mit dem konfigurierten Gateway, daher muss das Gateway laufen; `chrome-node` erfordert außerdem, dass der Chrome-Node verbunden ist. ### Twilio-Einrichtungsprüfungen schlagen fehl `twilio-voice-call-plugin` schlägt fehl, wenn `voice-call` nicht erlaubt oder nicht aktiviert ist. -Fügen Sie es zu `plugins.allow` hinzu, aktivieren Sie `plugins.entries.voice-call`, und laden Sie das +Fügen Sie es zu `plugins.allow` hinzu, aktivieren Sie `plugins.entries.voice-call` und laden Sie das Gateway neu. `twilio-voice-call-credentials` schlägt fehl, wenn dem Twilio-Backend Konto- -SID, Auth-Token oder Anrufernummer fehlen. Setzen Sie diese auf dem Gateway-Host: +SID, Auth-Token oder Absendernummer fehlen. Setzen Sie diese auf dem Gateway-Host: ```bash export TWILIO_ACCOUNT_SID=AC... @@ -1482,13 +1515,13 @@ export TWILIO_FROM_NUMBER=+15550001234 ``` `twilio-voice-call-webhook` schlägt fehl, wenn `voice-call` keine öffentliche Webhook- -Verfügbarkeit hat oder wenn `publicUrl` auf loopback oder privaten Netzwerkadressraum zeigt. +Bereitstellung hat oder wenn `publicUrl` auf Loopback- oder privaten Netzwerkbereich zeigt. Setzen Sie `plugins.entries.voice-call.config.publicUrl` auf die öffentliche Provider-URL oder -konfigurieren Sie eine `voice-call`-Tunnel-/Tailscale-Verfügbarkeit. +konfigurieren Sie einen `voice-call`-Tunnel/eine Tailscale-Bereitstellung. -Loopback- und private URLs sind für Carrier-Callbacks nicht gültig. Verwenden Sie +Loopback- und private URLs sind für Carrier-Callbacks nicht gültig. Verwenden Sie nicht `localhost`, `127.0.0.1`, `0.0.0.0`, `10.x`, `172.16.x`-`172.31.x`, -`192.168.x`, `169.254.x`, `fc00::/7` oder `fd00::/8` nicht als `publicUrl`. +`192.168.x`, `169.254.x`, `fc00::/7` oder `fd00::/8` als `publicUrl`. Für eine stabile öffentliche URL: @@ -1509,8 +1542,8 @@ Für eine stabile öffentliche URL: } ``` -Verwenden Sie für lokale Entwicklung eine Tunnel- oder Tailscale-Verfügbarkeit statt einer privaten -Host-URL: +Verwenden Sie für die lokale Entwicklung einen Tunnel oder eine Tailscale-Freigabe +anstelle einer privaten Host-URL: ```json5 { @@ -1528,7 +1561,8 @@ Host-URL: } ``` -Starten oder laden Sie dann das Gateway neu und führen Sie aus: +Starten Sie anschließend den Gateway neu oder laden Sie ihn neu und führen Sie +Folgendes aus: ```bash openclaw googlemeet setup --transport twilio @@ -1536,14 +1570,15 @@ openclaw voicecall setup openclaw voicecall smoke ``` -`voicecall smoke` ist standardmäßig nur eine Bereitschaftsprüfung. Für einen Testlauf mit einer bestimmten Nummer: +`voicecall smoke` prüft standardmäßig nur die Bereitschaft. So führen Sie einen +Testlauf für eine bestimmte Nummer aus: ```bash openclaw voicecall smoke --to "+15555550123" ``` -Fügen Sie `--yes` nur hinzu, wenn Sie bewusst einen ausgehenden Live-Benachrichtigungsanruf -platzieren möchten: +Fügen Sie `--yes` nur hinzu, wenn Sie absichtlich einen echten ausgehenden +Benachrichtigungsanruf auslösen möchten: ```bash openclaw voicecall smoke --to "+15555550123" --yes @@ -1551,8 +1586,9 @@ openclaw voicecall smoke --to "+15555550123" --yes ### Twilio-Anruf startet, tritt dem Meeting aber nie bei -Bestätigen Sie, dass das Meet-Ereignis Telefon-Einwahldetails bereitstellt. Übergeben Sie die genaue Einwahl- -nummer und PIN oder eine benutzerdefinierte DTMF-Sequenz: +Bestätigen Sie, dass das Meet-Ereignis telefonische Einwahldaten bereitstellt. +Übergeben Sie die exakte Einwahlnummer und PIN oder eine benutzerdefinierte +DTMF-Sequenz: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -1561,54 +1597,94 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --dtmf-sequence ww123456# ``` -Verwenden Sie führende `w` oder Kommas in `--dtmf-sequence`, wenn der Provider vor -Eingabe der PIN eine Pause benötigt. +Verwenden Sie führende `w` oder Kommas in `--dtmf-sequence`, wenn der Provider +vor der PIN-Eingabe eine Pause benötigt. -Wenn der Telefonanruf erstellt wird, aber die Meet-Teilnehmerliste den Einwahl- -Teilnehmer nie anzeigt: +Wenn der Telefonanruf erstellt wird, die Meet-Teilnehmerliste den +Einwahlteilnehmer aber nie anzeigt: -- Führen Sie `openclaw googlemeet doctor ` aus, um die delegierte Twilio- - Anruf-ID zu bestätigen, ob DTMF eingereiht wurde und ob die Einführungsbegrüßung angefordert wurde. -- Führen Sie `openclaw voicecall status --call-id ` aus und bestätigen Sie, dass der Anruf noch - aktiv ist. +- Führen Sie `openclaw googlemeet doctor ` aus, um die delegierte + Twilio-Anruf-ID zu bestätigen, zu prüfen, ob DTMF in die Warteschlange gestellt + wurde, und ob die Begrüßung angefordert wurde. +- Führen Sie `openclaw voicecall status --call-id ` aus und bestätigen Sie, + dass der Anruf noch aktiv ist. - Führen Sie `openclaw voicecall tail` aus und prüfen Sie, ob Twilio-Webhooks am Gateway ankommen. -- Führen Sie `openclaw logs --follow` aus und suchen Sie nach der Twilio-Meet-Sequenz: Google - Meet delegiert den Beitritt, Voice Call startet die Telefonverbindung, Google Meet wartet - `voiceCall.dtmfDelayMs`, sendet DTMF mit `voicecall.dtmf`, wartet - `voiceCall.postDtmfSpeechDelayMs` und fordert dann Einführungsansprache mit - `voicecall.speak` an. -- Führen Sie `openclaw googlemeet setup --transport twilio` erneut aus; eine grüne Einrichtungsprüfung ist - erforderlich, beweist aber nicht, dass die Meeting-PIN-Sequenz korrekt ist. -- Bestätigen Sie, dass die Einwahlnummer zur gleichen Meet-Einladung und Region wie - die PIN gehört. -- Erhöhen Sie `voiceCall.dtmfDelayMs`, wenn Meet langsam antwortet oder das Anruftranskript - nach dem Senden von DTMF weiterhin die Aufforderung zur PIN-Eingabe zeigt. +- Führen Sie `openclaw logs --follow` aus und suchen Sie nach der + Twilio-Meet-Sequenz: Google Meet delegiert den Beitritt, Voice Call startet + die Telefonverbindung, Google Meet wartet `voiceCall.dtmfDelayMs`, sendet DTMF + mit `voicecall.dtmf`, wartet `voiceCall.postDtmfSpeechDelayMs` und fordert dann + die Begrüßungsansage mit `voicecall.speak` an. +- Führen Sie erneut `openclaw googlemeet setup --transport twilio` aus; eine + erfolgreiche Setup-Prüfung ist erforderlich, beweist aber nicht, dass die + Meeting-PIN-Sequenz korrekt ist. +- Bestätigen Sie, dass die Einwahlnummer zur selben Meet-Einladung und Region + gehört wie die PIN. +- Erhöhen Sie `voiceCall.dtmfDelayMs`, wenn Meet langsam antwortet oder das + Anruftranskript nach dem Senden von DTMF weiterhin die Aufforderung zur Eingabe + einer PIN zeigt. - Wenn der Teilnehmer beitritt, Sie die Begrüßung aber nicht hören, prüfen Sie - `openclaw logs --follow` auf die Post-DTMF-Anforderung `voicecall.speak` und - entweder Medienstream-TTS-Wiedergabe oder den Twilio-``-Fallback. Wenn das Anruf- - transkript weiterhin „enter the meeting PIN“ enthält, ist die Telefonverbindung dem - Meet-Raum noch nicht beigetreten, sodass Meetingteilnehmende keine Sprache hören. + `openclaw logs --follow` auf die post-DTMF-Anforderung `voicecall.speak` und + entweder die Medienstream-TTS-Wiedergabe oder den Twilio-``-Fallback. Wenn + das Anruftranskript weiterhin "enter the meeting PIN" enthält, ist die + Telefonverbindung dem Meet-Raum noch nicht beigetreten; Meeting-Teilnehmer + hören daher keine Sprache. -Wenn Webhooks nicht ankommen, debuggen Sie zuerst das Voice Call Plugin: Der Provider muss `plugins.entries.voice-call.config.publicUrl` oder den konfigurierten Tunnel erreichen. Siehe [Fehlerbehebung für Voice Call](/de/plugins/voice-call#troubleshooting). +Wenn Webhooks nicht ankommen, debuggen Sie zuerst das Voice Call Plugin: Der +Provider muss `plugins.entries.voice-call.config.publicUrl` oder den +konfigurierten Tunnel erreichen. Siehe [Fehlerbehebung für Voice Call](/de/plugins/voice-call#troubleshooting). ## Hinweise -Die offizielle Medien-API von Google Meet ist empfangsorientiert, daher benötigt das Sprechen in einen Meet-Anruf weiterhin einen Teilnehmerpfad. Dieses Plugin macht diese Grenze sichtbar: Chrome übernimmt die Browser-Teilnahme und das lokale Audio-Routing; Twilio übernimmt die Telefon-Einwahlteilnahme. +Die offizielle Medien-API von Google Meet ist auf Empfang ausgerichtet, daher +benötigt das Sprechen in einen Meet-Anruf weiterhin einen Teilnehmerpfad. Dieses +Plugin macht diese Grenze sichtbar: Chrome übernimmt die Teilnahme im Browser +und das lokale Audio-Routing; Twilio übernimmt die telefonische Einwahl. -Chrome-Talkback-Modi benötigen `BlackHole 2ch` sowie entweder: +Chrome-Talkback-Modi benötigen `BlackHole 2ch` plus entweder: -- `chrome.audioInputCommand` plus `chrome.audioOutputCommand`: OpenClaw besitzt die Bridge und leitet Audio in `chrome.audioFormat` zwischen diesen Befehlen und dem ausgewählten Provider weiter. Der Agent-Modus verwendet Echtzeit-Transkription plus reguläres TTS; der bidi-Modus verwendet den Echtzeit-Voice-Provider. Der Standard-Chrome-Pfad ist 24 kHz PCM16; 8 kHz G.711 mu-law bleibt für ältere Befehlspaare verfügbar. -- `chrome.audioBridgeCommand`: Ein externer Bridge-Befehl besitzt den gesamten lokalen Audiopfad und muss nach dem Starten oder Validieren seines Daemons beendet werden. Dies ist nur für `bidi` gültig, da der `agent`-Modus direkten Zugriff auf Befehlspaare für TTS benötigt. +- `chrome.audioInputCommand` plus `chrome.audioOutputCommand`: OpenClaw besitzt + die Bridge und leitet Audio in `chrome.audioFormat` zwischen diesen Befehlen + und dem ausgewählten Provider weiter. Der Agent-Modus verwendet + Echtzeittranskription plus reguläres TTS; der Bidi-Modus verwendet den + Echtzeit-Sprach-Provider. Der Standardpfad für Chrome ist 24 kHz PCM16 mit + `chrome.audioBufferBytes: 4096`; 8 kHz G.711 mu-law bleibt für ältere + Befehlspaare verfügbar. +- `chrome.audioBridgeCommand`: Ein externer Bridge-Befehl besitzt den gesamten + lokalen Audiopfad und muss nach dem Starten oder Validieren seines Daemons + beendet werden. Dies ist nur für `bidi` gültig, da der `agent`-Modus direkten + Zugriff auf Befehlspaare für TTS benötigt. -Für sauberes Duplex-Audio routen Sie Meet-Ausgabe und Meet-Mikrofon über getrennte virtuelle Geräte oder einen virtuellen Gerätegraphen im Loopback-Stil. Ein einzelnes gemeinsam genutztes BlackHole-Gerät kann andere Teilnehmer zurück in den Anruf echoen. +Wenn ein Agent das Tool `google_meet` im Agent-Modus aufruft, verzweigt die +Meeting-Beratersitzung das aktuelle Transkript des Aufrufers, bevor sie auf +Teilnehmersprache antwortet. Die Meet-Sitzung bleibt weiterhin getrennt +(`agent::subagent:google-meet:`), sodass Meeting-Folgeaktionen +das Aufrufertranskript nicht direkt verändern. -Mit der Chrome-Bridge aus Befehlspaaren kann `chrome.bargeInInputCommand` ein separates lokales Mikrofon abhören und die Assistentenwiedergabe löschen, wenn der Mensch zu sprechen beginnt. Dadurch bleibt menschliche Sprache vor der Assistentenausgabe, selbst wenn die gemeinsam genutzte BlackHole-loopback-Eingabe während der Assistentenwiedergabe vorübergehend unterdrückt wird. Wie `chrome.audioInputCommand` und `chrome.audioOutputCommand` ist dies ein lokal vom Operator konfigurierter Befehl. Verwenden Sie einen expliziten vertrauenswürdigen Befehlspfad oder eine Argumentliste, und verweisen Sie nicht auf Skripte aus nicht vertrauenswürdigen Orten. +Für sauberes Duplex-Audio leiten Sie Meet-Ausgabe und Meet-Mikrofon über +separate virtuelle Geräte oder einen virtuellen Geräte-Graph im Stil von +Loopback. Ein einzelnes gemeinsam genutztes BlackHole-Gerät kann andere +Teilnehmer in den Anruf zurückspiegeln. -`googlemeet speak` löst die aktive Talkback-Audio-Bridge für eine Chrome-Sitzung aus. `googlemeet leave` stoppt diese Bridge. Für Twilio-Sitzungen, die über das Voice Call Plugin delegiert werden, legt `leave` auch den zugrunde liegenden Sprachanruf auf. Verwenden Sie `googlemeet end-active-conference`, wenn Sie außerdem die aktive Google Meet-Konferenz für einen API-verwalteten Bereich schließen möchten. +Mit der Chrome-Bridge über Befehlspaare kann `chrome.bargeInInputCommand` ein +separates lokales Mikrofon abhören und die Assistentenwiedergabe löschen, wenn +der Mensch zu sprechen beginnt. Dadurch bleibt menschliche Sprache vor der +Assistentenausgabe, selbst wenn die gemeinsam genutzte BlackHole-loopback-Eingabe +während der Assistentenwiedergabe vorübergehend unterdrückt wird. Wie +`chrome.audioInputCommand` und `chrome.audioOutputCommand` ist dies ein lokal vom +Betreiber konfigurierter Befehl. Verwenden Sie einen expliziten vertrauenswürdigen +Befehlspfad oder eine Argumentliste und verweisen Sie nicht auf Skripte aus nicht +vertrauenswürdigen Speicherorten. + +`googlemeet speak` löst die aktive Talkback-Audiobridge für eine Chrome-Sitzung +aus. `googlemeet leave` stoppt diese Bridge. Bei Twilio-Sitzungen, die über das +Voice Call Plugin delegiert werden, legt `leave` auch den zugrunde liegenden +Sprachanruf auf. Verwenden Sie `googlemeet end-active-conference`, wenn Sie auch +die aktive Google Meet-Konferenz für einen API-verwalteten Bereich schließen +möchten. ## Verwandte Themen - [Voice Call Plugin](/de/plugins/voice-call) -- [Talk-Modus](/de/nodes/talk) +- [Sprechmodus](/de/nodes/talk) - [Plugins erstellen](/de/plugins/building-plugins) diff --git a/docs/de/plugins/voice-call.md b/docs/de/plugins/voice-call.md index 4cbdee2db..094880c47 100644 --- a/docs/de/plugins/voice-call.md +++ b/docs/de/plugins/voice-call.md @@ -1,22 +1,22 @@ --- read_when: - - Sie möchten einen ausgehenden Sprachanruf von OpenClaw aus tätigen - - Sie konfigurieren oder entwickeln das Sprachanruf-Plugin + - Sie möchten von OpenClaw aus einen ausgehenden Sprachanruf tätigen + - Sie konfigurieren oder entwickeln das voice-call-Plugin - Sie benötigen Echtzeit-Sprachübertragung oder Streaming-Transkription für Telefonie sidebarTitle: Voice call -summary: Tätigen Sie ausgehende Sprachanrufe und nehmen Sie eingehende Sprachanrufe über Twilio, Telnyx oder Plivo an, mit optionaler Echtzeit-Sprachkommunikation und Streaming-Transkription -title: Sprachanruf-Plugin +summary: Tätigen Sie ausgehende Sprachanrufe und nehmen Sie eingehende Sprachanrufe über Twilio, Telnyx oder Plivo entgegen, mit optionaler Echtzeit-Sprachfunktion und Streaming-Transkription +title: Plugin für Sprachanrufe x-i18n: - generated_at: "2026-05-02T22:21:30Z" + generated_at: "2026-05-04T06:43:08Z" model: gpt-5.5 provider: openai - source_hash: 18a9a0d7095ec92036b516cc26c69219a0a2fd9bb8e0cb2e7509123bb4f3f65a + source_hash: 8ec2c22dcc9073572963744685a432328787bcedb14025e0326c20d9d842f857 source_path: plugins/voice-call.md workflow: 16 --- Sprachanrufe für OpenClaw über ein Plugin. Unterstützt ausgehende Benachrichtigungen, -mehrstufige Unterhaltungen, Full-Duplex-Echtzeit-Sprache, Streaming- +mehrzügige Unterhaltungen, Full-Duplex-Echtzeit-Sprache, Streaming- Transkription und eingehende Anrufe mit Allowlist-Richtlinien. **Aktuelle Provider:** `twilio` (Programmable Voice + Media Streams), @@ -24,9 +24,10 @@ Transkription und eingehende Anrufe mit Allowlist-Richtlinien. speech), `mock` (Entwicklung/kein Netzwerk). -Das Voice Call-Plugin läuft **innerhalb des Gateway-Prozesses**. Wenn Sie ein -entferntes Gateway verwenden, installieren und konfigurieren Sie das Plugin auf dem Computer, auf dem -das Gateway läuft, und starten Sie anschließend das Gateway neu, damit es geladen wird. +Das Voice-Call-Plugin läuft **innerhalb des Gateway-Prozesses**. Wenn Sie ein +Remote-Gateway verwenden, installieren und konfigurieren Sie das Plugin auf dem +Computer, auf dem das Gateway läuft, und starten Sie anschließend das Gateway neu, +damit es geladen wird. ## Schnellstart @@ -48,15 +49,15 @@ das Gateway läuft, und starten Sie anschließend das Gateway neu, damit es gela - Verwenden Sie das unveränderte Paket, um dem aktuellen offiziellen Release-Tag zu folgen. Pinnen Sie eine - exakte Version nur dann, wenn Sie eine reproduzierbare Installation benötigen. + Verwenden Sie das Paket ohne Versionsangabe, um dem aktuellen offiziellen Release-Tag zu folgen. Pinnen Sie eine + exakte Version nur, wenn Sie eine reproduzierbare Installation benötigen. - Starten Sie anschließend das Gateway neu, damit das Plugin geladen wird. + Starten Sie danach das Gateway neu, damit das Plugin geladen wird. - Legen Sie die Konfiguration unter `plugins.entries.voice-call.config` fest (siehe - [Konfiguration](#configuration) unten für die vollständige Struktur). Mindestens erforderlich sind: + Legen Sie die Konfiguration unter `plugins.entries.voice-call.config` fest (die vollständige Struktur finden Sie unten unter + [Konfiguration](#configuration)). Mindestens erforderlich sind: `provider`, Provider-Zugangsdaten, `fromNumber` und eine öffentlich erreichbare Webhook-URL. @@ -65,8 +66,8 @@ das Gateway läuft, und starten Sie anschließend das Gateway neu, damit es gela openclaw voicecall setup ``` - Die Standardausgabe ist in Chatprotokollen und Terminals gut lesbar. Sie prüft - die Aktivierung des Plugins, Provider-Zugangsdaten, Webhook-Erreichbarkeit und dass + Die Standardausgabe ist in Chatprotokollen und Terminals lesbar. Sie prüft, + ob das Plugin aktiviert ist, ob Provider-Zugangsdaten vorhanden sind, ob der Webhook erreichbar ist und ob nur ein Audiomodus (`streaming` oder `realtime`) aktiv ist. Verwenden Sie `--json` für Skripte. @@ -78,7 +79,7 @@ das Gateway läuft, und starten Sie anschließend das Gateway neu, damit es gela ``` Beide Befehle sind standardmäßig Trockenläufe. Fügen Sie `--yes` hinzu, um tatsächlich einen kurzen - ausgehenden Benachrichtigungsanruf zu platzieren: + ausgehenden Benachrichtigungsanruf zu starten: ```bash openclaw voicecall smoke --to "+15555550123" --yes @@ -90,16 +91,16 @@ das Gateway läuft, und starten Sie anschließend das Gateway neu, damit es gela Für Twilio, Telnyx und Plivo muss die Einrichtung zu einer **öffentlichen Webhook-URL** auflösen. Wenn `publicUrl`, die Tunnel-URL, die Tailscale-URL oder der Serve-Fallback -zu loopback oder einem privaten Netzwerkbereich auflöst, schlägt die Einrichtung fehl, statt +auf local loopback oder privaten Netzwerkadressraum aufgelöst wird, schlägt die Einrichtung fehl, anstatt einen Provider zu starten, der keine Carrier-Webhooks empfangen kann. ## Konfiguration -Wenn `enabled: true` gesetzt ist, dem ausgewählten Provider aber Zugangsdaten fehlen, -protokolliert der Gateway-Start eine Warnung über eine unvollständige Einrichtung mit den fehlenden Schlüsseln und +Wenn `enabled: true` gesetzt ist, aber dem ausgewählten Provider Zugangsdaten fehlen, +protokolliert der Gateway-Start eine Warnung über die unvollständige Einrichtung mit den fehlenden Schlüsseln und überspringt den Start der Runtime. Befehle, RPC-Aufrufe und Agent-Tools geben bei Verwendung weiterhin -die exakt fehlende Provider-Konfiguration zurück. +die genaue fehlende Provider-Konfiguration zurück. Voice-Call-Zugangsdaten akzeptieren SecretRefs. `plugins.entries.voice-call.config.twilio.authToken`, `plugins.entries.voice-call.config.realtime.providers.*.apiKey`, `plugins.entries.voice-call.config.streaming.providers.*.apiKey` und `plugins.entries.voice-call.config.tts.providers.*.apiKey` werden über die standardmäßige SecretRef-Oberfläche aufgelöst; siehe [SecretRef-Zugangsdatenoberfläche](/de/reference/secretref-credential-surface). @@ -178,15 +179,15 @@ Voice-Call-Zugangsdaten akzeptieren SecretRefs. `plugins.entries.voice-call.conf - Twilio, Telnyx und Plivo benötigen alle eine **öffentlich erreichbare** Webhook-URL. - `mock` ist ein lokaler Entwicklungs-Provider (keine Netzwerkaufrufe). - - Telnyx benötigt `telnyx.publicKey` (oder `TELNYX_PUBLIC_KEY`), sofern `skipSignatureVerification` nicht true ist. - - `skipSignatureVerification` ist nur für lokale Tests gedacht. - - In der kostenlosen ngrok-Stufe setzen Sie `publicUrl` auf die exakte ngrok-URL; Signaturprüfung wird immer erzwungen. - - `tunnel.allowNgrokFreeTierLoopbackBypass: true` erlaubt Twilio-Webhooks mit ungültigen Signaturen **nur**, wenn `tunnel.provider="ngrok"` und `serve.bind` loopback ist (lokaler ngrok-Agent). Nur für lokale Entwicklung. - - URLs der kostenlosen ngrok-Stufe können sich ändern oder Interstitial-Verhalten hinzufügen; wenn `publicUrl` abweicht, schlagen Twilio-Signaturen fehl. Produktion: Bevorzugen Sie eine stabile Domain oder einen Tailscale-Funnel. + - Telnyx benötigt `telnyx.publicKey` (oder `TELNYX_PUBLIC_KEY`), außer `skipSignatureVerification` ist true. + - `skipSignatureVerification` ist nur für lokale Tests vorgesehen. + - Setzen Sie im kostenlosen ngrok-Tarif `publicUrl` auf die exakte ngrok-URL; die Signaturprüfung wird immer erzwungen. + - `tunnel.allowNgrokFreeTierLoopbackBypass: true` erlaubt Twilio-Webhooks mit ungültigen Signaturen **nur**, wenn `tunnel.provider="ngrok"` ist und `serve.bind` local loopback ist (lokaler ngrok-Agent). Nur für lokale Entwicklung. + - URLs im kostenlosen ngrok-Tarif können sich ändern oder Zwischenseiten hinzufügen; wenn `publicUrl` abweicht, schlagen Twilio-Signaturen fehl. Produktion: Verwenden Sie bevorzugt eine stabile Domain oder einen Tailscale-Funnel. - - `streaming.preStartTimeoutMs` schließt Sockets, die nie einen gültigen `start`-Frame senden. + - `streaming.preStartTimeoutMs` schließt Sockets, die nie ein gültiges `start`-Frame senden. - `streaming.maxPendingConnections` begrenzt die Gesamtzahl nicht authentifizierter Pre-Start-Sockets. - `streaming.maxPendingConnectionsPerIp` begrenzt nicht authentifizierte Pre-Start-Sockets pro Quell-IP. - `streaming.maxConnections` begrenzt die Gesamtzahl offener Media-Stream-Sockets (ausstehend + aktiv). @@ -194,9 +195,9 @@ Voice-Call-Zugangsdaten akzeptieren SecretRefs. `plugins.entries.voice-call.conf Ältere Konfigurationen mit `provider: "log"`, `twilio.from` oder alten - OpenAI-Schlüsseln unter `streaming.*` werden durch `openclaw doctor --fix` umgeschrieben. + `streaming.*`-OpenAI-Schlüsseln werden durch `openclaw doctor --fix` umgeschrieben. Der Runtime-Fallback akzeptiert die alten Voice-Call-Schlüssel vorerst weiterhin, aber - der Umschreibpfad ist `openclaw doctor --fix` und die Kompatibilitätsschicht ist + der Umschreibpfad ist `openclaw doctor --fix` und der Kompatibilitäts-Shim ist temporär. Automatisch migrierte Streaming-Schlüssel: @@ -213,10 +214,10 @@ Voice-Call-Zugangsdaten akzeptieren SecretRefs. `plugins.entries.voice-call.conf ## Sitzungsumfang Standardmäßig verwendet Voice Call `sessionScope: "per-phone"`, sodass wiederholte Anrufe vom -gleichen Anrufer den Unterhaltungsspeicher beibehalten. Setzen Sie `sessionScope: "per-call"`, wenn -jeder Carrier-Anruf mit frischem Kontext beginnen soll, beispielsweise für Empfang, -Buchungen, IVR oder Google Meet-Bridge-Abläufe, bei denen dieselbe Telefonnummer -verschiedene Meetings darstellen kann. +selben Anrufer das Unterhaltungsgedächtnis behalten. Setzen Sie `sessionScope: "per-call"`, wenn +jeder Carrier-Anruf mit frischem Kontext starten soll, zum Beispiel bei Empfangs-, +Buchungs-, IVR- oder Google-Meet-Bridge-Abläufen, bei denen dieselbe Telefonnummer +verschiedene Meetings repräsentieren kann. ## Echtzeit-Sprachunterhaltungen @@ -232,23 +233,23 @@ Audiomodus pro Anruf. Aktuelles Runtime-Verhalten: - `realtime.enabled` wird für Twilio Media Streams unterstützt. -- `realtime.provider` ist optional. Wenn nicht gesetzt, verwendet Voice Call den zuerst registrierten Echtzeit-Sprach-Provider. +- `realtime.provider` ist optional. Wenn es nicht gesetzt ist, verwendet Voice Call den ersten registrierten Echtzeit-Sprach-Provider. - Gebündelte Echtzeit-Sprach-Provider: Google Gemini Live (`google`) und OpenAI (`openai`), registriert durch ihre Provider-Plugins. -- Provider-eigene Rohkonfiguration liegt unter `realtime.providers.`. -- Voice Call stellt standardmäßig das gemeinsame Echtzeit-Tool `openclaw_agent_consult` bereit. Das Echtzeitmodell kann es aufrufen, wenn der Anrufer tiefergehendes Reasoning, aktuelle Informationen oder normale OpenClaw-Tools anfordert. -- `realtime.fastContext.enabled` ist standardmäßig deaktiviert. Wenn aktiviert, durchsucht Voice Call zuerst indizierten Speicher/Sitzungskontext nach der Consult-Frage und gibt diese Ausschnitte innerhalb von `realtime.fastContext.timeoutMs` an das Echtzeitmodell zurück, bevor nur dann auf den vollständigen Consult-Agent zurückgefallen wird, wenn `realtime.fastContext.fallbackToConsult` true ist. -- Wenn `realtime.provider` auf einen nicht registrierten Provider verweist oder überhaupt kein Echtzeit-Sprach-Provider registriert ist, protokolliert Voice Call eine Warnung und überspringt Echtzeitmedien, statt das gesamte Plugin fehlschlagen zu lassen. -- Consult-Sitzungsschlüssel verwenden die gespeicherte Anrufsitzung erneut, wenn verfügbar, und fallen dann auf den konfigurierten `sessionScope` zurück (`per-phone` standardmäßig oder `per-call` für isolierte Anrufe). +- Provider-eigene Rohkonfiguration befindet sich unter `realtime.providers.`. +- Voice Call stellt standardmäßig das gemeinsame Echtzeit-Tool `openclaw_agent_consult` bereit. Das Echtzeitmodell kann es aufrufen, wenn der Anrufer nach tiefergehender Schlussfolgerung, aktuellen Informationen oder normalen OpenClaw-Tools fragt. +- `realtime.fastContext.enabled` ist standardmäßig deaktiviert. Wenn aktiviert, durchsucht Voice Call zuerst indexierten Speicher-/Sitzungskontext nach der Consult-Frage und gibt diese Ausschnitte innerhalb von `realtime.fastContext.timeoutMs` an das Echtzeitmodell zurück, bevor nur dann auf den vollständigen Consult-Agent zurückgefallen wird, wenn `realtime.fastContext.fallbackToConsult` true ist. +- Wenn `realtime.provider` auf einen nicht registrierten Provider zeigt oder überhaupt kein Echtzeit-Sprach-Provider registriert ist, protokolliert Voice Call eine Warnung und überspringt Echtzeitmedien, anstatt das gesamte Plugin fehlschlagen zu lassen. +- Consult-Sitzungsschlüssel verwenden die gespeicherte Anrufsitzung, wenn verfügbar, und fallen dann auf den konfigurierten `sessionScope` zurück (`per-phone` standardmäßig oder `per-call` für isolierte Anrufe). ### Tool-Richtlinie `realtime.toolPolicy` steuert den Consult-Lauf: -| Richtlinie | Verhalten | +| Richtlinie | Verhalten | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `safe-read-only` | Stellt das Consult-Tool bereit und beschränkt den regulären Agent auf `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` und `memory_get`. | | `owner` | Stellt das Consult-Tool bereit und lässt den regulären Agent die normale Agent-Tool-Richtlinie verwenden. | -| `none` | Stellt das Consult-Tool nicht bereit. Benutzerdefinierte `realtime.tools` werden weiterhin an den Echtzeit-Provider durchgereicht. | +| `none` | Stellt das Consult-Tool nicht bereit. Benutzerdefinierte `realtime.tools` werden weiterhin an den Echtzeit-Provider durchgereicht. | ### Beispiele für Echtzeit-Provider @@ -257,6 +258,9 @@ Aktuelles Runtime-Verhalten: Standardwerte: API-Schlüssel aus `realtime.providers.google.apiKey`, `GEMINI_API_KEY` oder `GOOGLE_GENERATIVE_AI_API_KEY`; Modell `gemini-2.5-flash-native-audio-preview-12-2025`; Stimme `Kore`. + `sessionResumption` und `contextWindowCompression` sind für längere, + wiederverbindbare Anrufe standardmäßig aktiviert. Verwenden Sie `silenceDurationMs`, `startSensitivity` und + `endSensitivity`, um schnellere Sprecherwechsel bei Telefonie-Audio abzustimmen. ```json5 { @@ -277,6 +281,8 @@ Aktuelles Runtime-Verhalten: apiKey: "${GEMINI_API_KEY}", model: "gemini-2.5-flash-native-audio-preview-12-2025", voice: "Kore", + silenceDurationMs: 500, + startSensitivity: "high", }, }, }, @@ -312,19 +318,18 @@ Aktuelles Runtime-Verhalten: Siehe [Google-Provider](/de/providers/google) und -[OpenAI-Provider](/de/providers/openai) für Provider-spezifische Echtzeit-Sprach- -Optionen. +[OpenAI-Provider](/de/providers/openai) für Provider-spezifische Echtzeit-Sprachoptionen. ## Streaming-Transkription -`streaming` wählt einen Echtzeit-Transkriptions-Provider für Live-Anruf-Audio aus. +`streaming` wählt einen Echtzeit-Transkriptions-Provider für Live-Anrufaudio aus. -Aktuelles Runtime-Verhalten: +Aktuelles Laufzeitverhalten: -- `streaming.provider` ist optional. Wenn nicht gesetzt, verwendet Voice Call den ersten registrierten Provider für Echtzeittranskription. -- Gebündelte Provider für Echtzeittranskription: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) und xAI (`xai`), registriert durch ihre Provider-Plugins. +- `streaming.provider` ist optional. Wenn nicht gesetzt, verwendet Voice Call den ersten registrierten Echtzeit-Transkriptions-Provider. +- Gebündelte Echtzeit-Transkriptions-Provider: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) und xAI (`xai`), registriert durch ihre Provider-Plugins. - Provider-eigene Rohkonfiguration liegt unter `streaming.providers.`. -- Nachdem Twilio eine akzeptierte Stream-`start`-Nachricht sendet, registriert Voice Call den Stream sofort, reiht eingehende Medien über den Transkriptions-Provider ein, während der Provider verbindet, und startet die erste Begrüßung erst, wenn die Echtzeittranskription bereit ist. +- Nachdem Twilio eine akzeptierte Stream-`start`-Nachricht sendet, registriert Voice Call den Stream sofort, stellt eingehende Medien über den Transkriptions-Provider in die Warteschlange, während der Provider verbindet, und startet die erste Begrüßung erst, wenn die Echtzeit-Transkription bereit ist. - Wenn `streaming.provider` auf einen nicht registrierten Provider verweist oder keiner registriert ist, protokolliert Voice Call eine Warnung und überspringt Medien-Streaming, statt das gesamte Plugin fehlschlagen zu lassen. ### Beispiele für Streaming-Provider @@ -397,9 +402,9 @@ Aktuelles Runtime-Verhalten: ## TTS für Anrufe -Voice Call verwendet die zentrale `messages.tts`-Konfiguration für gestreamte -Sprachausgabe in Anrufen. Sie können sie in der Plugin-Konfiguration mit -**derselben Struktur** überschreiben — sie wird per Deep Merge mit `messages.tts` zusammengeführt. +Voice Call verwendet die zentrale `messages.tts`-Konfiguration für Streaming- +Sprache bei Anrufen. Sie können sie in der Plugin-Konfiguration mit +**derselben Struktur** überschreiben — sie wird per Deep-Merge mit `messages.tts` zusammengeführt. ```json5 { @@ -416,22 +421,22 @@ Sprachausgabe in Anrufen. Sie können sie in der Plugin-Konfiguration mit ``` -**Microsoft Speech wird für Sprachanrufe ignoriert.** Telefonie-Audio benötigt PCM; +**Microsoft Speech wird für Sprachanrufe ignoriert.** Telefonieaudio benötigt PCM; der aktuelle Microsoft-Transport stellt keine Telefonie-PCM-Ausgabe bereit. -Hinweise zum Verhalten: +Verhaltenshinweise: -- Ältere `tts.`-Schlüssel innerhalb der Plugin-Konfiguration (`openai`, `elevenlabs`, `microsoft`, `edge`) werden durch `openclaw doctor --fix` repariert; festgeschriebene Konfiguration sollte `tts.providers.` verwenden. -- Zentrales TTS wird verwendet, wenn Twilio-Medien-Streaming aktiviert ist; andernfalls fallen Anrufe auf provider-native Stimmen zurück. +- Veraltete `tts.`-Schlüssel in der Plugin-Konfiguration (`openai`, `elevenlabs`, `microsoft`, `edge`) werden durch `openclaw doctor --fix` repariert; übergebene Konfiguration sollte `tts.providers.` verwenden. +- Zentrales TTS wird verwendet, wenn Twilio-Medien-Streaming aktiviert ist; andernfalls fallen Anrufe auf Provider-native Stimmen zurück. - Wenn ein Twilio-Medienstream bereits aktiv ist, fällt Voice Call nicht auf TwiML `` zurück. Wenn Telefonie-TTS in diesem Zustand nicht verfügbar ist, schlägt die Wiedergabeanforderung fehl, statt zwei Wiedergabepfade zu mischen. - Wenn Telefonie-TTS auf einen sekundären Provider zurückfällt, protokolliert Voice Call eine Warnung mit der Provider-Kette (`from`, `to`, `attempts`) zur Fehlersuche. -- Wenn Twilio-Barge-in oder Stream-Abbau die ausstehende TTS-Warteschlange leert, werden eingereihte Wiedergabeanforderungen abgeschlossen, statt Anrufer hängen zu lassen, die auf den Abschluss der Wiedergabe warten. +- Wenn Twilio-Barge-in oder Stream-Abbau die ausstehende TTS-Warteschlange leert, werden eingereihte Wiedergabeanforderungen abgeschlossen, statt Anrufer, die auf den Abschluss der Wiedergabe warten, hängen zu lassen. ### TTS-Beispiele - + ```json5 { messages: { @@ -445,7 +450,7 @@ Hinweise zum Verhalten: } ``` - + ```json5 { plugins: { @@ -469,7 +474,7 @@ Hinweise zum Verhalten: } ``` - + ```json5 { plugins: { @@ -506,30 +511,30 @@ Die Richtlinie für eingehende Anrufe ist standardmäßig `disabled`. Um eingehe ``` -`inboundPolicy: "allowlist"` ist eine Anrufer-ID-Prüfung mit geringer Vertrauenswürdigkeit. Das -Plugin normalisiert den vom Provider bereitgestellten `From`-Wert und vergleicht ihn mit +`inboundPolicy: "allowlist"` ist eine Caller-ID-Prüfung mit geringer Vertrauenswürdigkeit. Das +Plugin normalisiert den vom Provider gelieferten `From`-Wert und vergleicht ihn mit `allowFrom`. Webhook-Verifizierung authentifiziert die Provider-Zustellung und -Payload-Integrität, beweist aber **nicht** den Besitz der PSTN-/VoIP-Anrufernummer. -Behandeln Sie `allowFrom` als Anrufer-ID-Filterung, nicht als starke Anruferidentität. +Payload-Integrität, beweist aber **nicht** die Inhaberschaft der PSTN/VoIP-Anrufernummer. +Behandeln Sie `allowFrom` als Caller-ID-Filterung, nicht als starke Anruferidentität. -Automatische Antworten verwenden das Agentensystem. Stimmen Sie sie mit `responseModel`, -`responseSystemPrompt` und `responseTimeoutMs` ab. +Automatische Antworten verwenden das Agentensystem. Passen Sie sie mit `responseModel`, +`responseSystemPrompt` und `responseTimeoutMs` an. ### Routing pro Nummer -Verwenden Sie `numbers`, wenn ein Voice Call-Plugin Anrufe für mehrere Telefonnummern -empfängt und jede Nummer sich wie eine eigene Leitung verhalten soll. Beispielsweise kann eine +Verwenden Sie `numbers`, wenn ein Voice-Call-Plugin Anrufe für mehrere Telefonnummern +empfängt und sich jede Nummer wie eine andere Leitung verhalten soll. Zum Beispiel kann eine Nummer einen lockeren persönlichen Assistenten verwenden, während eine andere eine geschäftliche Persona, einen anderen Antwort-Agenten und eine andere TTS-Stimme verwendet. -Routen werden anhand der vom Provider bereitgestellten gewählten `To`-Nummer ausgewählt. Schlüssel müssen +Routen werden aus der vom Provider gelieferten gewählten `To`-Nummer ausgewählt. Schlüssel müssen E.164-Nummern sein. Wenn ein Anruf eingeht, löst Voice Call die passende Route einmal auf, -speichert die passende Route im Anrufdatensatz und verwendet diese effektive Konfiguration +speichert die übereinstimmende Route im Anrufdatensatz und verwendet diese effektive Konfiguration für die Begrüßung, den klassischen automatischen Antwortpfad, den Echtzeit-Konsultationspfad und die TTS- -Wiedergabe. Wenn keine Route passt, wird die globale Voice Call-Konfiguration verwendet. -Ausgehende Anrufe verwenden `numbers` nicht; übergeben Sie das ausgehende Ziel, die Nachricht und -die Sitzung explizit beim Starten des Anrufs. +Wiedergabe wieder. Wenn keine Route passt, wird die globale Voice-Call-Konfiguration verwendet. +Ausgehende Anrufe verwenden `numbers` nicht; übergeben Sie ausgehendes Ziel, Nachricht und +Sitzung beim Starten des Anrufs explizit. Routenüberschreibungen unterstützen derzeit: @@ -540,7 +545,7 @@ Routenüberschreibungen unterstützen derzeit: - `responseSystemPrompt` - `responseTimeoutMs` -Der Routenwert `tts` wird per Deep Merge über die globale Voice Call-`tts`-Konfiguration gelegt, sodass +Der `tts`-Routenwert wird per Deep-Merge über die globale Voice-Call-`tts`-Konfiguration gelegt, sodass Sie normalerweise nur die Provider-Stimme überschreiben können: ```json5 @@ -580,40 +585,40 @@ Voice Call extrahiert Sprachtext defensiv: - Ignoriert Payloads, die als Reasoning-/Fehlerinhalte markiert sind. - Parst direktes JSON, eingezäuntes JSON oder Inline-`"spoken"`-Schlüssel. -- Fällt auf Klartext zurück und entfernt wahrscheinliche einleitende Planungs-/Meta-Absätze. +- Fällt auf Klartext zurück und entfernt wahrscheinliche Planungs-/Meta-Einleitungsabsätze. -Dadurch bleibt die gesprochene Wiedergabe auf anruferorientierten Text fokussiert und es wird vermieden, -dass Planungstext in Audio gelangt. +So bleibt die gesprochene Wiedergabe auf anruferorientierten Text fokussiert und +verhindert, dass Planungstext in Audio gelangt. -### Startverhalten von Unterhaltungen +### Verhalten beim Gesprächsstart -Für ausgehende `conversation`-Anrufe ist die Behandlung der ersten Nachricht an den Live- +Bei ausgehenden `conversation`-Anrufen ist die Behandlung der ersten Nachricht an den Live- Wiedergabestatus gebunden: -- Barge-in-Warteschlangenleerung und automatische Antwort werden nur unterdrückt, während die erste Begrüßung aktiv gesprochen wird. +- Das Leeren der Barge-in-Warteschlange und automatische Antwort werden nur unterdrückt, während die erste Begrüßung aktiv gesprochen wird. - Wenn die erste Wiedergabe fehlschlägt, kehrt der Anruf zu `listening` zurück und die erste Nachricht bleibt für einen erneuten Versuch in der Warteschlange. - Die erste Wiedergabe für Twilio-Streaming startet beim Verbinden des Streams ohne zusätzliche Verzögerung. -- Barge-in bricht aktive Wiedergabe ab und löscht eingereihte, aber noch nicht abgespielte Twilio-TTS-Einträge. Gelöschte Einträge werden als übersprungen aufgelöst, sodass die Logik für Folgeantworten fortfahren kann, ohne auf Audio zu warten, das nie abgespielt wird. -- Echtzeit-Sprachunterhaltungen verwenden den eigenen Eröffnungs-Turn des Echtzeitstreams. Voice Call sendet kein älteres ``-TwiML-Update für diese erste Nachricht, sodass ausgehende ``-Sitzungen verbunden bleiben. +- Barge-in bricht aktive Wiedergabe ab und leert eingereihte, aber noch nicht wiedergegebene Twilio-TTS-Einträge. Geleerte Einträge werden als übersprungen aufgelöst, sodass nachfolgende Antwortlogik fortfahren kann, ohne auf Audio zu warten, das nie abgespielt wird. +- Echtzeit-Sprachgespräche verwenden den eigenen Eröffnungszug des Echtzeit-Streams. Voice Call sendet **kein** veraltetes ``-TwiML-Update für diese erste Nachricht, sodass ausgehende ``-Sitzungen verbunden bleiben. -### Karenzzeit bei Twilio-Stream-Trennung +### Twilio-Stream-Trennungsfrist Wenn ein Twilio-Medienstream getrennt wird, wartet Voice Call **2000 ms**, bevor der Anruf automatisch beendet wird: -- Wenn der Stream während dieses Fensters erneut verbindet, wird die automatische Beendigung abgebrochen. -- Wenn sich nach der Karenzzeit kein Stream erneut registriert, wird der Anruf beendet, um hängende aktive Anrufe zu verhindern. +- Wenn der Stream in diesem Zeitfenster erneut verbindet, wird die automatische Beendigung abgebrochen. +- Wenn nach Ablauf der Frist kein Stream erneut registriert wird, wird der Anruf beendet, um festhängende aktive Anrufe zu verhindern. ## Reaper für veraltete Anrufe Verwenden Sie `staleCallReaperSeconds`, um Anrufe zu beenden, die nie einen abschließenden -Webhook erhalten (zum Beispiel Benachrichtigungsmodus-Anrufe, die nie abgeschlossen werden). Der Standardwert +Webhook erhalten (zum Beispiel Notify-Modus-Anrufe, die nie abgeschlossen werden). Der Standardwert ist `0` (deaktiviert). Empfohlene Bereiche: -- **Produktion:** `120`–`300` Sekunden für Benachrichtigungs-Workflows. -- Halten Sie diesen Wert **höher als `maxDurationSeconds`**, damit normale Anrufe abgeschlossen werden können. Ein guter Ausgangspunkt ist `maxDurationSeconds + 30–60` Sekunden. +- **Produktion:** `120`–`300` Sekunden für Notify-artige Abläufe. +- Halten Sie diesen Wert **höher als `maxDurationSeconds`**, damit normale Anrufe beendet werden können. Ein guter Ausgangspunkt ist `maxDurationSeconds + 30–60` Sekunden. ```json5 { @@ -632,12 +637,12 @@ Empfohlene Bereiche: ## Webhook-Sicherheit -Wenn sich ein Proxy oder Tunnel vor dem Gateway befindet, rekonstruiert das Plugin +Wenn ein Proxy oder Tunnel vor dem Gateway sitzt, rekonstruiert das Plugin die öffentliche URL für die Signaturverifizierung. Diese Optionen steuern, welchen weitergeleiteten Headern vertraut wird: - Allowlist-Hosts aus Weiterleitungs-Headern. + Allowlist-Hosts aus Weiterleitungsheadern. Weitergeleiteten Headern ohne Allowlist vertrauen. @@ -648,10 +653,10 @@ welchen weitergeleiteten Headern vertraut wird: Zusätzliche Schutzmaßnahmen: -- Webhook-**Replay-Schutz** ist für Twilio und Plivo aktiviert. Wiederholte gültige Webhook-Anfragen werden bestätigt, aber für Nebenwirkungen übersprungen. -- Twilio-Unterhaltungs-Turns enthalten ein Token pro Turn in ``-Callbacks, sodass veraltete/wiederholte Sprach-Callbacks keinen neueren ausstehenden Transkript-Turn erfüllen können. -- Nicht authentifizierte Webhook-Anfragen werden vor Body-Lesevorgängen abgelehnt, wenn die erforderlichen Signatur-Header des Providers fehlen. -- Der voice-call-Webhook verwendet das gemeinsame Pre-Auth-Body-Profil (64 KB / 5 Sekunden) plus ein Pro-IP-In-Flight-Limit vor der Signaturverifizierung. +- Webhook-**Replay-Schutz** ist für Twilio und Plivo aktiviert. Wiederholte gültige Webhook-Anfragen werden bestätigt, aber für Seiteneffekte übersprungen. +- Twilio-Gesprächsrunden enthalten ein Token pro Runde in ``-Callbacks, sodass veraltete/wiederholte Sprach-Callbacks keine neuere ausstehende Transkriptionsrunde erfüllen können. +- Nicht authentifizierte Webhook-Anfragen werden vor Body-Lesevorgängen abgelehnt, wenn die erforderlichen Signaturheader des Providers fehlen. +- Der voice-call-Webhook verwendet das gemeinsame Pre-Auth-Body-Profil (64 KB / 5 Sekunden) plus eine Pro-IP-Obergrenze für gleichzeitig laufende Anfragen vor der Signaturverifizierung. Beispiel mit einem stabilen öffentlichen Host: @@ -687,19 +692,19 @@ openclaw voicecall latency # summarize turn latency from lo openclaw voicecall expose --mode funnel ``` -Wenn das Gateway bereits läuft, delegieren operative `voicecall`-Befehle -an die Gateway-eigene Voice Call-Runtime, sodass die CLI keinen zweiten +Wenn der Gateway bereits läuft, delegieren operative `voicecall`-Befehle +an die vom Gateway verwaltete Voice-Call-Runtime, damit die CLI keinen zweiten Webhook-Server bindet. Wenn kein Gateway erreichbar ist, fallen die Befehle auf eine eigenständige CLI-Runtime zurück. -`latency` liest `calls.jsonl` aus dem standardmäßigen Speicherpfad für Sprachanrufdaten. -Verwenden Sie `--file `, um auf ein anderes Log zu verweisen, und `--last `, um die -Analyse auf die letzten N Datensätze zu begrenzen (Standard: 200). Die Ausgabe enthält p50/p90/p99 -für Antwortlatenz und Wartezeiten beim Zuhören. +`latency` liest `calls.jsonl` aus dem standardmäßigen Speicherpfad für Voice-Call. +Verwenden Sie `--file `, um auf ein anderes Log zu verweisen, und `--last `, um +die Analyse auf die letzten N Datensätze zu begrenzen (Standardwert 200). Die Ausgabe enthält p50/p90/p99 +für Turn-Latenz und Listen-Wait-Zeiten. ## Agent-Tool -Tool-Name: `voice_call`. +Toolname: `voice_call`. | Aktion | Argumente | | --------------- | ------------------------------------------ | @@ -710,7 +715,7 @@ Tool-Name: `voice_call`. | `end_call` | `callId` | | `get_status` | `callId` | -Dieses Repository enthält eine passende Skill-Dokumentation unter `skills/voice-call/SKILL.md`. +Dieses Repo liefert eine passende Skill-Dokumentation unter `skills/voice-call/SKILL.md`. ## Gateway-RPC @@ -723,15 +728,15 @@ Dieses Repository enthält eine passende Skill-Dokumentation unter `skills/voice | `voicecall.end` | `callId` | | `voicecall.status` | `callId` | -`dtmfSequence` ist nur mit `mode: "conversation"` gültig. Anrufe im Benachrichtigungsmodus -sollten `voicecall.dtmf` verwenden, nachdem der Anruf existiert, wenn sie nach dem Verbindungsaufbau +`dtmfSequence` ist nur mit `mode: "conversation"` gültig. Aufrufe im Benachrichtigungsmodus +sollten `voicecall.dtmf` verwenden, nachdem der Aufruf besteht, wenn sie nach dem Verbindungsaufbau Ziffern benötigen. -## Fehlerbehebung +## Problembehandlung -### Setup schlägt bei der Webhook-Freigabe fehl +### Einrichtung schlägt bei Webhook-Bereitstellung fehl -Führen Sie das Setup aus derselben Umgebung aus, in der auch der Gateway läuft: +Führen Sie die Einrichtung in derselben Umgebung aus, in der auch der Gateway läuft: ```bash openclaw voicecall setup @@ -739,18 +744,18 @@ openclaw voicecall setup --json ``` Für `twilio`, `telnyx` und `plivo` muss `webhook-exposure` grün sein. Eine -konfigurierte `publicUrl` schlägt trotzdem fehl, wenn sie auf lokalen oder privaten Netzwerkbereich -zeigt, weil der Netzbetreiber diese Adressen nicht zurückrufen kann. Verwenden Sie nicht +konfigurierte `publicUrl` schlägt dennoch fehl, wenn sie auf lokale oder private Netzwerkbereiche +zeigt, da der Netzbetreiber diese Adressen nicht zurückrufen kann. Verwenden Sie `localhost`, `127.0.0.1`, `0.0.0.0`, `10.x`, `172.16.x`-`172.31.x`, -`192.168.x`, `169.254.x`, `fc00::/7` oder `fd00::/8` als `publicUrl`. +`192.168.x`, `169.254.x`, `fc00::/7` oder `fd00::/8` nicht als `publicUrl`. -Ausgehende Twilio-Anrufe im Benachrichtigungsmodus senden ihr anfängliches ``-TwiML direkt in -der Anfrage zum Erstellen des Anrufs, daher hängt die erste gesprochene Nachricht nicht davon ab, -dass Twilio Webhook-TwiML abruft. Ein öffentlicher Webhook ist weiterhin für Status-Callbacks, -Konversationsanrufe, DTMF vor dem Verbindungsaufbau, Echtzeit-Streams und Anrufsteuerung nach dem +Ausgehende Twilio-Aufrufe im Benachrichtigungsmodus senden ihr initiales ``-TwiML direkt in +der Anfrage zum Erstellen des Aufrufs, sodass die erste gesprochene Nachricht nicht davon abhängt, dass Twilio +Webhook-TwiML abruft. Ein öffentlicher Webhook ist weiterhin für Status-Callbacks, +Konversationsaufrufe, DTMF vor dem Verbindungsaufbau, Echtzeitstreams und Aufrufsteuerung nach dem Verbindungsaufbau erforderlich. -Verwenden Sie einen öffentlichen Freigabepfad: +Verwenden Sie einen öffentlichen Bereitstellungspfad: ```json5 { @@ -770,18 +775,18 @@ Verwenden Sie einen öffentlichen Freigabepfad: } ``` -Starten oder laden Sie nach einer Konfigurationsänderung den Gateway neu und führen Sie dann aus: +Starten oder laden Sie den Gateway nach der Konfigurationsänderung neu und führen Sie dann aus: ```bash openclaw voicecall setup openclaw voicecall smoke ``` -`voicecall smoke` ist ein Probelauf, sofern Sie nicht `--yes` übergeben. +`voicecall smoke` ist ein Testlauf ohne Änderungen, sofern Sie nicht `--yes` übergeben. ### Provider-Anmeldedaten schlagen fehl -Prüfen Sie den ausgewählten Provider und die erforderlichen Felder für Anmeldedaten: +Prüfen Sie den ausgewählten Provider und die erforderlichen Anmeldedatenfelder: - Twilio: `twilio.accountSid`, `twilio.authToken` und `fromNumber` oder `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` und `TWILIO_FROM_NUMBER`. @@ -789,19 +794,19 @@ Prüfen Sie den ausgewählten Provider und die erforderlichen Felder für Anmeld `fromNumber`. - Plivo: `plivo.authId`, `plivo.authToken` und `fromNumber`. -Die Anmeldedaten müssen auf dem Gateway-Host vorhanden sein. Das Bearbeiten eines lokalen Shell-Profils -wirkt sich nicht auf einen bereits laufenden Gateway aus, bis dieser neu gestartet wird oder seine +Anmeldedaten müssen auf dem Gateway-Host vorhanden sein. Das Bearbeiten eines lokalen Shell-Profils wirkt +sich nicht auf einen bereits laufenden Gateway aus, bis dieser neu gestartet wird oder seine Umgebung neu lädt. -### Anrufe starten, aber Provider-Webhooks kommen nicht an +### Aufrufe starten, aber Provider-Webhooks treffen nicht ein -Bestätigen Sie, dass die Provider-Konsole auf die exakte öffentliche Webhook-URL verweist: +Bestätigen Sie, dass die Provider-Konsole auf die exakte öffentliche Webhook-URL zeigt: ```text https://voice.example.com/voice/webhook ``` -Untersuchen Sie dann den Laufzeitstatus: +Prüfen Sie dann den Runtime-Status: ```bash openclaw voicecall status --call-id @@ -811,80 +816,82 @@ openclaw logs --follow Häufige Ursachen: -- `publicUrl` verweist auf einen anderen Pfad als `serve.path`. +- `publicUrl` zeigt auf einen anderen Pfad als `serve.path`. - Die Tunnel-URL hat sich geändert, nachdem der Gateway gestartet wurde. -- Ein Proxy leitet die Anfrage weiter, entfernt oder überschreibt aber Host-/Proto-Header. -- Firewall oder DNS routen den öffentlichen Hostnamen an einen anderen Ort als den Gateway. -- Der Gateway wurde ohne aktiviertes Voice Call-Plugin neu gestartet. +- Ein Proxy leitet die Anfrage weiter, entfernt oder überschreibt jedoch Host-/Proto-Header. +- Firewall oder DNS leiten den öffentlichen Hostnamen an ein anderes Ziel als den Gateway weiter. +- Der Gateway wurde ohne aktiviertes Voice-Call-Plugin neu gestartet. -Wenn sich ein Reverse-Proxy oder Tunnel vor dem Gateway befindet, setzen Sie +Wenn ein Reverse Proxy oder Tunnel vor dem Gateway steht, setzen Sie `webhookSecurity.allowedHosts` auf den öffentlichen Hostnamen oder verwenden Sie `webhookSecurity.trustedProxyIPs` für eine bekannte Proxy-Adresse. Verwenden Sie -`webhookSecurity.trustForwardingHeaders` nur, wenn die Proxy-Grenze unter Ihrer Kontrolle steht. +`webhookSecurity.trustForwardingHeaders` nur, wenn die Proxy-Grenze unter +Ihrer Kontrolle steht. ### Signaturprüfung schlägt fehl -Provider-Signaturen werden gegen die öffentliche URL geprüft, die OpenClaw aus der eingehenden -Anfrage rekonstruiert. Wenn Signaturen fehlschlagen: +Provider-Signaturen werden gegen die öffentliche URL geprüft, die OpenClaw +aus der eingehenden Anfrage rekonstruiert. Wenn Signaturen fehlschlagen: - Bestätigen Sie, dass die Provider-Webhook-URL exakt mit `publicUrl` übereinstimmt, einschließlich Schema, Host und Pfad. -- Aktualisieren Sie bei kostenlosen ngrok-URLs `publicUrl`, wenn sich der Tunnel-Hostname ändert. +- Aktualisieren Sie bei ngrok-URLs im kostenlosen Tarif `publicUrl`, wenn sich der Tunnel-Hostname ändert. - Stellen Sie sicher, dass der Proxy die ursprünglichen Host- und Proto-Header beibehält, oder konfigurieren Sie `webhookSecurity.allowedHosts`. - Aktivieren Sie `skipSignatureVerification` nicht außerhalb lokaler Tests. -### Google Meet-Twilio-Beitritte schlagen fehl +### Google Meet Twilio-Beitritte schlagen fehl -Google Meet verwendet dieses Plugin für Twilio-Einwahlbeitritte. Verifizieren Sie zuerst Voice Call: +Google Meet verwendet dieses Plugin für Twilio-Einwahlbeitritte. Prüfen Sie zuerst Voice Call: ```bash openclaw voicecall setup openclaw voicecall smoke --to "+15555550123" ``` -Verifizieren Sie dann den Google Meet-Transport ausdrücklich: +Prüfen Sie dann den Google-Meet-Transport explizit: ```bash openclaw googlemeet setup --transport twilio ``` Wenn Voice Call grün ist, der Meet-Teilnehmer aber nie beitritt, prüfen Sie die Meet- -Einwahlnummer, die PIN und `--dtmf-sequence`. Der Telefonanruf kann fehlerfrei sein, während -die Besprechung eine falsche DTMF-Sequenz ablehnt oder ignoriert. +Einwahlnummer, PIN und `--dtmf-sequence`. Der Telefonanruf kann fehlerfrei sein, während +das Meeting eine falsche DTMF-Sequenz ablehnt oder ignoriert. -Google Meet übergibt die Meet-DTMF-Sequenz und den Einführungstext an `voicecall.start`. -Bei Twilio-Anrufen stellt Voice Call zuerst das DTMF-TwiML bereit, leitet zurück zum -Webhook und öffnet dann den Echtzeit-Medienstream, damit die gespeicherte Einführung generiert wird, -nachdem der Telefonteilnehmer der Besprechung beigetreten ist. +Google Meet übergibt die Meet-DTMF-Sequenz und den Introtext an `voicecall.start`. +Bei Twilio-Aufrufen stellt Voice Call zuerst das DTMF-TwiML bereit, leitet zurück zum +Webhook und öffnet dann den Echtzeit-Medienstream, sodass das gespeicherte Intro erzeugt wird, +nachdem der Telefonteilnehmer dem Meeting beigetreten ist. -Verwenden Sie `openclaw logs --follow` für die Live-Phasenablaufverfolgung. Ein fehlerfreier Twilio-Meet- +Verwenden Sie `openclaw logs --follow` für die Live-Phasenverfolgung. Ein fehlerfreier Twilio-Meet- Beitritt protokolliert diese Reihenfolge: - Google Meet delegiert den Twilio-Beitritt an Voice Call. - Voice Call speichert DTMF-TwiML vor dem Verbindungsaufbau. -- Das anfängliche Twilio-TwiML wird verbraucht und vor der Echtzeitverarbeitung bereitgestellt. -- Voice Call stellt Echtzeit-TwiML für den Twilio-Anruf bereit. -- Die Echtzeit-Bridge startet mit der anfänglichen Begrüßung in der Warteschlange. +- Twilio-initiales TwiML wird vor der Echtzeitverarbeitung konsumiert und bereitgestellt. +- Voice Call stellt Echtzeit-TwiML für den Twilio-Aufruf bereit. +- Die Echtzeit-Bridge startet mit der eingereihten anfänglichen Begrüßung. -`openclaw voicecall tail` zeigt weiterhin persistierte Anrufdatensätze; es ist nützlich für -Anrufstatus und Transkripte, aber nicht jeder Webhook-/Echtzeitübergang erscheint dort. +`openclaw voicecall tail` zeigt weiterhin persistierte Aufrufdatensätze; es ist nützlich für +Aufrufstatus und Transkripte, aber nicht jeder Webhook-/Echtzeitübergang erscheint +dort. -### Echtzeitanruf hat keine Sprache +### Echtzeitaufruf hat keine Sprache Bestätigen Sie, dass nur ein Audiomodus aktiviert ist. `realtime.enabled` und `streaming.enabled` können nicht beide `true` sein. -Prüfen Sie für Echtzeit-Twilio-Anrufe außerdem: +Prüfen Sie bei Echtzeit-Twilio-Aufrufen außerdem: - Ein Echtzeit-Provider-Plugin ist geladen und registriert. -- `realtime.provider` ist nicht gesetzt oder nennt einen registrierten Provider. +- `realtime.provider` ist nicht gesetzt oder benennt einen registrierten Provider. - Der Provider-API-Schlüssel ist für den Gateway-Prozess verfügbar. - `openclaw logs --follow` zeigt, dass Echtzeit-TwiML bereitgestellt, die Echtzeit-Bridge - gestartet und die anfängliche Begrüßung in die Warteschlange gestellt wurde. + gestartet und die anfängliche Begrüßung eingereiht wurde. ## Verwandte Themen -- [Sprechmodus](/de/nodes/talk) -- [Text-to-Speech](/de/tools/tts) -- [Sprachaktivierung](/de/nodes/voicewake) +- [Talk-Modus](/de/nodes/talk) +- [Text-to-speech](/de/tools/tts) +- [Voice Wake](/de/nodes/voicewake) diff --git a/docs/de/providers/elevenlabs.md b/docs/de/providers/elevenlabs.md index 58f867b83..f68971c3e 100644 --- a/docs/de/providers/elevenlabs.md +++ b/docs/de/providers/elevenlabs.md @@ -1,32 +1,32 @@ --- read_when: - - Sie möchten ElevenLabs-Text-to-Speech in OpenClaw verwenden. - - Sie möchten ElevenLabs Scribe Speech-to-Text für Audioanhänge verwenden. - - Sie möchten ElevenLabs-Realtime-Transkription für Voice Call verwenden. -summary: ElevenLabs-Sprache, Scribe STT und Realtime-Transkription mit OpenClaw verwenden + - Sie möchten ElevenLabs-Text-to-Speech in OpenClaw verwenden + - Sie möchten die Spracherkennung von ElevenLabs Scribe für Audioanhänge verwenden + - Sie möchten ElevenLabs-Echtzeit-Transkription für Sprachanrufe oder Google Meet +summary: ElevenLabs-Sprachausgabe, Scribe-STT und Echtzeittranskription mit OpenClaw verwenden title: ElevenLabs x-i18n: - generated_at: "2026-04-25T13:55:01Z" - model: gpt-5.4 + generated_at: "2026-05-04T06:43:24Z" + model: gpt-5.5 provider: openai - source_hash: 1f858a344228c6355cd5fdc3775cddac39e0075f2e9fcf7683271f11be03a31a + source_hash: 4c880bf9dcab01ef70779c74576c70ea5d0203b96b5f739291842fafcb4bdb4b source_path: providers/elevenlabs.md - workflow: 15 + workflow: 16 --- OpenClaw verwendet ElevenLabs für Text-to-Speech, Batch-Speech-to-Text mit Scribe -v2 und Voice-Call-Streaming-STT mit Scribe v2 Realtime. +v2 und Streaming-STT mit Scribe v2 Realtime. -| Fähigkeit | OpenClaw-Oberfläche | Standard | -| ------------------------ | --------------------------------------------- | ------------------------ | -| Text-to-Speech | `messages.tts` / `talk` | `eleven_multilingual_v2` | -| Batch-Speech-to-Text | `tools.media.audio` | `scribe_v2` | -| Streaming-Speech-to-Text | Voice Call `streaming.provider: "elevenlabs"` | `scribe_v2_realtime` | +| Fähigkeit | OpenClaw-Oberfläche | Standard | +| ------------------------ | -------------------------------------------------------------------- | ------------------------ | +| Text-to-Speech | `messages.tts` / `talk` | `eleven_multilingual_v2` | +| Batch-Speech-to-Text | `tools.media.audio` | `scribe_v2` | +| Streaming-Speech-to-Text | Voice-Call-Streaming oder Google Meet `realtime.transcriptionProvider` | `scribe_v2_realtime` | ## Authentifizierung -Setzen Sie `ELEVENLABS_API_KEY` in der Umgebung. `XI_API_KEY` wird ebenfalls akzeptiert, um -mit bestehendem ElevenLabs-Tooling kompatibel zu bleiben. +Setzen Sie `ELEVENLABS_API_KEY` in der Umgebung. `XI_API_KEY` wird ebenfalls für +die Kompatibilität mit vorhandenen ElevenLabs-Tools akzeptiert. ```bash export ELEVENLABS_API_KEY="..." @@ -51,7 +51,7 @@ export ELEVENLABS_API_KEY="..." ``` Setzen Sie `modelId` auf `eleven_v3`, um ElevenLabs v3 TTS zu verwenden. OpenClaw behält -`eleven_multilingual_v2` als Standard für bestehende Installationen bei. +`eleven_multilingual_v2` als Standard für vorhandene Installationen bei. ## Speech-to-Text @@ -71,21 +71,21 @@ Verwenden Sie Scribe v2 für eingehende Audioanhänge und kurze aufgezeichnete S ``` OpenClaw sendet Multipart-Audio an ElevenLabs `/v1/speech-to-text` mit -`model_id: "scribe_v2"`. Sprachhinweise werden auf `language_code` abgebildet, wenn vorhanden. +`model_id: "scribe_v2"`. Sprachhinweise werden, sofern vorhanden, `language_code` zugeordnet. -## Voice-Call-Streaming-STT +## Streaming-STT -Das gebündelte Plugin `elevenlabs` registriert Scribe v2 Realtime für die Streaming- -Transkription von Voice Call. +Das gebündelte `elevenlabs`-Plugin registriert Scribe v2 Realtime für Voice Call und +Google Meet-Streaming-Transkription im Agentenmodus. -| Einstellung | Konfigurationspfad | Standard | -| ---------------- | --------------------------------------------------------------------------- | ------------------------------------------------- | -| API key | `plugins.entries.voice-call.config.streaming.providers.elevenlabs.apiKey` | Greift auf `ELEVENLABS_API_KEY` / `XI_API_KEY` zurück | -| Modell | `...elevenlabs.modelId` | `scribe_v2_realtime` | -| Audioformat | `...elevenlabs.audioFormat` | `ulaw_8000` | -| Sample-Rate | `...elevenlabs.sampleRate` | `8000` | -| Commit-Strategie | `...elevenlabs.commitStrategy` | `vad` | -| Sprache | `...elevenlabs.languageCode` | (nicht gesetzt) | +| Einstellung | Konfigurationspfad | Standard | +| --------------- | ------------------------------------------------------------------------- | ------------------------------------------------- | +| API-Schlüssel | `plugins.entries.voice-call.config.streaming.providers.elevenlabs.apiKey` | Fällt auf `ELEVENLABS_API_KEY` / `XI_API_KEY` zurück | +| Modell | `...elevenlabs.modelId` | `scribe_v2_realtime` | +| Audioformat | `...elevenlabs.audioFormat` | `ulaw_8000` | +| Abtastrate | `...elevenlabs.sampleRate` | `8000` | +| Commit-Strategie | `...elevenlabs.commitStrategy` | `vad` | +| Sprache | `...elevenlabs.languageCode` | (nicht gesetzt) | ```json5 { @@ -113,12 +113,18 @@ Transkription von Voice Call. ``` -Voice Call empfängt Twilio-Medien als 8-kHz-G.711-u-law. Der Realtime- -Provider von ElevenLabs verwendet standardmäßig `ulaw_8000`, sodass Telefonie-Frames ohne +Voice Call empfängt Twilio-Medien als 8 kHz G.711 u-law. Der ElevenLabs-Realtime- +Provider verwendet standardmäßig `ulaw_8000`, sodass Telefonie-Frames ohne Transkodierung weitergeleitet werden können. +Setzen Sie für den Google Meet-Agentenmodus +`plugins.entries.google-meet.config.realtime.transcriptionProvider` auf +`"elevenlabs"` und konfigurieren Sie denselben Provider-Block unter +`plugins.entries.google-meet.config.realtime.providers.elevenlabs`. + ## Verwandt - [Text-to-Speech](/de/tools/tts) +- [Google Meet](/de/plugins/google-meet) - [Modellauswahl](/de/concepts/model-providers) diff --git a/docs/de/providers/google.md b/docs/de/providers/google.md index d8bccfa0c..ba4684f10 100644 --- a/docs/de/providers/google.md +++ b/docs/de/providers/google.md @@ -2,13 +2,13 @@ read_when: - Sie möchten Google Gemini-Modelle mit OpenClaw verwenden - Sie benötigen den API-Schlüssel oder den OAuth-Authentifizierungsablauf -summary: Google Gemini einrichten (API-Schlüssel + OAuth, Bildgenerierung, Medienverständnis, TTS, Websuche) +summary: Google Gemini einrichten (API-Schlüssel + OAuth, Bilderzeugung, Medienverständnis, TTS, Websuche) title: Google (Gemini) x-i18n: - generated_at: "2026-05-02T06:42:50Z" + generated_at: "2026-05-04T06:43:25Z" model: gpt-5.5 provider: openai - source_hash: 14605b88f0d1d7e01796d429113a73b2b52a48fde6443565dcb3db47653be5e7 + source_hash: 3e45627f5d5cd57e858c7590a90435b7fc0e9381509f3312a16fc9e9a4cbd908 source_path: providers/google.md workflow: 16 --- @@ -20,16 +20,16 @@ Gemini Grounding. - Provider: `google` - Authentifizierung: `GEMINI_API_KEY` oder `GOOGLE_API_KEY` - API: Google Gemini API -- Laufzeitoption: `agents.defaults.agentRuntime.id: "google-gemini-cli"` +- Runtime-Option: `agents.defaults.agentRuntime.id: "google-gemini-cli"` verwendet Gemini CLI OAuth wieder, während Modellreferenzen kanonisch als `google/*` beibehalten werden. ## Erste Schritte -Wählen Sie Ihre bevorzugte Authentifizierungsmethode und folgen Sie den Einrichtungsschritten. +Wählen Sie Ihre bevorzugte Authentifizierungsmethode aus und folgen Sie den Einrichtungsschritten. - **Am besten geeignet für:** standardmäßigen Zugriff auf die Gemini API über Google AI Studio. + **Am besten geeignet für:** Standardzugriff auf die Gemini API über Google AI Studio. @@ -65,22 +65,22 @@ Wählen Sie Ihre bevorzugte Authentifizierungsmethode und folgen Sie den Einrich - Die Umgebungsvariablen `GEMINI_API_KEY` und `GOOGLE_API_KEY` werden beide akzeptiert. Verwenden Sie die, die Sie bereits konfiguriert haben. + Die Umgebungsvariablen `GEMINI_API_KEY` und `GOOGLE_API_KEY` werden beide akzeptiert. Verwenden Sie diejenige, die Sie bereits konfiguriert haben. - **Am besten geeignet für:** die Wiederverwendung einer bestehenden Gemini CLI-Anmeldung über PKCE OAuth anstelle eines separaten API-Schlüssels. + **Am besten geeignet für:** Wiederverwendung einer bestehenden Gemini CLI-Anmeldung über PKCE OAuth statt eines separaten API-Schlüssels. Der Provider `google-gemini-cli` ist eine inoffizielle Integration. Einige Benutzer - berichten von Kontoeinschränkungen, wenn OAuth auf diese Weise verwendet wird. Nutzung auf eigene Gefahr. + berichten von Kontobeschränkungen, wenn OAuth auf diese Weise verwendet wird. Nutzung auf eigenes Risiko. - Der lokale Befehl `gemini` muss in `PATH` verfügbar sein. + Der lokale Befehl `gemini` muss auf `PATH` verfügbar sein. ```bash # Homebrew @@ -106,17 +106,17 @@ Wählen Sie Ihre bevorzugte Authentifizierungsmethode und folgen Sie den Einrich - Standardmodell: `google/gemini-3.1-pro-preview` - - Laufzeit: `google-gemini-cli` + - Runtime: `google-gemini-cli` - Alias: `gemini-cli` - Die Gemini API-Modell-ID von Gemini 3.1 Pro ist `gemini-3.1-pro-preview`. OpenClaw akzeptiert die kürzere Form `google/gemini-3.1-pro` als praktischen Alias und normalisiert sie vor Provider-Aufrufen. + Die Modell-ID von Gemini 3.1 Pro in der Gemini API lautet `gemini-3.1-pro-preview`. OpenClaw akzeptiert den kürzeren Alias `google/gemini-3.1-pro` als Komfortalias und normalisiert ihn vor Provider-Aufrufen. **Umgebungsvariablen:** - `OPENCLAW_GEMINI_OAUTH_CLIENT_ID` - `OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET` - (Oder die Varianten `GEMINI_CLI_*`.) + (Oder die `GEMINI_CLI_*`-Varianten.) Wenn Gemini CLI OAuth-Anfragen nach der Anmeldung fehlschlagen, setzen Sie `GOOGLE_CLOUD_PROJECT` oder @@ -124,13 +124,13 @@ Wählen Sie Ihre bevorzugte Authentifizierungsmethode und folgen Sie den Einrich - Wenn die Anmeldung fehlschlägt, bevor der Browserablauf startet, stellen Sie sicher, dass der lokale Befehl `gemini` - installiert und in `PATH` verfügbar ist. + Wenn die Anmeldung fehlschlägt, bevor der Browser-Ablauf startet, stellen Sie sicher, dass der lokale Befehl `gemini` + installiert und auf `PATH` verfügbar ist. - Modellreferenzen mit `google-gemini-cli/*` sind Legacy-Kompatibilitätsaliase. Neue - Konfigurationen sollten `google/*`-Modellreferenzen plus die Laufzeit `google-gemini-cli` - verwenden, wenn sie lokale Gemini CLI-Ausführung wünschen. + `google-gemini-cli/*`-Modellreferenzen sind Legacy-Kompatibilitätsaliasse. Neue + Konfigurationen sollten `google/*`-Modellreferenzen plus die Runtime `google-gemini-cli` + verwenden, wenn sie eine lokale Gemini CLI-Ausführung wünschen. @@ -148,12 +148,12 @@ Wählen Sie Ihre bevorzugte Authentifizierungsmethode und folgen Sie den Einrich | Audiotranskription | Ja | | Videoverständnis | Ja | | Websuche (Grounding) | Ja | -| Denken/Reasoning | Ja (Gemini 2.5+ / Gemini 3+) | +| Thinking/Reasoning | Ja (Gemini 2.5+ / Gemini 3+) | | Gemma 4-Modelle | Ja | ## Websuche -Der gebündelte Websuch-Provider `gemini` verwendet Gemini Google Search Grounding. +Der gebündelte `gemini`-Websuche-Provider verwendet Gemini Google Search Grounding. Konfigurieren Sie einen dedizierten Suchschlüssel unter `plugins.entries.google.config.webSearch`, oder lassen Sie ihn nach `GEMINI_API_KEY` `models.providers.google.apiKey` wiederverwenden: @@ -175,32 +175,32 @@ oder lassen Sie ihn nach `GEMINI_API_KEY` `models.providers.google.apiKey` wiede } ``` -Die Priorität für Anmeldedaten lautet: dediziertes `webSearch.apiKey`, dann `GEMINI_API_KEY`, -dann `models.providers.google.apiKey`. `webSearch.baseUrl` ist optional und -für Betreiber-Proxys oder kompatible Gemini API-Endpunkte vorgesehen; wenn nicht angegeben, +Die Reihenfolge der Anmeldeinformationen ist zuerst der dedizierte `webSearch.apiKey`, dann `GEMINI_API_KEY` +und dann `models.providers.google.apiKey`. `webSearch.baseUrl` ist optional und +für Betreiber-Proxys oder kompatible Gemini API-Endpunkte vorgesehen; wenn es weggelassen wird, verwendet die Gemini-Websuche `models.providers.google.baseUrl` wieder. Siehe [Gemini-Suche](/de/tools/gemini-search) für das Provider-spezifische Tool-Verhalten. Gemini 3-Modelle verwenden `thinkingLevel` statt `thinkingBudget`. OpenClaw ordnet -Reasoning-Steuerungen für Gemini 3, Gemini 3.1 und Aliasnamen wie `gemini-*-latest` -`thinkingLevel` zu, sodass Standardläufe und Läufe mit niedriger Latenz keine deaktivierten +Reasoning-Steuerelemente für Gemini 3, Gemini 3.1 und `gemini-*-latest`-Aliasse +`thinkingLevel` zu, damit Standard-/Niedriglatenz-Läufe keine deaktivierten `thinkingBudget`-Werte senden. -`/think adaptive` behält Googles dynamische Denksemantik bei, anstatt eine -feste OpenClaw-Stufe zu wählen. Gemini 3 und Gemini 3.1 lassen ein festes `thinkingLevel` aus, damit +`/think adaptive` behält die dynamische Thinking-Semantik von Google bei, statt +eine feste OpenClaw-Stufe auszuwählen. Gemini 3 und Gemini 3.1 lassen ein festes `thinkingLevel` weg, damit Google die Stufe wählen kann; Gemini 2.5 sendet Googles dynamischen Sentinel `thinkingBudget: -1`. -Gemma 4-Modelle (zum Beispiel `gemma-4-26b-a4b-it`) unterstützen den Denkmodus. OpenClaw -schreibt `thinkingBudget` für Gemma 4 in ein unterstütztes Google-`thinkingLevel` um. -Wenn Denken auf `off` gesetzt wird, bleibt Denken deaktiviert, statt auf -`MINIMAL` abgebildet zu werden. +Gemma 4-Modelle (zum Beispiel `gemma-4-26b-a4b-it`) unterstützen den Thinking-Modus. OpenClaw +schreibt `thinkingBudget` in ein unterstütztes Google-`thinkingLevel` für Gemma 4 um. +Wenn Thinking auf `off` gesetzt wird, bleibt Thinking deaktiviert, statt es auf +`MINIMAL` abzubilden. ## Bilderzeugung -Der gebündelte Bilderzeugungs-Provider `google` verwendet standardmäßig +Der gebündelte `google`-Provider für Bilderzeugung verwendet standardmäßig `google/gemini-3.1-flash-image-preview`. - Unterstützt auch `google/gemini-3-pro-image-preview` @@ -208,7 +208,7 @@ Der gebündelte Bilderzeugungs-Provider `google` verwendet standardmäßig - Bearbeitungsmodus: aktiviert, bis zu 5 Eingabebilder - Geometriesteuerungen: `size`, `aspectRatio` und `resolution` -So verwenden Sie Google als Standard-Bild-Provider: +So verwenden Sie Google als Standard-Provider für Bilder: ```json5 { @@ -232,11 +232,11 @@ Das gebündelte `google`-Plugin registriert außerdem Videoerzeugung über das g Tool `video_generate`. - Standard-Videomodell: `google/veo-3.1-fast-generate-preview` -- Modi: Text-zu-Video, Bild-zu-Video und Referenzabläufe mit einem einzelnen Video +- Modi: Text-zu-Video, Bild-zu-Video und Einzelvideo-Referenzabläufe - Unterstützt `aspectRatio`, `resolution` und `audio` -- Aktuelle Begrenzung der Dauer: **4 bis 8 Sekunden** +- Aktuelle Dauerbegrenzung: **4 bis 8 Sekunden** -So verwenden Sie Google als Standard-Video-Provider: +So verwenden Sie Google als Standard-Provider für Videos: ```json5 { @@ -264,9 +264,9 @@ Tool `music_generate`. - Prompt-Steuerungen: `lyrics` und `instrumental` - Ausgabeformat: standardmäßig `mp3`, zusätzlich `wav` bei `google/lyria-3-pro-preview` - Referenzeingaben: bis zu 10 Bilder -- Sitzungsbasierte Läufe werden über den gemeinsamen Aufgaben-/Statusablauf entkoppelt, einschließlich `action: "status"` +- Sitzungsbasierte Läufe koppeln sich über den gemeinsamen Task-/Statusablauf ab, einschließlich `action: "status"` -So verwenden Sie Google als Standard-Musik-Provider: +So verwenden Sie Google als Standard-Provider für Musik: ```json5 { @@ -286,13 +286,13 @@ Siehe [Musikerzeugung](/de/tools/music-generation) für gemeinsame Tool-Paramete ## Text-to-Speech -Der gebündelte Sprach-Provider `google` verwendet den Gemini API-TTS-Pfad mit +Der gebündelte `google`-Sprach-Provider verwendet den TTS-Pfad der Gemini API mit `gemini-3.1-flash-tts-preview`. - Standardstimme: `Kore` - Authentifizierung: `messages.tts.providers.google.apiKey`, `models.providers.google.apiKey`, `GEMINI_API_KEY` oder `GOOGLE_API_KEY` - Ausgabe: WAV für reguläre TTS-Anhänge, Opus für Sprachnotiz-Ziele, PCM für Talk/Telefonie -- Sprachnotiz-Ausgabe: Google PCM wird als WAV verpackt und mit `ffmpeg` nach 48 kHz Opus transkodiert +- Sprachnotiz-Ausgabe: Google-PCM wird als WAV verpackt und mit `ffmpeg` in 48-kHz-Opus transkodiert So verwenden Sie Google als Standard-TTS-Provider: @@ -314,13 +314,13 @@ So verwenden Sie Google als Standard-TTS-Provider: } ``` -Gemini API TTS verwendet natürlichsprachliche Prompts zur Stilsteuerung. Setzen Sie +Gemini API TTS verwendet natürlichsprachliches Prompting zur Stilsteuerung. Setzen Sie `audioProfile`, um dem gesprochenen Text einen wiederverwendbaren Stil-Prompt voranzustellen. Setzen Sie `speakerName`, wenn Ihr Prompt-Text auf einen benannten Sprecher verweist. Gemini API TTS akzeptiert außerdem ausdrucksstarke Audio-Tags in eckigen Klammern im Text, -wie `[whispers]` oder `[laughs]`. Um Tags aus der sichtbaren Chat-Antwort herauszuhalten, -sie aber an TTS zu senden, platzieren Sie sie in einem `[[tts:text]]...[[/tts:text]]`- +wie `[whispers]` oder `[laughs]`. Um Tags aus der sichtbaren Chat-Antwort herauszuhalten +und sie trotzdem an TTS zu senden, setzen Sie sie in einen `[[tts:text]]...[[/tts:text]]`- Block: ```text @@ -336,23 +336,25 @@ Provider gültig. Dies ist nicht der separate Cloud Text-to-Speech API-Pfad. ## Echtzeit-Sprache -Das gebündelte `google`-Plugin registriert einen Echtzeit-Sprach-Provider, der auf der -Gemini Live API für Backend-Audiobrücken wie Voice Call und Google Meet basiert. +Das gebündelte `google`-Plugin registriert einen Echtzeit-Sprach-Provider, der durch die +Gemini Live API für Backend-Audio-Bridges wie Voice Call und Google Meet unterstützt wird. -| Einstellung | Konfigurationspfad | Standard | -| --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -| Modell | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` | -| Stimme | `...google.voice` | `Kore` | -| Temperatur | `...google.temperature` | (nicht gesetzt) | -| VAD-Startempfindlichkeit | `...google.startSensitivity` | (nicht gesetzt) | -| VAD-Endempfindlichkeit | `...google.endSensitivity` | (nicht gesetzt) | -| Stilledauer | `...google.silenceDurationMs` | (nicht gesetzt) | -| Aktivitätsbehandlung | `...google.activityHandling` | Google-Standard, `start-of-activity-interrupts` | -| Turn-Abdeckung | `...google.turnCoverage` | Google-Standard, `only-activity` | -| Auto-VAD deaktivieren | `...google.automaticActivityDetectionDisabled` | `false` | -| API-Schlüssel | `...google.apiKey` | Fällt zurück auf `models.providers.google.apiKey`, `GEMINI_API_KEY` oder `GOOGLE_API_KEY` | +| Einstellung | Konfigurationspfad | Standardwert | +| --------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | +| Modell | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` | +| Stimme | `...google.voice` | `Kore` | +| Temperatur | `...google.temperature` | (nicht gesetzt) | +| VAD-Startempfindlichkeit | `...google.startSensitivity` | (nicht gesetzt) | +| VAD-Endempfindlichkeit | `...google.endSensitivity` | (nicht gesetzt) | +| Stilledauer | `...google.silenceDurationMs` | (nicht gesetzt) | +| Aktivitätsbehandlung | `...google.activityHandling` | Google-Standard, `start-of-activity-interrupts` | +| Turn-Abdeckung | `...google.turnCoverage` | Google-Standard, `only-activity` | +| Automatische VAD deaktivieren | `...google.automaticActivityDetectionDisabled` | `false` | +| Sitzungswiederaufnahme | `...google.sessionResumption` | `true` | +| Kontextkomprimierung | `...google.contextWindowCompression` | `true` | +| API-Schlüssel | `...google.apiKey` | Fällt zurück auf `models.providers.google.apiKey`, `GEMINI_API_KEY` oder `GOOGLE_API_KEY` | -Beispiel für die Echtzeitkonfiguration für Sprachanrufe: +Beispielkonfiguration für Voice Call Realtime: ```json5 { @@ -382,38 +384,38 @@ Beispiel für die Echtzeitkonfiguration für Sprachanrufe: Die Google Live API verwendet bidirektionales Audio und Function Calling über einen WebSocket. -OpenClaw passt Audio aus der Telefonie-/Meet-Bridge an den PCM-Live-API-Stream von Gemini an und -hält Tool-Aufrufe auf dem gemeinsamen Echtzeit-Sprachvertrag. Lassen Sie `temperature` -nicht gesetzt, sofern Sie keine Sampling-Änderungen benötigen; OpenClaw lässt nicht positive Werte weg, -weil Google Live für `temperature: 0` Transkripte ohne Audio zurückgeben kann. +OpenClaw passt Audio aus Telefonie-/Meet-Bridges an den PCM-Live-API-Stream von Gemini an und +hält Tool-Aufrufe im gemeinsamen Realtime-Voice-Vertrag. Lassen Sie `temperature` +ungesetzt, sofern Sie keine Änderungen am Sampling benötigen; OpenClaw lässt nicht positive Werte aus, +weil Google Live bei `temperature: 0` Transkripte ohne Audio zurückgeben kann. Die Transkription der Gemini API wird ohne `languageCodes` aktiviert; das aktuelle Google -SDK weist Hinweise auf Sprachcodes in diesem API-Pfad zurück. +SDK lehnt Hinweise auf Sprachcodes auf diesem API-Pfad ab. Control UI Talk unterstützt Google-Live-Browsersitzungen mit eingeschränkten Einmal- -Tokens. Nur-Backend-Echtzeit-Sprachprovider können auch über den generischen -Gateway-Relay-Transport laufen, wodurch Provider-Anmeldeinformationen auf dem Gateway bleiben. +Tokens. Nur-Backend-Realtime-Voice-Provider können auch über den generischen +Gateway-Relay-Transport laufen, wodurch Provider-Zugangsdaten auf dem Gateway bleiben. Für die Live-Verifizierung durch Maintainer führen Sie `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` aus. -Der Google-Teil erstellt dieselbe eingeschränkte Live-API-Token-Form, die von Control -UI Talk verwendet wird, öffnet den Browser-WebSocket-Endpunkt, sendet die anfängliche Setup-Payload +Der Google-Zweig prägt dieselbe eingeschränkte Live-API-Token-Form, die Control +UI Talk verwendet, öffnet den Browser-WebSocket-Endpunkt, sendet die anfängliche Setup-Nutzlast und wartet auf `setupComplete`. ## Erweiterte Konfiguration - - Für direkte Gemini-API-Läufe (`api: "google-generative-ai"`) gibt OpenClaw - ein konfiguriertes `cachedContent`-Handle an Gemini-Anfragen weiter. + + Für direkte Gemini-API-Läufe (`api: "google-generative-ai"`) übergibt OpenClaw + ein konfiguriertes `cachedContent`-Handle an Gemini-Anfragen. - - Konfigurieren Sie modellbezogene oder globale Parameter entweder mit - `cachedContent` oder dem Legacy-Parameter `cached_content` - - Wenn beide vorhanden sind, hat `cachedContent` Vorrang + - Konfigurieren Sie Parameter pro Modell oder global entweder mit + `cachedContent` oder dem alten `cached_content` + - Wenn beide vorhanden sind, gewinnt `cachedContent` - Beispielwert: `cachedContents/prebuilt-context` - - Die Gemini-Cache-Treffer-Nutzung wird aus dem upstream-seitigen `cachedContentTokenCount` + - Die Gemini-Nutzung bei Cache-Treffern wird aus dem upstream `cachedContentTokenCount` in OpenClaw `cacheRead` normalisiert ```json5 @@ -434,22 +436,22 @@ und wartet auf `setupComplete`. - + Bei Verwendung des OAuth-Providers `google-gemini-cli` normalisiert OpenClaw die JSON-Ausgabe der CLI wie folgt: - Antworttext stammt aus dem CLI-JSON-Feld `response`. - Die Nutzung fällt auf `stats` zurück, wenn die CLI `usage` leer lässt. - `stats.cached` wird in OpenClaw `cacheRead` normalisiert. - - Wenn `stats.input` fehlt, leitet OpenClaw Eingabe-Tokens aus + - Wenn `stats.input` fehlt, leitet OpenClaw Eingabe-Token aus `stats.input_tokens - stats.cached` ab. - + Wenn der Gateway als Daemon läuft (launchd/systemd), stellen Sie sicher, dass `GEMINI_API_KEY` - für diesen Prozess verfügbar ist, zum Beispiel in `~/.openclaw/.env` oder über - `env.shellEnv`. + für diesen Prozess verfügbar ist (zum Beispiel in `~/.openclaw/.env` oder über + `env.shellEnv`). @@ -459,7 +461,7 @@ und wartet auf `setupComplete`. Provider, Modellreferenzen und Failover-Verhalten auswählen. - + Gemeinsame Bild-Tool-Parameter und Provider-Auswahl. diff --git a/docs/de/reference/RELEASING.md b/docs/de/reference/RELEASING.md index fd6f39768..488283185 100644 --- a/docs/de/reference/RELEASING.md +++ b/docs/de/reference/RELEASING.md @@ -1,175 +1,287 @@ --- read_when: - - Suche nach Definitionen für öffentliche Release-Kanäle + - Suche nach Definitionen öffentlicher Release-Kanäle - Release-Validierung oder Paketakzeptanz ausführen - Suche nach Versionsbenennung und Veröffentlichungsrhythmus -summary: Release-Lanes, Operator-Checkliste, Validierungsboxen, Versionsbenennung und Taktung -title: Veröffentlichungsrichtlinie +summary: Release-Lanes, Operator-Checkliste, Validierungsboxen, Versionsbenennung und Kadenz +title: Release-Richtlinie x-i18n: - generated_at: "2026-05-03T21:37:28Z" + generated_at: "2026-05-04T06:43:44Z" model: gpt-5.5 provider: openai - source_hash: 566088d826e1e2bac21b11443b82b62cb73ed1fd9c508c3fb865149cf8a428ba + source_hash: ef50d3ef5d1e23b4e2c2b097fc4ca9f6d46bf8acb9aea0c9bca6d14e213b88b6 source_path: reference/RELEASING.md workflow: 16 --- -OpenClaw hat drei öffentliche Release-Kanäle: +OpenClaw hat drei öffentliche Release-Spuren: -- stable: getaggte Releases, die standardmäßig nach npm `beta` veröffentlichen, oder nach npm `latest`, wenn dies ausdrücklich angefordert wird -- beta: Prerelease-Tags, die nach npm `beta` veröffentlichen -- dev: der bewegliche Stand von `main` +- stable: getaggte Releases, die standardmäßig auf npm `beta` veröffentlichen oder auf npm `latest`, wenn dies ausdrücklich angefordert wird +- beta: Vorab-Release-Tags, die auf npm `beta` veröffentlichen +- dev: der sich fortlaufend bewegende Stand von `main` ## Versionsbenennung -- Stable-Release-Version: `YYYY.M.D` +- Stabile Release-Version: `YYYY.M.D` - Git-Tag: `vYYYY.M.D` -- Stable-Korrekturrelease-Version: `YYYY.M.D-N` +- Stabile Korrektur-Release-Version: `YYYY.M.D-N` - Git-Tag: `vYYYY.M.D-N` -- Beta-Prerelease-Version: `YYYY.M.D-beta.N` +- Beta-Vorab-Release-Version: `YYYY.M.D-beta.N` - Git-Tag: `vYYYY.M.D-beta.N` - Monat oder Tag nicht mit führenden Nullen auffüllen -- `latest` bedeutet das aktuelle hervorgehobene stabile npm-Release +- `latest` bedeutet das aktuell hochgestufte stabile npm-Release - `beta` bedeutet das aktuelle Beta-Installationsziel -- Stable- und Stable-Korrekturreleases veröffentlichen standardmäßig nach npm `beta`; Release-Operatoren können ausdrücklich `latest` anvisieren oder einen geprüften Beta-Build später hochstufen -- Jedes stabile OpenClaw-Release liefert das npm-Paket und die macOS-App gemeinsam aus; - Beta-Releases validieren und veröffentlichen normalerweise zuerst den npm-/Paketpfad, während - Build/Signierung/Notarisierung der Mac-App für stable reserviert bleibt, sofern nicht ausdrücklich angefordert +- Stabile und stabile Korrektur-Releases veröffentlichen standardmäßig auf npm `beta`; Release-Verantwortliche können ausdrücklich `latest` anvisieren oder einen geprüften Beta-Build später hochstufen +- Jedes stabile OpenClaw-Release liefert das npm-Paket und die macOS-App zusammen aus; + Beta-Releases validieren und veröffentlichen normalerweise zuerst den npm-/Paketpfad, wobei + Build, Signierung und Notarisierung der Mac-App stabilen Releases vorbehalten bleiben, sofern nicht ausdrücklich angefordert ## Release-Takt -- Releases laufen zuerst über beta +- Releases bewegen sich zuerst über Beta - Stable folgt erst, nachdem die neueste Beta validiert wurde -- Maintainer erstellen Releases normalerweise von einem Branch `release/YYYY.M.D`, der - vom aktuellen `main` erstellt wurde, damit Release-Validierung und Fixes neue +- Maintainer erstellen Releases normalerweise von einem `release/YYYY.M.D`-Branch, der + vom aktuellen `main` erstellt wurde, damit Release-Validierung und Korrekturen neue Entwicklung auf `main` nicht blockieren -- Wenn ein Beta-Tag gepusht oder veröffentlicht wurde und einen Fix benötigt, erstellen Maintainer - das nächste `-beta.N`-Tag, statt das alte Beta-Tag zu löschen oder neu zu erstellen -- Detaillierte Release-Prozeduren, Freigaben, Zugangsdaten und Wiederherstellungshinweise sind - nur für Maintainer bestimmt +- Wenn ein Beta-Tag gepusht oder veröffentlicht wurde und eine Korrektur benötigt, erstellen Maintainer + den nächsten `-beta.N`-Tag, statt den alten Beta-Tag zu löschen oder neu zu erstellen +- Detailliertes Release-Verfahren, Freigaben, Anmeldedaten und Wiederherstellungshinweise sind + ausschließlich für Maintainer bestimmt -## Checkliste für Release-Operatoren +## Checkliste für Release-Verantwortliche -Diese Checkliste beschreibt die öffentliche Form des Release-Ablaufs. Private Zugangsdaten, -Signierung, Notarisierung, dist-tag-Wiederherstellung und Details zum Notfall-Rollback bleiben im +Diese Checkliste ist die öffentliche Form des Release-Ablaufs. Private Anmeldedaten, +Signierung, Notarisierung, Wiederherstellung von dist-tags und Details zu Notfall-Rollbacks bleiben im nur für Maintainer bestimmten Release-Runbook. -1. Vom aktuellen `main` starten: den neuesten Stand pullen, bestätigen, dass der Ziel-Commit gepusht ist, - und bestätigen, dass das aktuelle `main`-CI grün genug ist, um davon zu branchen. -2. Den obersten Abschnitt von `CHANGELOG.md` anhand der echten Commit-Historie mit - `/changelog` neu schreiben, Einträge benutzerorientiert halten, committen, pushen und - vor dem Branching noch einmal rebasen/pullen. -3. Release-Kompatibilitätsdatensätze in +1. Beginnen Sie vom aktuellen `main`: neuesten Stand pullen, bestätigen, dass der Ziel-Commit gepusht ist, + und bestätigen, dass die aktuelle CI auf `main` ausreichend grün ist, um davon zu branchen. +2. Schreiben Sie den obersten Abschnitt von `CHANGELOG.md` anhand der echten Commit-Historie mit + `/changelog` neu, halten Sie Einträge nutzerorientiert, committen und pushen Sie ihn, und führen Sie vor dem Branching + noch einmal Rebase/Pull aus. +3. Prüfen Sie Release-Kompatibilitätsdatensätze in `src/plugins/compat/registry.ts` und - `src/commands/doctor/shared/deprecation-compat.ts` prüfen. Abgelaufene - Kompatibilität nur entfernen, wenn der Upgrade-Pfad weiterhin abgedeckt ist, oder dokumentieren, warum sie - absichtlich beibehalten wird. -4. `release/YYYY.M.D` vom aktuellen `main` erstellen; normale Release-Arbeiten nicht - direkt auf `main` durchführen. -5. Jede erforderliche Versionsstelle für das geplante Tag erhöhen, dann - `pnpm plugins:sync` ausführen, damit veröffentlichbare Plugin-Pakete die Release- - Version und Kompatibilitätsmetadaten teilen, anschließend den lokalen deterministischen Preflight ausführen: + `src/commands/doctor/shared/deprecation-compat.ts`. Entfernen Sie abgelaufene + Kompatibilität nur, wenn der Upgrade-Pfad weiterhin abgedeckt bleibt, oder dokumentieren Sie, warum sie + absichtlich weitergeführt wird. +4. Erstellen Sie `release/YYYY.M.D` vom aktuellen `main`; führen Sie normale Release-Arbeit nicht + direkt auf `main` aus. +5. Erhöhen Sie jede erforderliche Versionsstelle für den vorgesehenen Tag, führen Sie + `pnpm plugins:sync` aus, damit veröffentlichbare Plugin-Pakete die Release- + Version und Kompatibilitätsmetadaten teilen, und führen Sie anschließend den lokalen deterministischen Preflight aus: `pnpm check:test-types`, `pnpm check:architecture`, `pnpm build && pnpm ui:build`, `pnpm plugins:sync:check` und `pnpm release:check`. -6. `OpenClaw NPM Release` mit `preflight_only=true` ausführen. Bevor ein Tag existiert, - ist ein vollständiger 40-Zeichen-SHA des Release-Branches für einen reinen Validierungs- - Preflight zulässig. Die erfolgreiche `preflight_run_id` speichern. -7. Alle Pre-Release-Tests mit `Full Release Validation` für den - Release-Branch, das Tag oder den vollständigen Commit-SHA starten. Dies ist der eine manuelle Einstiegspunkt +6. Führen Sie `OpenClaw NPM Release` mit `preflight_only=true` aus. Bevor ein Tag existiert, + ist ein vollständiger 40-stelliger Release-Branch-SHA für ausschließlich validierenden + Preflight zulässig. Speichern Sie die erfolgreiche `preflight_run_id`. +7. Starten Sie alle Pre-Release-Tests mit `Full Release Validation` für den + Release-Branch, Tag oder vollständigen Commit-SHA. Dies ist der eine manuelle Einstiegspunkt für die vier großen Release-Testboxen: Vitest, Docker, QA Lab und Package. -8. Wenn die Validierung fehlschlägt, auf dem Release-Branch fixen und die kleinste fehlgeschlagene - Datei, Lane, Workflow-Job, Paketprofil, den Provider oder die Modell-Allowlist erneut ausführen, die - den Fix belegt. Die vollständige Umbrella-Validierung nur erneut ausführen, wenn die geänderte Oberfläche - frühere Nachweise veralten lässt. -9. Für Beta `vYYYY.M.D-beta.N` taggen, dann `OpenClaw Release Publish` vom - passenden Branch `release/YYYY.M.D` aus ausführen. Es überprüft `pnpm plugins:sync:check`, - veröffentlicht zuerst alle veröffentlichbaren Plugin-Pakete nach npm, veröffentlicht dieselbe - Menge danach nach ClawHub als ClawPack npm-pack-Tarballs und stuft anschließend das - vorbereitete OpenClaw-npm-Preflight-Artefakt mit dem passenden dist-tag hoch. Nach - der Veröffentlichung die Post-Publish-Paket- - abnahme gegen das veröffentlichte Paket `openclaw@YYYY.M.D-beta.N` oder - `openclaw@beta` ausführen. Wenn ein gepushter oder veröffentlichter Prerelease einen Fix benötigt, - die nächste passende Prerelease-Nummer erstellen; das alte - Prerelease nicht löschen oder umschreiben. -10. Für stable erst fortfahren, nachdem die geprüfte Beta oder der Release Candidate die - erforderlichen Validierungsnachweise hat. Auch die Stable-npm-Veröffentlichung läuft über - `OpenClaw Release Publish` und verwendet das erfolgreiche Preflight-Artefakt über - `preflight_run_id` erneut; die Stable-macOS-Release-Bereitschaft erfordert außerdem die +8. Wenn die Validierung fehlschlägt, beheben Sie das Problem auf dem Release-Branch und führen Sie die kleinste fehlgeschlagene + Datei, Spur, den Workflow-Job, das Package-Profil, den Provider oder die Modell-Allowlist erneut aus, die + die Korrektur belegt. Führen Sie das vollständige Dach nur erneut aus, wenn die geänderte Oberfläche + frühere Nachweise veraltet macht. +9. Für Beta taggen Sie `vYYYY.M.D-beta.N` und führen anschließend `OpenClaw Release Publish` vom + passenden `release/YYYY.M.D`-Branch aus. Es verifiziert `pnpm plugins:sync:check`, + veröffentlicht zuerst alle veröffentlichbaren Plugin-Pakete auf npm, veröffentlicht denselben + Satz danach auf ClawHub als ClawPack-npm-pack-Tarballs und stuft dann das + vorbereitete OpenClaw-npm-Preflight-Artefakt mit dem passenden dist-tag hoch. Nach der + Veröffentlichung führen Sie die Package-Akzeptanz nach der Veröffentlichung gegen das veröffentlichte + Paket `openclaw@YYYY.M.D-beta.N` oder `openclaw@beta` aus. Wenn ein gepushter oder veröffentlichter Vorab-Release eine Korrektur benötigt, + erstellen Sie die nächste passende Vorab-Release-Nummer; löschen oder überschreiben Sie den alten + Vorab-Release nicht. +10. Für Stable fahren Sie erst fort, nachdem die geprüfte Beta oder der Release Candidate die + erforderlichen Validierungsnachweise hat. Die stabile npm-Veröffentlichung läuft ebenfalls über + `OpenClaw Release Publish`, wobei das erfolgreiche Preflight-Artefakt über + `preflight_run_id` wiederverwendet wird; die Release-Bereitschaft für stabiles macOS erfordert außerdem die paketierten `.zip`, `.dmg`, `.dSYM.zip` und die aktualisierte `appcast.xml` auf `main`. -11. Nach der Veröffentlichung den npm-Post-Publish-Verifier ausführen, optional den eigenständigen - published-npm Telegram E2E, wenn Sie einen Post-Publish-Kanalnachweis benötigen, - dist-tag-Hochstufung bei Bedarf, GitHub-Release-/Prerelease-Notizen aus dem - vollständigen passenden Abschnitt von `CHANGELOG.md` und die Schritte für die Release-Ankündigung. +11. Nach der Veröffentlichung führen Sie den npm-Post-Publish-Verifizierer aus, optional die eigenständige + Telegram-E2E mit veröffentlichtem npm, wenn Sie Channel-Nachweis nach der Veröffentlichung benötigen, + dist-tag-Hochstufung bei Bedarf, GitHub-Release-/Vorab-Release-Notizen aus dem + vollständigen passenden Abschnitt von `CHANGELOG.md` sowie die Schritte für die Release-Ankündigung. ## Release-Preflight -- Führen Sie `pnpm check:test-types` vor dem Release-Preflight aus, damit Test-TypeScript auch außerhalb des schnelleren lokalen `pnpm check`-Gates abgedeckt bleibt. -- Führen Sie `pnpm check:architecture` vor dem Release-Preflight aus, damit die umfassenderen Importzyklus- und Architekturgrenzen-Prüfungen außerhalb des schnelleren lokalen Gates grün sind. -- Führen Sie `pnpm build && pnpm ui:build` vor `pnpm release:check` aus, damit die erwarteten `dist/*`-Release-Artefakte und das Control-UI-Bundle für den Pack-Validierungsschritt vorhanden sind. -- Führen Sie `pnpm plugins:sync` nach dem Versions-Bump im Root und vor dem Tagging aus. Es aktualisiert veröffentlichbare Plugin-Paketversionen, OpenClaw-Peer/API-Kompatibilitätsmetadaten, Build-Metadaten und Plugin-Changelog-Stubs passend zur Core-Release-Version. `pnpm plugins:sync:check` ist der nicht verändernde Release-Schutz; der Publish-Workflow schlägt vor jeder Registry-Mutation fehl, wenn dieser Schritt vergessen wurde. -- Führen Sie den manuellen Workflow `Full Release Validation` vor der Release-Freigabe aus, um alle Pre-Release-Testboxen von einem Einstiegspunkt aus zu starten. Er akzeptiert einen Branch, ein Tag oder eine vollständige Commit-SHA, dispatcht manuell `CI` und dispatcht `OpenClaw Release Checks` für Install-Smoke, Package Acceptance, Docker-Release-Pfad-Suites, Live/E2E, OpenWebUI, QA-Lab-Parität, Matrix- und Telegram-Lanes. Mit `release_profile=full` und `rerun_group=all` führt er außerdem Paket-Telegram-E2E gegen das Artefakt `release-package-under-test` aus den Release Checks aus. Geben Sie `npm_telegram_package_spec` nach der Veröffentlichung an, wenn dieselbe Telegram-E2E auch das veröffentlichte npm-Paket nachweisen soll. Geben Sie `package_acceptance_package_spec` nach der Veröffentlichung an, wenn Package Acceptance seine Paket-/Update-Matrix gegen das ausgelieferte npm-Paket statt gegen das aus der SHA gebaute Artefakt ausführen soll. Geben Sie `evidence_package_spec` an, wenn der private Nachweisbericht belegen soll, dass die Validierung einem veröffentlichten npm-Paket entspricht, ohne Telegram-E2E zu erzwingen. Beispiel: +- Führen Sie `pnpm check:test-types` vor dem Release-Preflight aus, damit Test-TypeScript + außerhalb des schnelleren lokalen `pnpm check`-Gates abgedeckt bleibt +- Führen Sie `pnpm check:architecture` vor dem Release-Preflight aus, damit die umfassenderen Prüfungen auf Importzyklen + und Architekturgrenzen außerhalb des schnelleren lokalen Gates grün sind +- Führen Sie `pnpm build && pnpm ui:build` vor `pnpm release:check` aus, damit die erwarteten + `dist/*`-Release-Artefakte und das Control-UI-Bundle für den Pack- + Validierungsschritt vorhanden sind +- Führen Sie `pnpm plugins:sync` nach dem Root-Versionsbump und vor dem Tagging aus. Es + aktualisiert veröffentlichbare Plugin-Paketversionen, OpenClaw-Peer/API-Kompatibilitäts- + Metadaten, Build-Metadaten und Plugin-Changelog-Stubs passend zur Core- + Release-Version. `pnpm plugins:sync:check` ist der nicht mutierende Release-Guard; + der Veröffentlichungs-Workflow schlägt vor jeder Registry-Mutation fehl, wenn dieser Schritt + vergessen wurde. +- Führen Sie den manuellen `Full Release Validation`-Workflow vor der Release-Freigabe aus, um + alle Pre-Release-Testboxen von einem Einstiegspunkt aus zu starten. Er akzeptiert einen Branch, + Tag oder vollständigen Commit-SHA, stößt manuelles `CI` an und stößt + `OpenClaw Release Checks` für Install-Smoke, Package Acceptance, Docker- + Release-Pfad-Suites, Live/E2E, OpenWebUI, QA-Lab-Parität, Matrix- und Telegram- + Lanes an. Mit `release_profile=full` und `rerun_group=all` führt er außerdem Package + Telegram E2E gegen das `release-package-under-test`-Artefakt aus den Release- + Checks aus. Geben Sie `npm_telegram_package_spec` nach der Veröffentlichung an, wenn derselbe + Telegram E2E auch das veröffentlichte npm-Paket nachweisen soll. Geben Sie + `package_acceptance_package_spec` nach der Veröffentlichung an, wenn Package Acceptance + seine Paket-/Update-Matrix gegen das ausgelieferte npm-Paket statt + gegen das aus dem SHA gebaute Artefakt ausführen soll. Geben Sie + `evidence_package_spec` an, wenn der private Evidenzbericht nachweisen soll, dass die + Validierung zu einem veröffentlichten npm-Paket passt, ohne Telegram E2E zu erzwingen. + Beispiel: `gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D` -- Führen Sie den manuellen Workflow `Package Acceptance` aus, wenn Sie einen Side-Channel-Nachweis für einen Paketkandidaten wünschen, während die Release-Arbeit weiterläuft. Verwenden Sie `source=npm` für `openclaw@beta`, `openclaw@latest` oder eine exakte Release-Version; `source=ref`, um einen vertrauenswürdigen `package_ref`-Branch/Tag/SHA mit dem aktuellen `workflow_ref`-Harness zu packen; `source=url` für einen HTTPS-Tarball mit erforderlicher SHA-256; oder `source=artifact` für einen Tarball, der von einem anderen GitHub-Actions-Lauf hochgeladen wurde. Der Workflow löst den Kandidaten zu `package-under-test` auf, verwendet den Docker-E2E-Release-Scheduler gegen diesen Tarball erneut und kann Telegram-QA gegen denselben Tarball mit `telegram_mode=mock-openai` oder `telegram_mode=live-frontier` ausführen. Wenn die ausgewählten Docker-Lanes `published-upgrade-survivor` enthalten, ist das Paketartefakt der Kandidat und `published_upgrade_survivor_baseline` wählt die veröffentlichte Baseline aus. +- Führen Sie den manuellen `Package Acceptance`-Workflow aus, wenn Sie Side-Channel-Nachweise + für einen Paketkandidaten wünschen, während die Release-Arbeit weiterläuft. Verwenden Sie `source=npm` für + `openclaw@beta`, `openclaw@latest` oder eine exakte Release-Version; `source=ref`, + um einen vertrauenswürdigen `package_ref`-Branch/Tag/SHA mit dem aktuellen + `workflow_ref`-Harness zu packen; `source=url` für einen HTTPS-Tarball mit erforderlichem + SHA-256; oder `source=artifact` für einen Tarball, der von einem anderen GitHub- + Actions-Lauf hochgeladen wurde. Der Workflow löst den Kandidaten zu + `package-under-test` auf, verwendet den Docker-E2E-Release-Scheduler gegen diesen + Tarball wieder und kann Telegram-QA gegen denselben Tarball mit + `telegram_mode=mock-openai` oder `telegram_mode=live-frontier` ausführen. Wenn die + ausgewählten Docker-Lanes `published-upgrade-survivor` enthalten, ist das Paket- + Artefakt der Kandidat und `published_upgrade_survivor_baseline` wählt + die veröffentlichte Baseline aus. Beispiel: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai` - Gängige Profile: - - `smoke`: Install-/Channel-/Agent-, Gateway-Netzwerk- und Konfigurations-Reload-Lanes + Häufige Profile: + - `smoke`: Installations-/Kanal-/Agent-, Gateway-Netzwerk- und Konfigurations-Reload-Lanes - `package`: artefaktnative Paket-/Update-/Plugin-Lanes ohne OpenWebUI oder Live-ClawHub - - `product`: Paketprofil plus MCP-Channels, Cron-/Subagent-Bereinigung, OpenAI-Websuche und OpenWebUI - - `full`: Docker-Release-Pfad-Chunks mit OpenWebUI + - `product`: Paketprofil plus MCP-Kanäle, Cron-/Subagent-Bereinigung, + OpenAI-Websuche und OpenWebUI + - `full`: Docker-Release-Pfad-Blöcke mit OpenWebUI - `custom`: exakte `docker_lanes`-Auswahl für einen fokussierten erneuten Lauf -- Führen Sie den manuellen Workflow `CI` direkt aus, wenn Sie nur vollständige normale CI-Abdeckung für den Release-Kandidaten benötigen. Manuelle CI-Dispatches umgehen Changed-Scoping und erzwingen die Linux-Node-Shards, gebündelten Plugin-Shards, Channel-Verträge, Node-22-Kompatibilität, `check`, `check-additional`, Build-Smoke, Docs-Checks, Python-Skills, Windows, macOS, Android und Control-UI-i18n-Lanes. +- Führen Sie den manuellen `CI`-Workflow direkt aus, wenn Sie nur die vollständige normale CI- + Abdeckung für den Release-Kandidaten benötigen. Manuelle CI-Dispatches umgehen das Changed- + Scoping und erzwingen die Linux-Node-Shards, Bundled-Plugin-Shards, Kanal- + Verträge, Node-22-Kompatibilität, `check`, `check-additional`, Build-Smoke, + Docs-Prüfungen, Python-Skills, Windows, macOS, Android und Control-UI-i18n- + Lanes. Beispiel: `gh workflow run ci.yml --ref release/YYYY.M.D` -- Führen Sie `pnpm qa:otel:smoke` aus, wenn Sie Release-Telemetrie validieren. Es übt QA-Lab über einen lokalen OTLP/HTTP-Receiver aus und verifiziert die exportierten Trace-Span-Namen, begrenzten Attribute sowie Inhalts-/Kennungs-Redaktion, ohne Opik, Langfuse oder einen anderen externen Collector zu benötigen. -- Führen Sie `pnpm release:check` vor jedem getaggten Release aus. -- Führen Sie `OpenClaw Release Publish` für die verändernde Publish-Sequenz aus, nachdem das Tag existiert. Dispatchen Sie ihn von `release/YYYY.M.D` (oder `main`, wenn ein von `main` erreichbares Tag veröffentlicht wird), übergeben Sie das Release-Tag und die erfolgreiche OpenClaw-npm-`preflight_run_id` und behalten Sie den standardmäßigen Plugin-Publish-Scope `all-publishable` bei, sofern Sie nicht bewusst eine fokussierte Reparatur ausführen. Der Workflow serialisiert Plugin-npm-Publish, Plugin-ClawHub-Publish und OpenClaw-npm-Publish, damit das Core-Paket nicht vor seinen externalisierten Plugins veröffentlicht wird. -- Release Checks laufen jetzt in einem separaten manuellen Workflow: +- Führen Sie `pnpm qa:otel:smoke` aus, wenn Sie Release-Telemetrie validieren. Es führt + QA-Lab über einen lokalen OTLP/HTTP-Empfänger aus und verifiziert die exportierten Trace- + Span-Namen, begrenzten Attribute sowie Inhalts-/Kennungs-Redaktion, ohne + Opik, Langfuse oder einen anderen externen Collector zu benötigen. +- Führen Sie `pnpm release:check` vor jedem getaggten Release aus +- Führen Sie `OpenClaw Release Publish` für die mutierende Veröffentlichungssequenz aus, nachdem das + Tag existiert. Dispatchen Sie ihn von `release/YYYY.M.D` (oder `main`, wenn Sie ein + von main erreichbares Tag veröffentlichen), übergeben Sie das Release-Tag und die erfolgreiche OpenClaw-npm- + `preflight_run_id` und behalten Sie den standardmäßigen Plugin-Veröffentlichungsumfang + `all-publishable` bei, sofern Sie nicht bewusst eine fokussierte Reparatur ausführen. Der + Workflow serialisiert Plugin-npm-Veröffentlichung, Plugin-ClawHub-Veröffentlichung und OpenClaw- + npm-Veröffentlichung, damit das Core-Paket nicht vor seinen externalisierten + Plugins veröffentlicht wird. +- Release-Prüfungen laufen jetzt in einem separaten manuellen Workflow: `OpenClaw Release Checks` -- `OpenClaw Release Checks` führt außerdem die QA-Lab-Mock-Paritäts-Lane sowie das schnelle Live-Matrix-Profil und die Telegram-QA-Lane vor der Release-Freigabe aus. Die Live-Lanes verwenden die Umgebung `qa-live-shared`; Telegram verwendet zusätzlich Convex-CI-Credential-Leases. Führen Sie den manuellen Workflow `QA-Lab - All Lanes` mit `matrix_profile=all` und `matrix_shards=true` aus, wenn Sie vollständigen Matrix-Transport, Medien und E2EE-Inventar parallel wünschen. -- Cross-OS-Installations- und Upgrade-Laufzeitvalidierung ist Teil der öffentlichen `OpenClaw Release Checks` und der `Full Release Validation`, die den wiederverwendbaren Workflow `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` direkt aufrufen. -- Diese Aufteilung ist beabsichtigt: Halten Sie den echten npm-Release-Pfad kurz, deterministisch und artefaktfokussiert, während langsamere Live-Checks in ihrer eigenen Lane bleiben, damit sie das Veröffentlichen nicht verzögern oder blockieren. -- Release Checks mit Geheimnissen sollten über `Full Release Validation` oder vom `main`-/Release-Workflow-Ref dispatcht werden, damit Workflow-Logik und Secrets kontrolliert bleiben. -- `OpenClaw Release Checks` akzeptiert einen Branch, ein Tag oder eine vollständige Commit-SHA, solange der aufgelöste Commit von einem OpenClaw-Branch oder Release-Tag erreichbar ist. -- Der nur validierende Preflight von `OpenClaw NPM Release` akzeptiert auch die aktuelle vollständige 40-Zeichen-Commit-SHA des Workflow-Branches, ohne ein gepushtes Tag zu verlangen. -- Dieser SHA-Pfad dient nur der Validierung und kann nicht in einen echten Publish überführt werden. -- Im SHA-Modus synthetisiert der Workflow `v` nur für den Paketmetadaten-Check; echter Publish erfordert weiterhin ein echtes Release-Tag. -- Beide Workflows behalten den echten Publish- und Promotion-Pfad auf GitHub-gehosteten Runnern, während der nicht verändernde Validierungspfad die größeren Blacksmith-Linux-Runner verwenden kann. -- Dieser Workflow führt `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` mit den Workflow-Secrets `OPENAI_API_KEY` und `ANTHROPIC_API_KEY` aus. -- Der npm-Release-Preflight wartet nicht mehr auf die separate Release-Checks-Lane. -- Führen Sie `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` (oder das passende Beta-/Korrektur-Tag) vor der Freigabe aus. -- Führen Sie nach dem npm-Publish `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` (oder die passende Beta-/Korrekturversion) aus, um den veröffentlichten Registry-Installationspfad in einem frischen temporären Prefix zu verifizieren. -- Führen Sie nach einem Beta-Publish `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` aus, um Installed-Package-Onboarding, Telegram-Einrichtung und echtes Telegram-E2E gegen das veröffentlichte npm-Paket mit dem gemeinsam geleasten Telegram-Credential-Pool zu verifizieren. Lokale einmalige Maintainer-Läufe können die Convex-Variablen weglassen und die drei `OPENCLAW_QA_TELEGRAM_*`-Env-Credentials direkt übergeben. -- Maintainer können denselben Post-Publish-Check über den manuellen Workflow `NPM Telegram Beta E2E` von GitHub Actions ausführen. Er ist absichtlich nur manuell und läuft nicht bei jedem Merge. -- Die Maintainer-Release-Automatisierung verwendet jetzt Preflight-dann-Promote: - - echter npm-Publish muss eine erfolgreiche npm-`preflight_run_id` bestehen - - der echte npm-Publish muss von demselben `main`- oder `release/YYYY.M.D`-Branch dispatcht werden wie der erfolgreiche Preflight-Lauf - - stabile npm-Releases setzen standardmäßig auf `beta` - - stabiler npm-Publish kann über Workflow-Input explizit `latest` anvisieren - - tokenbasierte npm-Dist-Tag-Mutation befindet sich jetzt aus Sicherheitsgründen in `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`, weil `npm dist-tag add` weiterhin `NPM_TOKEN` benötigt, während das öffentliche Repo OIDC-only-Publish beibehält - - öffentlicher `macOS Release` dient nur der Validierung; wenn ein Tag nur auf einem Release-Branch liegt, der Workflow aber von `main` dispatcht wird, setzen Sie `public_release_branch=release/YYYY.M.D` - - echter privater Mac-Publish muss erfolgreiche private Mac-`preflight_run_id` und `validate_run_id` bestehen - - die echten Publish-Pfade promoten vorbereitete Artefakte, statt sie erneut zu bauen -- Für stabile Korrektur-Releases wie `YYYY.M.D-N` prüft der Post-Publish-Verifier außerdem denselben Temp-Prefix-Upgrade-Pfad von `YYYY.M.D` zu `YYYY.M.D-N`, damit Release-Korrekturen ältere globale Installationen nicht stillschweigend auf dem stabilen Basis-Payload belassen. -- Der npm-Release-Preflight schlägt geschlossen fehl, sofern der Tarball nicht sowohl `dist/control-ui/index.html` als auch einen nicht leeren `dist/control-ui/assets/`-Payload enthält, damit wir nicht erneut ein leeres Browser-Dashboard ausliefern. -- Die Post-Publish-Verifizierung prüft außerdem, dass veröffentlichte Plugin-Entrypoints und Paketmetadaten im installierten Registry-Layout vorhanden sind. Ein Release, dem Plugin-Runtime-Payloads fehlen, schlägt im Postpublish-Verifier fehl und kann nicht zu `latest` promotet werden. -- `pnpm test:install:smoke` erzwingt außerdem das npm-Pack-`unpackedSize`-Budget für den Kandidaten-Update-Tarball, damit Installer-E2E versehentliches Pack-Bloat vor dem Release-Publish-Pfad erkennt. -- Wenn die Release-Arbeit CI-Planung, Plugin-Timing-Manifeste oder Plugin-Testmatrizen berührt hat, regenerieren und prüfen Sie vor der Freigabe die Planner-eigenen `plugin-prerelease-extension-shard`-Matrix-Ausgaben aus `.github/workflows/plugin-prerelease.yml`, damit Release Notes kein veraltetes CI-Layout beschreiben. -- Die Bereitschaft für stabile macOS-Releases umfasst außerdem die Updater-Oberflächen: - - das GitHub-Release muss am Ende die paketierten `.zip`, `.dmg` und `.dSYM.zip` enthalten - - `appcast.xml` auf `main` muss nach dem Publish auf die neue stabile Zip zeigen - - die paketierte App muss eine Nicht-Debug-Bundle-ID, eine nicht leere Sparkle-Feed-URL und eine `CFBundleVersion` auf oder über dem kanonischen Sparkle-Build-Floor für diese Release-Version behalten +- `OpenClaw Release Checks` führt vor der Release-Freigabe außerdem die QA-Lab-Mock-Paritäts-Lane sowie das schnelle + Live-Matrix-Profil und die Telegram-QA-Lane aus. Die Live- + Lanes verwenden die Umgebung `qa-live-shared`; Telegram verwendet außerdem Convex-CI- + Credential-Leases. Führen Sie den manuellen `QA-Lab - All Lanes`-Workflow mit + `matrix_profile=all` und `matrix_shards=true` aus, wenn Sie vollständigen Matrix- + Transport, Medien und E2EE-Inventar parallel wünschen. +- Cross-OS-Installations- und Upgrade-Laufzeitvalidierung ist Teil der öffentlichen + `OpenClaw Release Checks` und `Full Release Validation`, die den + wiederverwendbaren Workflow + `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` direkt aufrufen +- Diese Aufteilung ist beabsichtigt: Der echte npm-Release-Pfad bleibt kurz, + deterministisch und artefaktorientiert, während langsamere Live-Prüfungen in ihrer + eigenen Lane bleiben, damit sie die Veröffentlichung nicht verzögern oder blockieren +- Release-Prüfungen mit Secrets sollten über `Full Release +Validation` oder aus der `main`-/Release-Workflow-Ref dispatcht werden, damit Workflow-Logik und + Secrets kontrolliert bleiben +- `OpenClaw Release Checks` akzeptiert einen Branch, ein Tag oder einen vollständigen Commit-SHA, solange + der aufgelöste Commit von einem OpenClaw-Branch oder Release-Tag erreichbar ist +- Der reine Validierungs-Preflight von `OpenClaw NPM Release` akzeptiert auch den aktuellen + vollständigen 40-Zeichen-Workflow-Branch-Commit-SHA, ohne ein gepushtes Tag zu erfordern +- Dieser SHA-Pfad dient nur der Validierung und kann nicht in eine echte Veröffentlichung + überführt werden +- Im SHA-Modus synthetisiert der Workflow `v` nur für die + Paketmetadatenprüfung; echte Veröffentlichung erfordert weiterhin ein echtes Release-Tag +- Beide Workflows behalten den echten Veröffentlichungs- und Promotion-Pfad auf GitHub-gehosteten + Runnern, während der nicht mutierende Validierungspfad die größeren + Blacksmith-Linux-Runner verwenden kann +- Dieser Workflow führt + `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` + unter Verwendung der Workflow-Secrets `OPENAI_API_KEY` und `ANTHROPIC_API_KEY` aus +- Der npm-Release-Preflight wartet nicht mehr auf die separate Release-Checks-Lane +- Führen Sie `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` + (oder das passende Beta-/Korrektur-Tag) vor der Freigabe aus +- Führen Sie nach der npm-Veröffentlichung + `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` + (oder die passende Beta-/Korrekturversion) aus, um den veröffentlichten Registry- + Installationspfad in einem frischen temporären Präfix zu verifizieren +- Führen Sie nach einer Beta-Veröffentlichung `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` + aus, um Installed-Package-Onboarding, Telegram-Einrichtung und echtes Telegram E2E + gegen das veröffentlichte npm-Paket mit dem gemeinsamen geleasten Telegram-Credential- + Pool zu verifizieren. Lokale Maintainer-Einmalläufe können die Convex-Variablen weglassen und die drei + `OPENCLAW_QA_TELEGRAM_*`-Env-Credentials direkt übergeben. +- Um den vollständigen Post-Publish-Beta-Smoke von einem Maintainer-Rechner aus auszuführen, verwenden Sie `pnpm release:beta-smoke -- --beta betaN`. Der Helper führt Parallels-npm-Update-/Fresh-Target-Validierung aus, dispatcht `NPM Telegram Beta E2E`, pollt den exakten Workflow-Lauf, lädt das Artefakt herunter und gibt den Telegram-Bericht aus. +- Maintainer können dieselbe Post-Publish-Prüfung über GitHub Actions mit dem + manuellen `NPM Telegram Beta E2E`-Workflow ausführen. Er ist absichtlich nur manuell und + läuft nicht bei jedem Merge. +- Maintainer-Release-Automatisierung verwendet jetzt Preflight-dann-Promote: + - echte npm-Veröffentlichung muss eine erfolgreiche npm-`preflight_run_id` bestanden haben + - die echte npm-Veröffentlichung muss vom selben `main`- oder + `release/YYYY.M.D`-Branch dispatcht werden wie der erfolgreiche Preflight-Lauf + - stabile npm-Releases verwenden standardmäßig `beta` + - stabile npm-Veröffentlichung kann über Workflow-Eingabe explizit `latest` anvisieren + - tokenbasierte npm-Dist-Tag-Mutation liegt jetzt in + `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` + aus Sicherheitsgründen, weil `npm dist-tag add` weiterhin `NPM_TOKEN` benötigt, während das + öffentliche Repo OIDC-only-Veröffentlichung beibehält + - öffentliches `macOS Release` dient nur der Validierung; wenn ein Tag nur auf einem + Release-Branch existiert, der Workflow aber von `main` dispatcht wird, setzen Sie + `public_release_branch=release/YYYY.M.D` + - echte private Mac-Veröffentlichung muss erfolgreiche private Mac- + `preflight_run_id` und `validate_run_id` bestanden haben + - die echten Veröffentlichungspfade promoten vorbereitete Artefakte, statt sie + erneut zu bauen +- Für stabile Korrektur-Releases wie `YYYY.M.D-N` prüft der Post-Publish-Verifier + außerdem denselben Temp-Präfix-Upgrade-Pfad von `YYYY.M.D` zu `YYYY.M.D-N`, + damit Release-Korrekturen ältere globale Installationen nicht unbemerkt auf der + stabilen Basis-Payload zurücklassen können +- Der npm-Release-Preflight schlägt geschlossen fehl, sofern der Tarball nicht sowohl + `dist/control-ui/index.html` als auch eine nicht leere `dist/control-ui/assets/`-Payload enthält, + damit wir nicht erneut ein leeres Browser-Dashboard ausliefern +- Die Post-Publish-Verifizierung prüft außerdem, dass veröffentlichte Plugin-Einstiegspunkte und + Paketmetadaten im installierten Registry-Layout vorhanden sind. Ein Release, das + fehlende Plugin-Runtime-Payloads ausliefert, lässt den Postpublish-Verifier fehlschlagen und + kann nicht zu `latest` promotet werden. +- `pnpm test:install:smoke` erzwingt außerdem das npm-Pack-`unpackedSize`-Budget für + den Kandidaten-Update-Tarball, sodass Installer-E2E versehentliches Pack-Bloat + vor dem Release-Veröffentlichungspfad erkennt +- Wenn die Release-Arbeit CI-Planung, Extension-Timing-Manifeste oder + Extension-Testmatrizen berührt hat, generieren und prüfen Sie vor der Freigabe die vom Planner verwalteten + `plugin-prerelease-extension-shard`-Matrix-Ausgaben aus + `.github/workflows/plugin-prerelease.yml`, damit Release Notes keine + veraltete CI-Struktur beschreiben +- Die Bereitschaft eines stabilen macOS-Releases umfasst auch die Updater-Oberflächen: + - das GitHub-Release muss am Ende die gepackte `.zip`, `.dmg` und `.dSYM.zip` enthalten + - `appcast.xml` auf `main` muss nach der Veröffentlichung auf die neue stabile Zip verweisen + - die gepackte App muss eine Nicht-Debug-Bundle-ID, eine nicht leere Sparkle-Feed- + URL und eine `CFBundleVersion` auf oder über dem kanonischen Sparkle-Build-Floor + für diese Release-Version behalten ## Release-Testboxen -`Full Release Validation` ist der Weg, wie Operatoren alle Pre-Release-Tests von einem Einstiegspunkt aus starten. Für einen gepinnten Commit-Nachweis auf einem schnell fortschreitenden Branch verwenden Sie den Helper, damit jeder Child-Workflow von einem temporären Branch läuft, der auf die Ziel-SHA fixiert ist: +`Full Release Validation` ist der Weg, wie Operatoren alle Pre-Release-Tests von +einem Einstiegspunkt aus starten. Für einen gepinnten Commit-Nachweis auf einem schnelllebigen Branch verwenden Sie den +Helper, damit jeder Child-Workflow von einem temporären Branch ausgeht, der auf den Ziel- +SHA fixiert ist: ```bash pnpm ci:full-release --sha ``` -Der Helper pusht `release-ci/-...`, dispatcht `Full Release Validation` von diesem Branch mit `ref=`, verifiziert, dass jede Child-Workflow-`headSha` dem Ziel entspricht, und löscht anschließend den temporären Branch. So vermeiden Sie, versehentlich einen neueren `main`-Child-Lauf nachzuweisen. +Der Helper pusht `release-ci/-...`, dispatcht `Full Release Validation` +von diesem Branch mit `ref=`, verifiziert, dass jede Child-Workflow-`headSha` +zum Ziel passt, und löscht dann den temporären Branch. Dadurch wird vermieden, versehentlich einen +neueren `main`-Child-Lauf nachzuweisen. -Für die Validierung eines Release-Branches oder Tags führen Sie ihn vom vertrauenswürdigen `main`-Workflow-Ref aus und übergeben den Release-Branch oder das Tag als `ref`: +Für Release-Branch- oder Tag-Validierung führen Sie ihn von der vertrauenswürdigen `main`-Workflow- +Ref aus und übergeben den Release-Branch oder das Tag als `ref`: ```bash gh workflow run full-release-validation.yml \ @@ -183,46 +295,45 @@ gh workflow run full-release-validation.yml \ Der Workflow löst die Ziel-Ref auf, dispatcht manuell `CI` mit `target_ref=`, dispatcht `OpenClaw Release Checks`, bereitet ein -übergeordnetes Artefakt `release-package-under-test` für paketbezogene Prüfungen vor und -dispatcht eigenständige Paket-Telegram-E2E, wenn `release_profile=full` mit +übergeordnetes `release-package-under-test`-Artefakt für packagebezogene Checks +vor und dispatcht eigenständiges Package-Telegram-E2E, wenn `release_profile=full` mit `rerun_group=all` verwendet wird oder wenn `npm_telegram_package_spec` gesetzt ist. `OpenClaw Release -Checks` fächert dann Install-Smoke, Cross-OS-Release-Prüfungen, Live-/E2E-Docker- -Abdeckung für den Release-Pfad, Package Acceptance mit Telegram-Paket-QA, QA-Lab- -Parität, Live-Matrix und Live-Telegram auf. Ein vollständiger Lauf ist nur akzeptabel, wenn die -Zusammenfassung von `Full Release Validation` -`normal_ci` und `release_checks` als erfolgreich ausweist. Im full/all-Modus -muss auch der untergeordnete Lauf `npm_telegram` erfolgreich sein; außerhalb von full/all wird er übersprungen, -sofern keine veröffentlichte `npm_telegram_package_spec` angegeben wurde. Die finale -Prüferzusammenfassung enthält Tabellen der langsamsten Jobs für jeden untergeordneten Lauf, sodass der Release- -Manager den aktuellen kritischen Pfad sehen kann, ohne Logs herunterzuladen. +Checks` fächert anschließend in Install-Smoke, Cross-OS-Release-Checks, +Live/E2E-Docker-Abdeckung für den Release-Pfad, Package Acceptance mit Telegram-Package-QA, QA Lab +Parity, Live Matrix und Live Telegram auf. Ein vollständiger Lauf ist nur akzeptabel, wenn die +Zusammenfassung von `Full Release Validation` `normal_ci` und `release_checks` als erfolgreich +anzeigt. Im full/all-Modus muss auch das Kind `npm_telegram` erfolgreich sein; außerhalb von full/all wird es übersprungen, +sofern keine veröffentlichte `npm_telegram_package_spec` angegeben wurde. Die abschließende +Verifier-Zusammenfassung enthält Tabellen der langsamsten Jobs für jeden Kindlauf, sodass die Release-Verantwortlichen +den aktuellen kritischen Pfad sehen können, ohne Logs herunterzuladen. Siehe [Vollständige Release-Validierung](/de/reference/full-release-validation) für die -vollständige Phasenmatrix, die exakten Workflow-Jobnamen, Unterschiede zwischen Stable- und Full-Profil, -Artefakte und gezielte Rerun-Handles. -Untergeordnete Workflows werden von der vertrauenswürdigen Ref dispatcht, auf der `Full Release -Validation` läuft, normalerweise `--ref main`, auch wenn die Ziel-`ref` auf einen +vollständige Stufenmatrix, exakte Workflow-Jobnamen, Unterschiede zwischen stable- und full-Profil, +Artefakte und fokussierte Rerun-Handles. +Kind-Workflows werden von der vertrauenswürdigen Ref dispatcht, die `Full Release +Validation` ausführt, normalerweise `--ref main`, auch wenn die Ziel-`ref` auf einen älteren Release-Branch oder Tag zeigt. Es gibt keine separate Full-Release-Validation- Workflow-Ref-Eingabe; wählen Sie den vertrauenswürdigen Harness, indem Sie die Ref des Workflow-Laufs wählen. -Verwenden Sie `--ref main -f ref=` nicht für exakten Commit-Nachweis auf einem sich bewegenden `main`; +Verwenden Sie `--ref main -f ref=` nicht für exakten Commit-Nachweis auf einem beweglichen `main`; rohe Commit-SHAs können keine Workflow-Dispatch-Refs sein, verwenden Sie daher -`pnpm ci:full-release --sha `, um den angehefteten temporären Branch zu erstellen. +`pnpm ci:full-release --sha `, um den gepinnten temporären Branch zu erstellen. Verwenden Sie `release_profile`, um die Live-/Provider-Breite auszuwählen: -- `minimum`: schnellster release-kritischer OpenAI-/Core-Live- und Docker-Pfad -- `stable`: Minimum plus Stable-Provider-/Backend-Abdeckung für die Release-Freigabe -- `full`: Stable plus breite Advisory-Provider-/Medienabdeckung +- `minimum`: schnellster releasekritischer OpenAI-/Core-Live- und Docker-Pfad +- `stable`: minimum plus stabile Provider-/Backend-Abdeckung für die Release-Freigabe +- `full`: stable plus breite Advisory-Provider-/Media-Abdeckung -`OpenClaw Release Checks` verwendet die vertrauenswürdige Workflow-Ref, um die Ziel- -Ref einmal als `release-package-under-test` aufzulösen, und nutzt dieses Artefakt sowohl in -Docker-Prüfungen des Release-Pfads als auch in Package Acceptance wieder. Dadurch bleiben alle -paketbezogenen Boxen auf denselben Bytes, und wiederholte Paket-Builds werden vermieden. +`OpenClaw Release Checks` verwendet die vertrauenswürdige Workflow-Ref, um die Ziel-Ref +einmal als `release-package-under-test` aufzulösen, und verwendet dieses Artefakt sowohl in +Docker-Checks für den Release-Pfad als auch in Package Acceptance erneut. Dadurch bleiben alle +packagebezogenen Boxen auf denselben Bytes und wiederholte Package-Builds werden vermieden. Der Cross-OS-OpenAI-Install-Smoke verwendet `OPENCLAW_CROSS_OS_OPENAI_MODEL`, wenn die Repo-/Org-Variable gesetzt ist, andernfalls `openai/gpt-5.4`, weil diese Lane -Paketinstallation, Onboarding, Gateway-Start und einen Live-Agent-Turn nachweist, -anstatt das langsamste Standardmodell zu benchmarken. Die breitere Live-Provider- +Package-Installation, Onboarding, Gateway-Start und eine Live-Agent-Runde nachweist, +statt das langsamste Standardmodell zu benchmarken. Die breitere Live-Provider- Matrix bleibt der Ort für modellspezifische Abdeckung. -Verwenden Sie diese Varianten je nach Release-Phase: +Verwenden Sie diese Varianten je nach Release-Stufe: ```bash # Validate an unpublished release candidate branch. @@ -252,41 +363,41 @@ gh workflow run full-release-validation.yml \ -f npm_telegram_provider_mode=mock-openai ``` -Verwenden Sie den vollständigen Umbrella nicht als ersten Rerun nach einem gezielten Fix. Wenn eine Box -fehlschlägt, verwenden Sie für den nächsten Nachweis den fehlgeschlagenen untergeordneten Workflow, Job, -die Docker-Lane, das Paketprofil, den Modell-Provider oder die QA-Lane. Führen Sie den vollständigen Umbrella nur dann erneut aus, -wenn der Fix die gemeinsame Release-Orchestrierung geändert oder frühere All-Box-Nachweise -veraltet gemacht hat. Der finale Prüfer des Umbrellas prüft die aufgezeichneten IDs der untergeordneten Workflow-Läufe erneut, -sodass nach einem erfolgreich erneut ausgeführten untergeordneten Workflow nur der fehlgeschlagene übergeordnete Job -`Verify full validation` erneut ausgeführt werden muss. +Verwenden Sie den vollständigen Umbrella nicht als ersten Rerun nach einem fokussierten Fix. Wenn eine Box +fehlschlägt, verwenden Sie für den nächsten Nachweis den fehlgeschlagenen Kind-Workflow, Job, +die Docker-Lane, das Package-Profil, den Modell-Provider oder die QA-Lane. Führen Sie den vollständigen Umbrella erst dann +erneut aus, wenn der Fix gemeinsame Release-Orchestrierung geändert oder frühere All-Box-Nachweise +veraltet gemacht hat. Der abschließende Verifier des Umbrella prüft die aufgezeichneten Kind-Workflow-Run- +IDs erneut. Nachdem ein Kind-Workflow erfolgreich erneut ausgeführt wurde, führen Sie daher nur den fehlgeschlagenen +übergeordneten Job `Verify full validation` erneut aus. Für begrenzte Wiederherstellung übergeben Sie `rerun_group` an den Umbrella. `all` ist der echte -Release-Candidate-Lauf, `ci` führt nur den normalen CI-Unterlauf aus, `plugin-prerelease` -führt nur den release-spezifischen Plugin-Unterlauf aus, `release-checks` führt jede Release- +Release-Candidate-Lauf, `ci` führt nur das normale CI-Kind aus, `plugin-prerelease` +führt nur das releaseexklusive Plugin-Kind aus, `release-checks` führt jede Release- Box aus, und die engeren Release-Gruppen sind `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` und `npm-telegram`. -Gezielte `npm-telegram`-Reruns erfordern `npm_telegram_package_spec`; full/all-Läufe -mit `release_profile=full` verwenden das Paketartefakt aus release-checks. +Fokussierte `npm-telegram`-Reruns erfordern `npm_telegram_package_spec`; full/all-Läufe +mit `release_profile=full` verwenden das Package-Artefakt der Release-Checks. ### Vitest -Die Vitest-Box ist der manuelle untergeordnete Workflow `CI`. Manuelle CI umgeht -Changed-Scoping absichtlich und erzwingt den normalen Testgraphen für den Release- -Kandidaten: Linux-Node-Shards, gebündelte-Plugin-Shards, Channel-Verträge, Node-22- -Kompatibilität, `check`, `check-additional`, Build-Smoke, Docs-Prüfungen, Python- +Die Vitest-Box ist der manuelle `CI`-Kind-Workflow. Manuelle CI umgeht bewusst +Changed-Scoping und erzwingt den normalen Testgraphen für den Release- +Candidate: Linux-Node-Shards, Bundled-Plugin-Shards, Channel-Contracts, Node-22- +Kompatibilität, `check`, `check-additional`, Build-Smoke, Docs-Checks, Python- Skills, Windows, macOS, Android und Control-UI-i18n. -Verwenden Sie diese Box, um zu beantworten: „Hat der Quellbaum die vollständige normale Testsuite bestanden?“ -Sie ist nicht dasselbe wie Produktvalidierung auf dem Release-Pfad. Zu sichernde Nachweise: +Verwenden Sie diese Box, um zu beantworten: „Hat der Source Tree die vollständige normale Testsuite bestanden?“ +Das ist nicht dasselbe wie Produktvalidierung für den Release-Pfad. Aufzubewahrende Nachweise: -- Zusammenfassung von `Full Release Validation` mit der URL des dispatchten `CI`-Laufs +- `Full Release Validation`-Zusammenfassung mit der URL des dispatchten `CI`-Laufs - grüner `CI`-Lauf auf der exakten Ziel-SHA -- Namen fehlgeschlagener oder langsamer Shards aus den CI-Jobs bei der Untersuchung von Regressionen +- fehlgeschlagene oder langsame Shard-Namen aus den CI-Jobs bei der Untersuchung von Regressionen - Vitest-Timing-Artefakte wie `.artifacts/vitest-shard-timings.json`, wenn ein Lauf Performance-Analyse benötigt -Führen Sie manuelle CI nur dann direkt aus, wenn das Release deterministische normale CI benötigt, aber -nicht die Docker-, QA-Lab-, Live-, Cross-OS- oder Paket-Boxen: +Führen Sie manuelle CI nur dann direkt aus, wenn der Release deterministische normale CI benötigt, aber +nicht die Docker-, QA-Lab-, Live-, Cross-OS- oder Package-Boxen: ```bash gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D @@ -294,19 +405,19 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D ### Docker -Die Docker-Box befindet sich in `OpenClaw Release Checks` über -`openclaw-live-and-e2e-checks-reusable.yml` sowie den Release-Modus- -Workflow `install-smoke`. Sie validiert den Release-Kandidaten über paketierte -Docker-Umgebungen statt nur über Tests auf Quellcodeebene. +Die Docker-Box lebt in `OpenClaw Release Checks` über +`openclaw-live-and-e2e-checks-reusable.yml` plus den Release-Modus- +`install-smoke`-Workflow. Sie validiert den Release-Candidate über paketierte +Docker-Umgebungen statt nur über Tests auf Source-Ebene. Die Release-Docker-Abdeckung umfasst: -- vollständigen Install-Smoke mit aktiviertem langsamem Bun-Global-Install-Smoke +- vollständiger Install-Smoke mit aktiviertem langsamen globalen Bun-Install-Smoke - Vorbereitung/Wiederverwendung des Root-Dockerfile-Smoke-Images nach Ziel-SHA, wobei QR-, Root-/Gateway- und Installer-/Bun-Smoke-Jobs als separate Install-Smoke- Shards laufen - Repository-E2E-Lanes -- Docker-Chunks des Release-Pfads: `core`, `package-update-openai`, +- Docker-Chunks für den Release-Pfad: `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, `plugins-runtime-install-a`, `plugins-runtime-install-b`, @@ -317,46 +428,46 @@ Die Release-Docker-Abdeckung umfasst: - aufgeteilte Lanes für Installation/Deinstallation gebündelter Plugins `bundled-plugin-install-uninstall-0` bis `bundled-plugin-install-uninstall-23` -- Live-/E2E-Provider-Suites und Docker-Live-Modellabdeckung, wenn Release-Prüfungen - Live-Suites enthalten +- Live/E2E-Provider-Suiten und Docker-Live-Modellabdeckung, wenn Release-Checks + Live-Suiten enthalten -Verwenden Sie Docker-Artefakte vor einem Rerun. Der Release-Pfad-Scheduler lädt +Verwenden Sie Docker-Artefakte vor einem Rerun. Der Scheduler für den Release-Pfad lädt `.artifacts/docker-tests/` mit Lane-Logs, `summary.json`, `failures.json`, -Phasen-Timings, Scheduler-Plan-JSON und Rerun-Befehlen hoch. Für gezielte Wiederherstellung -verwenden Sie `docker_lanes=` im wiederverwendbaren Live-/E2E-Workflow, statt +Phasen-Timings, Scheduler-Plan-JSON und Rerun-Befehlen hoch. Für fokussierte Wiederherstellung +verwenden Sie `docker_lanes=` im wiederverwendbaren Live/E2E-Workflow statt alle Release-Chunks erneut auszuführen. Generierte Rerun-Befehle enthalten frühere -`package_artifact_run_id`- und vorbereitete Docker-Image-Eingaben, wenn verfügbar, sodass eine -fehlgeschlagene Lane denselben Tarball und dieselben GHCR-Images wiederverwenden kann. +`package_artifact_run_id` und vorbereitete Docker-Image-Eingaben, wenn verfügbar, sodass eine +fehlgeschlagene Lane denselben Tarball und dieselben GHCR-Images erneut verwenden kann. ### QA Lab Die QA-Lab-Box ist ebenfalls Teil von `OpenClaw Release Checks`. Sie ist das agentische -Verhaltens- und Channel-Level-Release-Gate, getrennt von Vitest- und Docker- -Paketmechanik. +Verhaltens- und Channel-Level-Release-Gate, getrennt von Vitest und Docker- +Package-Mechanik. Die Release-QA-Lab-Abdeckung umfasst: -- Mock-Paritäts-Lane, die die OpenAI-Kandidaten-Lane anhand des agentischen Parity-Packs +- Mock-Parity-Lane, die die OpenAI-Candidate-Lane anhand des agentischen Parity-Packs mit der Opus-4.6-Baseline vergleicht - schnelles Live-Matrix-QA-Profil mit der Umgebung `qa-live-shared` - Live-Telegram-QA-Lane mit Convex-CI-Credential-Leases - `pnpm qa:otel:smoke`, wenn Release-Telemetrie expliziten lokalen Nachweis benötigt -Verwenden Sie diese Box, um zu beantworten: „Verhält sich das Release in QA-Szenarien und -Live-Channel-Flows korrekt?“ Bewahren Sie die Artefakt-URLs für Paritäts-, Matrix- und Telegram- -Lanes auf, wenn Sie das Release freigeben. Vollständige Matrix-Abdeckung bleibt als -manueller sharded QA-Lab-Lauf verfügbar und ist nicht die standardmäßige release-kritische Lane. +Verwenden Sie diese Box, um zu beantworten: „Verhält sich der Release in QA-Szenarien und +Live-Channel-Flows korrekt?“ Bewahren Sie die Artefakt-URLs für Parity-, Matrix- und Telegram- +Lanes auf, wenn Sie den Release freigeben. Vollständige Matrix-Abdeckung bleibt als +manueller, geshardeter QA-Lab-Lauf verfügbar statt als standardmäßige releasekritische Lane. -### Paket +### Package -Die Paket-Box ist das Gate für das installierbare Produkt. Sie wird von -`Package Acceptance` und dem Resolver +Die Package-Box ist das Gate für das installierbare Produkt. Sie wird durch +`Package Acceptance` und den Resolver `scripts/resolve-openclaw-package-candidate.mjs` gestützt. Der Resolver normalisiert einen -Kandidaten in den Tarball `package-under-test`, der von Docker E2E konsumiert wird, validiert -das Paketinventar, zeichnet die Paketversion und SHA-256 auf und hält die -Workflow-Harness-Ref von der Paket-Quell-Ref getrennt. +Candidate in den `package-under-test`-Tarball, der von Docker-E2E verbraucht wird, validiert +das Package-Inventar, zeichnet Package-Version und SHA-256 auf und hält die +Workflow-Harness-Ref von der Package-Source-Ref getrennt. -Unterstützte Kandidatenquellen: +Unterstützte Candidate-Quellen: - `source=npm`: `openclaw@beta`, `openclaw@latest` oder eine exakte OpenClaw-Release- Version @@ -366,41 +477,41 @@ Unterstützte Kandidatenquellen: - `source=artifact`: ein von einem anderen GitHub-Actions-Lauf hochgeladenes `.tgz` wiederverwenden `OpenClaw Release Checks` führt Package Acceptance mit `source=artifact`, dem -vorbereiteten Release-Paketartefakt, `suite_profile=custom`, +vorbereiteten Release-Package-Artefakt, `suite_profile=custom`, `docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`, `published_upgrade_survivor_baselines=all-since-2026.4.23`, `published_upgrade_survivor_scenarios=reported-issues` und `telegram_mode=mock-openai` aus. Package Acceptance hält Migration, Update, Bereinigung veralteter Plugin-Abhängigkeiten, Offline-Plugin-Fixtures, Plugin-Update und Telegram- -Paket-QA gegen denselben aufgelösten Tarball. Die Upgrade-Matrix deckt jede stabile npm-veröffentlichte Baseline von `2026.4.23` bis `latest` ab; verwenden Sie -Package Acceptance mit `source=npm` für einen bereits ausgelieferten Kandidaten oder +Package-QA gegen denselben aufgelösten Tarball. Die Upgrade-Matrix deckt jede stabile npm-veröffentlichte Baseline von `2026.4.23` bis `latest` ab; verwenden Sie +Package Acceptance mit `source=npm` für einen bereits ausgelieferten Candidate oder `source=ref`/`source=artifact` für einen SHA-gestützten lokalen npm-Tarball vor der -Veröffentlichung. Sie ist der GitHub-native -Ersatz für den Großteil der Paket-/Update-Abdeckung, die zuvor Parallels erforderte. -Cross-OS-Release-Prüfungen bleiben für OS-spezifisches Onboarding, -Installer- und Plattformverhalten wichtig, aber Paket-/Update-Produktvalidierung sollte +Veröffentlichung. Es ist der GitHub-native +Ersatz für den Großteil der Package-/Update-Abdeckung, die zuvor Parallels erforderte. +Cross-OS-Release-Checks bleiben für OS-spezifisches Onboarding, +Installer- und Plattformverhalten wichtig, aber Package-/Update-Produktvalidierung sollte Package Acceptance bevorzugen. Die kanonische Checkliste für Update- und Plugin-Validierung ist [Updates und Plugins testen](/de/help/testing-updates-plugins). Verwenden Sie sie, wenn Sie entscheiden, welche lokale, Docker-, Package-Acceptance- oder Release-Check-Lane eine -Plugin-Installation/-Aktualisierung, Doctor-Bereinigung oder veröffentlichte-Paket-Migrationsänderung nachweist. -Erschöpfende veröffentlichte Update-Migration aus jedem stabilen `2026.4.23+`-Paket ist -ein separater manueller Workflow `Update Migration`, nicht Teil von Full Release CI. +Plugin-Installation/ein Plugin-Update, Doctor-Bereinigung oder eine Published-Package-Migrationsänderung nachweist. +Vollständige veröffentlichte Update-Migration aus jedem stabilen `2026.4.23+`-Package ist +ein separater manueller `Update Migration`-Workflow, nicht Teil der vollständigen Release-CI. -Legacy-Nachsicht in Package Acceptance ist absichtlich zeitlich begrenzt. Pakete bis einschließlich +Legacy-Package-Acceptance-Toleranz ist absichtlich zeitlich begrenzt. Packages bis `2026.4.25` dürfen den Kompatibilitätspfad für Metadatenlücken verwenden, die bereits auf npm veröffentlicht wurden: private QA-Inventareinträge, die im Tarball fehlen, fehlendes `gateway install --wrapper`, fehlende Patch-Dateien im aus dem Tarball abgeleiteten Git- Fixture, fehlende persistierte `update.channel`, Legacy-Speicherorte für Plugin-Install-Records, -fehlende Persistenz von Marketplace-Install-Records und Konfigurationsmetadaten- -Migration während `plugins update`. Das veröffentlichte Paket `2026.4.26` darf für lokale -Build-Metadaten-Stempeldateien warnen, die bereits ausgeliefert wurden. Spätere Pakete -müssen die modernen Paketverträge erfüllen; dieselben Lücken lassen die Release- +fehlende Persistenz von Marketplace-Install-Records und Config-Metadatenmigration während +`plugins update`. Das veröffentlichte Package `2026.4.26` darf für lokale Build-Metadaten- +Stamp-Dateien warnen, die bereits ausgeliefert wurden. Spätere Packages müssen +die modernen Package-Verträge erfüllen; dieselben Lücken lassen die Release- Validierung fehlschlagen. Verwenden Sie breitere Package-Acceptance-Profile, wenn die Release-Frage ein -tatsächlich installierbares Paket betrifft: +tatsächlich installierbares Package betrifft: ```bash gh workflow run package-acceptance.yml \ @@ -412,18 +523,18 @@ gh workflow run package-acceptance.yml \ -f published_upgrade_survivor_baseline=openclaw@2026.4.26 ``` -Gängige Paketprofile: +Gängige Package-Profile: - `smoke`: schnelle Lanes für Paketinstallation/Kanal/Agent, Gateway-Netzwerk und - Neuladen der Konfiguration + erneutes Laden der Konfiguration - `package`: Installations-/Update-/Plugin-Paketverträge ohne Live-ClawHub; dies ist der Standard für Release-Checks - `product`: `package` plus MCP-Kanäle, Cron-/Subagent-Bereinigung, OpenAI-Websuche und OpenWebUI - `full`: Docker-Release-Pfad-Abschnitte mit OpenWebUI -- `custom`: exakte `docker_lanes`-Liste für fokussierte Wiederholungsläufe +- `custom`: exakte `docker_lanes`-Liste für fokussierte Wiederholungen -Aktivieren Sie für den Telegram-Nachweis eines Paketkandidaten `telegram_mode=mock-openai` oder +Aktivieren Sie für den Telegram-Nachweis mit Paketkandidat `telegram_mode=mock-openai` oder `telegram_mode=live-frontier` in Package Acceptance. Der Workflow übergibt den aufgelösten `package-under-test`-Tarball an die Telegram-Lane; der eigenständige Telegram-Workflow akzeptiert weiterhin eine veröffentlichte npm-Spezifikation für Prüfungen nach der Veröffentlichung. @@ -433,14 +544,14 @@ Telegram-Workflow akzeptiert weiterhin eine veröffentlichte npm-Spezifikation f `OpenClaw Release Publish` ist der normale mutierende Einstiegspunkt für Veröffentlichungen. Er orchestriert die Trusted-Publisher-Workflows in der Reihenfolge, die das Release benötigt: -1. Checken Sie das Release-Tag aus und ermitteln Sie dessen Commit-SHA. -2. Verifizieren Sie, dass das Tag von `main` oder `release/*` erreichbar ist. -3. Führen Sie `pnpm plugins:sync:check` aus. -4. Lösen Sie `Plugin NPM Release` mit `publish_scope=all-publishable` und - `ref=` aus. -5. Lösen Sie `Plugin ClawHub Release` mit demselben Scope und derselben SHA aus. -6. Lösen Sie `OpenClaw NPM Release` mit dem Release-Tag, dem npm-Dist-Tag und - der gespeicherten `preflight_run_id` aus. +1. Release-Tag auschecken und dessen Commit-SHA auflösen. +2. Prüfen, ob der Tag von `main` oder `release/*` erreichbar ist. +3. `pnpm plugins:sync:check` ausführen. +4. `Plugin NPM Release` mit `publish_scope=all-publishable` und + `ref=` auslösen. +5. `Plugin ClawHub Release` mit demselben Scope und derselben SHA auslösen. +6. `OpenClaw NPM Release` mit Release-Tag, npm-Dist-Tag und + gespeichertem `preflight_run_id` auslösen. Beispiel für eine Beta-Veröffentlichung: @@ -462,7 +573,7 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -Stabile Promotion direkt nach `latest` ist explizit: +Stabile Promotion direkt zu `latest` ist explizit: ```bash gh workflow run openclaw-release-publish.yml \ @@ -472,91 +583,91 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=latest ``` -Verwenden Sie die untergeordneten Workflows `Plugin NPM Release` und `Plugin ClawHub Release` -nur für fokussierte Reparatur- oder erneute Veröffentlichungsarbeiten. Übergeben Sie für eine ausgewählte Plugin-Reparatur +Verwenden Sie die niedrigeren Workflows `Plugin NPM Release` und `Plugin ClawHub Release` +nur für fokussierte Reparatur- oder erneute Veröffentlichungsarbeiten. Für eine ausgewählte Plugin-Reparatur übergeben Sie `plugin_publish_scope=selected` und `plugins=@openclaw/name` an `OpenClaw Release Publish`, oder lösen Sie den untergeordneten Workflow direkt aus, wenn das OpenClaw-Paket nicht veröffentlicht werden darf. ## NPM-Workflow-Eingaben -`OpenClaw NPM Release` akzeptiert diese vom Operator gesteuerten Eingaben: +`OpenClaw NPM Release` akzeptiert diese operatorgesteuerten Eingaben: -- `tag`: erforderliches Release-Tag wie `v2026.4.2`, `v2026.4.2-1` oder - `v2026.4.2-beta.1`; wenn `preflight_only=true` gilt, kann es auch die aktuelle - vollständige 40-stellige Commit-SHA des Workflow-Branch für einen reinen Validierungs-Preflight sein +- `tag`: erforderlicher Release-Tag wie `v2026.4.2`, `v2026.4.2-1` oder + `v2026.4.2-beta.1`; wenn `preflight_only=true` ist, darf es auch die aktuelle + vollständige 40-stellige Commit-SHA des Workflow-Branches für einen rein validierenden Preflight sein - `preflight_only`: `true` nur für Validierung/Build/Paket, `false` für den echten Veröffentlichungspfad -- `preflight_run_id`: auf dem echten Veröffentlichungspfad erforderlich, damit der Workflow +- `preflight_run_id`: im echten Veröffentlichungspfad erforderlich, damit der Workflow den vorbereiteten Tarball aus dem erfolgreichen Preflight-Lauf wiederverwendet -- `npm_dist_tag`: npm-Ziel-Tag für den Veröffentlichungspfad; Standard ist `beta` +- `npm_dist_tag`: npm-Ziel-Tag für den Veröffentlichungspfad; standardmäßig `beta` -`OpenClaw Release Publish` akzeptiert diese vom Operator gesteuerten Eingaben: +`OpenClaw Release Publish` akzeptiert diese operatorgesteuerten Eingaben: -- `tag`: erforderliches Release-Tag; muss bereits existieren +- `tag`: erforderlicher Release-Tag; muss bereits existieren - `preflight_run_id`: erfolgreiche `OpenClaw NPM Release`-Preflight-Lauf-ID; - erforderlich, wenn `publish_openclaw_npm=true` gilt + erforderlich, wenn `publish_openclaw_npm=true` ist - `npm_dist_tag`: npm-Ziel-Tag für das OpenClaw-Paket -- `plugin_publish_scope`: Standard ist `all-publishable`; verwenden Sie `selected` nur +- `plugin_publish_scope`: standardmäßig `all-publishable`; verwenden Sie `selected` nur für fokussierte Reparaturarbeiten -- `plugins`: durch Kommas getrennte `@openclaw/*`-Paketnamen, wenn - `plugin_publish_scope=selected` gilt -- `publish_openclaw_npm`: Standard ist `true`; setzen Sie es nur dann auf `false`, - wenn der Workflow als reiner Plugin-Reparatur-Orchestrator verwendet wird +- `plugins`: kommagetrennte `@openclaw/*`-Paketnamen, wenn + `plugin_publish_scope=selected` +- `publish_openclaw_npm`: standardmäßig `true`; setzen Sie dies nur auf `false`, wenn Sie den + Workflow als reinen Plugin-Reparatur-Orchestrator verwenden -`OpenClaw Release Checks` akzeptiert diese vom Operator gesteuerten Eingaben: +`OpenClaw Release Checks` akzeptiert diese operatorgesteuerten Eingaben: -- `ref`: Branch, Tag oder vollständige Commit-SHA, der bzw. die validiert werden soll. Prüfungen mit Secrets +- `ref`: Branch, Tag oder vollständige Commit-SHA, die validiert werden soll. Prüfungen mit Secrets erfordern, dass der aufgelöste Commit von einem OpenClaw-Branch oder Release-Tag erreichbar ist. Regeln: -- Stabile Tags und Korrektur-Tags dürfen entweder nach `beta` oder `latest` veröffentlichen +- Stabile und Korrektur-Tags dürfen entweder nach `beta` oder `latest` veröffentlichen - Beta-Prerelease-Tags dürfen nur nach `beta` veröffentlichen - Für `OpenClaw NPM Release` ist die Eingabe einer vollständigen Commit-SHA nur erlaubt, wenn - `preflight_only=true` gilt + `preflight_only=true` ist - `OpenClaw Release Checks` und `Full Release Validation` sind immer - ausschließlich Validierungen -- Der echte Veröffentlichungspfad muss denselben `npm_dist_tag` verwenden, der während des Preflight verwendet wurde; - der Workflow verifiziert diese Metadaten, bevor die Veröffentlichung fortgesetzt wird + nur zur Validierung +- Der echte Veröffentlichungspfad muss denselben `npm_dist_tag` verwenden, der während des Preflights verwendet wurde; + der Workflow prüft diese Metadaten, bevor die Veröffentlichung fortgesetzt wird -## Stabile npm-Release-Sequenz +## Stabile npm-Release-Abfolge -Wenn Sie ein stabiles npm-Release erstellen: +Beim Schneiden eines stabilen npm-Releases: 1. Führen Sie `OpenClaw NPM Release` mit `preflight_only=true` aus - - Bevor ein Tag existiert, können Sie die aktuelle vollständige Commit-SHA des Workflow-Branch - für einen reinen Validierungs-Trockenlauf des Preflight-Workflows verwenden -2. Wählen Sie `npm_dist_tag=beta` für den normalen Beta-zuerst-Ablauf oder nur dann `latest`, + - Bevor ein Tag existiert, können Sie die aktuelle vollständige Commit-SHA des Workflow-Branches + für einen rein validierenden Trockenlauf des Preflight-Workflows verwenden +2. Wählen Sie `npm_dist_tag=beta` für den normalen Beta-zuerst-Ablauf oder `latest` nur, wenn Sie bewusst eine direkte stabile Veröffentlichung wünschen 3. Führen Sie `Full Release Validation` auf dem Release-Branch, Release-Tag oder der vollständigen Commit-SHA aus, wenn Sie normale CI plus Live-Prompt-Cache, Docker, QA Lab, Matrix und Telegram-Abdeckung aus einem manuellen Workflow wünschen 4. Wenn Sie bewusst nur den deterministischen normalen Testgraphen benötigen, führen Sie stattdessen den - manuellen `CI`-Workflow auf der Release-Ref aus + manuellen `CI`-Workflow auf der Release-Referenz aus 5. Speichern Sie die erfolgreiche `preflight_run_id` 6. Führen Sie `OpenClaw Release Publish` mit demselben `tag`, demselben `npm_dist_tag` - und der gespeicherten `preflight_run_id` aus; er veröffentlicht externalisierte Plugins bei npm - und ClawHub, bevor das OpenClaw-npm-Paket promotet wird + und der gespeicherten `preflight_run_id` aus; dies veröffentlicht externalisierte Plugins in npm + und ClawHub, bevor das OpenClaw-npm-Paket promoted wird 7. Wenn das Release auf `beta` gelandet ist, verwenden Sie den privaten - `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`- - Workflow, um diese stabile Version von `beta` nach `latest` zu promoten + `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`-Workflow, + um diese stabile Version von `beta` nach `latest` zu promoten 8. Wenn das Release bewusst direkt nach `latest` veröffentlicht wurde und `beta` sofort demselben stabilen Build folgen soll, verwenden Sie denselben privaten - Workflow, um beide Dist-Tags auf die stabile Version zu setzen, oder lassen Sie - die geplante Selbstheilungs-Synchronisierung `beta` später verschieben + Workflow, um beide Dist-Tags auf die stabile Version zu zeigen, oder lassen Sie dessen geplante + Self-Healing-Synchronisierung `beta` später verschieben -Die Dist-Tag-Mutation liegt aus Sicherheitsgründen im privaten Repository, weil sie weiterhin -`NPM_TOKEN` erfordert, während das öffentliche Repository ausschließlich OIDC-Veröffentlichung verwendet. +Die Dist-Tag-Mutation liegt aus Sicherheitsgründen im privaten Repo, weil sie weiterhin +`NPM_TOKEN` erfordert, während das öffentliche Repo nur OIDC-Veröffentlichung beibehält. -Dadurch bleiben sowohl der direkte Veröffentlichungspfad als auch der Beta-zuerst-Promotion-Pfad +Dadurch bleiben der direkte Veröffentlichungspfad und der Beta-zuerst-Promotion-Pfad beide dokumentiert und für Operatoren sichtbar. -Wenn ein Maintainer auf lokale npm-Authentifizierung zurückgreifen muss, führen Sie alle 1Password- -CLI-Befehle (`op`) nur in einer dedizierten tmux-Sitzung aus. Rufen Sie `op` nicht -direkt aus der Haupt-Agent-Shell auf; die Ausführung in tmux macht Prompts, -Warnungen und OTP-Verarbeitung beobachtbar und verhindert wiederholte Host-Warnungen. +Wenn ein Maintainer auf lokale npm-Authentifizierung zurückfallen muss, führen Sie alle 1Password- +CLI-Befehle (`op`) nur innerhalb einer dedizierten tmux-Sitzung aus. Rufen Sie `op` nicht +direkt aus der Haupt-Agent-Shell auf; wenn es in tmux bleibt, sind Prompts, +Warnungen und OTP-Handhabung beobachtbar, und wiederholte Host-Warnungen werden verhindert. ## Öffentliche Referenzen @@ -572,7 +683,7 @@ Warnungen und OTP-Verarbeitung beobachtbar und verhindert wiederholte Host-Warnu Maintainer verwenden die privaten Release-Dokumente in [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) -für das tatsächliche Runbook. +für das eigentliche Runbook. ## Verwandt diff --git a/docs/de/security/network-proxy.md b/docs/de/security/network-proxy.md index a245b4c38..0903475c6 100644 --- a/docs/de/security/network-proxy.md +++ b/docs/de/security/network-proxy.md @@ -1,40 +1,40 @@ --- read_when: - - Sie möchten mehrschichtigen Schutz gegen SSRF- und DNS-Rebinding-Angriffe - - Konfigurieren eines externen Forward-Proxys für OpenClaw-Laufzeitverkehr -summary: So leiten Sie den HTTP- und WebSocket-Datenverkehr der OpenClaw-Laufzeit über einen vom Betreiber verwalteten Filter-Proxy + - Sie möchten Defense-in-Depth gegen SSRF- und DNS-Rebinding-Angriffe + - Konfigurieren eines externen Forward-Proxys für OpenClaw-Laufzeitdatenverkehr +summary: So leiten Sie den HTTP- und WebSocket-Verkehr der OpenClaw-Laufzeitumgebung über einen vom Betreiber verwalteten Filter-Proxy weiter title: Netzwerk-Proxy x-i18n: - generated_at: "2026-05-04T02:25:34Z" + generated_at: "2026-05-04T06:43:57Z" model: gpt-5.5 provider: openai - source_hash: cd5594324e8c6b7da51d903e98fda0feacb8970e0b15d980f7a249d6641461c9 + source_hash: fc7140c5ced0e7454a6f85d1ea8f3256bbd28cc0cb42eeafe8e5e6439b90e3f0 source_path: security/network-proxy.md workflow: 16 --- -# Netzwerk-Proxy +# Netzwerkproxy -OpenClaw kann Runtime-HTTP- und WebSocket-Datenverkehr über einen von Betreibern verwalteten Forward-Proxy leiten. Dies ist eine optionale mehrschichtige Verteidigung für Bereitstellungen, die zentrale Egress-Kontrolle, stärkeren SSRF-Schutz und bessere Netzwerk-Auditierbarkeit wünschen. +OpenClaw kann HTTP- und WebSocket-Traffic zur Laufzeit über einen vom Betreiber verwalteten Forward Proxy leiten. Dies ist eine optionale Defense-in-Depth-Maßnahme für Deployments, die zentrale Egress-Kontrolle, stärkeren SSRF-Schutz und bessere Netzwerk-Auditierbarkeit wünschen. OpenClaw liefert, lädt, startet, konfiguriert oder zertifiziert keinen Proxy. Sie betreiben die Proxy-Technologie, die zu Ihrer Umgebung passt, und OpenClaw leitet normale prozesslokale HTTP- und WebSocket-Clients darüber. ## Warum einen Proxy verwenden? -Ein Proxy gibt Betreibern einen zentralen Netzwerk-Kontrollpunkt für ausgehenden HTTP- und WebSocket-Datenverkehr. Das kann auch außerhalb der SSRF-Härtung nützlich sein: +Ein Proxy gibt Betreibern einen zentralen Netzwerkkontrollpunkt für ausgehenden HTTP- und WebSocket-Traffic. Das kann auch außerhalb von SSRF-Härtung nützlich sein: -- Zentrale Richtlinie: Pflegen Sie eine Egress-Richtlinie, statt sich darauf zu verlassen, dass jede HTTP-Aufrufstelle der Anwendung die Netzwerkregeln korrekt umsetzt. -- Prüfungen zum Verbindungszeitpunkt: Bewerten Sie das Ziel nach der DNS-Auflösung und unmittelbar bevor der Proxy die Upstream-Verbindung öffnet. -- Schutz vor DNS-Rebinding: Verringern Sie die Lücke zwischen einer DNS-Prüfung auf Anwendungsebene und der tatsächlichen ausgehenden Verbindung. -- Breitere JavaScript-Abdeckung: Leiten Sie gewöhnliche `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch und ähnliche Clients über denselben Pfad. -- Auditierbarkeit: Protokollieren Sie erlaubte und verweigerte Ziele an der Egress-Grenze. -- Betriebliche Kontrolle: Erzwingen Sie Zielregeln, Netzwerksegmentierung, Ratenbegrenzungen oder ausgehende Allowlists, ohne OpenClaw neu zu bauen. +- Zentrale Richtlinie: pflegen Sie eine Egress-Richtlinie, statt sich darauf zu verlassen, dass jede HTTP-Aufrufstelle der Anwendung die Netzwerkregeln korrekt umsetzt. +- Prüfungen zur Verbindungszeit: bewerten Sie das Ziel nach der DNS-Auflösung und unmittelbar bevor der Proxy die Upstream-Verbindung öffnet. +- DNS-Rebinding-Abwehr: verringern Sie die Lücke zwischen einer DNS-Prüfung auf Anwendungsebene und der tatsächlichen ausgehenden Verbindung. +- Breitere JavaScript-Abdeckung: leiten Sie gewöhnliche Clients wie `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch und ähnliche über denselben Pfad. +- Auditierbarkeit: protokollieren Sie erlaubte und abgelehnte Ziele an der Egress-Grenze. +- Betriebliche Kontrolle: setzen Sie Zielregeln, Netzwerksegmentierung, Rate Limits oder ausgehende Allowlists durch, ohne OpenClaw neu zu bauen. -Proxy-Routing ist eine Guardrail auf Prozessebene für normalen HTTP- und WebSocket-Egress. Es gibt Betreibern einen fail-closed Pfad, um unterstützte JavaScript-HTTP-Clients über ihren eigenen filternden Proxy zu leiten, ist aber keine Netzwerk-Sandbox auf Betriebssystemebene und bedeutet nicht, dass OpenClaw die Zielrichtlinie des Proxy zertifiziert. +Proxy-Routing ist eine Schutzplanke auf Prozessebene für normalen HTTP- und WebSocket-Egress. Es gibt Betreibern einen Fail-Closed-Pfad, um unterstützte JavaScript-HTTP-Clients über ihren eigenen filternden Proxy zu leiten, ist aber keine Netzwerk-Sandbox auf Betriebssystemebene und sorgt nicht dafür, dass OpenClaw die Zielrichtlinie des Proxys zertifiziert. -## Wie OpenClaw Datenverkehr weiterleitet +## Wie OpenClaw Traffic leitet -Wenn `proxy.enabled=true` gesetzt und eine Proxy-URL konfiguriert ist, leiten geschützte Runtime-Prozesse wie `openclaw gateway run`, `openclaw node run` und `openclaw agent --local` normalen HTTP- und WebSocket-Egress über den konfigurierten Proxy: +Wenn `proxy.enabled=true` gesetzt und eine Proxy-URL konfiguriert ist, leiten geschützte Laufzeitprozesse wie `openclaw gateway run`, `openclaw node run` und `openclaw agent --local` normalen HTTP- und WebSocket-Egress über den konfigurierten Proxy: ```text OpenClaw process @@ -43,27 +43,27 @@ OpenClaw process WebSocket clients -> operator-managed filtering proxy -> public internet ``` -Der öffentliche Vertrag ist das Routing-Verhalten, nicht die internen Node-Hooks, mit denen es implementiert wird. OpenClaw Gateway-Control-Plane-WebSocket-Clients verwenden einen schmalen direkten Pfad für local loopback-Gateway-RPC-Datenverkehr, wenn die Gateway-URL `localhost` oder eine literale Loopback-IP wie `127.0.0.1` oder `[::1]` verwendet. Dieser Control-Plane-Pfad muss Loopback-Gateways erreichen können, selbst wenn der Betreiber-Proxy Loopback-Ziele blockiert. Normale Runtime-HTTP- und WebSocket-Anfragen verwenden weiterhin den konfigurierten Proxy. +Der öffentliche Vertrag ist das Routing-Verhalten, nicht die internen Node-Hooks, mit denen es implementiert wird. OpenClaw Gateway Control-Plane-WebSocket-Clients verwenden einen schmalen direkten Pfad für local loopback Gateway-RPC-Traffic, wenn die Gateway-URL `localhost` oder eine wörtliche Loopback-IP wie `127.0.0.1` oder `[::1]` verwendet. Dieser Control-Plane-Pfad muss Loopback-Gateways erreichen können, selbst wenn der Betreiber-Proxy Loopback-Ziele blockiert. Normale HTTP- und WebSocket-Anfragen zur Laufzeit verwenden weiterhin den konfigurierten Proxy. Intern verwendet OpenClaw zwei Routing-Hooks auf Prozessebene für diese Funktion: -- Undici-Dispatcher-Routing deckt `fetch`, undici-basierte Clients und Transports ab, die ihren eigenen undici-Dispatcher bereitstellen. -- `global-agent`-Routing deckt Aufrufer von Node-Core `node:http` und `node:https` ab, einschließlich vieler Bibliotheken, die auf `http.request`, `https.request`, `http.get` und `https.get` aufsetzen. Der verwaltete Proxy-Modus erzwingt diesen globalen Agent, damit explizite Node-HTTP-Agents den Betreiber-Proxy nicht versehentlich umgehen. +- Undici-Dispatcher-Routing deckt `fetch`, Undici-basierte Clients und Transports ab, die ihren eigenen Undici-Dispatcher bereitstellen. +- `global-agent`-Routing deckt Aufrufer von Node-Core `node:http` und `node:https` ab, einschließlich vieler Bibliotheken, die auf `http.request`, `https.request`, `http.get` und `https.get` aufbauen. Der verwaltete Proxy-Modus erzwingt diesen globalen Agent, damit explizite Node-HTTP-Agents den Betreiber-Proxy nicht versehentlich umgehen. -Einige Plugins besitzen eigene Transports, die explizite Proxy-Verdrahtung benötigen, selbst wenn Routing auf Prozessebene vorhanden ist. Beispielsweise verwendet der Bot-API-Transport von Telegram seinen eigenen HTTP/1-undici-Dispatcher und berücksichtigt daher Prozess-Proxy-Umgebungsvariablen plus den verwalteten Fallback `OPENCLAW_PROXY_URL` in diesem ownerspezifischen Transportpfad. +Einige Plugins besitzen eigene Transports, die explizite Proxy-Verdrahtung benötigen, auch wenn Routing auf Prozessebene vorhanden ist. Beispielsweise verwendet der Bot-API-Transport von Telegram seinen eigenen HTTP/1-Undici-Dispatcher und berücksichtigt daher Prozess-Proxy-Umgebungsvariablen plus den verwalteten `OPENCLAW_PROXY_URL`-Fallback in diesem owner-spezifischen Transportpfad. -Die Proxy-URL selbst muss `http://` verwenden. HTTPS-Ziele werden über den Proxy weiterhin mit HTTP `CONNECT` unterstützt; dies bedeutet nur, dass OpenClaw einen einfachen HTTP-Forward-Proxy-Listener wie `http://127.0.0.1:3128` erwartet. +Die Proxy-URL selbst muss `http://` verwenden. HTTPS-Ziele werden weiterhin über den Proxy mit HTTP `CONNECT` unterstützt; dies bedeutet nur, dass OpenClaw einen einfachen HTTP-Forward-Proxy-Listener wie `http://127.0.0.1:3128` erwartet. -Während der Proxy aktiv ist, leert OpenClaw `no_proxy`, `NO_PROXY` und `GLOBAL_AGENT_NO_PROXY`. Diese Umgehungslisten sind zielbasiert, sodass `localhost` oder `127.0.0.1` dort riskante SSRF-Ziele den filternden Proxy umgehen lassen würden. +Während der Proxy aktiv ist, löscht OpenClaw `no_proxy`, `NO_PROXY` und `GLOBAL_AGENT_NO_PROXY`. Diese Bypass-Listen sind zielbasiert, sodass `localhost` oder `127.0.0.1` dort dazu führen würde, dass SSRF-Ziele mit hohem Risiko den filternden Proxy umgehen. Beim Herunterfahren stellt OpenClaw die vorherige Proxy-Umgebung wieder her und setzt den zwischengespeicherten Prozess-Routing-Zustand zurück. ## Verwandte Proxy-Begriffe -- `proxy.enabled` / `proxy.proxyUrl`: ausgehendes Forward-Proxy-Routing für OpenClaw-Runtime-Egress. Diese Seite dokumentiert diese Funktion. +- `proxy.enabled` / `proxy.proxyUrl`: ausgehendes Forward-Proxy-Routing für OpenClaw-Laufzeit-Egress. Diese Seite dokumentiert diese Funktion. - `gateway.auth.mode: "trusted-proxy"`: eingehende identitätsbewusste Reverse-Proxy-Authentifizierung für Gateway-Zugriff. Siehe [Trusted-Proxy-Authentifizierung](/de/gateway/trusted-proxy-auth). -- `openclaw proxy`: lokaler Debug-Proxy und Capture-Inspector für Entwicklung und Support. Siehe [openclaw proxy](/de/cli/proxy). -- Kanal- oder Provider-spezifische Proxy-Einstellungen: ownerspezifische Overrides für einen bestimmten Transport. Bevorzugen Sie den verwalteten Netzwerk-Proxy, wenn das Ziel zentrale Egress-Kontrolle über die Runtime hinweg ist. +- `openclaw proxy`: lokaler Debug-Proxy und Erfassungsinspektor für Entwicklung und Support. Siehe [openclaw proxy](/de/cli/proxy). +- Channel- oder Provider-spezifische Proxy-Einstellungen: owner-spezifische Overrides für einen bestimmten Transport. Bevorzugen Sie den verwalteten Netzwerkproxy, wenn das Ziel zentrale Egress-Kontrolle über die Laufzeit hinweg ist. ## Konfiguration @@ -92,51 +92,51 @@ openclaw gateway install --force openclaw gateway start ``` -Der Umgebungs-Fallback eignet sich am besten für Vordergrundläufe. Wenn Sie ihn mit einem installierten Dienst verwenden, legen Sie `OPENCLAW_PROXY_URL` in der dauerhaften Umgebung des Dienstes ab, etwa in `$OPENCLAW_STATE_DIR/.env` oder `~/.openclaw/.env`, und installieren Sie den Dienst dann neu, damit launchd, systemd oder Scheduled Tasks das Gateway mit diesem Wert startet. +Der Umgebungs-Fallback eignet sich am besten für Vordergrundausführungen. Wenn Sie ihn mit einem installierten Dienst verwenden, legen Sie `OPENCLAW_PROXY_URL` in die dauerhafte Dienstumgebung, etwa `$OPENCLAW_STATE_DIR/.env` oder `~/.openclaw/.env`, und installieren Sie den Dienst anschließend neu, damit launchd, systemd oder Scheduled Tasks das Gateway mit diesem Wert starten. -Für `openclaw --container ...`-Befehle leitet OpenClaw `OPENCLAW_PROXY_URL` an die containerbezogene Child-CLI weiter, wenn sie gesetzt ist. Die URL muss aus dem Container heraus erreichbar sein; `127.0.0.1` verweist auf den Container selbst, nicht auf den Host. OpenClaw weist Loopback-Proxy-URLs für containerbezogene Befehle zurück, es sei denn, Sie überschreiben diese Sicherheitsprüfung ausdrücklich. +Für `openclaw --container ...`-Befehle leitet OpenClaw `OPENCLAW_PROXY_URL` an die containerbezogene untergeordnete CLI weiter, wenn sie gesetzt ist. Die URL muss aus dem Container heraus erreichbar sein; `127.0.0.1` verweist auf den Container selbst, nicht auf den Host. OpenClaw lehnt Loopback-Proxy-URLs für containerbezogene Befehle ab, sofern Sie diese Sicherheitsprüfung nicht ausdrücklich außer Kraft setzen. ## Proxy-Anforderungen -Die Proxy-Richtlinie ist die Sicherheitsgrenze. OpenClaw kann nicht überprüfen, ob der Proxy die richtigen Ziele blockiert. +Die Proxy-Richtlinie ist die Sicherheitsgrenze. OpenClaw kann nicht verifizieren, dass der Proxy die richtigen Ziele blockiert. Konfigurieren Sie den Proxy so, dass er: -- Nur an Loopback oder eine private vertrauenswürdige Schnittstelle bindet. -- Den Zugriff so einschränkt, dass nur der OpenClaw-Prozess, Host, Container oder das Dienstkonto ihn verwenden kann. +- nur an Loopback oder eine private vertrauenswürdige Schnittstelle bindet. +- den Zugriff so beschränkt, dass nur der OpenClaw-Prozess, Host, Container oder das Dienstkonto ihn verwenden kann. - Ziele selbst auflöst und Ziel-IPs nach der DNS-Auflösung blockiert. -- Richtlinien zum Verbindungszeitpunkt sowohl für einfache HTTP-Anfragen als auch für HTTPS-`CONNECT`-Tunnel anwendet. -- Zielbasierte Umgehungen für Loopback-, private, Link-Local-, Metadata-, Multicast-, reservierte oder Dokumentationsbereiche ablehnt. +- Richtlinien zur Verbindungszeit sowohl für einfache HTTP-Anfragen als auch für HTTPS-`CONNECT`-Tunnel anwendet. +- zielbasierte Bypässe für Loopback-, private, link-lokale, Metadata-, Multicast-, reservierte oder Dokumentationsbereiche ablehnt. - Hostname-Allowlists vermeidet, sofern Sie dem DNS-Auflösungspfad nicht vollständig vertrauen. -- Ziel, Entscheidung, Status und Grund protokolliert, ohne Request-Bodies, Autorisierungs-Header, Cookies oder andere Secrets zu protokollieren. -- Die Proxy-Richtlinie unter Versionskontrolle hält und Änderungen wie sicherheitssensitive Konfiguration prüft. +- Ziel, Entscheidung, Status und Grund protokolliert, ohne Request-Bodys, Autorisierungs-Header, Cookies oder andere Geheimnisse zu protokollieren. +- die Proxy-Richtlinie unter Versionskontrolle hält und Änderungen wie sicherheitssensitive Konfiguration prüft. ## Empfohlene blockierte Ziele -Verwenden Sie diese Denylist als Ausgangspunkt für jeden Forward-Proxy, jede Firewall oder jede Egress-Richtlinie. +Verwenden Sie diese Denylist als Ausgangspunkt für jeden Forward Proxy, jede Firewall oder jede Egress-Richtlinie. -Die Klassifizierungslogik auf OpenClaw-Anwendungsebene befindet sich in `src/infra/net/ssrf.ts` und `src/shared/net/ip.ts`. Die relevanten Parity-Hooks sind `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` und die eingebettete IPv4-Sentinel-Behandlung für NAT64, 6to4, Teredo, ISATAP und IPv4-mapped Formen. Diese Dateien sind nützliche Referenzen bei der Pflege einer externen Proxy-Richtlinie, aber OpenClaw exportiert oder erzwingt diese Regeln nicht automatisch in Ihrem Proxy. +Die Klassifizierungslogik auf OpenClaw-Anwendungsebene befindet sich in `src/infra/net/ssrf.ts` und `src/shared/net/ip.ts`. Die relevanten Paritäts-Hooks sind `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` und die eingebettete IPv4-Sentinel-Behandlung für NAT64, 6to4, Teredo, ISATAP und IPv4-mapped-Formen. Diese Dateien sind nützliche Referenzen, wenn Sie eine externe Proxy-Richtlinie pflegen, aber OpenClaw exportiert oder erzwingt diese Regeln nicht automatisch in Ihrem Proxy. -| Bereich oder Host | Warum blockieren | -| ------------------------------------------------------------------------------------ | --------------------------------------------------- | -| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4-Loopback | -| `::1/128` | IPv6-Loopback | -| `0.0.0.0/8`, `::/128` | Nicht spezifizierte und This-Network-Adressen | -| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Private RFC1918-Netzwerke | -| `169.254.0.0/16`, `fe80::/10` | Link-Local-Adressen und gängige Cloud-Metadata-Pfade | -| `169.254.169.254`, `metadata.google.internal` | Cloud-Metadata-Dienste | -| `100.64.0.0/10` | Gemeinsamer Adressraum für Carrier-Grade-NAT | -| `198.18.0.0/15`, `2001:2::/48` | Benchmarking-Bereiche | -| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Special-Use- und Dokumentationsbereiche | -| `224.0.0.0/4`, `ff00::/8` | Multicast | -| `240.0.0.0/4` | Reserviertes IPv4 | -| `fc00::/7`, `fec0::/10` | Lokale/private IPv6-Bereiche | -| `100::/64`, `2001:20::/28` | IPv6-Discard- und ORCHIDv2-Bereiche | -| `64:ff9b::/96`, `64:ff9b:1::/48` | NAT64-Präfixe mit eingebettetem IPv4 | -| `2002::/16`, `2001::/32` | 6to4 und Teredo mit eingebettetem IPv4 | -| `::/96`, `::ffff:0:0/96` | IPv4-kompatibles und IPv4-mapped IPv6 | +| Bereich oder Host | Warum blockieren | +| ------------------------------------------------------------------------------------ | ---------------------------------------------------- | +| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4-Loopback | +| `::1/128` | IPv6-Loopback | +| `0.0.0.0/8`, `::/128` | Nicht spezifizierte und This-Network-Adressen | +| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Private Netzwerke nach RFC1918 | +| `169.254.0.0/16`, `fe80::/10` | Link-lokale Adressen und gängige Cloud-Metadata-Pfade | +| `169.254.169.254`, `metadata.google.internal` | Cloud-Metadata-Dienste | +| `100.64.0.0/10` | Gemeinsamer Adressraum für Carrier-grade NAT | +| `198.18.0.0/15`, `2001:2::/48` | Benchmarking-Bereiche | +| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Special-Use- und Dokumentationsbereiche | +| `224.0.0.0/4`, `ff00::/8` | Multicast | +| `240.0.0.0/4` | Reserviertes IPv4 | +| `fc00::/7`, `fec0::/10` | Lokale/private IPv6-Bereiche | +| `100::/64`, `2001:20::/28` | IPv6-Discard- und ORCHIDv2-Bereiche | +| `64:ff9b::/96`, `64:ff9b:1::/48` | NAT64-Präfixe mit eingebettetem IPv4 | +| `2002::/16`, `2001::/32` | 6to4 und Teredo mit eingebettetem IPv4 | +| `::/96`, `::ffff:0:0/96` | IPv4-kompatibles und IPv4-mapped IPv6 | -Wenn Ihr Cloud-Provider oder Ihre Netzwerkplattform zusätzliche Metadata-Hosts oder reservierte Bereiche dokumentiert, fügen Sie auch diese hinzu. +Wenn Ihr Cloud-Provider oder Ihre Netzwerkplattform zusätzliche Metadata-Hosts oder reservierte Bereiche dokumentiert, fügen Sie diese ebenfalls hinzu. ## Validierung @@ -146,9 +146,9 @@ Validieren Sie den Proxy von demselben Host, Container oder Dienstkonto aus, auf openclaw proxy validate --proxy-url http://127.0.0.1:3128 ``` -Standardmäßig prüft der Befehl, wenn keine benutzerdefinierten Ziele angegeben sind, dass `https://example.com/` erfolgreich ist, und startet einen temporären Loopback-Canary, den der Proxy nicht erreichen darf. Die standardmäßige verweigerte Prüfung besteht, wenn der Proxy eine Nicht-2xx-Verweigerungsantwort zurückgibt oder den Canary mit einem Transportfehler blockiert; sie schlägt fehl, wenn eine erfolgreiche Antwort den Canary erreicht. Wenn kein Proxy aktiviert und konfiguriert ist, meldet die Validierung ein Konfigurationsproblem; verwenden Sie `--proxy-url` für einen einmaligen Preflight, bevor Sie die Konfiguration ändern. Verwenden Sie `--allowed-url` und `--denied-url`, um bereitstellungsspezifische Erwartungen zu testen. Benutzerdefinierte verweigerte Ziele sind fail-closed: Jede HTTP-Antwort bedeutet, dass das Ziel über den Proxy erreichbar war, und jeder Transportfehler wird als nicht schlüssig gemeldet, weil OpenClaw nicht beweisen kann, dass der Proxy einen erreichbaren Origin blockiert hat. Bei einem Validierungsfehler beendet sich der Befehl mit Code 1. +Standardmäßig prüft der Befehl, wenn keine benutzerdefinierten Ziele bereitgestellt werden, dass `https://example.com/` erfolgreich ist, und startet einen temporären Loopback-Canary, den der Proxy nicht erreichen darf. Die standardmäßige Ablehnungsprüfung gilt als bestanden, wenn der Proxy eine Nicht-2xx-Ablehnungsantwort zurückgibt oder den Canary mit einem Transportfehler blockiert; sie schlägt fehl, wenn eine erfolgreiche Antwort den Canary erreicht. Wenn kein Proxy aktiviert und konfiguriert ist, meldet die Validierung ein Konfigurationsproblem; verwenden Sie `--proxy-url` für einen einmaligen Preflight, bevor Sie die Konfiguration ändern. Verwenden Sie `--allowed-url` und `--denied-url`, um deployment-spezifische Erwartungen zu testen. Benutzerdefinierte abgelehnte Ziele sind Fail-Closed: Jede HTTP-Antwort bedeutet, dass das Ziel über den Proxy erreichbar war, und jeder Transportfehler wird als nicht schlüssig gemeldet, weil OpenClaw nicht beweisen kann, dass der Proxy einen erreichbaren Ursprung blockiert hat. Bei einem Validierungsfehler beendet sich der Befehl mit Code 1. -Verwenden Sie `--json` für Automatisierung. Die JSON-Ausgabe enthält das Gesamtergebnis, die effektive Proxy-Konfigurationsquelle, alle Konfigurationsfehler und jede Zielprüfung. Anmeldedaten in Proxy-URLs werden in Text- und JSON-Ausgabe redigiert: +Verwenden Sie `--json` für Automatisierung. Die JSON-Ausgabe enthält das Gesamtergebnis, die effektive Proxy-Konfigurationsquelle, etwaige Konfigurationsfehler und jede Zielprüfung. Proxy-URL-Anmeldedaten werden in Text- und JSON-Ausgabe geschwärzt: ```json { @@ -178,7 +178,7 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/ curl -x http://127.0.0.1:3128 http://169.254.169.254/ ``` -Die öffentliche Anfrage sollte erfolgreich sein. Die Loopback- und Metadatenanfragen sollten vom Proxy blockiert werden. Bei `openclaw proxy validate` kann der integrierte Loopback-Canary eine Proxy-Ablehnung von einem erreichbaren Ursprung unterscheiden. Benutzerdefinierte `--denied-url`-Prüfungen haben diesen Canary nicht. Behandeln Sie daher sowohl HTTP-Antworten als auch mehrdeutige Transportfehler als Validierungsfehler, es sei denn, Ihr Proxy stellt ein bereitstellungsspezifisches Ablehnungssignal bereit, das Sie separat verifizieren können. +Die öffentliche Anfrage sollte erfolgreich sein. Die Loopback- und Metadatenanfragen sollten vom Proxy blockiert werden. Bei `openclaw proxy validate` kann der integrierte Loopback-Canary eine Proxy-Ablehnung von einem erreichbaren Ursprungsziel unterscheiden. Benutzerdefinierte `--denied-url`-Prüfungen haben diesen Canary nicht. Behandeln Sie daher sowohl HTTP-Antworten als auch uneindeutige Transportfehler als Validierungsfehler, es sei denn, Ihr Proxy stellt ein bereitstellungsspezifisches Ablehnungssignal bereit, das Sie separat verifizieren können. Aktivieren Sie anschließend das OpenClaw-Proxy-Routing: @@ -188,7 +188,7 @@ openclaw config set proxy.proxyUrl http://127.0.0.1:3128 openclaw gateway run ``` -oder setzen Sie: +oder legen Sie Folgendes fest: ```yaml proxy: @@ -196,12 +196,13 @@ proxy: proxyUrl: http://127.0.0.1:3128 ``` -## Grenzen +## Einschränkungen - Der Proxy verbessert die Abdeckung für prozesslokale JavaScript-HTTP- und WebSocket-Clients, ist aber keine Netzwerk-Sandbox auf Betriebssystemebene. -- Rohe `net`-, `tls`- und `http2`-Sockets, native Add-ons und Kindprozesse können Proxy-Routing auf Node-Ebene umgehen, sofern sie Proxy-Umgebungsvariablen nicht erben und beachten. -- IRC ist ein roher TCP/TLS-Kanal außerhalb des vom Betreiber verwalteten Forward-Proxy-Routings. In Bereitstellungen, die erfordern, dass der gesamte ausgehende Datenverkehr über diesen Forward Proxy läuft, setzen Sie `channels.irc.enabled=false`, sofern direkter IRC-Ausgang nicht ausdrücklich genehmigt ist. -- Benutzerlokale WebUIs und lokale Modellserver sollten bei Bedarf in der Proxy-Richtlinie des Betreibers auf die Allowlist gesetzt werden; OpenClaw stellt dafür keinen allgemeinen Bypass für lokale Netzwerke bereit. -- Der Proxy-Bypass der Gateway-Control-Plane ist absichtlich auf `localhost` und wörtliche Loopback-IP-URLs beschränkt. Verwenden Sie `ws://127.0.0.1:18789`, `ws://[::1]:18789` oder `ws://localhost:18789` für lokale direkte Gateway-Control-Plane-Verbindungen; andere Hostnamen werden wie gewöhnlicher hostnamenbasierter Datenverkehr geroutet. +- Raw-`net`-, `tls`- und `http2`-Sockets, native Add-ons und untergeordnete Prozesse können das Proxy-Routing auf Node-Ebene umgehen, sofern sie Proxy-Umgebungsvariablen nicht erben und respektieren. +- IRC ist ein Raw-TCP/TLS-Kanal außerhalb des vom Betreiber verwalteten Forward-Proxy-Routings. Legen Sie in Bereitstellungen, die sämtlichen ausgehenden Datenverkehr über diesen Forward Proxy erzwingen, `channels.irc.enabled=false` fest, sofern direkter ausgehender IRC-Datenverkehr nicht ausdrücklich genehmigt ist. +- Der lokale Debug-Proxy ist Diagnosewerkzeug, und seine direkte Upstream-Weiterleitung für Proxy-Anfragen und CONNECT-Tunnel ist standardmäßig deaktiviert, solange der verwaltete Proxy-Modus aktiv ist. Aktivieren Sie die direkte Weiterleitung nur für genehmigte lokale Diagnosen. +- Lokale WebUIs von Benutzern und lokale Modellserver sollten bei Bedarf in der Betreiber-Proxy-Richtlinie auf die Allowlist gesetzt werden. OpenClaw stellt für sie keine allgemeine Umgehung des lokalen Netzwerks bereit. +- Die Proxy-Umgehung der Gateway-Control-Plane ist absichtlich auf `localhost` und wörtliche Loopback-IP-URLs beschränkt. Verwenden Sie `ws://127.0.0.1:18789`, `ws://[::1]:18789` oder `ws://localhost:18789` für lokale direkte Gateway-Control-Plane-Verbindungen. Andere Hostnamen werden wie gewöhnlicher hostnamenbasierter Datenverkehr geroutet. - OpenClaw prüft, testet oder zertifiziert Ihre Proxy-Richtlinie nicht. -- Behandeln Sie Änderungen an Proxy-Richtlinien als sicherheitsrelevante betriebliche Änderungen. +- Behandeln Sie Änderungen an der Proxy-Richtlinie als sicherheitsrelevante betriebliche Änderungen. diff --git a/docs/de/tools/subagents.md b/docs/de/tools/subagents.md index effa130e9..3330a3c5a 100644 --- a/docs/de/tools/subagents.md +++ b/docs/de/tools/subagents.md @@ -1,29 +1,28 @@ --- read_when: - - Sie möchten Hintergrundarbeit oder parallele Arbeit über den Agenten ausführen - - Sie ändern `sessions_spawn` oder die Richtlinie für Sub-Agent-Tools - - Sie implementieren oder beheben Probleme bei threadgebundenen Subagent-Sitzungen + - Sie möchten Hintergrundarbeit oder parallele Arbeit über den Agenten nutzen + - Sie ändern die Richtlinie für sessions_spawn oder Sub-Agent-Tools + - Sie implementieren threadgebundene Subagent-Sitzungen oder beheben Probleme damit sidebarTitle: Sub-agents -summary: Isolierte Agent-Ausführungen im Hintergrund starten, die Ergebnisse an den Chat der anfragenden Person zurückmelden +summary: Starten Sie isolierte Hintergrund-Agentenläufe, die Ergebnisse an den Chat der anfragenden Person zurückmelden title: Sub-Agenten x-i18n: - generated_at: "2026-05-04T02:26:34Z" + generated_at: "2026-05-04T06:44:07Z" model: gpt-5.5 provider: openai - source_hash: d0df39e06b952def3eb0b296f36c7dc8c0b0a115785d865236a970c5d453fc37 + source_hash: 65d60bf6813d667b7311aa28109d4bd6be012a16e638c64cfff130831db88cd8 source_path: tools/subagents.md workflow: 16 --- -Sub-Agents sind Hintergrund-Agentenläufe, die aus einem bestehenden Agentenlauf gestartet werden. +Sub-Agents sind Hintergrund-Agent-Ausführungen, die aus einer bestehenden Agent-Ausführung gestartet werden. Sie laufen in ihrer eigenen Sitzung (`agent::subagent:`) und -**kündigen** nach Abschluss ihr Ergebnis im Chat-Kanal des Anforderers an. -Jeder Sub-Agent-Lauf wird als +**kündigen** nach Abschluss ihr Ergebnis im Chat-Kanal des Anforderers an. Jede Sub-Agent-Ausführung wird als [Hintergrundaufgabe](/de/automation/tasks) nachverfolgt. Primäre Ziele: -- Arbeit für „Recherche / lange Aufgabe / langsames Tool“ parallelisieren, ohne den Hauptlauf zu blockieren. +- Arbeit für „Recherche / lange Aufgabe / langsames Tool“ parallelisieren, ohne die Hauptausführung zu blockieren. - Sub-Agents standardmäßig isoliert halten (Sitzungstrennung + optionales Sandboxing). - Die Tool-Oberfläche schwer missbrauchbar halten: Sub-Agents erhalten standardmäßig **keine** Sitzungs-Tools. - Konfigurierbare Verschachtelungstiefe für Orchestrator-Muster unterstützen. @@ -31,18 +30,18 @@ Primäre Ziele: **Kostenhinweis:** Jeder Sub-Agent hat standardmäßig seinen eigenen Kontext und Token-Verbrauch. Legen Sie für aufwendige oder repetitive Aufgaben ein -günstigeres Modell für Sub-Agents fest und behalten Sie Ihren Haupt-Agenten -auf einem hochwertigeren Modell. Konfigurieren Sie dies über -`agents.defaults.subagents.model` oder über agentenspezifische Overrides. Wenn ein Kind - tatsächlich das aktuelle Transkript des Anforderers benötigt, kann der Agent - für diesen einen Spawn `context: "fork"` anfordern. Thread-gebundene Sub-Agent-Sitzungen verwenden standardmäßig +günstigeres Modell für Sub-Agents fest und behalten Sie für Ihren Haupt-Agent +ein hochwertigeres Modell bei. Konfigurieren Sie dies über +`agents.defaults.subagents.model` oder agent-spezifische Überschreibungen. Wenn ein untergeordneter Agent + wirklich das aktuelle Transkript des Anforderers benötigt, kann der Agent + bei genau diesem Spawn `context: "fork"` anfordern. Thread-gebundene Sub-Agent-Sitzungen verwenden standardmäßig `context: "fork"`, weil sie die aktuelle Unterhaltung in einen - Folge-Thread verzweigen. + Follow-up-Thread verzweigen. ## Slash-Befehl -Verwenden Sie `/subagents`, um Sub-Agent-Läufe für die **aktuelle +Verwenden Sie `/subagents`, um Sub-Agent-Ausführungen für die **aktuelle Sitzung** zu prüfen oder zu steuern: ```text @@ -55,11 +54,11 @@ Sitzung** zu prüfen oder zu steuern: /subagents spawn [--model ] [--thinking ] ``` -Verwenden Sie den Top-Level-Befehl [`/steer `](/de/tools/steer), um den aktiven Lauf der aktuellen Anforderer-Sitzung zu steuern. Verwenden Sie `/subagents steer `, wenn das Ziel ein Kindlauf ist. +Verwenden Sie [`/steer `](/de/tools/steer) auf oberster Ebene, um die aktive Ausführung der aktuellen Anforderer-Sitzung zu steuern. Verwenden Sie `/subagents steer `, wenn das Ziel eine untergeordnete Ausführung ist. -`/subagents info` zeigt Lauf-Metadaten (Status, Zeitstempel, Sitzungs-ID, +`/subagents info` zeigt Ausführungsmetadaten (Status, Zeitstempel, Sitzungs-ID, Transkriptpfad, Bereinigung). Verwenden Sie `sessions_history` für eine begrenzte, -sicherheitsgefilterte Erinnerungsansicht; prüfen Sie den Transkriptpfad auf dem Datenträger, wenn Sie +sicherheitsgefilterte Abrufansicht; prüfen Sie den Transkriptpfad auf dem Datenträger, wenn Sie das rohe vollständige Transkript benötigen. ### Steuerelemente für Thread-Bindung @@ -78,76 +77,76 @@ Siehe [Thread-unterstützende Kanäle](#thread-supporting-channels) unten. ### Spawn-Verhalten `/subagents spawn` startet einen Hintergrund-Sub-Agent als Benutzerbefehl (nicht als -interne Weiterleitung) und sendet eine abschließende Abschlussaktualisierung zurück an den -Anforderer-Chat, wenn der Lauf beendet ist. +internen Relay) und sendet eine abschließende Abschlussaktualisierung zurück an den +Anforderer-Chat, wenn die Ausführung beendet ist. - - - Der Spawn-Befehl ist nicht blockierend; er gibt sofort eine Lauf-ID zurück. - - Nach Abschluss kündigt der Sub-Agent eine Zusammenfassung/Ergebnisnachricht zurück im Chat-Kanal des Anforderers an. - - Der Abschluss ist push-basiert. Nach dem Starten sollten Sie **nicht** `/subagents list`, `sessions_list` oder `sessions_history` in einer Schleife abfragen, nur um auf den Abschluss zu warten; prüfen Sie den Status nur bei Bedarf zum Debuggen oder Eingreifen. - - Nach Abschluss schließt OpenClaw nach bestem Aufwand nachverfolgte Browser-Tabs/Prozesse, die von dieser Sub-Agent-Sitzung geöffnet wurden, bevor der Ankündigungs-Bereinigungsablauf fortgesetzt wird. + + - Der Spawn-Befehl blockiert nicht; er gibt sofort eine Ausführungs-ID zurück. + - Nach Abschluss kündigt der Sub-Agent eine Zusammenfassungs-/Ergebnismeldung im Chat-Kanal des Anforderers an. + - Der Abschluss ist Push-basiert. Nachdem der Spawn gestartet wurde, pollen Sie **nicht** `/subagents list`, `sessions_list` oder `sessions_history` in einer Schleife, nur um auf den Abschluss zu warten; prüfen Sie den Status nur bei Bedarf für Debugging oder Eingriff. + - Nach Abschluss schließt OpenClaw nach bestem Aufwand nachverfolgte Browser-Tabs/-Prozesse, die von dieser Sub-Agent-Sitzung geöffnet wurden, bevor der Ankündigungs-Bereinigungsablauf fortgesetzt wird. - + - OpenClaw versucht zuerst die direkte `agent`-Zustellung mit einem stabilen Idempotenzschlüssel. - - Wenn die direkte Zustellung fehlschlägt, fällt es auf Queue-Routing zurück. + - Wenn der Abschluss-Turn des Anforderer-Agents fehlschlägt, keine sichtbare Ausgabe erzeugt oder ein offensichtlich unvollständiges Präfix des erfassten untergeordneten Ergebnisses zurückgibt, fällt OpenClaw auf direkte Abschlusszustellung aus dem erfassten untergeordneten Ergebnis zurück. + - Wenn die direkte Zustellung nicht verwendet werden kann, fällt es auf Queue-Routing zurück. - Wenn Queue-Routing weiterhin nicht verfügbar ist, wird die Ankündigung mit kurzem exponentiellem Backoff erneut versucht, bevor endgültig aufgegeben wird. - - Die Abschlusszustellung behält die aufgelöste Anforderer-Route bei: Thread-gebundene oder unterhaltungsgebundene Abschlussrouten gewinnen, wenn sie verfügbar sind; wenn der Abschlussursprung nur einen Kanal bereitstellt, ergänzt OpenClaw das fehlende Ziel/Konto aus der aufgelösten Route der Anforderer-Sitzung (`lastChannel` / `lastTo` / `lastAccountId`), sodass die direkte Zustellung weiterhin funktioniert. + - Die Abschlusszustellung behält die aufgelöste Anforderer-Route bei: Thread-gebundene oder unterhaltungsgebundene Abschlussrouten gewinnen, wenn verfügbar; wenn der Abschlussursprung nur einen Kanal bereitstellt, ergänzt OpenClaw das fehlende Ziel/Konto aus der aufgelösten Route der Anforderer-Sitzung (`lastChannel` / `lastTo` / `lastAccountId`), sodass direkte Zustellung weiterhin funktioniert. - + Die Abschlussübergabe an die Anforderer-Sitzung ist zur Laufzeit erzeugter - interner Kontext (kein vom Benutzer verfasster Text) und enthält: + interner Kontext (kein von Benutzern verfasster Text) und enthält: - - `Result` — den neuesten sichtbaren `assistant`-Antworttext, andernfalls bereinigten neuesten Tool-/toolResult-Text. Terminal fehlgeschlagene Läufe verwenden erfassten Antworttext nicht erneut. + - `Result` — neuester sichtbarer `assistant`-Antworttext, andernfalls bereinigter neuester Tool-/toolResult-Text. Terminal fehlgeschlagene Ausführungen verwenden erfassten Antworttext nicht erneut. - `Status` — `completed successfully` / `failed` / `timed out` / `unknown`. - Kompakte Laufzeit-/Token-Statistiken. - - Eine Zustellungsanweisung, die dem Anforderer-Agenten mitteilt, in normaler Assistant-Stimme umzuschreiben (keine rohen internen Metadaten weiterzuleiten). + - Eine Zustellungsanweisung, die den Anforderer-Agent anweist, in normaler Assistentenstimme neu zu formulieren (keine rohen internen Metadaten weiterzuleiten). - - - `--model` und `--thinking` überschreiben die Standards für diesen spezifischen Lauf. + + - `--model` und `--thinking` überschreiben die Standardwerte für diese spezifische Ausführung. - Verwenden Sie `info`/`log`, um Details und Ausgabe nach Abschluss zu prüfen. - `/subagents spawn` ist ein Einmalmodus (`mode: "run"`). Verwenden Sie für persistente Thread-gebundene Sitzungen `sessions_spawn` mit `thread: true` und `mode: "session"`. - - Verwenden Sie für ACP-Harness-Sitzungen (Claude Code, Gemini CLI, OpenCode oder explizites Codex ACP/acpx) `sessions_spawn` mit `runtime: "acp"`, wenn das Tool diese Laufzeit bewirbt. Siehe [ACP-Zustellungsmodell](/de/tools/acp-agents#delivery-model), wenn Sie Abschlüsse oder Agent-zu-Agent-Schleifen debuggen. Wenn das `codex`-Plugin aktiviert ist, sollte die Codex-Chat-/Thread-Steuerung `/codex ...` gegenüber ACP bevorzugen, sofern der Benutzer nicht ausdrücklich ACP/acpx anfordert. - - OpenClaw blendet `runtime: "acp"` aus, bis ACP aktiviert ist, der Anforderer nicht sandboxed ist und ein Backend-Plugin wie `acpx` geladen ist. `runtime: "acp"` erwartet eine externe ACP-Harness-ID oder einen Eintrag `agents.list[]` mit `runtime.type="acp"`; verwenden Sie die Standard-Sub-Agent-Laufzeit für normale OpenClaw-Konfigurationsagenten aus `agents_list`. + - Verwenden Sie für ACP-Harness-Sitzungen (Claude Code, Gemini CLI, OpenCode oder explizites Codex ACP/acpx) `sessions_spawn` mit `runtime: "acp"`, wenn das Tool diese Runtime bewirbt. Siehe [ACP-Zustellungsmodell](/de/tools/acp-agents#delivery-model), wenn Sie Abschlüsse oder Agent-zu-Agent-Schleifen debuggen. Wenn das `codex`-Plugin aktiviert ist, sollte die Steuerung von Codex-Chat/-Thread `/codex ...` gegenüber ACP bevorzugen, sofern der Benutzer nicht ausdrücklich ACP/acpx anfordert. + - OpenClaw blendet `runtime: "acp"` aus, bis ACP aktiviert ist, der Anforderer nicht sandboxed ist und ein Backend-Plugin wie `acpx` geladen ist. `runtime: "acp"` erwartet eine externe ACP-Harness-ID oder einen `agents.list[]`-Eintrag mit `runtime.type="acp"`; verwenden Sie die Standard-Sub-Agent-Runtime für normale OpenClaw-Konfigurations-Agents aus `agents_list`. ## Kontextmodi -Native Sub-Agents starten isoliert, sofern der Aufrufer nicht ausdrücklich anfordert, das -aktuelle Transkript zu forken. +Native Sub-Agents starten isoliert, sofern der Aufrufer nicht ausdrücklich anfordert, das aktuelle Transkript zu forken. -| Modus | Wann Sie ihn verwenden sollten | Verhalten | +| Modus | Wann er verwendet werden sollte | Verhalten | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | -| `isolated` | Frische Recherche, unabhängige Implementierung, langsame Tool-Arbeit oder alles, was im Aufgabentext knapp erklärt werden kann | Erstellt ein sauberes Kindtranskript. Dies ist der Standard und hält den Token-Verbrauch niedriger. | -| `fork` | Arbeit, die von der aktuellen Unterhaltung, vorherigen Tool-Ergebnissen oder nuancierten Anweisungen abhängt, die bereits im Anforderer-Transkript vorhanden sind | Verzweigt das Anforderer-Transkript in die Kind-Sitzung, bevor das Kind startet. | +| `isolated` | Frische Recherche, unabhängige Implementierung, langsame Tool-Arbeit oder alles, was im Aufgabentext beschrieben werden kann | Erstellt ein sauberes untergeordnetes Transkript. Dies ist der Standard und hält den Token-Verbrauch niedriger. | +| `fork` | Arbeit, die von der aktuellen Unterhaltung, früheren Tool-Ergebnissen oder nuancierten Anweisungen abhängt, die bereits im Anforderer-Transkript vorhanden sind | Verzweigt das Anforderer-Transkript in die untergeordnete Sitzung, bevor der untergeordnete Agent startet. | -Verwenden Sie `fork` sparsam. Es ist für kontextsensitive Delegierung gedacht, nicht als -Ersatz für einen klaren Aufgaben-Prompt. +Verwenden Sie `fork` sparsam. Es ist für kontextsensitive Delegation gedacht, nicht als +Ersatz für das Schreiben eines klaren Aufgabenprompts. ## Tool: `sessions_spawn` -Startet einen Sub-Agent-Lauf mit `deliver: false` auf der globalen `subagent`-Lane, +Startet eine Sub-Agent-Ausführung mit `deliver: false` auf der globalen `subagent`-Lane, führt dann einen Ankündigungsschritt aus und postet die Ankündigungsantwort in den Chat-Kanal des Anforderers. Die Verfügbarkeit hängt von der effektiven Tool-Richtlinie des Aufrufers ab. Die Profile `coding` und `full` stellen `sessions_spawn` standardmäßig bereit. Das Profil `messaging` -tut dies nicht; fügen Sie `tools.alsoAllow: ["sessions_spawn", "sessions_yield", -"subagents"]` hinzu oder verwenden Sie `tools.profile: "coding"` für Agenten, die Arbeit -delegieren sollen. Kanal-/Gruppen-, Provider-, Sandbox- und agentenspezifische Allow-/Deny-Richtlinien können +nicht; fügen Sie `tools.alsoAllow: ["sessions_spawn", "sessions_yield", +"subagents"]` hinzu oder verwenden Sie `tools.profile: "coding"` für Agents, die Arbeit +delegieren sollen. Kanal-/Gruppen-, Provider-, Sandbox- und agent-spezifische Allow-/Deny-Richtlinien können das Tool nach der Profilphase weiterhin entfernen. Verwenden Sie `/tools` aus derselben Sitzung, um die effektive Tool-Liste zu bestätigen. -**Standards:** +**Standardwerte:** -- **Modell:** erbt vom Aufrufer, sofern Sie nicht `agents.defaults.subagents.model` festlegen (oder agentenspezifisch `agents.list[].subagents.model`); ein explizites `sessions_spawn.model` gewinnt weiterhin. -- **Thinking:** erbt vom Aufrufer, sofern Sie nicht `agents.defaults.subagents.thinking` festlegen (oder agentenspezifisch `agents.list[].subagents.thinking`); ein explizites `sessions_spawn.thinking` gewinnt weiterhin. -- **Lauf-Timeout:** Wenn `sessions_spawn.runTimeoutSeconds` ausgelassen wird, verwendet OpenClaw `agents.defaults.subagents.runTimeoutSeconds`, falls gesetzt; andernfalls fällt es auf `0` zurück (kein Timeout). +- **Modell:** erbt vom Aufrufer, sofern Sie nicht `agents.defaults.subagents.model` (oder agent-spezifisch `agents.list[].subagents.model`) festlegen; ein explizites `sessions_spawn.model` gewinnt weiterhin. +- **Thinking:** erbt vom Aufrufer, sofern Sie nicht `agents.defaults.subagents.thinking` (oder agent-spezifisch `agents.list[].subagents.thinking`) festlegen; ein explizites `sessions_spawn.thinking` gewinnt weiterhin. +- **Ausführungs-Timeout:** Wenn `sessions_spawn.runTimeoutSeconds` ausgelassen wird, verwendet OpenClaw `agents.defaults.subagents.runTimeoutSeconds`, sofern gesetzt; andernfalls fällt es auf `0` (kein Timeout) zurück. ### Tool-Parameter @@ -158,60 +157,60 @@ Sitzung, um die effektive Tool-Liste zu bestätigen. Optionales menschenlesbares Label. - Unter einer anderen Agenten-ID starten, wenn dies durch `subagents.allowAgents` erlaubt ist. + Unter einer anderen Agent-ID starten, wenn durch `subagents.allowAgents` erlaubt. - `acp` ist nur für externe ACP-Harnesse (`claude`, `droid`, `gemini`, `opencode` oder ausdrücklich angefordertes Codex ACP/acpx) und für `agents.list[]`-Einträge, deren `runtime.type` `acp` ist. + `acp` ist nur für externe ACP-Harnesses (`claude`, `droid`, `gemini`, `opencode` oder ausdrücklich angefordertes Codex ACP/acpx) und für `agents.list[]`-Einträge bestimmt, deren `runtime.type` `acp` ist. Nur ACP. Setzt eine bestehende ACP-Harness-Sitzung fort, wenn `runtime: "acp"`; wird bei nativen Sub-Agent-Spawns ignoriert. - Nur ACP. Streamt die Ausgabe des ACP-Laufs an die übergeordnete Sitzung, wenn `runtime: "acp"`; bei nativen Sub-Agent-Spawns weglassen. + Nur ACP. Streamt die ACP-Ausführungsausgabe an die übergeordnete Sitzung, wenn `runtime: "acp"`; bei nativen Sub-Agent-Spawns auslassen. - Überschreibt das Sub-Agent-Modell. Ungültige Werte werden übersprungen und der Sub-Agent läuft mit einer Warnung im Tool-Ergebnis auf dem Standardmodell. + Überschreibt das Sub-Agent-Modell. Ungültige Werte werden übersprungen, und der Sub-Agent läuft auf dem Standardmodell mit einer Warnung im Tool-Ergebnis. - Überschreibt die Thinking-Stufe für den Sub-Agent-Lauf. + Überschreibt die Thinking-Stufe für die Sub-Agent-Ausführung. - Standardmäßig `agents.defaults.subagents.runTimeoutSeconds`, wenn gesetzt, andernfalls `0`. Wenn gesetzt, wird der Sub-Agent-Lauf nach N Sekunden abgebrochen. + Standardmäßig `agents.defaults.subagents.runTimeoutSeconds`, wenn gesetzt, andernfalls `0`. Wenn gesetzt, wird die Sub-Agent-Ausführung nach N Sekunden abgebrochen. - Wenn `true`, fordert dies eine Kanal-Thread-Bindung für diese Sub-Agent-Sitzung an. + Wenn `true`, wird eine Kanal-Thread-Bindung für diese Sub-Agent-Sitzung angefordert. Wenn `thread: true` und `mode` ausgelassen wird, wird der Standard zu `session`. `mode: "session"` erfordert `thread: true`. - `"delete"` archiviert unmittelbar nach der Ankündigung (behält das Transkript trotzdem per Umbenennung). + `"delete"` archiviert unmittelbar nach der Ankündigung (behält das Transkript weiterhin per Umbenennung). - `require` lehnt den Spawn ab, sofern die Ziel-Kindlaufzeit nicht sandboxed ist. + `require` weist den Spawn zurück, sofern die Ziel-Laufzeit des untergeordneten Agents nicht sandboxed ist. - `fork` verzweigt das aktuelle Transkript des Anforderers in die Kind-Sitzung. Nur native Sub-Agents. Thread-gebundene Spawns verwenden standardmäßig `fork`; nicht Thread-gebundene Spawns standardmäßig `isolated`. + `fork` verzweigt das aktuelle Transkript des Anforderers in die untergeordnete Sitzung. Nur native Sub-Agents. Thread-gebundene Spawns verwenden standardmäßig `fork`; Nicht-Thread-Spawns standardmäßig `isolated`. -`sessions_spawn` akzeptiert **keine** Parameter für Kanalzustellung (`target`, +`sessions_spawn` akzeptiert **keine** Kanalzustellungsparameter (`target`, `channel`, `to`, `threadId`, `replyTo`, `transport`). Verwenden Sie für die Zustellung -`message`/`sessions_send` aus dem gestarteten Lauf. +`message`/`sessions_send` aus der gestarteten Ausführung. ## Thread-gebundene Sitzungen -Wenn Thread-Bindungen für einen Kanal aktiviert sind, kann ein Sub-Agent an -einen Thread gebunden bleiben, sodass Folge-Nachrichten von Benutzern in diesem Thread weiterhin an dieselbe -Sub-Agent-Sitzung weitergeleitet werden. +Wenn Thread-Bindungen für einen Kanal aktiviert sind, kann ein Sub-Agent an einen Thread +gebunden bleiben, sodass Folge-Nachrichten von Benutzern in diesem Thread weiterhin an dieselbe +Sub-Agent-Sitzung geroutet werden. ### Thread-unterstützende Kanäle **Discord** ist derzeit der einzige unterstützte Kanal. Er unterstützt persistente Thread-gebundene Sub-Agent-Sitzungen (`sessions_spawn` mit `thread: true`), manuelle Thread-Steuerungen (`/focus`, `/unfocus`, `/agents`, -`/session idle`, `/session max-age`) und Adapter-Schlüssel +`/session idle`, `/session max-age`) sowie Adapter-Schlüssel `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours` und @@ -220,21 +219,21 @@ persistente Thread-gebundene Sub-Agent-Sitzungen (`sessions_spawn` mit ### Schnellablauf - + `sessions_spawn` mit `thread: true` (und optional `mode: "session"`). - - OpenClaw erstellt oder bindet einen Thread an dieses Sitzungsziel im aktiven Kanal. + + OpenClaw erstellt einen Thread oder bindet einen Thread an dieses Sitzungsziel im aktiven Kanal. - - Antworten und Folge-Nachrichten in diesem Thread werden an die gebundene Sitzung weitergeleitet. + + Antworten und Folgemeldungen in diesem Thread werden an die gebundene Sitzung weitergeleitet. - - Verwenden Sie `/session idle`, um automatisches Unfocus bei Inaktivität zu prüfen/aktualisieren, und + + Verwenden Sie `/session idle`, um die automatische Inaktivitäts-Entfokussierung zu prüfen/aktualisieren, und `/session max-age`, um die harte Obergrenze zu steuern. - - Verwenden Sie `/unfocus`, um manuell zu trennen. + + Verwenden Sie `/unfocus`, um die Bindung manuell zu lösen. @@ -242,16 +241,16 @@ persistente Thread-gebundene Sub-Agent-Sitzungen (`sessions_spawn` mit | Befehl | Wirkung | | ------------------ | --------------------------------------------------------------------- | -| `/focus ` | Bindet den aktuellen Thread (oder erstellt einen) an ein Sub-Agent-/Sitzungsziel | -| `/unfocus` | Entfernt die Bindung für den aktuell gebundenen Thread | -| `/agents` | Listet aktive Ausführungen und den Bindungsstatus auf (`thread:` oder `unbound`) | -| `/session idle` | Idle-Auto-Unfocus prüfen/aktualisieren (nur fokussierte gebundene Threads) | -| `/session max-age` | Hard Cap prüfen/aktualisieren (nur fokussierte gebundene Threads) | +| `/focus ` | Aktuellen Thread (oder einen neuen) an ein Sub-Agent-/Sitzungsziel binden | +| `/unfocus` | Bindung für den aktuell gebundenen Thread entfernen | +| `/agents` | Aktive Läufe und Bindungsstatus auflisten (`thread:` oder `unbound`) | +| `/session idle` | Automatische Inaktivitäts-Entfokussierung prüfen/aktualisieren (nur fokussierte gebundene Threads) | +| `/session max-age` | Harte Obergrenze prüfen/aktualisieren (nur fokussierte gebundene Threads) | ### Konfigurationsschalter - **Globaler Standard:** `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. -- **Channel-Override und Spawn-Auto-Bind-Schlüssel** sind adapter-spezifisch. Siehe [Thread-unterstützende Channels](#thread-supporting-channels) oben. +- **Kanalspezifische Überschreibung und Schlüssel für automatische Bindung beim Spawn** sind adapterspezifisch. Siehe [Thread-unterstützende Kanäle](#thread-supporting-channels) oben. Siehe [Konfigurationsreferenz](/de/gateway/configuration-reference) und [Slash-Befehle](/de/tools/slash-commands) für aktuelle Adapterdetails. @@ -259,41 +258,41 @@ Siehe [Konfigurationsreferenz](/de/gateway/configuration-reference) und ### Allowlist - Liste von Agent-IDs, die über explizites `agentId` als Ziel verwendet werden können (`["*"]` erlaubt beliebige). Standard: nur der anfragende Agent. Wenn Sie eine Liste festlegen und trotzdem möchten, dass der Anfragende sich selbst mit `agentId` starten kann, nehmen Sie die ID des Anfragenden in die Liste auf. + Liste von Agent-IDs, die über explizites `agentId` adressiert werden können (`["*"]` erlaubt beliebige). Standard: nur der anfordernde Agent. Wenn Sie eine Liste festlegen und weiterhin möchten, dass der anfordernde Agent sich selbst mit `agentId` spawnt, nehmen Sie die ID des anfordernden Agents in die Liste auf. - Standard-Allowlist für Ziel-Agenten, die verwendet wird, wenn der anfragende Agent kein eigenes `subagents.allowAgents` festlegt. + Standard-Allowlist für Ziel-Agents, die verwendet wird, wenn der anfordernde Agent kein eigenes `subagents.allowAgents` festlegt. - Blockiert `sessions_spawn`-Aufrufe, die `agentId` weglassen (erzwingt explizite Profilauswahl). Override pro Agent: `agents.list[].subagents.requireAgentId`. + Blockiert `sessions_spawn`-Aufrufe, die `agentId` auslassen (erzwingt explizite Profilauswahl). Überschreibung pro Agent: `agents.list[].subagents.requireAgentId`. -Wenn die Sitzung des Anfragenden sandboxed ist, lehnt `sessions_spawn` Ziele ab, +Wenn die anfordernde Sitzung sandboxed ist, lehnt `sessions_spawn` Ziele ab, die ohne Sandbox laufen würden. ### Erkennung Verwenden Sie `agents_list`, um zu sehen, welche Agent-IDs derzeit für `sessions_spawn` erlaubt sind. Die Antwort enthält das effektive -Modell jedes aufgeführten Agenten und eingebettete Laufzeitmetadaten, damit Aufrufer Pi, Codex -App-Server und andere konfigurierte native Laufzeiten unterscheiden können. +Modell jedes aufgeführten Agents und eingebettete Runtime-Metadaten, damit Aufrufer Pi, Codex +App-Server und andere konfigurierte native Runtimes unterscheiden können. ### Automatische Archivierung -- Sub-Agent-Sitzungen werden nach `agents.defaults.subagents.archiveAfterMinutes` automatisch archiviert (Standard `60`). -- Die Archivierung verwendet `sessions.delete` und benennt das Transkript in `*.deleted.` um (gleicher Ordner). -- `cleanup: "delete"` archiviert unmittelbar nach der Ankündigung (behält das Transkript trotzdem per Umbenennung). -- Automatische Archivierung ist bestmöglich; ausstehende Timer gehen verloren, wenn der Gateway neu startet. -- `runTimeoutSeconds` archiviert **nicht** automatisch; es stoppt nur die Ausführung. Die Sitzung bleibt bis zur automatischen Archivierung bestehen. +- Sub-Agent-Sitzungen werden nach `agents.defaults.subagents.archiveAfterMinutes` (Standard `60`) automatisch archiviert. +- Die Archivierung verwendet `sessions.delete` und benennt das Transcript in `*.deleted.` um (gleicher Ordner). +- `cleanup: "delete"` archiviert unmittelbar nach der Ankündigung (bewahrt das Transcript weiterhin per Umbenennung auf). +- Automatische Archivierung erfolgt nach bestem Aufwand; ausstehende Timer gehen verloren, wenn der Gateway neu startet. +- `runTimeoutSeconds` archiviert **nicht** automatisch; es stoppt nur den Lauf. Die Sitzung bleibt bis zur automatischen Archivierung bestehen. - Automatische Archivierung gilt gleichermaßen für Sitzungen der Tiefe 1 und Tiefe 2. -- Browser-Bereinigung ist von Archivbereinigung getrennt: Verfolgte Browser-Tabs/-Prozesse werden bestmöglich geschlossen, wenn die Ausführung endet, auch wenn der Transkript-/Sitzungsdatensatz behalten wird. +- Browser-Bereinigung ist von Archivbereinigung getrennt: Nachverfolgte Browser-Tabs/-Prozesse werden nach bestem Aufwand geschlossen, wenn der Lauf endet, auch wenn der Transcript-/Sitzungsdatensatz erhalten bleibt. -## Verschachtelte Sub-Agenten +## Verschachtelte Sub-Agents -Standardmäßig können Sub-Agenten keine eigenen Sub-Agenten starten +Standardmäßig können Sub-Agents keine eigenen Sub-Agents spawnen (`maxSpawnDepth: 1`). Setzen Sie `maxSpawnDepth: 2`, um eine Ebene der -Verschachtelung zu aktivieren — das **Orchestrator-Muster**: Haupt → Orchestrator-Sub-Agent → -Worker-Sub-Sub-Agenten. +Verschachtelung zu aktivieren – das **Orchestrator-Muster**: Haupt-Agent → Orchestrator-Sub-Agent → +Worker-Sub-Sub-Agents. ```json5 { @@ -312,154 +311,154 @@ Worker-Sub-Sub-Agenten. ### Tiefenebenen -| Tiefe | Form des Sitzungsschlüssels | Rolle | Kann starten? | +| Tiefe | Form des Sitzungsschlüssels | Rolle | Kann spawnen? | | ----- | -------------------------------------------- | --------------------------------------------- | ---------------------------- | -| 0 | `agent::main` | Haupt-Agent | Immer | +| 0 | `agent::main` | Haupt-Agent | Immer | | 1 | `agent::subagent:` | Sub-Agent (Orchestrator, wenn Tiefe 2 erlaubt ist) | Nur wenn `maxSpawnDepth >= 2` | -| 2 | `agent::subagent::subagent:` | Sub-Sub-Agent (Leaf-Worker) | Nie | +| 2 | `agent::subagent::subagent:` | Sub-Sub-Agent (Leaf-Worker) | Nie | ### Ankündigungskette -Ergebnisse fließen entlang der Kette zurück: +Ergebnisse fließen die Kette zurück nach oben: -1. Worker der Tiefe 2 beendet → kündigt an seinen Parent an (Orchestrator der Tiefe 1). -2. Orchestrator der Tiefe 1 empfängt die Ankündigung, synthetisiert Ergebnisse, beendet → kündigt an Haupt an. +1. Worker der Tiefe 2 ist fertig → kündigt an seinen übergeordneten Agent an (Orchestrator der Tiefe 1). +2. Orchestrator der Tiefe 1 empfängt die Ankündigung, synthetisiert Ergebnisse, ist fertig → kündigt an den Haupt-Agent an. 3. Haupt-Agent empfängt die Ankündigung und liefert sie an den Benutzer. -Jede Ebene sieht nur Ankündigungen ihrer direkten Children. +Jede Ebene sieht nur Ankündigungen ihrer direkten untergeordneten Agents. -**Betriebliche Anleitung:** Starten Sie Child-Arbeit einmal und warten Sie auf Abschlussereignisse, -anstatt Polling-Schleifen um `sessions_list`, +**Betriebliche Leitlinien:** Starten Sie untergeordnete Arbeit einmalig und warten Sie auf Abschlussereignisse, +statt Poll-Schleifen um `sessions_list`, `sessions_history`, `/subagents list` oder `exec`-Sleep-Befehle zu bauen. -`sessions_list` und `/subagents list` halten Child-Sitzungsbeziehungen -auf Live-Arbeit fokussiert — Live-Children bleiben angehängt, beendete Children bleiben -für ein kurzes aktuelles Fenster sichtbar, und veraltete reine Store-Child-Links werden -nach ihrem Aktualitätsfenster ignoriert. Dadurch wird verhindert, dass alte `spawnedBy`-/ -`parentSessionKey`-Metadaten nach einem Neustart Ghost-Children wiederbeleben. -Wenn ein Child-Abschlussereignis eintrifft, nachdem Sie bereits die -finale Antwort gesendet haben, ist die korrekte Nachfolge der exakte stille Token +`sessions_list` und `/subagents list` halten Beziehungen zu untergeordneten Sitzungen +auf Live-Arbeit fokussiert – aktive untergeordnete Agents bleiben angehängt, beendete untergeordnete Agents bleiben +für ein kurzes aktuelles Zeitfenster sichtbar, und veraltete reine Store-Links zu untergeordneten Agents werden +nach ihrem Aktualitätsfenster ignoriert. Dadurch wird verhindert, dass alte `spawnedBy`- / +`parentSessionKey`-Metadaten nach einem Neustart Ghost-Children wiederherstellen. +Wenn ein Abschlussereignis eines untergeordneten Agents eintrifft, nachdem Sie bereits die +finale Antwort gesendet haben, ist die korrekte Folgeantwort das exakte stille Token `NO_REPLY` / `no_reply`. ### Tool-Richtlinie nach Tiefe -- Rolle und Kontrollumfang werden zum Spawn-Zeitpunkt in die Sitzungsmetadaten geschrieben. Dadurch wird verhindert, dass flache oder wiederhergestellte Sitzungsschlüssel versehentlich Orchestrator-Berechtigungen zurückerlangen. -- **Tiefe 1 (Orchestrator, wenn `maxSpawnDepth >= 2`):** erhält `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history`, damit er seine Children verwalten kann. Andere Sitzungs-/System-Tools bleiben verweigert. +- Rolle und Steuerungsumfang werden beim Spawn in die Sitzungsmetadaten geschrieben. Dadurch können flache oder wiederhergestellte Sitzungsschlüssel nicht versehentlich Orchestrator-Berechtigungen zurückerlangen. +- **Tiefe 1 (Orchestrator, wenn `maxSpawnDepth >= 2`):** erhält `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history`, damit er seine untergeordneten Agents verwalten kann. Andere Sitzungs-/System-Tools bleiben verweigert. - **Tiefe 1 (Leaf, wenn `maxSpawnDepth == 1`):** keine Sitzungs-Tools (aktuelles Standardverhalten). -- **Tiefe 2 (Leaf-Worker):** keine Sitzungs-Tools — `sessions_spawn` wird bei Tiefe 2 immer verweigert. Kann keine weiteren Children starten. +- **Tiefe 2 (Leaf-Worker):** keine Sitzungs-Tools – `sessions_spawn` wird in Tiefe 2 immer verweigert. Kann keine weiteren untergeordneten Agents spawnen. ### Spawn-Limit pro Agent -Jede Agent-Sitzung (in beliebiger Tiefe) kann höchstens `maxChildrenPerAgent` -(Standard `5`) aktive Children gleichzeitig haben. Das verhindert unkontrolliertes Fan-out +Jede Agent-Sitzung (in beliebiger Tiefe) kann gleichzeitig höchstens `maxChildrenPerAgent` +(Standard `5`) aktive untergeordnete Agents haben. Dies verhindert unkontrolliertes Fan-out durch einen einzelnen Orchestrator. -### Kaskadierendes Stoppen +### Kaskadierender Stopp -Das Stoppen eines Orchestrators der Tiefe 1 stoppt automatisch alle seine Children der Tiefe 2: +Das Stoppen eines Orchestrators der Tiefe 1 stoppt automatisch alle seine untergeordneten Agents der Tiefe 2: -- `/stop` im Haupt-Chat stoppt alle Agenten der Tiefe 1 und kaskadiert zu ihren Children der Tiefe 2. -- `/subagents kill ` stoppt einen bestimmten Sub-Agenten und kaskadiert zu seinen Children. -- `/subagents kill all` stoppt alle Sub-Agenten für den Anfragenden und kaskadiert. +- `/stop` im Hauptchat stoppt alle Agents der Tiefe 1 und kaskadiert zu deren untergeordneten Agents der Tiefe 2. +- `/subagents kill ` stoppt einen bestimmten Sub-Agent und kaskadiert zu seinen untergeordneten Agents. +- `/subagents kill all` stoppt alle Sub-Agents für den Anforderer und kaskadiert. ## Authentifizierung -Sub-Agent-Auth wird nach **Agent-ID** aufgelöst, nicht nach Sitzungstyp: +Sub-Agent-Authentifizierung wird nach **Agent-ID** aufgelöst, nicht nach Sitzungstyp: -- Der Sub-Agent-Sitzungsschlüssel ist `agent::subagent:`. -- Der Auth-Store wird aus dem `agentDir` dieses Agenten geladen. -- Die Auth-Profile des Haupt-Agenten werden als **Fallback** zusammengeführt; Agent-Profile überschreiben Hauptprofile bei Konflikten. +- Der Sitzungsschlüssel des Sub-Agents lautet `agent::subagent:`. +- Der Auth-Store wird aus dem `agentDir` dieses Agents geladen. +- Die Auth-Profile des Haupt-Agents werden als **Fallback** zusammengeführt; Agent-Profile überschreiben bei Konflikten Hauptprofile. -Die Zusammenführung ist additiv, sodass Hauptprofile immer als -Fallbacks verfügbar sind. Vollständig isolierte Auth pro Agent wird noch nicht unterstützt. +Die Zusammenführung ist additiv, daher sind Hauptprofile immer als +Fallbacks verfügbar. Vollständig isolierte Authentifizierung pro Agent wird noch nicht unterstützt. ## Ankündigung -Sub-Agenten melden über einen Ankündigungsschritt zurück: +Sub-Agents melden sich über einen Ankündigungsschritt zurück: -- Der Ankündigungsschritt läuft innerhalb der Sub-Agent-Sitzung (nicht der Sitzung des Anfragenden). +- Der Ankündigungsschritt wird innerhalb der Sub-Agent-Sitzung ausgeführt (nicht in der anfordernden Sitzung). - Wenn der Sub-Agent exakt `ANNOUNCE_SKIP` antwortet, wird nichts gepostet. -- Wenn der neueste Assistententext der exakte stille Token `NO_REPLY` / `no_reply` ist, wird die Ankündigungsausgabe unterdrückt, auch wenn zuvor sichtbarer Fortschritt vorhanden war. +- Wenn der neueste Assistant-Text das exakte stille Token `NO_REPLY` / `no_reply` ist, wird die Ankündigungsausgabe unterdrückt, selbst wenn zuvor sichtbarer Fortschritt vorhanden war. -Die Zustellung hängt von der Tiefe des Anfragenden ab: +Die Zustellung hängt von der Tiefe des Anforderers ab: -- Top-Level-Sitzungen des Anfragenden verwenden einen Follow-up-`agent`-Aufruf mit externer Zustellung (`deliver=true`). -- Verschachtelte anfragende Sub-Agent-Sitzungen erhalten eine interne Follow-up-Injektion (`deliver=false`), damit der Orchestrator Child-Ergebnisse innerhalb der Sitzung synthetisieren kann. -- Wenn eine verschachtelte anfragende Sub-Agent-Sitzung nicht mehr vorhanden ist, fällt OpenClaw auf den Anfragenden dieser Sitzung zurück, sofern verfügbar. +- Anfordernde Sitzungen auf oberster Ebene verwenden einen Folge-`agent`-Aufruf mit externer Zustellung (`deliver=true`). +- Verschachtelte anfordernde Subagent-Sitzungen erhalten eine interne Folgeinjektion (`deliver=false`), damit der Orchestrator untergeordnete Ergebnisse in der Sitzung synthetisieren kann. +- Wenn eine verschachtelte anfordernde Subagent-Sitzung nicht mehr vorhanden ist, fällt OpenClaw auf den Anforderer dieser Sitzung zurück, sofern verfügbar. -Für Top-Level-Sitzungen des Anfragenden löst die direkte Zustellung im Abschlussmodus zuerst -jede gebundene Konversations-/Thread-Route und jeden Hook-Override auf und füllt dann -fehlende Channel-Zielfelder aus der gespeicherten Route der Sitzung des Anfragenden. -So bleiben Abschlüsse im richtigen Chat/Thema, auch wenn der Abschlussursprung -nur den Channel identifiziert. +Für anfordernde Sitzungen auf oberster Ebene löst direkte Zustellung im Completion-Modus zuerst +jede gebundene Konversations-/Thread-Route und Hook-Überschreibung auf und füllt dann +fehlende Kanal-Zielfelder aus der gespeicherten Route der anfordernden Sitzung. +Dadurch bleiben Completions im richtigen Chat/Thema, selbst wenn der Completion-Ursprung +nur den Kanal identifiziert. -Die Child-Abschlussaggregation ist beim Erstellen verschachtelter Abschlussbefunde -auf die aktuelle Ausführung des Anfragenden begrenzt, wodurch verhindert wird, dass veraltete Child- -Ausgaben aus früheren Ausführungen in die aktuelle Ankündigung gelangen. Ankündigungsantworten behalten -Thread-/Themen-Routing bei, wenn es auf Channel-Adaptern verfügbar ist. +Die Aggregation von Abschlussmeldungen untergeordneter Agents ist beim Erstellen verschachtelter Completion-Befunde +auf den aktuellen Anforderer-Lauf begrenzt, wodurch verhindert wird, dass veraltete +Ausgaben untergeordneter Agents aus früheren Läufen in die aktuelle Ankündigung gelangen. Ankündigungsantworten bewahren +Thread-/Themen-Routing, sofern es auf Kanaladaptern verfügbar ist. ### Ankündigungskontext -Der Ankündigungskontext wird auf einen stabilen internen Ereignisblock normalisiert: +Der Ankündigungskontext wird zu einem stabilen internen Ereignisblock normalisiert: -| Feld | Quelle | +| Feld | Quelle | | -------------- | ------------------------------------------------------------------------------------------------------------- | | Quelle | `subagent` oder `cron` | -| Sitzungs-IDs | Child-Sitzungsschlüssel/-ID | -| Typ | Ankündigungstyp + Aufgabenlabel | -| Status | Aus Laufzeitergebnis abgeleitet (`success`, `error`, `timeout` oder `unknown`) — **nicht** aus Modelltext erschlossen | -| Ergebnisinhalt | Neuester sichtbarer Assistententext, andernfalls bereinigter neuester Tool-/toolResult-Text | -| Follow-up | Anweisung, die beschreibt, wann geantwortet bzw. still geblieben werden soll | +| Sitzungs-IDs | Sitzungsschlüssel/-ID des untergeordneten Agents | +| Typ | Ankündigungstyp + Aufgabenlabel | +| Status | Aus Runtime-Ergebnis abgeleitet (`success`, `error`, `timeout` oder `unknown`) – **nicht** aus Modelltext abgeleitet | +| Ergebnisinhalt | Neuester sichtbarer Assistant-Text, andernfalls bereinigter neuester Tool-/toolResult-Text | +| Follow-up | Anweisung, wann geantwortet bzw. still geblieben werden soll | -Terminal fehlgeschlagene Ausführungen melden den Fehlerstatus, ohne erfassten -Antworttext erneut abzuspielen. Bei Timeout kann die Ankündigung, wenn das Child nur bis zu Tool-Aufrufen gekommen ist, -diese Historie zu einer kurzen Teilfortschrittszusammenfassung zusammenfassen, anstatt rohe Tool-Ausgabe erneut abzuspielen. +Terminal fehlgeschlagene Läufe melden den Fehlerstatus, ohne erfassten +Antworttext erneut abzuspielen. Bei Timeout kann die Ankündigung, wenn der untergeordnete Agent nur Tool-Aufrufe durchlaufen hat, +diesen Verlauf zu einer kurzen Zusammenfassung des Teilfortschritts verdichten, +statt rohe Tool-Ausgabe erneut abzuspielen. ### Statistikzeile Ankündigungs-Payloads enthalten am Ende eine Statistikzeile (auch wenn umbrochen): -- Laufzeit (z. B. `runtime 5m12s`). -- Token-Nutzung (Eingabe/Ausgabe/Gesamt). +- Runtime (z. B. `runtime 5m12s`). +- Tokenverbrauch (Eingabe/Ausgabe/Gesamt). - Geschätzte Kosten, wenn Modellpreise konfiguriert sind (`models.providers.*.models[].cost`). -- `sessionKey`, `sessionId` und Transkriptpfad, damit der Haupt-Agent die Historie über `sessions_history` abrufen oder die Datei auf der Festplatte prüfen kann. +- `sessionKey`, `sessionId` und Transcript-Pfad, damit der Haupt-Agent den Verlauf über `sessions_history` abrufen oder die Datei auf der Festplatte prüfen kann. -Interne Metadaten sind nur für Orchestrierung gedacht; benutzerorientierte Antworten -sollten in normaler Assistentenstimme neu geschrieben werden. +Interne Metadaten sind nur für Orchestrierung gedacht; benutzerseitige Antworten +sollten in normaler Assistant-Stimme neu formuliert werden. ### Warum `sessions_history` bevorzugen `sessions_history` ist der sicherere Orchestrierungspfad: -- Assistenten-Recall wird zuerst normalisiert: Thinking-Tags entfernt; ``-/``-Gerüst entfernt; Klartext-Tool-Call-XML-Payload-Blöcke (``, ``, ``, ``) entfernt, einschließlich abgeschnittener Payloads, die nie sauber schließen; herabgestuftes Tool-Call-/Result-Gerüst und historische Kontextmarker entfernt; durchgesickerte Modell-Steuertoken (`<|assistant|>`, andere ASCII-`<|...|>`, vollbreite `<｜...｜>`) entfernt; fehlerhaftes MiniMax-Tool-Call-XML entfernt. -- Credential-/Token-ähnlicher Text wird redigiert. +- Assistant-Recall wird zuerst normalisiert: Thinking-Tags entfernt; ``- / ``-Gerüst entfernt; Klartext-Tool-Call-XML-Payload-Blöcke (``, ``, ``, ``) entfernt, einschließlich abgeschnittener Payloads, die nie sauber geschlossen werden; herabgestuftes Tool-Call-/Ergebnis-Gerüst und historische Kontextmarker entfernt; durchgesickerte Modellsteuerungs-Token (`<|assistant|>`, andere ASCII-`<|...|>`, vollbreite `<｜...｜>`) entfernt; fehlerhaftes MiniMax-Tool-Call-XML entfernt. +- Anmeldeinformations-/tokenähnlicher Text wird redigiert. - Lange Blöcke können gekürzt werden. -- Sehr große Historien können ältere Zeilen verwerfen oder eine übergroße Zeile durch `[sessions_history omitted: message too large]` ersetzen. -- Die Prüfung des rohen On-Disk-Transkripts ist der Fallback, wenn Sie das vollständige bytegenaue Transkript benötigen. +- Sehr große Verläufe können ältere Zeilen verwerfen oder eine übergroße Zeile durch `[sessions_history omitted: message too large]` ersetzen. +- Rohe Transcript-Inspektion auf der Festplatte ist der Fallback, wenn Sie das vollständige bytegenaue Transcript benötigen. ## Tool-Richtlinie -Sub-Agenten verwenden zuerst dieselbe Profil- und Tool-Policy-Pipeline wie der Parent- oder -Ziel-Agent. Danach wendet OpenClaw die Sub-Agent-Einschränkungs- -schicht an. +Sub-Agents verwenden zuerst dieselbe Profil- und Tool-Policy-Pipeline wie der übergeordnete oder +Ziel-Agent. Danach wendet OpenClaw die Einschränkungsebene für Sub-Agents an. -Ohne einschränkendes `tools.profile` erhalten Sub-Agenten **alle Tools außer -Sitzungs-Tools** und System-Tools: +Ohne einschränkendes `tools.profile` erhalten Sub-Agents **alle Tools außer +Session-Tools** und System-Tools: - `sessions_list` - `sessions_history` - `sessions_send` - `sessions_spawn` -`sessions_history` bleibt auch hier eine begrenzte, bereinigte Recall-Ansicht — es -ist kein roher Transkript-Dump. +`sessions_history` bleibt auch hier eine begrenzte, bereinigte Erinnerungsansicht — +es ist kein roher Transcript-Dump. -Wenn `maxSpawnDepth >= 2`, erhalten Orchestrator-Sub-Agenten der Tiefe 1 zusätzlich +Wenn `maxSpawnDepth >= 2` ist, erhalten Orchestrator-Sub-Agents auf Tiefe 1 zusätzlich `sessions_spawn`, `subagents`, `sessions_list` und -`sessions_history`, damit sie ihre Children verwalten können. +`sessions_history`, damit sie ihre untergeordneten Agents verwalten können. -### Override über Konfiguration +### Per Konfiguration überschreiben ```json5 { @@ -483,7 +482,12 @@ Wenn `maxSpawnDepth >= 2`, erhalten Orchestrator-Sub-Agenten der Tiefe 1 zusätz } ``` -`tools.subagents.tools.allow` ist ein abschließender Allow-Only-Filter. Er kann den bereits aufgelösten Tool-Satz einschränken, aber kein Tool **wieder hinzufügen**, das durch `tools.profile` entfernt wurde. Beispielsweise enthält `tools.profile: "coding"` `web_search`/`web_fetch`, aber nicht das Tool `browser`. Damit Unteragenten mit Coding-Profil Browser-Automatisierung verwenden können, fügen Sie browser in der Profilphase hinzu: +`tools.subagents.tools.allow` ist ein finaler Allow-only-Filter. Er kann +die bereits aufgelöste Tool-Menge einschränken, aber kein Tool **wieder hinzufügen**, +das durch `tools.profile` entfernt wurde. Zum Beispiel enthält `tools.profile: "coding"` +`web_search`/`web_fetch`, aber nicht das `browser`-Tool. Damit +Sub-Agents mit Coding-Profil Browser-Automation verwenden können, fügen Sie Browser auf +der Profilebene hinzu: ```json5 { @@ -494,44 +498,65 @@ Wenn `maxSpawnDepth >= 2`, erhalten Orchestrator-Sub-Agenten der Tiefe 1 zusätz } ``` -Verwenden Sie `agents.list[].tools.alsoAllow: ["browser"]` pro Agent, wenn nur ein Agent Browser-Automatisierung erhalten soll. +Verwenden Sie pro Agent `agents.list[].tools.alsoAllow: ["browser"]`, wenn nur ein +Agent Browser-Automation erhalten soll. -## Nebenläufigkeit +## Parallelität -Unteragenten verwenden eine dedizierte In-Process-Warteschlangen-Lane: +Sub-Agents verwenden eine eigene In-Process-Warteschlangen-Lane: - **Lane-Name:** `subagent` -- **Nebenläufigkeit:** `agents.defaults.subagents.maxConcurrent` (Standard `8`) +- **Parallelität:** `agents.defaults.subagents.maxConcurrent` (Standard `8`) ## Liveness und Wiederherstellung -OpenClaw behandelt das Fehlen von `endedAt` nicht als dauerhaften Nachweis dafür, dass ein Unteragent noch aktiv ist. Nicht beendete Läufe, die älter als das Zeitfenster für veraltete Läufe sind, zählen in `/subagents list`, Statuszusammenfassungen, Abschluss-Gating für Nachkommen und sitzungsbezogenen Nebenläufigkeitsprüfungen nicht mehr als aktiv/ausstehend. +OpenClaw behandelt das Fehlen von `endedAt` nicht als dauerhaften Nachweis, dass ein +Sub-Agent noch aktiv ist. Nicht beendete Ausführungen, die älter als das Stale-Run-Fenster sind, +zählen in `/subagents list`, Statuszusammenfassungen, +Abschluss-Gating für Nachkommen und Parallelitätsprüfungen pro Session nicht mehr als aktiv/ausstehend. -Nach einem Gateway-Neustart werden veraltete, nicht beendete wiederhergestellte Läufe bereinigt, sofern ihre untergeordnete Sitzung nicht als `abortedLastRun: true` markiert ist. Diese durch den Neustart abgebrochenen untergeordneten Sitzungen bleiben über den Orphan-Wiederherstellungsfluss für Unteragenten wiederherstellbar, der eine synthetische Resume-Nachricht sendet, bevor die Abbruchmarkierung gelöscht wird. +Nach einem Gateway-Neustart werden veraltete, nicht beendete wiederhergestellte Ausführungen entfernt, sofern +ihre Child-Session nicht als `abortedLastRun: true` markiert ist. Diese +durch Neustart abgebrochenen Child-Sessions bleiben über den Wiederherstellungsablauf für verwaiste Sub-Agents +wiederherstellbar; dabei wird eine synthetische Resume-Nachricht gesendet, bevor +die Abbruchmarkierung gelöscht wird. -Die automatische Neustartwiederherstellung ist pro untergeordneter Sitzung begrenzt. Wenn derselbe untergeordnete Unteragent innerhalb des schnellen Re-Wedge-Zeitfensters wiederholt für die Orphan-Wiederherstellung akzeptiert wird, speichert OpenClaw einen Wiederherstellungs-Tombstone für diese Sitzung und nimmt sie bei späteren Neustarts nicht mehr automatisch wieder auf. Führen Sie `openclaw tasks maintenance --apply` aus, um den Task-Datensatz abzugleichen, oder `openclaw doctor --fix`, um veraltete abgebrochene Wiederherstellungs-Flags auf Tombstone-Sitzungen zu löschen. +Die automatische Neustart-Wiederherstellung ist pro Child-Session begrenzt. Wenn derselbe +Sub-Agent-Child innerhalb des schnellen Re-Wedge-Fensters wiederholt zur Wiederherstellung verwaister Sessions +angenommen wird, persistiert OpenClaw einen Wiederherstellungs-Tombstone auf dieser +Session und nimmt die automatische Wiederaufnahme bei späteren Neustarts nicht mehr vor. Führen Sie +`openclaw tasks maintenance --apply` aus, um den Task-Datensatz abzugleichen, oder +`openclaw doctor --fix`, um veraltete abgebrochene Wiederherstellungs-Flags auf +Sessions mit Tombstone zu löschen. -Wenn das Starten eines Unteragenten mit Gateway `PAIRING_REQUIRED` / `scope-upgrade` fehlschlägt, prüfen Sie den RPC-Aufrufer, bevor Sie den Pairing-Status bearbeiten. Interne `sessions_spawn`-Koordination sollte sich als `client.id: "gateway-client"` mit `client.mode: "backend"` über direkte loopback-Authentifizierung mit gemeinsamem Token/Passwort verbinden; dieser Pfad hängt nicht von der Scope-Baseline der gekoppelten Geräte der CLI ab. Remote-Aufrufer, explizite `deviceIdentity`, explizite Gerätetoken-Pfade und Browser-/Node-Clients benötigen weiterhin die normale Gerätegenehmigung für Scope-Upgrades. +Wenn das Starten eines Sub-Agents mit Gateway `PAIRING_REQUIRED` / +`scope-upgrade` fehlschlägt, prüfen Sie den RPC-Aufrufer, bevor Sie den Pairing-Zustand bearbeiten. +Interne `sessions_spawn`-Koordination sollte als +`client.id: "gateway-client"` mit `client.mode: "backend"` über direkte +local loopback Shared-Token-/Passwort-Authentifizierung verbinden; dieser Pfad hängt nicht von der +Scope-Baseline gekoppelter Geräte der CLI ab. Remote-Aufrufer, explizite +`deviceIdentity`, explizite Gerätetoken-Pfade und Browser-/Node-Clients +benötigen weiterhin die normale Gerätefreigabe für Scope-Upgrades. ## Stoppen -- Das Senden von `/stop` im Anforderer-Chat bricht die Anforderer-Sitzung ab und stoppt alle aktiven Unteragenten-Läufe, die von ihr gestartet wurden, kaskadierend bis zu verschachtelten untergeordneten Läufen. -- `/subagents kill ` stoppt einen bestimmten Unteragenten und kaskadiert zu seinen untergeordneten Läufen. +- Das Senden von `/stop` im Requester-Chat bricht die Requester-Session ab und stoppt alle daraus gestarteten aktiven Sub-Agent-Ausführungen, kaskadierend bis zu verschachtelten Child-Agents. +- `/subagents kill ` stoppt einen bestimmten Sub-Agent und kaskadiert zu seinen Child-Agents. ## Einschränkungen -- Die Ankündigung von Unteragenten erfolgt **nach bestem Bemühen**. Wenn der Gateway neu startet, geht ausstehende „announce back“-Arbeit verloren. -- Unteragenten teilen sich weiterhin dieselben Ressourcen des Gateway-Prozesses; betrachten Sie `maxConcurrent` als Sicherheitsventil. +- Die Ankündigung von Sub-Agents erfolgt **nach bestem Aufwand**. Wenn der Gateway neu startet, geht ausstehende „Zurückankündigen“-Arbeit verloren. +- Sub-Agents teilen sich weiterhin dieselben Ressourcen des Gateway-Prozesses; behandeln Sie `maxConcurrent` als Sicherheitsventil. - `sessions_spawn` ist immer nicht blockierend: Es gibt sofort `{ status: "accepted", runId, childSessionKey }` zurück. -- Der Kontext von Unteragenten injiziert nur `AGENTS.md` + `TOOLS.md` (kein `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` oder `BOOTSTRAP.md`). +- Sub-Agent-Kontext injiziert nur `AGENTS.md` + `TOOLS.md` (kein `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` oder `BOOTSTRAP.md`). - Die maximale Verschachtelungstiefe beträgt 5 (`maxSpawnDepth`-Bereich: 1–5). Tiefe 2 wird für die meisten Anwendungsfälle empfohlen. -- `maxChildrenPerAgent` begrenzt aktive untergeordnete Läufe pro Sitzung (Standard `5`, Bereich `1–20`). +- `maxChildrenPerAgent` begrenzt aktive Child-Agents pro Session (Standard `5`, Bereich `1–20`). ## Verwandte Themen -- [ACP-Agenten](/de/tools/acp-agents) +- [ACP-Agents](/de/tools/acp-agents) - [Agent senden](/de/tools/agent-send) -- [Hintergrundtasks](/de/automation/tasks) +- [Hintergrund-Tasks](/de/automation/tasks) - [Multi-Agent-Sandbox-Tools](/de/tools/multi-agent-sandbox-tools) diff --git a/docs/de/web/control-ui.md b/docs/de/web/control-ui.md index fec3cf9c4..afe493951 100644 --- a/docs/de/web/control-ui.md +++ b/docs/de/web/control-ui.md @@ -3,21 +3,21 @@ read_when: - Sie möchten das Gateway über einen Browser bedienen - Sie möchten Tailnet-Zugriff ohne SSH-Tunnel sidebarTitle: Control UI -summary: Browserbasierte Steuerungs-UI für das Gateway (Chat, Knoten, Konfiguration) +summary: Browserbasierte Steuerungs-UI für den Gateway (Chat, Nodes, Konfiguration) title: Steuerungsoberfläche x-i18n: - generated_at: "2026-05-04T02:26:48Z" + generated_at: "2026-05-04T06:44:37Z" model: gpt-5.5 provider: openai - source_hash: c890d83da2c296b600e4b5a00a538f37e6bd54da31fbe62113ecd6177b15626e + source_hash: 07fbbe1c7fec5f67a04a231e02bdf0f7d16be9c5fe188915674d71fcd69002a5 source_path: web/control-ui.md workflow: 16 --- -Die Steuerungs-UI ist eine kleine **Vite + Lit**-Single-Page-App, die vom Gateway bereitgestellt wird: +The Control UI ist eine kleine **Vite + Lit**-Single-Page-App, die vom Gateway bereitgestellt wird: - Standard: `http://:18789/` -- optionales Präfix: `gateway.controlUi.basePath` setzen (z. B. `/openclaw`) +- optionales Präfix: `gateway.controlUi.basePath` festlegen (z. B. `/openclaw`) Sie kommuniziert **direkt mit dem Gateway WebSocket** auf demselben Port. @@ -33,16 +33,16 @@ Die Authentifizierung wird während des WebSocket-Handshakes bereitgestellt übe - `connect.params.auth.token` - `connect.params.auth.password` -- Tailscale Serve-Identitäts-Header, wenn `gateway.auth.allowTailscale: true` -- Trusted-Proxy-Identitäts-Header, wenn `gateway.auth.mode: "trusted-proxy"` +- Tailscale Serve-Identitätsheader, wenn `gateway.auth.allowTailscale: true` +- Trusted-Proxy-Identitätsheader, wenn `gateway.auth.mode: "trusted-proxy"` -Das Einstellungsfeld des Dashboards speichert ein Token für die aktuelle Browser-Tab-Sitzung und die ausgewählte Gateway-URL; Passwörter werden nicht dauerhaft gespeichert. Das Onboarding erzeugt normalerweise beim ersten Verbindungsaufbau ein Gateway-Token für Shared-Secret-Authentifizierung, aber Passwortauthentifizierung funktioniert ebenfalls, wenn `gateway.auth.mode` `"password"` ist. +Das Einstellungspanel des Dashboards speichert ein Token für die aktuelle Browser-Tab-Sitzung und die ausgewählte Gateway-URL; Passwörter werden nicht persistiert. Das Onboarding erzeugt normalerweise beim ersten Verbindungsaufbau ein Gateway-Token für die Shared-Secret-Authentifizierung, aber Passwortauthentifizierung funktioniert ebenfalls, wenn `gateway.auth.mode` `"password"` ist. ## Gerätekopplung (erste Verbindung) -Wenn Sie sich von einem neuen Browser oder Gerät aus mit der Steuerungs-UI verbinden, verlangt das Gateway normalerweise eine **einmalige Kopplungsgenehmigung**. Dies ist eine Sicherheitsmaßnahme, um unbefugten Zugriff zu verhindern. +Wenn Sie sich von einem neuen Browser oder Gerät mit der Control UI verbinden, verlangt das Gateway normalerweise eine **einmalige Kopplungsgenehmigung**. Dies ist eine Sicherheitsmaßnahme, um unbefugten Zugriff zu verhindern. -**Was Sie sehen werden:** „disconnected (1008): pairing required“ +**Was Sie sehen:** „disconnected (1008): pairing required“ @@ -50,103 +50,103 @@ Wenn Sie sich von einem neuen Browser oder Gerät aus mit der Steuerungs-UI verb openclaw devices list ``` - + ```bash openclaw devices approve ``` -Wenn der Browser die Kopplung mit geänderten Authentifizierungsdetails (Rolle/Berechtigungsumfänge/öffentlicher Schlüssel) erneut versucht, wird die vorherige ausstehende Anfrage ersetzt und eine neue `requestId` erstellt. Führen Sie vor der Genehmigung erneut `openclaw devices list` aus. +Wenn der Browser die Kopplung mit geänderten Authentifizierungsdetails (Rolle/Scopes/öffentlicher Schlüssel) erneut versucht, wird die vorherige ausstehende Anfrage ersetzt und eine neue `requestId` erstellt. Führen Sie vor der Genehmigung erneut `openclaw devices list` aus. -Wenn der Browser bereits gekoppelt ist und Sie ihn von Lesezugriff auf Schreib-/Adminzugriff ändern, wird dies als Genehmigungs-Upgrade behandelt, nicht als stiller Wiederverbindungsaufbau. OpenClaw lässt die alte Genehmigung aktiv, blockiert die Wiederverbindung mit erweitertem Umfang und fordert Sie auf, den neuen Berechtigungsumfang ausdrücklich zu genehmigen. +Wenn der Browser bereits gekoppelt ist und Sie ihn von Lesezugriff auf Schreib-/Adminzugriff ändern, wird dies als Genehmigungsupgrade behandelt, nicht als stiller erneuter Verbindungsaufbau. OpenClaw hält die alte Genehmigung aktiv, blockiert die umfassendere erneute Verbindung und fordert Sie auf, den neuen Scope-Satz ausdrücklich zu genehmigen. -Nach der Genehmigung wird das Gerät gespeichert und muss nicht erneut genehmigt werden, es sei denn, Sie widerrufen es mit `openclaw devices revoke --device --role `. Siehe [Geräte-CLI](/de/cli/devices) für Token-Rotation und Widerruf. +Nach der Genehmigung wird das Gerät gespeichert und erfordert keine erneute Genehmigung, es sei denn, Sie widerrufen es mit `openclaw devices revoke --device --role `. Siehe [Devices CLI](/de/cli/devices) für Token-Rotation und Widerruf. - Direkte local loopback-Browserverbindungen (`127.0.0.1` / `localhost`) werden automatisch genehmigt. -- Tailscale Serve kann den Kopplungsdurchlauf für Operator-Sitzungen der Steuerungs-UI überspringen, wenn `gateway.auth.allowTailscale: true` gesetzt ist, die Tailscale-Identität verifiziert wird und der Browser seine Geräteidentität übermittelt. -- Direkte Tailnet-Bindungen, LAN-Browserverbindungen und Browserprofile ohne Geräteidentität erfordern weiterhin eine ausdrückliche Genehmigung. -- Jedes Browserprofil erzeugt eine eindeutige Geräte-ID; ein Browserwechsel oder das Löschen von Browserdaten erfordert daher eine erneute Kopplung. +- Tailscale Serve kann den Kopplungs-Roundtrip für Control-UI-Operatorsitzungen überspringen, wenn `gateway.auth.allowTailscale: true` gilt, die Tailscale-Identität verifiziert wird und der Browser seine Geräteidentität vorlegt. +- Direkte Tailnet-Bindings, LAN-Browserverbindungen und Browserprofile ohne Geräteidentität erfordern weiterhin eine ausdrückliche Genehmigung. +- Jedes Browserprofil erzeugt eine eindeutige Geräte-ID, daher erfordert ein Browserwechsel oder das Löschen von Browserdaten eine erneute Kopplung. ## Persönliche Identität (browserlokal) -Die Steuerungs-UI unterstützt eine persönliche Identität pro Browser (Anzeigename und Avatar), die ausgehenden Nachrichten zur Zuordnung in gemeinsamen Sitzungen angehängt wird. Sie wird im Browserspeicher abgelegt, ist auf das aktuelle Browserprofil beschränkt und wird weder mit anderen Geräten synchronisiert noch serverseitig dauerhaft gespeichert, abgesehen von den normalen Autorenschaftsmetadaten im Transkript für Nachrichten, die Sie tatsächlich senden. Das Löschen von Websitedaten oder ein Browserwechsel setzt sie auf leer zurück. +Die Control UI unterstützt eine persönliche Identität pro Browser (Anzeigename und Avatar), die ausgehenden Nachrichten zur Zuordnung in gemeinsam genutzten Sitzungen angehängt wird. Sie liegt im Browserspeicher, ist auf das aktuelle Browserprofil beschränkt und wird weder mit anderen Geräten synchronisiert noch serverseitig über die normalen Autorenschaftsmetadaten des Transkripts für Nachrichten hinaus persistiert, die Sie tatsächlich senden. Das Löschen von Websitedaten oder ein Browserwechsel setzt sie auf leer zurück. -Dasselbe browserlokale Muster gilt für die Überschreibung des Assistenten-Avatars. Hochgeladene Assistenten-Avatare überlagern die vom Gateway aufgelöste Identität nur im lokalen Browser und werden nie über `config.patch` übertragen. Das gemeinsame Konfigurationsfeld `ui.assistant.avatar` bleibt für Nicht-UI-Clients verfügbar, die das Feld direkt schreiben (z. B. skriptgesteuerte Gateways oder benutzerdefinierte Dashboards). +Dasselbe browserlokale Muster gilt für die Avatar-Überschreibung des Assistenten. Hochgeladene Assistenten-Avatare überlagern die vom Gateway aufgelöste Identität nur im lokalen Browser und durchlaufen niemals `config.patch`. Das gemeinsame Konfigurationsfeld `ui.assistant.avatar` bleibt für Nicht-UI-Clients verfügbar, die das Feld direkt schreiben (z. B. skriptgesteuerte Gateways oder benutzerdefinierte Dashboards). ## Laufzeit-Konfigurationsendpunkt -Die Steuerungs-UI ruft ihre Laufzeiteinstellungen von `/__openclaw/control-ui-config.json` ab. Dieser Endpunkt wird durch dieselbe Gateway-Authentifizierung geschützt wie der übrige HTTP-Bereich: Nicht authentifizierte Browser können ihn nicht abrufen, und ein erfolgreicher Abruf erfordert entweder ein bereits gültiges Gateway-Token/Passwort, eine Tailscale Serve-Identität oder eine Trusted-Proxy-Identität. +Die Control UI ruft ihre Laufzeiteinstellungen von `/__openclaw/control-ui-config.json` ab. Dieser Endpunkt ist durch dieselbe Gateway-Authentifizierung geschützt wie der restliche HTTP-Bereich: Nicht authentifizierte Browser können ihn nicht abrufen, und ein erfolgreicher Abruf erfordert entweder ein bereits gültiges Gateway-Token/-Passwort, eine Tailscale Serve-Identität oder eine Trusted-Proxy-Identität. ## Sprachunterstützung -Die Steuerungs-UI kann sich beim ersten Laden anhand Ihrer Browser-Locale lokalisieren. Um dies später zu überschreiben, öffnen Sie **Übersicht -> Gateway-Zugriff -> Sprache**. Die Locale-Auswahl befindet sich in der Gateway-Zugriff-Karte, nicht unter Erscheinungsbild. +Die Control UI kann sich beim ersten Laden anhand Ihrer Browser-Locale lokalisieren. Um dies später zu überschreiben, öffnen Sie **Übersicht -> Gateway-Zugriff -> Sprache**. Die Locale-Auswahl befindet sich in der Gateway-Zugriff-Karte, nicht unter Darstellung. - Unterstützte Locales: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa` -- Nicht englische Übersetzungen werden im Browser nach Bedarf geladen. +- Nicht-englische Übersetzungen werden im Browser lazy-loaded. - Die ausgewählte Locale wird im Browserspeicher gespeichert und bei zukünftigen Besuchen wiederverwendet. - Fehlende Übersetzungsschlüssel fallen auf Englisch zurück. -Dokumentationsübersetzungen werden für denselben nicht englischen Locale-Satz erzeugt, aber die integrierte Mintlify-Sprachauswahl der Dokumentationswebsite ist auf die Locale-Codes beschränkt, die Mintlify akzeptiert. Thailändische (`th`) und persische (`fa`) Dokumentation wird weiterhin im Veröffentlichungs-Repo erzeugt; sie erscheint möglicherweise erst in dieser Auswahl, wenn Mintlify diese Codes unterstützt. +Dokumentationsübersetzungen werden für denselben nicht-englischen Locale-Satz generiert, aber die integrierte Mintlify-Sprachauswahl der Dokumentationswebsite ist auf die Locale-Codes beschränkt, die Mintlify akzeptiert. Thailändische (`th`) und persische (`fa`) Dokumentation wird weiterhin im Publish-Repo generiert; sie erscheint möglicherweise erst in dieser Auswahl, wenn Mintlify diese Codes unterstützt. ## Darstellungsthemes -Das Erscheinungsbild-Panel behält die integrierten Themes Claw, Knot und Dash sowie einen browserlokalen tweakcn-Importplatz. Um ein Theme zu importieren, öffnen Sie [tweakcn-Themes](https://tweakcn.com/themes), wählen oder erstellen Sie ein Theme, klicken Sie auf **Teilen** und fügen Sie den kopierten Theme-Link in Erscheinungsbild ein. Der Importer akzeptiert außerdem `https://tweakcn.com/r/themes/`-Registry-URLs, Editor-URLs wie `https://tweakcn.com/editor/theme?theme=amethyst-haze`, relative `/themes/`-Pfade, rohe Theme-IDs und Standard-Theme-Namen wie `amethyst-haze`. +Das Darstellungspanel enthält die integrierten Themes Claw, Knot und Dash sowie einen browserlokalen tweakcn-Importslot. Um ein Theme zu importieren, öffnen Sie den [tweakcn editor](https://tweakcn.com/editor/theme), wählen oder erstellen Sie ein Theme, klicken Sie auf **Teilen** und fügen Sie den kopierten Theme-Link in Darstellung ein. Der Importer akzeptiert außerdem `https://tweakcn.com/r/themes/`-Registry-URLs, Editor-URLs wie `https://tweakcn.com/editor/theme?theme=amethyst-haze`, relative `/themes/`-Pfade, rohe Theme-IDs und Standard-Theme-Namen wie `amethyst-haze`. -Importierte Themes werden nur im aktuellen Browserprofil gespeichert. Sie werden nicht in die Gateway-Konfiguration geschrieben und nicht geräteübergreifend synchronisiert. Das Ersetzen des importierten Themes aktualisiert den einen lokalen Platz; das Löschen schaltet das aktive Theme zurück auf Claw, wenn das importierte Theme ausgewählt war. +Importierte Themes werden nur im aktuellen Browserprofil gespeichert. Sie werden nicht in die Gateway-Konfiguration geschrieben und nicht zwischen Geräten synchronisiert. Das Ersetzen des importierten Themes aktualisiert den einen lokalen Slot; das Löschen wechselt das aktive Theme zurück zu Claw, wenn das importierte Theme ausgewählt war. ## Was sie kann (heute) - + - Chatten Sie mit dem Modell über Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`). - - Sprechen Sie über Browser-Echtzeitsitzungen. OpenAI verwendet direktes WebRTC, Google Live verwendet ein eingeschränktes einmaliges Browser-Token über WebSocket, und reine Backend-Echtzeit-Sprach-Plugins verwenden den Gateway-Relay-Transport. Das Relay hält Provider-Anmeldedaten auf dem Gateway, während der Browser Mikrofon-PCM über `talk.realtime.relay*`-RPCs streamt und `openclaw_agent_consult`-Toolaufrufe über `chat.send` an das größere konfigurierte OpenClaw-Modell zurücksendet. - - Streamen Sie Toolaufrufe und Live-Toolausgabe-Karten im Chat (Agent-Ereignisse). + - Sprechen Sie über Browser-Echtzeitsitzungen. OpenAI verwendet direktes WebRTC, Google Live verwendet ein eingeschränktes einmalig nutzbares Browser-Token über WebSocket, und rein backendseitige Echtzeit-Sprach-Plugins verwenden den Gateway-Relay-Transport. Das Relay hält Provider-Anmeldedaten auf dem Gateway, während der Browser Mikrofon-PCM über `talk.realtime.relay*`-RPCs streamt und `openclaw_agent_consult`-Toolaufrufe über `chat.send` für das größere konfigurierte OpenClaw-Modell zurücksendet. + - Streamen Sie Toolaufrufe und Live-Tool-Ausgabekarten im Chat (Agentenereignisse). - + - Kanäle: Status integrierter sowie gebündelter/externer Plugin-Kanäle, QR-Anmeldung und kanalbezogene Konfiguration (`channels.status`, `web.login.*`, `config.patch`). - Instanzen: Präsenzliste und Aktualisierung (`system-presence`). - - Sitzungen: Liste und sitzungsbezogene Überschreibungen für Modell/Denken/schnell/ausführlich/Trace/Reasoning (`sessions.list`, `sessions.patch`). - - Träume: Dreaming-Status, Aktivieren/Deaktivieren-Schalter und Dream-Diary-Reader (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`). + - Sitzungen: Liste und sitzungsbezogene Überschreibungen für Modell/Thinking/Fast/Verbose/Trace/Reasoning (`sessions.list`, `sessions.patch`). + - Dreams: Dreaming-Status, Aktivieren-/Deaktivieren-Schalter und Dream-Diary-Leser (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`). - - Cron-Jobs: auflisten/hinzufügen/bearbeiten/ausführen/aktivieren/deaktivieren und Ausführungsverlauf (`cron.*`). - - Skills: Status, aktivieren/deaktivieren, installieren, API-Schlüssel aktualisieren (`skills.*`). - - Nodes: Liste und Fähigkeiten (`node.list`). - - Exec-Genehmigungen: Gateway- oder Node-Zulassungslisten und Abfragerichtlinie für `exec host=gateway/node` bearbeiten (`exec.approvals.*`). + - Cron-Jobs: Auflisten/Hinzufügen/Bearbeiten/Ausführen/Aktivieren/Deaktivieren und Ausführungshistorie (`cron.*`). + - Skills: Status, Aktivieren/Deaktivieren, Installieren, API-Schlüsselaktualisierungen (`skills.*`). + - Nodes: Liste und Caps (`node.list`). + - Exec-Genehmigungen: Gateway- oder Node-Allowlists und Ask-Policy für `exec host=gateway/node` bearbeiten (`exec.approvals.*`). - `~/.openclaw/openclaw.json` anzeigen/bearbeiten (`config.get`, `config.set`). - - Mit Validierung anwenden und neu starten (`config.apply`) sowie die zuletzt aktive Sitzung aufwecken. - - Schreibvorgänge enthalten einen Basis-Hash-Schutz, um das Überschreiben paralleler Änderungen zu verhindern. - - Schreibvorgänge (`config.set`/`config.apply`/`config.patch`) prüfen die Auflösung aktiver SecretRefs für Referenzen in der übermittelten Konfigurationsnutzlast vorab; nicht auflösbare aktive übermittelte Referenzen werden vor dem Schreiben abgelehnt. - - Schema und Formular-Rendering (`config.schema` / `config.schema.lookup`, einschließlich Feld `title` / `description`, passender UI-Hinweise, Zusammenfassungen direkter Kindelemente, Dokumentationsmetadaten auf verschachtelten Objekt-/Wildcard-/Array-/Kompositionsknoten sowie Plugin- und Kanal-Schemas, sofern verfügbar); der Raw-JSON-Editor ist nur verfügbar, wenn der Snapshot einen sicheren Raw-Roundtrip unterstützt. - - Wenn ein Snapshot Raw-Text nicht sicher per Roundtrip verarbeiten kann, erzwingt die Steuerungs-UI den Formularmodus und deaktiviert den Raw-Modus für diesen Snapshot. - - „Auf gespeicherten Stand zurücksetzen“ im Raw-JSON-Editor bewahrt die roh verfasste Form (Formatierung, Kommentare, `$include`-Layout), statt einen abgeflachten Snapshot neu zu rendern, sodass externe Änderungen einen Reset überstehen, wenn der Snapshot sicher per Roundtrip verarbeitet werden kann. - - Strukturierte SecretRef-Objektwerte werden in Formulartexteingaben schreibgeschützt gerendert, um versehentliche Beschädigung durch Umwandlung von Objekt zu String zu verhindern. + - Anwenden und mit Validierung neu starten (`config.apply`) sowie die zuletzt aktive Sitzung aufwecken. + - Schreibvorgänge enthalten einen Base-Hash-Schutz, um das Überschreiben gleichzeitiger Bearbeitungen zu verhindern. + - Schreibvorgänge (`config.set`/`config.apply`/`config.patch`) prüfen vorab die aktive SecretRef-Auflösung für Refs in der übermittelten Konfigurations-Payload; nicht auflösbare aktive übermittelte Refs werden vor dem Schreiben abgelehnt. + - Schema- und Formular-Rendering (`config.schema` / `config.schema.lookup`, einschließlich Feld-`title` / `description`, passender UI-Hinweise, unmittelbarer Kindzusammenfassungen, Dokumentationsmetadaten auf verschachtelten Objekt-/Wildcard-/Array-/Kompositions-Nodes sowie Plugin- und Kanalschemas, sofern verfügbar); der Raw-JSON-Editor ist nur verfügbar, wenn der Snapshot einen sicheren Raw-Roundtrip besitzt. + - Wenn ein Snapshot Raw-Text nicht sicher per Roundtrip verarbeiten kann, erzwingt die Control UI den Formularmodus und deaktiviert den Raw-Modus für diesen Snapshot. + - „Reset to saved“ im Raw-JSON-Editor bewahrt die raw-verfasste Form (Formatierung, Kommentare, `$include`-Layout), anstatt einen abgeflachten Snapshot neu zu rendern, sodass externe Bearbeitungen einen Reset überstehen, wenn der Snapshot sicher per Roundtrip verarbeitet werden kann. + - Strukturierte SecretRef-Objektwerte werden in Formular-Texteingaben schreibgeschützt gerendert, um versehentliche Objekt-zu-String-Beschädigung zu verhindern. - - - Debugging: Status-/Health-/Modell-Snapshots, Ereignislog und manuelle RPC-Aufrufe (`status`, `health`, `models.list`). + + - Debug: Status-/Health-/Modell-Snapshots, Ereignislog und manuelle RPC-Aufrufe (`status`, `health`, `models.list`). - Logs: Live-Tail der Gateway-Dateilogs mit Filter/Export (`logs.tail`). - - Update: Paket-/Git-Update und Neustart ausführen (`update.run`) mit Neustartbericht, anschließend nach der Wiederverbindung `update.status` abfragen, um die laufende Gateway-Version zu verifizieren. + - Update: Paket-/Git-Update ausführen und neu starten (`update.run`) mit einem Neustartbericht; anschließend nach der erneuten Verbindung `update.status` pollen, um die laufende Gateway-Version zu verifizieren. - - Für isolierte Jobs ist die Auslieferung standardmäßig auf Zusammenfassung ankündigen gesetzt. Sie können auf keine umschalten, wenn Sie nur interne Ausführungen wünschen. - - Kanal-/Zielfelder erscheinen, wenn ankündigen ausgewählt ist. + - Für isolierte Jobs ist die Zustellung standardmäßig auf Zusammenfassung ankündigen gesetzt. Sie können auf keine umschalten, wenn Sie rein interne Ausführungen möchten. + - Kanal-/Zielfelder erscheinen, wenn Ankündigen ausgewählt ist. - Der Webhook-Modus verwendet `delivery.mode = "webhook"` mit `delivery.to`, das auf eine gültige HTTP(S)-Webhook-URL gesetzt ist. - - Für Hauptsitzungs-Jobs sind die Auslieferungsmodi Webhook und keine verfügbar. - - Erweiterte Bearbeitungssteuerelemente umfassen Nach-Ausführung-löschen, Agent-Überschreibung löschen, Cron-Optionen für exakt/gestaffelt, Agent-Modell-/Thinking-Überschreibungen und Best-Effort-Auslieferungsschalter. - - Die Formularvalidierung erfolgt inline mit feldbezogenen Fehlern; ungültige Werte deaktivieren die Speichern-Schaltfläche, bis sie korrigiert wurden. - - Setzen Sie `cron.webhookToken`, um ein dediziertes Bearer-Token zu senden; wenn es weggelassen wird, wird der Webhook ohne Authentifizierungs-Header gesendet. - - Veralteter Fallback: Gespeicherte Legacy-Jobs mit `notify: true` können bis zur Migration weiterhin `cron.webhook` verwenden. + - Für Jobs in der Hauptsitzung sind die Zustellmodi Webhook und keine verfügbar. + - Erweiterte Bearbeitungssteuerungen umfassen Nach-Ausführung-löschen, Agentenüberschreibung löschen, exakte/gestaffelte Cron-Optionen, Agentenmodell-/Thinking-Überschreibungen und Best-Effort-Zustellungsschalter. + - Die Formularvalidierung erfolgt inline mit Fehlern auf Feldebene; ungültige Werte deaktivieren die Speichern-Schaltfläche, bis sie korrigiert sind. + - Setzen Sie `cron.webhookToken`, um ein dediziertes Bearer-Token zu senden; wenn es ausgelassen wird, wird der Webhook ohne Auth-Header gesendet. + - Veralteter Fallback: Gespeicherte Legacy-Jobs mit `notify: true` können weiterhin `cron.webhook` verwenden, bis sie migriert werden. @@ -158,59 +158,59 @@ Importierte Themes werden nur im aktuellen Browserprofil gespeichert. Sie werden - `chat.send` ist **nicht blockierend**: Es bestätigt sofort mit `{ runId, status: "started" }`, und die Antwort wird über `chat`-Ereignisse gestreamt. - Chat-Uploads akzeptieren Bilder sowie Nicht-Video-Dateien. Bilder behalten den nativen Bildpfad; andere Dateien werden als verwaltete Medien gespeichert und im Verlauf als Anhangslinks angezeigt. - Erneutes Senden mit demselben `idempotencyKey` gibt während der Ausführung `{ status: "in_flight" }` und nach Abschluss `{ status: "ok" }` zurück. - - `chat.history`-Antworten sind aus Gründen der UI-Sicherheit größenbegrenzt. Wenn Transkripteinträge zu groß sind, kann Gateway lange Textfelder kürzen, umfangreiche Metadatenblöcke auslassen und übergroße Nachrichten durch einen Platzhalter ersetzen (`[chat.history omitted: message too large]`). - - Vom Assistenten generierte Bilder werden als verwaltete Medienreferenzen dauerhaft gespeichert und über authentifizierte Gateway-Medien-URLs zurückgeliefert, sodass Neuladevorgänge nicht davon abhängen, dass rohe Base64-Bilddaten in der Chatverlaufsantwort verbleiben. - - `chat.history` entfernt außerdem nur für die Anzeige gedachte Inline-Direktiv-Tags aus sichtbarem Assistententext (zum Beispiel `[[reply_to_*]]` und `[[audio_as_voice]]`), Nur-Text-XML-Nutzdaten von Tool-Aufrufen (einschließlich `...`, `...`, `...`, `...` und gekürzter Tool-Aufrufblöcke) sowie durchgesickerte ASCII-/vollbreite Modellsteuerungstoken und lässt Assistenteneinträge aus, deren gesamter sichtbarer Text nur das exakte stille Token `NO_REPLY` / `no_reply` ist. - - Während eines aktiven Sendevorgangs und der abschließenden Verlaufaktualisierung hält die Chatansicht lokale optimistische Benutzer-/Assistentennachrichten sichtbar, wenn `chat.history` kurzzeitig einen älteren Snapshot zurückgibt; das kanonische Transkript ersetzt diese lokalen Nachrichten, sobald der Gateway-Verlauf aufgeholt hat. - - Live-`chat`-Ereignisse sind Zustellstatus, während `chat.history` aus dem dauerhaften Sitzungstranskript neu aufgebaut wird. Nach Tool-Abschlussereignissen lädt die Control UI den Verlauf neu und führt nur einen kleinen optimistischen Nachlauf zusammen; die Transkriptgrenze ist in [WebChat](/de/web/webchat) dokumentiert. + - `chat.history`-Antworten sind zur UI-Sicherheit größenbegrenzt. Wenn Transkripteinträge zu groß sind, kann das Gateway lange Textfelder kürzen, umfangreiche Metadatenblöcke auslassen und übergroße Nachrichten durch einen Platzhalter (`[chat.history omitted: message too large]`) ersetzen. + - Vom Assistenten generierte Bilder werden als verwaltete Medienreferenzen persistiert und über authentifizierte Gateway-Medien-URLs zurückgegeben, sodass erneutes Laden nicht davon abhängt, dass rohe Base64-Bild-Payloads in der Chat-Verlaufsantwort verbleiben. + - `chat.history` entfernt außerdem nur zur Anzeige gedachte Inline-Direktiv-Tags aus sichtbarem Assistententext (zum Beispiel `[[reply_to_*]]` und `[[audio_as_voice]]`), Nur-Text-XML-Payloads von Tool-Aufrufen (einschließlich `...`, `...`, `...`, `...` und gekürzte Tool-Aufrufblöcke) sowie durchgesickerte ASCII-/Vollbreiten-Modellsteuerungstoken und lässt Assistenteneinträge aus, deren gesamter sichtbarer Text nur aus dem exakten stummen Token `NO_REPLY` / `no_reply` besteht. + - Während eines aktiven Sendevorgangs und der abschließenden Verlaufsaktualisierung hält die Chat-Ansicht lokale optimistische Benutzer-/Assistentennachrichten sichtbar, wenn `chat.history` kurzzeitig einen älteren Snapshot zurückgibt; das kanonische Transkript ersetzt diese lokalen Nachrichten, sobald der Gateway-Verlauf aufgeholt hat. + - Live-`chat`-Ereignisse bilden den Zustellungsstatus ab, während `chat.history` aus dem dauerhaften Sitzungstranskript neu aufgebaut wird. Nach Tool-Final-Ereignissen lädt die Control UI den Verlauf neu und führt nur ein kleines optimistisches Ende zusammen; die Transkriptgrenze ist in [WebChat](/de/web/webchat) dokumentiert. - `chat.inject` hängt eine Assistentennotiz an das Sitzungstranskript an und sendet ein `chat`-Ereignis für reine UI-Aktualisierungen (kein Agentenlauf, keine Kanalzustellung). - - Die Modell- und Denkmodus-Auswahllisten im Chatkopf patchen die aktive Sitzung sofort über `sessions.patch`; sie sind dauerhafte Sitzungsüberschreibungen, keine nur für einen Turn geltenden Sendeoptionen. - - Die Eingabe von `/new` in der Control UI erstellt dieselbe neue Dashboard-Sitzung wie Neuer Chat und wechselt zu ihr. Die Eingabe von `/reset` behält den expliziten In-Place-Reset des Gateway für die aktuelle Sitzung bei. - - Die Chat-Modellauswahl fragt die konfigurierte Modellansicht des Gateway ab. Wenn `agents.defaults.models` vorhanden ist, steuert diese Allowlist die Auswahl. Andernfalls zeigt die Auswahl explizite `models.providers.*.models`-Einträge sowie Provider mit nutzbarer Authentifizierung. Der vollständige Katalog bleibt über den Debug-RPC `models.list` mit `view: "all"` verfügbar. - - Wenn aktuelle Gateway-Sitzungsnutzungsberichte hohen Kontextdruck anzeigen, zeigt der Chat-Composer-Bereich einen Kontexthinweis und bei empfohlenen Compaction-Stufen eine kompakte Schaltfläche, die den normalen Sitzungs-Compaction-Pfad ausführt. Veraltete Token-Snapshots werden ausgeblendet, bis Gateway wieder aktuelle Nutzung meldet. + - Die Modell- und Denkmodus-Auswahlen im Chat-Header patchen die aktive Sitzung sofort über `sessions.patch`; sie sind persistente Sitzungsüberschreibungen, keine nur für einen Durchgang geltenden Sendeoptionen. + - Wenn Sie `/new` in der Control UI eingeben, wird dieselbe frische Dashboard-Sitzung wie bei Neuer Chat erstellt und aktiviert. Bei Eingabe von `/reset` bleibt die explizite In-Place-Zurücksetzung des Gateways für die aktuelle Sitzung erhalten. + - Die Chat-Modellauswahl fragt die konfigurierte Modellansicht des Gateways an. Wenn `agents.defaults.models` vorhanden ist, steuert diese Allowlist die Auswahl. Andernfalls zeigt die Auswahl explizite `models.providers.*.models`-Einträge sowie Provider mit nutzbarer Authentifizierung. Der vollständige Katalog bleibt über den Debug-`models.list`-RPC mit `view: "all"` verfügbar. + - Wenn aktuelle Gateway-Berichte zur Sitzungsnutzung hohen Kontextdruck anzeigen, zeigt der Chat-Composer-Bereich einen Kontext-Hinweis und bei empfohlenen Compaction-Stufen eine Compaction-Schaltfläche, die den normalen Pfad für Session-Compaction ausführt. Veraltete Token-Snapshots werden ausgeblendet, bis das Gateway wieder aktuelle Nutzung meldet. - - Der Sprechmodus verwendet einen registrierten Echtzeit-Voice-Provider. Konfigurieren Sie OpenAI mit `talk.provider: "openai"` plus `talk.providers.openai.apiKey`, oder konfigurieren Sie Google mit `talk.provider: "google"` plus `talk.providers.google.apiKey`; die Echtzeit-Provider-Konfiguration für Voice Call kann weiterhin als Fallback wiederverwendet werden. Der Browser erhält niemals einen Standard-Provider-API-Schlüssel. OpenAI erhält ein kurzlebiges Realtime-Client-Secret für WebRTC. Google Live erhält ein einmal verwendbares, eingeschränktes Live-API-Authentifizierungstoken für eine Browser-WebSocket-Sitzung, wobei Anweisungen und Tool-Deklarationen durch Gateway im Token fixiert werden. Provider, die nur eine Backend-Echtzeit-Bridge bereitstellen, laufen über den Gateway-Relay-Transport, sodass Anmeldedaten und Vendor-Sockets serverseitig bleiben, während Browser-Audio über authentifizierte Gateway-RPCs übertragen wird. Der Realtime-Sitzungsprompt wird vom Gateway zusammengesetzt; `talk.realtime.session` akzeptiert keine vom Aufrufer bereitgestellten Anweisungsüberschreibungen. + + Der Talk-Modus verwendet einen registrierten Echtzeit-Sprach-Provider. Konfigurieren Sie OpenAI mit `talk.provider: "openai"` plus `talk.providers.openai.apiKey`, oder konfigurieren Sie Google mit `talk.provider: "google"` plus `talk.providers.google.apiKey`; die Echtzeit-Provider-Konfiguration von Voice Call kann weiterhin als Fallback wiederverwendet werden. Der Browser erhält niemals einen normalen Provider-API-Schlüssel. OpenAI erhält ein flüchtiges Realtime-Client-Secret für WebRTC. Google Live erhält ein einmalig verwendbares, eingeschränktes Live API-Authentifizierungstoken für eine Browser-WebSocket-Sitzung, wobei Anweisungen und Tool-Deklarationen durch das Gateway im Token gesperrt werden. Provider, die nur eine Backend-Echtzeit-Bridge bereitstellen, laufen über den Gateway-Relay-Transport, sodass Anmeldedaten und Vendor-Sockets serverseitig bleiben, während Browser-Audio über authentifizierte Gateway-RPCs läuft. Der Realtime-Sitzungsprompt wird vom Gateway zusammengesetzt; `talk.realtime.session` akzeptiert keine vom Aufrufer bereitgestellten Anweisungsüberschreibungen. - Im Chat-Composer ist das Talk-Bedienelement die Wellenschaltfläche neben der Mikrofon-Diktatschaltfläche. Wenn Talk startet, zeigt die Composer-Statuszeile `Connecting Talk...`, anschließend `Talk live`, während Audio verbunden ist, oder `Asking OpenClaw...`, während ein Echtzeit-Tool-Aufruf das konfigurierte größere Modell über `chat.send` konsultiert. + Im Chat-Composer ist die Talk-Steuerung die Wellen-Schaltfläche neben der Mikrofon-Diktat-Schaltfläche. Wenn Talk startet, zeigt die Statuszeile des Composers `Connecting Talk...`, dann `Talk live`, während Audio verbunden ist, oder `Asking OpenClaw...`, während ein Echtzeit-Tool-Aufruf das konfigurierte größere Modell über `chat.send` konsultiert. - Maintainer-Live-Smoke: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` verifiziert den OpenAI-Browser-WebRTC-SDP-Austausch, die Browser-WebSocket-Einrichtung mit eingeschränktem Token für Google Live und den Gateway-Relay-Browseradapter mit simulierten Mikrofonmedien. Der Befehl gibt nur den Provider-Status aus und protokolliert keine Secrets. + Maintainer-Live-Smoke: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` verifiziert den OpenAI-Browser-WebRTC-SDP-Austausch, die Google Live-Browser-WebSocket-Einrichtung mit eingeschränktem Token und den Gateway-Relay-Browseradapter mit gefälschten Mikrofonmedien. Der Befehl gibt nur den Provider-Status aus und protokolliert keine Secrets. - - Klicken Sie auf **Stop** (ruft `chat.abort` auf). - - Während ein Lauf aktiv ist, werden normale Folgeanfragen in die Warteschlange gestellt. Klicken Sie bei einer in der Warteschlange befindlichen Nachricht auf **Steer**, um diese Folgeanfrage in den laufenden Turn einzuschleusen. - - Geben Sie `/stop` ein (oder eigenständige Abbruchphrasen wie `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`), um außerhalb des normalen Ablaufs abzubrechen. + - Klicken Sie auf **Stoppen** (ruft `chat.abort` auf). + - Während ein Lauf aktiv ist, werden normale Folgefragen in die Warteschlange gestellt. Klicken Sie bei einer eingereihten Nachricht auf **Steuern**, um diese Folgefrage in den laufenden Durchgang einzuspeisen. + - Geben Sie `/stop` ein (oder eigenständige Abbruchformulierungen wie `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`), um out-of-band abzubrechen. - `chat.abort` unterstützt `{ sessionKey }` (ohne `runId`), um alle aktiven Läufe für diese Sitzung abzubrechen. - - - Wenn ein Lauf abgebrochen wird, kann Teiltext des Assistenten weiterhin in der UI angezeigt werden. - - Gateway speichert abgebrochenen Assistenten-Teiltext im Transkriptverlauf, wenn gepufferte Ausgabe vorhanden ist. - - Gespeicherte Einträge enthalten Abbruchmetadaten, damit Transkriptnutzer abgebrochene Teilausgaben von normaler Abschlussausgabe unterscheiden können. + + - Wenn ein Lauf abgebrochen wird, kann teilweiser Assistententext weiterhin in der UI angezeigt werden. + - Das Gateway persistiert abgebrochenen teilweisen Assistententext im Transkriptverlauf, wenn gepufferte Ausgabe vorhanden ist. + - Persistierte Einträge enthalten Abbruchmetadaten, damit Transkriptkonsumenten Abbruch-Teilergebnisse von normaler Abschlussausgabe unterscheiden können. ## PWA-Installation und Web Push -Die Control UI liefert ein `manifest.webmanifest` und einen Service Worker aus, sodass moderne Browser sie als eigenständige PWA installieren können. Mit Web Push kann Gateway die installierte PWA per Benachrichtigung wecken, selbst wenn der Tab oder das Browserfenster nicht geöffnet ist. +Die Control UI liefert ein `manifest.webmanifest` und einen Service Worker aus, sodass moderne Browser sie als eigenständige PWA installieren können. Mit Web Push kann das Gateway die installierte PWA mit Benachrichtigungen wecken, auch wenn der Tab oder das Browserfenster nicht geöffnet ist. -| Oberfläche | Funktion | -| ----------------------------------------------------- | ------------------------------------------------------------------ | -| `ui/public/manifest.webmanifest` | PWA-Manifest. Browser bieten „Install app“ an, sobald es erreichbar ist. | -| `ui/public/sw.js` | Service Worker, der `push`-Ereignisse und Benachrichtigungsklicks verarbeitet. | -| `push/vapid-keys.json` (unter dem OpenClaw-Statusverzeichnis) | Automatisch generiertes VAPID-Schlüsselpaar zum Signieren von Web-Push-Nutzdaten. | -| `push/web-push-subscriptions.json` | Dauerhaft gespeicherte Browser-Abonnement-Endpunkte. | +| Oberfläche | Was sie tut | +| ---------------------------------------------------- | ------------------------------------------------------------------ | +| `ui/public/manifest.webmanifest` | PWA-Manifest. Browser bieten "App installieren" an, sobald es erreichbar ist. | +| `ui/public/sw.js` | Service Worker, der `push`-Ereignisse und Benachrichtigungsklicks verarbeitet. | +| `push/vapid-keys.json` (im OpenClaw-Zustandsverzeichnis) | Automatisch generiertes VAPID-Schlüsselpaar, das zum Signieren von Web Push-Payloads verwendet wird. | +| `push/web-push-subscriptions.json` | Persistierte Browser-Abonnement-Endpunkte. | -Überschreiben Sie das VAPID-Schlüsselpaar über Umgebungsvariablen im Gateway-Prozess, wenn Sie Schlüssel fest vorgeben möchten (für Multi-Host-Deployments, Secret-Rotation oder Tests): +Überschreiben Sie das VAPID-Schlüsselpaar über Umgebungsvariablen im Gateway-Prozess, wenn Sie Schlüssel fest vorgeben möchten (für Multi-Host-Deployments, Secrets-Rotation oder Tests): - `OPENCLAW_VAPID_PUBLIC_KEY` - `OPENCLAW_VAPID_PRIVATE_KEY` - `OPENCLAW_VAPID_SUBJECT` (standardmäßig `mailto:openclaw@localhost`) -Die Control UI verwendet diese scope-gebundenen Gateway-Methoden, um Browser-Abonnements zu registrieren und zu testen: +Die Control UI verwendet diese bereichsbeschränkten Gateway-Methoden, um Browser-Abonnements zu registrieren und zu testen: - `push.web.vapidPublicKey` — ruft den aktiven öffentlichen VAPID-Schlüssel ab. - `push.web.subscribe` — registriert einen `endpoint` plus `keys.p256dh`/`keys.auth`. @@ -218,22 +218,22 @@ Die Control UI verwendet diese scope-gebundenen Gateway-Methoden, um Browser-Abo - `push.web.test` — sendet eine Testbenachrichtigung an das Abonnement des Aufrufers. -Web Push ist unabhängig vom iOS-APNS-Relay-Pfad (siehe [Konfiguration](/de/gateway/configuration) für relay-gestützten Push) und von der bestehenden Methode `push.test`, die auf natives mobiles Pairing abzielt. +Web Push ist unabhängig vom iOS-APNS-Relay-Pfad (siehe [Konfiguration](/de/gateway/configuration) für relaygestützten Push) und von der bestehenden Methode `push.test`, die auf native mobile Kopplung abzielen. ## Gehostete Einbettungen -Assistentennachrichten können gehostete Webinhalte inline mit dem Shortcode `[embed ...]` rendern. Die iframe-Sandbox-Richtlinie wird über `gateway.controlUi.embedSandbox` gesteuert: +Assistentennachrichten können gehostete Webinhalte inline mit dem Shortcode `[embed ...]` rendern. Die Iframe-Sandbox-Richtlinie wird durch `gateway.controlUi.embedSandbox` gesteuert: - Deaktiviert Skriptausführung innerhalb gehosteter Einbettungen. + Deaktiviert die Skriptausführung in gehosteten Einbettungen. - - Erlaubt interaktive Einbettungen bei beibehaltener Origin-Isolation; dies ist der Standard und reicht normalerweise für eigenständige Browser-Spiele/-Widgets aus. + + Erlaubt interaktive Einbettungen, während die Origin-Isolierung erhalten bleibt; dies ist die Standardeinstellung und reicht normalerweise für eigenständige Browser-Spiele/-Widgets aus. - Fügt zusätzlich zu `allow-scripts` `allow-same-origin` für same-site Dokumente hinzu, die absichtlich stärkere Berechtigungen benötigen. + Fügt `allow-same-origin` zusätzlich zu `allow-scripts` für Same-Site-Dokumente hinzu, die bewusst stärkere Berechtigungen benötigen. @@ -250,14 +250,14 @@ Beispiel: ``` -Verwenden Sie `trusted` nur, wenn das eingebettete Dokument tatsächlich Same-Origin-Verhalten benötigt. Für die meisten agentengenerierten Spiele und interaktiven Canvases ist `scripts` die sicherere Wahl. +Verwenden Sie `trusted` nur, wenn das eingebettete Dokument tatsächlich Same-Origin-Verhalten benötigt. Für die meisten von Agenten generierten Spiele und interaktiven Canvases ist `scripts` die sicherere Wahl. -Absolute externe `http(s)`-Einbettungs-URLs bleiben standardmäßig blockiert. Wenn Sie ausdrücklich möchten, dass `[embed url="https://..."]` Drittanbieterseiten lädt, setzen Sie `gateway.controlUi.allowExternalEmbedUrls: true`. +Absolute externe `http(s)`-Einbettungs-URLs bleiben standardmäßig blockiert. Wenn Sie bewusst möchten, dass `[embed url="https://..."]` Drittanbieter-Seiten lädt, setzen Sie `gateway.controlUi.allowExternalEmbedUrls: true`. -## Breite von Chatnachrichten +## Chat-Nachrichtenbreite -Gruppierte Chatnachrichten verwenden standardmäßig eine gut lesbare maximale Breite. Wide-Monitor-Deployments können sie ohne Patchen des gebündelten CSS überschreiben, indem `gateway.controlUi.chatMessageMaxWidth` gesetzt wird: +Gruppierte Chat-Nachrichten verwenden eine gut lesbare standardmäßige Maximalbreite. Bereitstellungen auf breiten Monitoren können sie überschreiben, ohne gebündeltes CSS zu patchen, indem `gateway.controlUi.chatMessageMaxWidth` gesetzt wird: ```json5 { @@ -269,13 +269,13 @@ Gruppierte Chatnachrichten verwenden standardmäßig eine gut lesbare maximale B } ``` -Der Wert wird validiert, bevor er den Browser erreicht. Unterstützte Werte umfassen einfache Längen und Prozentangaben wie `960px` oder `82%` sowie eingeschränkte Breiten-Ausdrücke mit `min(...)`, `max(...)`, `clamp(...)`, `calc(...)` und `fit-content(...)`. +Der Wert wird validiert, bevor er den Browser erreicht. Unterstützte Werte umfassen einfache Längen und Prozentangaben wie `960px` oder `82%` sowie eingeschränkte `min(...)`-, `max(...)`-, `clamp(...)`-, `calc(...)`- und `fit-content(...)`-Breitenausdrücke. ## Tailnet-Zugriff (empfohlen) - Belassen Sie Gateway auf loopback und lassen Sie Tailscale Serve es per HTTPS proxien: + Belassen Sie das Gateway auf Loopback und lassen Sie Tailscale Serve es per HTTPS als Proxy bereitstellen: ```bash openclaw gateway --tailscale serve @@ -283,48 +283,48 @@ Der Wert wird validiert, bevor er den Browser erreicht. Unterstützte Werte umfa Öffnen Sie: - - `https:///` (oder Ihr konfiguriertes `gateway.controlUi.basePath`) + - `https:///` (oder Ihren konfigurierten `gateway.controlUi.basePath`) - Standardmäßig können Control UI-/WebSocket-Serve-Anfragen über Tailscale-Identitätsheader (`tailscale-user-login`) authentifiziert werden, wenn `gateway.auth.allowTailscale` `true` ist. OpenClaw verifiziert die Identität, indem die Adresse `x-forwarded-for` mit `tailscale whois` aufgelöst und mit dem Header abgeglichen wird, und akzeptiert diese nur, wenn die Anfrage loopback mit den `x-forwarded-*`-Headern von Tailscale erreicht. Für Control UI-Bedienersitzungen mit Browser-Geräteidentität überspringt dieser verifizierte Serve-Pfad auch den Device-Pairing-Roundtrip; Browser ohne Gerät und Verbindungen mit Node-Rolle folgen weiterhin den normalen Geräteprüfungen. Setzen Sie `gateway.auth.allowTailscale: false`, wenn Sie auch für Serve-Traffic explizite Shared-Secret-Anmeldedaten verlangen möchten. Verwenden Sie dann `gateway.auth.mode: "token"` oder `"password"`. + Standardmäßig können Control UI- und WebSocket-Serve-Anfragen sich über Tailscale-Identitätsheader (`tailscale-user-login`) authentifizieren, wenn `gateway.auth.allowTailscale` `true` ist. OpenClaw verifiziert die Identität, indem es die `x-forwarded-for`-Adresse mit `tailscale whois` auflöst und sie mit dem Header abgleicht, und akzeptiert diese nur, wenn die Anfrage über Loopback mit Tailscales `x-forwarded-*`-Headern eintrifft. Bei Control UI-Operator-Sitzungen mit Browser-Geräteidentität überspringt dieser verifizierte Serve-Pfad außerdem den Device-Pairing-Roundtrip; gerätelose Browser und Verbindungen mit Node-Rolle folgen weiterhin den normalen Geräteprüfungen. Setzen Sie `gateway.auth.allowTailscale: false`, wenn Sie auch für Serve-Traffic explizite Shared-Secret-Anmeldedaten verlangen möchten. Verwenden Sie dann `gateway.auth.mode: "token"` oder `"password"`. - Für diesen asynchronen Serve-Identitätspfad werden fehlgeschlagene Authentifizierungsversuche für dieselbe Client-IP und denselben Authentifizierungsscope vor Rate-Limit-Schreibvorgängen serialisiert. Gleichzeitige fehlerhafte Wiederholungen aus demselben Browser können daher bei der zweiten Anfrage `retry later` anzeigen, statt dass zwei einfache Nichtübereinstimmungen parallel konkurrieren. + Für diesen asynchronen Serve-Identitätspfad werden fehlgeschlagene Authentifizierungsversuche für dieselbe Client-IP und denselben Auth-Scope vor Rate-Limit-Schreibvorgängen serialisiert. Gleichzeitige fehlerhafte Wiederholungen aus demselben Browser können daher bei der zweiten Anfrage `retry later` anzeigen, statt dass zwei einfache Nichtübereinstimmungen parallel konkurrieren. - Tokenlose Serve-Authentifizierung setzt voraus, dass dem Gateway-Host vertraut wird. Wenn nicht vertrauenswürdiger lokaler Code auf diesem Host ausgeführt werden kann, verlangen Sie Token-/Passwortauthentifizierung. + Tokenlose Serve-Authentifizierung setzt voraus, dass der Gateway-Host vertrauenswürdig ist. Wenn auf diesem Host nicht vertrauenswürdiger lokaler Code laufen könnte, verlangen Sie Token-/Passwortauthentifizierung. - + ```bash openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)" ``` Öffnen Sie dann: - - `http://:18789/` (oder Ihr konfiguriertes `gateway.controlUi.basePath`) + - `http://:18789/` (oder Ihren konfigurierten `gateway.controlUi.basePath`) - Fügen Sie das passende gemeinsame Secret in die UI-Einstellungen ein (gesendet als `connect.params.auth.token` oder `connect.params.auth.password`). + Fügen Sie den passenden gemeinsamen geheimen Schlüssel in die UI-Einstellungen ein (gesendet als `connect.params.auth.token` oder `connect.params.auth.password`). ## Unsicheres HTTP -Wenn Sie das Dashboard über einfaches HTTP öffnen (`http://` oder `http://`), läuft der Browser in einem **nicht sicheren Kontext** und blockiert WebCrypto. Standardmäßig **blockiert** OpenClaw Control UI-Verbindungen ohne Geräteidentität. +Wenn Sie das Dashboard über einfaches HTTP (`http://` oder `http://`) öffnen, läuft der Browser in einem **nicht sicheren Kontext** und blockiert WebCrypto. Standardmäßig **blockiert** OpenClaw Control UI-Verbindungen ohne Geräteidentität. Dokumentierte Ausnahmen: -- localhost-only unsichere HTTP-Kompatibilität mit `gateway.controlUi.allowInsecureAuth=true` -- erfolgreiche Bediener-Control UI-Authentifizierung über `gateway.auth.mode: "trusted-proxy"` +- nur für localhost geltende Kompatibilität für unsicheres HTTP mit `gateway.controlUi.allowInsecureAuth=true` +- erfolgreiche Control UI-Operatorauthentifizierung über `gateway.auth.mode: "trusted-proxy"` - Notfalloption `gateway.controlUi.dangerouslyDisableDeviceAuth=true` -**Empfohlene Korrektur:** Verwenden Sie HTTPS (Tailscale Serve) oder öffnen Sie die UI lokal: +**Empfohlene Lösung:** Verwenden Sie HTTPS (Tailscale Serve) oder öffnen Sie die UI lokal: - `https:///` (Serve) - `http://127.0.0.1:18789/` (auf dem Gateway-Host) - + ```json5 { gateway: { @@ -337,12 +337,12 @@ Dokumentierte Ausnahmen: `allowInsecureAuth` ist nur ein lokaler Kompatibilitätsschalter: - - Er erlaubt lokalen Control-UI-Sitzungen, in nicht sicheren HTTP-Kontexten ohne Geräteidentität fortzufahren. - - Er umgeht keine Kopplungsprüfungen. - - Er lockert keine Anforderungen an die Geräteidentität für entfernte Geräte (nicht localhost). + - Er erlaubt localhost-Control UI-Sitzungen, in nicht sicheren HTTP-Kontexten ohne Geräteidentität fortzufahren. + - Er umgeht keine Pairing-Prüfungen. + - Er lockert keine Anforderungen an die Geräteidentität für entfernte (nicht-localhost) Geräte. - + ```json5 { gateway: { @@ -354,42 +354,52 @@ Dokumentierte Ausnahmen: ``` - `dangerouslyDisableDeviceAuth` deaktiviert die Geräteidentitätsprüfungen der Control UI und ist eine erhebliche Sicherheitsabsenkung. Machen Sie dies nach der Notfallnutzung schnell rückgängig. + `dangerouslyDisableDeviceAuth` deaktiviert die Geräteidentitätsprüfungen der Control UI und stellt eine schwerwiegende Sicherheitsverschlechterung dar. Machen Sie dies nach einer Notfallnutzung schnell rückgängig. - - - Erfolgreiche Trusted-Proxy-Authentifizierung kann Control-UI-Sitzungen für **Operatoren** ohne Geräteidentität zulassen. - - Dies gilt **nicht** für Control-UI-Sitzungen mit Node-Rolle. - - Same-Host-Loopback-Reverse-Proxys erfüllen die Trusted-Proxy-Authentifizierung weiterhin nicht; siehe [Trusted-Proxy-Authentifizierung](/de/gateway/trusted-proxy-auth). + + - Erfolgreiche Trusted-Proxy-Authentifizierung kann **Operator**-Control UI-Sitzungen ohne Geräteidentität zulassen. + - Dies gilt **nicht** für Control UI-Sitzungen mit Node-Rolle. + - local loopback-Reverse-Proxys auf demselben Host erfüllen Trusted-Proxy-Authentifizierung weiterhin nicht; siehe [Trusted Proxy Auth](/de/gateway/trusted-proxy-auth). Siehe [Tailscale](/de/gateway/tailscale) für Hinweise zur HTTPS-Einrichtung. -## Content-Security-Policy +## Content Security Policy -Die Control UI wird mit einer strengen `img-src`-Richtlinie ausgeliefert: Nur Assets mit **gleichem Ursprung**, `data:`-URLs und lokal erzeugte `blob:`-URLs sind erlaubt. Entfernte `http(s)`- und protokollrelative Bild-URLs werden vom Browser abgelehnt und lösen keine Netzwerkabrufe aus. +Die Control UI wird mit einer strikten `img-src`-Policy ausgeliefert: Nur Assets mit **gleichem Ursprung**, `data:`-URLs und lokal erzeugte `blob:`-URLs sind erlaubt. Entfernte `http(s)`- und protokollrelative Bild-URLs werden vom Browser abgelehnt und lösen keine Netzwerkabrufe aus. Was das in der Praxis bedeutet: -- Avatare und Bilder, die unter relativen Pfaden bereitgestellt werden (zum Beispiel `/avatars/`), werden weiterhin gerendert, einschließlich authentifizierter Avatar-Routen, die die UI abruft und in lokale `blob:`-URLs konvertiert. +- Avatare und Bilder, die unter relativen Pfaden bereitgestellt werden (zum Beispiel `/avatars/`), werden weiterhin gerendert, einschließlich authentifizierter Avatar-Routen, die die UI abruft und in lokale `blob:`-URLs umwandelt. - Inline-`data:image/...`-URLs werden weiterhin gerendert (nützlich für Payloads innerhalb des Protokolls). -- Lokale `blob:`-URLs, die von der Control UI erstellt wurden, werden weiterhin gerendert. -- Entfernte Avatar-URLs, die von Kanalmetadaten ausgegeben werden, werden in den Avatar-Helfern der Control UI entfernt und durch das integrierte Logo/Badge ersetzt, sodass ein kompromittierter oder bösartiger Kanal keine beliebigen entfernten Bildabrufe aus dem Browser eines Operators erzwingen kann. +- Lokale `blob:`-URLs, die von der Control UI erstellt werden, werden weiterhin gerendert. +- Entfernte Avatar-URLs, die von Channel-Metadaten ausgegeben werden, werden in den Avatar-Helfern der Control UI entfernt und durch das integrierte Logo/Badge ersetzt, sodass ein kompromittierter oder bösartiger Channel keine beliebigen entfernten Bildabrufe aus dem Browser eines Operators erzwingen kann. -Sie müssen nichts ändern, um dieses Verhalten zu erhalten — es ist immer aktiv und nicht konfigurierbar. +Sie müssen nichts ändern, um dieses Verhalten zu erhalten — es ist immer aktiviert und nicht konfigurierbar. ## Authentifizierung der Avatar-Route -Wenn Gateway-Authentifizierung konfiguriert ist, erfordert der Avatar-Endpunkt der Control UI denselben Gateway-Token wie der Rest der API: +Wenn Gateway-Authentifizierung konfiguriert ist, erfordert der Avatar-Endpunkt der Control UI dasselbe Gateway-Token wie der Rest der API: - `GET /avatar/` gibt das Avatar-Bild nur an authentifizierte Aufrufer zurück. `GET /avatar/?meta=1` gibt die Avatar-Metadaten nach derselben Regel zurück. -- Nicht authentifizierte Anfragen an eine der beiden Routen werden abgelehnt (entsprechend der benachbarten Assistant-Media-Route). Dies verhindert, dass die Avatar-Route die Identität von Agenten auf Hosts preisgibt, die ansonsten geschützt sind. -- Die Control UI leitet beim Abrufen von Avataren selbst den Gateway-Token als Bearer-Header weiter und verwendet authentifizierte Blob-URLs, damit das Bild weiterhin in Dashboards gerendert wird. +- Nicht authentifizierte Anfragen an beide Routen werden abgelehnt (entsprechend der benachbarten Assistant-Media-Route). Dadurch wird verhindert, dass die Avatar-Route die Agentenidentität auf Hosts preisgibt, die ansonsten geschützt sind. +- Die Control UI leitet beim Abrufen von Avataren das Gateway-Token als Bearer-Header weiter und verwendet authentifizierte Blob-URLs, sodass das Bild weiterhin in Dashboards gerendert wird. -Wenn Sie die Gateway-Authentifizierung deaktivieren (auf gemeinsam genutzten Hosts nicht empfohlen), wird auch die Avatar-Route unauthentifiziert, entsprechend dem Rest des Gateway. +Wenn Sie die Gateway-Authentifizierung deaktivieren (auf gemeinsam genutzten Hosts nicht empfohlen), wird auch die Avatar-Route nicht authentifiziert, entsprechend dem Rest des Gateways. + +## Authentifizierung der Assistant-Media-Route + +Wenn Gateway-Authentifizierung konfiguriert ist, verwenden lokale Medienvorschauen des Assistenten eine zweistufige Route: + +- `GET /__openclaw__/assistant-media?meta=1&source=` erfordert die normale Operator-Authentifizierung der Control UI. Der Browser sendet beim Prüfen der Verfügbarkeit das Gateway-Token als Bearer-Header. +- Erfolgreiche Metadatenantworten enthalten ein kurzlebiges `mediaTicket`, das auf genau diesen Quellpfad beschränkt ist. +- Vom Browser gerenderte Bild-, Audio-, Video- und Dokument-URLs verwenden `mediaTicket=` anstelle des aktiven Gateway-Tokens oder Passworts. Das Ticket läuft schnell ab und kann keine andere Quelle autorisieren. + +Dadurch bleibt das normale Medien-Rendering mit browsernativen Medienelementen kompatibel, ohne wiederverwendbare Gateway-Anmeldedaten in sichtbare Medien-URLs aufzunehmen. ## UI erstellen @@ -415,7 +425,7 @@ Richten Sie die UI dann auf Ihre Gateway-WS-URL aus (z. B. `ws://127.0.0.1:18789 ## Debugging/Tests: Dev-Server + entferntes Gateway -Die Control UI besteht aus statischen Dateien; das WebSocket-Ziel ist konfigurierbar und kann sich vom HTTP-Ursprung unterscheiden. Das ist praktisch, wenn Sie den Vite-Dev-Server lokal verwenden möchten, das Gateway aber anderswo läuft. +Die Control UI besteht aus statischen Dateien; das WebSocket-Ziel ist konfigurierbar und kann sich vom HTTP-Ursprung unterscheiden. Das ist praktisch, wenn Sie den Vite-Dev-Server lokal verwenden möchten, das Gateway aber an anderer Stelle läuft. @@ -440,16 +450,16 @@ Die Control UI besteht aus statischen Dateien; das WebSocket-Ziel ist konfigurie - `gatewayUrl` wird nach dem Laden in localStorage gespeichert und aus der URL entfernt. - - Wenn Sie einen vollständigen `ws://`- oder `wss://`-Endpunkt über `gatewayUrl` übergeben, URL-kodieren Sie den Wert `gatewayUrl`, damit der Browser die Abfragezeichenfolge korrekt analysiert. - - `token` sollte nach Möglichkeit über das URL-Fragment (`#token=...`) übergeben werden. Fragmente werden nicht an den Server gesendet, wodurch Lecks in Anfrageprotokollen und im Referer vermieden werden. Alte `?token=`-Query-Parameter werden aus Kompatibilitätsgründen weiterhin einmal importiert, aber nur als Fallback, und unmittelbar nach dem Bootstrap entfernt. - - `password` wird nur im Speicher gehalten. - - Wenn `gatewayUrl` gesetzt ist, fällt die UI nicht auf Konfigurations- oder Umgebungsanmeldedaten zurück. Geben Sie `token` (oder `password`) explizit an. Fehlende explizite Anmeldedaten sind ein Fehler. + - Wenn Sie einen vollständigen `ws://`- oder `wss://`-Endpunkt über `gatewayUrl` übergeben, URL-codieren Sie den Wert von `gatewayUrl`, damit der Browser die Query-Zeichenfolge korrekt parst. + - `token` sollte nach Möglichkeit über das URL-Fragment (`#token=...`) übergeben werden. Fragmente werden nicht an den Server gesendet, wodurch Lecks in Anfrageprotokollen und über Referer vermieden werden. Ältere `?token=`-Query-Parameter werden aus Kompatibilitätsgründen weiterhin einmal importiert, aber nur als Fallback, und direkt nach dem Bootstrap entfernt. + - `password` wird nur im Arbeitsspeicher gehalten. + - Wenn `gatewayUrl` gesetzt ist, greift die UI nicht auf Konfigurations- oder Umgebungsanmeldedaten zurück. Geben Sie `token` (oder `password`) explizit an. Fehlende explizite Anmeldedaten sind ein Fehler. - Verwenden Sie `wss://`, wenn sich das Gateway hinter TLS befindet (Tailscale Serve, HTTPS-Proxy usw.). - - `gatewayUrl` wird nur in einem Top-Level-Fenster akzeptiert (nicht eingebettet), um Clickjacking zu verhindern. - - Nicht-Loopback-Bereitstellungen der Control UI müssen `gateway.controlUi.allowedOrigins` explizit setzen (vollständige Ursprünge). Dies schließt entfernte Dev-Setups ein. - - Beim Start kann das Gateway lokale Ursprünge wie `http://localhost:` und `http://127.0.0.1:` aus dem effektiven Laufzeit-Bind und Port übernehmen, entfernte Browser-Ursprünge benötigen jedoch weiterhin explizite Einträge. - - Verwenden Sie `gateway.controlUi.allowedOrigins: ["*"]` nur für streng kontrollierte lokale Tests. Es bedeutet, dass jeder Browser-Ursprung zugelassen wird, nicht „mit dem Host übereinstimmen, den ich gerade verwende“. - - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` aktiviert den Fallback-Modus für den Host-Header-Ursprung, ist jedoch ein gefährlicher Sicherheitsmodus. + - `gatewayUrl` wird nur in einem Fenster der obersten Ebene akzeptiert (nicht eingebettet), um Clickjacking zu verhindern. + - Nicht-loopback-Control-UI-Bereitstellungen müssen `gateway.controlUi.allowedOrigins` explizit festlegen (vollständige Ursprünge). Dazu gehören auch entfernte Dev-Setups. + - Beim Start des Gateway können lokale Ursprünge wie `http://localhost:` und `http://127.0.0.1:` aus dem effektiven Runtime-Bind und -Port übernommen werden, entfernte Browser-Ursprünge benötigen jedoch weiterhin explizite Einträge. + - Verwenden Sie `gateway.controlUi.allowedOrigins: ["*"]` nur für streng kontrollierte lokale Tests. Es bedeutet, jeden Browser-Ursprung zuzulassen, nicht „den Host abzugleichen, den ich gerade verwende“. + - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` aktiviert den Host-Header-Origin-Fallback-Modus, ist jedoch ein gefährlicher Sicherheitsmodus. @@ -466,11 +476,11 @@ Beispiel: } ``` -Details zur Einrichtung des entfernten Zugriffs: [Entfernter Zugriff](/de/gateway/remote). +Details zur Einrichtung des Remote-Zugriffs: [Remote-Zugriff](/de/gateway/remote). -## Verwandt +## Verwandte Themen - [Dashboard](/de/web/dashboard) — Gateway-Dashboard -- [Integritätsprüfungen](/de/gateway/health) — Gateway-Integritätsüberwachung +- [Health Checks](/de/gateway/health) — Gateway-Zustandsüberwachung - [TUI](/de/web/tui) — Terminal-Benutzeroberfläche - [WebChat](/de/web/webchat) — browserbasierte Chat-Oberfläche