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

chore(i18n): refresh de translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-02 23:42:23 +00:00
parent ffe4df986d
commit 98ebec649f
8 changed files with 1357 additions and 1308 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

392
docs/de/ci.md
View File

@ -1,94 +1,94 @@
---
read_when:
- Sie müssen nachvollziehen, warum ein CI-Job ausgeführt wurde oder nicht
- Sie debuggen einen fehlgeschlagenen GitHub Actions-Check
- Sie müssen nachvollziehen, warum ein CI-Job ausgeführt wurde oder nicht.
- Sie debuggen eine fehlschlagende GitHub Actions-Prüfung
- Sie koordinieren einen Release-Validierungslauf oder eine erneute Ausführung
- Sie ändern den ClawSweeper-Dispatch oder die Weiterleitung von GitHub-Aktivitäten
summary: CI-Job-Graph, bereichsbezogene Gates, Release-Sammelprüfungen und lokale Befehlsäquivalente
summary: CI-Jobgraph, Scope-Gates, Release-Umbrellas und lokale Befehlsäquivalente
title: CI-Pipeline
x-i18n:
generated_at: "2026-05-02T22:17:23Z"
generated_at: "2026-05-02T23:39:35Z"
model: gpt-5.5
provider: openai
source_hash: a8033b928b26adfa340200ea69fd63d339a6e65c21659b8119a68b23b8b16016
source_hash: 321fe0a061044f75b8e1d03b4d3e76d4f8dd2dae0ebc58831887fc20af953cf1
source_path: ci.md
workflow: 16
---
OpenClaw CI läuft bei jedem Push auf `main` und bei jedem Pull Request. Der `preflight`-Job klassifiziert das Diff und deaktiviert teure Lanes, wenn sich nur nicht zugehörige 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` optional. Release-exklusive Plugin-Abdeckung befindet sich im separaten Workflow [`Plugin-Prerelease`](#plugin-prerelease) und läuft nur über [`vollständige Release-Validierung`](#full-release-validation) oder einen expliziten manuellen Dispatch.
OpenClaw CI wird bei jedem Push nach `main` und jedem Pull Request ausgeführt. Der Job `preflight` klassifiziert den Diff und deaktiviert teure Lanes, wenn sich nur nicht zusammenhängende Bereiche geändert haben. Manuelle `workflow_dispatch`-Ausführungen umgehen Smart Scoping absichtlich und fächern den vollständigen Graphen für Release-Kandidaten und breite Validierung auf. Android-Lanes bleiben über `include_android` opt-in. Die Plugin-Abdeckung nur für Releases befindet sich im separaten Workflow [`Plugin-Prerelease`](#plugin-prerelease) und wird nur von [`Vollständige Release-Validierung`](#full-release-validation) oder einem expliziten manuellen Dispatch ausgeführt.
## Pipeline-Übersicht
| Job | Zweck | Wann er läuft |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `preflight` | Erkennt reine Dokumentationsä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 Produktions-Lockfile-Audit gegen npm-Advisories | Immer bei Nicht-Entwurfs-Pushes und PRs |
| `security-fast` | Erforderliches Aggregat für die schnellen Sicherheitsjobs | Immer bei Nicht-Entwurfs-Pushes und PRs |
| `check-dependencies` | Reiner Produktions-Knip-Abhängigkeitsdurchlauf plus Allowlist-Schutz für ungenutzte 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` | 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: Produktionstypen, Lint, Guards, Testtypen und strikter Smoke-Test | Node-relevante Änderungen |
| `check-additional` | Architektur, Grenzen, Prompt-Snapshot-Drift, Erweiterungsflächen-Guards, Paketgrenzen und Gateway-Watch-Shards | Node-relevante Änderungen |
| `build-smoke` | Smoke-Tests der gebauten CLI und Smoke-Test für Startspeicher | Node-relevante Änderungen |
| `checks` | Verifizierer für Channel-Tests mit gebauten Artefakten | Node-relevante Änderungen |
| `checks-node-compat-node22` | Node-22-Kompatibilitäts-Build und Smoke-Lane | Manueller CI-Dispatch für Releases |
| `check-docs` | Dokumentationsformatierung, Lint und Broken-Link-Prüfungen | Dokumentation geändert |
| `skills-python` | Ruff + pytest für Python-gestützte Skills | Python-Skill-relevante Änderungen |
| `checks-windows` | Windows-spezifische Prozess-/Pfadtests plus gemeinsame Regressionen bei Runtime-Import-Spezifizierern | Windows-relevante Änderungen |
| `macos-node` | macOS-TypeScript-Test-Lane mit den gemeinsam genutzten gebauten Artefakten | macOS-relevante Änderungen |
| `macos-swift` | Swift-Lint, Build und Tests für die macOS-App | macOS-relevante Änderungen |
| `android` | Android-Unit-Tests für beide Varianten 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/bedarfsbasierte Kova-Runtime-Performanceberichte mit Mock-Provider-, Deep-Profile- und GPT-5.4-Live-Lanes | Geplanter und manueller Dispatch |
| Job | Zweck | Wann er ausgeführt wird |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `preflight` | Erkennt reine Dokumentationsänderungen, geänderte Scopes, geänderte Erweiterungen und erstellt das CI-Manifest | Immer bei nicht als Entwurf markierten Pushes und PRs |
| `security-scm-fast` | Erkennung privater Schlüssel und Workflow-Audit über `zizmor` | Immer bei nicht als Entwurf markierten Pushes und PRs |
| `security-dependency-audit` | Dependency-freier Audit des Produktions-Lockfiles gegen npm-Advisories | Immer bei nicht als Entwurf markierten Pushes und PRs |
| `security-fast` | Erforderliches Aggregat für die schnellen Sicherheitsjobs | Immer bei nicht als Entwurf markierten Pushes und PRs |
| `check-dependencies` | Produktions-Knip-Durchlauf nur für Dependencies plus Allowlist-Schutz für ungenutzte 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 Prüfungen für gebündelte Plugins, Plugin-Verträge und Protokolle | Node-relevante Änderungen |
| `checks-fast-contracts-channels` | Geshardete Channel-Contract-Prüfungen mit stabilem aggregiertem Prüfergebnis | Node-relevante Änderungen |
| `checks-node-core-test` | Core-Node-Test-Shards ohne Channel-, gebündelte, Contract- und Extension-Lanes | Node-relevante Änderungen |
| `check` | Geshardetes Äquivalent zum lokalen Haupt-Gate: Prod-Typen, Lint, Guards, Testtypen und strikter Smoke-Test | Node-relevante Änderungen |
| `check-additional` | Architektur-, Boundary-, Prompt-Snapshot-Drift-, Extension-Surface-, Package-Boundary- und Gateway-Watch-Shards | Node-relevante Änderungen |
| `build-smoke` | Smoke-Tests für die gebaute CLI und Startup-Memory-Smoke | Node-relevante Änderungen |
| `checks` | Verifier für 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` | Dokumentationsformatierung, Lint und Broken-Link-Prüfungen | Dokumentation geändert |
| `skills-python` | Ruff + pytest für Python-gestützte Skills | Python-Skill-relevante Änderungen |
| `checks-windows` | Windows-spezifische Prozess-/Pfadtests plus gemeinsame Regressionstests für 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 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/bedarfsbasierte Kova-Runtime-Performanceberichte 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 Logiken `docs-scope` und `changed-scope` sind Schritte innerhalb dieses Jobs, keine eigenständigen Jobs.
1. `preflight` entscheidet, welche Lanes überhaupt existieren. Die Logik `docs-scope` und `changed-scope` sind Schritte innerhalb dieses Jobs, keine eigenständigen Jobs.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` und `skills-python` schlagen schnell fehl, ohne auf die schwereren Artefakt- und Plattform-Matrix-Jobs zu warten.
3. `build-artifacts` überschneidet sich mit den schnellen Linux-Lanes, damit Downstream-Verbraucher starten können, sobald der gemeinsame Build bereit ist.
3. `build-artifacts` überlappt sich mit den schnellen Linux-Lanes, damit Downstream-Verbraucher 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 in die Warteschlange gehen, nachdem der gesamte Workflow bereits überholt wurde. Der automatische CI-Concurrency-Key ist versioniert (`CI-v7-*`), sodass ein GitHub-seitiger Zombie in einer alten Queue-Gruppe neuere main-Läufe nicht unbegrenzt blockieren kann. Manuelle vollständige Suite-Läufe verwenden `CI-manual-v1-*` und brechen laufende Läufe nicht ab.
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 die neueste Ausführung für denselben Ref fehlschlägt. Aggregierte Shard-Prüfungen verwenden `!cancelled() && always()`, sodass 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 Queue-Gruppe neuere Main-Ausführungen nicht unbegrenzt blockieren kann. Manuelle Full-Suite-Ausführungen verwenden `CI-manual-v1-*` und brechen laufende Ausführungen nicht ab.
## Scope und Routing
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 Changed-Scope-Erkennung 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 wird durch Unit-Tests in `src/scripts/ci-changed-scope.test.ts` abgedeckt. Manueller Dispatch überspringt die Changed-Scope-Erkennung und lässt das Preflight-Manifest so agieren, als hätte sich jeder gescopte Bereich geändert.
- **CI-Workflow-Änderungen** validieren den Node-CI-Graphen plus Workflow-Linting, erzwingen aber nicht von selbst native Windows-, Android- oder macOS-Builds; diese Plattform-Lanes bleiben auf Plattform-Quelländerungen beschränkt.
- **Reine CI-Routing-Änderungen, ausgewählte günstige Core-Test-Fixture-Änderungen und enge Plugin-Vertrags-Helfer-/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, gebündelte-Plugin-Shards und zusätzliche Guard-Matrizen, wenn die Änderung auf die Routing- oder Hilfsflächen beschränkt 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 beschränkt, die diese Lane ausführen; nicht zugehörige Quell-, Plugin-, Install-Smoke- und reine Teständerungen bleiben auf den Linux-Node-Lanes.
- **CI-Workflow-Bearbeitungen** 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 beschränkt.
- **CI-Bearbeitungen nur am Routing, ausgewählte günstige Core-Test-Fixture-Bearbeitungen und schmale Plugin-Contract-Helper-/Test-Routing-Bearbeitungen** 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-Contracts, 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 Quell-, 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, kleine Core-Unit-Lanes werden gepaart, Auto-Reply läuft als vier ausbalancierte Worker (wobei der Reply-Teilbaum in Agent-Runner-, Dispatch- und Commands/State-Routing-Shards aufgeteilt ist), und agentische Gateway-/Plugin-Konfigurationen werden über die bestehenden quellcodebasierten agentischen Node-Jobs verteilt, statt auf gebaute Artefakte 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 Paketgrenzen-Compile-/Canary-Arbeit zusammen und trennt Runtime-Topologie-Architektur von Gateway-Watch-Abdeckung; der Boundary-Guard-Shard führt seine kleinen unabhängigen Guards innerhalb eines Jobs parallel aus, einschließlich `pnpm prompt:snapshots:check`, sodass Codex-Happy-Path-Prompt-Drift an den PR gebunden wird, 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-Contracts laufen als drei gewichtete Shards, kleine Core-Unit-Lanes werden gepaart, Auto-Reply läuft als vier ausbalancierte Worker (wobei der Reply-Teilbaum in Agent-Runner-, Dispatch- und Commands/State-Routing-Shards aufgeteilt ist), und agentische Gateway-/Plugin-Konfigurationen werden auf die bestehenden source-only agentischen Node-Jobs verteilt, statt auf gebaute Artefakte zu warten. Breite Browser-, QA-, Medien- und sonstige Plugin-Tests verwenden ihre dedizierten Vitest-Konfigurationen statt des gemeinsamen Plugin-Catch-all. Include-Pattern-Shards zeichnen Timing-Einträge mit dem CI-Shard-Namen auf, sodass `.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-Topology-Architektur von Gateway-Watch-Abdeckung; der Boundary-Guard-Shard führt seine kleinen unabhängigen Guards innerhalb eines Jobs parallel aus, einschließlich `pnpm prompt:snapshots:check`, sodass Prompt-Drift im Codex-Runtime-Happy-Path an den verursachenden PR gebunden ist. Gateway-Watch-, Channel-Tests und der Core-Support-Boundary-Shard laufen innerhalb von `build-artifacts` parallel, nachdem `dist/` und `dist-runtime/` bereits gebaut wurden.
Android-CI führt sowohl `testPlayDebugUnitTest` als auch `testThirdPartyDebugUnitTest` aus und baut anschließend das Play-Debug-APK. Die Drittanbieter-Variante hat kein separates Source Set oder Manifest; ihre Unit-Test-Lane kompiliert die Variante dennoch mit den SMS-/Anrufprotokoll-`BuildConfig`-Flags, während ein doppelter Debug-APK-Paketierungsjob bei jedem Android-relevanten Push vermieden wird.
Android CI führt sowohl `testPlayDebugUnitTest` als auch `testThirdPartyDebugUnitTest` aus und baut anschließend das Play-Debug-APK. Der Third-Party-Flavor hat kein separates Source Set oder Manifest; seine Unit-Test-Lane kompiliert den Flavor dennoch mit den SMS-/Call-Log-BuildConfig-Flags und vermeidet gleichzeitig einen doppelten Debug-APK-Packaging-Job bei jedem Android-relevanten Push.
Der Shard `check-dependencies` führt `pnpm deadcode:dependencies` (einen reinen Produktions-Knip-Abhängigkeitsdurchlauf, gepinnt 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 ungeprüfte ungenutzte Datei hinzufügt oder einen veralteten Allowlist-Eintrag hinterlä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 Shard `check-dependencies` führt `pnpm deadcode:dependencies` (einen Produktions-Knip-Durchlauf nur für Dependencies, 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 Knip's Produktionsbefunde zu ungenutzten Dateien mit `scripts/deadcode-unused-files.allowlist.mjs` vergleicht. Der Guard für ungenutzte Dateien schlägt fehl, wenn ein PR eine neue nicht überprüfte ungenutzte Datei hinzufügt oder einen veralteten Allowlist-Eintrag zurücklässt, während absichtliche dynamische Plugin-, generierte, Build-, Live-Test- und Package-Bridge-Oberflächen erhalten bleiben, die Knip statisch nicht auflösen kann.
## ClawSweeper-Aktivitätsweiterleitung
## Weiterleitung von ClawSweeper-Aktivitäten
`.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 ein GitHub-App-Token aus `CLAWSWEEPER_APP_PRIVATE_KEY` und dispatcht dann kompakte `repository_dispatch`-Payloads an `openclaw/clawsweeper`.
`.github/workflows/clawsweeper-dispatch.yml` ist die zielseitige Brücke von OpenClaw-Repository-Aktivitäten 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`.
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 prüfen kann.
- `github_activity` für allgemeine GitHub-Aktivitäten, die der ClawSweeper-Agent prüfen kann.
Die Lane `github_activity` leitet nur normalisierte Metadaten weiter: Ereignistyp, Aktion, Akteur, Repository, Elementnummer, URL, Titel, Status und kurze Auszüge für Kommentare oder Reviews, sofern vorhanden. Sie vermeidet bewusst, den vollständigen Webhook-Body weiterzuleiten. 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 sendet.
Die Lane `github_activity` leitet nur normalisierte Metadaten weiter: Ereignistyp, Aktion, Actor, Repository, Item-Nummer, URL, Titel, Zustand und kurze Auszüge für Kommentare oder Reviews, sofern vorhanden. Sie vermeidet absichtlich 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 in `#clawsweeper` posten, wenn das Ereignis überraschend, handlungsrelevant, riskant oder operativ nützlich ist. Routinemäßige Eröffnungen, Bearbeitungen, Bot-Fluktuation, doppeltes Webhook-Rauschen und normaler Review-Verkehr sollten zu `NO_REPLY` führen.
Allgemeine Aktivität ist Beobachtung, keine 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, Bearbeiten, 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 entlang dieses gesamten Pfads 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, Bodys, Review-Text, Branch-Namen und Commit-Nachrichten auf 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 normale CI aus, erzwingen aber jede nicht auf Android beschränkte Lane: Linux Node-Shards, Shards für gebündelte Plugins, Kanalverträ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; das 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, der vollständige Batch-Sweep für Extensions 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 aktiviertem Release-Validation-Gate auslöst.
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, gebündelte Plugin-Shards, Channel-Contracts, 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, der vollständige Erweiterungs-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 Workflow `Plugin Prerelease` mit aktiviertem Release-Validierungs-Gate auslöst.
Manuelle Läufe verwenden eine eindeutige Concurrency-Gruppe, damit eine vollständige Release-Candidate-Suite nicht durch einen anderen Push- oder PR-Lauf auf demselben Ref abgebrochen wird. Die optionale Eingabe `target_ref` erlaubt es 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 Nebenläufigkeitsgruppe, damit eine vollständige Release-Candidate-Suite nicht durch einen anderen Push- oder PR-Lauf auf derselben Ref abgebrochen wird. Die optionale Eingabe `target_ref` ermöglicht es 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 der 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=<branch-or-sha>
## Runner
| Runner | Jobs |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`, schnelle Sicherheitsjobs und Aggregate (`security-scm-fast`, `security-dependency-audit`, `security-fast`), schnelle Protokoll-/Vertrags-/Bundled-Prüfungen, geshardete Kanalvertragsprüfungen, `check`-Shards außer Lint, `check-additional`-Shards und Aggregate, Aggregat-Verifier für Node-Tests, Dokumentationsprüfungen, Python-Skills, Workflow-Sanity, Labeler, Auto-Response; die Install-Smoke-Preflight verwendet ebenfalls GitHub-gehostetes Ubuntu, damit die Blacksmith-Matrix früher in die Warteschlange eingereiht 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 kosteten, als sie einsparten); Install-Smoke-Docker-Builds (32-vCPU-Warteschlangenzeit kostete mehr, als sie einsparten) |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` auf `openclaw/openclaw`; Forks fallen auf `macos-latest` zurück |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` auf `openclaw/openclaw`; Forks fallen auf `macos-latest` zurück |
| Runner | Jobs |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`, schnelle Security-Jobs und Aggregate (`security-scm-fast`, `security-dependency-audit`, `security-fast`), schnelle Protokoll-/Contract-/gebündelte Prüfungen, geshardete Channel-Contract-Prüfungen, `check`-Shards außer Lint, `check-additional`-Shards und Aggregate, Node-Test-Aggregatverifizierer, Dokumentationsprü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 kann |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, weniger aufwendige 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-sensibel genug, dass 8 vCPU mehr gekostet haben, als sie eingespart haben); Install-Smoke-Docker-Builds (32-vCPU-Warteschlangenzeit hat mehr gekostet, als sie eingespart hat) |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` auf `openclaw/openclaw`; Forks fallen auf `macos-latest` zurück |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` auf `openclaw/openclaw`; Forks fallen auf `macos-latest` zurück |
## Lokale Entsprechungen
@ -135,7 +135,7 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac
pnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.json --output .artifacts/kova/summary.md
```
## OpenClaw Performance
## OpenClaw-Performance
`OpenClaw Performance` ist der Workflow für Produkt-/Runtime-Performance. Er läuft täglich auf `main` und kann manuell ausgelöst werden:
@ -146,28 +146,28 @@ gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1
Der Workflow installiert OCM aus einem gepinnten Release und Kova aus der gepinnten Eingabe `kova_ref` und führt dann drei Lanes aus:
- `mock-provider`: Kova-Diagnoseszenarien gegen eine Runtime aus lokalem Build mit deterministischer Fake-OpenAI-kompatibler Authentifizierung.
- `mock-deep-profile`: CPU-/Heap-/Trace-Profiling für Hotspots bei Start, Gateway und Agent-Turn.
- `live-gpt54`: ein echter OpenAI-`openai/gpt-5.4`-Agent-Turn, der übersprungen wird, wenn `OPENAI_API_KEY` nicht verfügbar ist.
- `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 Hotspots beim Start, Gateway und Agent-Turn.
- `live-gpt54`: ein echter Agent-Turn mit OpenAI `openai/gpt-5.4`, der übersprungen wird, wenn `OPENAI_API_KEY` nicht verfügbar ist.
Die Mock-Provider-Lane führt nach dem Kova-Durchlauf auch OpenClaw-native Source-Probes aus: Gateway-Startzeit und Speicher über Standard-, Hook- und 50-Plugin-Startfälle hinweg; wiederholte Mock-OpenAI-`channel-chat-baseline`-Hello-Loops; und CLI-Startbefehle gegen das gebootete Gateway. Die Markdown-Zusammenfassung der Source-Probes liegt unter `source/index.md` im Report-Bundle, mit Roh-JSON daneben.
Die Mock-Provider-Lane führt nach dem Kova-Durchlauf außerdem OpenClaw-native Source-Probes aus: Gateway-Startzeit 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 befindet sich unter `source/index.md` im Report-Bundle, 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`, Bundles, `index.md` und Source-Probe-Artefakte nach `openclaw/clawgrit-reports` unter `openclaw-performance/<ref>/<run-id>-<attempt>/<lane>/`. Der aktuelle Branch-Zeiger wird als `openclaw-performance/<ref>/latest-<lane>.json` geschrieben.
## Full Release Validation
## 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 im Release vorgesehene Plugin-/Paket-/statische/Docker-Nachweise und dispatcht `OpenClaw Release Checks` für Install-Smoke, Paketakzeptanz, Docker-Release-Path-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 Checks 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, löst den manuellen `CI`-Workflow mit diesem Ziel aus, löst `Plugin Prerelease` für nur im Release verwendete Plugin-/Paket-/Static-/Docker-Nachweise aus und löst `OpenClaw Release Checks` für Install-Smoke, Package Acceptance, Docker-Release-Pfad-Suites, Live/E2E, OpenWebUI, QA-Lab-Parität, Matrix- und Telegram-Lanes aus. 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-Checks 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.
Siehe [Vollständige Release-Validierung](/de/reference/full-release-validation) für die
Stage-Matrix, exakte Workflow-Jobnamen, Profilunterschiede, Artefakte und
fokussierte 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 die
`OpenClaw Release Publish` ist der manuelle mutierende Release-Workflow. Lösen Sie ihn
von `release/YYYY.M.D` oder `main` aus, 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 denselben Release-SHA und dispatcht erst dann
`OpenClaw NPM Release` mit der gespeicherten `preflight_run_id`.
löst `Plugin NPM Release` für alle veröffentlichbaren Plugin-Pakete aus, löst
`Plugin ClawHub Release` für dieselbe Release-SHA aus und löst erst dann
`OpenClaw NPM Release` mit der gespeicherten `preflight_run_id` aus.
```bash
gh workflow run openclaw-release-publish.yml \
@ -177,7 +177,7 @@ gh workflow run openclaw-release-publish.yml \
-f npm_dist_tag=beta
```
Für einen Nachweis mit gepinntem Commit auf einem schnelllebigen Branch verwenden Sie den Helper statt
Für einen gepinnten Commit-Nachweis auf einem sich schnell bewegenden Branch verwenden Sie den Helper statt
`gh workflow run ... --ref main -f ref=<sha>`:
```bash
@ -185,35 +185,35 @@ pnpm ci:full-release --sha <full-sha>
```
GitHub-Workflow-Dispatch-Refs müssen Branches oder Tags sein, keine rohen Commit-SHAs. Der
Helper pusht einen temporären Branch `release-ci/<sha>-...` auf dem 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-Verifier schlägt außerdem fehl, wenn ein untergeordneter Workflow mit einem
Helper pusht einen temporären Branch `release-ci/<sha>-...` an der Ziel-SHA,
löst `Full Release Validation` von dieser gepinnten Ref aus, verifiziert, dass jede
Child-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 ein Child-Workflow mit einer
anderen SHA lief.
`release_profile` steuert die Live-/Provider-Breite, die an Release Checks übergeben wird. Die
`release_profile` steuert die Live-/Provider-Breite, die an Release-Checks übergeben wird. Die
manuellen Release-Workflows verwenden standardmäßig `stable`; verwenden Sie `full` nur, wenn Sie
absichtlich die breite advisory Provider-/Medien-Matrix möchten.
absichtlich die breite beratende Provider-/Medien-Matrix wünschen.
- `minimum` behält die schnellsten OpenAI-/Core-releasekritischen Lanes bei.
- `stable` fügt den stabilen Provider-/Backend-Satz hinzu.
- `full` führt die breite advisory Provider-/Medien-Matrix aus.
- `full` führt die breite beratende Provider-/Medien-Matrix aus.
Das Umbrella zeichnet die ausgelösten untergeordneten Run-IDs auf, und der abschließende Job `Verify full validation` prüft die aktuellen Conclusions der untergeordneten Läufe erneut und hängt Tabellen der langsamsten Jobs für jeden untergeordneten Lauf an. Wenn ein untergeordneter Workflow erneut ausgeführt wird und grün wird, führen Sie nur den übergeordneten Verifier-Job erneut aus, um das Umbrella-Ergebnis und die Timing-Zusammenfassung zu aktualisieren.
Der Umbrella zeichnet die ausgelösten Child-Run-IDs auf, und der abschließende Job `Verify full validation` prüft die aktuellen Child-Run-Ergebnisse 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 übergeordneten Verifiziererjob 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 Candidate, `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` im Umbrella. Dadurch bleibt die erneute Ausführung einer fehlgeschlagenen Release-Box nach einem gezielten Fix begrenzt.
`OpenClaw Release Checks` verwendet den vertrauenswürdigen Workflow-Ref, um den ausgewählten Ref einmal in ein `release-package-under-test`-Tarball aufzulösen, und übergibt dieses Artefakt dann sowohl an den Live/E2E-Docker-Workflow für den Release-Pfad als auch an den Package-Acceptance-Shard. Dadurch bleiben die Package-Bytes über Release-Boxen hinweg konsistent, und derselbe Candidate muss nicht in mehreren Child-Jobs erneut gepackt werden.
`OpenClaw Release Checks` verwendet den vertrauenswürdigen Workflow-Ref, um den ausgewählten Ref einmal in ein `release-package-under-test`-Tarball aufzulösen, und übergibt dieses Artefakt dann sowohl an den Live/E2E-Docker-Workflow für den Release-Pfad als auch an den Package-Acceptance-Shard. Dadurch bleiben die Paketbytes über Release-Boxen hinweg konsistent und dasselbe Candidate wird nicht in mehreren Child-Jobs erneut gepackt.
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
Doppelte `Full Release Validation`-Läufe für `ref=main` und `rerun_group=all`
ersetzen das ältere Umbrella. Der Parent-Monitor bricht jeden Child-Workflow ab, den er
bereits ausgelöst hat, wenn der Parent abgebrochen wird, sodass neuere Main-Validierung
nicht hinter einem veralteten zweistündigen Release-Check-Run wartet. Release-Branch/Tag-
Validierung und fokussierte Rerun-Gruppen behalten `cancel-in-progress: false`.
nicht hinter einem veralteten zweistündigen Release-Check-Lauf wartet. Validierung von Release-Branches/-Tags
und gezielte Rerun-Gruppen behalten `cancel-in-progress: false`.
## Live- und E2E-Shards
Das Release-Live/E2E-Child behält die breite native `pnpm test:live`-Abdeckung bei, führt sie jedoch als benannte Shards über `scripts/test-live-shard.mjs` aus statt als einen seriellen Job:
Das Release-Live/E2E-Child behält breite native `pnpm test:live`-Abdeckung bei, führt sie aber als benannte Shards über `scripts/test-live-shard.mjs` statt als einen seriellen Job aus:
- `native-live-src-agents`
- `native-live-src-gateway-core`
@ -225,33 +225,33 @@ Das Release-Live/E2E-Child behält die breite native `pnpm test:live`-Abdeckung
- `native-live-extensions-openai`
- `native-live-extensions-o-z-other`
- `native-live-extensions-xai`
- aufgeteilte Medien-Audio/Video-Shards und Provider-gefilterte Musik-Shards
- Aufgeteilte Media-Audio/Video-Shards und Provider-gefilterte Musik-Shards
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 einmalige Reruns gültig.
Dadurch bleibt dieselbe Datei-Abdeckung erhalten, während langsame Live-Provider-Fehler leichter erneut auszuführen und zu diagnostizieren sind. Die aggregierten Shard-Namen `native-live-extensions-o-z`, `native-live-extensions-media` und `native-live-extensions-media-music` bleiben für manuelle One-Shot-Reruns gültig.
Die nativen Live-Medien-Shards laufen in `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, gebaut durch den Workflow `Live Media Runner Image`. Dieses Image installiert `ffmpeg` und `ffprobe` vor; Medien-Jobs prüfen vor dem Setup nur die Binärdateien. Lassen Sie Docker-gestützte Live-Suites auf normalen Blacksmith-Runnern laufen — Container-Jobs sind der falsche Ort, um verschachtelte Docker-Tests zu starten.
Die nativen Live-Media-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` vorab; Media-Jobs prüfen vor dem Setup nur die Binärdateien. Lassen Sie Docker-gestützte Live-Suites auf normalen Blacksmith-Runnern laufen — 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:<sha>` 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 haben 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 mit doppelten Image-Builds.
Docker-gestützte Live-Modell-/Backend-Shards verwenden ein separates gemeinsames Image `ghcr.io/openclaw/openclaw-live-test:<sha>` pro ausgewähltem Commit. Der Live-Release-Workflow baut und pusht dieses Image einmal, dann laufen die Docker-Live-Modell-, Provider-Sharded-Gateway-, CLI-Backend-, ACP-Bind- und Codex-Harness-Shards mit `OPENCLAW_SKIP_DOCKER_BUILD=1`. Gateway-Docker-Shards haben explizite Timeout-Obergrenzen auf Skriptebene unterhalb des Workflow-Job-Timeouts, 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-Lauf falsch konfiguriert und verschwendet Laufzeit mit doppelten Image-Builds.
## Package Acceptance
Verwenden Sie `Package Acceptance`, wenn die Frage lautet: „Funktioniert dieses installierbare OpenClaw-Package als Produkt?“ Sie unterscheidet sich von normaler CI: Normale CI validiert den Source Tree, während Package Acceptance ein einzelnes Tarball über denselben Docker-E2E-Harness validiert, den Benutzer nach Installation oder Update ausführen.
Verwenden Sie `Package Acceptance`, wenn die Frage lautet: „Funktioniert dieses installierbare OpenClaw-Paket als Produkt?“ Es unterscheidet sich von normaler CI: Normale CI validiert den Source Tree, während Package Acceptance ein einzelnes Tarball über dasselbe Docker-E2E-Harness validiert, das Nutzer nach Installation oder Update ausführen.
### Jobs
1. `resolve_package` checkt `workflow_ref` aus, löst einen Package-Candidate 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, Package-Ref, 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 Package aus, statt den Workflow-Checkout zu packen. Wenn ein Profil mehrere gezielte `docker_lanes` auswählt, bereitet der wiederverwendbare Workflow das Package und die gemeinsamen Images einmal vor und fächert diese Lanes dann als parallele gezielte Docker-Jobs mit eindeutigen Artefakten aus.
1. `resolve_package` checkt `workflow_ref` aus, löst einen Paket-Candidate 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-Summary 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; eigenständige Telegram-Dispatches können weiterhin eine veröffentlichte npm-Spezifikation installieren.
4. `summary` lässt den Workflow fehlschlagen, wenn Package-Auflösung, Docker Acceptance oder die optionale Telegram-Lane fehlgeschlagen ist.
4. `summary` lässt den Workflow fehlschlagen, wenn Paketauflösung, Docker Acceptance oder die optionale Telegram-Lane fehlgeschlagen ist.
### Candidate-Quellen
- `source=npm` akzeptiert nur `openclaw@alpha`, `openclaw@beta`, `openclaw@latest` oder eine exakte OpenClaw-Release-Version wie `openclaw@2026.4.27-beta.2`. Verwenden Sie dies für veröffentlichte Prerelease-/Stable-Abnahme.
- `source=ref` packt einen vertrauenswürdigen `package_ref`-Branch, -Tag oder vollständigen Commit-SHA. Der Resolver ruft OpenClaw-Branches/Tags ab, prüft, dass der ausgewählte Commit aus der Repository-Branch-Historie oder einem Release-Tag erreichbar ist, installiert Dependencies in einem detached Worktree und packt ihn mit `scripts/package-openclaw-for-docker.mjs`.
- `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 veröffentlichte Prerelease-/Stable-Acceptance.
- `source=ref` packt einen vertrauenswürdigen `package_ref`-Branch, -Tag oder vollständigen Commit-SHA. Der Resolver ruft OpenClaw-Branches/-Tags ab, überprüft, dass 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 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` gilt. Dadurch kann der 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 das aktuelle Test-Harness ältere vertrauenswürdige Source-Commits validieren, ohne alte Workflow-Logik auszuführen.
### Suite-Profile
@ -261,25 +261,25 @@ Halten Sie `workflow_ref` und `package_ref` getrennt. `workflow_ref` ist der ver
- `full` — vollständige Docker-Release-Pfad-Chunks mit OpenWebUI
- `custom` — exakte `docker_lanes`; erforderlich, wenn `suite_profile=custom`
Das Profil `package` verwendet Offline-Plugin-Abdeckung, damit die Validierung veröffentlichter Packages nicht von Live-ClawHub-Verfügbarkeit abhängt. Die optionale Telegram-Lane verwendet das Artefakt `package-under-test` in `NPM Telegram Beta E2E` wieder; der veröffentlichte npm-Spezifikationspfad bleibt für eigenständige Dispatches erhalten.
Das Profil `package` verwendet Offline-Plugin-Abdeckung, sodass die Validierung veröffentlichter Pakete nicht von Live-ClawHub-Verfügbarkeit abhängt. Die optionale Telegram-Lane verwendet das Artefakt `package-under-test` in `NPM Telegram Beta E2E` wieder; der veröffentlichte npm-Spezifikationspfad bleibt für eigenständige Dispatches erhalten.
Die dedizierte Update- und Plugin-Testpolicy, einschließlich lokaler Befehle,
Zur dedizierten Richtlinie für Update- und Plugin-Tests, einschließlich lokaler Befehle,
Docker-Lanes, Package-Acceptance-Eingaben, Release-Defaults und Fehlertriage,
finden Sie unter [Updates und Plugins testen](/de/help/testing-updates-plugins).
siehe [Testen von Updates und Plugins](/de/help/testing-updates-plugins).
Release Checks rufen Package Acceptance mit `source=artifact`, dem 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` auf. Dadurch bleiben Package-Migration, Update, Cleanup veralteter Plugin-Dependency, Reparatur installierter konfigurierter Plugins, Offline-Plugin, Plugin-Update und Telegram-Nachweis auf demselben aufgelösten Package-Tarball. Setzen Sie `package_acceptance_package_spec` für Full Release Validation oder OpenClaw Release Checks, um dieselbe Matrix gegen ein ausgeliefertes npm-Package statt gegen das aus dem SHA gebaute Artefakt auszuführen. Cross-OS Release Checks decken weiterhin OS-spezifisches Onboarding, Installer- und Plattformverhalten ab; Produktvalidierung für Package/Update sollte mit Package Acceptance beginnen. Die Docker-Lane `published-upgrade-survivor` validiert pro Run eine veröffentlichte Package-Baseline. In Package Acceptance ist das aufgelöste Tarball `package-under-test` immer der Candidate, 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 jede stabile npm-Version von `2026.4.23` bis `latest` zu erweitern; `release-history` bleibt für manuelle breitere Stichproben mit dem älteren Vordatums-Anker verfügbar. Setzen Sie `published_upgrade_survivor_scenarios=reported-issues`, um dieselben Baselines über issue-förmige Fixtures für Feishu-Konfiguration, erhaltene Bootstrap-/Persona-Dateien, konfigurierte OpenClaw-Plugin-Installationen, Tilde-Logpfade und veraltete Legacy-Plugin-Dependency-Roots zu erweitern. Der separate Workflow `Update Migration` verwendet die Docker-Lane `update-migration` mit `all-since-2026.4.23` und `plugin-deps-cleanup`, wenn die Frage eine vollständige Cleanup-Prüfung veröffentlichter Updates ist und nicht die normale Breite von Full Release CI. Lokale Aggregat-Runs können exakte Package-Spezifikationen mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` übergeben, eine einzelne Lane mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` wie `openclaw@2026.4.15` beibehalten oder `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` für die Szenario-Matrix setzen. Die veröffentlichte Lane konfiguriert die Baseline mit einem eingebauten `openclaw config set`-Befehlsrezept, zeichnet Rezeptschritte in `summary.json` auf und prüft nach Gateway-Start `/healthz`, `/readyz` sowie RPC-Status. Die frischen Windows-Packaged- und Installer-Lanes prüfen außerdem, dass ein installiertes Package 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-Defaults vermieden werden.
Release-Checks rufen Package Acceptance mit `source=artifact`, dem 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` auf. Dadurch bleiben Paketmigration, Update, Bereinigung veralteter Plugin-Abhängigkeiten, Installationsreparatur für konfigurierte 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 dem SHA gebaute Artefakt auszuführen. Cross-OS-Release-Checks decken weiterhin betriebssystemspezifisches Onboarding-, Installer- und Plattformverhalten ab; Produktvalidierung für Pakete/Updates sollte mit Package Acceptance beginnen. Die Docker-Lane `published-upgrade-survivor` validiert eine veröffentlichte Paket-Baseline pro Lauf. In Package Acceptance ist das aufgelöste Tarball `package-under-test` immer der Candidate, und `published_upgrade_survivor_baseline` wählt die veröffentlichte Fallback-Baseline aus, standardmäßig `openclaw@latest`; Befehle zur erneuten Ausführung fehlgeschlagener 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 Pre-Date-Anker verfügbar. Setzen Sie `published_upgrade_survivor_scenarios=reported-issues`, um dieselben Baselines über issue-förmige Fixtures für Feishu-Konfiguration, erhaltene Bootstrap-/Persona-Dateien, konfigurierte OpenClaw-Plugin-Installationen, Tilde-Logpfade und veraltete Legacy-Plugin-Abhängigkeits-Roots 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 erschöpfende veröffentlichte Update-Bereinigung geht, nicht um normale Full-Release-CI-Breite. Lokale aggregierte Läufe 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` beibehalten oder `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` für die Szenario-Matrix 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 frischen Windows-Packaged- und Installer-Lanes prüfen 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 Installations- und Gateway-Nachweis auf einem GPT-5-Testmodell bleiben und GPT-4.x-Defaults vermieden werden.
### Legacy-Kompatibilitätsfenster
Package Acceptance hat begrenzte Legacy-Kompatibilitätsfenster für bereits veröffentlichte Packages. Packages bis `2026.4.25`, einschließlich `2026.4.25-beta.*`, dürfen 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.*`, können den Kompatibilitätspfad verwenden:
- bekannte private QA-Einträge in `dist/postinstall-inventory.json` dürfen auf Dateien zeigen, die im Tarball fehlen;
- `doctor-switch` darf den Teilfall zur Persistenz von `gateway install --wrapper` überspringen, wenn das Package dieses Flag nicht bereitstellt;
- `update-channel-switch` darf fehlende `pnpm.patchedDependencies` aus der vom Tarball abgeleiteten Fake-Git-Fixture entfernen und fehlendes persistiertes `update.channel` protokollieren;
- Plugin-Smokes dürfen Legacy-Speicherorte von Installationsdatensätzen lesen oder fehlende Marketplace-Persistenz von Installationsdatensätzen akzeptieren;
- `plugin-update` darf Konfigurationsmetadaten-Migration zulassen, während weiterhin verlangt wird, dass Installationsdatensatz 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 fehlen;
- `doctor-switch` darf den Unterfall zur 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 Marketplace-Install-Record-Persistenz akzeptieren;
- `plugin-update` darf die Migration von Konfigurationsmetadaten zulassen, während weiterhin gefordert wird, dass Install Record und No-Reinstall-Verhalten unverändert bleiben.
Das veröffentlichte Package `2026.4.26` darf außerdem vor lokal gebauten Metadaten-Stamp-Dateien warnen, die bereits ausgeliefert wurden. Spätere Packages 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 auch vor lokal bereits ausgelieferten Build-Metadaten-Stamp-Dateien warnen. Spätere Pakete müssen die modernen Verträge erfüllen; dieselben Bedingungen schlagen dann fehl, statt zu warnen oder übersprungen zu werden.
### Beispiele
@ -322,60 +322,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 `resolve_package`-Zusammenfassung, um Paketquelle, Version und SHA-256 zu bestätigen. Prüfen Sie anschließend den untergeordneten `docker_acceptance`-Lauf und seine Docker-Artefakte: `.artifacts/docker-tests/**/summary.json`, `failures.json`, Lane-Logs, Phasenzeiten 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.
Beginnen Sie beim Debuggen eines fehlgeschlagenen Paketakzeptanzlaufs 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-Logs, Phasen-Timings und Befehle zum erneuten Ausführen. Führen Sie bevorzugt das fehlgeschlagene Paketprofil oder die exakten Docker-Lanes erneut aus, statt die vollständige Release-Validierung erneut zu starten.
## Installations-Smoke-Test
Der separate Workflow `Install Smoke` verwendet dasselbe Scope-Skript über seinen eigenen `preflight`-Job wieder. Er teilt die Smoke-Abdeckung in `run_fast_install_smoke` und `run_full_install_smoke` auf.
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 betreffen, die von den Docker-Smoke-Jobs geprüft werden. Reine Source-Ä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 Agents-Delete-Shared-Workspace-CLI-Smoke-Test aus, führt das Container-Gateway-Network-E2E aus, verifiziert ein Build-Argument für gebündelte Erweiterungen und führt das begrenzte gebündelte-Plugin-Docker-Profil unter einem aggregierten Befehls-Timeout von 240 Sekunden aus (jeder Docker-Lauf eines Szenarios ist separat begrenzt).
- **Vollständiger Pfad** behält QR-Paketinstallation sowie Installer-Docker-/Update-Abdeckung für nächtlich geplante Läufe, manuelle Dispatches, Workflow-Call-Release-Checks und Pull Requests bei, die tatsächlich Installer-/Paket-/Docker-Oberflächen betreffen. Im vollständigen Modus bereitet Install-Smoke ein Root-Dockerfile-Smoke-Image aus GHCR für die Ziel-SHA vor oder verwendet es wieder und führt dann QR-Paketinstallation, Root-Dockerfile-/Gateway-Smokes, Installer-/Update-Smokes und das schnelle gebündelte-Plugin-Docker-E2E als separate Jobs aus, damit Installer-Arbeit nicht hinter den Root-Image-Smokes warten muss.
- **Schneller Pfad** läuft für Pull Requests, die Docker-/Paketoberflächen, Änderungen an gebündelten Plugin-Paketen/-Manifesten oder Kernoberflächen für Plugin/Kanal/Gateway/Plugin SDK 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 des gemeinsamen Arbeitsbereichs der Agents aus, führt den Container-Gateway-Netzwerk-E2E-Test aus, verifiziert ein Build-Argument für gebündelte Erweiterungen und führt das begrenzte gebündelte-Plugin-Docker-Profil mit einem aggregierten Befehls-Timeout von 240 Sekunden aus, wobei jeder Docker-Lauf eines Szenarios separat begrenzt ist.
- **Vollständiger Pfad** behält QR-Paketinstallation sowie Installer-Docker-/Update-Abdeckung für nächtlich geplante Läufe, manuelle Dispatches, Workflow-Call-Release-Checks und Pull Requests bei, die tatsächlich Installer-/Paket-/Docker-Oberflächen berühren. Im vollständigen Modus bereitet install-smoke ein Ziel-SHA-GHCR-Root-Dockerfile-Smoke-Image vor oder verwendet es wieder und führt dann QR-Paketinstallation, Root-Dockerfile-/Gateway-Smokes, Installer-/Update-Smokes und das schnelle gebündelte-Plugin-Docker-E2E als separate Jobs aus, damit Installer-Arbeit nicht hinter den Root-Image-Smokes warten muss.
`main`-Pushes (einschließlich Merge-Commits) erzwingen den vollständigen Pfad nicht; 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 den vollständigen Pfad nicht; 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 durch `run_bun_global_install_smoke` gesteuert. Er läuft im nächtlichen Zeitplan und aus dem Release-Checks-Workflow, und manuelle `Install Smoke`-Dispatches können ihn optional aktivieren, Pull Requests und `main`-Pushes jedoch nicht. QR- und Installer-Docker-Tests behalten ihre eigenen installfokussierten 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 Release-Checks-Workflow heraus, und manuelle `Install Smoke`-Dispatches können ihn aktivieren, Pull Requests und `main`-Pushes jedoch nicht. QR- und Installer-Docker-Tests behalten ihre eigenen installfokussierten Dockerfiles.
## Lokales Docker-E2E
`pnpm test:docker:all` baut ein gemeinsames Live-Test-Image vor, packt OpenClaw einmal als npm-Tarball und baut zwei gemeinsame `scripts/e2e/Dockerfile`-Images:
`pnpm test:docker:all` baut ein gemeinsames Live-Test-Image vorab, packt OpenClaw einmal als npm-Tarball und baut zwei gemeinsame `scripts/e2e/Dockerfile`-Images:
- einen einfachen Node-/Git-Runner für Installer-/Update-/Plugin-Abhängigkeits-Lanes;
- ein funktionsfähiges Image, das denselben Tarball für normale Funktions-Lanes in `/app` installiert.
- ein funktionales Image, das denselben Tarball für normale Funktions-Lanes nach `/app` installiert.
Docker-Lane-Definitionen befinden sich in `scripts/lib/docker-e2e-scenarios.mjs`, die Planerlogik 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 Lanes dann mit `OPENCLAW_SKIP_DOCKER_BUILD=1` aus.
Docker-Lane-Definitionen befinden sich in `scripts/lib/docker-e2e-scenarios.mjs`, die Planerlogik 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 Lanes anschließend mit `OPENCLAW_SKIP_DOCKER_BUILD=1` aus.
### Einstellbare Parameter
| Variable | Standard | Zweck |
| -------------------------------------- | -------- | --------------------------------------------------------------------------------------------- |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Slot-Anzahl im Hauptpool 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 | Versatz zwischen Lane-Starts, um Docker-Daemon-Create-Stürme zu vermeiden; `0` deaktiviert den Versatz. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Fallback-Timeout pro Lane (120 Minuten); ausgewählte Live-/Tail-Lanes verwenden strengere Limits. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` gibt den Scheduler-Plan aus, ohne Lanes auszuführen. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | Durch Kommas getrennte exakte Lane-Liste; überspringt Cleanup-Smoke, damit Agents eine fehlgeschlagene Lane reproduzieren können. |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Slot-Anzahl des Haupt-Pools für normale Lanes. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Provider-sensible Slot-Anzahl des Tail-Pools. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Obergrenze für gleichzeitige Live-Lanes, damit Provider nicht drosseln. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Obergrenze für gleichzeitige npm-Install-Lanes. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Obergrenze für gleichzeitige Multi-Service-Lanes. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Staffelung zwischen Lane-Starts zur Vermeidung von Docker-Daemon-Erstellungswellen; setzen Sie `0` für keine Staffelung. |
| `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 | Durch Kommas getrennte exakte Lane-Liste; überspringt den Cleanup-Smoke, damit Agents eine fehlgeschlagene Lane reproduzieren können. |
Eine Lane, die schwerer ist als ihr effektives Limit, kann dennoch aus einem leeren Pool starten und läuft dann allein, bis sie Kapazität freigibt. Die lokale aggregierte Vorprüfung prüft Docker, entfernt veraltete OpenClaw-E2E-Container, gibt den Status aktiver Lanes aus, speichert Lane-Zeiten für Longest-First-Sortierung und plant standardmäßig nach dem ersten Fehler keine neuen gepoolten Lanes mehr ein.
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 führt Docker-Preflights aus, entfernt veraltete OpenClaw-E2E-Container, gibt den Status aktiver Lanes aus, persistiert Lane-Timings für Longest-first-Sortierung und stoppt standardmäßig nach dem ersten Fehler die Planung neuer gepoolter Lanes.
### Wiederverwendbarer Live-/E2E-Workflow
Der wiederverwendbare Live-/E2E-Workflow fragt `scripts/test-docker-all.mjs --plan-json`, welche Paket-, Image-Art, welches Live-Image sowie welche Lane- und Zugangsdaten-Abdeckung erforderlich sind. `scripts/docker-e2e.mjs` wandelt diesen Plan dann in GitHub-Ausgaben und Zusammenfassungen um. Es packt 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`; validiert das Tarball-Inventar; baut und pusht paketdigest-getaggte Bare-/Functional-GHCR-Docker-E2E-Images über Blacksmiths Docker-Layer-Cache, wenn der Plan Lanes mit installiertem Paket benötigt; und verwendet angegebene Eingaben `docker_e2e_bare_image`/`docker_e2e_functional_image` oder vorhandene Paketdigest-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 erneut 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-Art-, Live-Image-, Lane- und Zugangsdatenabdeckung erforderlich ist. `scripts/docker-e2e.mjs` wandelt diesen Plan anschließend in GitHub-Ausgaben und Zusammenfassungen um. Es packt OpenClaw entweder über `scripts/package-openclaw-for-docker.mjs`, lädt ein Paketartefakt aus dem aktuellen Lauf herunter oder lädt ein Paketartefakt aus `package_artifact_run_id` herunter; validiert das Tarball-Inventar; baut und pusht paketdigest-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 Paketdigest-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 erneut versucht wird, statt den Großteil des kritischen CI-Pfads zu verbrauchen.
### Release-Pfad-Chunks
### Release-Pfad-Blöcke
Release-Docker-Abdeckung läuft in kleineren aufgeteilten Jobs mit `OPENCLAW_SKIP_DOCKER_BUILD=1`, sodass jeder Chunk nur die benötigte Image-Art zieht und mehrere Lanes über denselben gewichteten Scheduler ausführt:
Die Release-Docker-Abdeckung läuft in kleineren aufgeteilten Jobs mit `OPENCLAW_SKIP_DOCKER_BUILD=1`, sodass jeder Block nur die benötigte Image-Art 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-Aliasse. Der Lane-Alias `install-e2e` bleibt der aggregierte manuelle Rerun-Alias für beide Provider-Installer-Lanes.
Aktuelle Release-Docker-Blöcke sind `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services` sowie `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 Wiederholungslauf-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 reine OpenWebUI-Dispatches einen eigenständigen `openwebui`-Chunk. Update-Lanes für gebündelte Channels versuchen bei vorübergehenden npm-Netzwerkfehlern einmal erneut.
OpenWebUI wird in `plugins-runtime-services` eingebunden, wenn vollständige Release-Pfad-Abdeckung dies anfordert, und behält nur für OpenWebUI-only-Dispatches einen eigenständigen Block `openwebui`. Update-Lanes für gebündelte Kanäle versuchen bei vorübergehenden npm-Netzwerkfehlern einmal erneut.
Jeder Chunk lädt `.artifacts/docker-tests/` mit Lane-Logs, Zeiten, `summary.json`, `failures.json`, Phasenzeiten, 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 statt der Chunk-Jobs aus, wodurch das Debugging fehlgeschlagener Lanes auf einen gezielten Docker-Job begrenzt bleibt und das Paketartefakt für diesen Lauf vorbereitet, heruntergeladen oder wiederverwendet wird; 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 existieren, sodass eine fehlgeschlagene Lane exakt dasselbe Paket und dieselben Images aus dem fehlgeschlagenen Lauf wiederverwenden kann.
Jeder Block lädt `.artifacts/docker-tests/` mit Lane-Logs, Timings, `summary.json`, `failures.json`, Phasen-Timings, Scheduler-Plan-JSON, Tabellen langsamer Lanes und Wiederholungslaufbefehlen pro Lane hoch. Die Workflow-Eingabe `docker_lanes` führt ausgewählte Lanes gegen die vorbereiteten Images aus statt gegen die Block-Jobs. Dadurch bleibt das Debuggen 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 für diesen Wiederholungslauf lokal. Generierte GitHub-Wiederholungslaufbefehle 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 <run-id> # download Docker artifacts and print combined/per-lane targeted rerun commands
@ -384,89 +384,89 @@ pnpm test:docker:timings <summary> # slow-lane and phase critical-path summari
Der geplante Live-/E2E-Workflow führt täglich die vollständige Release-Pfad-Docker-Suite aus.
## Plugin-Vorveröffentlichung
## 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-Dispatches lassen diese Suite deaktiviert. Er verteilt gebündelte Plugin-Tests auf 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 Release-only-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 teurere Produkt-/Paketabdeckung, daher ist es ein separater Workflow, der durch `Full Release Validation` oder durch einen expliziten Operator ausgelöst wird. Normale Pull Requests, `main`-Pushes und eigenständige manuelle CI-Dispatches halten diese Suite deaktiviert. Er verteilt Tests gebündelter Plugins auf acht Erweiterungs-Worker; diese Erweiterungs-Shard-Jobs führen jeweils bis zu zwei Plugin-Konfigurationsgruppen gleichzeitig aus, mit einem Vitest-Worker pro Gruppe und größerem Node-Heap, 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 Jobs von ein bis drei Minuten zu reservieren.
## QA-Lab
## QA Lab
QA Lab hat dedizierte CI-Lanes außerhalb des wichtigsten smart-gescopten Workflows. Agentische Parität ist unter den breiten QA- und Release-Harnesses 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.
QA Lab verfügt über dedizierte CI-Lanes außerhalb des zentralen Smart-Scoped-Workflows. Agentische Parität ist unter die breiten QA- und Release-Harnesses geschachtelt, nicht als eigenständiger PR-Workflow. Verwenden Sie `Full Release Validation` mit `rerun_group=qa-parity`, wenn Parität Teil eines breiten Validierungslaufs sein soll.
- Der Workflow `QA-Lab - All Lanes` läuft nächtlich auf `main` und bei manuellem Dispatch; er fächert die Mock-Parity-Lane, Live-Matrix-Lane sowie 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, Live-Matrix-Lane sowie Live-Telegram- und Discord-Lanes als parallele Jobs auf. Live-Jobs verwenden die Umgebung `qa-live-shared`, und Telegram/Discord verwenden Convex-Leases.
Release-Checks 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 die Memory-Suche, weil QA-Parität Memory-Verhalten separat abdeckt; Provider-Konnektivität wird durch die separaten Live-Modell-, nativen Provider- und Docker-Provider-Suites abgedeckt.
Release-Checks führen Matrix- und Telegram-Live-Transport-Lanes mit dem deterministischen Mock-Provider und mockqualifizierten Modellen (`mock-openai/gpt-5.5` und `mock-openai/gpt-5.5-alt`) aus, sodass der Kanalvertrag von Live-Modelllatenz und normalem Provider-Plugin-Start isoliert ist. Das Live-Transport-Gateway deaktiviert die Speichersuche, da 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 fügt `--fail-fast` nur hinzu, wenn die ausgecheckte CLI dies unterstützt. Der CLI-Standard und die manuelle Workflow-Eingabe bleiben `all`; manuelle `matrix_profile=all`-Dispatches sharden 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 ergänzt `--fail-fast` nur, wenn die ausgecheckte CLI dies unterstützt. Der CLI-Standard und die manuelle Workflow-Eingabe bleiben `all`; ein manueller Dispatch mit `matrix_profile=all` shardet 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 releasekritischen QA-Lab-Lanes vor der Release-Freigabe aus; sein QA-Parity-Gate führt Candidate- und Baseline-Packs als parallele Lane-Jobs aus und lädt anschließend beide Artefakte in einen kleinen Berichtsjob für den finalen Paritätsvergleich herunter.
`OpenClaw Release Checks` führt außerdem die releasekritischen QA-Lab-Lanes vor der Release-Freigabe 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 finalen Paritätsvergleich herunter.
Folgen Sie bei normalen PRs gescopten CI-/Check-Nachweisen, statt Parität als erforderlichen Status zu behandeln.
Für normale PRs verwenden Sie gescopte CI-/Check-Nachweise, statt Parität als erforderlichen Status zu behandeln.
## CodeQL
Der `CodeQL`-Workflow ist absichtlich ein eng gefasster Security-Scanner für den ersten Durchlauf, nicht der vollständige Repository-Sweep. Tägliche, manuelle und nicht als Draft markierte Pull-Request-Guard-Läufe scannen Actions-Workflow-Code sowie die risikoreichsten JavaScript-/TypeScript-Bereiche mit Security-Abfragen mit hoher Konfidenz, gefiltert auf hohe/kritische `security-severity`.
Der `CodeQL`-Workflow ist bewusst als enger Sicherheits-Scanner für den ersten Durchlauf angelegt, nicht als vollständige Repository-Prüfung. Tägliche, manuelle und Wächterläufe für Pull Requests, die keine Entwürfe sind, scannen Actions-Workflow-Code sowie die JavaScript/TypeScript-Flächen mit dem höchsten Risiko und verwenden Sicherheitsabfragen mit hoher Konfidenz, 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 er führt dieselbe Security-Matrix mit hoher Konfidenz aus wie der geplante Workflow. Android- und macOS-CodeQL bleiben außerhalb der PR-Standardwerte.
Der Pull-Request-Wächter bleibt schlank: Er startet nur bei Änderungen unter `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` oder `src` und führt dieselbe Sicherheitsmatrix mit hoher Konfidenz aus wie der geplante Workflow. Android- und macOS-CodeQL bleiben aus den PR-Standardeinstellungen heraus.
### Security-Kategorien
### Sicherheitskategorien
| Kategorie | Bereich |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-security-high/core-auth-secrets` | Auth, Secrets, Sandbox, Cron und Gateway-Baseline |
| `/codeql-security-high/channel-runtime-boundary` | Verträge der Kern-Channel-Implementierung plus Channel-Plugin-Runtime, Gateway, Plugin SDK, Secrets, Audit-Touchpoints |
| `/codeql-security-high/network-ssrf-boundary` | Kern-SSRF, IP-Parsing, Network Guard, Web-Fetch und SSRF-Policy-Bereiche des Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | MCP-Server, Helfer 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, Paketmanager-Installation, Source-Loading und Vertrauensbereiche des Plugin-SDK-Paketvertrags |
| Kategorie | Fläche |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-security-high/core-auth-secrets` | Authentifizierung, Secrets, Sandbox, Cron und Gateway-Basislinie |
| `/codeql-security-high/channel-runtime-boundary` | Implementierungsverträge für zentrale Channels plus Channel-Plugin-Runtime, Gateway, Plugin SDK, Secrets, Audit-Berührungspunkte |
| `/codeql-security-high/network-ssrf-boundary` | Zentrale SSRF-, IP-Parsing-, Netzwerkschutz-, Web-Fetch- und SSRF-Policy-Flächen des Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | MCP-Server, Hilfsfunktionen für Prozessausführung, ausgehende Zustellung und Gates für Tool-Ausführung durch Agents |
| `/codeql-security-high/plugin-trust-boundary` | Plugin-Installation, Loader, Manifest, Registry, Package-Manager-Installation, Source-Loading und Trust-Flächen des Plugin-SDK-Package-Vertrags |
### 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, den die Workflow-Sanity akzeptiert. 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 Dependency-Build-Ergebnisse aus dem hochgeladenen SARIF heraus und lädt unter `/codeql-critical-security/macos` hoch. Bleibt außerhalb der täglichen Standardwerte, weil der macOS-Build selbst bei sauberem Lauf die Runtime dominiert.
- `CodeQL Android Critical Security` — geplanter Android-Sicherheits-Shard. Baut die Android-App manuell für CodeQL auf dem kleinsten Blacksmith-Linux-Runner, den die Workflow-Sanity akzeptiert. 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 dem hochgeladenen SARIF heraus und lädt unter `/codeql-critical-security/macos` hoch. Bleibt außerhalb der täglichen Standardeinstellungen, weil der macOS-Build selbst bei sauberem Lauf die Laufzeit dominiert.
### Critical-Quality-Kategorien
### Kategorien für Critical Quality
`CodeQL Critical Quality` ist der passende Nicht-Security-Shard. Er führt nur JavaScript-/TypeScript-Quality-Abfragen mit Fehler-Schweregrad und ohne Security-Bezug über enge, hochwertige Bereiche auf dem kleineren Blacksmith-Linux-Runner aus. Sein Pull-Request-Guard ist absichtlich kleiner als das geplante Profil: Nicht-Draft-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 Agent-Befehls-/Modell-/Tool-Ausführung und Reply-Dispatch-Code, Konfigurationsschema-/Migrations-/IO-Code, Auth-/Secrets-/Sandbox-/Security-Code, Kern-Channel- und gebündelte Channel-Plugin-Runtime, Gateway-Protokoll-/Server-Methoden, Memory-Runtime-/SDK-Glue, MCP-/Prozess-/ausgehende Zustellung, Provider-Runtime-/Modellkatalog, Session-Diagnostics-/Delivery-Queues, Plugin-Loader, Plugin SDK/Paketvertrag oder Änderungen an der Plugin-SDK-Reply-Runtime aus. CodeQL-Konfigurations- und Quality-Workflow-Änderungen führen alle zwölf PR-Quality-Shards aus.
`CodeQL Critical Quality` ist der entsprechende Nicht-Sicherheits-Shard. Er führt nur JavaScript/TypeScript-Qualitätsabfragen mit Fehler-Schweregrad und ohne Sicherheitsbezug über enge, besonders wertvolle Flächen auf dem kleineren Blacksmith-Linux-Runner aus. Sein Pull-Request-Wächter ist bewusst kleiner als das geplante Profil: PRs, die keine Entwürfe sind, 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 Agent-Befehls-/Modell-/Tool-Ausführung und Reply-Dispatch-Code, Konfigurationsschema-/Migrations-/IO-Code, Auth-/Secrets-/Sandbox-/Sicherheitscode, zentrale Channel- und gebündelte Channel-Plugin-Runtime, Gateway-Protokoll-/Server-Methoden, Memory-Runtime-/SDK-Verbindungscode, MCP-/Prozess-/ausgehende Zustellung, Provider-Runtime-/Modellkatalog, Session-Diagnose-/Zustellungswarteschlangen, Plugin-Loader, Plugin-SDK-/Package-Vertrag oder Plugin-SDK-Reply-Runtime ändern. Änderungen an CodeQL-Konfiguration und Qualitäts-Workflow führen alle zwölf PR-Qualitäts-Shards aus.
Manueller Dispatch akzeptiert:
Manuelle Ausführung 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 engen Profile sind Teaching-/Iterations-Hooks, um einen Quality-Shard isoliert auszuführen.
Die engen Profile sind Lehr- und Iterations-Hooks, um einen Qualitäts-Shard isoliert auszuführen.
| Kategorie | Bereich |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | Auth, Secrets, Sandbox, Cron und Code der Gateway-Security-Grenze |
| `/codeql-critical-quality/config-boundary` | Konfigurationsschema, Migration, Normalisierung und IO-Verträge |
| `/codeql-critical-quality/gateway-runtime-boundary` | Gateway-Protokollschemas und Server-Methoden-Verträge |
| `/codeql-critical-quality/channel-runtime-boundary` | Implementierungsverträge für Kern-Channel und gebündeltes Channel-Plugin |
| `/codeql-critical-quality/agent-runtime-boundary` | Befehlsausführung, Modell-/Provider-Dispatch, Auto-Reply-Dispatch und Queues sowie ACP-Control-Plane-Runtime-Verträge |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP-Server und Tool-Bridges, Helfer für 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, Glue für Memory-Runtime-Aktivierung und Memory-Doctor-Befehle |
| `/codeql-critical-quality/session-diagnostics-boundary` | Reply-Queue-Interna, Session-Delivery-Queues, Helfer für ausgehende Session-Bindung/-Zustellung, Diagnoseereignis-/Log-Bundle-Bereiche und Session-Doctor-CLI-Verträge |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Plugin-SDK-Dispatch für eingehende Replies, Reply-Payload-/Chunking-/Runtime-Helfer, Channel-Reply-Optionen, Delivery-Queues und Helfer für Session-/Thread-Bindung |
| `/codeql-critical-quality/provider-runtime-boundary` | Modellkatalog-Normalisierung, Provider-Auth und Discovery, Provider-Runtime-Registrierung, Provider-Defaults/-Kataloge und Web-/Search-/Fetch-/Embedding-Registries |
| `/codeql-critical-quality/ui-control-plane` | Control-UI-Bootstrap, lokale Persistenz, Gateway-Control-Flows und Runtime-Verträge der Task-Control-Plane |
| `/codeql-critical-quality/web-media-runtime-boundary` | Kern-Web-Fetch/Search, Media-IO, Media-Understanding, 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 paketbezogener Plugin-SDK-Quellcode und Helfer für Plugin-Paketverträge |
| Kategorie | Fläche |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | Authentifizierung, Secrets, Sandbox, Cron und Code für die Gateway-Sicherheitsgrenze |
| `/codeql-critical-quality/config-boundary` | Konfigurationsschema, Migration, Normalisierung und IO-Verträge |
| `/codeql-critical-quality/gateway-runtime-boundary` | Gateway-Protokollschemata und Server-Methoden-Verträge |
| `/codeql-critical-quality/channel-runtime-boundary` | Implementierungsverträge für zentrale Channels und gebündelte 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 für 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, Verbindungscode für Memory-Runtime-Aktivierung und Memory-Doctor-Befehle |
| `/codeql-critical-quality/session-diagnostics-boundary` | Interna der Reply-Warteschlange, Session-Zustellungswarteschlangen, Hilfsfunktionen für ausgehende Session-Bindung/-Zustellung, Diagnose-Event-/Log-Bundle-Flächen und Session-Doctor-CLI-Verträge |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Plugin-SDK-Dispatch für eingehende Replies, Reply-Payload-/Chunking-/Runtime-Hilfsfunktionen, Channel-Reply-Optionen, Zustellungswarteschlangen und Hilfsfunktionen für Session-/Thread-Bindung |
| `/codeql-critical-quality/provider-runtime-boundary` | Modellkatalog-Normalisierung, Provider-Authentifizierung und -Discovery, Provider-Runtime-Registrierung, 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-Runtime-Verträge |
| `/codeql-critical-quality/web-media-runtime-boundary` | Zentrale Web-Fetch-/Search-Flächen, Medien-IO, Medienverständnis, Bildgenerierung und Runtime-Verträ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öffentlichtes Package-seitiges Plugin-SDK-Source und Hilfsfunktionen für Plugin-Package-Verträge |
Quality bleibt von Security getrennt, damit Quality-Ergebnisse geplant, gemessen, deaktiviert oder erweitert werden können, ohne das Security-Signal zu verdecken. Swift-, Python- und gebündelte-Plugin-CodeQL-Erweiterungen sollten erst wieder als eng begrenzte oder geshardete Folgearbeit hinzugefügt werden, nachdem die engen Profile stabile Runtime und stabile Signale haben.
Qualität bleibt von Sicherheit getrennt, damit Qualitätsbefunde geplant, gemessen, deaktiviert oder erweitert werden können, ohne das Sicherheitssignal zu verdecken. Swift-, Python- und gebündelte-Plugin-CodeQL-Erweiterungen sollten erst wieder als eng begrenzte oder geshardete Folgearbeit hinzugefügt werden, nachdem die engen Profile stabile Laufzeit und stabiles Signal haben.
## Wartungsworkflows
## Wartungs-Workflows
### Docs Agent
Der `Docs Agent`-Workflow ist eine ereignisgesteuerte Codex-Wartungslane, um bestehende Dokumentation mit kürzlich gelandeten Änderungen synchron zu halten. Er hat keinen reinen Zeitplan: Ein erfolgreicher Nicht-Bot-Push-CI-Lauf auf `main` kann ihn auslösen, und manueller Dispatch kann ihn direkt ausführen. Workflow-Run-Aufrufe werden übersprungen, wenn `main` weitergezogen ist oder wenn in der letzten Stunde ein anderer nicht übersprungener Docs-Agent-Lauf erstellt wurde. Wenn er läuft, prüft er den Commit-Bereich von der vorherigen nicht übersprungenen Docs-Agent-Source-SHA bis zum aktuellen `main`, sodass ein stündlicher Lauf alle seit dem letzten Docs-Durchlauf angesammelten Main-Änderungen abdecken kann.
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 einem Bot stammender Push-CI-Lauf auf `main` kann ihn auslösen, und manuelle Ausführung kann ihn direkt starten. Workflow-Run-Aufrufe werden übersprungen, wenn `main` weitergelaufen ist oder wenn in der letzten Stunde ein anderer, nicht übersprungener Docs-Agent-Lauf erstellt wurde. Wenn er läuft, prüft er den Commit-Bereich von der vorherigen nicht übersprungenen Docs-Agent-Source-SHA bis zum aktuellen `main`, sodass ein stündlicher Lauf alle Main-Änderungen abdecken kann, die seit dem letzten Dokumentationsdurchlauf aufgelaufen sind.
### Test Performance Agent
Der `Test Performance Agent`-Workflow ist eine ereignisgesteuerte Codex-Wartungslane 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 an diesem UTC-Tag bereits ein anderer Workflow-Run-Aufruf gelaufen ist oder läuft. Manueller Dispatch umgeht dieses tägliche Aktivitätsgate. Die Lane erstellt einen gruppierten Vitest-Performance-Bericht für die vollständige Suite, lässt Codex nur kleine, coverage-erhaltende Test-Performance-Fixes statt breiter Refactorings vornehmen, führt dann den Bericht für die vollständige Suite erneut aus und lehnt Änderungen ab, die die bestandene Baseline-Testanzahl reduzieren. Wenn die Baseline fehlschlagende Tests enthält, darf Codex nur offensichtliche Fehler beheben, und der Nach-Agent-Bericht für die vollständige Suite muss bestehen, bevor etwas committet wird. Wenn `main` weiterläuft, bevor der Bot-Push landet, rebased die Lane den validierten Patch, führt `pnpm check:changed` erneut aus und versucht den Push erneut; widersprüchliche 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 einem Bot stammender Push-CI-Lauf auf `main` kann ihn auslösen, aber er überspringt, wenn an diesem 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 danach den Full-Suite-Bericht erneut aus und verwirft Änderungen, die die Anzahl der bestehenden bestandenen Baseline-Tests reduzieren. Wenn die Baseline fehlschlagende Tests hat, darf Codex nur offensichtliche Fehler beheben, und der Full-Suite-Bericht nach dem Agent muss bestanden sein, bevor etwas committed wird. Wenn `main` weiterläuft, bevor der Bot-Push landet, rebaset die Spur den validierten Patch, führt `pnpm check:changed` erneut aus und versucht den Push erneut; konfligierende veraltete Patches werden übersprungen. Sie verwendet GitHub-gehostetes Ubuntu, damit die Codex-Action dieselbe Drop-Sudo-Sicherheitshaltung wie der Docs Agent beibehalten kann.
### Duplicate PRs After Merge
### Doppelte PRs nach Merge
Der `Duplicate PRs After Merge`-Workflow ist ein manueller Maintainer-Workflow für Duplicate-Cleanup nach dem Landen. Er ist standardmäßig ein Dry-Run und schließt nur explizit aufgelistete PRs, wenn `apply=true` gesetzt ist. Vor GitHub-Mutationen prüft er, dass der gelandete PR gemergt ist 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 einen Dry Run und schließt nur ausdrücklich aufgeführte PRs, wenn `apply=true` ist. Bevor GitHub geändert wird, prüft er, dass der gelandete PR gemerged ist und dass jedes Duplikat entweder ein gemeinsam referenziertes Issue oder überlappende geänderte Hunks hat.
```bash
gh workflow run duplicate-after-merge.yml \
@ -475,29 +475,29 @@ gh workflow run duplicate-after-merge.yml \
-f apply=true
```
## Lokale Check-Gates und Changed-Routing
## Lokale Check-Gates und Routing für Änderungen
Die lokale Changed-Lane-Logik lebt 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:
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 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;
- Änderungen nur an Extension-Tests führen Extension-Test-Typecheck plus Extension-Lint aus;
- Änderungen am öffentlichen Plugin SDK oder Plugin-Vertrag erweitern auf Extension-Typecheck, weil Extensions von diesen Core-Verträgen abhängen (Vitest-Extension-Sweeps bleiben explizite Testarbeit);
- Release-Metadaten-only-Versionsbumps führen gezielte Versions-/Konfigurations-/Root-Dependency-Checks aus;
- unbekannte Root-/Konfigurationsänderungen fallen sicher auf alle Check-Lanes zurück.
- Änderungen an zentralem Produktionscode führen Core-Prod- und Core-Test-Typecheck plus Core-Lint/-Guards aus;
- reine Änderungen an zentralen Tests führen nur Core-Test-Typecheck plus Core-Lint aus;
- Änderungen an Plugin-Produktionscode führen Plugin-Prod- und Plugin-Test-Typecheck plus Plugin-Lint aus;
- reine Änderungen an Plugin-Tests führen Plugin-Test-Typecheck plus Plugin-Lint aus;
- Änderungen am öffentlichen Plugin SDK oder an Plugin-Verträgen erweitern auf Plugin-Typecheck, weil Plugins von diesen zentralen Verträgen abhängen (Vitest-Plugin-Sweeps bleiben explizite Testarbeit);
- reine Versionsbump-Änderungen an Release-Metadaten führen gezielte Versions-/Konfigurations-/Root-Abhängigkeitschecks aus;
- unbekannte Root-/Konfigurationsänderungen schlagen sicher auf alle Check-Lanes aus.
Lokales Changed-Test-Routing lebt in `scripts/test-projects.test-support.mjs` und ist absichtlich günstiger als `check:changed`: Direkte Teständerungen führen sich selbst aus, Source-Änderungen bevorzugen explizite Zuordnungen, danach Sibling-Tests und Import-Graph-Abhängige. Die gemeinsame Group-Room-Delivery-Konfiguration ist eine der expliziten Zuordnungen: Änderungen an der sichtbaren Reply-Konfiguration der Gruppe, am Source-Reply-Delivery-Modus oder am System-Prompt des Message-Tools laufen durch die Core-Reply-Tests plus Discord- und Slack-Delivery-Regressionen, damit eine gemeinsame Default-Ä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 die günstige zugeordnete Menge kein vertrauenswürdiger Proxy ist.
Lokales 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, Source-Änderungen bevorzugen explizite Mappings, danach Geschwistertests und Import-Graph-Abhängige. Shared-Group-Room-Zustellungskonfiguration ist eines der expliziten Mappings: Änderungen an der für Gruppen sichtbaren Reply-Konfiguration, am Source-Reply-Zustellungsmodus oder am System-Prompt des Message-Tools laufen über die zentralen Reply-Tests 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 weitreichend für das Test-Harness ist, dass das günstige gemappte Set kein vertrauenswürdiger Proxy ist.
## Testbox-Validierung
Führen Sie Testbox aus dem Repository-Root aus und bevorzugen Sie für umfassende Nachweise eine frisch vorgewärmte Box. Bevor Sie einen langsamen Gate-Lauf auf eine Box verwenden, die wiederverwendet wurde, abgelaufen ist oder gerade eine unerwartet große Synchronisierung gemeldet hat, führen Sie zuerst `pnpm testbox:sanity` innerhalb der Box aus.
Führen Sie Testbox vom Repo-Root aus und bevorzugen Sie für breite Validierung 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` innerhalb 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 in der Regel, dass der Remote-Synchronisierungszustand keine vertrauenswürdige Kopie des PR ist; stoppen Sie diese Box und wärmen Sie stattdessen eine frische vor, anstatt den Produkttestfehler zu debuggen. Legen Sie für beabsichtigte PRs mit vielen Löschungen für diesen Sanity-Lauf `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` fest.
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 in der Regel, dass der Remote-Synchronisierungszustand 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 Synchronisierungsphase bleibt, ohne Ausgabe nach der Synchronisierung zu erzeugen. Legen Sie `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` fest, um diesen Schutz zu deaktivieren, oder verwenden Sie für ungewöhnlich große lokale Diffs einen größeren Millisekundenwert.
`pnpm testbox:run` beendet außerdem eine lokale Blacksmith-CLI-Ausführung, die länger als fünf Minuten in der Synchronisierungsphase bleibt, ohne Ausgabe nach der Synchronisierung zu liefern. Setzen Sie `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, um diese Schutzvorkehrung zu deaktivieren, oder verwenden Sie einen größeren Millisekundenwert für ungewöhnlich große lokale Diffs.
Crabbox ist der repositoryeigene zweite Remote-Box-Pfad für Linux-Nachweise, 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 zweite Remote-Box-Pfad für Linux-Nachweise, 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:
```bash
pnpm crabbox:warmup -- --idle-timeout 90m
@ -506,9 +506,9 @@ pnpm crabbox:run -- --id <cbx_id> --shell "OPENCLAW_TESTBOX=1 pnpm check:changed
pnpm crabbox:stop -- <cbx_id>
```
`.crabbox.yaml` verwaltet Provider-, Synchronisierungs- und GitHub-Actions-Hydrationsdefaults. Es schließt lokales `.git` aus, damit der hydratisierte Actions-Checkout seine eigenen Remote-Git-Metadaten behält, anstatt maintainerlokale Remotes und Objektspeicher zu synchronisieren, und es schließt lokale Runtime-/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, die spätere `crabbox run --id <cbx_id>`-Befehle beziehen.
`.crabbox.yaml` verwaltet die Standardwerte für Provider, Synchronisierung und GitHub Actions-Hydration. Sie schließt die lokale `.git` aus, damit der hydratisierte Actions-Checkout seine eigenen Remote-Git-Metadaten behält, statt 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`-Abruf und die nicht geheime Umgebungsübergabe, die spätere `crabbox run --id <cbx_id>`-Befehle sourcen.
## Verwandt
## Verwandte Themen
- [Installationsübersicht](/de/install)
- [Entwicklungskanäle](/de/install/development-channels)

235
docs/de/concepts/system-prompt.md
View File

@ -1,152 +1,155 @@
---
read_when:
- System-Prompt-Text, Tool-Liste oder Zeit-/Heartbeat-Abschnitte bearbeiten
- System-Prompt-Text, Tools-Liste oder Zeit-/Heartbeat-Abschnitte bearbeiten
- Ändern des Workspace-Bootstraps oder des Verhaltens der Skills-Injektion
summary: Was der OpenClaw-System-Prompt enthält und wie er zusammengesetzt wird
title: System-Prompt
summary: Was der OpenClaw-Systemprompt enthält und wie er zusammengesetzt wird
title: Systemanweisung
x-i18n:
generated_at: "2026-05-02T22:17:58Z"
generated_at: "2026-05-02T23:39:18Z"
model: gpt-5.5
provider: openai
source_hash: 3b8761a8722bb328b937e0832774be7b4e99602ae032c9a255f26843237c110c
source_hash: f8e0234453812c16cf5d273096d335049bf435ca76ade36200caf4bb344624e5
source_path: concepts/system-prompt.md
workflow: 16
---
OpenClaw erstellt für jede Agent-Ausführung einen benutzerdefinierten System-Prompt. Der Prompt ist **OpenClaw-eigen** und verwendet nicht den Standard-Prompt von pi-coding-agent.
OpenClaw erstellt für jeden Agent-Lauf einen benutzerdefinierten System-Prompt. Der Prompt ist **OpenClaw-owned** und verwendet nicht den Standard-Prompt von pi-coding-agent.
Der Prompt wird von OpenClaw zusammengesetzt und in jede Agent-Ausführung injiziert.
Der Prompt wird von OpenClaw zusammengesetzt und in jeden Agent-Lauf injiziert.
Provider-Plugins können cache-bewusste Prompt-Hinweise beitragen, ohne den
vollständigen OpenClaw-eigenen Prompt zu ersetzen. Die Provider-Laufzeitumgebung kann:
Provider-Plugins können cache-bewusste Prompt-Anweisungen beitragen, ohne den
vollständigen OpenClaw-owned Prompt zu ersetzen. Die Provider-Runtime kann:
- einen kleinen Satz benannter Kernabschnitte ersetzen (`interaction_style`,
- eine kleine Gruppe benannter Kernabschnitte ersetzen (`interaction_style`,
`tool_call_style`, `execution_bias`)
- ein **stabiles Präfix** oberhalb der Prompt-Cache-Grenze injizieren
- ein **dynamisches Suffix** unterhalb der Prompt-Cache-Grenze injizieren
Verwenden Sie Provider-eigene Beiträge für modellfamilien-spezifische Feinabstimmung. Behalten Sie die ältere
`before_prompt_build`-Prompt-Mutation für Kompatibilität oder wirklich globale Prompt-Änderungen bei,
nicht für normales Provider-Verhalten.
Verwenden Sie Provider-eigene Beiträge für modellfamilien-spezifisches Tuning. Behalten Sie die alte
`before_prompt_build`-Prompt-Mutation für Kompatibilität oder wirklich globale Prompt-
Änderungen bei, nicht für normales Provider-Verhalten.
Das Overlay für die OpenAI GPT-5-Familie hält die Kernausführungsregel klein und ergänzt
modellspezifische Hinweise für Persona-Verankerung, knappe Ausgabe, Tool-Disziplin,
parallele Nachschlagevorgänge, Abdeckung von Liefergegenständen, Verifikation, fehlenden Kontext und
Hygiene bei Terminal-Tools.
Das OpenAI-GPT-5-Familien-Overlay hält die zentrale Ausführungsregel klein und fügt
modellspezifische Hinweise für Persona-Latching, knappe Ausgabe, Werkzeugdisziplin,
paralleles Nachschlagen, Abdeckung von Arbeitsergebnissen, Verifikation, fehlenden Kontext und
Terminal-Tool-Hygiene hinzu.
## Struktur
Der Prompt ist absichtlich kompakt und verwendet feste Abschnitte:
- **Tooling**: Erinnerung an strukturierte Tools als Quelle der Wahrheit plus Laufzeit-Hinweise zur Tool-Nutzung.
- **Ausführungsfokus**: kompakte Hinweise zum konsequenten Abarbeiten: bei
handlungsfähigen Anfragen innerhalb derselben Runde handeln, fortfahren bis abgeschlossen oder blockiert,
sich von schwachen Tool-Ergebnissen erholen, veränderlichen Zustand live prüfen und vor der Finalisierung verifizieren.
- **Werkzeuge**: Erinnerung an die strukturierte Tool-Quelle der Wahrheit sowie Runtime-Hinweise zur Tool-Nutzung.
- **Ausführungsbias**: kompakte Follow-through-Hinweise: bei
umsetzbaren Anfragen im aktuellen Turn handeln, fortfahren, bis die Aufgabe erledigt oder blockiert ist, schwache Tool-
Ergebnisse ausgleichen, veränderlichen Zustand live prüfen und vor dem Abschließen verifizieren.
- **Sicherheit**: kurze Guardrail-Erinnerung, machtstrebendes Verhalten oder das Umgehen von Aufsicht zu vermeiden.
- **Skills** (wenn verfügbar): erklärt dem Modell, wie es Skill-Anweisungen bei Bedarf laden soll.
- **Skills** (wenn verfügbar): erklärt dem Modell, wie Skill-Anweisungen bei Bedarf geladen werden.
- **OpenClaw-Selbstaktualisierung**: wie Konfiguration sicher mit
`config.schema.lookup` geprüft, Konfiguration mit `config.patch` gepatcht, die vollständige
Konfiguration mit `config.apply` ersetzt und `update.run` nur auf ausdrückliche Benutzeranforderung
ausgeführt wird. Das nur für Eigentümer vorgesehene `gateway`-Tool verweigert außerdem das Umschreiben von
`tools.exec.ask` / `tools.exec.security`, einschließlich älterer `tools.bash.*`-
Aliasse, die auf diese geschützten exec-Pfade normalisieren.
`config.schema.lookup` geprüft, mit `config.patch` gepatcht, die vollständige
Konfiguration mit `config.apply` ersetzt und `update.run` nur auf explizite Benutzeranfrage
ausgeführt wird. Das owner-only `gateway`-Tool verweigert außerdem das Umschreiben von
`tools.exec.ask` / `tools.exec.security`, einschließlich alter `tools.bash.*`-
Aliasse, die auf diese geschützten Exec-Pfade normalisiert werden.
- **Arbeitsbereich**: Arbeitsverzeichnis (`agents.defaults.workspace`).
- **Dokumentation**: lokaler Pfad zu OpenClaw-Dokumentation (Repo oder npm-Paket) und wann sie zu lesen ist.
- **Arbeitsbereichsdateien (injiziert)**: weist darauf hin, dass Bootstrap-Dateien unten enthalten sind.
- **Sandbox** (wenn aktiviert): weist auf Sandbox-Laufzeitumgebung, Sandbox-Pfade und die Verfügbarkeit erhöhter exec-Rechte hin.
- **Aktuelles Datum und Uhrzeit**: benutzerlokale Zeit, Zeitzone und Zeitformat.
- **Dokumentation**: lokaler Pfad zur OpenClaw-Dokumentation (Repo oder npm-Paket) und wann sie gelesen werden soll.
- **Arbeitsbereichsdateien (injiziert)**: zeigt an, dass Bootstrap-Dateien unten enthalten sind.
- **Sandbox** (wenn aktiviert): zeigt sandboxed Runtime, Sandbox-Pfade und ob erhöhte Exec-Rechte verfügbar sind.
- **Aktuelles Datum & Uhrzeit**: benutzerlokale Zeit, Zeitzone und Zeitformat.
- **Antwort-Tags**: optionale Antwort-Tag-Syntax für unterstützte Provider.
- **Heartbeats**: Heartbeat-Prompt und Bestätigungsverhalten, wenn Heartbeats für den Standard-Agent aktiviert sind.
- **Laufzeitumgebung**: Host, Betriebssystem, Node, Modell, Repo-Wurzel (wenn erkannt), Denkstufe (eine Zeile).
- **Runtime**: Host, Betriebssystem, Node, Modell, Repo-Root (wenn erkannt), Denkstufe (eine Zeile).
- **Reasoning**: aktuelle Sichtbarkeitsstufe + Hinweis zum /reasoning-Umschalter.
OpenClaw hält große stabile Inhalte, einschließlich **Projektkontext**, oberhalb der
internen Prompt-Cache-Grenze. Veränderliche Kanal-/Sitzungsabschnitte wie
internen Prompt-Cache-Grenze. Veränderliche Channel-/Session-Abschnitte wie
Control-UI-Einbettungshinweise, **Messaging**, **Voice**, **Gruppenchat-Kontext**,
**Reaktionen**, **Heartbeats** und **Laufzeitumgebung** werden unterhalb dieser Grenze angehängt,
**Reactions**, **Heartbeats** und **Runtime** werden unterhalb dieser Grenze angehängt,
damit lokale Backends mit Präfix-Caches das stabile Arbeitsbereichspräfix
über Kanalrunden hinweg wiederverwenden können. Tool-Beschreibungen sollten ebenfalls vermeiden,
aktuelle Kanalnamen einzubetten, wenn das akzeptierte Schema dieses Laufzeitdetail bereits enthält.
über Channel-Turns hinweg wiederverwenden können. Tool-Beschreibungen sollten ebenfalls vermeiden, aktuelle
Channel-Namen einzubetten, wenn das akzeptierte Schema dieses Runtime-Detail bereits enthält.
Der Tooling-Abschnitt enthält außerdem Laufzeit-Hinweise für lang laufende Arbeit:
Der Abschnitt Werkzeuge enthält außerdem Runtime-Hinweise für lang laufende Arbeit:
- Cron für zukünftige Nachverfolgung verwenden (`check back later`, Erinnerungen, wiederkehrende Arbeit)
- Verwenden Sie Cron für künftige Nachverfolgung (`check back later`, Erinnerungen, wiederkehrende Arbeit)
statt `exec`-Sleep-Schleifen, `yieldMs`-Verzögerungstricks oder wiederholtem `process`-
Polling
- `exec` / `process` nur für Befehle verwenden, die jetzt starten und im Hintergrund weiterlaufen
- wenn automatisches Aufwecken bei Abschluss aktiviert ist, den Befehl einmal starten und sich auf
den push-basierten Aufweckpfad verlassen, wenn er Ausgabe erzeugt oder fehlschlägt
- `process` für Protokolle, Status, Eingabe oder Eingriff verwenden, wenn Sie einen laufenden Befehl prüfen müssen
- wenn die Aufgabe größer ist, `sessions_spawn` bevorzugen; der Abschluss von Sub-Agents ist
push-basiert und kündigt sich automatisch beim Anforderer zurück
- `subagents list` / `sessions_list` nicht in einer Schleife abfragen, nur um auf den Abschluss zu warten
- verwenden Sie `exec` / `process` nur für Befehle, die jetzt starten und
im Hintergrund weiterlaufen
- wenn automatisches Aufwachen bei Abschluss aktiviert ist, starten Sie den Befehl einmal und verlassen Sie sich auf
den push-basierten Wake-Pfad, wenn er Ausgabe erzeugt oder fehlschlägt
- verwenden Sie `process` für Logs, Status, Eingaben oder Eingriffe, wenn Sie
einen laufenden Befehl prüfen müssen
- wenn die Aufgabe größer ist, bevorzugen Sie `sessions_spawn`; der Abschluss von Sub-Agents ist
push-basiert und meldet sich automatisch beim Anfragenden zurück
- pollen Sie `subagents list` / `sessions_list` nicht in einer Schleife, nur um auf
den Abschluss zu warten
Wenn das experimentelle Tool `update_plan` aktiviert ist, weist Tooling das
Modell außerdem an, es nur für nicht triviale mehrstufige Arbeit zu verwenden, genau einen
`in_progress`-Schritt beizubehalten und zu vermeiden, nach jeder Aktualisierung den gesamten Plan zu wiederholen.
Wenn das experimentelle `update_plan`-Tool aktiviert ist, weist Werkzeuge das
Modell außerdem an, es nur für nicht triviale mehrschrittige Arbeit zu verwenden, genau einen
`in_progress`-Schritt beizubehalten und den gesamten Plan nicht nach jeder Aktualisierung zu wiederholen.
Sicherheits-Guardrails im System-Prompt sind beratend. Sie leiten Modellverhalten an, erzwingen aber keine Richtlinie. Verwenden Sie Tool-Richtlinien, exec-Genehmigungen, Sandboxing und Kanal-Allowlists für harte Durchsetzung; Operatoren können diese absichtlich deaktivieren.
Sicherheits-Guardrails im System-Prompt sind beratend. Sie leiten das Modellverhalten, erzwingen aber keine Richtlinie. Verwenden Sie Tool-Richtlinien, Exec-Genehmigungen, Sandboxing und Channel-Allowlists für harte Durchsetzung; Betreiber können diese absichtlich deaktivieren.
Auf Kanälen mit nativen Genehmigungskarten/-Buttons weist der Laufzeit-Prompt den
Auf Channels mit nativen Genehmigungskarten/-Buttons weist der Runtime-Prompt den
Agent jetzt an, zuerst diese native Genehmigungs-UI zu verwenden. Er sollte nur dann einen manuellen
`/approve`-Befehl einschließen, wenn das Tool-Ergebnis angibt, dass Chat-Genehmigungen nicht verfügbar sind oder
`/approve`-Befehl einschließen, wenn das Tool-Ergebnis sagt, dass Chat-Genehmigungen nicht verfügbar sind oder
manuelle Genehmigung der einzige Weg ist.
## Prompt-Modi
OpenClaw kann kleinere System-Prompts für Sub-Agents rendern. Die Laufzeitumgebung setzt für jede Ausführung einen
`promptMode` (keine benutzerseitige Konfiguration):
OpenClaw kann kleinere System-Prompts für Sub-Agents rendern. Die Runtime setzt für
jeden Lauf einen `promptMode` (keine benutzerseitige Konfiguration):
- `full` (Standard): enthält alle oben genannten Abschnitte.
- `minimal`: wird für Sub-Agents verwendet; lässt **Skills**, **Memory Recall**, **OpenClaw-
Selbstaktualisierung**, **Modellaliase**, **Benutzeridentität**, **Antwort-Tags**,
**Messaging**, **Stille Antworten** und **Heartbeats** aus. Tooling, **Sicherheit**,
Arbeitsbereich, Sandbox, Aktuelles Datum und Uhrzeit (wenn bekannt), Laufzeitumgebung und injizierter
- `minimal`: wird für Sub-Agents verwendet; lässt **Skills**, **Memory Recall**, **OpenClaw
Self-Update**, **Model Aliases**, **User Identity**, **Reply Tags**,
**Messaging**, **Silent Replies** und **Heartbeats** aus. Werkzeuge, **Sicherheit**,
Arbeitsbereich, Sandbox, Aktuelles Datum & Uhrzeit (wenn bekannt), Runtime und injizierter
Kontext bleiben verfügbar.
- `none`: gibt nur die Basisidentitätszeile zurück.
- `none`: gibt nur die Basis-Identitätszeile zurück.
Wenn `promptMode=minimal` ist, werden zusätzlich injizierte Prompts als **Subagent-
Kontext** statt **Gruppenchat-Kontext** gekennzeichnet.
Wenn `promptMode=minimal` gilt, werden zusätzlich injizierte Prompts als **Subagent
Context** statt **Group Chat Context** beschriftet.
Für automatische Kanalantwort-Ausführungen kann OpenClaw den generischen Abschnitt **Stille Antworten**
weglassen, wenn der direkte/Gruppenchat-Kontext bereits das aufgelöste
konversationsspezifische `NO_REPLY`-Verhalten enthält. Dadurch wird vermieden, Token-Mechanik
sowohl im globalen System-Prompt als auch im Kanalkontext zu wiederholen.
Für Channel-Auto-Reply-Läufe kann OpenClaw den generischen Abschnitt **Silent Replies**
weglassen, wenn der Direkt-/Gruppenchat-Kontext bereits das aufgelöste
konversationsspezifische `NO_REPLY`-Verhalten enthält. Dadurch wird vermieden, Token-Mechaniken
sowohl im globalen System-Prompt als auch im Channel-Kontext zu wiederholen.
## Prompt-Snapshots
OpenClaw hält committete Happy-Path-Prompt-Snapshots für die Codex/message-tool-
Laufzeit unter `test/fixtures/agents/prompt-snapshots/happy-path/` vor. Sie rendern
ausgewählte App-Server-Thread-/Rundenparameter plus einen rekonstruierten modellgebundenen Prompt-
Layer-Stack für direkte Telegram-, Discord-Gruppen- und Heartbeat-Runden. Dieser Stack
enthält ein angeheftetes Codex-`gpt-5.5`-Modell-Prompt-Fixture, das aus der
Modellkatalog-/Cache-Form von Codex generiert wurde, den Codex-Happy-Path-Berechtigungs-Developer-Text,
OpenClaw-Developer-Anweisungen, Benutzerrunden-Eingabe und Verweise auf die dynamischen
OpenClaw hält committete Prompt-Snapshots für den Happy Path der Codex-Runtime unter
`test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/`. Sie rendern
ausgewählte App-Server-Thread-/Turn-Parameter plus einen rekonstruierten modellgebundenen Prompt-
Layer-Stack für Telegram-Direkt-, Discord-Gruppen- und Heartbeat-Turns. Dieser Stack
enthält ein gepinntes Codex-`gpt-5.5`-Modell-Prompt-Fixture, das aus Codex’
Modellkatalog-/Cache-Form erzeugt wurde, den Codex-Happy-Path-Berechtigungs-Developer-Text,
OpenClaw-Developer-Anweisungen, Benutzereingabe im Turn und Referenzen auf die dynamischen
Tool-Spezifikationen.
Aktualisieren Sie das angeheftete Codex-Modell-Prompt-Fixture mit
`pnpm prompt:snapshots:sync-codex-model`. Standardmäßig sucht das Skript den
Laufzeit-Cache von Codex unter `$CODEX_HOME/models_cache.json`, dann unter
Aktualisieren Sie das gepinnte Codex-Modell-Prompt-Fixture mit
`pnpm prompt:snapshots:sync-codex-model`. Standardmäßig sucht das Skript nach
Codex’ Runtime-Cache unter `$CODEX_HOME/models_cache.json`, dann unter
`~/.codex/models_cache.json` und fällt erst danach auf die Maintainer-Codex-
Checkout-Konvention unter `~/code/codex/codex-rs/models-manager/models.json` zurück. Wenn
keine dieser Quellen existiert, beendet sich der Befehl, ohne das committete
Fixture zu ändern. Übergeben Sie `--catalog <path>`, um aus einer bestimmten `models_cache.json`-
oder `models.json`-Datei zu aktualisieren.
Diese Snapshots sind weiterhin keine bytegenaue rohe OpenAI-Anfrageerfassung. Codex
kann laufzeiteigenen Arbeitsbereichskontext wie `AGENTS.md`, Umgebungskontext,
Memories, App-/Plugin-Anweisungen und zukünftige Anweisungen für den Kollaborationsmodus
innerhalb der Codex-Laufzeit hinzufügen, nachdem OpenClaw Thread- und Rundenparameter
gesendet hat.
Diese Snapshots sind weiterhin keine bytegenaue Roh-Erfassung einer OpenAI-Anfrage. Codex
kann Runtime-eigenen Arbeitsbereichskontext wie `AGENTS.md`, Umgebungs-
kontext, Erinnerungen, App-/Plugin-Anweisungen und künftige Collaboration-Mode-
Anweisungen innerhalb der Codex-Runtime hinzufügen, nachdem OpenClaw Thread- und Turn-
Parameter gesendet hat.
Generieren Sie sie mit `pnpm prompt:snapshots:gen` neu und prüfen Sie Drift mit
Regenerieren Sie sie mit `pnpm prompt:snapshots:gen` und prüfen Sie Drift mit
`pnpm prompt:snapshots:check`. CI führt die Drift-Prüfung im zusätzlichen
Boundary-Shard aus, damit Prompt-Änderungen und Snapshot-Aktualisierungen am selben
PR hängen bleiben.
## Arbeitsbereich-Bootstrap-Injektion
Bootstrap-Dateien werden gekürzt und unter **Projektkontext** angehängt, damit das Modell Identitäts- und Profilkontext sieht, ohne explizite Lesevorgänge zu benötigen:
Bootstrap-Dateien werden gekürzt und unter **Projektkontext** angehängt, damit das Modell Identitäts- und Profilkontext sieht, ohne explizite Lesezugriffe zu benötigen:
- `AGENTS.md`
- `SOUL.md`
@ -154,71 +157,78 @@ Bootstrap-Dateien werden gekürzt und unter **Projektkontext** angehängt, damit
- `IDENTITY.md`
- `USER.md`
- `HEARTBEAT.md`
- `BOOTSTRAP.md` (nur in brandneuen Arbeitsbereichen)
- `BOOTSTRAP.md` (nur bei ganz neuen Arbeitsbereichen)
- `MEMORY.md`, wenn vorhanden
Alle diese Dateien werden bei jeder Runde **in das Kontextfenster injiziert**, sofern
kein dateispezifisches Gate greift. `HEARTBEAT.md` wird bei normalen Ausführungen weggelassen, wenn
Alle diese Dateien werden bei jedem Turn **in das Kontextfenster injiziert**, sofern
kein dateispezifisches Gate gilt. `HEARTBEAT.md` wird bei normalen Läufen ausgelassen, wenn
Heartbeats für den Standard-Agent deaktiviert sind oder
`agents.defaults.heartbeat.includeSystemPromptSection` false ist. Halten Sie injizierte
Dateien knapp, insbesondere `MEMORY.md`, das mit der Zeit wachsen und zu
unerwartet hoher Kontextnutzung und häufigerer Compaction führen kann.
Dateien knapp — besonders `MEMORY.md`, das mit der Zeit wachsen und zu
unerwartet hoher Kontextnutzung sowie häufigerer Compaction führen kann.
Wenn eine Session auf dem nativen Codex-Harness läuft, lädt Codex `AGENTS.md`
über seine eigene Projekt-Dokumenterkennung. OpenClaw löst weiterhin die übrigen
Bootstrap-Dateien auf und leitet sie als Codex-Konfigurationsanweisungen weiter, sodass `SOUL.md`,
`TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` und
`MEMORY.md` dieselbe Arbeitsbereich-Kontextrolle behalten, ohne
`AGENTS.md` zu duplizieren.
<Note>
Tägliche `memory/*.md`-Dateien sind **nicht** Teil des normalen Bootstrap-Projektkontexts. In gewöhnlichen Runden wird bei Bedarf über die Tools `memory_search` und `memory_get` auf sie zugegriffen, sodass sie nicht gegen das Kontextfenster zählen, sofern das Modell sie nicht explizit liest. Bloße `/new`- und `/reset`-Runden sind die Ausnahme: Die Laufzeitumgebung kann aktuellen täglichen Memory als einmaligen Startkontextblock für diese erste Runde voranstellen.
Tägliche `memory/*.md`-Dateien sind **nicht** Teil des normalen Bootstrap-Projektkontexts. Bei gewöhnlichen Turns wird bei Bedarf über die Tools `memory_search` und `memory_get` darauf zugegriffen, sodass sie nicht auf das Kontextfenster angerechnet werden, sofern das Modell sie nicht explizit liest. Reine `/new`- und `/reset`-Turns sind die Ausnahme: Die Runtime kann aktuellen täglichen Speicher als einmaligen Startkontextblock für diesen ersten Turn voranstellen.
</Note>
Große Dateien werden mit einer Markierung abgeschnitten. Die maximale Größe pro Datei wird durch
`agents.defaults.bootstrapMaxChars` gesteuert (Standard: 12000). Der gesamte injizierte Bootstrap-
Inhalt über alle Dateien hinweg ist durch `agents.defaults.bootstrapTotalMaxChars`
begrenzt (Standard: 60000). Fehlende Dateien injizieren eine kurze Markierung für fehlende Dateien. Wenn Kürzung
begrenzt (Standard: 60000). Fehlende Dateien injizieren eine kurze Missing-File-Markierung. Wenn Kürzung
auftritt, kann OpenClaw einen Warnblock im Projektkontext injizieren; steuern Sie dies mit
`agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`;
Standard: `once`).
Sub-Agent-Sitzungen injizieren nur `AGENTS.md` und `TOOLS.md` (andere Bootstrap-Dateien
Sub-Agent-Sessions injizieren nur `AGENTS.md` und `TOOLS.md` (andere Bootstrap-Dateien
werden herausgefiltert, um den Sub-Agent-Kontext klein zu halten).
Interne Hooks können diesen Schritt über `agent:bootstrap` abfangen, um die
injizierten Bootstrap-Dateien zu verändern oder zu ersetzen (zum Beispiel `SOUL.md` gegen eine alternative Persona auszutauschen).
Wenn Sie möchten, dass der Agent weniger generisch klingt, beginnen Sie mit dem
[SOUL.md-Persönlichkeitsleitfaden](/de/concepts/soul).
[SOUL.md Personality Guide](/de/concepts/soul).
Um zu prüfen, wie viel jede injizierte Datei beiträgt (roh gegenüber injiziert, Kürzung plus Tool-Schema-Overhead), verwenden Sie `/context list` oder `/context detail`. Siehe [Kontext](/de/concepts/context).
Um zu prüfen, wie viel jede injizierte Datei beiträgt (roh vs. injiziert, Kürzung plus Tool-Schema-Overhead), verwenden Sie `/context list` oder `/context detail`. Siehe [Kontext](/de/concepts/context).
## Zeitbehandlung
## Zeitverarbeitung
Der System-Prompt enthält einen dedizierten Abschnitt **Aktuelles Datum und Uhrzeit**, wenn die
Zeitzone des Benutzers bekannt ist. Damit der Prompt cache-stabil bleibt, enthält er jetzt nur noch
Der System-Prompt enthält einen eigenen Abschnitt **Aktuelles Datum & Uhrzeit**, wenn die
Benutzerzeitzone bekannt ist. Um den Prompt cache-stabil zu halten, enthält er jetzt nur noch
die **Zeitzone** (keine dynamische Uhr oder kein Zeitformat).
Verwenden Sie `session_status`, wenn der Agent die aktuelle Uhrzeit benötigt; die Statuskarte
enthält eine Zeitstempelzeile. Dasselbe Tool kann optional eine modellspezifische Überschreibung pro Sitzung
setzen (`model=default` entfernt sie).
enthält eine Zeitstempelzeile. Dasselbe Tool kann optional eine Modellauswahl pro Session
setzen (`model=default` löscht sie).
Konfigurieren Sie dies mit:
Konfiguration mit:
- `agents.defaults.userTimezone`
- `agents.defaults.timeFormat` (`auto` | `12` | `24`)
Siehe [Datum und Uhrzeit](/de/date-time) für vollständige Verhaltensdetails.
Vollständige Verhaltensdetails finden Sie unter [Datum & Uhrzeit](/de/date-time).
## Skills
Wenn geeignete Skills existieren, injiziert OpenClaw eine kompakte **Liste verfügbarer Skills**
(`formatSkillsForPrompt`), die den **Dateipfad** für jeden Skill enthält. Der
Prompt weist das Modell an, `read` zu verwenden, um die SKILL.md am aufgeführten
Prompt weist das Modell an, `read` zu verwenden, um die SKILL.md am aufgelisteten
Ort zu laden (Arbeitsbereich, verwaltet oder gebündelt). Wenn keine Skills geeignet sind, wird der
Skills-Abschnitt ausgelassen.
Die Eignung umfasst Skill-Metadaten-Gates, Laufzeitumgebungs-/Konfigurationsprüfungen
Die Eignung umfasst Skill-Metadaten-Gates, Runtime-Umgebungs-/Konfigurationsprüfungen
und die effektive Skill-Allowlist des Agent, wenn `agents.defaults.skills` oder
`agents.list[].skills` konfiguriert ist.
Plugin-gebündelte Skills sind nur geeignet, wenn ihr besitzendes Plugin aktiviert ist.
Dadurch können Tool-Plugins tiefere Betriebsleitfäden bereitstellen, ohne die gesamte
Anleitung direkt in jede Tool-Beschreibung einzubetten.
Dadurch können Tool-Plugins tiefere Betriebsanleitungen bereitstellen, ohne alle
diese Hinweise direkt in jede Tool-Beschreibung einzubetten.
```
<available_skills>
@ -230,29 +240,28 @@ Anleitung direkt in jede Tool-Beschreibung einzubetten.
</available_skills>
```
Dies hält den Basis-Prompt klein und ermöglicht dennoch gezielte Skill-Nutzung.
Das hält den Basis-Prompt klein und ermöglicht dennoch gezielte Skill-Nutzung.
Das Budget für die Skills-Liste gehört dem Skills-Subsystem:
Das Budget der Skills-Liste gehört dem Skills-Subsystem:
- Globaler Standard: `skills.limits.maxSkillsPromptChars`
- Überschreibung pro Agent: `agents.list[].skillsLimits.maxSkillsPromptChars`
- Agent-spezifische Überschreibung: `agents.list[].skillsLimits.maxSkillsPromptChars`
Generische begrenzte Laufzeitauszüge verwenden eine andere Oberfläche:
Generische begrenzte Runtime-Auszüge verwenden eine andere Oberfläche:
- `agents.defaults.contextLimits.*`
- `agents.list[].contextLimits.*`
Diese Trennung hält die Skills-Größenbemessung getrennt von der Größenbemessung für Laufzeit-Lesen/-Injektion wie
`memory_get`, Live-Tool-Ergebnisse und AGENTS.md-Aktualisierungen nach Compaction.
Diese Aufteilung hält die Dimensionierung von Skills getrennt von der Dimensionierung für das Lesen/Injizieren zur Laufzeit, etwa `memory_get`, Live-Tool-Ergebnisse und AGENTS.md-Aktualisierungen nach der Compaction.
## Dokumentation
Der System-Prompt enthält einen Abschnitt **Dokumentation**. Wenn lokale Dokumentation verfügbar ist, verweist er auf das lokale OpenClaw-Dokumentationsverzeichnis (`docs/` in einem Git-Checkout oder die mitgelieferte Dokumentation des npm-Pakets). Wenn keine lokale Dokumentation verfügbar ist, weicht er auf [https://docs.openclaw.ai](https://docs.openclaw.ai) aus.
Der System-Prompt enthält einen Abschnitt **Dokumentation**. Wenn lokale Dokumentation verfügbar ist, verweist er auf das lokale OpenClaw-Dokumentationsverzeichnis (`docs/` in einem Git-Checkout oder die gebündelte npm-Paketdokumentation). Wenn keine lokale Dokumentation verfügbar ist, fällt er auf [https://docs.openclaw.ai](https://docs.openclaw.ai) zurück.
Derselbe Abschnitt enthält außerdem den Speicherort des OpenClaw-Quellcodes. Git-Checkouts stellen das lokale Quell-Root bereit, damit der Agent den Code direkt prüfen kann. Paketinstallationen enthalten die GitHub-Quell-URL und weisen den Agenten an, den Quellcode dort zu prüfen, wenn die Dokumentation unvollständig oder veraltet ist. Der Prompt erwähnt außerdem die öffentliche Dokumentationsspiegelung, den Community-Discord und ClawHub ([https://clawhub.ai](https://clawhub.ai)) für die Entdeckung von Skills. Er weist das Modell an, für OpenClaw-Verhalten, Befehle, Konfiguration oder Architektur zuerst die Dokumentation zu konsultieren und nach Möglichkeit selbst `openclaw status` auszuführen (und den Benutzer nur zu fragen, wenn ihm der Zugriff fehlt). Speziell für die Konfiguration verweist er Agenten auf die `gateway`-Tool-Aktion `config.schema.lookup` für exakte feldbezogene Dokumentation und Einschränkungen und anschließend auf `docs/gateway/configuration.md` und `docs/gateway/configuration-reference.md` für weiterführende Anleitung.
Derselbe Abschnitt enthält außerdem den Speicherort des OpenClaw-Quellcodes. Git-Checkouts stellen das lokale Source-Root bereit, damit der Agent Code direkt prüfen kann. Paketinstallationen enthalten die GitHub-Quell-URL und weisen den Agenten an, dort den Quellcode zu prüfen, wenn die Dokumentation unvollständig oder veraltet ist. Der Prompt erwähnt außerdem die öffentliche Dokumentationsspiegelung, den Community-Discord und ClawHub ([https://clawhub.ai](https://clawhub.ai)) zur Entdeckung von Skills. Er weist das Modell an, zuerst die Dokumentation zu OpenClaw-Verhalten, -Befehlen, -Konfiguration oder -Architektur zu konsultieren und nach Möglichkeit selbst `openclaw status` auszuführen (und den Benutzer nur zu fragen, wenn ihm der Zugriff fehlt). Speziell für die Konfiguration verweist er Agenten zuerst auf die `gateway`-Tool-Aktion `config.schema.lookup` für exakte Dokumentation und Einschränkungen auf Feldebene, anschließend auf `docs/gateway/configuration.md` und `docs/gateway/configuration-reference.md` für weiterführende Anleitung.
## Verwandt
## Verwandte Themen
- [Agenten-Laufzeit](/de/concepts/agent)
- [Agenten-Arbeitsbereich](/de/concepts/agent-workspace)
- [Agent-Laufzeitumgebung](/de/concepts/agent)
- [Agent-Arbeitsbereich](/de/concepts/agent-workspace)
- [Kontext-Engine](/de/concepts/context-engine)

95
docs/de/nodes/audio.md
View File

@ -1,29 +1,30 @@
---
read_when:
- Audio-Transkription oder Medienverarbeitung ändern
summary: Wie eingehende Audio-/Sprachnachrichten heruntergeladen, transkribiert und in Antworten eingefügt werden
title: Audio und Sprachnotizen
- Audiotranskription oder Medienverarbeitung ändern
summary: Wie eingehende Audio-/Sprachnotizen heruntergeladen, transkribiert und in Antworten eingefügt werden
title: Audio- und Sprachnotizen
x-i18n:
generated_at: "2026-04-30T07:01:55Z"
generated_at: "2026-05-02T23:39:04Z"
model: gpt-5.5
provider: openai
source_hash: 35074d79104f767ee252064462202a8ec21ac26f6db25c39e67f31f6b40edeb7
source_hash: 91cd6951f80c6137061a7d4e82415b0872bc92c6d6ad136273a2e9ad7ec00ac1
source_path: nodes/audio.md
workflow: 16
---
# Audio / Sprachnotizen (2026-01-17)
# Audio-/Sprachnotizen (2026-01-17)
## Was funktioniert
- **Medienverständnis (Audio)**: Wenn Audioverständnis aktiviert ist (oder automatisch erkannt wird), führt OpenClaw Folgendes aus:
1. Sucht den ersten Audioanhang (lokaler Pfad oder URL) und lädt ihn bei Bedarf herunter.
2. Erzwingt `maxBytes`, bevor der Anhang an jeden Modelleintrag gesendet wird.
3. Führt den ersten geeigneten Modelleintrag der Reihe nach aus (Provider oder CLI).
1. Es findet den ersten Audioanhang (lokaler Pfad oder URL) und lädt ihn bei Bedarf herunter.
2. Es erzwingt `maxBytes`, bevor an jeden Modelleintrag gesendet wird.
3. Es führt den ersten geeigneten Modelleintrag in der Reihenfolge aus (Provider oder CLI).
4. Wenn dies fehlschlägt oder übersprungen wird (Größe/Timeout), wird der nächste Eintrag versucht.
5. Bei Erfolg wird `Body` durch einen `[Audio]`-Block ersetzt und `{{Transcript}}` gesetzt.
5. Bei Erfolg ersetzt es `Body` durch einen `[Audio]`-Block und setzt `{{Transcript}}`.
- **Befehlsparsing**: Wenn die Transkription erfolgreich ist, werden `CommandBody`/`RawBody` auf das Transkript gesetzt, sodass Slash-Befehle weiterhin funktionieren.
- **Ausführliche Protokollierung**: Mit `--verbose` protokollieren wir, wann die Transkription ausgeführt wird und wann sie den Body ersetzt.
- **Ausführliche Protokollierung**: In `--verbose` protokollieren wir, wann die Transkription ausgeführt wird und wann sie den Body ersetzt.
- **Diktat in der Steuerungs-UI**: Der Chat-Composer kann einen im Browser aufgenommenen Mikrofonclip an `chat.transcribeAudio` senden. Dieser Gateway-RPC schreibt den Clip in eine temporäre lokale Datei, führt dieselbe Audio-Transkriptionspipeline aus, gibt Entwurfstext an den Browser zurück und löscht die temporäre Datei. Er erstellt nicht selbst einen Agentenlauf.
## Automatische Erkennung (Standard)
@ -35,18 +36,18 @@ erkennt OpenClaw automatisch in dieser Reihenfolge und stoppt bei der ersten fun
- `sherpa-onnx-offline` (erfordert `SHERPA_ONNX_MODEL_DIR` mit Encoder/Decoder/Joiner/Tokens)
- `whisper-cli` (aus `whisper-cpp`; verwendet `WHISPER_CPP_MODEL` oder das gebündelte Tiny-Modell)
- `whisper` (Python-CLI; lädt Modelle automatisch herunter)
3. **Gemini CLI** (`gemini`) mit `read_many_files`
3. **Gemini-CLI** (`gemini`) mit `read_many_files`
4. **Provider-Authentifizierung**
- Konfigurierte `models.providers.*`-Einträge, die Audio unterstützen, werden zuerst versucht
- Gebündelte Fallback-Reihenfolge: OpenAI → Groq → xAI → Deepgram → Google → SenseAudio → ElevenLabs → Mistral
Um die automatische Erkennung zu deaktivieren, setzen Sie `tools.media.audio.enabled: false`.
Um sie anzupassen, setzen Sie `tools.media.audio.models`.
Hinweis: Die Erkennung von Binärdateien ist unter macOS/Linux/Windows nach bestem Bemühen; stellen Sie sicher, dass die CLI in `PATH` liegt (wir erweitern `~`), oder setzen Sie ein explizites CLI-Modell mit vollständigem Befehlspfad.
Zum Anpassen setzen Sie `tools.media.audio.models`.
Hinweis: Die Binärerkennung erfolgt nach bestem Bemühen unter macOS/Linux/Windows; stellen Sie sicher, dass die CLI auf `PATH` liegt (wir erweitern `~`), oder setzen Sie ein explizites CLI-Modell mit vollständigem Befehlspfad.
## Konfigurationsbeispiele
### Provider + CLI-Fallback (OpenAI + Whisper CLI)
### Provider + CLI-Fallback (OpenAI + Whisper-CLI)
```json5
{
@ -70,7 +71,7 @@ Hinweis: Die Erkennung von Binärdateien ist unter macOS/Linux/Windows nach best
}
```
### Nur Provider mit Scope-Gating
### Nur Provider mit Bereichssteuerung
```json5
{
@ -134,7 +135,7 @@ Hinweis: Die Erkennung von Binärdateien ist unter macOS/Linux/Windows nach best
}
```
### Transkript in den Chat zurücksenden (Opt-in)
### Transkript in den Chat zurückgeben (Opt-in)
```json5
{
@ -153,28 +154,28 @@ Hinweis: Die Erkennung von Binärdateien ist unter macOS/Linux/Windows nach best
## Hinweise und Grenzen
- Die Provider-Authentifizierung folgt der standardmäßigen Authentifizierungsreihenfolge für Modelle (Auth-Profile, Umgebungsvariablen, `models.providers.*.apiKey`).
- Die Provider-Authentifizierung folgt der Standardreihenfolge für die Modellauthentifizierung (Authentifizierungsprofile, Umgebungsvariablen, `models.providers.*.apiKey`).
- Details zur Groq-Einrichtung: [Groq](/de/providers/groq).
- Deepgram übernimmt `DEEPGRAM_API_KEY`, wenn `provider: "deepgram"` verwendet wird.
- Details zur Deepgram-Einrichtung: [Deepgram (Audiotranskription)](/de/providers/deepgram).
- Deepgram greift `DEEPGRAM_API_KEY` auf, wenn `provider: "deepgram"` verwendet wird.
- Details zur Deepgram-Einrichtung: [Deepgram (Audio-Transkription)](/de/providers/deepgram).
- Details zur Mistral-Einrichtung: [Mistral](/de/providers/mistral).
- SenseAudio übernimmt `SENSEAUDIO_API_KEY`, wenn `provider: "senseaudio"` verwendet wird.
- SenseAudio greift `SENSEAUDIO_API_KEY` auf, wenn `provider: "senseaudio"` verwendet wird.
- Details zur SenseAudio-Einrichtung: [SenseAudio](/de/providers/senseaudio).
- Audio-Provider können `baseUrl`, `headers` und `providerOptions` über `tools.media.audio` überschreiben.
- Die standardmäßige Größenbegrenzung beträgt 20 MB (`tools.media.audio.maxBytes`). Zu große Audiodateien werden für dieses Modell übersprungen und der nächste Eintrag wird versucht.
- Winzige/leere Audiodateien unter 1024 Bytes werden vor der Provider-/CLI-Transkription übersprungen.
- Die standardmäßige Größenbegrenzung beträgt 20 MB (`tools.media.audio.maxBytes`). Zu große Audiodateien werden für dieses Modell übersprungen, und der nächste Eintrag wird versucht.
- Sehr kleine/leere Audiodateien unter 1024 Byte werden vor der Provider-/CLI-Transkription übersprungen.
- Der Standardwert für `maxChars` bei Audio ist **nicht gesetzt** (vollständiges Transkript). Setzen Sie `tools.media.audio.maxChars` oder `maxChars` pro Eintrag, um die Ausgabe zu kürzen.
- Der automatische OpenAI-Standard ist `gpt-4o-mini-transcribe`; setzen Sie `model: "gpt-4o-transcribe"` für höhere Genauigkeit.
- Verwenden Sie `tools.media.audio.attachments`, um mehrere Sprachnotizen zu verarbeiten (`mode: "all"` + `maxAttachments`).
- Das Transkript ist für Vorlagen als `{{Transcript}}` verfügbar.
- `tools.media.audio.echoTranscript` ist standardmäßig deaktiviert; aktivieren Sie es, um vor der Agent-Verarbeitung eine Transkriptbestätigung an den ursprünglichen Chat zurückzusenden.
- Das Transkript ist in Vorlagen als `{{Transcript}}` verfügbar.
- `tools.media.audio.echoTranscript` ist standardmäßig deaktiviert; aktivieren Sie es, um vor der Agentenverarbeitung eine Transkriptbestätigung an den ursprünglichen Chat zurückzusenden.
- `tools.media.audio.echoFormat` passt den Echo-Text an (Platzhalter: `{transcript}`).
- CLI-stdout ist begrenzt (5 MB); halten Sie die CLI-Ausgabe knapp.
- CLI-`args` sollte `{{MediaPath}}` für den lokalen Audiodateipfad verwenden. Führen Sie `openclaw doctor --fix` aus, um veraltete `{input}`-Platzhalter aus älteren `audio.transcription.command`-Konfigurationen zu migrieren.
- Die CLI-Standardausgabe ist begrenzt (5 MB); halten Sie die CLI-Ausgabe knapp.
- CLI-`args` sollten `{{MediaPath}}` für den lokalen Audiodateipfad verwenden. Führen Sie `openclaw doctor --fix` aus, um veraltete `{input}`-Platzhalter aus älteren `audio.transcription.command`-Konfigurationen zu migrieren.
### Unterstützung für Proxy-Umgebungen
Provider-basierte Audiotranskription berücksichtigt standardmäßige ausgehende Proxy-Umgebungsvariablen:
Provider-basierte Audio-Transkription berücksichtigt standardmäßige ausgehende Proxy-Umgebungsvariablen:
- `HTTPS_PROXY`
- `HTTP_PROXY`
@ -185,40 +186,40 @@ Provider-basierte Audiotranskription berücksichtigt standardmäßige ausgehende
Wenn keine Proxy-Umgebungsvariablen gesetzt sind, wird direkter ausgehender Zugriff verwendet. Wenn die Proxy-Konfiguration fehlerhaft ist, protokolliert OpenClaw eine Warnung und fällt auf direkten Abruf zurück.
## Mention-Erkennung in Gruppen
## Erwähnungserkennung in Gruppen
Wenn `requireMention: true` für einen Gruppenchat gesetzt ist, transkribiert OpenClaw Audio jetzt **vor** der Prüfung auf Mentions. Dadurch können Sprachnotizen auch dann verarbeitet werden, wenn sie Mentions enthalten.
Wenn `requireMention: true` für einen Gruppenchat gesetzt ist, transkribiert OpenClaw Audio jetzt **vor** der Prüfung auf Erwähnungen. Dadurch können Sprachnotizen auch dann verarbeitet werden, wenn sie Erwähnungen enthalten.
**So funktioniert es:**
1. Wenn eine Sprachnachricht keinen Text-Body hat und die Gruppe Mentions erfordert, führt OpenClaw eine „Preflight“-Transkription aus.
2. Das Transkript wird auf Mention-Muster geprüft (z. B. `@BotName`, Emoji-Auslöser).
3. Wenn eine Mention gefunden wird, durchläuft die Nachricht die vollständige Antwort-Pipeline.
4. Das Transkript wird für die Mention-Erkennung verwendet, damit Sprachnotizen das Mention-Gate passieren können.
1. Wenn eine Sprachnachricht keinen Text-Body hat und die Gruppe Erwähnungen erfordert, führt OpenClaw eine „Preflight“-Transkription aus.
2. Das Transkript wird auf Erwähnungsmuster geprüft (z. B. `@BotName`, Emoji-Auslöser).
3. Wenn eine Erwähnung gefunden wird, durchläuft die Nachricht die vollständige Antwortpipeline.
4. Das Transkript wird für die Erwähnungserkennung verwendet, sodass Sprachnotizen das Erwähnungs-Gate passieren können.
**Fallback-Verhalten:**
- Wenn die Transkription während des Preflight fehlschlägt (Timeout, API-Fehler usw.), wird die Nachricht basierend auf reiner Text-Mention-Erkennung verarbeitet.
- Wenn die Transkription während des Preflight fehlschlägt (Timeout, API-Fehler usw.), wird die Nachricht anhand der reinen Text-Erwähnungserkennung verarbeitet.
- Dadurch wird sichergestellt, dass gemischte Nachrichten (Text + Audio) nie fälschlicherweise verworfen werden.
**Opt-out pro Telegram-Gruppe/-Thema:**
**Opt-out pro Telegram-Gruppe/Thema:**
- Setzen Sie `channels.telegram.groups.<chatId>.disableAudioPreflight: true`, um Preflight-Transkript-Mention-Prüfungen für diese Gruppe zu überspringen.
- Setzen Sie `channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight`, um dies pro Thema zu überschreiben (`true` zum Überspringen, `false` zum erzwungenen Aktivieren).
- Standard ist `false` (Preflight aktiviert, wenn Mention-Gating-Bedingungen zutreffen).
- Setzen Sie `channels.telegram.groups.<chatId>.disableAudioPreflight: true`, um Preflight-Transkriptprüfungen auf Erwähnungen für diese Gruppe zu überspringen.
- Setzen Sie `channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight`, um pro Thema zu überschreiben (`true` zum Überspringen, `false` zum Erzwingen der Aktivierung).
- Standard ist `false` (Preflight aktiviert, wenn die durch Erwähnungen gesteuerten Bedingungen zutreffen).
**Beispiel:** Ein Benutzer sendet in einer Telegram-Gruppe mit `requireMention: true` eine Sprachnotiz mit dem Inhalt „Hey @Claude, what's the weather?“. Die Sprachnotiz wird transkribiert, die Mention wird erkannt und der Agent antwortet.
**Beispiel:** Ein Benutzer sendet in einer Telegram-Gruppe mit `requireMention: true` eine Sprachnotiz mit dem Inhalt „Hey @Claude, wie ist das Wetter?“. Die Sprachnotiz wird transkribiert, die Erwähnung wird erkannt, und der Agent antwortet.
## Stolperfallen
## Fallstricke
- Scope-Regeln verwenden First-match-wins. `chatType` wird auf `direct`, `group` oder `room` normalisiert.
- Stellen Sie sicher, dass Ihre CLI mit 0 beendet wird und Klartext ausgibt; JSON muss über `jq -r .text` angepasst werden.
- Wenn Sie bei `parakeet-mlx` `--output-dir` übergeben, liest OpenClaw `<output-dir>/<media-basename>.txt`, wenn `--output-format` `txt` ist (oder weggelassen wurde); Ausgabeformate ungleich `txt` fallen auf stdout-Parsing zurück.
- Halten Sie Timeouts angemessen (`timeoutSeconds`, Standard 60 s), um die Antwortwarteschlange nicht zu blockieren.
- Die Preflight-Transkription verarbeitet für die Mention-Erkennung nur den **ersten** Audioanhang. Zusätzliches Audio wird während der Hauptphase des Medienverständnisses verarbeitet.
- Bereichsregeln verwenden „erste Übereinstimmung gewinnt“. `chatType` wird zu `direct`, `group` oder `room` normalisiert.
- Stellen Sie sicher, dass Ihre CLI mit 0 beendet wird und Klartext ausgibt; JSON muss über `jq -r .text` aufbereitet werden.
- Bei `parakeet-mlx` liest OpenClaw, wenn Sie `--output-dir` übergeben, `<output-dir>/<media-basename>.txt`, wenn `--output-format` `txt` ist (oder ausgelassen wird); Nicht-`txt`-Ausgabeformate fallen auf das Parsen von stdout zurück.
- Halten Sie Timeouts angemessen (`timeoutSeconds`, Standard 60 s), um ein Blockieren der Antwortwarteschlange zu vermeiden.
- Die Preflight-Transkription verarbeitet zur Erwähnungserkennung nur den **ersten** Audioanhang. Zusätzliches Audio wird während der Hauptphase des Medienverständnisses verarbeitet.
## Verwandt
- [Medienverständnis](/de/nodes/media-understanding)
- [Sprechmodus](/de/nodes/talk)
- [Voice Wake](/de/nodes/voicewake)
- [Sprachaktivierung](/de/nodes/voicewake)

890
docs/de/plugins/codex-harness.md
View File

File diff suppressed because it is too large Load Diff

90
docs/de/providers/arcee.md
View File

@ -1,43 +1,43 @@
---
read_when:
- Sie möchten Arcee AI mit OpenClaw verwenden.
- Sie benötigen die API-Key-Umgebungsvariable oder die CLI-Authentifizierungsoption.
summary: Einrichtung von Arcee AI (Authentifizierung + Modellauswahl)
- Sie möchten Arcee AI mit OpenClaw verwenden
- Sie benötigen die Umgebungsvariable für den API-Schlüssel oder die CLI-Authentifizierungsoption
summary: Arcee AI-Einrichtung (Authentifizierung + Modellauswahl)
title: Arcee AI
x-i18n:
generated_at: "2026-04-24T06:52:55Z"
model: gpt-5.4
generated_at: "2026-05-02T23:39:13Z"
model: gpt-5.5
provider: openai
source_hash: 54989e1706901fedc8a0c816ca7ee7f877fa4b973697540dd90cb9182420043f
source_hash: 622ee5288aec3ae0b45d3f06ba65fd6f972e07d7a7596ae3905d6fbdac0bf737
source_path: providers/arcee.md
workflow: 15
workflow: 16
---
[Arcee AI](https://arcee.ai) bietet Zugriff auf die Trinity-Familie von Mixture-of-Experts-Modellen über eine OpenAI-kompatible API. Alle Trinity-Modelle sind unter Apache 2.0 lizenziert.
[Arcee AI](https://arcee.ai) bietet über eine OpenAI-kompatible API Zugriff auf die Trinity-Familie von Mixture-of-Experts-Modellen. Alle Trinity-Modelle sind unter Apache 2.0 lizenziert.
Auf Modelle von Arcee AI kann direkt über die Arcee-Plattform oder über [OpenRouter](/de/providers/openrouter) zugegriffen werden.
Auf Arcee AI-Modelle kann direkt über die Arcee-Plattform oder über [OpenRouter](/de/providers/openrouter) zugegriffen werden.
| Eigenschaft | Wert |
| ----------- | ------------------------------------------------------------------------------------- |
| Provider | `arcee` |
| Auth | `ARCEEAI_API_KEY` (direkt) oder `OPENROUTER_API_KEY` (über OpenRouter) |
| API | OpenAI-kompatibel |
| Base URL | `https://api.arcee.ai/api/v1` (direkt) oder `https://openrouter.ai/api/v1` (OpenRouter) |
| -------- | ------------------------------------------------------------------------------------- |
| Provider | `arcee` |
| Auth | `ARCEEAI_API_KEY` (direkt) oder `OPENROUTER_API_KEY` (über OpenRouter) |
| API | OpenAI-kompatibel |
| Basis-URL | `https://api.arcee.ai/api/v1` (direkt) oder `https://openrouter.ai/api/v1` (OpenRouter) |
## Erste Schritte
<Tabs>
<Tab title="Direkt (Arcee-Plattform)">
<Steps>
<Step title="API-Key abrufen">
Erstellen Sie einen API-Key bei [Arcee AI](https://chat.arcee.ai/).
<Step title="API-Schlüssel abrufen">
Erstellen Sie einen API-Schlüssel bei [Arcee AI](https://chat.arcee.ai/).
</Step>
<Step title="Onboarding ausführen">
```bash
openclaw onboard --auth-choice arceeai-api-key
```
</Step>
<Step title="Ein Standardmodell festlegen">
<Step title="Standardmodell festlegen">
```json5
{
agents: {
@ -53,15 +53,15 @@ Auf Modelle von Arcee AI kann direkt über die Arcee-Plattform oder über [OpenR
<Tab title="Über OpenRouter">
<Steps>
<Step title="API-Key abrufen">
Erstellen Sie einen API-Key bei [OpenRouter](https://openrouter.ai/keys).
<Step title="API-Schlüssel abrufen">
Erstellen Sie einen API-Schlüssel bei [OpenRouter](https://openrouter.ai/keys).
</Step>
<Step title="Onboarding ausführen">
```bash
openclaw onboard --auth-choice arceeai-openrouter
```
</Step>
<Step title="Ein Standardmodell festlegen">
<Step title="Standardmodell festlegen">
```json5
{
agents: {
@ -72,14 +72,14 @@ Auf Modelle von Arcee AI kann direkt über die Arcee-Plattform oder über [OpenR
}
```
Dieselben Modellreferenzen funktionieren sowohl für direkte Setups als auch über OpenRouter (zum Beispiel `arcee/trinity-large-thinking`).
Dieselben Modellreferenzen funktionieren sowohl für direkte als auch für OpenRouter-Setups (zum Beispiel `arcee/trinity-large-thinking`).
</Step>
</Steps>
</Tab>
</Tabs>
## Nicht interaktives Setup
## Nicht interaktive Einrichtung
<Tabs>
<Tab title="Direkt (Arcee-Plattform)">
@ -101,51 +101,51 @@ Auf Modelle von Arcee AI kann direkt über die Arcee-Plattform oder über [OpenR
</Tab>
</Tabs>
## Eingebauter Katalog
## Integrierter Katalog
OpenClaw wird derzeit mit diesem gebündelten Arcee-Katalog ausgeliefert:
OpenClaw enthält derzeit diesen gebündelten Arcee-Katalog:
| Modellreferenz | Name | Eingabe | Kontext | Kosten (In/Out pro 1M) | Hinweise |
| ----------------------------- | ---------------------- | ------- | ------- | ---------------------- | ------------------------------------------- |
| `arcee/trinity-large-thinking` | Trinity Large Thinking | Text | 256K | $0.25 / $0.90 | Standardmodell; Reasoning aktiviert |
| `arcee/trinity-large-preview` | Trinity Large Preview | Text | 128K | $0.25 / $1.00 | Allgemeiner Zweck; 400B Parameter, 13B aktiv |
| `arcee/trinity-mini` | Trinity Mini 26B | Text | 128K | $0.045 / $0.15 | Schnell und kosteneffizient; Function Calling |
| Modellreferenz | Name | Eingabe | Kontext | Kosten (Ein-/Ausgabe pro 1 Mio.) | Hinweise |
| ------------------------------ | ---------------------- | ----- | ------- | -------------------- | ------------------------------------------ |
| `arcee/trinity-large-thinking` | Trinity Large Thinking | Text | 256K | $0.25 / $0.90 | Standardmodell; Reasoning aktiviert; keine Tools |
| `arcee/trinity-large-preview` | Trinity Large Preview | Text | 128K | $0.25 / $1.00 | Allzweckmodell; 400B Parameter, 13B aktiv |
| `arcee/trinity-mini` | Trinity Mini 26B | Text | 128K | $0.045 / $0.15 | Schnell und kosteneffizient; Funktionsaufrufe |
<Tip>
Das Onboarding-Preset setzt `arcee/trinity-large-thinking` als Standardmodell.
Die Onboarding-Voreinstellung legt `arcee/trinity-large-thinking` als Standardmodell fest. Es ist ein reines Reasoning-/Textmodell und unterstützt weder Tool-Nutzung noch Funktionsaufrufe.
</Tip>
## Unterstützte Funktionen
| Funktion | Unterstützt |
| --------------------------------------------- | ----------------------------- |
| Streaming | Ja |
| Tool-Nutzung / Function Calling | Ja |
| Strukturierte Ausgabe (JSON-Modus und JSON-Schema) | Ja |
| Erweitertes Thinking | Ja (Trinity Large Thinking) |
| Funktion | Unterstützt |
| --------------------------------------------- | ------------------------------------------- |
| Streaming | Ja |
| Tool-Nutzung / Funktionsaufrufe | Modellabhängig; nicht Trinity Large Thinking |
| Strukturierte Ausgabe (JSON-Modus und JSON-Schema) | Ja |
| Erweitertes Denken | Ja (Trinity Large Thinking) |
<AccordionGroup>
<Accordion title="Hinweis zur Umgebung">
Wenn das Gateway als Daemon läuft (launchd/systemd), stellen Sie sicher, dass `ARCEEAI_API_KEY`
(oder `OPENROUTER_API_KEY`) diesem Prozess zur Verfügung steht (zum Beispiel in
Wenn der Gateway als Daemon ausgeführt wird (launchd/systemd), stellen Sie sicher, dass `ARCEEAI_API_KEY`
(oder `OPENROUTER_API_KEY`) für diesen Prozess verfügbar ist (zum Beispiel in
`~/.openclaw/.env` oder über `env.shellEnv`).
</Accordion>
<Accordion title="OpenRouter-Routing">
Wenn Sie Arcee-Modelle über OpenRouter verwenden, gelten dieselben Modellreferenzen `arcee/*`.
OpenClaw übernimmt das Routing transparent basierend auf Ihrer Authentifizierungswahl. Siehe die
[OpenRouter-Provider-Dokumentation](/de/providers/openrouter) für OpenRouter-spezifische
Konfigurationsdetails.
Wenn Sie Arcee-Modelle über OpenRouter verwenden, gelten dieselben `arcee/*`-Modellreferenzen.
OpenClaw verarbeitet das Routing transparent anhand Ihrer Auth-Auswahl. Weitere OpenRouter-spezifische
Konfigurationsdetails finden Sie in der
[OpenRouter-Provider-Dokumentation](/de/providers/openrouter).
</Accordion>
</AccordionGroup>
## Verwandt
## Verwandte Themen
<CardGroup cols={2}>
<Card title="OpenRouter" href="/de/providers/openrouter" icon="shuffle">
Zugriff auf Arcee-Modelle und viele andere über einen einzigen API-Key.
Greifen Sie mit einem einzigen API-Schlüssel auf Arcee-Modelle und viele andere zu.
</Card>
<Card title="Modellauswahl" href="/de/concepts/model-providers" icon="layers">
Auswahl von Providern, Modellreferenzen und Failover-Verhalten.
Provider, Modellreferenzen und Failover-Verhalten auswählen.
</Card>
</CardGroup>

600
docs/de/reference/RELEASING.md
View File

@ -1,178 +1,179 @@
---
read_when:
- Suche nach Definitionen öffentlicher Release-Kanäle
- Suche nach Definitionen für öffentliche Release-Kanäle
- Release-Validierung oder Paketabnahme ausführen
- Suchen Sie Informationen zu Versionsbenennung und Veröffentlichungsrhythmus
- Suche nach Versionsbenennung und Veröffentlichungsrhythmus
summary: Release-Lanes, Operator-Checkliste, Validierungsboxen, Versionsbenennung und Taktung
title: Release-Richtlinie
x-i18n:
generated_at: "2026-05-02T21:01:50Z"
generated_at: "2026-05-02T23:39:26Z"
model: gpt-5.5
provider: openai
source_hash: 493cb8b42f0e15f3bf5f8fb9be7d01fd626f4f16db9ac0a85e6efa747ef12d12
source_hash: ba316d1736eae8edd2fb0a71b9a3da345f8895c3b536e9a1f619718ea12fc851
source_path: reference/RELEASING.md
workflow: 16
---
OpenClaw hat vier öffentliche Release-Lanes:
OpenClaw hat drei öffentliche Release-Lanes:
- stable: getaggte Releases, die standardmäßig nach npm `beta` veröffentlichen oder nach npm `latest`, wenn dies ausdrücklich angefordert wird
- alpha: Prerelease-Tags, die nach npm `alpha` veröffentlichen
- beta: Prerelease-Tags, die nach npm `beta` veröffentlichen
- dev: der bewegliche Head von `main`
- stable: getaggte Releases, die standardmäßig nach npm `beta` veröffentlicht werden oder nach npm `latest`, wenn dies ausdrücklich angefordert wird
- beta: Vorabversions-Tags, die nach npm `beta` veröffentlicht werden
- dev: die fortlaufende Spitze von `main`
## Versionsbenennung
- Stabile Release-Version: `YYYY.M.D`
- Version eines stabilen Releases: `YYYY.M.D`
- Git-Tag: `vYYYY.M.D`
- Stabile Korrektur-Release-Version: `YYYY.M.D-N`
- Version eines stabilen Korrektur-Releases: `YYYY.M.D-N`
- Git-Tag: `vYYYY.M.D-N`
- Alpha-Prerelease-Version: `YYYY.M.D-alpha.N`
- Git-Tag: `vYYYY.M.D-alpha.N`
- Beta-Prerelease-Version: `YYYY.M.D-beta.N`
- Version einer Beta-Vorabversion: `YYYY.M.D-beta.N`
- Git-Tag: `vYYYY.M.D-beta.N`
- Monat oder Tag nicht mit führenden Nullen schreiben
- `latest` bedeutet das aktuell promotete stabile npm-Release
- `alpha` bedeutet das aktuelle Alpha-Installationsziel
- Monat und Tag nicht mit führenden Nullen auffüllen
- `latest` bedeutet das aktuell hochgestufte stabile npm-Release
- `beta` bedeutet das aktuelle Beta-Installationsziel
- Stabile und stabile Korrektur-Releases veröffentlichen standardmäßig nach npm `beta`; Release-Operatoren können ausdrücklich `latest` als Ziel wählen oder später einen geprüften Beta-Build promoten
- Stabile Releases und stabile Korrektur-Releases werden standardmäßig nach npm `beta` veröffentlicht; Release-Operatoren können ausdrücklich `latest` als Ziel wählen oder später einen geprüften Beta-Build 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/Notarisierung der mac-App für stabile Releases reserviert bleibt, sofern nicht ausdrücklich angefordert
Beta-Releases validieren und veröffentlichen normalerweise zuerst den npm-/Paketpfad, während
Build, Signierung und Notarisierung der Mac-App für stabile Releases reserviert sind, sofern nicht ausdrücklich angefordert
## Release-Rhythmus
## Release-Takt
- Releases bewegen sich Beta-zuerst
- Releases laufen zuerst über Beta
- Stable folgt erst, nachdem die neueste Beta validiert wurde
- Maintainer erstellen Releases normalerweise von einem `release/YYYY.M.D`-Branch, der
aus dem aktuellen `main` erstellt wurde, damit Release-Validierung und Fixes neue
- Maintainer erstellen Releases normalerweise aus einem `release/YYYY.M.D`-Branch, der
aus dem 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
- Detailliertes Release-Verfahren, Freigaben, Anmeldedaten und Wiederherstellungshinweise sind
- Wenn ein Beta-Tag gepusht oder veröffentlicht wurde und eine Korrektur benötigt, erstellen Maintainer
stattdessen den nächsten `-beta.N`-Tag, anstatt den alten Beta-Tag zu löschen oder neu zu erstellen
- Detaillierte Release-Verfahren, Freigaben, Zugangsdaten und Wiederherstellungshinweise sind
nur für Maintainer bestimmt
## Checkliste für Release-Operatoren
Diese Checkliste beschreibt die öffentliche Form des Release-Ablaufs. Private Anmeldedaten,
Signierung, Notarisierung, Dist-Tag-Wiederherstellung und Details zu Notfall-Rollbacks bleiben im
Diese Checkliste ist die öffentliche Form des Release-Ablaufs. Private Zugangsdaten,
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: neueste Änderungen pullen, bestätigen, dass der Ziel-Commit gepusht ist,
und bestätigen, dass die aktuelle CI von `main` grün genug ist, um davon zu branchen.
1. Vom aktuellen `main` starten: neuesten Stand pullen, bestätigen, dass der Ziel-Commit gepusht ist,
und bestätigen, dass die aktuelle `main`-CI grün genug ist, um davon zu branchen.
2. Den obersten Abschnitt in `CHANGELOG.md` aus der echten Commit-Historie mit
`/changelog` neu schreiben, Einträge nutzerorientiert halten, committen, pushen und
vor dem Branching noch einmal rebasen/pullen.
3. Release-Kompatibilitätseinträge 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 weiter abgedeckt bleibt, oder dokumentieren, warum sie
Kompatibilität nur entfernen, wenn der Upgrade-Pfad weiterhin abgedeckt bleibt, oder dokumentieren, warum sie
absichtlich beibehalten wird.
4. `release/YYYY.M.D` aus dem aktuellen `main` erstellen; normale Release-Arbeiten nicht
4. `release/YYYY.M.D` aus dem aktuellen `main` erstellen; normale Release-Arbeit nicht
direkt auf `main` durchführen.
5. Jede erforderliche Versionsstelle für das beabsichtigte Tag erhöhen, dann
`pnpm plugins:sync` ausführen, damit veröffentlichbare Plugin-Pakete dieselbe Release-
Version und Kompatibilitätsmetadaten teilen, danach den lokalen deterministischen Preflight ausführen:
5. Jede erforderliche Versionsstelle für den vorgesehenen 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:
`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-stelliger Release-Branch-SHA für einen nur zur Validierung dienenden
Preflight erlaubt. Die erfolgreiche `preflight_run_id` speichern.
ist für einen reinen Validierungs-Preflight ein vollständiger Release-Branch-SHA mit 40 Zeichen erlaubt.
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 einzige manuelle Einstiegspunkt
Release-Branch, Tag oder vollständigen Commit-SHA anstoßen. Dies ist der einzige 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, Provider- oder Modell-Allowlist erneut ausführen, die
den Fix nachweist. Den gesamten Umbrella nur erneut ausführen, wenn die geänderte Oberfläche
8. Wenn die Validierung fehlschlägt, auf dem Release-Branch korrigieren und die kleinste fehlgeschlagene
Datei, Lane, den Workflow-Job, das Paketprofil, den Provider oder die Modell-Allowlist erneut ausführen, die
die Korrektur belegt. Das vollständige Umbrella nur erneut ausführen, wenn die geänderte Oberfläche
frühere Nachweise veralten lässt.
9. Für Alpha oder Beta `vYYYY.M.D-alpha.N` oder `vYYYY.M.D-beta.N` taggen, dann `OpenClaw Release Publish` vom
passenden `release/YYYY.M.D`-Branch ausführen. Es verifiziert `pnpm plugins:sync:check`,
veröffentlicht zuerst alle veröffentlichbaren Plugin-Pakete nach npm, veröffentlicht dieselbe
Menge anschließend nach ClawHub und promotet dann das vorbereitete OpenClaw-npm-Preflight-
Artefakt mit dem passenden Dist-Tag. Nach der Veröffentlichung die Package-Acceptance nach dem Veröffentlichen
gegen das veröffentlichte Paket `openclaw@YYYY.M.D-alpha.N`, `openclaw@alpha`,
`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;
den alten Prerelease nicht löschen oder umschreiben.
10. Für stable nur fortfahren, nachdem die geprüfte Beta oder der Release Candidate die
9. Für Beta `vYYYY.M.D-beta.N` taggen, dann `OpenClaw Release Publish` aus
dem passenden `release/YYYY.M.D`-Branch ausführen. Es prüft `pnpm plugins:sync:check`,
veröffentlicht zuerst alle veröffentlichbaren Plugin-Pakete nach npm, veröffentlicht denselben
Satz danach nach ClawHub und stuft anschließend das vorbereitete OpenClaw-npm-Preflight-
Artefakt mit dem passenden dist-tag hoch. Nach der Veröffentlichung die Paketakzeptanz nach der Veröffentlichung
gegen das veröffentlichte Paket `openclaw@YYYY.M.D-beta.N` oder
`openclaw@beta` ausführen. Wenn eine gepushte oder veröffentlichte Vorabversion eine Korrektur benötigt,
die nächste passende Vorabversionsnummer erstellen; die alte
Vorabversion nicht löschen oder umschreiben.
10. Für Stable nur fortfahren, 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` und verwendet das erfolgreiche Preflight-Artefakt über
`preflight_run_id` erneut; die stabile macOS-Release-Bereitschaft 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 eigenständige
veröffentlichte-npm-Telegram-E2E, wenn Sie Channel-Nachweise nach der Veröffentlichung benötigen,
Dist-Tag-Promotion bei Bedarf, GitHub-Release-/Prerelease-Notizen aus dem
vollständigen passenden Abschnitt in `CHANGELOG.md` und die Schritte zur Release-Ankündigung.
`preflight_run_id` wieder; die Bereitschaft des stabilen macOS-Releases erfordert außerdem die
paketierte `.zip`, `.dmg`, `.dSYM.zip` und die aktualisierte `appcast.xml` auf `main`.
11. Nach der Veröffentlichung den npm-Verifizierer nach der Veröffentlichung ausführen, optional das eigenständige
Telegram-E2E mit veröffentlichtem npm, wenn Sie einen Kanalnachweis nach der Veröffentlichung benötigen,
dist-tag-Hochstufung bei Bedarf, GitHub-Release-/Vorabversionshinweise aus dem
vollständigen passenden Abschnitt von `CHANGELOG.md` und die Schritte zur 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 breiteren Importzyklus- und Architekturgrenzenprü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 Release-Artefakte unter `dist/*` und das Control-UI-Bundle für den Pack-Validierungsschritt vorhanden sind
- Führen Sie `pnpm plugins:sync` nach dem Versionssprung 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-mutierende Release-Guard; der Veröffentlichungsworkflow 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, Tag oder vollständigen Commit-SHA, dispatcht manuelles `CI` und dispatcht `OpenClaw Release Checks` für Install-Smoke, Package Acceptance, Docker-Release-Path-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 dem SHA gebaute Artefakt ausführen soll. Geben Sie `evidence_package_spec` an, wenn der private Evidence-Bericht nachweisen soll, dass die Validierung zu einem veröffentlichten npm-Paket passt, 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 Gates `pnpm check` 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 Release-Artefakte `dist/*` und das Control-UI-Bundle für den Paketvalidierungsschritt vorhanden sind
- Führen Sie `pnpm plugins:sync` nach dem Versions-Bump im Root und vor dem Tagging aus. Es aktualisiert die Versionen veröffentlichbarer Plugin-Pakete, OpenClaw-Peer-/API-Kompatibilitätsmetadaten, Build-Metadaten und Plugin-Changelog-Stubs passend zur Core-Release-Version. `pnpm plugins:sync:check` ist der nicht mutierende Release-Guard; 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 über einen Einstiegspunkt zu starten. Er akzeptiert einen Branch, ein Tag oder eine vollständige Commit-SHA, startet manuell `CI` und startet `OpenClaw Release Checks` für Install-Smoke, Package Acceptance, Docker-Release-Pfad-Suiten, 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-Prüfungen aus. Geben Sie `npm_telegram_package_spec` nach der Veröffentlichung an, wenn dasselbe 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 Evidenzbericht nachweisen soll, dass die Validierung einem veröffentlichten npm-Paket entspricht, 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 Side-Channel-Nachweise für einen Paketkandidaten benötigen, während die Release-Arbeit weiterläuft. Verwenden Sie `source=npm` für `openclaw@alpha`, `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 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.
- Führen Sie den manuellen Workflow `Package Acceptance` aus, wenn Sie einen Nebenkanal-Nachweis für einen Paketkandidaten möchten, 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.
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`
Häufige Profile:
- `smoke`: Installations-, Channel/Agent-, Gateway-Netzwerk- und Config-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-Path-Chunks mit OpenWebUI
- `custom`: exakte `docker_lanes`-Auswahl für eine fokussierte Wiederholung
- Führen Sie den manuellen Workflow `CI` direkt aus, wenn Sie nur die vollständige normale CI-Abdeckung für den Release-Kandidaten benötigen. Manuelle CI-Dispatches umgehen Changed-Scoping und erzwingen die Linux-Node-Shards, Bundled-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.
- `smoke`: Install-/Channel-/Agent-, Gateway-Netzwerk- und Config-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
- `custom`: exakte Auswahl von `docker_lanes` für einen fokussierten erneuten Lauf
- Führen Sie den manuellen Workflow `CI` direkt aus, wenn Sie nur die vollständige normale CI-Abdeckung für den Release-Kandidaten benötigen. Manuelle CI-Starts umgehen das Changed-Scoping und erzwingen die Linux-Node-Shards, Bundled-Plugin-Shards, Channel-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-Empfänger aus und verifiziert die exportierten Trace-Span-Namen, begrenzten Attribute und die Redaktion von Inhalten/Bezeichnern, ohne Opik, Langfuse oder einen anderen externen Collector zu benötigen.
- 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 prüft die exportierten Trace-Span-Namen, begrenzte Attribute sowie Inhalts-/Kennungsredaktion, 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 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 Standard-Plugin-Veröffentlichungsumfang `all-publishable` bei, sofern Sie nicht bewusst eine fokussierte Reparatur ausführen. Der Workflow serialisiert die Veröffentlichung von Plugin-npm, Plugin-ClawHub und OpenClaw-npm, damit das Core-Paket nicht vor seinen externalisierten Plugins veröffentlicht wird.
- Release-Checks laufen jetzt in einem separaten manuellen Workflow:
- Führen Sie `OpenClaw Release Publish` für die mutierende Publish-Sequenz aus, nachdem das Tag existiert. Starten Sie es von `release/YYYY.M.D` aus (oder von `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 den Plugin-npm-Publish, den Plugin-ClawHub-Publish und den OpenClaw-npm-Publish, 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 vor der Release-Freigabe außerdem die QA-Lab-Mock-Paritäts-Lane plus 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 Workflow `QA-Lab - All Lanes` mit `matrix_profile=all` und `matrix_shards=true` aus, wenn Sie den vollständigen Matrix-Transport, Medien und E2EE-Inventar parallel benötigen.
- 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 artefaktfokussiert, während langsamere Live-Checks in ihrer eigenen Lane bleiben, damit sie die Veröffentlichung nicht verzögern oder blockieren
- Release-Checks mit Secrets 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 einen vollständigen Commit-SHA, solange der aufgelöste Commit von einem OpenClaw-Branch oder Release-Tag erreichbar ist
- Der validierungsreine Preflight `OpenClaw NPM Release` akzeptiert auch den aktuellen vollständigen 40-Zeichen-Commit-SHA des Workflow-Branches, ohne ein gepushtes Tag zu verlangen
- Dieser SHA-Pfad ist nur für die Validierung und kann nicht in eine echte Veröffentlichung befördert werden
- Im SHA-Modus synthetisiert der Workflow `v<package.json version>` nur für die Paketmetadatenprüfung; echte Veröffentlichung erfordert weiterhin ein echtes Release-Tag
- Beide Workflows halten 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` mit den beiden Workflow-Secrets `OPENAI_API_KEY` und `ANTHROPIC_API_KEY` aus
- `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 außerdem 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 den vollständigen Matrix-Transport-, Medien- und E2EE-Bestand parallel prüfen möchten.
- Plattformübergreifende Installations- und Upgrade-Laufzeitvalidierung ist Teil der öffentlichen `OpenClaw Release Checks` und von `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-Prüfungen in ihrer eigenen Lane bleiben, damit sie den Publish nicht aufhalten oder blockieren
- Release-Prüfungen mit Secrets sollten über `Full Release Validation` oder vom Workflow-Ref `main`/Release aus gestartet 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 rein validierende Preflight von `OpenClaw NPM Release` akzeptiert außerdem die aktuelle vollständige 40-stellige Workflow-Branch-Commit-SHA, ohne ein gepushtes Tag zu verlangen
- Dieser SHA-Pfad dient nur der Validierung und kann nicht zu einem echten Publish befördert werden
- Im SHA-Modus synthetisiert der Workflow `v<package.json version>` nur für die Paketmetadatenprüfung; 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 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`
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 der npm-Veröffentlichung `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` (oder die passende Beta/Korrektur-Version) 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 echte Telegram-E2E gegen das veröffentlichte npm-Paket mit dem gemeinsam geleasten Telegram-Credential-Pool zu verifizieren. Lokale Maintainer-Einmalprüfungen können die Convex-Variablen weglassen und die drei `OPENCLAW_QA_TELEGRAM_*`-Env-Credentials direkt übergeben.
- Maintainer können dieselbe Post-Publish-Prüfung über den manuellen Workflow `NPM Telegram Beta E2E` in GitHub Actions ausführen. Er ist absichtlich nur manuell und läuft nicht bei jedem Merge.
- 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 prüfen
- 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 genutzten geleasten Telegram-Credential-Pool zu prüfen. Lokale einmalige Maintainer-Läufe können die Convex-Variablen weglassen und die drei `OPENCLAW_QA_TELEGRAM_*`-Env-Credentials direkt übergeben.
- Maintainer können dieselbe Post-Publish-Prüfung über den manuellen Workflow `NPM Telegram Beta E2E` aus GitHub Actions ausführen. Er ist bewusst ausschließlich 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` bestehen
- die echte npm-Veröffentlichung muss vom selben `main`- oder `release/YYYY.M.D`-Branch wie der erfolgreiche Preflight-Lauf dispatcht werden
- 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 gestartet werden wie der erfolgreiche Preflight-Lauf
- stabile npm-Releases verwenden standardmäßig `beta`
- stabile npm-Veröffentlichung kann über Workflow-Eingabe explizit `latest` ansteuern
- tokenbasierte npm-Dist-Tag-Mutation befindet sich aus Sicherheitsgründen jetzt 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 nur OIDC-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` bestehen
- 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 Upgrade-Pfad mit temporärem Präfix von `YYYY.M.D` zu `YYYY.M.D-N`, damit Release-Korrekturen ältere globale Installationen nicht still auf dem Basis-Stable-Payload belassen können
- 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-Einstiegspunkte und Paketmetadaten im installierten Registry-Layout vorhanden sind. Ein Release, das fehlende Plugin-Runtime-Payloads ausliefert, 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 versehentlichen Pack-Bloat vor dem Release-Veröffentlichungspfad findet
- Wenn die Release-Arbeit CI-Planung, Timing-Manifeste von Erweiterungen oder Testmatrizen von Erweiterungen berührt hat, generieren und prüfen Sie die planer-eigenen `plugin-prerelease-extension-shard`-Matrixausgaben aus `.github/workflows/plugin-prerelease.yml` vor der Freigabe neu, damit Release Notes kein veraltetes CI-Layout beschreiben
- Zur Bereitschaft eines stabilen macOS-Release gehören außerdem die Updater-Oberflächen:
- stabiler npm-Publish kann über Workflow-Eingabe explizit auf `latest` zielen
- tokenbasierte npm-Dist-Tag-Mutation liegt aus Sicherheitsgründen jetzt in `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`, da `npm dist-tag add` weiterhin `NPM_TOKEN` benötigt, während das öffentliche Repo OIDC-only-Publish beibehält
- öffentliches `macOS Release` ist nur validierend; wenn ein Tag nur auf einem Release-Branch liegt, der Workflow aber von `main` gestartet 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 zurücklassen können
- Der npm-Release-Preflight schlägt geschlossen fehl, sofern der Tarball nicht sowohl `dist/control-ui/index.html` als auch einen nicht leeren Payload `dist/control-ui/assets/` enthält, damit wir nicht erneut ein leeres Browser-Dashboard ausliefern
- Die Post-Publish-Verifizierung prüft außerdem, dass veröffentlichte Plugin-Entry-Points und Paketmetadaten im installierten Registry-Layout vorhanden sind. Ein Release, das fehlende Plugin-Laufzeit-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 versehentlichen Pack-Bloat vor dem Release-Publish-Pfad erkennt
- Wenn die Release-Arbeit CI-Planung, Extension-Timing-Manifeste oder Extension-Testmatrizen berührt hat, regenerieren und prüfen Sie vor der Freigabe die Planner-eigenen `plugin-prerelease-extension-shard`-Matrixausgaben 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-Flächen:
- das GitHub-Release muss am Ende die gepackten `.zip`, `.dmg` und `.dSYM.zip` enthalten
- `appcast.xml` auf `main` muss nach der Veröffentlichung auf das neue stabile Zip zeigen
- 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
- `appcast.xml` auf `main` muss nach dem Publish auf das 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-Minimum für diese Release-Version behalten
## Release-Testboxen
`Full Release Validation` ist der Weg, wie Operators alle Pre-Release-Tests von einem Einstiegspunkt aus starten. Für einen Pinned-Commit-Nachweis auf einem schnelllebigen Branch verwenden Sie den Helper, damit jeder Child-Workflow von einem temporären Branch läuft, der auf den Ziel-SHA fixiert ist:
`Full Release Validation` ist die Methode, mit der Operatoren alle Pre-Release-Tests über einen Einstiegspunkt starten. Für einen gepinnten Commit-Nachweis auf einem schnell bewegten Branch verwenden Sie den Helper, damit jeder Child-Workflow von einem temporären Branch läuft, der auf die Ziel-SHA fixiert ist:
```bash
pnpm ci:full-release --sha <full-sha>
```
Der Helper pusht `release-ci/<sha>-...`, dispatcht `Full Release Validation` von diesem Branch mit `ref=<sha>`, verifiziert, dass jeder Child-Workflow-`headSha` dem Ziel entspricht, und löscht dann den temporären Branch. So wird vermieden, versehentlich einen neueren `main`-Child-Lauf nachzuweisen.
Der Helper pusht `release-ci/<sha>-...`, startet `Full Release Validation` von diesem Branch mit `ref=<sha>`, prüft, dass jede Child-Workflow-`headSha` dem Ziel entspricht, und löscht anschließend den temporären Branch. Dadurch wird vermieden, versehentlich einen neueren `main`-Child-Lauf nachzuweisen.
Für die Validierung von Release-Branch oder Tag 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 vom vertrauenswürdigen Workflow-Ref `main` aus und übergeben den Release-Branch oder das Tag als `ref`:
```bash
gh workflow run full-release-validation.yml \
@ -184,41 +185,49 @@ gh workflow run full-release-validation.yml \
-f evidence_package_spec=openclaw@YYYY.M.D-beta.N
```
Der Workflow löst die Ziel-Ref auf, startet manuell `CI` mit
`target_ref=<release-ref>`, startet `OpenClaw Release Checks` und startet
eigenständige Package-Telegram-E2E, wenn `release_profile=full` mit
`rerun_group=all` verwendet wird oder wenn `npm_telegram_package_spec` gesetzt
ist. `OpenClaw Release Checks` verzweigt dann in Install-Smoke, Cross-OS-Release-Checks, Live-/E2E-Docker-Abdeckung für den Release-Pfad, Package Acceptance mit Telegram-Package-QA, QA-Lab-Parität, Live-Matrix und Live-Telegram. 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 das untergeordnete `npm_telegram` erfolgreich sein; außerhalb von
full/all wird es übersprungen, sofern kein veröffentlichtes
`npm_telegram_package_spec` angegeben wurde. Die abschließende
Verifiziererzusammenfassung enthält Tabellen der langsamsten Jobs für jeden untergeordneten Lauf, sodass die Release-Verantwortlichen den aktuellen kritischen Pfad sehen können, ohne Logs herunterladen zu müssen.
Siehe [vollständige Release-Validierung](/de/reference/full-release-validation) für die
vollständige Phasenmatrix, die exakten Workflow-Jobnamen, Unterschiede zwischen stabilem und vollständigem Profil, Artefakte und gezielte Rerun-Handles.
Untergeordnete Workflows werden von der vertrauenswürdigen Ref gestartet, die
`Full Release Validation` ausführt, normalerweise `--ref main`, selbst wenn die Ziel-`ref` auf einen
älteren Release-Branch oder Tag zeigt. Es gibt keine separate Workflow-Ref-Eingabe für Full Release Validation; wählen Sie das vertrauenswürdige Harness, indem Sie die Ref des Workflow-Laufs wählen.
Verwenden Sie `--ref main -f ref=<sha>` nicht für exakten Commit-Nachweis auf beweglichem `main`;
rohe Commit-SHAs können keine Workflow-Dispatch-Refs sein. Verwenden Sie daher
`pnpm ci:full-release --sha <sha>`, um den angehefteten temporären Branch zu erstellen.
Der Workflow löst den Ziel-Ref auf, dispatcht manuell `CI` mit
`target_ref=<release-ref>`, dispatcht `OpenClaw Release Checks` und dispatcht
eigenständige Telegram-Paket-E2E, wenn `release_profile=full` mit
`rerun_group=all` gesetzt ist oder wenn `npm_telegram_package_spec` gesetzt ist.
`OpenClaw Release Checks` verzweigt dann in Install-Smoke, Cross-OS-Release-Checks,
Live/E2E-Docker-Abdeckung des Release-Pfads, Package Acceptance mit Telegram-Paket-QA,
QA-Lab-Parität, Live-Matrix und Live-Telegram. 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 der
`npm_telegram`-Child erfolgreich sein; außerhalb von full/all wird er übersprungen,
sofern kein veröffentlichtes `npm_telegram_package_spec` bereitgestellt wurde.
Die abschließende Verifier-Zusammenfassung enthält Tabellen der langsamsten Jobs
für jeden Child-Lauf, sodass der Release-Manager den aktuellen kritischen Pfad
sehen kann, ohne Logs herunterzuladen.
Siehe [Vollständige Release-Validierung](/de/reference/full-release-validation) für
die vollständige Stage-Matrix, exakte Workflow-Jobnamen, Unterschiede zwischen
stable- und full-Profilen, Artefakte und gezielte Rerun-Handles.
Child-Workflows werden von dem vertrauenswürdigen Ref dispatched, der
`Full Release Validation` ausführt, normalerweise `--ref main`, selbst wenn der
Ziel-`ref` auf einen älteren Release-Branch oder Tag zeigt. Es gibt keine separate
Workflow-Ref-Eingabe für Full Release Validation; wählen Sie den vertrauenswürdigen
Harness, indem Sie den Ref des Workflow-Laufs wählen. Verwenden Sie nicht
`--ref main -f ref=<sha>` für exakte Commit-Nachweise auf einem sich bewegenden
`main`; rohe Commit-SHAs können keine Workflow-Dispatch-Refs sein. Verwenden Sie
daher `pnpm ci:full-release --sha <sha>`, um den gepinnten temporären Branch zu
erstellen.
Verwenden Sie `release_profile`, um die Breite von Live/Provider auszuwählen:
- `minimum`: schnellster release-kritischer OpenAI-/Core-Live- und Docker-Pfad
- `stable`: Minimum plus stabile Provider-/Backend-Abdeckung für Release-Freigabe
- `full`: Stable plus breite Abdeckung für beratende Provider/Medien
- `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 verwendet dieses Artefakt sowohl in
Docker-Checks für den Release-Pfad als auch in Package Acceptance wieder. Dadurch bleiben alle
package-seitigen 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
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.
`OpenClaw Release Checks` verwendet den vertrauenswürdigen Workflow-Ref, um den
Ziel-Ref einmal als `release-package-under-test` aufzulösen, und verwendet dieses
Artefakt sowohl in Docker-Checks des Release-Pfads als auch in Package Acceptance
wieder. Dadurch bleiben alle packagebezogenen Boxen auf denselben Bytes, und
wiederholte Paket-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, 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:
@ -250,36 +259,46 @@ 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, Docker-Lane, Package-Profil, Modell-Provider oder QA-Lane. Führen Sie den vollständigen Umbrella nur erneut aus, wenn
der Fix die gemeinsame Release-Orchestrierung geändert oder frühere All-Box-Evidence
veraltet gemacht hat. Der abschließende Verifizierer des Umbrella prüft die aufgezeichneten IDs untergeordneter Workflow-Läufe erneut. Nachdem ein untergeordneter Workflow erfolgreich erneut ausgeführt wurde, führen Sie daher nur den fehlgeschlagenen übergeordneten Job
`Verify full validation` erneut aus.
Verwenden Sie den vollständigen Umbrella-Lauf nicht als ersten Rerun nach einem
gezielten Fix. Wenn eine Box fehlschlägt, verwenden Sie für den nächsten Nachweis
den fehlgeschlagenen Child-Workflow, Job, die Docker-Lane, das Paketprofil, den
Modell-Provider oder die QA-Lane. Führen Sie den vollständigen Umbrella-Lauf nur
dann erneut aus, wenn der Fix die gemeinsame Release-Orchestrierung geändert hat
oder frühere All-Box-Nachweise veraltet gemacht hat. Der abschließende Verifier
des Umbrella-Laufs prüft die aufgezeichneten Child-Workflow-Run-IDs erneut.
Nachdem ein Child-Workflow erfolgreich erneut ausgeführt wurde, führen Sie daher
nur den fehlgeschlagenen Parent-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 das normale CI-Child aus, `plugin-prerelease`
führt nur das release-only Plugin-Child 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 Package-Artefakt aus release-checks.
Für begrenzte Wiederherstellung übergeben Sie `rerun_group` an den Umbrella-Lauf.
`all` ist der echte Release-Candidate-Lauf, `ci` führt nur den normalen CI-Child
aus, `plugin-prerelease` führt nur den releasebezogenen Plugin-Child 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 den Release-Checks.
### Vitest
Die Vitest-Box ist der manuelle untergeordnete `CI`-Workflow. Manuelles CI umgeht absichtlich
Changed-Scoping und erzwingt den normalen Testgraphen für den Release
Candidate: Linux-Node-Shards, gebündelte Plugin-Shards, Channel-Contracts, Node-22-Kompatibilität, `check`, `check-additional`, Build-Smoke, Docs-Checks, Python-Skills, Windows, macOS, Android und Control-UI-i18n.
Die Vitest-Box ist der manuelle `CI`-Child-Workflow. Manuelle CI umgeht bewusst
Changed-Scoping und erzwingt den normalen Testgraphen für den Release-Kandidaten:
Linux-Node-Shards, gebündelte Plugin-Shards, Kanalverträge, 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 Source Tree die vollständige normale Testsuite bestanden?“
Sie ist nicht dasselbe wie Produktvalidierung für den Release-Pfad. Aufzubewahrende Evidence:
Verwenden Sie diese Box, um zu beantworten: „Hat der Quellbaum die vollständige
normale Testsuite bestanden?“ Sie ist nicht dasselbe wie Produktvalidierung über
den Release-Pfad. Aufzubewahrende Nachweise:
- Zusammenfassung von `Full Release Validation`, die die URL des gestarteten `CI`-Laufs zeigt
- grüner `CI`-Lauf auf dem exakten Ziel-SHA
- Zusammenfassung von `Full Release Validation` mit der URL des dispatched `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
- Vitest-Timing-Artefakte wie `.artifacts/vitest-shard-timings.json`, wenn
ein Lauf Performance-Analyse benötigt
- Vitest-Timing-Artefakte wie `.artifacts/vitest-shard-timings.json`, wenn ein
Lauf eine Performance-Analyse benötigt
Führen Sie manuelles CI nur direkt aus, wenn der Release deterministisches normales CI benötigt, aber
nicht die Docker-, QA-Lab-, Live-, Cross-OS- oder Package-Boxen:
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:
```bash
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
@ -288,17 +307,18 @@ 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` plus dem Release-Modus-Workflow
`install-smoke`. Sie validiert den Release Candidate durch paketierte
Docker-Umgebungen statt nur durch Source-Level-Tests.
`openclaw-live-and-e2e-checks-reusable.yml` sowie im Release-Modus-Workflow
`install-smoke`. Sie validiert den Release-Kandidaten über paketierte
Docker-Umgebungen statt nur über Tests auf Quellcodeebene.
Die Docker-Abdeckung für Releases umfasst:
Die Release-Docker-Abdeckung umfasst:
- vollständigen Install-Smoke mit aktiviertem langsamem globalem 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
- vollständigen 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 für den Release-Pfad: `core`, `package-update-openai`,
- Docker-Chunks des Release-Pfads: `core`, `package-update-openai`,
`package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`,
`plugins-runtime-services`,
`plugins-runtime-install-a`, `plugins-runtime-install-b`,
@ -309,90 +329,95 @@ Die Docker-Abdeckung für Releases umfasst:
- aufgeteilte Install-/Uninstall-Lanes für gebündelte Plugins
`bundled-plugin-install-uninstall-0` bis
`bundled-plugin-install-uninstall-23`
- Live-/E2E-Provider-Suiten und Docker-Live-Modellabdeckung, wenn Release-Checks
Live-Suiten enthalten
- Live/E2E-Provider-Suites und Docker-Live-Modellabdeckung, wenn Release-Checks
Live-Suites einschließen
Verwenden Sie Docker-Artefakte vor einem Rerun. Der Release-Pfad-Scheduler 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=<lane[,lane]>` im wiederverwendbaren Live-/E2E-Workflow, statt
alle Release-Chunks erneut auszuführen. Generierte Rerun-Befehle enthalten vorherige
`package_artifact_run_id` und vorbereitete Docker-Image-Eingaben, wenn verfügbar, sodass eine
fehlgeschlagene Lane denselben Tarball und dieselben GHCR-Images wiederverwenden kann.
Verwenden Sie Docker-Artefakte vor einem Rerun. Der Scheduler des Release-Pfads
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=<lane[,lane]>` 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.
### 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-
Package-Mechanik.
Die QA-Lab-Box ist ebenfalls Teil von `OpenClaw Release Checks`. Sie ist das
Release-Gate für agentisches Verhalten und Kanalebene, getrennt von Vitest und
Docker-Paketmechanik.
Die QA-Lab-Abdeckung für Releases umfasst:
Die Release-QA-Lab-Abdeckung umfasst:
- Mock-Paritäts-Lane, die die OpenAI-Candidate-Lane mit der Opus-4.6-
Baseline unter Verwendung des agentischen Paritätspakets vergleicht
- Mock-Parity-Lane, die die OpenAI-Kandidaten-Lane mit der Opus-4.6-Baseline
mithilfe des agentischen Parity-Packs 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 der 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 den Release freigeben. Vollständige Matrix-Abdeckung bleibt als
manueller, geshardeter QA-Lab-Lauf verfügbar, nicht als standardmäßige release-kritische Lane.
Verwenden Sie diese Box, um zu beantworten: „Verhält sich das Release in
QA-Szenarien und Live-Kanalflüssen korrekt?“ Bewahren Sie die Artefakt-URLs für
Parity-, Matrix- und Telegram-Lanes auf, wenn Sie das Release freigeben.
Vollständige Matrix-Abdeckung bleibt als manueller geshardeter QA-Lab-Lauf
verfügbar und ist nicht die standardmäßige releasekritische Lane.
### Package
### Paket
Die Package-Box ist das Gate für das installierbare Produkt. Sie wird von
`Package Acceptance` und dem Resolver
`scripts/resolve-openclaw-package-candidate.mjs` gestützt. Der Resolver normalisiert einen
Candidate in den `package-under-test`-Tarball, der von Docker E2E konsumiert wird, validiert
das Package-Inventar, zeichnet die Package-Version und SHA-256 auf und hält die
Workflow-Harness-Ref getrennt von der Package-Source-Ref.
Die Paket-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 Paketversion und SHA-256 auf und hält den
Workflow-Harness-Ref vom Paketquell-Ref getrennt.
Unterstützte Candidate-Quellen:
Unterstützte Kandidatenquellen:
- `source=npm`: `openclaw@beta`, `openclaw@latest` oder eine exakte OpenClaw-Release-
Version
- `source=ref`: einen vertrauenswürdigen `package_ref`-Branch, Tag oder vollständigen Commit-SHA
mit dem ausgewählten `workflow_ref`-Harness packen
- `source=url`: eine HTTPS-`.tgz` mit erforderlichem `package_sha256` herunterladen
- `source=artifact`: eine von einem anderen GitHub-Actions-Lauf hochgeladene `.tgz` wiederverwenden
- `source=npm`: `openclaw@beta`, `openclaw@latest` oder eine exakte OpenClaw-Release-Version
- `source=ref`: einen vertrauenswürdigen `package_ref`-Branch, Tag oder vollständige
Commit-SHA mit dem ausgewählten `workflow_ref`-Harness packen
- `source=url`: ein HTTPS-`.tgz` mit erforderlichem `package_sha256` herunterladen
- `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-Package-Artefakt, `suite_profile=custom`,
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` aus. Package Acceptance hält Migration, Update, Bereinigung veralteter
Plugin-Abhängigkeiten, Offline-Plugin-Fixtures, Plugin-Update und Telegram-
Package-QA gegen denselben aufgelösten Tarball. Die Upgrade-Matrix deckt jede stabil 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 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.
`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 `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 größten Teil der Paket-/Update-Abdeckung, die zuvor
Parallels erforderte. Cross-OS-Release-Checks bleiben für OS-spezifisches
Onboarding, Installer- und Plattformverhalten wichtig, aber Paket-/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/ein Plugin-Update, Doctor-Cleanup oder eine veröffentlichte Package-Migrationsänderung nachweist.
Erschöpfende veröffentlichte Update-Migration aus jedem stabilen Package `2026.4.23+` ist
ein separater manueller Workflow `Update Migration` und nicht Teil von Full Release CI.
[Updates und Plugins testen](/de/help/testing-updates-plugins). Verwenden Sie sie,
wenn Sie entscheiden, welche lokale Lane, Docker-Lane, Package-Acceptance-Lane
oder Release-Check-Lane eine Plugin-Installation/ein Plugin-Update,
Doctor-Cleanup oder eine Änderung der Migration veröffentlichter Pakete nachweist.
Erschöpfende veröffentlichte Update-Migration aus jedem stabilen Paket
`2026.4.23+` ist ein separater manueller Workflow `Update Migration` und nicht
Teil von Full Release CI.
Legacy-Nachsicht bei Package Acceptance ist absichtlich zeitlich begrenzt. Packages bis
`2026.4.25` dürfen den Kompatibilitätspfad für bereits auf npm veröffentlichte Metadatenlücken
verwenden: private QA-Inventareinträge, die im Tarball fehlen, fehlendes
`gateway install --wrapper`, fehlende Patch-Dateien im aus dem Tarball abgeleiteten Git-
Fixture, fehlendes persistiertes `update.channel`, Legacy-Plugin-Install-Record-
Speicherorte, fehlende Persistenz von Marketplace-Install-Records und Config-Metadaten-
Migration während `plugins update`. Das veröffentlichte Package `2026.4.26` darf
für bereits ausgelieferte lokale Build-Metadaten-Stamp-Dateien warnen. Spätere Packages
müssen die modernen Package-Verträge erfüllen; dieselben Lücken lassen die Release-
Validierung fehlschlagen.
Legacy-Nachsicht bei package-acceptance ist bewusst zeitlich begrenzt. Pakete
bis einschließlich `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
in der aus dem Tarball abgeleiteten Git-Fixture, fehlendes persistiertes
`update.channel`, Legacy-Speicherorte für Plugin-Install-Records, fehlende
Persistenz von Marketplace-Install-Records und Config-Metadatenmigration während
`plugins update`. Das veröffentlichte Paket `2026.4.26` darf für bereits
ausgelieferte lokale Build-Metadaten-Stamp-Dateien warnen. Spätere Pakete müssen
die modernen Paketverträge erfüllen; dieselben Lücken lassen die Release-Validierung
fehlschlagen.
Verwenden Sie breitere Package-Acceptance-Profile, wenn sich die Release-Frage auf ein
tatsächliches installierbares Package bezieht:
Verwenden Sie breitere Package-Acceptance-Profile, wenn sich die Release-Frage
auf ein tatsächlich installierbares Paket bezieht:
```bash
gh workflow run package-acceptance.yml \
@ -404,20 +429,18 @@ gh workflow run package-acceptance.yml \
-f published_upgrade_survivor_baseline=openclaw@2026.4.26
```
Gängige Package-Profile:
Gängige Paketprofile:
- `smoke`: schnelle Package-Install-/Channel-/Agent-, Gateway-Netzwerk- und Config-
Reload-Lanes
- `package`: Install-/Update-/Plugin-Package-Verträge ohne Live-ClawHub; dies ist der Release-Check-
Standard
- `product`: `package` plus MCP-Channels, Cron-/Subagent-Cleanup, OpenAI-Web-
Suche und OpenWebUI
- `full`: Docker-Release-Pfad-Chunks mit OpenWebUI
- `smoke`: schnelle Lanes für Paketinstallation/Kanal/Agent, Gateway-Netzwerk und Config-Neuladen
- `package`: Install-/Update-/Plugin-Paketverträge ohne Live-ClawHub; dies ist der
Standard für Release-Checks
- `product`: `package` plus MCP-Kanäle, Cron-/Subagent-Cleanup, OpenAI-Websuche und OpenWebUI
- `full`: Docker-Chunks des Release-Pfads mit OpenWebUI
- `custom`: exakte `docker_lanes`-Liste für gezielte Reruns
Für den Telegram-Nachweis für Package Candidates aktivieren Sie `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
Für den Telegram-Nachweis eines Package-Kandidaten aktivieren Sie `telegram_mode=mock-openai` oder
`telegram_mode=live-frontier` in Package Acceptance. Der Workflow übergibt das
aufgelöste `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.
## Automatisierung der Release-Veröffentlichung
@ -426,15 +449,15 @@ Telegram-Workflow akzeptiert weiterhin eine veröffentlichte npm-Spezifikation f
orchestriert die Trusted-Publisher-Workflows in der Reihenfolge, die das Release benötigt:
1. Release-Tag auschecken und dessen Commit-SHA auflösen.
2. Prüfen, ob das Tag von `main` oder `release/*` erreichbar ist.
2. Prüfen, dass 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=<release-sha>` auslösen.
5. `Plugin ClawHub Release` mit demselben Scope und derselben SHA auslösen.
6. `OpenClaw NPM Release` mit dem Release-Tag, dem npm-Dist-Tag und der
6. `OpenClaw NPM Release` mit dem Release-Tag, npm-Dist-Tag und der
gespeicherten `preflight_run_id` auslösen.
Beispiel für eine Beta-Veröffentlichung:
Beispiel für Beta-Veröffentlichung:
```bash
gh workflow run openclaw-release-publish.yml \
@ -444,17 +467,7 @@ gh workflow run openclaw-release-publish.yml \
-f npm_dist_tag=beta
```
Beispiel für eine Alpha-Veröffentlichung:
```bash
gh workflow run openclaw-release-publish.yml \
--ref release/YYYY.M.D \
-f tag=vYYYY.M.D-alpha.N \
-f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
-f npm_dist_tag=alpha
```
Stabile Veröffentlichung mit dem Standard-Beta-Dist-Tag:
Stabile Veröffentlichung zum standardmäßigen Beta-Dist-Tag:
```bash
gh workflow run openclaw-release-publish.yml \
@ -464,7 +477,7 @@ gh workflow run openclaw-release-publish.yml \
-f npm_dist_tag=beta
```
Die stabile Promotion direkt zu `latest` erfolgt ausdrücklich:
Stabile Promotion direkt zu `latest` ist explizit:
```bash
gh workflow run openclaw-release-publish.yml \
@ -475,91 +488,90 @@ gh workflow run openclaw-release-publish.yml \
```
Verwenden Sie die untergeordneten Workflows `Plugin NPM Release` und `Plugin ClawHub Release`
nur für gezielte Reparatur- oder erneute Veröffentlichungsarbeiten. Für die Reparatur eines ausgewählten Plugins übergeben Sie
nur für gezielte Reparatur- oder Neuverö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 Child-Workflow direkt aus, wenn das
OpenClaw-Paket nicht veröffentlicht werden darf.
## NPM-Workflow-Eingaben
`OpenClaw NPM Release` akzeptiert diese operatorgesteuerten Eingaben:
`OpenClaw NPM Release` akzeptiert diese vom Operator gesteuerten Eingaben:
- `tag`: erforderliches Release-Tag wie `v2026.4.2`, `v2026.4.2-1` oder
`v2026.4.2-alpha.1` oder `v2026.4.2-beta.1`; wenn `preflight_only=true` gilt, kann es auch die aktuelle
vollständige 40-Zeichen-Commit-SHA des Workflow-Branches für einen rein validierenden Preflight sein
- `tag`: erforderlicher Release-Tag wie `v2026.4.2`, `v2026.4.2-1` oder
`v2026.4.2-beta.1`; wenn `preflight_only=true`, kann er auch die aktuelle
vollständige 40-Zeichen-Commit-SHA des Workflow-Branches für einen reinen Validierungs-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
den vorbereiteten Tarball aus dem erfolgreichen Preflight-Lauf wiederverwendet
- `preflight_run_id`: im echten Veröffentlichungspfad erforderlich, damit der Workflow
das vorbereitete Tarball aus dem erfolgreichen Preflight-Lauf wiederverwendet
- `npm_dist_tag`: npm-Ziel-Tag für den Veröffentlichungspfad; Standardwert ist `beta`
`OpenClaw Release Publish` akzeptiert diese operatorgesteuerten Eingaben:
`OpenClaw Release Publish` akzeptiert diese vom Operator gesteuerten Eingaben:
- `tag`: erforderliches Release-Tag; muss bereits existieren
- `preflight_run_id`: erfolgreiche `OpenClaw NPM Release`-Preflight-Run-ID;
erforderlich, wenn `publish_openclaw_npm=true` gilt
- `tag`: erforderlicher Release-Tag; muss bereits existieren
- `preflight_run_id`: erfolgreiche Preflight-Lauf-ID von `OpenClaw NPM Release`;
erforderlich, wenn `publish_openclaw_npm=true`
- `npm_dist_tag`: npm-Ziel-Tag für das OpenClaw-Paket
- `plugin_publish_scope`: Standardwert ist `all-publishable`; verwenden Sie `selected` nur
für gezielte Reparaturarbeiten
- `plugins`: durch Kommas getrennte Paketnamen im Format `@openclaw/*`, wenn
`plugin_publish_scope=selected` gilt
- `publish_openclaw_npm`: Standardwert ist `true`; setzen Sie dies 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`: Standardwert ist `true`; setzen Sie dies nur dann auf `false`, wenn Sie den
Workflow als reinen Reparatur-Orchestrator für Plugins verwenden
`OpenClaw Release Checks` akzeptiert diese operatorgesteuerten Eingaben:
`OpenClaw Release Checks` akzeptiert diese vom Operator gesteuerten Eingaben:
- `ref`: Branch, Tag oder vollständige Commit-SHA, die validiert werden soll. Prüfungen mit Secrets
- `ref`: Branch, Tag oder vollständige Commit-SHA zur Validierung. 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 zu `beta` oder `latest` veröffentlichen
- Alpha-Prerelease-Tags dürfen nur zu `alpha` veröffentlichen
- Beta-Prerelease-Tags dürfen nur zu `beta` veröffentlichen
- Für `OpenClaw NPM Release` ist eine vollständige Commit-SHA-Eingabe nur erlaubt, wenn
`preflight_only=true` gilt
- `OpenClaw Release Checks` und `Full Release Validation` dienen immer
nur der Validierung
- Stabile Tags und Korrektur-Tags dürfen entweder zu `beta` oder `latest` veröffentlicht werden
- Beta-Prerelease-Tags dürfen nur zu `beta` veröffentlicht werden
- Für `OpenClaw NPM Release` ist die Eingabe einer vollständigen Commit-SHA nur erlaubt, wenn
`preflight_only=true`
- `OpenClaw Release Checks` und `Full Release Validation` sind immer
reine Validierung
- Der echte Veröffentlichungspfad muss dasselbe `npm_dist_tag` verwenden, das während des Preflights verwendet wurde;
der Workflow prüft diese Metadaten, bevor die Veröffentlichung fortgesetzt wird
der Workflow prüft diese Metadaten vor dem Fortsetzen der Veröffentlichung
## Stabile npm-Release-Sequenz
Beim Erstellen 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 Workflow-Branch-Commit-SHA
für einen rein validierenden Probelauf des Preflight-Workflows verwenden
2. Wählen Sie `npm_dist_tag=beta` für den normalen Beta-zuerst-Ablauf oder `latest` nur dann,
- Bevor ein Tag existiert, können Sie die aktuelle vollständige Commit-SHA des Workflow-Branches
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`,
wenn Sie bewusst eine direkte stabile Veröffentlichung wünschen
3. Führen Sie `Full Release Validation` auf dem Release-Branch, dem Release-Tag oder der vollständigen
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 heraus wünschen
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; dies veröffentlicht externalisierte Plugins auf npm
und ClawHub, bevor das OpenClaw-npm-Paket hochgestuft wird
und ClawHub, bevor das OpenClaw-npm-Paket promoted wird
7. Wenn das Release auf `beta` gelandet ist, verwenden Sie den privaten
Workflow `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`,
um diese stabile Version von `beta` zu `latest` hochzustufen
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`-
Workflow, um diese stabile Version von `beta` zu `latest` zu promoten
8. Wenn das Release bewusst direkt zu `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 zeigen zu lassen, oder lassen Sie die geplante
Workflow, um beide Dist-Tags auf die stabile Version zeigen zu lassen, oder lassen Sie dessen geplante
selbstheilende Synchronisierung `beta` später verschieben
Die Dist-Tag-Mutation liegt aus Sicherheitsgründen im privaten Repo, weil sie weiterhin
`NPM_TOKEN` benötigt, während das öffentliche Repo ausschließlich OIDC-Veröffentlichungen verwendet.
`NPM_TOKEN` erfordert, während das öffentliche Repo nur OIDC-Veröffentlichung verwendet.
Damit bleiben sowohl der direkte Veröffentlichungspfad als auch der Beta-zuerst-Promotion-Pfad
Dadurch bleiben sowohl der direkte Veröffentlichungspfad als auch der Beta-zuerst-Promotion-Pfad
dokumentiert und für Operatoren sichtbar.
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; innerhalb von tmux bleiben Prompts,
Warnungen und OTP-Handling beobachtbar und wiederholte Host-Warnungen werden verhindert.
Wenn ein Maintainer auf lokale npm-Authentifizierung zurückgreifen muss, führen Sie alle 1Password
CLI-(`op`)-Befehle 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-Verarbeitung beobachtbar, und wiederholte Host-Warnungen werden verhindert.
## Öffentliche Referenzen

286
docs/de/web/control-ui.md
View File

@ -3,23 +3,23 @@ read_when:
- Sie möchten das Gateway über einen Browser bedienen
- Sie möchten Tailnet-Zugriff ohne SSH-Tunnel
sidebarTitle: Control UI
summary: Browserbasierte Steuerungsoberfläche für das Gateway (Chat, Knoten, Konfiguration)
title: Steuerungsoberfläche
summary: Browserbasierte Steuerungs-UI für das Gateway (Chat, Nodes, Konfiguration)
title: Steuerungs-UI
x-i18n:
generated_at: "2026-05-02T21:05:24Z"
generated_at: "2026-05-02T23:39:16Z"
model: gpt-5.5
provider: openai
source_hash: 88959ccf435b31015039bf28c3043023d99f0b953a1489986ab2d0cbd261771c
source_hash: 50bef807915f27406e19f1c6ca7d839a610d79ba79da85d7a78523400cbf9208
source_path: web/control-ui.md
workflow: 16
---
Die Control UI ist eine kleine **Vite + Lit**-Single-Page-App, die vom Gateway bereitgestellt wird:
Die Steuerungsoberfläche ist eine kleine **Vite + Lit** Single-Page-App, die vom Gateway bereitgestellt wird:
- Standard: `http://<host>:18789/`
- optionales Präfix: `gateway.controlUi.basePath` festlegen (z. B. `/openclaw`)
Sie kommuniziert **direkt mit dem Gateway WebSocket** auf demselben Port.
Sie kommuniziert **direkt mit dem Gateway-WebSocket** auf demselben Port.
## Schnell öffnen (lokal)
@ -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ätsheader, wenn `gateway.auth.allowTailscale: true`
- Tailscale-Serve-Identitätsheader, wenn `gateway.auth.allowTailscale: true`
- Trusted-Proxy-Identitätsheader, wenn `gateway.auth.mode: "trusted-proxy"`
Das Einstellungsfenster 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 beim ersten Verbindungsaufbau normalerweise ein Gateway-Token für Shared-Secret-Authentifizierung, aber Passwortauthentifizierung funktioniert ebenfalls, wenn `gateway.auth.mode` `"password"` ist.
Das Einstellungsfenster 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 beim ersten Verbinden normalerweise ein Gateway-Token für Shared-Secret-Authentifizierung, aber Passwortauthentifizierung funktioniert ebenfalls, wenn `gateway.auth.mode` `"password"` ist.
## Gerätekopplung (erste Verbindung)
Wenn Sie von einem neuen Browser oder Gerät aus eine Verbindung zur Control UI herstellen, verlangt das Gateway normalerweise eine **einmalige Kopplungsgenehmigung**. Dies ist eine Sicherheitsmaßnahme, um unbefugten Zugriff zu verhindern.
Wenn Sie die Steuerungsoberfläche von einem neuen Browser oder Gerät aus verbinden, verlangt das Gateway normalerweise eine **einmalige Kopplungsbestätigung**. Dies ist eine Sicherheitsmaßnahme, um unbefugten Zugriff zu verhindern.
**Was Sie sehen:** „disconnected (1008): pairing required“
**Was Sie sehen:** "getrennt (1008): Kopplung erforderlich"
<Steps>
<Step title="Ausstehende Anfragen auflisten">
@ -50,103 +50,104 @@ Wenn Sie von einem neuen Browser oder Gerät aus eine Verbindung zur Control UI
openclaw devices list
```
</Step>
<Step title="Per Anfrage-ID genehmigen">
<Step title="Nach Anfrage-ID genehmigen">
```bash
openclaw devices approve <requestId>
```
</Step>
</Steps>
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 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 bereits gekoppelt ist und Sie ihn von Lesezugriff auf Schreib-/Admin-Zugriff ändern, wird dies als Genehmigungsupgrade behandelt, nicht als stiller Neuaufbau der Verbindung. OpenClaw hält die alte Genehmigung aktiv, blockiert die Verbindung mit erweiterten Rechten und fordert Sie auf, das neue Scope-Set ausdrücklich zu genehmigen.
Wenn der Browser bereits gekoppelt ist und Sie ihn von Lesezugriff auf Schreib-/Adminzugriff umstellen, wird dies als Genehmigungsupgrade behandelt, nicht als stillschweigende erneute Verbindung. OpenClaw hält die alte Genehmigung aktiv, blockiert die umfassendere erneute Verbindung und fordert Sie auf, den neuen Umfangssatz explizit zu genehmigen.
Nach der Genehmigung wird das Gerät gemerkt und erfordert keine erneute Genehmigung, es sei denn, Sie widerrufen es mit `openclaw devices revoke --device <id> --role <role>`. Siehe [Devices CLI](/de/cli/devices) für Tokenrotation 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 <id> --role <role>`. Siehe [Geräte-CLI](/de/cli/devices) für Token-Rotation und Widerruf.
<Note>
- Direkte local loopback-Browserverbindungen (`127.0.0.1` / `localhost`) werden automatisch genehmigt.
- Tailscale Serve kann den Kopplungsdurchlauf 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 präsentiert.
- Direkte Tailnet-Bindings, LAN-Browserverbindungen und Browserprofile ohne Geräteidentität erfordern weiterhin eine ausdrückliche Genehmigung.
- Direkte Browserverbindungen über local loopback (`127.0.0.1` / `localhost`) werden automatisch genehmigt.
- Tailscale Serve kann den Kopplungsdurchlauf für Operator-Sitzungen der Steuerungsoberfläche überspringen, wenn `gateway.auth.allowTailscale: true` gesetzt ist, die Tailscale-Identität verifiziert wird und der Browser seine Geräteidentität vorlegt.
- Direkte Tailnet-Bindungen, LAN-Browserverbindungen und Browserprofile ohne Geräteidentität erfordern weiterhin eine explizite Genehmigung.
- Jedes Browserprofil erzeugt eine eindeutige Geräte-ID, daher erfordert ein Browserwechsel oder das Löschen von Browserdaten eine erneute Kopplung.
</Note>
## Persönliche Identität (browserlokal)
Die Control UI unterstützt eine browserbezogene persönliche Identität (Anzeigename und Avatar), die ausgehenden Nachrichten zur Zuordnung in geteilten Sitzungen angehängt wird. Sie befindet sich im Browserspeicher, ist auf das aktuelle Browserprofil beschränkt und wird weder mit anderen Geräten synchronisiert noch serverseitig dauerhaft gespeichert, abgesehen von den normalen Urheberschaftsmetadaten 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 Steuerungsoberfläche unterstützt eine persönliche Identität pro Browser (Anzeigename und Avatar), die ausgehenden Nachrichten zur Zuordnung in geteilten Sitzungen angehängt wird. Sie befindet sich im Browserspeicher, ist auf das aktuelle Browserprofil beschränkt und wird weder mit anderen Geräten synchronisiert noch serverseitig über die normalen Autor-Metadaten des Transkripts für Nachrichten hinaus gespeichert, 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 laufen nie über `config.patch` zurück. Das gemeinsame Konfigurationsfeld `ui.assistant.avatar` bleibt für Nicht-UI-Clients verfügbar, die das Feld direkt schreiben (etwa geskriptete 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 geteilte Konfigurationsfeld `ui.assistant.avatar` bleibt weiterhin für Nicht-UI-Clients verfügbar, die das Feld direkt schreiben (z. B. skriptgesteuerte Gateways oder benutzerdefinierte Dashboards).
## Endpunkt für Laufzeitkonfiguration
## Laufzeitkonfigurations-Endpunkt
Die Control UI ruft ihre Laufzeiteinstellungen von `/__openclaw/control-ui-config.json` ab. Dieser Endpunkt ist durch dieselbe Gateway-Authentifizierung geschützt wie der Rest der HTTP-Oberfläche: 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 Steuerungsoberfläche ruft ihre Laufzeiteinstellungen von `/__openclaw/control-ui-config.json` ab. Dieser Endpunkt wird durch dieselbe Gateway-Authentifizierung geschützt wie die restliche HTTP-Oberfläche: 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 Control UI kann sich beim ersten Laden anhand Ihrer Browserlocale lokalisieren. Um sie später zu überschreiben, öffnen Sie **Overview -> Gateway Access -> Language**. Die Locale-Auswahl befindet sich in der Gateway Access-Karte, nicht unter Appearance.
Die Steuerungsoberfläche 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 verzögert geladen.
- Nicht englische Übersetzungen werden im Browser bei Bedarf geladen.
- 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 dieselbe nicht englische Locale-Menge 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 Veröffentlichungs-Repo generiert; sie erscheint möglicherweise erst in dieser Auswahl, wenn Mintlify diese Codes unterstützt.
Dokumentationsübersetzungen werden für dieselbe nicht englische Locale-Menge 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-Repository erzeugt; sie erscheint möglicherweise erst in dieser Auswahl, wenn Mintlify diese Codes unterstützt.
## Darstellungsthemen
Das Appearance-Fenster behält die integrierten Themen Claw, Knot und Dash sowie einen browserlokalen tweakcn-Importslot. Um ein Thema zu importieren, öffnen Sie [tweakcn themes](https://tweakcn.com/themes), wählen oder erstellen Sie ein Thema, klicken Sie auf **Share** und fügen Sie den kopierten Themenlink in Appearance ein. Der Importer akzeptiert außerdem `https://tweakcn.com/r/themes/<id>`-Registry-URLs, Editor-URLs wie `https://tweakcn.com/editor/theme?theme=amethyst-haze`, relative `/themes/<id>`-Pfade, rohe Themen-IDs und Standardthemennamen wie `amethyst-haze`.
Das Darstellungsfenster behält die integrierten Designs Claw, Knot und Dash sowie einen browserlokalen tweakcn-Importplatz. Um ein Design zu importieren, öffnen Sie [tweakcn-Designs](https://tweakcn.com/themes), wählen oder erstellen Sie ein Design, klicken Sie auf **Teilen**, und fügen Sie den kopierten Designlink in Darstellung ein. Der Importer akzeptiert außerdem `https://tweakcn.com/r/themes/<id>`-Registry-URLs, Editor-URLs wie `https://tweakcn.com/editor/theme?theme=amethyst-haze`, relative `/themes/<id>`-Pfade, reine Design-IDs und Standard-Designnamen wie `amethyst-haze`.
Importierte Themen werden nur im aktuellen Browserprofil gespeichert. Sie werden nicht in die Gateway-Konfiguration geschrieben und nicht zwischen Geräten synchronisiert. Das Ersetzen des importierten Themas aktualisiert den einen lokalen Slot; das Löschen wechselt das aktive Thema zurück zu Claw, wenn das importierte Thema ausgewählt war.
Importierte Designs werden nur im aktuellen Browserprofil gespeichert. Sie werden nicht in die Gateway-Konfiguration geschrieben und nicht geräteübergreifend synchronisiert. Das Ersetzen des importierten Designs aktualisiert den einen lokalen Platz; das Löschen schaltet das aktive Design zurück auf Claw, wenn das importierte Design ausgewählt war.
## Was sie kann (heute)
<AccordionGroup>
<Accordion title="Chat und Talk">
- Chatten Sie mit dem Modell über Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
- Sprechen Sie über Browser-Echtzeitsitzungen. OpenAI nutzt direktes WebRTC, Google Live nutzt ein eingeschränktes, einmal verwendbares 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-Toolausgabekarten im Chat (Agent-Ereignisse).
<Accordion title="Chat und Sprechen">
- Mit dem Modell über Gateway WS chatten (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
- In den Chat-Composer mit serverseitiger STT diktieren (`chat.transcribeAudio`). Der Browser zeichnet einen kurzen Mikrofonclip auf und sendet ihn an das Gateway, das die konfigurierte `tools.media.audio`-Transkriptionspipeline ausführt und Entwurfstext zurückgibt, ohne Provider-Anmeldedaten im Browser offenzulegen.
- Über Browser-Echtzeitsitzungen sprechen. OpenAI verwendet direktes WebRTC, Google Live verwendet ein eingeschränktes einmalig nutzbares Browser-Token über WebSocket, und nur 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` an das größere konfigurierte OpenClaw-Modell zurücksendet.
- Toolaufrufe und Live-Toolausgabe-Karten im Chat streamen (Agent-Ereignisse).
</Accordion>
<Accordion title="Kanäle, Instanzen, Sitzungen, Dreams">
- Kanäle: Status integrierter sowie gebündelter/externer Plugin-Kanäle, QR-Login und kanalbezogene Konfiguration (`channels.status`, `web.login.*`, `config.patch`).
<Accordion title="Kanäle, Instanzen, Sitzungen, Träume">
- Kanäle: integrierter Status plus Status gebündelter/externer Plugin-Kanäle, QR-Anmeldung und Konfiguration pro Kanal (`channels.status`, `web.login.*`, `config.patch`).
- Instanzen: Anwesenheitsliste und Aktualisierung (`system-presence`).
- 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-Reader (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
- Sitzungen: Liste und sitzungsbezogene Überschreibungen für Modell/Denken/schnell/ausführlich/Trace/Reasoning (`sessions.list`, `sessions.patch`).
- Träume: Dreaming-Status, Umschalter zum Aktivieren/Deaktivieren und Dream-Diary-Leser (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
</Accordion>
<Accordion title="Cron, Skills, Nodes, Exec-Genehmigungen">
- Cron-Jobs: auflisten/hinzufügen/bearbeiten/ausführen/aktivieren/deaktivieren und Ausführungsverlauf (`cron.*`).
- Cron-Jobs: auflisten/hinzufügen/bearbeiten/ausführen/aktivieren/deaktivieren und Ausführungshistorie (`cron.*`).
- Skills: Status, aktivieren/deaktivieren, installieren, API-Schlüssel aktualisieren (`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.*`).
- Nodes: Liste und Fähigkeiten (`node.list`).
- Exec-Genehmigungen: Gateway- oder Node-Allowlists bearbeiten und Abfragerichtlinie für `exec host=gateway/node` (`exec.approvals.*`).
</Accordion>
<Accordion title="Konfiguration">
- `~/.openclaw/openclaw.json` anzeigen/bearbeiten (`config.get`, `config.set`).
- Anwenden und mit Validierung neu starten (`config.apply`) sowie die zuletzt aktive Sitzung wecken.
- Schreibvorgänge enthalten eine Base-Hash-Schutzprüfung, um das Überschreiben gleichzeitiger Bearbeitungen zu verhindern.
- Schreibvorgänge (`config.set`/`config.apply`/`config.patch`) prüfen vorab die Auflösung aktiver SecretRef für Refs im übermittelten Konfigurationspayload; 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, Zusammenfassungen unmittelbarer untergeordneter Elemente, Dokumentationsmetadaten auf verschachtelten Objekt-/Wildcard-/Array-/Kompositions-Nodes sowie Plugin- und Kanalschemas, wenn verfügbar); der Raw-JSON-Editor ist nur verfügbar, wenn der Snapshot einen sicheren Raw-Roundtrip hat.
- Wenn ein Snapshot Rohtext nicht sicher per Roundtrip erhalten kann, erzwingt die Control UI den Formularmodus und deaktiviert für diesen Snapshot den Raw-Modus.
- „Reset to saved“ im Raw-JSON-Editor bewahrt die roh verfasste Form (Formatierung, Kommentare, `$include`-Layout), statt einen abgeflachten Snapshot erneut zu rendern, sodass externe Bearbeitungen einen Reset überstehen, wenn der Snapshot sicher per Roundtrip erhalten werden kann.
- Strukturierte SecretRef-Objektwerte werden in Formular-Texteingaben schreibgeschützt gerendert, um versehentliche Objekt-zu-String-Beschädigung zu verhindern.
- Anwenden und Neustart mit Validierung (`config.apply`) sowie Aufwecken der zuletzt aktiven Sitzung.
- Schreibvorgänge enthalten einen Basis-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 Referenzen in der übermittelten Konfigurationsnutzlast; nicht aufgelöste 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, unmittelbarer Kindzusammenfassungen, Dokumentationsmetadaten auf verschachtelten Objekt-/Wildcard-/Array-/Kompositions-Nodes sowie Plugin- und Kanalschemata, wenn verfügbar); der Raw-JSON-Editor ist nur verfügbar, wenn der Snapshot eine sichere Raw-Roundtrip-Verarbeitung hat.
- Wenn ein Snapshot Rohtext nicht sicher im Roundtrip verarbeiten kann, erzwingt die Steuerungsoberfläche den Formularmodus und deaktiviert den Raw-Modus für diesen Snapshot.
- Der Raw-JSON-Editor „Auf gespeicherten Stand zurücksetzen“ bewahrt die raw-verfasste Form (Formatierung, Kommentare, `$include`-Layout), statt einen abgeflachten Snapshot neu zu rendern, sodass externe Bearbeitungen einen Reset überstehen, wenn der Snapshot sicher im Roundtrip verarbeitet werden kann.
- Strukturierte SecretRef-Objektwerte werden in Formular-Texteingaben schreibgeschützt dargestellt, um versehentliche Beschädigung durch Umwandlung von Objekt zu String zu verhindern.
</Accordion>
<Accordion title="Debug, Protokolle, Update">
- Debug: Status-/Health-/Modellsnapshots, Ereignisprotokoll und manuelle RPC-Aufrufe (`status`, `health`, `models.list`).
<Accordion title="Debug, Protokolle, Aktualisierung">
- Debug: Status-/Health-/Modell-Snapshots, Ereignisprotokoll und manuelle RPC-Aufrufe (`status`, `health`, `models.list`).
- Protokolle: Live-Tail der Gateway-Dateiprotokolle mit Filter/Export (`logs.tail`).
- Update: ein Paket-/Git-Update und Neustart ausführen (`update.run`) mit Neustartbericht, anschließend nach dem erneuten Verbinden `update.status` abfragen, um die laufende Gateway-Version zu verifizieren.
- Aktualisierung: Paket-/Git-Aktualisierung und Neustart ausführen (`update.run`) mit Neustartbericht, anschließend nach der erneuten Verbindung `update.status` abfragen, um die laufende Gateway-Version zu verifizieren.
</Accordion>
<Accordion title="Hinweise zum Cron-Jobs-Fenster">
- Für isolierte Jobs ist die Auslieferung standardmäßig auf Zusammenfassung ankündigen gesetzt. Sie können auf keine umschalten, wenn Sie rein interne Ausführungen wünschen.
- Für isolierte Jobs ist die Zustellung 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.
- 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, exakte/gestaffelte Cron-Optionen, Agent-Modell-/Thinking-Überschreibungen und Best-Effort-Auslieferungsschalter.
- Formularvalidierung erfolgt inline mit feldbezogenen Fehlern; ungültige Werte deaktivieren die Speichern-Schaltfläche, bis sie behoben sind.
- Setzen Sie `cron.webhookToken`, um ein dediziertes Bearer-Token zu senden; wenn es weggelassen wird, wird der Webhook ohne Authentifizierungsheader gesendet.
- Veralteter Fallback: gespeicherte Legacy-Jobs mit `notify: true` können bis zur Migration weiterhin `cron.webhook` verwenden.
- Der Webhook-Modus verwendet `delivery.mode = "webhook"` mit `delivery.to`, gesetzt auf eine gültige HTTP(S)-Webhook-URL.
- Für Hauptsitzungs-Jobs sind die Zustellmodi Webhook und keine verfügbar.
- Erweiterte Bearbeitungssteuerelemente umfassen Nach-Ausführung-löschen, Agent-Überschreibung löschen, Cron-Optionen exakt/gestaffelt, Überschreibungen für Agent-Modell/Denken und Best-Effort-Zustellumschalter.
- Die Formularvalidierung erfolgt inline mit feldbezogenen Fehlern; ungültige Werte deaktivieren die Speichern-Schaltfläche, bis sie korrigiert sind.
- Setzen Sie `cron.webhookToken`, um ein dediziertes Bearer-Token zu senden; wenn ausgelassen, wird der Webhook ohne Authentifizierungsheader gesendet.
- Veralteter Fallback: Gespeicherte Legacy-Jobs mit `notify: true` können weiterhin `cron.webhook` verwenden, bis sie migriert wurden.
</Accordion>
</AccordionGroup>
@ -155,61 +156,62 @@ Importierte Themen werden nur im aktuellen Browserprofil gespeichert. Sie werden
<AccordionGroup>
<Accordion title="Sende- und Verlaufssemantik">
- `chat.send` ist **nicht blockierend**: Es bestätigt sofort mit `{ runId, status: "started" }`, und die Antwort wird über `chat`-Events gestreamt.
- `chat.send` ist **nicht blockierend**: Es bestätigt sofort mit `{ runId, status: "started" }`, und die Antwort wird über `chat`-Ereignisse gestreamt.
- `chat.transcribeAudio` ist ein einmaliger Diktierhelfer für Chat-Entwürfe. Er akzeptiert im Browser aufgezeichnetes Base64-Audio, hält Uploads unterhalb des Gateway-WebSocket-Frame-Limits, schreibt eine temporäre lokale Datei, führt Audio-Transkription mit Medienverständnis und der aktiven Gateway-Konfiguration aus, gibt `{ text, provider, model }` zurück und entfernt die temporäre Datei. Er erstellt keinen Agentenlauf und ist von Echtzeit-Talk getrennt.
- 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" }` zurück und nach Abschluss `{ status: "ok" }`.
- `chat.history`-Antworten sind aus Sicherheitsgründen für die UI 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]`).
- Von 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 Chat-Verlaufsantwort verbleiben.
- `chat.history` entfernt außerdem nur zur Anzeige dienende Inline-Direktiv-Tags aus sichtbarem Assistententext (zum Beispiel `[[reply_to_*]]` und `[[audio_as_voice]]`), Nur-Text-XML-Nutzdaten von Tool-Aufrufen (einschließlich `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` und gekürzter Tool-Aufruf-Blöcke) sowie durchgesickerte ASCII- und vollbreite Modell-Steuertoken und lässt Assistenteneinträge aus, deren gesamter sichtbarer Text ausschließlich das exakte stille Token `NO_REPLY` / `no_reply` ist.
- 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.
- `chat.inject` fügt dem Sitzungstranskript eine Assistentennotiz hinzu und sendet ein `chat`-Event für reine UI-Aktualisierungen (kein Agent-Lauf, keine Kanalauslieferung).
- Die Modell- und Denk-Auswahlen im Chat-Header patchen die aktive Sitzung sofort über `sessions.patch`; sie sind dauerhafte Sitzungsüberschreibungen, keine nur für einen Zug geltenden Sendeoptionen.
- Die Eingabe von `/new` in der Control UI erstellt dieselbe frische 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 fordert die konfigurierte Modellansicht des Gateway 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-RPC `models.list` mit `view: "all"` verfügbar.
- Wenn frische Gateway-Sitzungsnutzungsberichte hohen Kontextdruck anzeigen, zeigt der Chat-Composer-Bereich einen Kontexthinweis und bei empfohlenen Compaction-Stufen eine Kompakt-Schaltfläche, die den normalen Sitzungspfad für Compaction ausführt. Veraltete Token-Snapshots werden ausgeblendet, bis Gateway wieder frische Nutzung meldet.
- 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 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 ersetzen (`[chat.history omitted: message too large]`).
- Vom Assistenten generierte Bilder werden als verwaltete Medienreferenzen persistiert und über authentifizierte Gateway-Medien-URLs wieder ausgeliefert, sodass Neuladen nicht davon abhängt, dass rohe Base64-Bilddaten in der Chat-Verlaufsantwort verbleiben.
- `chat.history` entfernt außerdem nur für die Anzeige bestimmte Inline-Direktiv-Tags aus sichtbarem Assistententext (zum Beispiel `[[reply_to_*]]` und `[[audio_as_voice]]`), Nur-Text-XML-Nutzdaten von Tool-Aufrufen (einschließlich `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` und gekürzter Tool-Aufrufblöcke) sowie durchgesickerte ASCII- und vollbreite Modell-Steuertoken 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 Verlaufsaktualisierung hält die Chat-Ansicht lokale optimistische Benutzer- und Assistentennachrichten sichtbar, wenn `chat.history` kurzzeitig einen älteren Snapshot zurückgibt; das kanonische Transkript ersetzt diese lokalen Nachrichten, sobald der Gateway-Verlauf aufgeholt hat.
- `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 Thinking-Auswahlen im Chat-Header patchen die aktive Sitzung sofort über `sessions.patch`; sie sind persistente Sitzungsüberschreibungen, keine nur für einen einzelnen Turn geltenden Sendeoptionen.
- Die Eingabe von `/new` in der Control UI erstellt und wechselt zu derselben frischen Dashboard-Sitzung wie New Chat. Die Eingabe von `/reset` behält den expliziten In-Place-Reset des Gateways für die aktuelle Sitzung bei.
- Die Chat-Modellauswahl fordert 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-RPC `models.list` mit `view: "all"` verfügbar.
- Wenn frische 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 das Gateway erneut frische Nutzung meldet.
</Accordion>
<Accordion title="Sprechmodus (Browser-Echtzeit)">
Der Sprechmodus verwendet einen registrierten Echtzeit-Sprachprovider. 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 Sprachanrufe kann weiterhin als Fallback wiederverwendet werden. Der Browser erhält niemals einen standardmäßigen Provider-API-Schlüssel. OpenAI erhält ein kurzlebiges 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 den Gateway im Token fixiert werden. Provider, die nur eine Backend-Echtzeitbrücke bereitstellen, laufen über den Gateway-Relay-Transport, sodass Anmeldedaten und Anbieter-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.
<Accordion title="Talk-Modus (Browser-Echtzeit)">
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 für Voice Call kann weiterhin als Fallback wiederverwendet werden. Der Browser erhält niemals einen standardmäßigen Provider-API-Schlüssel. OpenAI erhält ein kurzlebiges Realtime-Client-Secret für WebRTC. Google Live erhält ein einmalig nutzbares, eingeschränktes Live-API-Authentifizierungstoken für eine Browser-WebSocket-Sitzung, wobei Anweisungen und Tool-Deklarationen durch das Gateway im Token gesperrt sind. Provider, die nur eine Backend-Echtzeit-Bridge bereitstellen, laufen über den Gateway-Relay-Transport, sodass Zugangsdaten 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.
Im Chat-Composer ist das Sprech-Steuerelement die Wellen-Schaltfläche neben der Mikrofon-Diktat-Schaltfläche. Wenn Sprechen startet, zeigt die Composer-Statuszeile `Connecting Talk...`, danach `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 das Talk-Steuerelement die Wellen-Schaltfläche neben der Mikrofon-Diktat-Schaltfläche. Wenn Talk startet, zeigt die Composer-Statuszeile `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 Google Live-Einrichtung eines eingeschränkten Token-Browser-WebSocket sowie den Gateway-Relay-Browser-Adapter mit gefälschten 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` überprüft 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.
</Accordion>
<Accordion title="Stoppen und abbrechen">
- 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 Zug einzuspeisen.
- Geben Sie `/stop` ein (oder eigenständige Abbruchphrasen wie `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`), um außerhalb des Bands abzubrechen.
- 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 wartenden 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 Pfads abzubrechen.
- `chat.abort` unterstützt `{ sessionKey }` (ohne `runId`), um alle aktiven Läufe für diese Sitzung abzubrechen.
</Accordion>
<Accordion title="Beibehaltung von Abbruch-Teilausgaben">
- Wenn ein Lauf abgebrochen wird, kann teilweiser Assistententext weiterhin in der UI angezeigt werden.
- Gateway speichert abgebrochenen teilweisen Assistententext im Transkriptverlauf dauerhaft, wenn gepufferte Ausgabe vorhanden ist.
- Dauerhaft gespeicherte Einträge enthalten Abbruchmetadaten, damit Transkriptverbraucher Abbruch-Teilausgaben von normaler Abschlussausgabe unterscheiden können.
<Accordion title="Beibehaltung abgebrochener Teilausgaben">
- Wenn ein Lauf abgebrochen wird, kann partieller Assistententext weiterhin in der UI angezeigt werden.
- Das Gateway persistiert abgebrochenen partiellen Assistententext im Transkriptverlauf, wenn gepufferte Ausgabe vorhanden ist.
- Persistierte Einträge enthalten Abbruchmetadaten, damit Transkriptkonsumenten abgebrochene Teilausgaben von normaler Abschlussausgabe unterscheiden können.
</Accordion>
</AccordionGroup>
## 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. Web Push ermöglicht es dem Gateway, die installierte PWA mit Benachrichtigungen aufzuwecken, 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. Web Push ermöglicht dem Gateway, die installierte PWA mit Benachrichtigungen zu wecken, auch wenn der Tab oder das Browserfenster nicht geöffnet ist.
| Oberfläche | Funktion |
| ----------------------------------------------------- | ------------------------------------------------------------------ |
| `ui/public/manifest.webmanifest` | PWA-Manifest. Browser bieten „App installieren“ an, sobald es erreichbar ist. |
| `ui/public/sw.js` | Service Worker, der `push`-Events und Benachrichtigungsklicks verarbeitet. |
| `push/vapid-keys.json` (unter dem OpenClaw-State-Verzeichnis) | Automatisch generiertes VAPID-Schlüsselpaar zum Signieren von Web-Push-Nutzdaten. |
| `push/web-push-subscriptions.json` | Dauerhaft gespeicherte Browser-Abonnement-Endpunkte. |
| `ui/public/sw.js` | Service Worker, der `push`-Ereignisse und Benachrichtigungsklicks verarbeitet. |
| `push/vapid-keys.json` (im OpenClaw-Statusverzeichnis) | Automatisch generiertes VAPID-Schlüsselpaar zum Signieren von Web-Push-Nutzdaten. |
| `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 festlegen möchten (für Multi-Host-Deployments, Secret-Rotation oder Tests):
- `OPENCLAW_VAPID_PUBLIC_KEY`
- `OPENCLAW_VAPID_PRIVATE_KEY`
- `OPENCLAW_VAPID_SUBJECT` (Standard ist `mailto:openclaw@localhost`)
- `OPENCLAW_VAPID_SUBJECT` (standardmäßig `mailto:openclaw@localhost`)
Die Control UI verwendet diese scope-geschützten Gateway-Methoden, um Browser-Abonnements zu registrieren und zu testen:
Die Control UI verwendet diese scope-gebundenen 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`.
@ -217,7 +219,7 @@ Die Control UI verwendet diese scope-geschützten Gateway-Methoden, um Browser-A
- `push.web.test` — sendet eine Testbenachrichtigung an das Abonnement des Aufrufers.
<Note>
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 zielen.
Web Push ist unabhängig vom iOS-APNS-Relay-Pfad (siehe [Konfiguration](/de/gateway/configuration) für relay-gestützte Push-Benachrichtigungen) und von der bestehenden Methode `push.test`, die auf native mobile Kopplung abzielt.
</Note>
## Gehostete Einbettungen
@ -226,13 +228,13 @@ Assistentennachrichten können gehostete Webinhalte inline mit dem Shortcode `[e
<Tabs>
<Tab title="strict">
Deaktiviert die Skriptausführung innerhalb gehosteter Einbettungen.
Deaktiviert Skriptausführung innerhalb gehosteter Einbettungen.
</Tab>
<Tab title="scripts (default)">
Erlaubt interaktive Einbettungen bei beibehaltener Origin-Isolation; dies ist die Standardeinstellung und reicht in der Regel für eigenständige Browserspiele/-widgets aus.
<Tab title="scripts (Standard)">
Erlaubt interaktive Einbettungen bei gleichzeitiger Origin-Isolation; dies ist die Standardeinstellung und reicht normalerweise für eigenständige Browser-Spiele/Widgets aus.
</Tab>
<Tab title="trusted">
Fügt `allow-same-origin` zusätzlich zu `allow-scripts` für Same-Site-Dokumente hinzu, die bewusst stärkere Berechtigungen benötigen.
Fügt `allow-same-origin` zusätzlich zu `allow-scripts` für Dokumente derselben Website hinzu, die absichtlich stärkere Berechtigungen benötigen.
</Tab>
</Tabs>
@ -249,14 +251,14 @@ Beispiel:
```
<Warning>
Verwenden Sie `trusted` nur, wenn das eingebettete Dokument wirklich Same-Origin-Verhalten benötigt. Für die meisten agentgenerierten 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.
</Warning>
Absolute externe `http(s)`-Einbettungs-URLs bleiben standardmäßig blockiert. Wenn Sie bewusst 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 absichtlich möchten, dass `[embed url="https://..."]` Drittanbieterseiten lädt, setzen Sie `gateway.controlUi.allowExternalEmbedUrls: true`.
## Chat-Nachrichtenbreite
## Breite von Chat-Nachrichten
Gruppierte Chat-Nachrichten verwenden eine lesbare standardmäßige Maximalbreite. Deployments mit breiten Monitoren können sie überschreiben, ohne gebündeltes CSS zu patchen, indem `gateway.controlUi.chatMessageMaxWidth` gesetzt wird:
Gruppierte Chat-Nachrichten verwenden eine gut lesbare Standard-Maximalbreite. Deployments mit breiten Monitoren können sie ohne Patchen des gebündelten CSS überschreiben, indem `gateway.controlUi.chatMessageMaxWidth` gesetzt wird:
```json5
{
@ -268,13 +270,13 @@ Gruppierte Chat-Nachrichten verwenden eine lesbare standardmäßige Maximalbreit
}
```
Der Wert wird validiert, bevor er den Browser erreicht. Unterstützte Werte umfassen einfache Längen und Prozentwerte 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 Prozentsätze wie `960px` oder `82%` sowie beschränkte Breiten-Ausdrücke mit `min(...)`, `max(...)`, `clamp(...)`, `calc(...)` und `fit-content(...)`.
## Tailnet-Zugriff (empfohlen)
<Tabs>
<Tab title="Integrierter Tailscale Serve (bevorzugt)">
Halten Sie den Gateway auf loopback und lassen Sie ihn von Tailscale Serve per HTTPS proxien:
<Tab title="Integriertes Tailscale Serve (bevorzugt)">
Halten Sie das Gateway auf loopback und lassen Sie Tailscale Serve es per HTTPS proxien:
```bash
openclaw gateway --tailscale serve
@ -284,12 +286,12 @@ Der Wert wird validiert, bevor er den Browser erreicht. Unterstützte Werte umfa
- `https://<magicdns>/` (oder Ihren konfigurierten `gateway.controlUi.basePath`)
Standardmäßig können Control-UI-/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 Adresse `x-forwarded-for` mit `tailscale whois` auflöst und mit dem Header abgleicht, und akzeptiert diese nur, wenn die Anfrage local loopback mit den `x-forwarded-*`-Headern von Tailscale erreicht. Für Control-UI-Operator-Sitzungen mit Browser-Geräteidentität überspringt dieser verifizierte Serve-Pfad außerdem 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 explite Anmeldedaten mit gemeinsamem Secret verlangen möchten. Verwenden Sie dann `gateway.auth.mode: "token"` oder `"password"`.
Standardmäßig können sich Control-UI-/WebSocket-Serve-Anfragen über Tailscale-Identitätsheader (`tailscale-user-login`) authentifizieren, 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 Tailscales `x-forwarded-*`-Headern erreicht. Für Control-UI-Operator-Sitzungen mit Browser-Geräteidentität überspringt dieser verifizierte Serve-Pfad außerdem den Geräte-Kopplungs-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 selbst für Serve-Datenverkehr explizite Shared-Secret-Zugangsdaten 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 Authentifizierungs-Scope serialisiert, bevor Rate-Limit-Schreibvorgänge erfolgen. 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 Authentifizierungs-Scope vor Rate-Limit-Schreibvorgängen serialisiert. Gleichzeitige fehlerhafte Wiederholungen aus demselben Browser können daher bei der zweiten Anfrage `retry later` anzeigen, anstatt dass zwei einfache Nichtübereinstimmungen parallel konkurrieren.
<Warning>
Tokenlose Serve-Authentifizierung setzt voraus, dass der Gateway-Host vertrauenswürdig ist. Wenn nicht vertrauenswürdiger lokaler Code auf diesem Host laufen kann, verlangen Sie Token-/Passwortauthentifizierung.
Tokenlose Serve-Authentifizierung setzt voraus, dass der Gateway-Host vertrauenswürdig ist. Wenn nicht vertrauenswürdiger lokaler Code auf diesem Host ausgeführt werden könnte, verlangen Sie Token-/Passwort-Authentifizierung.
</Warning>
</Tab>
@ -309,21 +311,21 @@ Der Wert wird validiert, bevor er den Browser erreicht. Unterstützte Werte umfa
## Unsicheres HTTP
Wenn Sie das Dashboard über unverschlüsseltes HTTP öffnen (`http://<lan-ip>` oder `http://<tailscale-ip>`), 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 öffnen (`http://<lan-ip>` oder `http://<tailscale-ip>`), 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-Kompatibilität für unsicheres HTTP mit `gateway.controlUi.allowInsecureAuth=true`
- nur für localhost gedachte unsichere HTTP-Kompatibilität mit `gateway.controlUi.allowInsecureAuth=true`
- erfolgreiche Operator-Control-UI-Authentifizierung über `gateway.auth.mode: "trusted-proxy"`
- Break-Glass-Option `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
- Break-Glass `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
**Empfohlene Lösung:** Verwenden Sie HTTPS (Tailscale Serve) oder öffnen Sie die UI lokal:
**Empfohlene Behebung:** Verwenden Sie HTTPS (Tailscale Serve) oder öffnen Sie die UI lokal:
- `https://<magicdns>/` (Serve)
- `http://127.0.0.1:18789/` (auf dem Gateway-Host)
<AccordionGroup>
<Accordion title="Verhalten des Schalters für unsichere Authentifizierung">
<Accordion title="Insecure-auth toggle behavior">
```json5
{
gateway: {
@ -334,14 +336,14 @@ Dokumentierte Ausnahmen:
}
```
`allowInsecureAuth` ist nur ein lokaler Kompatibilitätsschalter:
`allowInsecureAuth` ist nur ein lokaler Kompatibilitäts-Schalter:
- Er erlaubt localhost-Control-UI-Sitzungen, in unsicheren 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 ermöglicht localhost-Control-UI-Sitzungen ohne Geräteidentität in nicht sicheren HTTP-Kontexten.
- Er umgeht keine Pairing-Prüfungen.
- Er lockert keine Anforderungen an die Geräteidentität für entfernte (nicht lokale localhost-)Zugriffe.
</Accordion>
<Accordion title="Nur für Notfälle">
<Accordion title="Break-glass only">
```json5
{
gateway: {
@ -353,52 +355,52 @@ Dokumentierte Ausnahmen:
```
<Warning>
`dangerouslyDisableDeviceAuth` deaktiviert die Geräteidentitätsprüfungen der Control UI und ist eine schwerwiegende Sicherheitsverschlechterung. Setzen Sie dies nach der Notfallnutzung schnell zurück.
`dangerouslyDisableDeviceAuth` deaktiviert die Geräteidentitätsprüfungen der Control UI und stellt eine erhebliche Sicherheitsabsenkung dar. Setzen Sie dies nach der Notfallnutzung schnell wieder zurück.
</Warning>
</Accordion>
<Accordion title="Hinweis zu vertrauenswürdigen Proxys">
- Erfolgreiche Authentifizierung über einen vertrauenswürdigen Proxy kann **Operator**-Control-UI-Sitzungen ohne Geräteidentität zulassen.
- Dies gilt **nicht** für Control-UI-Sitzungen mit node-role.
- Reverse Proxys über loopback auf demselben Host erfüllen die Authentifizierung über vertrauenswürdige Proxys weiterhin nicht; siehe [Authentifizierung über vertrauenswürdigen Proxy](/de/gateway/trusted-proxy-auth).
<Accordion title="Trusted-proxy note">
- 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).
</Accordion>
</AccordionGroup>
Siehe [Tailscale](/de/gateway/tailscale) für Anleitungen zur HTTPS-Einrichtung.
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`-Policy ausgeliefert: Es sind nur Assets mit **same-origin**, `data:`-URLs und lokal generierte `blob:`-URLs erlaubt. Entfernte `http(s)`- und protokollrelative Bild-URLs werden vom Browser abgelehnt und lösen keine Netzwerkabrufe aus.
Die Control UI wird mit einer strengen `img-src`-Richtlinie ausgeliefert: Es sind nur Assets mit **gleichem Ursprung**, `data:`-URLs und lokal erzeugte `blob:`-URLs erlaubt. Entfernte `http(s)`- und protokollrelative Bild-URLs werden vom Browser abgewiesen und lösen keine Netzwerkabrufe aus.
Das bedeutet in der Praxis:
- Avatare und Bilder, die unter relativen Pfaden bereitgestellt werden (zum Beispiel `/avatars/<id>`), 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 Nutzdaten innerhalb des Protokolls).
- Lokale `blob:`-URLs, die von der Control UI erstellt werden, werden weiterhin gerendert.
- Entfernte Avatar-URLs, die von Kanalmetadaten ausgegeben werden, werden in den Avatar-Hilfsfunktionen 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.
- Inline-`data:image/...`-URLs werden weiterhin gerendert (nützlich für Payloads innerhalb des Protokolls).
- Von der Control UI erstellte lokale `blob:`-URLs werden weiterhin gerendert.
- Entfernte Avatar-URLs, die von Kanalmetadaten ausgegeben werden, werden in den Avatar-Hilfsfunktionen der Control UI entfernt und durch das integrierte Logo/Badge ersetzt. So kann ein kompromittierter oder bösartiger Kanal keine beliebigen entfernten Bildabrufe aus dem Browser eines Operators erzwingen.
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 dasselbe Gateway-Token wie der Rest der API:
- `GET /avatar/<agentId>` gibt das Avatar-Bild nur an authentifizierte Aufrufer zurück. `GET /avatar/<agentId>?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). Dadurch wird verhindert, dass die Avatar-Route auf ansonsten geschützten Hosts Agentenidentitäten preisgibt.
- Die Control UI selbst leitet das Gateway-Token beim Abrufen von Avataren als Bearer-Header weiter und verwendet authentifizierte Blob-URLs, sodass das Bild in Dashboards weiterhin gerendert wird.
- Nicht authentifizierte Anfragen an eine der beiden 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 selbst leitet beim Abrufen von Avataren das Gateway-Token als Bearer-Header weiter und verwendet authentifizierte Blob-URLs, damit das Bild in Dashboards weiterhin gerendert wird.
Wenn Sie die Gateway-Authentifizierung deaktivieren (auf gemeinsam genutzten Hosts nicht empfohlen), wird auch die Avatar-Route unauthentifiziert, entsprechend dem Rest des Gateways.
Wenn Sie die Gateway-Authentifizierung deaktivieren (auf gemeinsam genutzten Hosts nicht empfohlen), wird auch die Avatar-Route nicht authentifiziert, entsprechend dem restlichen Gateway.
## UI bauen
## UI erstellen
Das Gateway stellt statische Dateien aus `dist/control-ui` bereit. Bauen Sie sie mit:
Das Gateway stellt statische Dateien aus `dist/control-ui` bereit. Erstellen Sie sie mit:
```bash
pnpm ui:build
```
Optionale absolute Basis (wenn Sie feste Asset-URLs möchten):
Optionale absolute Basis (wenn Sie feste Asset-URLs wünschen):
```bash
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
@ -410,19 +412,19 @@ Für lokale Entwicklung (separater Dev-Server):
pnpm ui:dev
```
Verweisen Sie die UI anschließend auf Ihre Gateway-WS-URL (z. B. `ws://127.0.0.1:18789`).
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
## Debugging/Testen: Dev-Server + entferntes Gateway
Die Control UI besteht aus statischen Dateien; das WebSocket-Ziel ist konfigurierbar und kann sich vom HTTP-Origin unterscheiden. Das ist praktisch, wenn Sie den Vite-Dev-Server lokal verwenden möchten, das Gateway aber an anderer Stelle 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 anderswo läuft.
<Steps>
<Step title="UI-Dev-Server starten">
<Step title="Start the UI dev server">
```bash
pnpm ui:dev
```
</Step>
<Step title="Mit gatewayUrl öffnen">
<Step title="Open with gatewayUrl">
```text
http://localhost:5173/?gatewayUrl=ws%3A%2F%2F<gateway-host>%3A18789
```
@ -437,18 +439,18 @@ Die Control UI besteht aus statischen Dateien; das WebSocket-Ziel ist konfigurie
</Steps>
<AccordionGroup>
<Accordion title="Hinweise">
<Accordion title="Notes">
- `gatewayUrl` wird nach dem Laden in localStorage gespeichert und aus der URL entfernt.
- Wenn Sie über `gatewayUrl` einen vollständigen `ws://`- oder `wss://`-Endpunkt übergeben, URL-kodieren Sie den Wert `gatewayUrl`, damit der Browser den Query-String 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 Referern vermieden werden. Legacy-Query-Parameter `?token=` werden aus Kompatibilitätsgründen weiterhin einmal importiert, aber nur als Fallback, und unmittelbar nach dem Bootstrap entfernt.
- Wenn Sie einen vollständigen `ws://`- oder `wss://`-Endpunkt über `gatewayUrl` übergeben, URL-kodieren Sie den `gatewayUrl`-Wert, damit der Browser die Abfragezeichenfolge 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 im Referer vermieden werden. Veraltete `?token=`-Abfrageparameter werden aus Kompatibilitätsgründen weiterhin einmal importiert, aber nur als Fallback, und unmittelbar nach dem Bootstrap entfernt.
- `password` wird nur im Arbeitsspeicher gehalten.
- Wenn `gatewayUrl` gesetzt ist, fällt die UI nicht auf Anmeldedaten aus Konfiguration oder Umgebung 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.).
- Wenn `gatewayUrl` gesetzt ist, greift die UI nicht auf Konfigurations- oder Umgebungs-Zugangsdaten zurück. Geben Sie `token` (oder `password`) explizit an. Fehlende explizite Zugangsdaten sind ein Fehler.
- Verwenden Sie `wss://`, wenn das Gateway hinter TLS liegt (Tailscale Serve, HTTPS-Proxy usw.).
- `gatewayUrl` wird nur in einem Top-Level-Fenster akzeptiert (nicht eingebettet), um Clickjacking zu verhindern.
- Nicht-loopback-Control-UI-Bereitstellungen müssen `gateway.controlUi.allowedOrigins` explizit setzen (vollständige Origins). Dies schließt entfernte Dev-Setups ein.
- Der Gateway-Start kann lokale Origins wie `http://localhost:<port>` und `http://127.0.0.1:<port>` aus dem effektiven Runtime-Bind und Port erzeugen, aber entfernte Browser-Origins benötigen weiterhin explizite Einträge.
- Verwenden Sie `gateway.controlUi.allowedOrigins: ["*"]` nur für streng kontrollierte lokale Tests. Es bedeutet, jeden Browser-Origin zuzulassen, nicht „den Host abgleichen, den ich gerade verwende“.
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` aktiviert den Host-Header-Origin-Fallback-Modus, aber dies ist ein gefährlicher Sicherheitsmodus.
- Nicht-loopback-Control-UI-Bereitstellungen müssen `gateway.controlUi.allowedOrigins` explizit setzen (vollständige Ursprünge). Dazu gehören entfernte Dev-Setups.
- Der Gateway-Start kann lokale Ursprünge wie `http://localhost:<port>` und `http://127.0.0.1:<port>` aus dem effektiven Laufzeit-Bind und -Port ableiten, aber entfernte Browser-Ursprünge benötigen weiterhin explizite Einträge.
- Verwenden Sie `gateway.controlUi.allowedOrigins: ["*"]` nur für streng kontrollierte lokale Tests. Es bedeutet, jeden Browser-Ursprung zu erlauben, nicht „den Host abgleichen, den ich gerade verwende“.
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` aktiviert den Fallback-Modus für Host-Header-Ursprünge, ist aber ein gefährlicher Sicherheitsmodus.
</Accordion>
</AccordionGroup>
@ -465,11 +467,11 @@ Beispiel:
}
```
Details zur Einrichtung des Fernzugriffs: [Fernzugriff](/de/gateway/remote).
Details zur Einrichtung des entfernten Zugriffs: [Remote access](/de/gateway/remote).
## Verwandt
- [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

77
docs/de/web/webchat.md
View File

@ -1,66 +1,67 @@
---
read_when:
- WebChat-Zugriff debuggen oder konfigurieren
summary: Statischer Loopback-WebChat-Host und Gateway-WS-Nutzung für die Chat-UI
- Debuggen oder Konfigurieren des WebChat-Zugriffs
summary: Statischer Loopback-WebChat-Host und Gateway-WS-Nutzung für die Chat-Benutzeroberfläche
title: Webchat
x-i18n:
generated_at: "2026-05-02T06:49:22Z"
generated_at: "2026-05-02T23:39:04Z"
model: gpt-5.5
provider: openai
source_hash: fe6d3cb30ed18d651b0d0ca8fd188b47c5f1d186410ee340deb79315f194ed8d
source_hash: ad3a09c8962e3a6dda83716d319df7ba27e18105cee50721278b5cba0a85c52f
source_path: web/webchat.md
workflow: 16
---
Status: Die macOS/iOS-SwiftUI-Chatoberfläche spricht direkt mit dem Gateway-WebSocket.
Status: Die macOS/iOS-SwiftUI-Chat-UI kommuniziert direkt mit dem Gateway-WebSocket.
## Was es ist
- Eine native Chatoberfläche für das Gateway (kein eingebetteter Browser und kein lokaler statischer Server).
- Verwendet dieselben Sitzungen und Routingregeln wie andere Kanäle.
- Eine native Chat-UI für das Gateway (kein eingebetteter Browser und kein lokaler statischer Server).
- Verwendet dieselben Sitzungen und Routing-Regeln wie andere Kanäle.
- Deterministisches Routing: Antworten gehen immer zurück an WebChat.
## Schnellstart
1. Starten Sie das Gateway.
2. Öffnen Sie die WebChat-UI (macOS/iOS-App) oder den Chat-Tab der Control UI.
3. Stellen Sie sicher, dass ein gültiger Gateway-Authentifizierungspfad konfiguriert ist (standardmäßig shared-secret,
selbst bei Loopback).
3. Stellen Sie sicher, dass ein gültiger Gateway-Authentifizierungspfad konfiguriert ist (standardmäßig Shared Secret,
auch bei Loopback).
## Funktionsweise (Verhalten)
- Die UI verbindet sich mit dem Gateway-WebSocket und verwendet `chat.history`, `chat.send` und `chat.inject`.
- `chat.history` ist aus Stabilitätsgründen begrenzt: Das Gateway kann lange Textfelder kürzen, umfangreiche Metadaten auslassen und übergroße Einträge durch `[chat.history omitted: message too large]` ersetzen.
- `chat.history` folgt dem aktiven Transkriptzweig für moderne Append-only-Sitzungsdateien, sodass verworfene Rewrite-Zweige und ersetzte Prompt-Kopien nicht in WebChat gerendert werden.
- Die Control UI merkt sich die vom `chat.history` zurückgegebene zugrunde liegende Gateway-`sessionId` und fügt sie nachfolgenden `chat.send`-Aufrufen hinzu, sodass Neuverbindungen und Seitenaktualisierungen dieselbe gespeicherte Unterhaltung fortsetzen, sofern der Benutzer keine Sitzung startet oder zurücksetzt.
- Die Control UI fasst doppelte laufende Übermittlungen für dieselbe Sitzung, Nachricht und Anhänge zusammen, bevor sie eine neue `chat.send`-Run-ID generiert; das Gateway dedupliziert weiterhin wiederholte Anfragen, die denselben Idempotenzschlüssel wiederverwenden.
- `chat.history` ist außerdem für die Anzeige normalisiert: nur zur Laufzeit vorhandener OpenClaw-Kontext,
- Die UI verbindet sich mit dem Gateway-WebSocket und verwendet `chat.history`, `chat.send`, `chat.inject` und `chat.transcribeAudio`.
- `chat.history` ist zur Stabilität begrenzt: Gateway kann lange Textfelder kürzen, umfangreiche Metadaten auslassen und übergroße Einträge durch `[chat.history omitted: message too large]` ersetzen.
- `chat.history` folgt bei modernen Append-only-Sitzungsdateien dem aktiven Transkriptzweig, sodass verworfene Rewrite-Zweige und ersetzte Prompt-Kopien nicht in WebChat gerendert werden.
- Control UI merkt sich die vom Gateway über `chat.history` zurückgegebene zugrunde liegende `sessionId` und übergibt sie bei nachfolgenden `chat.send`-Aufrufen, sodass erneute Verbindungen und Seitenaktualisierungen dieselbe gespeicherte Unterhaltung fortsetzen, sofern der Benutzer keine Sitzung startet oder zurücksetzt.
- Control UI führt doppelte laufende Übermittlungen für dieselbe Sitzung, Nachricht und Anhänge zusammen, bevor eine neue `chat.send`-Lauf-ID erzeugt wird; das Gateway dedupliziert weiterhin wiederholte Anfragen, die denselben Idempotenzschlüssel wiederverwenden.
- `chat.history` wird auch für die Anzeige normalisiert: Nur zur Laufzeit verwendeter OpenClaw-Kontext,
eingehende Envelope-Wrapper, Inline-Tags für Zustellungsdirektiven
wie `[[reply_to_*]]` und `[[audio_as_voice]]`, XML-Nutzdaten von Klartext-Tool-Aufrufen
wie `[[reply_to_*]]` und `[[audio_as_voice]]`, Nur-Text-XML-Nutzlasten von Tool-Aufrufen
(einschließlich `<tool_call>...</tool_call>`,
`<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`,
`<function_calls>...</function_calls>` und gekürzter Tool-Aufrufblöcke) sowie
durchgesickerte ASCII-/vollbreite Modell-Steuerungstoken werden aus sichtbarem Text entfernt,
und Assistant-Einträge, deren gesamter sichtbarer Text nur aus dem exakten stillen
Token `NO_REPLY` / `no_reply` besteht, werden ausgelassen.
- Als Reasoning markierte Antwortnutzdaten (`isReasoning: true`) werden von WebChat-Assistant-Inhalten, Transkript-Wiedergabetext und Audioinhaltsblöcken ausgeschlossen, sodass reine Denkinhalte nicht als sichtbare Assistant-Nachrichten oder abspielbares Audio erscheinen.
- `chat.inject` hängt eine Assistant-Notiz direkt an das Transkript an und sendet sie an die UI (kein Agent-Lauf).
- Abgebrochene Läufe können partielle Assistant-Ausgabe in der UI sichtbar lassen.
- Das Gateway speichert abgebrochenen partiellen Assistant-Text in der Transkript-Historie, wenn gepufferte Ausgabe vorhanden ist, und markiert diese Einträge mit Abbruchmetadaten.
- Die Historie wird immer vom Gateway abgerufen (keine lokale Dateiüberwachung).
und Assistenteneinträge, deren gesamter sichtbarer Text ausschließlich das exakte stille
Token `NO_REPLY` / `no_reply` ist, werden ausgelassen.
- Antwort-Nutzlasten mit Reasoning-Flag (`isReasoning: true`) werden aus WebChat-Assistenteninhalten, Transkript-Wiedergabetext und Audio-Inhaltsblöcken ausgeschlossen, sodass reine Denk-Nutzlasten nicht als sichtbare Assistentennachrichten oder abspielbares Audio erscheinen.
- `chat.transcribeAudio` ermöglicht serverseitiges Diktieren im Chat-Composer der Control UI. Der Browser zeichnet Mikrofon-Audio auf, sendet es als Base64 an das Gateway, und das Gateway führt die konfigurierte `tools.media.audio`-Pipeline aus. Das zurückgegebene Transkript wird in den Entwurf eingefügt; es wird kein Agentenlauf gestartet, bis der Benutzer ihn absendet.
- `chat.inject` hängt eine Assistentennotiz direkt an das Transkript an und sendet sie an die UI (kein Agentenlauf).
- Abgebrochene Läufe können teilweise Assistentenausgaben in der UI sichtbar halten.
- Gateway persistiert abgebrochenen partiellen Assistententext im Transkriptverlauf, wenn gepufferte Ausgabe vorhanden ist, und markiert diese Einträge mit Abbruchmetadaten.
- Der Verlauf wird immer vom Gateway abgerufen (keine lokale Dateiüberwachung).
- Wenn das Gateway nicht erreichbar ist, ist WebChat schreibgeschützt.
## Tools-Panel für Control-UI-Agents
## Tools-Bereich für Control-UI-Agenten
- Das Tools-Panel `/agents` der Control UI hat zwei separate Ansichten:
- **Derzeit verfügbar** verwendet `tools.effective(sessionKey=...)` und zeigt, was die aktuelle
Sitzung zur Laufzeit tatsächlich verwenden kann, einschließlich core-, Plugin- und kanaleigener Tools.
- Der Tools-Bereich der Control UI unter `/agents` hat zwei getrennte Ansichten:
- **Aktuell verfügbar** verwendet `tools.effective(sessionKey=...)` und zeigt, was die aktuelle
Sitzung zur Laufzeit tatsächlich verwenden kann, einschließlich Core-, Plugin- und kanalverwalteter Tools.
- **Tool-Konfiguration** verwendet `tools.catalog` und bleibt auf Profile, Überschreibungen und
Katalogsemantik fokussiert.
- Die Laufzeitverfügbarkeit ist sitzungsbezogen. Das Wechseln von Sitzungen auf demselben Agent kann die
Liste **Derzeit verfügbar** ändern.
- Der Konfigurationseditor impliziert keine Laufzeitverfügbarkeit; der effektive Zugriff folgt weiterhin der Richtlinienpriorität
(`allow`/`deny`, pro Agent und Provider-/Kanal-Überschreibungen).
- Laufzeitverfügbarkeit ist sitzungsbezogen. Der Wechsel zwischen Sitzungen desselben Agenten kann die Liste
**Aktuell verfügbar** ändern.
- Der Konfigurationseditor impliziert keine Laufzeitverfügbarkeit; effektiver Zugriff folgt weiterhin der Richtlinienpriorität
(`allow`/`deny`, Überschreibungen pro Agent sowie Provider-/Kanal-Overrides).
## Remote-Nutzung
@ -73,20 +74,20 @@ Vollständige Konfiguration: [Konfiguration](/de/gateway/configuration)
WebChat-Optionen:
- `gateway.webchat.chatHistoryMaxChars`: maximale Zeichenanzahl für Textfelder in `chat.history`-Antworten. Wenn ein Transkripteintrag dieses Limit überschreitet, kürzt das Gateway lange Textfelder und kann übergroße Nachrichten durch einen Platzhalter ersetzen. Pro Anfrage kann außerdem `maxChars` vom Client gesendet werden, um diesen Standardwert für einen einzelnen `chat.history`-Aufruf zu überschreiben.
- `gateway.webchat.chatHistoryMaxChars`: maximale Zeichenanzahl für Textfelder in `chat.history`-Antworten. Wenn ein Transkripteintrag diesen Grenzwert überschreitet, kürzt Gateway lange Textfelder und kann übergroße Nachrichten durch einen Platzhalter ersetzen. Der Client kann pro Anfrage auch `maxChars` senden, um diesen Standardwert für einen einzelnen `chat.history`-Aufruf zu überschreiben.
Zugehörige globale Optionen:
- `gateway.port`, `gateway.bind`: WebSocket-Host/-Port.
- `gateway.auth.mode`, `gateway.auth.token`, `gateway.auth.password`:
shared-secret-WebSocket-Authentifizierung.
- `gateway.auth.allowTailscale`: Der Chat-Tab der Browser-Control-UI kann bei Aktivierung Tailscale
Serve-Identitäts-Header verwenden.
- `gateway.auth.mode: "trusted-proxy"`: Reverse-Proxy-Authentifizierung für Browser-Clients hinter einer identitätsbewussten **Nicht-Loopback**-Proxyquelle (siehe [Trusted Proxy Auth](/de/gateway/trusted-proxy-auth)).
Shared-Secret-WebSocket-Authentifizierung.
- `gateway.auth.allowTailscale`: Der Chat-Tab der browserbasierten Control UI kann bei Aktivierung Tailscale-
Serve-Identitätsheader verwenden.
- `gateway.auth.mode: "trusted-proxy"`: Reverse-Proxy-Authentifizierung für Browser-Clients hinter einer identitätsbewussten **Nicht-Loopback**-Proxy-Quelle (siehe [Trusted Proxy Auth](/de/gateway/trusted-proxy-auth)).
- `gateway.remote.url`, `gateway.remote.token`, `gateway.remote.password`: Remote-Gateway-Ziel.
- `session.*`: Sitzungsspeicher und Standardwerte für den Hauptschlüssel.
- `session.*`: Sitzungsspeicher und Standardwerte für Hauptschlüssel.
## Verwandt
## Verwandte Themen
- [Control UI](/de/web/control-ui)
- [Dashboard](/de/web/dashboard)