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

chore(i18n): refresh de translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-30 18:42:12 +00:00
parent c1da93ad49
commit e5de2beed4
5 changed files with 707 additions and 737 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

312
docs/de/ci.md
View File

@ -2,74 +2,74 @@
read_when:
- Sie müssen nachvollziehen, warum ein CI-Job ausgeführt wurde oder nicht
- Sie untersuchen eine fehlgeschlagene GitHub Actions-Prüfung
- Sie koordinieren einen Release-Validierungslauf oder dessen erneute Ausführung
summary: CI-Jobgraph, Bereichsprüfungen, Release-Sammelprüfungen und lokale Befehlsäquivalente
- Sie koordinieren einen Release-Validierungslauf oder dessen Wiederholung
summary: CI-Jobgraph, Bereichs-Gates, Release-Dachbereiche und lokale Befehlsentsprechungen
title: CI-Pipeline
x-i18n:
generated_at: "2026-04-30T09:34:53Z"
generated_at: "2026-04-30T18:38:49Z"
model: gpt-5.5
provider: openai
source_hash: a9c18f0801864ca1030aac9ea81117b011bd7936388984a1809ce3ae6e906e62
source_hash: a24afc27606ac7f4e9ead89acdd319bffa23336610f8a6cd8b576ea1a5b233dd
source_path: ci.md
workflow: 16
---
OpenClaw CI läuft bei jedem Push auf `main` und bei jedem Pull Request. Der `preflight`-Job klassifiziert den Diff und deaktiviert teure Lanes, wenn sich nur nicht zusammenhängende Bereiche geändert haben. Manuelle `workflow_dispatch`-Läufe umgehen das 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. Release-exklusive Plugin-Abdeckung liegt im separaten [`Plugin-Prerelease`](#plugin-prerelease)-Workflow und läuft nur über [`Vollständige Release-Validierung`](#full-release-validation) oder einen expliziten manuellen Dispatch.
OpenClaw-CI läuft bei jedem Push nach `main` und bei jedem Pull Request. Der Job `preflight` klassifiziert den Diff und deaktiviert teure Lanes, wenn nur nicht zugehörige Bereiche geändert wurden. Manuelle `workflow_dispatch`-Läufe umgehen das intelligente Scoping absichtlich und fächern den vollständigen Graphen für Release Candidates und breite Validierung auf. Android-Lanes bleiben über `include_android` optional. Die reine Release-Abdeckung für Plugins befindet sich im separaten Workflow [`Plugin-Prerelease`](#plugin-prerelease) und läuft nur aus [`Vollständige Release-Validierung`](#full-release-validation) heraus oder durch einen expliziten manuellen Dispatch.
## Pipeline-Übersicht
## Pipeline-Überblick
| Job | Zweck | Wann er läuft |
| -------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------- |
| `preflight` | Erkennt reine Docs-Änderungen, geänderte Scopes, geänderte Extensions und erstellt das CI-Manifest | Immer bei Nicht-Draft-Pushes und PRs |
| `security-scm-fast` | Erkennung privater Schlüssel und Workflow-Audit über `zizmor` | Immer bei Nicht-Draft-Pushes und PRs |
| `security-dependency-audit` | Abhängigkeitsfreies Produktions-Lockfile-Audit gegen npm-Advisories | Immer bei Nicht-Draft-Pushes und PRs |
| `security-fast` | Erforderliches Aggregat für die schnellen Security-Jobs | Immer bei Nicht-Draft-Pushes und PRs |
| `check-dependencies` | Produktions-Knip-Durchlauf nur für Abhängigkeiten plus Guard für die Allowlist ungenutzter Dateien | Node-relevante Änderungen |
| `build-artifacts` | Erstellt `dist/`, Control UI, Built-Artifact-Prüfungen und wiederverwendbare Downstream-Artefakte | Node-relevante Änderungen |
| `checks-fast-core` | Schnelle Linux-Korrektheits-Lanes wie gebündelte/Plugin-Contract/Protocol-Prüfungen | Node-relevante Änderungen |
| `checks-fast-contracts-channels` | Gesplittete 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` | Gesplittetes Äquivalent zum wichtigsten lokalen Gate: Produktionstypen, Lint, Guards, Testtypen und strikter Smoke | Node-relevante Änderungen |
| `check-additional` | Architektur-, Boundary-, Extension-Surface-Guards, Package-Boundary- und Gateway-Watch-Shards | Node-relevante Änderungen |
| `build-smoke` | Built-CLI-Smoke-Tests und Startup-Memory-Smoke | Node-relevante Änderungen |
| `checks` | Verifier für Built-Artifact-Channel-Tests | Node-relevante Änderungen |
| `checks-node-compat-node22` | Node-22-Kompatibilitäts-Build und Smoke-Lane | Manueller CI-Dispatch für Releases |
| `check-docs` | Docs-Formatierung, Lint und Broken-Link-Prüfungen | Docs geändert |
| `skills-python` | Ruff + pytest für Python-gestützte Skills | Python-Skill-relevante Änderungen |
| `checks-windows` | Windows-spezifische Prozess-/Pfadtests plus Regressionen bei gemeinsamen Runtime-Import-Specifiers | Windows-relevante Änderungen |
| `macos-node` | macOS-TypeScript-Test-Lane mit den gemeinsamen Built Artifacts | macOS-relevante Änderungen |
| `macos-swift` | Swift-Lint, Build und Tests für die macOS-App | macOS-relevante Änderungen |
| `android` | Android-Unit-Tests für beide Flavors plus ein Debug-APK-Build | Android-relevante Änderungen |
| `test-performance-agent` | Tägliche Codex-Optimierung langsamer Tests nach vertrauenswürdiger Aktivität | Main-CI-Erfolg oder manueller Dispatch |
| Job | Zweck | Wann er läuft |
| -------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `preflight` | Erkennt reine Docs-Änderungen, geänderte Scopes, geänderte Plugins und erstellt das CI-Manifest | Immer bei Nicht-Draft-Pushes und PRs |
| `security-scm-fast` | Erkennung privater Schlüssel und Workflow-Audit über `zizmor` | Immer bei Nicht-Draft-Pushes und PRs |
| `security-dependency-audit` | Abhängigkeitsfreier Audit des Produktions-Lockfiles gegen npm-Advisories | Immer bei Nicht-Draft-Pushes und PRs |
| `security-fast` | Erforderliches Aggregat für die schnellen Security-Jobs | Immer bei Nicht-Draft-Pushes und PRs |
| `check-dependencies` | Produktions-Knip-Durchlauf nur für Abhängigkeiten plus Guard für die Allowlist ungenutzter Dateien | Node-relevante Änderungen |
| `build-artifacts` | Baut `dist/`, Control UI, Prüfungen gebauter Artefakte und wiederverwendbare Downstream-Artefakte | Node-relevante Änderungen |
| `checks-fast-core` | Schnelle Linux-Korrektheits-Lanes wie gebündelte/Plugin-Vertrags-/Protokollprüfungen | Node-relevante Änderungen |
| `checks-fast-contracts-channels` | Geshardete Channel-Vertragsprüfungen mit stabilem aggregiertem Prüfergebnis | Node-relevante Änderungen |
| `checks-node-core-test` | Core-Node-Test-Shards, ohne Channel-, gebündelte, Vertrags- und Plugin-Lanes | Node-relevante Änderungen |
| `check` | Gesplittetes Äquivalent des lokalen Haupt-Gates: Produktions-Typen, Lint, Guards, Testtypen und strikter Smoke-Test | Node-relevante Änderungen |
| `check-additional` | Architektur-, Boundary-, Plugin-Oberflächen-Guards, Package-Boundary- und Gateway-Watch-Shards | Node-relevante Änderungen |
| `build-smoke` | Smoke-Tests für die gebaute CLI und Startup-Memory-Smoke | Node-relevante Änderungen |
| `checks` | Verifier für gebaute Artefakt-Channel-Tests | Node-relevante Änderungen |
| `checks-node-compat-node22` | Node-22-Kompatibilitäts-Build und Smoke-Lane | Manueller CI-Dispatch für Releases |
| `check-docs` | Docs-Formatierung, Lint und Prüfungen auf defekte Links | Docs geändert |
| `skills-python` | Ruff + pytest für Python-gestützte Skills | Python-Skill-relevante Änderungen |
| `checks-windows` | Windows-spezifische Prozess-/Pfadtests plus Regressionen bei gemeinsamen Runtime-Import-Specifiern | Windows-relevante Änderungen |
| `macos-node` | macOS-TypeScript-Test-Lane mit den gemeinsamen 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 | Erfolgreiche Main-CI oder manueller Dispatch |
## Fail-Fast-Reihenfolge
## Reihenfolge für schnelles Fehlschlagen
1. `preflight` entscheidet, welche Lanes überhaupt existieren. Die Logik `docs-scope` und `changed-scope` sind Schritte innerhalb dieses Jobs, keine eigenständigen Jobs.
1. `preflight` entscheidet, welche Lanes überhaupt existieren. Die Logik für `docs-scope` und `changed-scope` sind Schritte innerhalb dieses Jobs, keine eigenständigen Jobs.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` und `skills-python` schlagen schnell fehl, ohne auf die schwereren Artefakt- und Plattform-Matrix-Jobs zu warten.
3. `build-artifacts` überschneidet sich mit den schnellen Linux-Lanes, damit Downstream-Consumer starten können, sobald der gemeinsame Build bereit ist.
4. Schwerere Plattform- und Runtime-Lanes fächern danach auf: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` und `android`.
3. `build-artifacts` überlappt mit den schnellen Linux-Lanes, damit Downstream-Konsumenten starten können, sobald der gemeinsame Build bereit ist.
4. Danach fächern schwerere Plattform- und Runtime-Lanes 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()`, sodass 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-*`), damit ein GitHub-seitiger Zombie in einer alten Queue-Gruppe neuere Main-Läufe nicht unbegrenzt blockieren kann. Manuelle Full-Suite-Läufe verwenden `CI-manual-v1-*` und brechen laufende Läufe nicht ab.
GitHub kann ersetzte Jobs als `cancelled` markieren, wenn ein neuerer Push auf demselben PR oder derselben `main`-Ref landet. Behandeln Sie das als CI-Rauschen, außer der neueste Lauf für dieselbe Ref schlägt ebenfalls fehl. Aggregierte Shard-Prüfungen verwenden `!cancelled() && always()`, sodass sie normale Shard-Fehler weiterhin melden, aber nicht mehr eingereiht werden, nachdem der gesamte Workflow bereits ersetzt wurde. Der automatische CI-Concurrency-Schlüssel ist versioniert (`CI-v7-*`), sodass ein GitHub-seitiger Zombie in einer alten Queue-Gruppe neuere Main-Läufe nicht unbegrenzt blockieren kann. Manuelle Full-Suite-Läufe verwenden `CI-manual-v1-*` und brechen laufende Läufe nicht ab.
## Scope und Routing
Die Scope-Logik liegt in `scripts/ci-changed-scope.mjs` und ist durch Unit-Tests in `src/scripts/ci-changed-scope.test.ts` abgedeckt. Manueller Dispatch überspringt die Changed-Scope-Erkennung und lässt das Preflight-Manifest so handeln, als hätte sich jeder gescopte Bereich geändert.
Die Scope-Logik befindet sich in `scripts/ci-changed-scope.mjs` und ist durch Unit-Tests in `src/scripts/ci-changed-scope.test.ts` abgedeckt. Manueller Dispatch überspringt die 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 für sich genommen keine nativen Windows-, Android- oder macOS-Builds; diese Plattform-Lanes bleiben auf Plattform-Quelländerungen beschränkt.
- **CI-Änderungen nur am Routing, ausgewählte günstige Core-Test-Fixture-Änderungen und enge Plugin-Contract-Helper-/Test-Routing-Änderungen** verwenden einen schnellen reinen Node-Manifest-Pfad: `preflight`, Security 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 Routing- oder Helper-Oberflächen begrenzt ist, die die schnelle Aufgabe direkt ausübt.
- **Windows-Node-Prüfungen** sind auf Windows-spezifische Prozess-/Pfad-Wrapper, npm/pnpm/UI-Runner-Helper, Package-Manager-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.
- **Reine CI-Routing-Änderungen, ausgewählte günstige Core-Test-Fixture-Änderungen und schmale Plugin-Vertrags-Helfer-/Test-Routing-Änderungen** verwenden einen schnellen reinen Node-Manifestpfad: `preflight`, Security und eine einzelne `checks-fast-core`-Aufgabe. Dieser Pfad überspringt Build-Artefakte, Node-22-Kompatibilität, Channel-Verträge, vollständige Core-Shards, Shards gebündelter Plugins und zusätzliche Guard-Matrizen, wenn die Änderung auf die Routing- oder Helferoberflächen begrenzt ist, die die schnelle Aufgabe direkt ausführt.
- **Windows-Node-Prüfungen** sind auf Windows-spezifische Prozess-/Pfad-Wrapper, npm-/pnpm-/UI-Runner-Helfer, Paketmanager-Konfiguration und die CI-Workflow-Oberflä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.
Die langsamsten Node-Testfamilien sind aufgeteilt oder ausbalanciert, damit jeder Job klein bleibt, ohne Runner zu stark 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-Subtree in Agent-Runner-, Dispatch- und Commands/State-Routing-Shards aufgeteilt ist), und agentische Gateway-/Plugin-Konfigurationen werden auf die vorhandenen source-only-agentic-Node-Jobs verteilt, statt auf Built Artifacts zu warten. Breite Browser-, QA-, Media- und sonstige Plugin-Tests verwenden ihre dedizierten Vitest-Konfigurationen statt des gemeinsamen Plugin-Catch-Alls. Include-Pattern-Shards zeichnen Timing-Einträge mit dem CI-Shard-Namen auf, sodass `.artifacts/vitest-shard-timings.json` eine gesamte 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 gleichzeitig aus. Gateway Watch, Channel-Tests und der Core-Support-Boundary-Shard laufen innerhalb von `build-artifacts` gleichzeitig, nachdem `dist/` und `dist-runtime/` bereits gebaut wurden.
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 Shards für Agent-Runner, Dispatch und Commands/State-Routing aufgeteilt ist), und agentische Gateway-/Plugin-Konfigurationen werden auf die vorhandenen reinen Source-agentischen Node-Jobs verteilt, statt auf gebaute Artefakte zu warten. Breite Browser-, QA-, Medien- und sonstige Plugin-Tests verwenden ihre eigenen 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-Topologie-Architektur von Gateway-Watch-Abdeckung; der Boundary-Guard-Shard führt seine kleinen unabhängigen Guards innerhalb eines Jobs parallel aus. Gateway-Watch-, Channel-Tests und der Core-Support-Boundary-Shard laufen innerhalb von `build-artifacts` 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. Der Third-Party-Flavor hat kein separates Source Set und kein separates Manifest; seine Unit-Test-Lane kompiliert den Flavor trotzdem mit den SMS-/Call-Log-BuildConfig-Flags, während ein doppelter Debug-APK-Packaging-Job bei jedem Android-relevanten Push vermieden wird.
Android-CI führt sowohl `testPlayDebugUnitTest` als auch `testThirdPartyDebugUnitTest` aus und baut danach das Play-Debug-APK. Die Drittanbieter-Variante hat kein separates Source Set oder Manifest; ihre Unit-Test-Lane kompiliert die Variante weiterhin mit den SMS-/Call-Log-BuildConfig-Flags, vermeidet aber einen doppelten Debug-APK-Packaging-Job bei jedem Android-relevanten Push.
Der `check-dependencies`-Shard führt `pnpm deadcode:dependencies` (einen Produktions-Knip-Durchlauf nur für Abhängigkeiten, der auf die neueste Knip-Version gepinnt ist, 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 zurücklässt, während beabsichtigte dynamische Plugin-, generierte, Build-, Live-Test- und Package-Bridge-Oberflä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 Abhängigkeiten, gepinnt auf die neueste Knip-Version, wobei pnpm's Mindestveröffentlichungsalter 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 zurücklässt, während absichtliche dynamische Plugin-, generierte, Build-, Live-Test- und Package-Bridge-Oberflächen erhalten bleiben, die Knip nicht statisch auflösen kann.
## Manuelle Dispatches
Manuelle CI-Dispatches führen denselben Job-Graphen wie normale CI aus, erzwingen aber jede gescopte Nicht-Android-Lane: Linux-Node-Shards, Bundled-Plugin-Shards, Channel Contracts, Node-22-Kompatibilität, `check`, `check-additional`, Build Smoke, Docs-Prüfungen, Python-Skills, Windows, macOS und Control-UI-i18n. Eigenständige manuelle CI-Dispatches führen Android nur mit `include_android=true` aus; das vollständige Release-Umbrella aktiviert Android durch Übergabe von `include_android=true`. Statische Plugin-Prerelease-Prüfungen, der release-exklusive `agentic-plugins`-Shard, der vollständige Extension-Batch-Sweep und Plugin-Prerelease-Docker-Lanes sind von 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.
Manuell ausgelöste CI-Läufe führen denselben Job-Graphen wie normale CI aus, erzwingen aber jede nicht-Android-gescopte Lane: Linux-Node-Shards, gebündelte Plugin-Shards, Channel-Verträge, Node-22-Kompatibilität, `check`, `check-additional`, Build-Smoke, Docs-Prüfungen, Python-Skills, Windows, macOS und Control-UI-i18n. Eigenständige manuell ausgelöste CI-Läufe führen Android nur mit `include_android=true` aus; der vollständige Release-Umbrella aktiviert Android, indem er `include_android=true` übergibt. Statische Plugin-Prerelease-Prüfungen, der reine Release-Shard `agentic-plugins`, der vollständige Batch-Sweep der Plugins und Plugin-Prerelease-Docker-Lanes sind von CI ausgeschlossen. Die Docker-Prerelease-Suite läuft nur, wenn `Full Release Validation` den separaten Workflow `Plugin Prerelease` mit aktiviertem Release-Validation-Gate dispatcht.
Manuelle Läufe verwenden eine eindeutige Concurrency-Gruppe, damit eine Release-Candidate-Full-Suite nicht durch einen anderen Push- oder PR-Lauf auf demselben Ref abgebrochen wird. Die optionale Eingabe `target_ref` ermöglicht es einem vertrauenswürdigen Aufrufer, diesen Graphen gegen einen Branch, Tag oder vollständigen Commit-SHA auszuführen und dabei die Workflow-Datei aus dem ausgewählten Dispatch-Ref zu verwenden.
Manuelle Läufe verwenden eine eindeutige Concurrency-Gruppe, 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
@ -79,15 +79,15 @@ gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
## Runner
| Runner | Jobs |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ubuntu-24.04` | `preflight`, schnelle Sicherheits-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, Docs-Prüfungen, Python-Skills, Workflow-Sanity, Labeler, Auto-Response; install-smoke-Preflight nutzt ebenfalls GitHub-gehostetes Ubuntu, damit die Blacksmith-Matrix früher eingereiht werden kann |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, kleinere Plugin-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-empfindlich genug, dass 8 vCPU mehr kosteten, als sie einsparten); install-smoke-Docker-Builds (32-vCPU-Wartezeit 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 Sicherheits-Jobs und Aggregate (`security-scm-fast`, `security-dependency-audit`, `security-fast`), schnelle Protokoll-/Contract-/gebündelte Prüfungen, aufgeteilte 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; die Install-Smoke-Preflight verwendet ebenfalls von GitHub gehostetes Ubuntu, damit die Blacksmith-Matrix früher in die Warteschlange eingereiht werden kann |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, leichtere Plugin-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 vCPUs mehr kosteten, als sie einsparten); Docker-Builds für Install-Smoke (die Wartezeit in der 32-vCPU-Warteschlange 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 |
## Lokale Entsprechungen
@ -117,23 +117,23 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac
## Vollständige Release-Validierung
`Full Release Validation` ist der manuelle Dach-Workflow für „alles vor dem Release ausführen“. Er akzeptiert einen Branch, Tag oder vollständigen Commit-SHA, startet den manuellen `CI`-Workflow mit diesem Ziel, startet `Plugin Prerelease` für release-spezifische Plugin-/Package-/Static-/Docker-Nachweise und startet `OpenClaw Release Checks` für Install-Smoke, Package Acceptance, Docker-Release-Pfad-Suites, Live/E2E, OpenWebUI, QA-Lab-Parität, Matrix und Telegram-Lanes. Er kann außerdem den Post-Publish-Workflow `NPM Telegram Beta E2E` ausführen, wenn eine veröffentlichte Package-Spezifikation angegeben wird.
`Full Release Validation` ist der manuelle Umbrella-Workflow für „alles vor dem Release ausführen“. Er akzeptiert einen Branch, ein Tag oder einen vollständigen Commit-SHA, startet den manuellen `CI`-Workflow mit diesem Ziel, startet `Plugin Prerelease` für Release-spezifische Plugin-/Paket-/statische/Docker-Nachweise und startet `OpenClaw Release Checks` für Install-Smoke, Paketakzeptanz, Docker-Release-Pfad-Suiten, Live/E2E, OpenWebUI, QA-Lab-Parität, Matrix- und Telegram-Lanes. Er kann außerdem den Post-Publish-Workflow `NPM Telegram Beta E2E` ausführen, wenn eine veröffentlichte Paketspezifikation angegeben wird.
`release_profile` steuert die Live-/Provider-Breite, die an Release-Prüfungen übergeben wird:
- `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.
Der Dach-Workflow zeichnet die gestarteten Child-Run-IDs auf, und der abschließende Job `Verify full validation` prüft die aktuellen Child-Run-Ergebnisse erneut und hängt Tabellen mit den langsamsten Jobs für jeden Child-Run an. Wenn ein Child-Workflow erneut ausgeführt wird und grün wird, führen Sie nur den Parent-Verifiziererjob erneut aus, um das Ergebnis und die Timing-Zusammenfassung des Dach-Workflows zu aktualisieren.
Der Umbrella zeichnet die gestarteten untergeordneten Run-IDs auf, und der abschließende Job `Verify full validation` prüft die aktuellen Ergebnisse der untergeordneten Runs erneut und hängt Tabellen mit den langsamsten Jobs für jeden untergeordneten Run an. Wenn ein untergeordneter Workflow erneut ausgeführt wird und grün wird, führen Sie nur den übergeordneten Verifizierer-Job erneut aus, um das Umbrella-Ergebnis und die Timing-Zusammenfassung zu aktualisieren.
Für die Wiederherstellung akzeptieren sowohl `Full Release Validation` als auch `OpenClaw Release Checks` `rerun_group`. Verwenden Sie `all` für einen Release-Kandidaten, `ci` nur für das normale vollständige CI-Child, `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 Dach-Workflow. So bleibt die erneute Ausführung einer fehlgeschlagenen Release-Box nach einem gezielten Fix begrenzt.
Für die Wiederherstellung akzeptieren sowohl `Full Release Validation` als auch `OpenClaw Release Checks` `rerun_group`. Verwenden Sie `all` für einen Release-Kandidaten, `ci` nur für das normale vollständige untergeordnete CI, `release-checks` für jedes untergeordnete Release oder eine engere Gruppe: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` oder `npm-telegram` im Umbrella. Dadurch bleibt ein erneuter Lauf einer fehlgeschlagenen Release-Box nach einer gezielten Korrektur begrenzt.
`OpenClaw Release Checks` verwendet die vertrauenswürdige Workflow-Referenz, um die ausgewählte Referenz einmal in ein `release-package-under-test`-Tarball aufzulösen, und übergibt dieses Artefakt dann sowohl an den 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 das erneute Packen desselben Kandidaten in mehreren Child-Jobs wird vermieden.
`OpenClaw Release Checks` verwendet die vertrauenswürdige Workflow-Ref, um die ausgewählte Ref einmal in einen `release-package-under-test`-Tarball aufzulösen, und übergibt dieses Artefakt dann sowohl an den Docker-Workflow für den Live/E2E-Release-Pfad als auch an den Paketakzeptanz-Shard. Dadurch bleiben die Paket-Bytes über Release-Boxen hinweg konsistent und es wird vermieden, denselben Kandidaten in mehreren untergeordneten Jobs erneut zu packen.
## Live- und E2E-Shards
Das Release-Live/E2E-Child behält eine breite native `pnpm test:live`-Abdeckung bei, führt sie jedoch als benannte Shards über `scripts/test-live-shard.mjs` statt als einen seriellen Job aus:
Das untergeordnete Release-Live/E2E behält eine breite native `pnpm test:live`-Abdeckung bei, führt sie jedoch als benannte Shards über `scripts/test-live-shard.mjs` statt als einen seriellen Job aus:
- `native-live-src-agents`
- `native-live-src-gateway-core`
@ -145,57 +145,57 @@ Das Release-Live/E2E-Child behält eine breite native `pnpm test:live`-Abdeckung
- `native-live-extensions-openai`
- `native-live-extensions-o-z-other`
- `native-live-extensions-xai`
- aufgeteilte Audio-/Video-Medien-Shards und Provider-gefilterte Musik-Shards
- aufgeteilte Medien-Audio-/Video-Shards und Provider-gefilterte Musik-Shards
Das behält dieselbe Dateiabdeckung bei und macht langsame Live-Provider-Fehler zugleich 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 Wiederholungen gültig.
Dadurch bleibt dieselbe Dateiabdeckung erhalten, während langsame Live-Provider-Fehler leichter erneut ausgeführt und diagnostiziert werden können. Die aggregierten Shard-Namen `native-live-extensions-o-z`, `native-live-extensions-media` und `native-live-extensions-media-music` bleiben für manuelle einmalige erneute Läufe gültig.
Die nativen Live-Medien-Shards laufen in `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, gebaut vom Workflow `Live Media Runner Image`. Dieses Image installiert `ffmpeg` und `ffprobe` vor; Medien-Jobs verifizieren vor der Einrichtung nur die Binaries. Belassen Sie Docker-gestützte Live-Suites auf normalen Blacksmith-Runnern - Container-Jobs sind der falsche Ort, um verschachtelte Docker-Tests zu starten.
Die nativen Live-Medien-Shards laufen in `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, das vom Workflow `Live Media Runner Image` gebaut wird. Dieses Image installiert `ffmpeg` und `ffprobe` vor; Medien-Jobs verifizieren die Binärdateien nur vor dem Setup. Belassen Sie Docker-gestützte Live-Suiten auf normalen Blacksmith-Runnern, da Container-Jobs der falsche Ort sind, 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, danach laufen die Docker-Live-Modell-, Gateway-, CLI-Backend-, ACP-Bind- und Codex-Harness-Shards mit `OPENCLAW_SKIP_DOCKER_BUILD=1`. Wenn diese Shards das vollständige Source-Docker-Ziel unabhängig neu bauen, ist der Release-Run falsch konfiguriert und verschwendet Laufzeit für doppelte 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-, Gateway-, CLI-Backend-, ACP-Bind- und Codex-Harness-Shards mit `OPENCLAW_SKIP_DOCKER_BUILD=1`. Wenn diese Shards das vollständige Source-Docker-Ziel unabhängig neu bauen, ist der Release-Run falsch konfiguriert und verschwendet Laufzeit für doppelte Image-Builds.
## Package Acceptance
## Paketakzeptanz
Verwenden Sie `Package Acceptance`, wenn die Frage lautet: „Funktioniert dieses installierbare OpenClaw-Package als Produkt?“ Es unterscheidet sich von normalem CI: Normales 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?“ Sie unterscheidet sich von normaler CI: Normale CI validiert den Quellbaum, während die Paketakzeptanz einen einzelnen Tarball über denselben Docker-E2E-Harness validiert, den Benutzer nach Installation oder Update ausführen.
### Jobs
1. `resolve_package` checkt `workflow_ref` aus, löst einen Package-Kandidaten auf, schreibt `.artifacts/docker-e2e-package/openclaw-current.tgz`, schreibt `.artifacts/docker-e2e-package/package-candidate.json`, lädt beide als Artefakt `package-under-test` hoch und gibt Quelle, Workflow-Referenz, Package-Referenz, Version, SHA-256 und Profil in der GitHub-Schrittzusammenfassung 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 verteilt diese Lanes dann als parallele gezielte Docker-Jobs mit eindeutigen Artefakten.
3. `package_telegram` ruft optional `NPM Telegram Beta E2E` auf. Es läuft, wenn `telegram_mode` nicht `none` ist, und installiert dasselbe `package-under-test`-Artefakt, wenn Package Acceptance eines aufgelöst hat; ein eigenständiger Telegram-Dispatch kann weiterhin eine veröffentlichte npm-Spezifikation installieren.
4. `summary` lässt den Workflow fehlschlagen, wenn Package-Auflösung, Docker Acceptance oder die optionale Telegram-Lane fehlgeschlagen ist.
1. `resolve_package` checkt `workflow_ref` aus, löst einen Paketkandidaten auf, schreibt `.artifacts/docker-e2e-package/openclaw-current.tgz`, schreibt `.artifacts/docker-e2e-package/package-candidate.json`, lädt beide als Artefakt `package-under-test` hoch und gibt Quelle, Workflow-Ref, Paket-Ref, Version, SHA-256 und Profil in der GitHub-Schrittzusammenfassung 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 den Tarball-Bestand, bereitet bei Bedarf Package-Digest-Docker-Images vor und führt die ausgewählten Docker-Lanes gegen dieses Paket aus, statt den Workflow-Checkout zu packen. Wenn ein Profil mehrere gezielte `docker_lanes` auswählt, bereitet der wiederverwendbare Workflow das Paket und die gemeinsamen Images einmal vor und fächert diese Lanes dann als parallele gezielte Docker-Jobs mit eindeutigen Artefakten auf.
3. `package_telegram` ruft optional `NPM Telegram Beta E2E` auf. Es läuft, wenn `telegram_mode` nicht `none` ist, und installiert dasselbe Artefakt `package-under-test`, wenn Package Acceptance eines aufgelöst hat; ein eigenständiger Telegram-Dispatch kann weiterhin eine veröffentlichte npm-Spezifikation installieren.
4. `summary` lässt den Workflow fehlschlagen, wenn die Paketauflösung, Docker-Akzeptanz oder die optionale Telegram-Lane fehlgeschlagen ist.
### Kandidatenquellen
- `source=npm` akzeptiert nur `openclaw@beta`, `openclaw@latest` oder eine exakte OpenClaw-Release-Version wie `openclaw@2026.4.27-beta.2`. Verwenden Sie dies für die Abnahme veröffentlichter Beta-/Stable-Versionen.
- `source=ref` packt einen vertrauenswürdigen `package_ref`-Branch, Tag oder vollständigen Commit-SHA. Der Resolver ruft OpenClaw-Branches/-Tags ab, verifiziert, dass der ausgewählte Commit aus der Repository-Branch-Historie oder einem Release-Tag erreichbar ist, installiert Abhängigkeiten in einem losgelösten Worktree und packt ihn mit `scripts/package-openclaw-for-docker.mjs`.
- `source=url` lädt eine HTTPS-`.tgz` herunter; `package_sha256` ist erforderlich.
- `source=artifact` lädt eine `.tgz` aus `artifact_run_id` und `artifact_name` herunter; `package_sha256` ist optional, sollte aber für extern freigegebene Artefakte angegeben werden.
- `source=ref` paketiert einen vertrauenswürdigen `package_ref`-Branch, ein Tag oder einen vollständigen Commit-SHA. Der Resolver ruft OpenClaw-Branches/-Tags ab, prüft, ob der ausgewählte Commit über die Branch-Historie des Repositorys oder ein Release-Tag erreichbar ist, installiert Abhängigkeiten in einem losgelösten Worktree und paketiert 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 Quell-Commit, der paketiert wird, wenn `source=ref` ist. Dadurch kann der aktuelle Test-Harness ältere vertrauenswürdige Quell-Commits validieren, ohne alte Workflow-Logik auszuführen.
### Suite-Profile
- `smoke` — `npm-onboard-channel-agent`, `gateway-network`, `config-reload`
- `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `bundled-channel-deps-compat`, `plugins-offline`, `plugin-update`
- `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `upgrade-survivor`, `bundled-channel-deps-compat`, `plugins-offline`, `plugin-update`
- `product` — `package` plus `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui`
- `full` — vollständige Docker-Release-Pfad-Chunks mit OpenWebUI
- `custom` — exakte `docker_lanes`; erforderlich, wenn `suite_profile=custom`
Das `package`-Profil verwendet Offline-Plugin-Abdeckung, sodass die Validierung veröffentlichter Pakete nicht von der Live-Verfügbarkeit von ClawHub abhängt. Die optionale Telegram-Lane verwendet das `package-under-test`-Artefakt in `NPM Telegram Beta E2E` wieder, wobei der veröffentlichte npm-Spec-Pfad für eigenständige Dispatches beibehalten wird.
Das Profil `package` verwendet Offline-Plugin-Abdeckung, damit die Validierung veröffentlichter Pakete nicht von der Live-Verfügbarkeit von ClawHub abhängt. Die optionale Telegram-Lane verwendet das Artefakt `package-under-test` in `NPM Telegram Beta E2E` wieder, wobei der veröffentlichte npm-Spezifikationspfad für eigenständige Dispatches erhalten bleibt.
Release-Prüfungen rufen Package Acceptance mit `source=ref`, `package_ref=<release-ref>`, `workflow_ref=<release workflow ref>`, `suite_profile=custom`, `docker_lanes='bundled-channel-deps-compat plugins-offline'` und `telegram_mode=mock-openai` auf. Release-Pfad-Docker-Chunks decken die überlappenden Paket-/Update-/Plugin-Lanes ab; Package Acceptance behält den artefaktnativen Nachweis für bundled-channel-Kompatibilität, Offline-Plugin und Telegram gegen denselben aufgelösten Paket-Tarball bei. Plattformübergreifende Release-Prüfungen decken weiterhin OS-spezifisches Onboarding, Installer- und Plattformverhalten ab; Paket-/Update-Produktvalidierung sollte mit Package Acceptance beginnen. Die Windows-Packaged- und Installer-Fresh-Lanes verifizieren außerdem, dass ein installiertes Paket ein 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-mini`, sodass der Installations- und Gateway-Nachweis schnell und deterministisch bleibt.
Release-Prüfungen rufen Package Acceptance mit `source=ref`, `package_ref=<release-ref>`, `workflow_ref=<release workflow ref>`, `suite_profile=custom`, `docker_lanes='bundled-channel-deps-compat plugins-offline'` und `telegram_mode=mock-openai` auf. Docker-Chunks des Release-Pfads decken die überlappenden Paket-/Update-/Plugin-Lanes ab; Package Acceptance behält den artefaktnativen Kompatibilitätsnachweis für gebündelte Channels, den Offline-Plugin-Nachweis und den Telegram-Nachweis gegen denselben aufgelösten Paket-Tarball bei. Cross-OS-Release-Prüfungen decken weiterhin OS-spezifisches Onboarding-, Installer- und Plattformverhalten ab; die Produktvalidierung für Paket/Update sollte mit Package Acceptance beginnen. Die Windows-Lanes für paketierte und frische Installer-Installationen prüfen außerdem, dass ein installiertes Paket ein 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-mini`, damit der Installations- und Gateway-Nachweis schnell und deterministisch bleibt.
### Zeitfenster für Legacy-Kompatibilität
### Legacy-Kompatibilitätsfenster
Package Acceptance hat begrenzte Zeitfenster für Legacy-Kompatibilität für bereits veröffentlichte Pakete. Pakete bis einschließlich `2026.4.25`, einschließlich `2026.4.25-beta.*`, können den Kompatibilitätspfad verwenden:
Package Acceptance hat begrenzte Legacy-Kompatibilitätsfenster für bereits veröffentlichte Pakete. Pakete bis einschließlich `2026.4.25`, einschließlich `2026.4.25-beta.*`, dürfen den Kompatibilitätspfad verwenden:
- bekannte private QA-Einträge in `dist/postinstall-inventory.json` können auf Dateien verweisen, die im Tarball fehlen;
- `doctor-switch` kann den Persistenz-Subfall `gateway install --wrapper` überspringen, wenn das Paket dieses Flag nicht verfügbar macht;
- `update-channel-switch` kann fehlende `pnpm.patchedDependencies` aus dem aus dem Tarball abgeleiteten Fake-Git-Fixture entfernen und fehlendes persistiertes `update.channel` protokollieren;
- Plugin-Smokes können Legacy-Install-Record-Speicherorte lesen oder fehlende Marketplace-Install-Record-Persistenz akzeptieren;
- `plugin-update` kann die Migration von Konfigurationsmetadaten zulassen, während weiterhin verlangt wird, dass Install-Record- und No-Reinstall-Verhalten unverändert bleiben.
- bekannte private QA-Einträge in `dist/postinstall-inventory.json` dürfen auf Dateien verweisen, die im Tarball ausgelassen wurden;
- `doctor-switch` darf den Persistenz-Unterfall `gateway install --wrapper` überspringen, wenn das Paket dieses Flag nicht bereitstellt;
- `update-channel-switch` darf fehlende `pnpm.patchedDependencies` aus der vom Tarball abgeleiteten gefälschten Git-Fixture entfernen und fehlendes persistiertes `update.channel` protokollieren;
- Plugin-Smokes dürfen Legacy-Speicherorte für Installationsdatensätze lesen oder fehlende Marketplace-Persistenz von Installationsdatensätzen akzeptieren;
- `plugin-update` darf die Migration von Konfigurationsmetadaten erlauben, während weiterhin erforderlich bleibt, dass Installationsdatensatz und Verhalten ohne Neuinstallation unverändert bleiben.
Das veröffentlichte Paket `2026.4.26` kann außerdem Warnungen für lokale Build-Metadaten-Stamp-Dateien ausgeben, die bereits ausgeliefert wurden. Spätere Pakete müssen die modernen Verträge erfüllen; dieselben Bedingungen führen dann zu Fehlern statt zu Warnungen oder Überspringen.
Das veröffentlichte Paket `2026.4.26` darf außerdem vor lokal ausgelieferten Build-Metadaten-Stempeldateien warnen. Spätere Pakete müssen die modernen Verträge erfüllen; dieselben Bedingungen schlagen dann fehl, anstatt zu warnen oder übersprungen zu werden.
### Beispiele
@ -238,47 +238,47 @@ gh workflow run package-acceptance.yml \
-f docker_lanes='install-e2e plugin-update'
```
Wenn Sie einen fehlgeschlagenen Package-Acceptance-Lauf debuggen, beginnen Sie bei der Zusammenfassung `resolve_package`, um Paketquelle, Version und SHA-256 zu bestätigen. Prüfen Sie anschließend den untergeordneten Lauf `docker_acceptance` und seine Docker-Artefakte: `.artifacts/docker-tests/**/summary.json`, `failures.json`, Lane-Logs, Phasen-Timings und Rerun-Befehle. Führen Sie bevorzugt das fehlgeschlagene Paketprofil oder die exakten Docker-Lanes erneut aus, statt die vollständige Release-Validierung erneut auszuführen.
Beginnen Sie beim Debuggen eines fehlgeschlagenen Package-Acceptance-Laufs mit der Zusammenfassung `resolve_package`, um Paketquelle, Version und SHA-256 zu bestätigen. Prüfen Sie anschließend den untergeordneten Lauf `docker_acceptance` und seine Docker-Artefakte: `.artifacts/docker-tests/**/summary.json`, `failures.json`, Lane-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 auszuführen.
## Install-Smoke
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.
- **Schneller Pfad** läuft für Pull Requests, die Docker-/Paketoberflächen, Änderungen an gebündelten Plugin-Paketen/-Manifesten oder Core-Plugin-/Channel-/Gateway-/Plugin-SDK-Oberflächen betreffen, die von den Docker-Smoke-Jobs ausgeübt werden. Reine Source-Änderungen an gebündelten Plugins, reine Test-Änderungen und reine Docs-Änderungen reservieren keine Docker-Worker. Der schnelle Pfad baut das Root-Dockerfile-Image einmal, prüft die CLI, führt den Shared-Workspace-CLI-Smoke zum Löschen von Agenten aus, führt das Container-`gateway-network`-E2E aus, verifiziert ein Build-Argument für eine gebündelte Erweiterung 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 und Installer-Docker-/Update-Abdeckung für nächtliche geplante Läufe, manuelle Dispatches, Workflow-Call-Release-Prüfungen und Pull Requests bei, die tatsächlich Installer-/Paket-/Docker-Oberflächen berühren. Im vollständigen Modus bereitet install-smoke ein GHCR-Root-Dockerfile-Smoke-Image für den 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 zentrale Plugin-/Channel-/Gateway-/Plugin-SDK-Oberflächen berühren, die von den Docker-Smoke-Jobs ausgeübt 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 zum Löschen von Agents in einem geteilten Workspace aus, führt das Container-`gateway-network`-E2E aus, verifiziert ein Build-Argument für gebündelte Erweiterungen und führt das begrenzte Docker-Profil für gebündelte Plugins unter einem aggregierten Befehls-Timeout von 240 Sekunden aus, wobei jeder Docker-Lauf eines Szenarios separat begrenzt ist.
- **Vollständiger Pfad** behält QR-Paketinstallation und Installer-Docker-/Update-Abdeckung für nächtlich geplante Läufe, manuelle Dispatches, Release-Prüfungen per Workflow-Aufruf und Pull Requests bei, die wirklich Installer-/Paket-/Docker-Oberflächen berühren. Im vollständigen Modus bereitet Install-Smoke ein GHCR-Root-Dockerfile-Smoke-Image für den Ziel-SHA vor oder verwendet es wieder und führt anschließend QR-Paketinstallation, Root-Dockerfile-/Gateway-Smokes, Installer-/Update-Smokes und das schnelle Docker-E2E für gebündelte Plugins 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 bei und überlässt den vollständigen Install-Smoke der nächtlichen oder Release-Validierung.
`main`-Pushes, einschließlich Merge-Commits, erzwingen nicht den vollständigen Pfad; wenn die Changed-Scope-Logik bei einem Push vollständige Abdeckung anfordern würde, behält der Workflow den schnellen Docker-Smoke bei und überlässt den vollständigen Install-Smoke der nächtlichen oder Release-Validierung.
Der langsame Bun-Global-Install-Image-Provider-Smoke 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, aber Pull Requests und `main`-Pushes tun dies nicht. QR- und Installer-Docker-Tests behalten ihre eigenen installationsorientierten Dockerfiles.
Der langsame Bun-Global-Install-Image-Provider-Smoke 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 aktivieren, Pull Requests und `main`-Pushes jedoch nicht. QR- und Installer-Docker-Tests behalten ihre eigenen installationsfokussierten Dockerfiles.
## Lokales Docker-E2E
`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:
`pnpm test:docker:all` baut ein gemeinsames Live-Test-Image vor, paketiert 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 funktionales Image, das denselben Tarball für normale Funktions-Lanes in `/app` installiert.
- einen schlanken 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.
Docker-Lane-Definitionen befinden sich in `scripts/lib/docker-e2e-scenarios.mjs`, Planner-Logik befindet sich in `scripts/lib/docker-e2e-plan.mjs`, und der Runner führt nur den ausgewählten Plan aus. Der Scheduler wählt das Image pro Lane mit `OPENCLAW_DOCKER_E2E_BARE_IMAGE` und `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` aus und führt dann Lanes mit `OPENCLAW_SKIP_DOCKER_BUILD=1` aus.
Docker-Lane-Definitionen befinden sich in `scripts/lib/docker-e2e-scenarios.mjs`, die Planner-Logik befindet sich in `scripts/lib/docker-e2e-plan.mjs`, und der Runner führt nur den ausgewählten Plan aus. Der Scheduler wählt das Image pro Lane mit `OPENCLAW_DOCKER_E2E_BARE_IMAGE` und `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` aus und führt Lanes dann mit `OPENCLAW_SKIP_DOCKER_BUILD=1` aus.
### Einstellbare Parameter
| Variable | Standard | Zweck |
| -------------------------------------- | -------- | --------------------------------------------------------------------------------------------- |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Slot-Anzahl des Haupt-Pools für normale Lanes. |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Slot-Anzahl des Haupt-Pools für normale Lanes. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Slot-Anzahl des Provider-sensitiven Tail-Pools. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Obergrenze für gleichzeitige Live-Lanes, damit Provider nicht drosseln. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Obergrenze für gleichzeitige npm-Installations-Lanes. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Obergrenze für gleichzeitige npm-Installations-Lanes. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Obergrenze 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; setzen Sie `0` für keinen Versatz. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Staffelung zwischen Lane-Starts, um Docker-Daemon-Erstellungsstürme zu vermeiden; 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 | Kommagetrennte exakte Lane-Liste; überspringt Cleanup-Smoke, damit Agenten eine fehlgeschlagene Lane reproduzieren können. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | Kommagetrennte exakte Lane-Liste; überspringt Cleanup-Smoke, damit Agents eine fehlgeschlagene Lane reproduzieren können. |
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 aggregierte Ausführung führt Docker-Preflights aus, entfernt veraltete OpenClaw-E2E-Container, gibt den Active-Lane-Status aus, persistiert Lane-Timings für Longest-First-Reihenfolge und stoppt standardmäßig nach dem ersten Fehler die Planung neuer gepoolter Lanes.
Eine Lane, die schwerer ist als ihre effektive Grenze, kann trotzdem aus einem leeren Pool starten und läuft dann allein, bis sie Kapazität freigibt. Das lokale Aggregat prüft Docker vorab, entfernt veraltete OpenClaw-E2E-Container, gibt den Status aktiver Lanes aus, persistiert Lane-Timings für eine längste-zuerst-Reihenfolge und plant standardmäßig nach dem ersten Fehler keine neuen gepoolten Lanes mehr ein.
### Wiederverwendbarer Live-/E2E-Workflow
Der wiederverwendbare Live-/E2E-Workflow fragt `scripts/test-docker-all.mjs --plan-json`, welche Paket-, Image-Art, Live-Image-, Lane- und Credential-Abdeckung erforderlich ist. `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 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 Lanes mit installiertem Paket 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, sodass 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 mit `scripts/test-docker-all.mjs --plan-json` ab, welche Paket-, Image-Art-, Live-Image-, Lane- und Anmeldedatenabdeckung erforderlich ist. `scripts/docker-e2e.mjs` wandelt diesen Plan anschließend in GitHub-Ausgaben und Zusammenfassungen um. Er paketiert OpenClaw entweder über `scripts/package-openclaw-for-docker.mjs`, lädt ein Paketartefakt aus dem aktuellen Lauf herunter oder lädt ein Paketartefakt aus `package_artifact_run_id`; validiert das Tarball-Inventar; baut und pusht paket-digest-getaggte Bare-/Functional-GHCR-Docker-E2E-Images über Blacksmiths Docker-Layer-Cache, wenn der Plan Lanes mit installiertem Paket benötigt; und verwendet bereitgestellte Eingaben `docker_e2e_bare_image`/`docker_e2e_functional_image` oder vorhandene Paket-Digest-Images wieder, anstatt neu zu bauen. Docker-Image-Pulls werden mit einem begrenzten Timeout von 180 Sekunden pro Versuch wiederholt, sodass ein festhängender Registry-/Cache-Stream schnell erneut versucht wird, statt den Großteil des kritischen CI-Pfads zu verbrauchen.
### Release-Pfad-Chunks
@ -287,103 +287,103 @@ Release-Docker-Abdeckung läuft in kleineren gechunkten Jobs mit `OPENCLAW_SKIP_
- `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 | bundled-channels`
Aktuelle Release-Docker-Chunks sind `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, `plugins-runtime-install-a` bis `plugins-runtime-install-h`, `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-discord`, `bundled-channels-update-b` und `bundled-channels-contracts`. Der aggregierte Chunk `bundled-channels` bleibt für manuelle einmalige Neuausführungen verfügbar, und `plugins-runtime-core`, `plugins-runtime` sowie `plugins-integrations` bleiben aggregierte Plugin-/Runtime-Aliasse. Der Lane-Alias `install-e2e` bleibt der aggregierte manuelle Neuausführungsalias für beide Provider-Installer-Lanes. Der Chunk `bundled-channels` führt aufgeteilte Lanes `bundled-channel-*` und `bundled-channel-update-*` aus, nicht die serielle All-in-one-Lane `bundled-channel-deps`.
Aktuelle Release-Docker-Abschnitte sind `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, `plugins-runtime-install-a` bis `plugins-runtime-install-h`, `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-discord`, `bundled-channels-update-b` und `bundled-channels-contracts`. Der aggregierte Abschnitt `bundled-channels` bleibt für manuelle einmalige Wiederholungen verfügbar, und `plugins-runtime-core`, `plugins-runtime` sowie `plugins-integrations` bleiben aggregierte Plugin-/Runtime-Aliasse. Der Lane-Alias `install-e2e` bleibt der aggregierte manuelle Wiederholungsalias für beide Provider-Installer-Lanes. Der Abschnitt `bundled-channels` führt aufgeteilte Lanes `bundled-channel-*` und `bundled-channel-update-*` aus, statt der seriellen All-in-one-Lane `bundled-channel-deps`.
OpenWebUI wird in `plugins-runtime-services` integriert, wenn vollständige Release-Pfad-Abdeckung dies anfordert, und behält einen eigenständigen Chunk `openwebui` nur für reine OpenWebUI-Dispatches. Update-Lanes für gebündelte Kanäle wiederholen sich einmal bei vorübergehenden npm-Netzwerkfehlern.
OpenWebUI wird in `plugins-runtime-services` integriert, wenn vollständige Abdeckung des Release-Pfads dies anfordert, und behält einen eigenständigen Abschnitt `openwebui` nur für reine OpenWebUI-Ausführungen. Aktualisierungs-Lanes für gebündelte Kanäle wiederholen sich bei vorübergehenden npm-Netzwerkfehlern einmal.
Jeder Chunk lädt `.artifacts/docker-tests/` mit Lane-Logs, Timings, `summary.json`, `failures.json`, Phasen-Timings, Scheduler-Plan-JSON, Tabellen langsamer Lanes und Neuausführungsbefehlen pro Lane hoch. Die Workflow-Eingabe `docker_lanes` führt ausgewählte Lanes gegen die vorbereiteten Images aus statt der Chunk-Jobs. Dadurch bleibt das Debugging fehlgeschlagener Lanes auf einen gezielten Docker-Job begrenzt und das Paketartefakt wird für diesen Lauf vorbereitet, heruntergeladen oder wiederverwendet; wenn eine ausgewählte Lane eine Live-Docker-Lane ist, baut der gezielte Job das Live-Test-Image lokal für diese Neuausführung. Generierte GitHub-Neuausführungsbefehle pro Lane enthalten `package_artifact_run_id`, `package_artifact_name` und vorbereitete Image-Eingaben, wenn diese Werte vorhanden sind, sodass eine fehlgeschlagene Lane exakt das Paket und die Images aus dem fehlgeschlagenen Lauf wiederverwenden kann.
Jeder Abschnitt lädt `.artifacts/docker-tests/` mit Lane-Logs, Zeitmessungen, `summary.json`, `failures.json`, Phasenzeiten, Scheduler-Plan-JSON, Tabellen langsamer Lanes und Wiederholungsbefehlen pro Lane hoch. Die Workflow-Eingabe `docker_lanes` führt ausgewählte Lanes gegen die vorbereiteten Images aus statt der Abschnitt-Jobs. Dadurch bleibt die Fehlersuche für fehlgeschlagene Lanes auf einen gezielten Docker-Job begrenzt und das Paketartefakt für diesen Lauf wird vorbereitet, heruntergeladen oder wiederverwendet; wenn eine ausgewählte Lane eine Live-Docker-Lane ist, baut der gezielte Job das Live-Test-Image lokal für diese Wiederholung. Generierte GitHub-Wiederholungsbefehle pro Lane enthalten `package_artifact_run_id`, `package_artifact_name` und vorbereitete Image-Eingaben, wenn diese Werte vorhanden sind, sodass eine fehlgeschlagene Lane exakt dasselbe Paket und dieselben Images aus dem fehlgeschlagenen Lauf wiederverwenden kann.
```bash
pnpm test:docker:rerun <run-id> # download Docker artifacts and print combined/per-lane targeted rerun commands
pnpm test:docker:timings <summary> # slow-lane and phase critical-path summaries
```
Der geplante Live-/E2E-Workflow führt die vollständige Docker-Suite für den Release-Pfad täglich aus.
Der geplante Live-/E2E-Workflow führt täglich die vollständige Docker-Suite des Release-Pfads aus.
## Plugin-Vorabversion
`Plugin Prerelease` ist aufwendigere Produkt-/Paketabdeckung und daher ein separater Workflow, der von `Full Release Validation` oder durch einen expliziten Operator ausgelöst wird. Normale Pull Requests, Pushes nach `main` und eigenständige manuelle CI-Dispatches lassen diese Suite deaktiviert. Er verteilt gebündelte Plugin-Tests auf acht Extension-Worker; diese Extension-Shard-Jobs führen bis zu zwei Plugin-Konfigurationsgruppen gleichzeitig aus, mit einem Vitest-Worker pro Gruppe und einem größeren Node-Heap, damit importlastige Plugin-Batches keine zusätzlichen CI-Jobs erzeugen.
`Plugin Prerelease` ist eine teurere Produkt-/Paketabdeckung 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-Ausführungen lassen diese Suite deaktiviert. Sie verteilt gebündelte Plugin-Tests auf acht Erweiterungs-Worker; diese Erweiterungs-Shard-Jobs führen bis zu zwei Plugin-Konfigurationsgruppen gleichzeitig aus, mit einem Vitest-Worker pro Gruppe und einem größeren Node-Heap, damit importlastige Plugin-Stapel keine zusätzlichen CI-Jobs erzeugen.
## QA Lab
QA Lab hat dedizierte CI-Lanes außerhalb des zentralen smart gescopten Workflows.
QA Lab verfügt über dedizierte CI-Lanes außerhalb des wichtigsten smart eingegrenzten Workflows.
- Der Workflow `Parity gate` läuft bei passenden PR-Änderungen und manuellem Dispatch; er baut die private QA-Runtime und vergleicht die agentischen Mock-Packs GPT-5.5 und Opus 4.6.
- Der Workflow `QA-Lab - All Lanes` läuft nächtlich auf `main` und bei manuellem Dispatch; er fächert das Mock-Parity-Gate, die Live-Matrix-Lane sowie die Live-Lanes für Telegram und Discord als parallele Jobs auf. Live-Jobs verwenden die Umgebung `qa-live-shared`, und Telegram/Discord verwenden Convex-Leases.
- Der Workflow `Parity gate` läuft bei passenden PR-Änderungen und manueller Ausführung; er baut die private QA-Runtime und vergleicht die agentischen Pakete mit Mock GPT-5.5 und Opus 4.6.
- Der Workflow `QA-Lab - All Lanes` läuft nächtlich auf `main` und bei manueller Ausführung; er fächert das Mock-Paritäts-Gate, die Live-Matrix-Lane sowie die Live-Telegram- und Discord-Lanes als parallele Jobs auf. Live-Jobs verwenden die Umgebung `qa-live-shared`, und Telegram/Discord verwenden Convex-Leases.
Release-Prüfungen führen Matrix- und Telegram-Live-Transport-Lanes mit dem deterministischen Mock-Provider und mock-qualifizierten Modellen (`mock-openai/gpt-5.5` und `mock-openai/gpt-5.5-alt`) aus, sodass der Kanalvertrag von Live-Modelllatenz und normalem Start des Provider-Plugins isoliert ist. Das Live-Transport-Gateway deaktiviert die Speichersuche, weil QA-Parität das Speicherverhalten separat abdeckt; Provider-Konnektivität wird durch die separaten Suites für Live-Modell, nativen Provider und Docker-Provider abgedeckt.
Release-Prüfungen 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, damit der Kanalvertrag von Live-Modell-Latenz und normalem Start des Provider-Plugins isoliert ist. Das Live-Transport-Gateway deaktiviert die Speichersuche, weil QA-Parität das Speicherverhalten separat abdeckt; Provider-Konnektivität wird durch die separaten Suiten für Live-Modelle, native Provider und Docker-Provider abgedeckt.
Matrix verwendet `--profile fast` für geplante Gates 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`; ein manueller Dispatch mit `matrix_profile=all` shardet die vollständige Matrix-Abdeckung immer in die Jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` und `e2ee-cli`.
Matrix verwendet `--profile fast` für geplante und Release-Gates und ergänzt `--fail-fast` nur, wenn die ausgecheckte CLI dies unterstützt. Die CLI-Standardeinstellung und die manuelle Workflow-Eingabe bleiben `all`; eine manuelle Ausführung mit `matrix_profile=all` teilt die vollständige Matrix-Abdeckung immer in die Jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` und `e2ee-cli` auf.
`OpenClaw Release Checks` führt außerdem die releasekritischen QA-Lab-Lanes vor der Release-Freigabe aus; sein QA-Parity-Gate führt Kandidaten- und Baseline-Packs als parallele Lane-Jobs aus und lädt anschließend beide Artefakte in einen kleinen Bericht-Job 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 die Kandidaten- und Baseline-Pakete als parallele Lane-Jobs aus und lädt anschließend beide Artefakte in einen kleinen Report-Job für den finalen Paritätsvergleich herunter.
Setzen Sie den PR-Landepfad nicht hinter `Parity gate`, es sei denn, die Änderung betrifft tatsächlich die QA-Runtime, Modell-Pack-Parität oder eine Oberfläche, die dem Parity-Workflow gehört. Für normale Kanal-, Konfigurations-, Dokumentations- oder Unit-Test-Korrekturen behandeln Sie es als optionales Signal und folgen stattdessen den gescopten CI-/Prüfnachweisen.
Setzen Sie den PR-Landing-Pfad nicht hinter `Parity gate`, sofern die Änderung nicht tatsächlich die QA-Runtime, Modellpaket-Parität oder eine Oberfläche berührt, die dem Paritäts-Workflow gehört. Behandeln Sie es bei normalen Korrekturen an Kanälen, Konfiguration, Dokumentation oder Unit-Tests als optionales Signal und folgen Sie stattdessen den eingegrenzten CI-/Prüfnachweisen.
## CodeQL
Der Workflow `CodeQL` ist bewusst ein enger erster Security-Scanner, nicht der vollständige Repository-Sweep. Tägliche, manuelle und nicht als Draft markierte Pull-Request-Guard-Läufe scannen Actions-Workflow-Code plus die JavaScript-/TypeScript-Oberflächen mit dem höchsten Risiko und verwenden dabei hochkonfidente Sicherheitsabfragen, gefiltert auf hohe/kritische `security-severity`.
Der Workflow `CodeQL` ist absichtlich ein enger erster Sicherheits-Scanner, nicht der vollständige Repository-Durchlauf. Tägliche, manuelle und Nicht-Draft-Pull-Request-Schutzläufe scannen Actions-Workflow-Code sowie die JavaScript-/TypeScript-Oberflächen mit dem höchsten Risiko mit Security-Queries hoher Konfidenz, gefiltert auf hohe/kritische `security-severity`.
Der Pull-Request-Guard bleibt schlank: Er startet nur bei Änderungen unter `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` oder `src` und führt dieselbe hochkonfidente Sicherheitsmatrix wie der geplante Workflow aus. Android- und macOS-CodeQL bleiben außerhalb der PR-Standards.
Der Pull-Request-Schutz bleibt leichtgewichtig: Er startet nur bei Änderungen unter `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` oder `src` und führt dieselbe Security-Matrix hoher Konfidenz aus wie der geplante Workflow. Android- und macOS-CodeQL bleiben aus den PR-Standardeinstellungen heraus.
### Sicherheitskategorien
| Kategorie | Oberfläche |
| Kategorie | Oberfläche |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-security-high/core-auth-secrets` | Auth, Secrets, Sandbox, Cron und Gateway-Baseline |
| `/codeql-security-high/channel-runtime-boundary` | Implementierungsverträge der Kernkanäle plus Kanal-Plugin-Runtime, Gateway, Plugin SDK, Secrets, Audit-Berührungspunkte |
| `/codeql-security-high/network-ssrf-boundary` | Kern-SSRF, IP-Parsing, Netzwerk-Guard, Web-Fetch und SSRF-Policy-Oberflächen des Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | MCP-Server, Hilfen zur Prozessausführung, ausgehende Zustellung und Gates für Agent-Tool-Ausführung |
| `/codeql-security-high/plugin-trust-boundary` | Plugin-Installation, Loader, Manifest, Registry, Staging von Runtime-Abhängigkeiten, Quellcode-Laden und Vertrauensoberflächen des Plugin-SDK-Paketvertrags |
| `/codeql-security-high/core-auth-secrets` | Authentifizierung, Secrets, Sandbox, Cron und Gateway-Baseline |
| `/codeql-security-high/channel-runtime-boundary` | Kernverträge der Kanalimplementierung plus Kanal-Plugin-Runtime, Gateway, Plugin SDK, Secrets, Audit-Berührungspunkte |
| `/codeql-security-high/network-ssrf-boundary` | Kern-SSRF, IP-Parsing, Netzwerk-Guard, Web-Fetch und SSRF-Richtlinienoberflächen des Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | MCP-Server, Prozessausführungshelfer, ausgehende Zustellung und Gates für die Tool-Ausführung von Agenten |
| `/codeql-security-high/plugin-trust-boundary` | Plugin-Installation, Loader, Manifest, Registry, Runtime-Abhängigkeits-Staging, Quellladen und Vertrauensoberflächen des Plugin-SDK-Paketvertrags |
### Plattformspezifische Security-Shards
### Plattformspezifische Sicherheits-Shards
- `CodeQL Android Critical Security` — geplanter Android-Security-Shard. Baut die Android-App manuell für CodeQL auf dem kleinsten Blacksmith-Linux-Runner, der von der Workflow-Sanity akzeptiert wird. Lädt unter `/codeql-critical-security/android` hoch.
- `CodeQL macOS Critical Security` — wöchentlicher/manueller macOS-Security-Shard. Baut die macOS-App manuell für CodeQL auf Blacksmith macOS, filtert Ergebnisse von Dependency-Builds aus dem hochgeladenen SARIF heraus und lädt unter `/codeql-critical-security/macos` hoch. Bleibt außerhalb der täglichen Standards, weil der macOS-Build auch bei sauberem Lauf die Laufzeit 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 täglicher Standardeinstellungen, weil der macOS-Build die Laufzeit selbst bei sauberem Zustand dominiert.
### Kategorien für kritische Qualität
`CodeQL Critical Quality` ist der entsprechende Nicht-Security-Shard. Er führt nur JavaScript-/TypeScript-Qualitätsabfragen mit Fehler-Schweregrad und ohne Security-Bezug über eng begrenzte hochwertige Oberflächen auf dem kleineren Blacksmith-Linux-Runner aus. Sein Pull-Request-Guard ist bewusst 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 Änderungen an Agent-Befehls-/Modell-/Tool-Ausführung und Reply-Dispatch-Code, Konfigurationsschema-/Migrations-/IO-Code, Auth-/Secrets-/Sandbox-/Security-Code, Kernkanal- und gebündelter Kanal-Plugin-Runtime, Gateway-Protokoll-/Server-Method-Code, Memory-Runtime-/SDK-Glue, MCP-/Prozess-/ausgehender Zustellung, Provider-Runtime-/Modellkatalog, Sitzungsdiagnose-/Zustellungswarteschlangen, Plugin-Loader, Plugin-SDK-/Paketvertrag oder Plugin-SDK-Reply-Runtime aus. Änderungen an CodeQL-Konfiguration und Qualitätsworkflow führen alle zwölf PR-Qualitäts-Shards aus.
`CodeQL Critical Quality` ist der passende Nicht-Sicherheits-Shard. Er führt ausschließlich JavaScript-/TypeScript-Qualitätsabfragen mit Fehler-Schweregrad und ohne Sicherheitsbezug über enge, hochwertige Oberflächen auf dem kleineren Blacksmith-Linux-Runner aus. Sein Pull-Request-Schutz 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 Änderungen an Agentenbefehls-/Modell-/Tool-Ausführung und Reply-Dispatch-Code, Konfigurationsschema-/Migrations-/IO-Code, Auth-/Secrets-/Sandbox-/Sicherheitscode, Kernkanal- und gebündelter Kanal-Plugin-Runtime, Gateway-Protokoll-/Server-Methoden, Memory-Runtime-/SDK-Verbindungscode, MCP-/Prozess-/ausgehender Zustellung, Provider-Runtime-/Modellkatalog, Sitzungsdiagnose-/Zustellungswarteschlangen, Plugin-Loader, Plugin-SDK-/Paketvertrag oder Plugin-SDK-Reply-Runtime aus. Ä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 Lern-/Iterations-Hooks, um einen Qualitäts-Shard isoliert auszuführen.
Die engen Profile sind Lehr-/Iterations-Hooks, um einen Qualitäts-Shard isoliert auszuführen.
| Kategorie | Oberfläche |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | Auth-, Secret-, Sandbox-, Cron- und Gateway-Sicherheitsgrenzcode |
| `/codeql-critical-quality/config-boundary` | Konfigurationsschema, Migration, Normalisierung und IO-Verträge |
| `/codeql-critical-quality/gateway-runtime-boundary` | Gateway-Protokollschemata und Servermethoden-Verträge |
| `/codeql-critical-quality/channel-runtime-boundary` | Verträge für Core-Kanäle und Implementierungen gebündelter Channel-Plugins |
| `/codeql-critical-quality/agent-runtime-boundary` | Befehlsausführung, Model-/Provider-Dispatch, Auto-Reply-Dispatch und Warteschlangen sowie Runtime-Verträge der ACP-Control-Plane |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP-Server und Tool-Bridges, Hilfen zur Prozessüberwachung und Verträge für ausgehende Zustellung |
| `/codeql-critical-quality/memory-runtime-boundary` | Memory-Host-SDK, Memory-Runtime-Fassaden, Memory-Aliase des Plugin SDK, Aktivierungs-Glue der Memory-Runtime und Memory-Doctor-Befehle |
| `/codeql-critical-quality/session-diagnostics-boundary` | Interna der Antwortwarteschlange, Sitzungs-Zustellungswarteschlangen, Hilfen für ausgehende Sitzungsbindung/-zustellung, Oberflächen für Diagnoseereignisse/Log-Bundles und Sitzungs-Doctor-CLI-Verträge |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Eingehender Reply-Dispatch des Plugin SDK, Hilfen für Reply-Payload/Chunking/Runtime, Channel-Reply-Optionen, Zustellungswarteschlangen und Hilfen für Sitzungs-/Thread-Bindung |
| `/codeql-critical-quality/provider-runtime-boundary` | Normalisierung des Model-Katalogs, Provider-Auth und -Discovery, Provider-Runtime-Registrierung, Provider-Defaults/-Kataloge sowie 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` | Core-Web-Fetch/Search, Medien-IO, Medienverständnis, Bilderzeugung und Runtime-Verträge für Medienerzeugung |
| `/codeql-critical-quality/plugin-boundary` | Verträge für Loader, Registry, öffentliche Oberfläche und Plugin SDK-Einstiegspunkte |
| `/codeql-critical-quality/plugin-sdk-package-contract` | Veröffentlichter package-seitiger Plugin SDK-Quellcode und Hilfen für Plugin-Package-Verträge |
| Kategorie | Bereich |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | Authentifizierung, Secrets, Sandbox, Cron und Code für die Sicherheitsgrenze des Gateway |
| `/codeql-critical-quality/config-boundary` | Konfigurationsschema, Migration, Normalisierung und IO-Verträge |
| `/codeql-critical-quality/gateway-runtime-boundary` | Gateway-Protokollschemata und Verträge für Servermethoden |
| `/codeql-critical-quality/channel-runtime-boundary` | Core-Kanal- und Implementierungsverträge für gebündelte Kanal-Plugins |
| `/codeql-critical-quality/agent-runtime-boundary` | Befehlsausführung, Modell-/Provider-Dispatch, Auto-Reply-Dispatch und Warteschlangen sowie Laufzeitverträge der ACP-Control-Plane |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP-Server und Tool-Brücken, Hilfsfunktionen für Prozessüberwachung und Verträge für ausgehende Zustellung |
| `/codeql-critical-quality/memory-runtime-boundary` | Memory-Host-SDK, Memory-Laufzeitfassaden, Memory-Plugin-SDK-Aliase, Memory-Laufzeitaktivierungs-Glue und Memory-Doctor-Befehle |
| `/codeql-critical-quality/session-diagnostics-boundary` | Interna der Antwortwarteschlange, Sitzungszustellungswarteschlangen, Hilfsfunktionen für ausgehende Sitzungsbindung/-zustellung, Oberflächen für Diagnoseereignisse/Log-Bundles und Sitzungs-Doctor-CLI-Verträge |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Eingehender Antwort-Dispatch des Plugin-SDK, Antwort-Payload-/Chunking-/Laufzeit-Hilfsfunktionen, Kanalantwortoptionen, Zustellungswarteschlangen und Hilfsfunktionen für Sitzungs-/Thread-Bindung |
| `/codeql-critical-quality/provider-runtime-boundary` | Modellkatalog-Normalisierung, Provider-Authentifizierung und -Erkennung, Provider-Laufzeitregistrierung, Provider-Standards/-Kataloge und Web-/Such-/Fetch-/Embedding-Registries |
| `/codeql-critical-quality/ui-control-plane` | Bootstrap der Control-UI, lokale Persistenz, Gateway-Control-Flows und Laufzeitverträge der Task-Control-Plane |
| `/codeql-critical-quality/web-media-runtime-boundary` | Core-Web-Fetch/-Suche, Medien-IO, Medienverständnis, Bildgenerierung und Laufzeitverträge für Mediengenerierung |
| `/codeql-critical-quality/plugin-boundary` | Loader-, Registry-, Public-Surface- und Plugin-SDK-Entrypoint-Verträge |
| `/codeql-critical-quality/plugin-sdk-package-contract` | Veröffentlichter paketbezogener Plugin-SDK-Quellcode und Hilfsfunktionen für Plugin-Paketverträge |
Qualität bleibt von Sicherheit getrennt, damit Qualitätsbefunde geplant, gemessen, deaktiviert oder erweitert werden können, ohne das Sicherheitssignal zu verschleiern. Die CodeQL-Erweiterung für Swift, Python und gebündelte Plugins sollte erst wieder als scoped oder sharded Folgearbeit hinzugefügt werden, nachdem die engen Profile stabile Runtime und stabiles Signal haben.
Qualität bleibt von Sicherheit getrennt, damit Qualitätsbefunde geplant, gemessen, deaktiviert oder erweitert werden können, ohne das Sicherheitssignal zu verdecken. Die CodeQL-Erweiterung für Swift, Python und gebündelte Plugins sollte erst dann wieder als eingegrenzte oder geshardete Nacharbeit hinzugefügt werden, wenn die schmalen Profile eine stabile Laufzeit und ein stabiles Signal haben.
## Wartungsworkflows
### Docs Agent
Der Workflow `Docs Agent` ist eine ereignisgesteuerte Codex-Wartungslane, um vorhandene Dokumentation an kürzlich gelandete Änderungen anzupassen. Er hat keinen reinen Zeitplan: Ein erfolgreicher Nicht-Bot-Push-CI-Lauf auf `main` kann ihn auslösen, und ein manueller Dispatch kann ihn direkt ausführen. Workflow-Run-Aufrufe werden übersprungen, wenn `main` bereits weitergelaufen ist oder wenn in der letzten Stunde ein anderer nicht übersprungener Docs-Agent-Lauf erstellt wurde. Wenn er ausgeführt wird, prüft er den Commit-Bereich vom vorherigen nicht übersprungenen Docs-Agent-Quell-SHA bis zum aktuellen `main`, sodass ein stündlicher Lauf alle Main-Änderungen abdecken kann, die sich seit dem letzten Dokumentationsdurchlauf angesammelt haben.
Der Workflow `Docs Agent` ist eine ereignisgesteuerte Codex-Wartungsspur, die bestehende Dokumentation mit kürzlich gelandeten Änderungen abgleicht. Er hat keinen reinen Zeitplan: Ein erfolgreicher Nicht-Bot-Push-CI-Lauf auf `main` kann ihn auslösen, und ein manueller Dispatch kann ihn direkt ausführen. Workflow-Run-Aufrufe werden übersprungen, wenn `main` bereits 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-Quell-SHA bis zum aktuellen `main`, sodass ein stündlicher Lauf alle Änderungen auf main abdecken kann, die seit dem letzten Dokumentationsdurchlauf aufgelaufen sind.
### Test Performance Agent
Der Workflow `Test Performance Agent` 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äts-Gate. Die Lane erstellt einen gruppierten Vitest-Performance-Bericht für die gesamte Suite, lässt Codex nur kleine, coverage-erhaltende Test-Performance-Fixes statt breiter Refactorings vornehmen, führt dann den Full-Suite-Bericht erneut aus und lehnt Änderungen ab, die die Baseline-Anzahl bestandener Tests verringern. Wenn die Baseline fehlgeschlagene Tests hat, darf Codex nur offensichtliche Fehler beheben, und der Full-Suite-Bericht nach dem Agent muss bestehen, bevor etwas committet wird. Wenn `main` vor dem Bot-Push weiterläuft, rebased die Lane den validierten Patch, führt `pnpm check:changed` erneut aus und versucht den Push erneut; kollidierende veraltete Patches werden übersprungen. Sie verwendet GitHub-gehostetes Ubuntu, damit die Codex-Action dieselbe Drop-Sudo-Sicherheitshaltung wie der Docs Agent beibehalten kann.
Der Workflow `Test Performance Agent` ist eine ereignisgesteuerte Codex-Wartungsspur für langsame Tests. Er hat keinen reinen Zeitplan: Ein erfolgreicher Nicht-Bot-Push-CI-Lauf auf `main` kann ihn auslösen, aber er wird übersprungen, wenn ein anderer Workflow-Run-Aufruf an diesem UTC-Tag bereits gelaufen ist oder läuft. Ein manueller Dispatch umgeht dieses tägliche Aktivitäts-Gate. Die Spur erstellt einen gruppierten Vitest-Performancebericht für die gesamte Suite, lässt Codex nur kleine, abdeckungserhaltende Test-Performance-Fixes statt breiter Refactorings vornehmen, führt den Bericht für die gesamte Suite anschließend erneut aus und lehnt Änderungen ab, die die Baseline-Anzahl bestandener Tests reduzieren. Wenn die Baseline fehlschlagende Tests enthält, darf Codex nur offensichtliche Fehler beheben, und der Full-Suite-Bericht nach dem Agenten muss bestehen, bevor etwas committet wird. Wenn `main` vor dem Bot-Push weiterläuft, rebased die Spur 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-Sicherheitsausrichtung wie der Docs-Agent beibehalten kann.
### Doppelte PRs nach Merge
### Doppelte PRs nach dem Merge
Der Workflow `Duplicate PRs After Merge` ist ein manueller Maintainer-Workflow für die Bereinigung doppelter PRs nach dem Landen. Standardmäßig läuft er als Dry-Run und schließt explizit aufgelistete PRs nur, wenn `apply=true` ist. Bevor GitHub verändert wird, prüft er, dass der gelandete PR gemergt ist und dass jeder doppelte PR entweder ein gemeinsam referenziertes Issue oder überlappende geänderte Hunks hat.
Der Workflow `Duplicate PRs After Merge` ist ein manueller Maintainer-Workflow für die Bereinigung doppelter PRs nach dem Landen. Standardmäßig läuft er als Dry-Run und schließt nur explizit aufgeführte PRs, wenn `apply=true` gesetzt ist. Bevor GitHub mutiert wird, prüft er, dass der gelandete PR gemergt wurde und dass jedes Duplikat entweder ein gemeinsam referenziertes Issue oder überlappende geänderte Hunks hat.
```bash
gh workflow run duplicate-after-merge.yml \
@ -392,29 +392,29 @@ gh workflow run duplicate-after-merge.yml \
-f apply=true
```
## Lokale Check-Gates und Änderungsrouting
## Lokale Check-Gates und Routing geänderter Dateien
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-Plattform-Scope:
Die lokale Changed-Lane-Logik befindet sich in `scripts/changed-lanes.mjs` und wird von `scripts/check-changed.mjs` ausgeführt. Dieses lokale Check-Gate ist bei Architekturgrenzen strenger als der breite Scope der CI-Plattform:
- Core-Produktionsänderungen führen Core-Prod- und Core-Test-Typecheck plus Core-Lint/Guards aus;
- reine Core-Teständerungen führen nur Core-Test-Typecheck plus Core-Lint aus;
- Extension-Produktionsänderungen führen Extension-Prod- und Extension-Test-Typecheck plus Extension-Lint aus;
- reine Extension-Teständerungen führen Extension-Test-Typecheck plus Extension-Lint aus;
- Änderungen am öffentlichen Plugin SDK oder an Plugin-Verträgen werden auf Extension-Typecheck erweitert, weil Extensions von diesen Core-Verträgen abhängen (Vitest-Extension-Sweeps bleiben explizite Testarbeit);
- Core-Produktionsänderungen führen Core-Prod- und Core-Test-Typecheck sowie Core-Lint/Guards aus;
- reine Core-Teständerungen führen nur Core-Test-Typecheck sowie Core-Lint aus;
- Plugin-Produktionsänderungen führen Plugin-Prod- und Plugin-Test-Typecheck sowie Plugin-Lint aus;
- reine Plugin-Teständerungen führen Plugin-Test-Typecheck sowie Plugin-Lint aus;
- Änderungen am öffentlichen Plugin-SDK oder an Plugin-Verträgen erweitern auf Plugin-Typecheck, weil Plugins von diesen Core-Verträgen abhängen (Vitest-Plugin-Sweeps bleiben explizite Testarbeit);
- reine Release-Metadaten-Versionsbumps führen gezielte Versions-/Konfigurations-/Root-Dependency-Checks aus;
- unbekannte Root-/Konfigurationsänderungen fallen sicherheitshalber auf alle Check-Lanes zurück.
Das lokale Changed-Test-Routing liegt in `scripts/test-projects.test-support.mjs` und ist absichtlich günstiger als `check:changed`: Direkte Teständerungen führen sich selbst aus, Quelländerungen bevorzugen explizite Mappings, dann Geschwistertests und Import-Graph-Abhängige. Die Shared-Group-Room-Zustellungskonfiguration ist eines der expliziten Mappings: Änderungen an der für die Gruppe sichtbaren Reply-Konfiguration, am Source-Reply-Zustellungsmodus oder am Message-Tool-System-Prompt laufen über die Core-Reply-Tests plus Discord- und Slack-Zustellungsregressionen, damit eine Änderung eines gemeinsamen Defaults 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 das günstige gemappte Set kein vertrauenswürdiger Proxy ist.
Das lokale Routing geänderter Tests befindet sich in `scripts/test-projects.test-support.mjs` und ist absichtlich günstiger als `check:changed`: Direkte Teständerungen führen sich selbst aus, Quelländerungen bevorzugen explizite Mappings, danach Geschwistertests und Importgraph-Abhängige. Die Konfiguration für die Zustellung in gemeinsam genutzten Gruppenräumen ist eines der expliziten Mappings: Änderungen an der für Gruppen sichtbaren Antwortkonfiguration, am Quell-Antwortzustellmodus oder am System-Prompt des Message-Tools laufen über die Core-Antworttests plus Discord- und Slack-Zustellungsregressionen, damit eine Änderung an einem gemeinsam genutzten Standard vor dem ersten PR-Push fehlschlägt. Verwenden Sie `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` nur, wenn die Änderung so harness-weit ist, dass die günstige gemappte Menge kein vertrauenswürdiger Proxy ist.
## Testbox-Validierung
Führen Sie Testbox vom Repo-Root aus und bevorzugen Sie für breiten Nachweis eine frisch vorgewärmte Box. Bevor Sie ein langsames Gate auf einer Box ausführen, die wiederverwendet wurde, abgelaufen ist oder gerade einen unerwartet großen Sync gemeldet hat, führen Sie zuerst `pnpm testbox:sanity` innerhalb der Box aus.
Führen Sie Testbox aus dem Repo-Root aus und bevorzugen Sie für breite Nachweise eine frisch vorgewärmte Box. Bevor Sie ein langsames Gate auf einer Box ausgeben, 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 getrackte Löschungen zeigt. Das bedeutet in der Regel, dass der Remote-Sync-Status keine vertrauenswürdige Kopie des PR ist; stoppen Sie diese Box und wärmen Sie eine frische auf, statt 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`.
Der Sanity-Check schlägt schnell fehl, wenn erforderliche Root-Dateien wie `pnpm-lock.yaml` verschwunden sind oder wenn `git status --short` mindestens 200 getrackte Löschungen anzeigt. Das bedeutet in der Regel, dass der Remote-Sync-Status keine vertrauenswürdige Kopie des PR ist; stoppen Sie diese Box und wärmen Sie eine frische vor, statt den Produkt-Testfehler zu debuggen. Für beabsichtigte 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 ohne Post-Sync-Ausgabe in der Sync-Phase bleibt. Setzen Sie `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, um diesen Guard 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 ohne Ausgabe nach der Synchronisierung in der Synchronisierungsphase verbleibt. Setzen Sie `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, um diese Schutzvorrichtung zu deaktivieren, oder verwenden Sie für ungewöhnlich große lokale Diffs einen größeren Millisekundenwert.
## Verwandt
- [Installationsüberblick](/de/install)
- [Installationsübersicht](/de/install)
- [Entwicklungskanäle](/de/install/development-channels)

181
docs/de/concepts/agent-loop.md
View File

@ -1,154 +1,155 @@
---
read_when:
- Sie benötigen eine genaue Schritt-für-Schritt-Anleitung zur Agenten-Schleife oder zu Lifecycle-Ereignissen
- Sie ändern die Warteschlangenbildung für Sitzungen, Transkript-Schreibvorgänge oder das Verhalten der Schreibsperre für Sitzungen
summary: Lebenszyklus der Agent-Schleife, Streams und Wartesemantik
title: Agent-Schleife
- Sie benötigen eine genaue Schritt-für-Schritt-Anleitung zur Agentenschleife oder zu Lebenszyklusereignissen
- Sie ändern die Warteschlangenverarbeitung von Sitzungen, Transkript-Schreibvorgänge oder das Verhalten der Schreibsperre für Sitzungen
summary: Lebenszyklus des Agent-Loops, Streams und Wartesemantik
title: Agentenschleife
x-i18n:
generated_at: "2026-04-30T06:47:44Z"
generated_at: "2026-04-30T18:38:40Z"
model: gpt-5.5
provider: openai
source_hash: 902d543bd71dd517a810d825cbe92e244fe89230f47eeada72477c657a2bec32
source_hash: 5466893253e1f82482284ff82db56f4c3fca018bf12e4114fad76d37cad954df
source_path: concepts/agent-loop.md
workflow: 16
---
Ein agentischer Loop ist die vollständige „echte“ Ausführung eines Agenten: Eingang → Kontextzusammenstellung → Modellinferenz →
Ein agentischer Loop ist der vollständige „echte“ Lauf eines Agenten: Eingang → Kontextzusammenstellung → Modellinferenz →
Tool-Ausführung → Streaming-Antworten → Persistenz. Er ist der maßgebliche Pfad, der eine Nachricht
in Aktionen und eine finale Antwort umsetzt und dabei den Sitzungsstatus konsistent hält.
in Aktionen und eine finale Antwort umwandelt und dabei den Sitzungszustand konsistent hält.
In OpenClaw ist ein Loop eine einzelne, serialisierte Ausführung pro Sitzung, die Lebenszyklus- und Stream-Ereignisse
ausgibt, während das Modell denkt, Tools aufruft und Ausgaben streamt. Dieses Dokument erklärt, wie dieser authentische Loop
End-to-End verdrahtet ist.
In OpenClaw ist ein Loop ein einzelner, serialisierter Lauf pro Sitzung, der Lifecycle- und Stream-Ereignisse ausgibt,
während das Modell nachdenkt, Tools aufruft und Ausgaben streamt. Dieses Dokument erklärt, wie dieser authentische Loop
durchgängig verdrahtet ist.
## Einstiegspunkte
- Gateway-RPC: `agent` und `agent.wait`.
- CLI: Befehl `agent`.
## Funktionsweise (überblicksartig)
## Funktionsweise (allgemein)
1. `agent`-RPC validiert Parameter, löst die Sitzung auf (sessionKey/sessionId), persistiert Sitzungsmetadaten und gibt sofort `{ runId, acceptedAt }` zurück.
2. `agentCommand` führt den Agenten aus:
- löst Modell- sowie Standardwerte für Denken/Verbose/Trace auf
- löst Modell- sowie Thinking/Verbose/Trace-Standardwerte auf
- lädt den Skills-Snapshot
- ruft `runEmbeddedPiAgent` auf (pi-agent-core-Runtime)
- gibt **Lebenszyklus-Ende/-Fehler** aus, wenn der eingebettete Loop keines ausgibt
- gibt **Lifecycle-Ende/Fehler** aus, falls der eingebettete Loop dies nicht selbst ausgibt
3. `runEmbeddedPiAgent`:
- serialisiert Ausführungen über sitzungsspezifische und globale Queues
- löst Modell und Authentifizierungsprofil auf und erstellt die Pi-Sitzung
- serialisiert Läufe über sitzungsbezogene und globale Queues
- löst Modell und Auth-Profil auf und erstellt die Pi-Sitzung
- abonniert Pi-Ereignisse und streamt Assistant-/Tool-Deltas
- erzwingt Timeout -> bricht die Ausführung ab, wenn es überschritten wird
- erzwingt Timeout -> bricht den Lauf ab, wenn er überschritten wird
- bricht bei Codex-App-Server-Turns einen akzeptierten Turn ab, der vor einem terminalen Ereignis keinen App-Server-Fortschritt mehr erzeugt
- gibt Payloads und Nutzungsmetadaten zurück
4. `subscribeEmbeddedPiSession` überbrückt pi-agent-core-Ereignisse zum OpenClaw-`agent`-Stream:
- Tool-Ereignisse => `stream: "tool"`
- Assistant-Deltas => `stream: "assistant"`
- Lebenszyklusereignisse => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`)
- Lifecycle-Ereignisse => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`)
5. `agent.wait` verwendet `waitForAgentRun`:
- wartet auf **Lebenszyklus-Ende/-Fehler** für `runId`
- wartet auf **Lifecycle-Ende/Fehler** für `runId`
- gibt `{ status: ok|error|timeout, startedAt, endedAt, error? }` zurück
## Queueing + Nebenläufigkeit
## Queueing und Nebenläufigkeit
- Ausführungen werden pro Sitzungsschlüssel (Sitzungs-Lane) serialisiert und optional über eine globale Lane geführt.
- Läufe werden pro Sitzungsschlüssel (Sitzungs-Lane) und optional über eine globale Lane serialisiert.
- Dies verhindert Tool-/Sitzungs-Races und hält den Sitzungsverlauf konsistent.
- Messaging-Kanäle können Queue-Modi (collect/steer/followup) wählen, die in dieses Lane-System einspeisen.
Siehe [Befehls-Queue](/de/concepts/queue).
- Transkriptschreibvorgänge werden außerdem durch eine Sitzungsschreibsperre auf der Sitzungsdatei geschützt. Die Sperre ist
prozessbewusst und dateibasiert, sodass sie Schreibende erfasst, die die prozessinterne Queue umgehen oder aus
- Messaging-Kanäle können Queue-Modi wählen (collect/steer/followup), die dieses Lane-System speisen.
Siehe [Command Queue](/de/concepts/queue).
- Transkript-Schreibvorgänge werden ebenfalls durch eine Sitzungs-Schreibsperre auf der Sitzungsdatei geschützt. Die Sperre ist
prozessbewusst und dateibasiert, sodass sie Writer erfasst, die die In-Process-Queue umgehen oder aus
einem anderen Prozess stammen.
- Sitzungsschreibsperren sind standardmäßig nicht reentrant. Wenn ein Helper absichtlich den Erwerb
derselben Sperre verschachtelt und dabei einen logischen Schreibenden beibehält, muss er dies explizit mit
- Sitzungs-Schreibsperren sind standardmäßig nicht wiedereintrittsfähig. Wenn ein Helper absichtlich den Erwerb
derselben Sperre verschachtelt und dabei einen logischen Writer beibehält, muss er dies explizit mit
`allowReentrant: true` aktivieren.
## Sitzungs- und Workspace-Vorbereitung
## Vorbereitung von Sitzung und Arbeitsbereich
- Der Workspace wird aufgelöst und erstellt; sandboxed Ausführungen können zu einem Sandbox-Workspace-Root umgeleitet werden.
- Der Arbeitsbereich wird aufgelöst und erstellt; sandboxierte Läufe können auf ein Sandbox-Arbeitsbereich-Root umgeleitet werden.
- Skills werden geladen (oder aus einem Snapshot wiederverwendet) und in Umgebung und Prompt injiziert.
- Bootstrap-/Kontextdateien werden aufgelöst und in den System-Prompt-Bericht injiziert.
- Eine Sitzungsschreibsperre wird erworben; `SessionManager` wird vor dem Streaming geöffnet und vorbereitet. Jeder
spätere Pfad für Transkript-Neuschreibung, Compaction oder Kürzung muss dieselbe Sperre erwerben, bevor er die Transkriptdatei öffnet oder
- Eine Sitzungs-Schreibsperre wird erworben; `SessionManager` wird vor dem Streaming geöffnet und vorbereitet. Jeder
spätere Pfad zum Neuschreiben, zur Compaction oder zur Kürzung des Transkripts muss dieselbe Sperre erwerben, bevor er die Transkriptdatei öffnet oder
verändert.
## Prompt-Zusammenstellung + System-Prompt
## Prompt-Zusammenstellung und System-Prompt
- Der System-Prompt wird aus OpenClaws Basis-Prompt, Skills-Prompt, Bootstrap-Kontext und ausführungsspezifischen Überschreibungen erstellt.
- Modellspezifische Limits und Reserve-Tokens für Compaction werden erzwungen.
- Siehe [System-Prompt](/de/concepts/system-prompt), um zu sehen, was das Modell erhält.
- Der System-Prompt wird aus OpenClaws Basis-Prompt, Skills-Prompt, Bootstrap-Kontext und laufbezogenen Overrides aufgebaut.
- Modellspezifische Limits und reservierte Token für Compaction werden erzwungen.
- Siehe [System-Prompt](/de/concepts/system-prompt) dafür, was das Modell sieht.
## Hook-Punkte (wo Sie eingreifen können)
## Hook-Punkte (an denen Sie eingreifen können)
OpenClaw hat zwei Hook-Systeme:
- **Interne Hooks** (Gateway-Hooks): ereignisgesteuerte Skripte für Befehle und Lebenszyklusereignisse.
- **Plugin-Hooks**: Erweiterungspunkte innerhalb des Agent-/Tool-Lebenszyklus und der Gateway-Pipeline.
- **Interne Hooks** (Gateway-Hooks): ereignisgesteuerte Skripte für Befehle und Lifecycle-Ereignisse.
- **Plugin-Hooks**: Erweiterungspunkte innerhalb des Agent-/Tool-Lifecycles und der Gateway-Pipeline.
### Interne Hooks (Gateway-Hooks)
- **`agent:bootstrap`**: läuft beim Erstellen von Bootstrap-Dateien, bevor der System-Prompt finalisiert wird.
Verwenden Sie dies, um Bootstrap-Kontextdateien hinzuzufügen/zu entfernen.
- **Befehls-Hooks**: `/new`, `/reset`, `/stop` und andere Befehlsereignisse (siehe Hooks-Dokument).
- **`agent:bootstrap`**: läuft beim Aufbau von Bootstrap-Dateien, bevor der System-Prompt finalisiert wird.
Verwenden Sie dies, um Bootstrap-Kontextdateien hinzuzufügen oder zu entfernen.
- **Command-Hooks**: `/new`, `/reset`, `/stop` und andere Befehlsereignisse (siehe Hooks-Dokument).
Siehe [Hooks](/de/automation/hooks) für Einrichtung und Beispiele.
### Plugin-Hooks (Agent- + Gateway-Lebenszyklus)
### Plugin-Hooks (Agent- und Gateway-Lifecycle)
Diese laufen innerhalb des Agent-Loops oder der Gateway-Pipeline:
Diese laufen innerhalb des Agenten-Loops oder der Gateway-Pipeline:
- **`before_model_resolve`**: läuft vor der Sitzung (keine `messages`), um Provider/Modell vor der Modellauflösung deterministisch zu überschreiben.
- **`before_prompt_build`**: läuft nach dem Laden der Sitzung (mit `messages`), um `prependContext`, `systemPrompt`, `prependSystemContext` oder `appendSystemContext` vor der Prompt-Übermittlung zu injizieren. Verwenden Sie `prependContext` für dynamischen Text pro Turn und Systemkontextfelder für stabile Anweisungen, die im System-Prompt-Bereich stehen sollen.
- **`before_agent_start`**: Legacy-Kompatibilitäts-Hook, der in beiden Phasen laufen kann; bevorzugen Sie die expliziten Hooks oben.
- **`before_model_resolve`**: läuft vor der Sitzung (keine `messages`), um Provider/Modell deterministisch vor der Modellauflösung zu überschreiben.
- **`before_prompt_build`**: läuft nach dem Laden der Sitzung (mit `messages`), um vor der Prompt-Übermittlung `prependContext`, `systemPrompt`, `prependSystemContext` oder `appendSystemContext` zu injizieren. Verwenden Sie `prependContext` für dynamischen Text pro Turn und Systemkontext-Felder für stabile Leitlinien, die im System-Prompt-Bereich stehen sollen.
- **`before_agent_start`**: Legacy-Kompatibilitätshook, der in beiden Phasen laufen kann; bevorzugen Sie die expliziten Hooks oben.
- **`before_agent_reply`**: läuft nach Inline-Aktionen und vor dem LLM-Aufruf, sodass ein Plugin den Turn übernehmen und eine synthetische Antwort zurückgeben oder den Turn vollständig stummschalten kann.
- **`agent_end`**: inspiziert die finale Nachrichtenliste und Ausführungsmetadaten nach Abschluss.
- **`before_compaction` / `after_compaction`**: beobachtet oder annotiert Compaction-Zyklen.
- **`before_tool_call` / `after_tool_call`**: fängt Tool-Parameter/-Ergebnisse ab.
- **`before_install`**: inspiziert eingebaute Scan-Ergebnisse und blockiert optional Skill- oder Plugin-Installationen.
- **`tool_result_persist`**: transformiert Tool-Ergebnisse synchron, bevor sie in ein von OpenClaw verwaltetes Sitzungstranskript geschrieben werden.
- **`message_received` / `message_sending` / `message_sent`**: Hooks für eingehende und ausgehende Nachrichten.
- **`session_start` / `session_end`**: Grenzen des Sitzungslebenszyklus.
- **`gateway_start` / `gateway_stop`**: Gateway-Lebenszyklusereignisse.
- **`agent_end`**: finale Nachrichtenliste und Laufmetadaten nach Abschluss prüfen.
- **`before_compaction` / `after_compaction`**: Compaction-Zyklen beobachten oder annotieren.
- **`before_tool_call` / `after_tool_call`**: Tool-Parameter/-Ergebnisse abfangen.
- **`before_install`**: integrierte Scan-Ergebnisse prüfen und Skill- oder Plugin-Installationen optional blockieren.
- **`tool_result_persist`**: Tool-Ergebnisse synchron transformieren, bevor sie in ein OpenClaw-eigenes Sitzungstranskript geschrieben werden.
- **`message_received` / `message_sending` / `message_sent`**: eingehende und ausgehende Nachrichten-Hooks.
- **`session_start` / `session_end`**: Sitzungs-Lifecycle-Grenzen.
- **`gateway_start` / `gateway_stop`**: Gateway-Lifecycle-Ereignisse.
Hook-Entscheidungsregeln für Outbound-/Tool-Guards:
- `before_tool_call`: `{ block: true }` ist terminal und stoppt Handler mit niedrigerer Priorität.
- `before_tool_call`: `{ block: false }` ist ein No-op und hebt keine frühere Blockierung auf.
- `before_tool_call`: `{ block: false }` ist ein No-op und hebt einen vorherigen Block nicht auf.
- `before_install`: `{ block: true }` ist terminal und stoppt Handler mit niedrigerer Priorität.
- `before_install`: `{ block: false }` ist ein No-op und hebt keine frühere Blockierung auf.
- `before_install`: `{ block: false }` ist ein No-op und hebt einen vorherigen Block nicht auf.
- `message_sending`: `{ cancel: true }` ist terminal und stoppt Handler mit niedrigerer Priorität.
- `message_sending`: `{ cancel: false }` ist ein No-op und hebt keinen früheren Abbruch auf.
- `message_sending`: `{ cancel: false }` ist ein No-op und hebt ein vorheriges Cancel nicht auf.
Siehe [Plugin-Hooks](/de/plugins/hooks) für die Hook-API und Registrierungsdetails.
Harnesses können diese Hooks unterschiedlich adaptieren. Der Codex-App-Server-Harness behält
Harnesses können diese Hooks unterschiedlich adaptieren. Der Codex-App-Server-Harness hält
OpenClaw-Plugin-Hooks als Kompatibilitätsvertrag für dokumentierte gespiegelte
Oberflächen bei, während native Codex-Hooks ein separater, niedrigerer Codex-Mechanismus bleiben.
Oberflächen aufrecht, während native Codex-Hooks ein separater, niedrigerer Codex-Mechanismus bleiben.
## Streaming + Teilantworten
## Streaming und Teilantworten
- Assistant-Deltas werden aus pi-agent-core gestreamt und als `assistant`-Ereignisse ausgegeben.
- Assistant-Deltas werden von pi-agent-core gestreamt und als `assistant`-Ereignisse ausgegeben.
- Block-Streaming kann Teilantworten entweder bei `text_end` oder `message_end` ausgeben.
- Reasoning-Streaming kann als separater Stream oder als Blockantworten ausgegeben werden.
- Siehe [Streaming](/de/concepts/streaming) für Chunking und Verhalten von Blockantworten.
- Siehe [Streaming](/de/concepts/streaming) für Chunking- und Blockantwort-Verhalten.
## Tool-Ausführung + Messaging-Tools
## Tool-Ausführung und Messaging-Tools
- Tool-Start-/Update-/Ende-Ereignisse werden im `tool`-Stream ausgegeben.
- Tool-Ergebnisse werden vor dem Protokollieren/Ausgeben hinsichtlich Größe und Bild-Payloads bereinigt.
- Sends von Messaging-Tools werden nachverfolgt, um doppelte Assistant-Bestätigungen zu unterdrücken.
- Tool-Ergebnisse werden vor dem Logging/der Ausgabe hinsichtlich Größe und Bild-Payloads bereinigt.
- Sends von Messaging-Tools werden verfolgt, um doppelte Assistant-Bestätigungen zu unterdrücken.
## Antwortformung + Unterdrückung
## Antwortformung und Unterdrückung
- Finale Payloads werden zusammengesetzt aus:
- Finale Payloads werden zusammengestellt aus:
- Assistant-Text (und optional Reasoning)
- Inline-Tool-Zusammenfassungen (wenn verbose + erlaubt)
- Assistant-Fehlertext, wenn das Modell Fehler verursacht
- Das exakte stille Token `NO_REPLY` / `no_reply` wird aus ausgehenden
- Inline-Tool-Zusammenfassungen (wenn verbose und erlaubt)
- Assistant-Fehlertext, wenn das Modell Fehler ausgibt
- Das exakte stumme Token `NO_REPLY` / `no_reply` wird aus ausgehenden
Payloads herausgefiltert.
- Duplikate von Messaging-Tools werden aus der finalen Payload-Liste entfernt.
- Wenn keine darstellbaren Payloads übrig bleiben und ein Tool fehlgeschlagen ist, wird eine Fallback-Tool-Fehlerantwort ausgegeben
(es sei denn, ein Messaging-Tool hat bereits eine für Benutzer sichtbare Antwort gesendet).
- Wenn keine renderbaren Payloads übrig bleiben und bei einem Tool ein Fehler aufgetreten ist, wird eine Fallback-Tool-Fehlerantwort ausgegeben
(sofern nicht bereits ein Messaging-Tool eine für Benutzer sichtbare Antwort gesendet hat).
## Compaction + Wiederholungen
## Compaction und Wiederholungen
- Auto-Compaction gibt `compaction`-Stream-Ereignisse aus und kann eine Wiederholung auslösen.
- Bei einer Wiederholung werden In-Memory-Puffer und Tool-Zusammenfassungen zurückgesetzt, um doppelte Ausgaben zu vermeiden.
@ -156,35 +157,35 @@ Oberflächen bei, während native Codex-Hooks ein separater, niedrigerer Codex-M
## Ereignis-Streams (heute)
- `lifecycle`: ausgegeben durch `subscribeEmbeddedPiSession` (und als Fallback durch `agentCommand`)
- `assistant`: gestreamte Deltas aus pi-agent-core
- `tool`: gestreamte Tool-Ereignisse aus pi-agent-core
- `lifecycle`: ausgegeben von `subscribeEmbeddedPiSession` (und als Fallback von `agentCommand`)
- `assistant`: gestreamte Deltas von pi-agent-core
- `tool`: gestreamte Tool-Ereignisse von pi-agent-core
## Chatkanal-Behandlung
## Umgang mit Chat-Kanälen
- Assistant-Deltas werden in Chat-`delta`-Nachrichten gepuffert.
- Ein Chat-`final` wird bei **Lebenszyklus-Ende/-Fehler** ausgegeben.
- Ein Chat-`final` wird bei **Lifecycle-Ende/Fehler** ausgegeben.
## Timeouts
- Standardwert für `agent.wait`: 30 s (nur das Warten). Parameter `timeoutMs` überschreibt ihn.
- Agent-Runtime: `agents.defaults.timeoutSeconds` Standardwert 172800 s (48 Stunden); erzwungen im Abbruch-Timer von `runEmbeddedPiAgent`.
- Cron-Runtime: isoliertes `timeoutSeconds` für Agent-Turns wird von cron verwaltet. Der Scheduler startet diesen Timer, wenn die Ausführung beginnt, bricht die zugrunde liegende Ausführung zur konfigurierten Deadline ab und führt dann begrenzte Bereinigung aus, bevor der Timeout aufgezeichnet wird, sodass eine veraltete Child-Sitzung die Lane nicht blockiert halten kann.
- Wiederherstellung blockierter Sitzungen: Wenn Diagnose aktiviert ist, erkennt `diagnostics.stuckSessionWarnMs` lange `processing`-Sitzungen. Aktive eingebettete Ausführungen, aktive Antwortoperationen und aktive Sitzungs-Lane-Tasks bleiben standardmäßig nur Warnungen; wenn die Diagnose keine aktive Arbeit für die Sitzung zeigt, gibt der Watchdog die betroffene Sitzungs-Lane frei, damit eingereihte Startarbeit abfließen kann.
- Modell-Leerlauf-Timeout: OpenClaw bricht eine Modellanfrage ab, wenn vor Ablauf des Leerlauffensters keine Antwort-Chunks eintreffen. `models.providers.<id>.timeoutSeconds` erweitert diesen Leerlauf-Watchdog für langsame lokale/selbst gehostete Provider; andernfalls verwendet OpenClaw `agents.defaults.timeoutSeconds`, wenn konfiguriert, standardmäßig auf 120 s gedeckelt. Durch Cron ausgelöste Ausführungen ohne explizites Modell- oder Agent-Timeout deaktivieren den Leerlauf-Watchdog und verlassen sich auf den äußeren Cron-Timeout.
- HTTP-Anfrage-Timeout des Providers: `models.providers.<id>.timeoutSeconds` gilt für die Modell-HTTP-Fetches dieses Providers, einschließlich Verbindung, Header, Body, SDK-Anfrage-Timeout, gesamter geschützter Fetch-Abbruchbehandlung und Modell-Stream-Leerlauf-Watchdog. Verwenden Sie dies für langsame lokale/selbst gehostete Provider wie Ollama, bevor Sie den gesamten Agent-Runtime-Timeout erhöhen.
- `agent.wait`-Standardwert: 30 s (nur das Warten). Parameter `timeoutMs` überschreibt dies.
- Agenten-Runtime: `agents.defaults.timeoutSeconds` Standardwert 172800 s (48 Stunden); durch den Abbruch-Timer in `runEmbeddedPiAgent` erzwungen.
- Cron-Runtime: Das `timeoutSeconds` eines isolierten Agent-Turns gehört Cron. Der Scheduler startet diesen Timer, wenn die Ausführung beginnt, bricht den zugrunde liegenden Lauf zum konfigurierten Stichtag ab und führt anschließend begrenztes Cleanup aus, bevor der Timeout aufgezeichnet wird, damit eine veraltete Child-Sitzung die Lane nicht blockiert halten kann.
- Wiederherstellung festhängender Sitzungen: Mit aktivierten Diagnosen erkennt `diagnostics.stuckSessionWarnMs` lange `processing`-Sitzungen. Aktive eingebettete Läufe, aktive Antwortoperationen und aktive Sitzungs-Lane-Aufgaben bleiben standardmäßig nur Warnungen; wenn die Diagnosen keine aktive Arbeit für die Sitzung zeigen, gibt der Watchdog die betroffene Sitzungs-Lane frei, damit aufgereihte Startarbeit abfließen kann.
- Modell-Inaktivitäts-Timeout: OpenClaw bricht eine Modellanfrage ab, wenn vor Ablauf des Inaktivitätsfensters keine Antwort-Chunks eintreffen. `models.providers.<id>.timeoutSeconds` erweitert diesen Inaktivitäts-Watchdog für langsame lokale/selbst gehostete Provider; andernfalls verwendet OpenClaw `agents.defaults.timeoutSeconds`, wenn konfiguriert, standardmäßig bei 120 s gedeckelt. Von Cron ausgelöste Läufe ohne explizites Modell- oder Agent-Timeout deaktivieren den Inaktivitäts-Watchdog und verlassen sich auf den äußeren Cron-Timeout.
- Provider-HTTP-Anfrage-Timeout: `models.providers.<id>.timeoutSeconds` gilt für Modell-HTTP-Fetches dieses Providers, einschließlich Verbindung, Headern, Body, SDK-Anfrage-Timeout, gesamter Guarded-Fetch-Abbruchbehandlung und Modell-Stream-Inaktivitäts-Watchdog. Verwenden Sie dies für langsame lokale/selbst gehostete Provider wie Ollama, bevor Sie den gesamten Agenten-Runtime-Timeout erhöhen.
## Wo Dinge vorzeitig enden können
- Agent-Timeout (Abbruch)
- Agenten-Timeout (Abbruch)
- AbortSignal (Abbrechen)
- Gateway-Trennung oder RPC-Timeout
- `agent.wait`-Timeout (nur Warten, stoppt den Agenten nicht)
## Verwandte Themen
## Verwandt
- [Tools](/de/tools) — verfügbare Agent-Tools
- [Hooks](/de/automation/hooks) — ereignisgesteuerte Skripte, die durch Agent-Lebenszyklusereignisse ausgelöst werden
- [Tools](/de/tools) — verfügbare Agenten-Tools
- [Hooks](/de/automation/hooks) — ereignisgesteuerte Skripte, die durch Agenten-Lifecycle-Ereignisse ausgelöst werden
- [Compaction](/de/concepts/compaction) — wie lange Unterhaltungen zusammengefasst werden
- [Exec-Freigaben](/de/tools/exec-approvals) — Freigabe-Gates für Shell-Befehle
- [Denken](/de/tools/thinking) — Konfiguration der Denk-/Reasoning-Stufe
- [Exec-Genehmigungen](/de/tools/exec-approvals) — Genehmigungsgates für Shell-Befehle
- [Thinking](/de/tools/thinking) — Konfiguration der Thinking-/Reasoning-Stufe

104
docs/de/concepts/queue.md
View File

@ -1,64 +1,64 @@
---
read_when:
- Ausführung oder Parallelität automatischer Antworten ändern
- Erläuterung von /queue-Modi oder des Verhaltens der Nachrichtensteuerung
summary: Modi der Warteschlange für automatische Antworten, Standardeinstellungen und sitzungsspezifische Überschreibungen
- Erläuterung der /queue-Modi oder des Verhaltens zur Nachrichtensteuerung
summary: Warteschlangenmodi, Standardwerte und sitzungsspezifische Überschreibungen für automatische Antworten
title: Befehlswarteschlange
x-i18n:
generated_at: "2026-04-30T06:50:46Z"
generated_at: "2026-04-30T18:38:36Z"
model: gpt-5.5
provider: openai
source_hash: 2ac0c0ded9558b080714fa4b8be0d552f985911bf19b427020f9654ae4955b2d
source_hash: fbf1bb1ffd4ce06fa138f63e31651b8821226d9c95dd6b93d68326a5fb91fdd0
source_path: concepts/queue.md
workflow: 16
---
Wir serialisieren eingehende Auto-Reply-Läufe (alle Kanäle) über eine kleine In-Process-Warteschlange, um zu verhindern, dass mehrere Agent-Läufe kollidieren, während sichere Parallelität über Sitzungen hinweg weiterhin möglich bleibt.
Wir serialisieren eingehende automatische Antwortläufe (alle Kanäle) über eine kleine In-Process-Warteschlange, um zu verhindern, dass mehrere Agentenläufe kollidieren, während sichere Parallelität über Sitzungen hinweg weiterhin möglich ist.
## Warum
- Auto-Reply-Läufe können teuer sein (LLM-Aufrufe) und kollidieren, wenn mehrere eingehende Nachrichten kurz nacheinander eintreffen.
- Automatische Antwortläufe können teuer sein (LLM-Aufrufe) und kollidieren, wenn mehrere eingehende Nachrichten kurz nacheinander eintreffen.
- Serialisierung vermeidet Konkurrenz um gemeinsam genutzte Ressourcen (Sitzungsdateien, Logs, CLI-stdin) und reduziert die Wahrscheinlichkeit von Upstream-Rate-Limits.
## Funktionsweise
- Eine Lane-bewusste FIFO-Warteschlange leert jede Lane mit einer konfigurierbaren Nebenläufigkeitsgrenze (standardmäßig 1 für nicht konfigurierte Lanes; main standardmäßig 4, subagent 8).
- `runEmbeddedPiAgent` reiht nach **Sitzungsschlüssel** ein (Lane `session:<key>`), um zu garantieren, dass pro Sitzung nur ein aktiver Lauf existiert.
- Jeder Sitzungslauf wird anschließend in eine **globale Lane** eingereiht (standardmäßig `main`), sodass die gesamte Parallelität durch `agents.defaults.maxConcurrent` begrenzt wird.
- Wenn ausführliche Protokollierung aktiviert ist, geben eingereihte Läufe einen kurzen Hinweis aus, falls sie vor dem Start mehr als etwa 2 s gewartet haben.
- Tippindikatoren werden weiterhin sofort beim Einreihen ausgelöst (wenn vom Kanal unterstützt), sodass die Benutzererfahrung unverändert bleibt, während wir warten, bis wir an der Reihe sind.
- Eine Lane-bewusste FIFO-Warteschlange leert jede Lane mit einem konfigurierbaren Nebenläufigkeitslimit (Standard 1 für nicht konfigurierte Lanes; main standardmäßig 4, subagent 8).
- `runEmbeddedPiAgent` reiht nach **Sitzungsschlüssel** ein (Lane `session:<key>`), um zu garantieren, dass pro Sitzung nur ein Lauf aktiv ist.
- Jeder Sitzungslauf wird anschließend in eine **globale Lane** eingereiht (`main` standardmäßig), sodass die Gesamtparallelität durch `agents.defaults.maxConcurrent` begrenzt ist.
- Wenn ausführliches Logging aktiviert ist, geben eingereihte Läufe einen kurzen Hinweis aus, wenn sie mehr als ca. 2 s vor dem Start gewartet haben.
- Tippindikatoren werden weiterhin sofort beim Einreihen ausgelöst (wenn vom Kanal unterstützt), sodass die Nutzererfahrung unverändert bleibt, während wir warten, bis wir an der Reihe sind.
## Standardwerte
Wenn nicht festgelegt, verwenden alle eingehenden Kanaloberflächen:
Wenn nicht gesetzt, verwenden alle eingehenden Kanaloberflächen:
- `mode: "steer"`
- `debounceMs: 500`
- `cap: 20`
- `drop: "summarize"`
`steer` ist der Standard, weil es den aktiven Modell-Turn reaktionsschnell hält, ohne
einen zweiten Sitzungslauf zu starten. Es verarbeitet alle Steuerungsnachrichten, die
vor der nächsten Modellgrenze eingetroffen sind. Wenn der aktuelle Lauf keine Steuerung
annehmen kann, fällt OpenClaw auf einen Follow-up-Warteschlangeneintrag zurück.
`steer` ist der Standard, weil es den aktiven Modell-Turn reaktionsfähig hält, ohne
einen zweiten Sitzungslauf zu starten. Es verarbeitet alle Steuerungsnachrichten,
die vor der nächsten Modellgrenze eingetroffen sind. Wenn der aktuelle Lauf keine
Steuerung annehmen kann, fällt OpenClaw auf einen Follow-up-Warteschlangeneintrag zurück.
## Warteschlangenmodi
Eingehende Nachrichten können den aktuellen Lauf steuern, auf einen Follow-up-Turn warten oder beides tun:
- `steer`: Steuerungsnachrichten in die aktive Runtime einreihen. Pi liefert alle ausstehenden Steuerungsnachrichten **nachdem der aktuelle Assistant-Turn die Ausführung seiner Tool-Aufrufe abgeschlossen hat**, vor dem nächsten LLM-Aufruf; der Codex-App-Server erhält ein gebündeltes `turn/steer`. Wenn der Lauf nicht aktiv streamt oder Steuerung nicht verfügbar ist, fällt OpenClaw auf einen Follow-up-Warteschlangeneintrag zurück.
- `queue` (Legacy): alte, einzelne Steuerung nacheinander. Pi liefert an jeder Modellgrenze eine eingereihte Steuerungsnachricht; der Codex-App-Server erhält separate `turn/steer`-Anfragen. Bevorzugen Sie `steer`, sofern Sie nicht das frühere serialisierte Verhalten benötigen.
- `followup`: jede Nachricht für einen späteren Agent-Turn nach Ende des aktuellen Laufs einreihen.
- `collect`: eingereihte Nachrichten nach dem Ruhefenster zu einem **einzigen** Follow-up-Turn zusammenführen. Wenn Nachrichten auf unterschiedliche Kanäle/Threads zielen, werden sie einzeln geleert, um das Routing zu erhalten.
- `steer-backlog` (auch `steer+backlog`): jetzt steuern **und** dieselbe Nachricht für einen Follow-up-Turn beibehalten.
- `interrupt` (Legacy): den aktiven Lauf für diese Sitzung abbrechen und anschließend die neueste Nachricht ausführen.
- `steer`: Steuerungsnachrichten in die aktive Runtime-Warteschlange einreihen. Pi liefert alle ausstehenden Steuerungsnachrichten **nachdem der aktuelle Assistant-Turn seine Tool-Aufrufe fertig ausgeführt hat**, vor dem nächsten LLM-Aufruf; Codex app-server erhält ein gebündeltes `turn/steer`. Wenn der Lauf nicht aktiv streamt oder Steuerung nicht verfügbar ist, fällt OpenClaw auf einen Follow-up-Warteschlangeneintrag zurück.
- `queue` (Legacy): alte Steuerung einzeln nacheinander. Pi liefert an jeder Modellgrenze eine eingereihte Steuerungsnachricht; Codex app-server erhält separate `turn/steer`-Anfragen. Bevorzugen Sie `steer`, sofern Sie nicht das frühere serialisierte Verhalten benötigen.
- `followup`: Jede Nachricht für einen späteren Agenten-Turn einreihen, nachdem der aktuelle Lauf endet.
- `collect`: Eingereihte Nachrichten nach dem Ruhefenster zu einem **einzelnen** Follow-up-Turn zusammenführen. Wenn Nachrichten unterschiedliche Kanäle/Threads adressieren, werden sie einzeln verarbeitet, um das Routing zu erhalten.
- `steer-backlog` (auch `steer+backlog`): jetzt steuern **und** dieselbe Nachricht für einen Follow-up-Turn bewahren.
- `interrupt` (Legacy): Den aktiven Lauf für diese Sitzung abbrechen und dann die neueste Nachricht ausführen.
Steer-backlog bedeutet, dass Sie nach dem gesteuerten Lauf eine Follow-up-Antwort erhalten können, sodass
Streaming-Oberflächen wie Duplikate wirken können. Bevorzugen Sie `collect`/`steer`, wenn Sie
eine Antwort pro eingehender Nachricht möchten.
Steer-backlog bedeutet, dass Sie nach dem gesteuerten Lauf eine Follow-up-Antwort
erhalten können, sodass Streaming-Oberflächen wie Duplikate wirken können.
Bevorzugen Sie `collect`/`steer`, wenn Sie eine Antwort pro eingehender Nachricht wünschen.
Für Runtime-spezifisches Timing und Abhängigkeitsverhalten siehe
[Steuerungswarteschlange](/de/concepts/queue-steering).
Informationen zu runtime-spezifischem Timing und Abhängigkeitsverhalten finden Sie unter
[Steering-Warteschlange](/de/concepts/queue-steering).
Global oder pro Kanal über `messages.queue` konfigurieren:
@ -78,52 +78,54 @@ Global oder pro Kanal über `messages.queue` konfigurieren:
## Warteschlangenoptionen
Optionen gelten für `followup`, `collect` und `steer-backlog` (und für `steer` oder Legacy-`queue`, wenn Steuerung auf Follow-up zurückfällt):
Optionen gelten für `followup`, `collect` und `steer-backlog` (sowie für `steer` oder Legacy-`queue`, wenn Steuerung auf Follow-up zurückfällt):
- `debounceMs`: Ruhefenster vor dem Leeren eingereihter Follow-ups. Reine Zahlen sind Millisekunden; die Einheiten `ms`, `s`, `m`, `h` und `d` werden von `/queue`-Optionen akzeptiert.
- `cap`: maximale Anzahl eingereihter Nachrichten pro Sitzung. Werte unter `1` werden ignoriert.
- `drop: "summarize"`: Standard. Die ältesten eingereihten Einträge bei Bedarf verwerfen, kompakte Zusammenfassungen behalten und sie als synthetischen Follow-up-Prompt einfügen.
- `drop: "old"`: die ältesten eingereihten Einträge bei Bedarf verwerfen, ohne Zusammenfassungen zu behalten.
- `drop: "new"`: die neueste Nachricht ablehnen, wenn die Warteschlange bereits voll ist.
- `debounceMs`: Ruhefenster vor dem Verarbeiten eingereihter Follow-ups. Reine Zahlen sind Millisekunden; die Einheiten `ms`, `s`, `m`, `h` und `d` werden von `/queue`-Optionen akzeptiert.
- `cap`: Maximale Anzahl eingereihter Nachrichten pro Sitzung. Werte unter `1` werden ignoriert.
- `drop: "summarize"`: Standard. Die ältesten eingereihten Einträge bei Bedarf verwerfen, kompakte Zusammenfassungen behalten und diese als synthetischen Follow-up-Prompt einfügen.
- `drop: "old"`: Die ältesten eingereihten Einträge bei Bedarf verwerfen, ohne Zusammenfassungen zu bewahren.
- `drop: "new"`: Die neueste Nachricht ablehnen, wenn die Warteschlange bereits voll ist.
Standardwerte: `debounceMs: 500`, `cap: 20`, `drop: summarize`.
## Vorrang
## Priorität
Für die Modusauswahl löst OpenClaw auf:
Für die Modusauswahl löst OpenClaw wie folgt auf:
1. Inline- oder gespeicherte sitzungsspezifische `/queue`-Überschreibung.
1. Inline oder gespeicherter sitzungsspezifischer `/queue`-Override.
2. `messages.queue.byChannel.<channel>`.
3. `messages.queue.mode`.
4. Standard `steer`.
Für Optionen haben Inline- oder gespeicherte `/queue`-Optionen Vorrang vor der Konfiguration. Danach werden
kanalspezifisches Debounce (`messages.queue.debounceMsByChannel`), Plugin-
Für Optionen haben Inline- oder gespeicherte `/queue`-Optionen Vorrang vor der Konfiguration. Danach
werden kanalspezifisches Debounce (`messages.queue.debounceMsByChannel`), Plugin-
Debounce-Standardwerte, globale `messages.queue`-Optionen und eingebaute Standardwerte
angewendet. `cap` und `drop` sind globale/Sitzungsoptionen, keine kanalspezifischen Konfigurationsschlüssel.
angewendet. `cap` und `drop` sind globale/Sitzungsoptionen, keine kanalspezifischen
Konfigurationsschlüssel.
## Sitzungsspezifische Überschreibungen
## Sitzungsspezifische Overrides
- Senden Sie `/queue <mode>` als eigenständigen Befehl, um den Modus für die aktuelle Sitzung zu speichern.
- Optionen können kombiniert werden: `/queue collect debounce:0.5s cap:25 drop:summarize`
- `/queue default` oder `/queue reset` löscht die Sitzungsüberschreibung.
- `/queue default` oder `/queue reset` löscht den Sitzungs-Override.
## Geltungsbereich und Garantien
## Umfang und Garantien
- Gilt für Auto-Reply-Agent-Läufe über alle eingehenden Kanäle hinweg, die die Gateway-Antwortpipeline verwenden (WhatsApp Web, Telegram, Slack, Discord, Signal, iMessage, Webchat usw.).
- Die Standard-Lane (`main`) ist prozessweit für eingehende Nachrichten und Haupt-Heartbeats; setzen Sie `agents.defaults.maxConcurrent`, um mehrere Sitzungen parallel zu erlauben.
- Zusätzliche Lanes können existieren (z. B. `cron`, `cron-nested`, `nested`, `subagent`), sodass Hintergrundjobs parallel laufen können, ohne eingehende Antworten zu blockieren. Isolierte Cron-Agent-Turns belegen einen `cron`-Slot, während ihre innere Agent-Ausführung `cron-nested` verwendet; beide verwenden `cron.maxConcurrentRuns`. Gemeinsame Nicht-Cron-`nested`-Abläufe behalten ihr eigenes Lane-Verhalten. Diese entkoppelten Läufe werden als [Hintergrundaufgaben](/de/automation/tasks) nachverfolgt.
- Sitzungsspezifische Lanes garantieren, dass jeweils nur ein Agent-Lauf eine bestimmte Sitzung berührt.
- Gilt für automatische Agentenantwortläufe über alle eingehenden Kanäle hinweg, die die Gateway-Antwortpipeline verwenden (WhatsApp Web, Telegram, Slack, Discord, Signal, iMessage, Webchat usw.).
- Die Standard-Lane (`main`) ist prozessweit für eingehende Antworten + Haupt-Heartbeats; setzen Sie `agents.defaults.maxConcurrent`, um mehrere Sitzungen parallel zuzulassen.
- Zusätzliche Lanes können existieren (z. B. `cron`, `cron-nested`, `nested`, `subagent`), sodass Hintergrundjobs parallel laufen können, ohne eingehende Antworten zu blockieren. Isolierte Cron-Agenten-Turns belegen einen `cron`-Slot, während ihre innere Agentenausführung `cron-nested` verwendet; beide nutzen `cron.maxConcurrentRuns`. Geteilte Nicht-Cron-`nested`-Abläufe behalten ihr eigenes Lane-Verhalten. Diese entkoppelten Läufe werden als [Hintergrundaufgaben](/de/automation/tasks) nachverfolgt.
- Sitzungsspezifische Lanes garantieren, dass jeweils nur ein Agentenlauf eine bestimmte Sitzung berührt.
- Keine externen Abhängigkeiten oder Hintergrund-Worker-Threads; reines TypeScript + Promises.
## Fehlerbehebung
- Wenn Befehle festzustecken scheinen, aktivieren Sie ausführliche Logs und suchen Sie nach Zeilen wie „queued for …ms“, um zu bestätigen, dass die Warteschlange geleert wird.
- Wenn Befehle festzustecken scheinen, aktivieren Sie ausführliche Logs und suchen Sie nach Zeilen „queued for …ms“, um zu bestätigen, dass die Warteschlange verarbeitet wird.
- Wenn Sie die Warteschlangentiefe benötigen, aktivieren Sie ausführliche Logs und achten Sie auf Warteschlangen-Timing-Zeilen.
- Wenn Diagnosen aktiviert sind, protokollieren Sitzungen, die über `diagnostics.stuckSessionWarnMs` hinaus in `processing` bleiben, eine Warnung zu feststeckenden Sitzungen. Aktive eingebettete Läufe, aktive Antwortoperationen und aktive Lane-Aufgaben bleiben standardmäßig reine Warnungen; veraltete Startbuchhaltung ohne aktive Sitzungsarbeit kann die betroffene Sitzungs-Lane freigeben, sodass eingereihte Arbeit abläuft.
- Codex app-server-Läufe, die einen Turn annehmen und dann keinen Fortschritt mehr ausgeben, werden vom Codex-Adapter unterbrochen, damit die aktive Sitzungs-Lane freigegeben werden kann, statt auf das Timeout des äußeren Laufs zu warten.
- Wenn Diagnosen aktiviert sind, protokollieren Sitzungen, die über `diagnostics.stuckSessionWarnMs` hinaus in `processing` bleiben, eine Warnung zu einer festhängenden Sitzung. Aktive eingebettete Läufe, aktive Antwortoperationen und aktive Lane-Aufgaben bleiben standardmäßig reine Warnungen; veraltete Startbuchhaltung ohne aktive Sitzungsarbeit kann die betroffene Sitzungs-Lane freigeben, sodass eingereihte Arbeit verarbeitet wird.
## Verwandte Themen
## Verwandt
- [Sitzungsverwaltung](/de/concepts/session)
- [Steuerungswarteschlange](/de/concepts/queue-steering)
- [Retry-Richtlinie](/de/concepts/retry)
- [Steering-Warteschlange](/de/concepts/queue-steering)
- [Wiederholungsrichtlinie](/de/concepts/retry)

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

File diff suppressed because it is too large Load Diff

113
docs/de/reference/test.md
View File

@ -1,58 +1,59 @@
---
read_when:
- Tests ausführen oder reparieren
summary: Wie Sie Tests lokal ausführen (vitest) und wann Sie Force-/Coverage-Modi verwenden
- Tests ausführen oder korrigieren
summary: So führen Sie Tests lokal aus (vitest) und wann Sie Erzwingungs- oder Testabdeckungsmodi verwenden
title: Tests
x-i18n:
generated_at: "2026-04-30T07:14:13Z"
generated_at: "2026-04-30T18:38:31Z"
model: gpt-5.5
provider: openai
source_hash: 9328d6f0383b5067fa8bb5d0f1bf22a3b9048a267908bf85167842ddc3d12e42
source_hash: 131f2bad3b2806d28394213cec38d632d106ddbf8ff04d06345ab8046fb8bcf2
source_path: reference/test.md
workflow: 16
---
- Vollständiges Test-Kit (Testsammlungen, Live-Tests, Docker): [Tests](/de/help/testing)
- Vollständiges Testkit (Suites, Live, Docker): [Testen](/de/help/testing)
- `pnpm test:force`: Beendet jeden verbleibenden Gateway-Prozess, der den standardmäßigen Control-Port hält, und führt dann die vollständige Vitest-Suite mit einem isolierten Gateway-Port aus, damit Server-Tests nicht mit einer laufenden Instanz kollidieren. Verwenden Sie dies, wenn ein vorheriger Gateway-Lauf Port 18789 belegt gelassen hat.
- `pnpm test:coverage`: Führt die Unit-Suite mit V8-Coverage aus (über `vitest.unit.config.ts`). Dies ist ein Coverage-Gate für geladene Unit-Dateien, keine All-File-Coverage für das gesamte Repository. Die Schwellenwerte sind 70 % für Zeilen/Funktionen/Anweisungen und 55 % für Branches. Da `coverage.all` false ist, misst das Gate Dateien, die von der Unit-Coverage-Suite geladen werden, statt jede Split-Lane-Quelldatei als nicht abgedeckt zu behandeln.
- `pnpm test:coverage:changed`: Führt Unit-Coverage nur für Dateien aus, die sich seit `origin/main` geändert haben.
- `pnpm test:changed`: günstiger intelligenter Changed-Testlauf. Er führt präzise Ziele aus direkten Teständerungen, benachbarten `*.test.ts`-Dateien, expliziten Quellzuordnungen und dem lokalen Importgraphen aus. Breite/config/package-Änderungen werden übersprungen, sofern sie nicht auf präzise Tests abbilden.
- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: expliziter breiter Changed-Testlauf. Verwenden Sie dies, wenn eine Änderung an Test-Harness/config/package auf das breitere Changed-Test-Verhalten von Vitest zurückfallen soll.
- `pnpm changed:lanes`: zeigt die architektonischen Lanes, die durch den Diff gegen `origin/main` ausgelöst werden.
- `pnpm check:changed`: führt das intelligente Changed-Check-Gate für den Diff gegen `origin/main` aus. Es führt Typecheck-, Lint- und Guard-Befehle für die betroffenen architektonischen Lanes aus, aber keine Vitest-Tests. Verwenden Sie `pnpm test:changed` oder explizit `pnpm test <target>` als Testnachweis.
- `pnpm test`: leitet explizite Datei-/Verzeichnisziele durch scoped Vitest-Lanes. Läufe ohne Ziel verwenden feste Shard-Gruppen und werden für lokale parallele Ausführung auf Leaf-Configs erweitert; die Plugin-Gruppe wird immer auf die Shard-Configs pro Plugin erweitert statt auf einen riesigen Root-Project-Prozess.
- `pnpm test:force`: Beendet jeden verbleibenden Gateway-Prozess, der den standardmäßigen Control-Port belegt, und führt dann die vollständige Vitest-Suite mit einem isolierten Gateway-Port aus, damit Server-Tests nicht mit einer laufenden Instanz kollidieren. Verwenden Sie dies, wenn ein vorheriger Gateway-Lauf Port 18789 belegt gelassen hat.
- `pnpm test:coverage`: Führt die Unit-Suite mit V8-Coverage aus (über `vitest.unit.config.ts`). Dies ist ein Unit-Coverage-Gate für geladene Dateien, keine Whole-Repo-All-File-Coverage. Die Schwellenwerte liegen bei 70 % für Zeilen/Funktionen/Statements und 55 % für Branches. Da `coverage.all` false ist, misst das Gate Dateien, die von der Unit-Coverage-Suite geladen werden, anstatt jede Split-Lane-Quelldatei als nicht abgedeckt zu behandeln.
- `pnpm test:coverage:changed`: Führt Unit-Coverage nur für Dateien aus, die seit `origin/main` geändert wurden.
- `pnpm test:changed`: günstiger intelligenter Changed-Test-Lauf. Er führt präzise Ziele aus direkten Teständerungen, benachbarten `*.test.ts`-Dateien, expliziten Quellzuordnungen und dem lokalen Importgraphen aus. Breite/config/package-Änderungen werden übersprungen, sofern sie nicht auf präzise Tests abbilden.
- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: expliziter breiter Changed-Test-Lauf. Verwenden Sie dies, wenn eine Änderung an Test-Harness/config/package auf das breitere Changed-Test-Verhalten von Vitest zurückfallen soll.
- `pnpm changed:lanes`: zeigt die durch den Diff gegen `origin/main` ausgelösten Architektur-Lanes.
- `pnpm check:changed`: führt das intelligente Changed-Check-Gate für den Diff gegen `origin/main` aus. Es führt Typecheck-, Lint- und Guard-Befehle für die betroffenen Architektur-Lanes aus, führt aber keine Vitest-Tests aus. Verwenden Sie `pnpm test:changed` oder explizit `pnpm test <target>` als Testnachweis.
- `pnpm test`: routet explizite Datei-/Verzeichnisziele durch scoped Vitest-Lanes. Nicht zielgerichtete Läufe verwenden feste Shard-Gruppen und erweitern auf Leaf-Configs für lokale parallele Ausführung; die Extension-Gruppe wird immer zu den pro Extension definierten Shard-Configs erweitert, statt zu einem einzigen riesigen Root-Project-Prozess.
- Test-Wrapper-Läufe enden mit einer kurzen Zusammenfassung `[test] passed|failed|skipped ... in ...`. Die eigene Dauerzeile von Vitest bleibt das Detail pro Shard.
- Gemeinsamer OpenClaw-Testzustand: Verwenden Sie `src/test-utils/openclaw-test-state.ts` aus Vitest, wenn ein Test ein isoliertes `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, ein Config-Fixture, einen Workspace, ein Agent-Verzeichnis oder einen Auth-Profile-Store benötigt.
- Process-E2E-Helfer: Verwenden Sie `test/helpers/openclaw-test-instance.ts`, wenn ein Vitest-Prozess-Level-E2E-Test einen laufenden Gateway, CLI-Env, Log-Erfassung und Cleanup an einer Stelle benötigt.
- Docker/Bash-E2E-Helfer: Lanes, die `scripts/lib/docker-e2e-image.sh` sourcen, können `docker_e2e_test_state_shell_b64 <label> <scenario>` in den Container übergeben und mit `scripts/lib/openclaw-e2e-instance.sh` dekodieren; Multi-Home-Skripte können `docker_e2e_test_state_function_b64` übergeben und in jedem Flow `openclaw_test_state_create <label> <scenario>` aufrufen. Low-Level-Aufrufer können `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` für ein In-Container-Shell-Snippet verwenden oder `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` für eine sourcebare Host-Env-Datei. Das `--` vor `create` verhindert, dass neuere Node-Runtimes `--env-file` als Node-Flag behandeln. Docker/Bash-Lanes, die einen Gateway starten, können `scripts/lib/openclaw-e2e-instance.sh` innerhalb des Containers sourcen, für Entrypoint-Auflösung, Mock-OpenAI-Start, Gateway-Foreground-/Background-Start, Readiness-Probes, State-Env-Export, Log-Dumps und Prozess-Cleanup.
- Vollständige, Plugin- und Include-Pattern-Shard-Läufe aktualisieren lokale Timing-Daten in `.artifacts/vitest-shard-timings.json`; spätere Whole-Config-Läufe verwenden diese Timings, um langsame und schnelle Shards auszubalancieren. Include-Pattern-CI-Shards hängen den Shard-Namen an den Timing-Schlüssel an, wodurch gefilterte Shard-Timings sichtbar bleiben, ohne Whole-Config-Timing-Daten zu ersetzen. Setzen Sie `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, um das lokale Timing-Artefakt zu ignorieren.
- Ausgewählte `plugin-sdk`- und `commands`-Testdateien laufen nun über dedizierte leichte Lanes, die nur `test/setup.ts` behalten und runtime-lastige Fälle auf ihren bestehenden Lanes lassen.
- Quelldateien mit benachbarten Tests werden zuerst auf diesen Nachbartest abgebildet, bevor auf breitere Verzeichnis-Globs zurückgefallen wird. Helper-Änderungen unter `src/channels/plugins/contracts/test-helpers`, `src/plugin-sdk/test-helpers` und `src/plugins/contracts` verwenden einen lokalen Importgraphen, um importierende Tests auszuführen, statt jeden Shard breit auszuführen, wenn der Abhängigkeitspfad präzise ist.
- `auto-reply` wird nun ebenfalls in drei dedizierte Configs (`core`, `top-level`, `reply`) aufgeteilt, damit der Reply-Harness die leichteren Top-Level-Status-/Token-/Helper-Tests nicht dominiert.
- Die Basis-Vitest-Config verwendet nun standardmäßig `pool: "threads"` und `isolate: false`, wobei der gemeinsame nicht isolierte Runner in allen Repo-Configs aktiviert ist.
- Gemeinsamer OpenClaw-Testzustand: Verwenden Sie `src/test-utils/openclaw-test-state.ts` aus Vitest, wenn ein Test ein isoliertes `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, eine Config-Fixture, einen Workspace, ein Agent-Verzeichnis oder einen Auth-Profile-Store benötigt.
- Prozess-E2E-Helfer: Verwenden Sie `test/helpers/openclaw-test-instance.ts`, wenn ein Vitest-Prozess-Level-E2E-Test ein laufendes Gateway, CLI-Env, Log-Erfassung und Cleanup an einer Stelle benötigt.
- Docker-/Bash-E2E-Helfer: Lanes, die `scripts/lib/docker-e2e-image.sh` sourcen, können `docker_e2e_test_state_shell_b64 <label> <scenario>` in den Container übergeben und mit `scripts/lib/openclaw-e2e-instance.sh` dekodieren; Multi-Home-Skripte können `docker_e2e_test_state_function_b64` übergeben und in jedem Flow `openclaw_test_state_create <label> <scenario>` aufrufen. Low-Level-Aufrufer können `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` für ein In-Container-Shell-Snippet verwenden oder `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` für eine sourcebare Host-Env-Datei. Das `--` vor `create` verhindert, dass neuere Node-Runtimes `--env-file` als Node-Flag behandeln. Docker-/Bash-Lanes, die ein Gateway starten, können `scripts/lib/openclaw-e2e-instance.sh` im Container sourcen für Entrypoint-Auflösung, Mock-OpenAI-Start, Gateway-Vordergrund-/Hintergrundstart, Readiness-Probes, State-Env-Export, Log-Dumps und Prozess-Cleanup.
- Full-, Extension- und Include-Pattern-Shard-Läufe aktualisieren lokale Timing-Daten in `.artifacts/vitest-shard-timings.json`; spätere Whole-Config-Läufe verwenden diese Timings, um langsame und schnelle Shards auszubalancieren. Include-Pattern-CI-Shards hängen den Shard-Namen an den Timing-Schlüssel an, wodurch gefilterte Shard-Timings sichtbar bleiben, ohne Whole-Config-Timing-Daten zu ersetzen. Setzen Sie `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, um das lokale Timing-Artefakt zu ignorieren.
- Ausgewählte `plugin-sdk`- und `commands`-Testdateien routen jetzt durch dedizierte leichte Lanes, die nur `test/setup.ts` beibehalten, während runtime-lastige Fälle auf ihren bestehenden Lanes bleiben.
- Quelldateien mit benachbarten Tests werden zuerst auf diesen benachbarten Test abgebildet, bevor auf breitere Verzeichnis-Globs zurückgefallen wird. Helferänderungen unter `src/channels/plugins/contracts/test-helpers`, `src/plugin-sdk/test-helpers` und `src/plugins/contracts` verwenden einen lokalen Importgraphen, um importierende Tests auszuführen, statt jeden Shard breit auszuführen, wenn der Dependency-Pfad präzise ist.
- `auto-reply` wird jetzt ebenfalls in drei dedizierte Configs (`core`, `top-level`, `reply`) aufgeteilt, damit das Reply-Harness die leichteren Top-Level-Status-/Token-/Helper-Tests nicht dominiert.
- Die Basis-Vitest-Config verwendet jetzt standardmäßig `pool: "threads"` und `isolate: false`, wobei der gemeinsame nicht isolierte Runner in allen Repo-Configs aktiviert ist.
- `pnpm test:channels` führt `vitest.channels.config.ts` aus.
- `pnpm test:extensions` und `pnpm test extensions` führen alle Plugin-Shards aus. Schwere Channel-Plugins, das Browser-Plugin und OpenAI laufen als dedizierte Shards; andere Plugin-Gruppen bleiben gebündelt. Verwenden Sie `pnpm test extensions/<id>` für eine gebündelte Plugin-Lane.
- `pnpm test:perf:imports`: aktiviert Vitest-Importdauer- und Importaufschlüsselungsberichte, verwendet aber weiterhin scoped Lane-Routing für explizite Datei-/Verzeichnisziele.
- `pnpm test:perf:imports:changed`: dasselbe Import-Profiling, aber nur für Dateien, die sich seit `origin/main` geändert haben.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` benchmarked den gerouteten Changed-Mode-Pfad gegen den nativen Root-Project-Lauf für denselben committed Git-Diff.
- `pnpm test:perf:changed:bench -- --worktree` benchmarked das aktuelle Worktree-Change-Set, ohne zuerst zu committen.
- `pnpm test:extensions` und `pnpm test extensions` führen alle Extension-/Plugin-Shards aus. Schwere Channel-Plugins, das Browser-Plugin und OpenAI laufen als dedizierte Shards; andere Plugin-Gruppen bleiben gebündelt. Verwenden Sie `pnpm test extensions/<id>` für eine gebündelte Plugin-Lane.
- `pnpm test:perf:imports`: aktiviert Vitest-Berichte zu Importdauer und Importaufschlüsselung, während weiterhin scoped Lane-Routing für explizite Datei-/Verzeichnisziele verwendet wird.
- `pnpm test:perf:imports:changed`: gleiches Import-Profiling, aber nur für Dateien, die seit `origin/main` geändert wurden.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` benchmarked den gerouteten Changed-Mode-Pfad gegen den nativen Root-Project-Lauf für denselben committeten Git-Diff.
- `pnpm test:perf:changed:bench -- --worktree` benchmarked das aktuelle Worktree-Changeset, ohne zuerst zu committen.
- `pnpm test:perf:profile:main`: schreibt ein CPU-Profil für den Vitest-Main-Thread (`.artifacts/vitest-main-profile`).
- `pnpm test:perf:profile:runner`: schreibt CPU- und Heap-Profile für den Unit-Runner (`.artifacts/vitest-runner-profile`).
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: führt jede Full-Suite-Vitest-Leaf-Config seriell aus und schreibt gruppierte Dauerdaten plus JSON-/Log-Artefakte pro Config. Der Test Performance Agent verwendet dies als Baseline, bevor er versucht, Slow-Test-Fixes vorzunehmen.
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: vergleicht gruppierte Berichte nach einer performancefokussierten Änderung.
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: führt jede Full-Suite-Vitest-Leaf-Config seriell aus und schreibt gruppierte Dauerdaten sowie JSON-/Log-Artefakte pro Config. Der Test Performance Agent verwendet dies als Baseline, bevor er Slow-Test-Fixes versucht.
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: vergleicht gruppierte Berichte nach einer performanceorientierten Änderung.
- Gateway-Integration: Opt-in über `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` oder `pnpm test:gateway`.
- `pnpm test:e2e`: Führt Gateway-End-to-End-Smoke-Tests aus (Multi-Instance-WS/HTTP/node-Pairing). Standardmäßig `threads` + `isolate: false` mit adaptiven Workern in `vitest.e2e.config.ts`; justieren Sie mit `OPENCLAW_E2E_WORKERS=<n>` und setzen Sie `OPENCLAW_E2E_VERBOSE=1` für ausführliche Logs.
- `pnpm test:live`: Führt Provider-Live-Tests aus (minimax/zai). Erfordert API-Schlüssel und `LIVE=1` (oder Provider-spezifisch `*_LIVE_TEST=1`), um das Überspringen aufzuheben.
- `pnpm test:docker:all`: Baut das gemeinsame Live-Test-Image, packt OpenClaw einmal als npm-Tarball, baut/verwendet ein Bare-Node/Git-Runner-Image plus ein funktionales Image wieder, das diesen Tarball in `/app` installiert, und führt dann Docker-Smoke-Lanes mit `OPENCLAW_SKIP_DOCKER_BUILD=1` über einen gewichteten Scheduler aus. Das Bare-Image (`OPENCLAW_DOCKER_E2E_BARE_IMAGE`) wird für Installer-/Update-/Plugin-Dependency-Lanes verwendet; diese Lanes mounten den vorgebauten Tarball statt kopierter Repo-Quellen. Das funktionale Image (`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`) wird für normale Built-App-Funktionalitäts-Lanes verwendet. `scripts/package-openclaw-for-docker.mjs` ist der einzige lokale/CI-Package-Packer und validiert den Tarball plus `dist/postinstall-inventory.json`, bevor Docker ihn verwendet. Docker-Lane-Definitionen liegen in `scripts/lib/docker-e2e-scenarios.mjs`; die Planner-Logik liegt in `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` führt den ausgewählten Plan aus. `node scripts/test-docker-all.mjs --plan-json` gibt den scheduler-eigenen CI-Plan für ausgewählte Lanes, Image-Arten, Package-/Live-Image-Bedarf, State-Szenarien und Credential-Checks aus, ohne Docker zu bauen oder auszuführen. `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` steuert Prozess-Slots und ist standardmäßig 10; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` steuert den Provider-sensitiven Tail-Pool und ist standardmäßig 10. Caps für schwere Lanes sind standardmäßig `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` und `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; Provider-Caps sind standardmäßig eine schwere Lane pro Provider über `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` und `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`. Verwenden Sie `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` oder `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` für größere Hosts. Wenn eine Lane auf einem Host mit geringer Parallelität das effektive Gewicht oder Resource-Cap überschreitet, kann sie dennoch aus einem leeren Pool starten und läuft allein, bis sie Kapazität freigibt. Lane-Starts werden standardmäßig um 2 Sekunden versetzt, um lokale Docker-Daemon-Create-Spitzen zu vermeiden; überschreiben Sie dies mit `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. Der Runner führt standardmäßig einen Docker-Preflight aus, bereinigt veraltete OpenClaw-E2E-Container, gibt alle 30 Sekunden Active-Lane-Status aus, teilt Provider-CLI-Tool-Caches zwischen kompatiblen Lanes, wiederholt transiente Live-Provider-Fehler standardmäßig einmal (`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`) und speichert Lane-Timings in `.artifacts/docker-tests/lane-timings.json` für Longest-First-Reihenfolge bei späteren Läufen. Verwenden Sie `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, um das Lane-Manifest ohne Docker-Lauf auszugeben, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>`, um die Statusausgabe zu justieren, oder `OPENCLAW_DOCKER_ALL_TIMINGS=0`, um Timing-Wiederverwendung zu deaktivieren. Verwenden Sie `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` nur für deterministische/lokale Lanes oder `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` nur für Live-Provider-Lanes; Package-Aliasse sind `pnpm test:docker:local:all` und `pnpm test:docker:live:all`. Der Live-Only-Modus führt Main- und Tail-Live-Lanes zu einem Longest-First-Pool zusammen, damit Provider-Buckets Claude-, Codex- und Gemini-Arbeit gemeinsam packen können. Der Runner plant nach dem ersten Fehler keine neuen gepoolten Lanes mehr, sofern `OPENCLAW_DOCKER_ALL_FAIL_FAST=0` nicht gesetzt ist, und jede Lane hat einen 120-Minuten-Fallback-Timeout, überschreibbar mit `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; ausgewählte Live-/Tail-Lanes verwenden engere Caps pro Lane. CLI-Backend-Docker-Setup-Befehle haben ihren eigenen Timeout über `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` (Standard 180). Logs pro Lane, `summary.json`, `failures.json` und Phase-Timings werden unter `.artifacts/docker-tests/<run-id>/` geschrieben; verwenden Sie `pnpm test:docker:timings <summary.json>`, um langsame Lanes zu untersuchen, und `pnpm test:docker:rerun <run-id|summary.json|failures.json>`, um günstige gezielte Rerun-Befehle auszugeben.
- `pnpm test:docker:browser-cdp-snapshot`: Baut einen Chromium-gestützten Source-E2E-Container, startet rohes CDP plus einen isolierten Gateway, führt `browser doctor --deep` aus und verifiziert, dass CDP-Rollen-Snapshots Link-URLs, cursor-promoted Clickables, iframe-Refs und Frame-Metadaten enthalten.
- CLI-Backend-Live-Docker-Probes können als fokussierte Lanes ausgeführt werden, zum Beispiel `pnpm test:docker:live-cli-backend:codex`, `pnpm test:docker:live-cli-backend:codex:resume` oder `pnpm test:docker:live-cli-backend:codex:mcp`. Claude und Gemini haben passende `:resume`- und `:mcp`-Aliasse.
- `pnpm test:docker:openwebui`: Startet dockerisiertes OpenClaw + Open WebUI, meldet sich über Open WebUI an, prüft `/api/models` und führt dann einen echten proxied Chat über `/api/chat/completions` aus. Erfordert einen verwendbaren Live-Model-Schlüssel (zum Beispiel OpenAI in `~/.profile`), zieht ein externes Open-WebUI-Image und wird nicht als CI-stabil wie die normalen Unit-/E2E-Suiten erwartet.
- `pnpm test:docker:mcp-channels`: Startet einen seeded Gateway-Container und einen zweiten Client-Container, der `openclaw mcp serve` startet, und verifiziert dann geroutete Conversation-Discovery, Transcript-Reads, Attachment-Metadaten, Live-Event-Queue-Verhalten, Outbound-Send-Routing sowie Channel- und Permission-Benachrichtigungen im Claude-Stil über die echte stdio-Bridge. Die Claude-Benachrichtigungs-Assertion liest die rohen stdio-MCP-Frames direkt, damit der Smoke widerspiegelt, was die Bridge tatsächlich emittiert.
- `pnpm test:e2e`: Führt Gateway-End-to-End-Smoke-Tests aus (Multi-Instance-WS/HTTP/Node-Pairing). Verwendet standardmäßig `threads` + `isolate: false` mit adaptiven Workern in `vitest.e2e.config.ts`; passen Sie dies mit `OPENCLAW_E2E_WORKERS=<n>` an und setzen Sie `OPENCLAW_E2E_VERBOSE=1` für ausführliche Logs.
- `pnpm test:live`: Führt Provider-Live-Tests aus (minimax/zai). Erfordert API-Schlüssel und `LIVE=1` (oder Provider-spezifisch `*_LIVE_TEST=1`), um sie nicht zu überspringen.
- `pnpm test:docker:all`: Baut das gemeinsame Live-Test-Image, packt OpenClaw einmal als npm-Tarball, baut/verwendet ein Bare-Node-/Git-Runner-Image plus ein funktionales Image, das diesen Tarball in `/app` installiert, und führt dann Docker-Smoke-Lanes mit `OPENCLAW_SKIP_DOCKER_BUILD=1` über einen gewichteten Scheduler aus. Das Bare-Image (`OPENCLAW_DOCKER_E2E_BARE_IMAGE`) wird für Installer-/Update-/Plugin-Dependency-Lanes verwendet; diese Lanes mounten den vorgebauten Tarball, statt kopierte Repo-Quellen zu verwenden. Das funktionale Image (`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`) wird für normale Built-App-Funktionalitäts-Lanes verwendet. `scripts/package-openclaw-for-docker.mjs` ist der einzige lokale/CI-Package-Packer und validiert den Tarball sowie `dist/postinstall-inventory.json`, bevor Docker ihn verwendet. Docker-Lane-Definitionen befinden sich in `scripts/lib/docker-e2e-scenarios.mjs`; die Planner-Logik befindet sich in `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` führt den ausgewählten Plan aus. `node scripts/test-docker-all.mjs --plan-json` gibt den Scheduler-eigenen CI-Plan für ausgewählte Lanes, Image-Arten, Package-/Live-Image-Anforderungen, State-Szenarien und Credential-Prüfungen aus, ohne Docker zu bauen oder auszuführen. `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` steuert Prozess-Slots und ist standardmäßig 10; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` steuert den Provider-sensitiven Tail-Pool und ist standardmäßig 10. Die Caps für schwere Lanes sind standardmäßig `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` und `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; Provider-Caps sind standardmäßig eine schwere Lane pro Provider über `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` und `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`. Verwenden Sie `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` oder `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` für größere Hosts. Wenn eine Lane auf einem Host mit niedriger Parallelität das effektive Gewicht oder Resource-Cap überschreitet, kann sie dennoch aus einem leeren Pool starten und läuft allein, bis sie Kapazität freigibt. Lane-Starts werden standardmäßig um 2 Sekunden versetzt, um lokale Docker-Daemon-Create-Stürme zu vermeiden; überschreiben Sie dies mit `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. Der Runner führt standardmäßig Docker-Preflights aus, bereinigt veraltete OpenClaw-E2E-Container, gibt alle 30 Sekunden Active-Lane-Status aus, teilt Provider-CLI-Tool-Caches zwischen kompatiblen Lanes, wiederholt transiente Live-Provider-Fehler standardmäßig einmal (`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`) und speichert Lane-Timings in `.artifacts/docker-tests/lane-timings.json` für Longest-First-Sortierung bei späteren Läufen. Verwenden Sie `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, um das Lane-Manifest ohne Docker-Lauf auszugeben, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>`, um die Statusausgabe anzupassen, oder `OPENCLAW_DOCKER_ALL_TIMINGS=0`, um Timing-Wiederverwendung zu deaktivieren. Verwenden Sie `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` nur für deterministische/lokale Lanes oder `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` nur für Live-Provider-Lanes; Package-Aliasse sind `pnpm test:docker:local:all` und `pnpm test:docker:live:all`. Der Live-Only-Modus führt Main- und Tail-Live-Lanes zu einem Longest-First-Pool zusammen, damit Provider-Buckets Claude-, Codex- und Gemini-Arbeit gemeinsam packen können. Der Runner plant nach dem ersten Fehler keine neuen gepoolten Lanes mehr ein, sofern `OPENCLAW_DOCKER_ALL_FAIL_FAST=0` nicht gesetzt ist, und jede Lane hat ein 120-Minuten-Fallback-Timeout, das mit `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` überschrieben werden kann; ausgewählte Live-/Tail-Lanes verwenden engere Caps pro Lane. CLI-Backend-Docker-Setup-Befehle haben ein eigenes Timeout über `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` (Standard 180). Logs pro Lane, `summary.json`, `failures.json` und Phase-Timings werden unter `.artifacts/docker-tests/<run-id>/` geschrieben; verwenden Sie `pnpm test:docker:timings <summary.json>`, um langsame Lanes zu untersuchen, und `pnpm test:docker:rerun <run-id|summary.json|failures.json>`, um günstige zielgerichtete Rerun-Befehle auszugeben.
- `pnpm test:docker:browser-cdp-snapshot`: Baut einen Chromium-gestützten Source-E2E-Container, startet raw CDP plus ein isoliertes Gateway, führt `browser doctor --deep` aus und verifiziert, dass CDP-Rollen-Snapshots Link-URLs, cursor-promoted Clickables, iframe-Refs und Frame-Metadaten enthalten.
- CLI-Backend-Live-Docker-Probes können als fokussierte Lanes ausgeführt werden, zum Beispiel `pnpm test:docker:live-cli-backend:codex`, `pnpm test:docker:live-cli-backend:codex:resume` oder `pnpm test:docker:live-cli-backend:codex:mcp`. Claude und Gemini haben entsprechende `:resume`- und `:mcp`-Aliasse.
- `pnpm test:docker:openwebui`: Startet Dockerized OpenClaw + Open WebUI, meldet sich über Open WebUI an, prüft `/api/models` und führt dann einen echten proxied Chat über `/api/chat/completions` aus. Erfordert einen nutzbaren Live-Modellschlüssel (zum Beispiel OpenAI in `~/.profile`), zieht ein externes Open WebUI-Image und wird nicht als CI-stabil wie die normalen Unit-/E2E-Suites erwartet.
- `pnpm test:docker:mcp-channels`: Startet einen geseedeten Gateway-Container und einen zweiten Client-Container, der `openclaw mcp serve` startet, und verifiziert dann geroutete Conversation-Discovery, Transcript-Reads, Attachment-Metadaten, Live-Event-Queue-Verhalten, Outbound-Send-Routing sowie Claude-artige Channel- und Berechtigungsbenachrichtigungen über die echte stdio-Bridge. Die Claude-Benachrichtigungs-Assertion liest die rohen stdio-MCP-Frames direkt, damit der Smoke widerspiegelt, was die Bridge tatsächlich ausgibt.
- `pnpm test:docker:upgrade-survivor`: Installiert den gepackten OpenClaw-Tarball über ein unsauberes Fixture für alte Benutzer, führt ein Paket-Update plus nicht interaktiven Doctor ohne Live-Provider- oder Kanal-Keys aus, startet anschließend einen Loopback-Gateway und prüft, ob Agenten, Kanalkonfiguration, Plugin-Allowlists, Workspace-/Sitzungsdateien, veralteter Plugin-`runtime-deps`-Status, Start und RPC-Status erhalten bleiben.
## Lokales PR-Gate
Für lokale PR-Landing-/Gate-Prüfungen führen Sie Folgendes aus:
Führen Sie für lokale PR-Lande-/Gate-Prüfungen aus:
- `pnpm check:changed`
- `pnpm check`
@ -61,27 +62,27 @@ Für lokale PR-Landing-/Gate-Prüfungen führen Sie Folgendes aus:
- `pnpm test`
- `pnpm check:docs`
Wenn `pnpm test` auf einem ausgelasteten Host instabil fehlschlägt, führen Sie es einmal erneut aus, bevor Sie es als Regression behandeln, und isolieren Sie es dann mit `pnpm test <path/to/test>`. Für Hosts mit eingeschränktem Speicher verwenden Sie:
Wenn `pnpm test` auf einem ausgelasteten Host flackert, führen Sie es einmal erneut aus, bevor Sie es als Regression behandeln, und isolieren Sie es dann mit `pnpm test <path/to/test>`. Verwenden Sie für Hosts mit begrenztem Arbeitsspeicher:
- `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
- `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
## Modell-Latenz-Benchmark (lokale Schlüssel)
## Benchmark für Modelllatenz (lokale Schlüssel)
Skript: [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts)
Verwendung:
- `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
- Optionale Umgebungsvariablen: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
- Standard-Prompt: „Antworten Sie mit einem einzigen Wort: ok. Keine Satzzeichen oder zusätzlicher Text.“
- Optionale Umgebung: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
- Standard-Prompt: „Antworte mit einem einzelnen Wort: ok. Keine Satzzeichen oder zusätzlicher Text.“
Letzter Lauf (2025-12-31, 20 Läufe):
Letzte Ausführung (2025-12-31, 20 Läufe):
- minimax Median 1279ms (Min. 1114, Max. 2431)
- opus Median 2454ms (Min. 1224, Max. 3170)
- minimax Median 1279 ms (min. 1114, max. 2431)
- opus Median 2454 ms (min. 1224, max. 3170)
## CLI-Startup-Benchmark
## Benchmark für CLI-Start
Skript: [`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts)
@ -103,47 +104,47 @@ Verwendung:
- `pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu`
- `pnpm tsx scripts/bench-cli-startup.ts --json`
Presets:
Voreinstellungen:
- `startup`: `--version`, `--help`, `health`, `health --json`, `status --json`, `status`
- `real`: `health`, `status`, `status --json`, `sessions`, `sessions --json`, `tasks --json`, `tasks list --json`, `tasks audit --json`, `agents list --json`, `gateway status`, `gateway status --json`, `gateway health --json`, `config get gateway.port`
- `all`: beide Presets
- `all`: beide Voreinstellungen
Die Ausgabe enthält `sampleCount`, Durchschnitt, p50, p95, Min./Max., Exit-Code-/Signal-Verteilung und maximale RSS-Zusammenfassungen für jeden Befehl. Optionale `--cpu-prof-dir` / `--heap-prof-dir` schreiben V8-Profile pro Lauf, damit Timing und Profilerfassung denselben Harness verwenden.
Die Ausgabe enthält `sampleCount`, Durchschnitt, p50, p95, Minimum/Maximum, Verteilung von Exit-Code/Signal und maximale RSS-Zusammenfassungen für jeden Befehl. Optional schreibt `--cpu-prof-dir` / `--heap-prof-dir` V8-Profile pro Lauf, sodass Timing und Profilerfassung denselben Harness verwenden.
Konventionen für gespeicherte Ausgaben:
- `pnpm test:startup:bench:smoke` schreibt das gezielte Smoke-Artefakt nach `.artifacts/cli-startup-bench-smoke.json`
- `pnpm test:startup:bench:save` schreibt das Full-Suite-Artefakt nach `.artifacts/cli-startup-bench-all.json` mit `runs=5` und `warmup=1`
- `pnpm test:startup:bench:update` aktualisiert das eingecheckte Baseline-Fixture unter `test/fixtures/cli-startup-bench.json` mit `runs=5` und `warmup=1`
- `pnpm test:startup:bench:save` schreibt das Artefakt der vollständigen Suite nach `.artifacts/cli-startup-bench-all.json` mit `runs=5` und `warmup=1`
- `pnpm test:startup:bench:update` aktualisiert die eingecheckte Baseline-Fixture unter `test/fixtures/cli-startup-bench.json` mit `runs=5` und `warmup=1`
Eingechecktes Fixture:
Eingecheckte Fixture:
- `test/fixtures/cli-startup-bench.json`
- Aktualisieren mit `pnpm test:startup:bench:update`
- Aktuelle Ergebnisse mit dem Fixture vergleichen mit `pnpm test:startup:bench:check`
- Aktuelle Ergebnisse mit `pnpm test:startup:bench:check` gegen die Fixture vergleichen
## Onboarding-E2E (Docker)
Docker ist optional; dies wird nur für containerisierte Onboarding-Smoke-Tests benötigt.
Vollständiger Cold-Start-Ablauf in einem sauberen Linux-Container:
Vollständiger Kaltstart-Ablauf in einem sauberen Linux-Container:
```bash
scripts/e2e/onboard-docker.sh
```
Dieses Skript steuert den interaktiven Assistenten über ein Pseudo-TTY, verifiziert Konfigurations-, Workspace- und Sitzungsdateien, startet dann das Gateway und führt `openclaw health` aus.
Dieses Skript steuert den interaktiven Assistenten über ein Pseudo-TTY, verifiziert Konfigurations-/Workspace-/Sitzungsdateien, startet anschließend den Gateway und führt `openclaw health` aus.
## QR-Import-Smoke-Test (Docker)
## QR-Import-Smoke (Docker)
Stellt sicher, dass der gepflegte QR-Runtime-Helper unter den unterstützten Docker-Node-Runtimes geladen wird (Node 24 als Standard, Node 22 kompatibel):
Stellt sicher, dass der gepflegte QR-Laufzeit-Helper unter den unterstützten Docker-Node-Laufzeiten geladen wird (Node 24 Standard, Node 22 kompatibel):
```bash
pnpm test:docker:qr
```
## Verwandte Themen
## Zugehörig
- [Testen](/de/help/testing)
- [Live testen](/de/help/testing-live)