diff --git a/docs/de/ci.md b/docs/de/ci.md index 5a6ba7efd..1c3323e5b 100644 --- a/docs/de/ci.md +++ b/docs/de/ci.md @@ -1,94 +1,94 @@ --- read_when: - - Sie müssen nachvollziehen, warum ein CI-Job ausgeführt wurde oder nicht - - Sie debuggen einen fehlgeschlagenen GitHub Actions-Check + - Sie müssen nachvollziehen, warum ein CI-Job ausgeführt wurde oder nicht. + - Sie debuggen eine fehlschlagende GitHub Actions-Prüfung - Sie koordinieren einen Release-Validierungslauf oder eine erneute Ausführung - Sie ändern den ClawSweeper-Dispatch oder die Weiterleitung von GitHub-Aktivitäten -summary: CI-Job-Graph, bereichsbezogene Gates, Release-Sammelprüfungen und lokale Befehlsäquivalente +summary: CI-Jobgraph, Scope-Gates, Release-Umbrellas und lokale Befehlsäquivalente title: CI-Pipeline x-i18n: - generated_at: "2026-05-02T22:17:23Z" + generated_at: "2026-05-02T23:39:35Z" model: gpt-5.5 provider: openai - source_hash: a8033b928b26adfa340200ea69fd63d339a6e65c21659b8119a68b23b8b16016 + source_hash: 321fe0a061044f75b8e1d03b4d3e76d4f8dd2dae0ebc58831887fc20af953cf1 source_path: ci.md workflow: 16 --- -OpenClaw CI läuft bei jedem Push auf `main` und bei jedem Pull Request. Der `preflight`-Job klassifiziert das Diff und deaktiviert teure Lanes, wenn sich nur nicht zugehörige Bereiche geändert haben. Manuelle `workflow_dispatch`-Läufe umgehen bewusst das intelligente Scoping und fächern den vollständigen Graphen für Release-Kandidaten und breite Validierung auf. Android-Lanes bleiben über `include_android` optional. Release-exklusive Plugin-Abdeckung befindet sich im separaten Workflow [`Plugin-Prerelease`](#plugin-prerelease) und läuft nur über [`vollständige Release-Validierung`](#full-release-validation) oder einen expliziten manuellen Dispatch. +OpenClaw CI wird bei jedem Push nach `main` und jedem Pull Request ausgeführt. Der Job `preflight` klassifiziert den Diff und deaktiviert teure Lanes, wenn sich nur nicht zusammenhängende Bereiche geändert haben. Manuelle `workflow_dispatch`-Ausführungen umgehen Smart Scoping absichtlich und fächern den vollständigen Graphen für Release-Kandidaten und breite Validierung auf. Android-Lanes bleiben über `include_android` opt-in. Die Plugin-Abdeckung nur für Releases befindet sich im separaten Workflow [`Plugin-Prerelease`](#plugin-prerelease) und wird nur von [`Vollständige Release-Validierung`](#full-release-validation) oder einem expliziten manuellen Dispatch ausgeführt. ## Pipeline-Übersicht -| Job | Zweck | Wann er läuft | -| -------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | -| `preflight` | Erkennt reine Dokumentationsänderungen, geänderte Scopes, geänderte Erweiterungen und erstellt das CI-Manifest | Immer bei Nicht-Entwurfs-Pushes und PRs | -| `security-scm-fast` | Erkennung privater Schlüssel und Workflow-Audit über `zizmor` | Immer bei Nicht-Entwurfs-Pushes und PRs | -| `security-dependency-audit` | Abhängigkeitsfreier Produktions-Lockfile-Audit gegen npm-Advisories | Immer bei Nicht-Entwurfs-Pushes und PRs | -| `security-fast` | Erforderliches Aggregat für die schnellen Sicherheitsjobs | Immer bei Nicht-Entwurfs-Pushes und PRs | -| `check-dependencies` | Reiner Produktions-Knip-Abhängigkeitsdurchlauf plus Allowlist-Schutz für ungenutzte Dateien | Node-relevante Änderungen | -| `build-artifacts` | Erstellt `dist/`, Control UI, Prüfungen gebauter Artefakte und wiederverwendbare Downstream-Artefakte | Node-relevante Änderungen | -| `checks-fast-core` | Schnelle Linux-Korrektheits-Lanes wie gebündelte/Plugin-Vertrags-/Protokollprüfungen | Node-relevante Änderungen | -| `checks-fast-contracts-channels` | Gesplittete Channel-Vertragsprüfungen mit stabilem aggregiertem Prüfergebnis | Node-relevante Änderungen | -| `checks-node-core-test` | Core-Node-Test-Shards, ohne Channel-, gebündelte, Vertrags- und Erweiterungs-Lanes | Node-relevante Änderungen | -| `check` | Gesplittetes Äquivalent zum lokalen Haupt-Gate: Produktionstypen, Lint, Guards, Testtypen und strikter Smoke-Test | Node-relevante Änderungen | -| `check-additional` | Architektur, Grenzen, Prompt-Snapshot-Drift, Erweiterungsflächen-Guards, Paketgrenzen und Gateway-Watch-Shards | Node-relevante Änderungen | -| `build-smoke` | Smoke-Tests der gebauten CLI und Smoke-Test für Startspeicher | Node-relevante Änderungen | -| `checks` | Verifizierer für Channel-Tests mit gebauten Artefakten | Node-relevante Änderungen | -| `checks-node-compat-node22` | Node-22-Kompatibilitäts-Build und Smoke-Lane | Manueller CI-Dispatch für Releases | -| `check-docs` | Dokumentationsformatierung, Lint und Broken-Link-Prüfungen | Dokumentation geändert | -| `skills-python` | Ruff + pytest für Python-gestützte Skills | Python-Skill-relevante Änderungen | -| `checks-windows` | Windows-spezifische Prozess-/Pfadtests plus gemeinsame Regressionen bei Runtime-Import-Spezifizierern | Windows-relevante Änderungen | -| `macos-node` | macOS-TypeScript-Test-Lane mit den gemeinsam genutzten gebauten Artefakten | macOS-relevante Änderungen | -| `macos-swift` | Swift-Lint, Build und Tests für die macOS-App | macOS-relevante Änderungen | -| `android` | Android-Unit-Tests für beide Varianten plus ein Debug-APK-Build | Android-relevante Änderungen | -| `test-performance-agent` | Tägliche Codex-Optimierung langsamer Tests nach vertrauenswürdiger Aktivität | Main-CI-Erfolg oder manueller Dispatch | -| `openclaw-performance` | Tägliche/bedarfsbasierte Kova-Runtime-Performanceberichte mit Mock-Provider-, Deep-Profile- und GPT-5.4-Live-Lanes | Geplanter und manueller Dispatch | +| Job | Zweck | Wann er ausgeführt wird | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | +| `preflight` | Erkennt reine Dokumentationsänderungen, geänderte Scopes, geänderte Erweiterungen und erstellt das CI-Manifest | Immer bei nicht als Entwurf markierten Pushes und PRs | +| `security-scm-fast` | Erkennung privater Schlüssel und Workflow-Audit über `zizmor` | Immer bei nicht als Entwurf markierten Pushes und PRs | +| `security-dependency-audit` | Dependency-freier Audit des Produktions-Lockfiles gegen npm-Advisories | Immer bei nicht als Entwurf markierten Pushes und PRs | +| `security-fast` | Erforderliches Aggregat für die schnellen Sicherheitsjobs | Immer bei nicht als Entwurf markierten Pushes und PRs | +| `check-dependencies` | Produktions-Knip-Durchlauf nur für Dependencies plus Allowlist-Schutz für ungenutzte Dateien | Node-relevante Änderungen | +| `build-artifacts` | Erstellt `dist/`, Control UI, Built-Artifact-Prüfungen und wiederverwendbare Downstream-Artefakte | Node-relevante Änderungen | +| `checks-fast-core` | Schnelle Linux-Korrektheits-Lanes wie Prüfungen für gebündelte Plugins, Plugin-Verträge und Protokolle | Node-relevante Änderungen | +| `checks-fast-contracts-channels` | Geshardete Channel-Contract-Prüfungen mit stabilem aggregiertem Prüfergebnis | Node-relevante Änderungen | +| `checks-node-core-test` | Core-Node-Test-Shards ohne Channel-, gebündelte, Contract- und Extension-Lanes | Node-relevante Änderungen | +| `check` | Geshardetes Äquivalent zum lokalen Haupt-Gate: Prod-Typen, Lint, Guards, Testtypen und strikter Smoke-Test | Node-relevante Änderungen | +| `check-additional` | Architektur-, Boundary-, Prompt-Snapshot-Drift-, Extension-Surface-, Package-Boundary- und Gateway-Watch-Shards | Node-relevante Änderungen | +| `build-smoke` | Smoke-Tests für die gebaute CLI und Startup-Memory-Smoke | Node-relevante Änderungen | +| `checks` | Verifier für Built-Artifact-Channel-Tests | Node-relevante Änderungen | +| `checks-node-compat-node22` | Node-22-Kompatibilitäts-Build und Smoke-Lane | Manueller CI-Dispatch für Releases | +| `check-docs` | Dokumentationsformatierung, Lint und Broken-Link-Prüfungen | Dokumentation geändert | +| `skills-python` | Ruff + pytest für Python-gestützte Skills | Python-Skill-relevante Änderungen | +| `checks-windows` | Windows-spezifische Prozess-/Pfadtests plus gemeinsame Regressionstests für Runtime-Import-Spezifizierer | Windows-relevante Änderungen | +| `macos-node` | macOS-TypeScript-Test-Lane mit den gemeinsam gebauten Artefakten | macOS-relevante Änderungen | +| `macos-swift` | Swift-Lint, Build und Tests für die macOS-App | macOS-relevante Änderungen | +| `android` | Android-Unit-Tests für beide Flavors plus ein Debug-APK-Build | Android-relevante Änderungen | +| `test-performance-agent` | Tägliche Codex-Optimierung langsamer Tests nach vertrauenswürdiger Aktivität | Main-CI-Erfolg oder manueller Dispatch | +| `openclaw-performance` | Tägliche/bedarfsbasierte Kova-Runtime-Performanceberichte mit Mock-Provider-, Deep-Profile- und GPT-5.4-Live-Lanes | Geplanter und manueller Dispatch | ## Fail-Fast-Reihenfolge -1. `preflight` entscheidet, welche Lanes überhaupt existieren. Die Logiken `docs-scope` und `changed-scope` sind Schritte innerhalb dieses Jobs, keine eigenständigen Jobs. +1. `preflight` entscheidet, welche Lanes überhaupt existieren. Die Logik `docs-scope` und `changed-scope` sind Schritte innerhalb dieses Jobs, keine eigenständigen Jobs. 2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` und `skills-python` schlagen schnell fehl, ohne auf die schwereren Artefakt- und Plattform-Matrix-Jobs zu warten. -3. `build-artifacts` überschneidet sich mit den schnellen Linux-Lanes, damit Downstream-Verbraucher starten können, sobald der gemeinsame Build bereit ist. +3. `build-artifacts` überlappt sich mit den schnellen Linux-Lanes, damit Downstream-Verbraucher starten können, sobald der gemeinsame Build bereit ist. 4. Schwerere Plattform- und Runtime-Lanes fächern danach auf: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` und `android`. -GitHub kann überholte Jobs als `cancelled` markieren, wenn ein neuerer Push auf demselben PR- oder `main`-Ref landet. Behandeln Sie das als CI-Rauschen, sofern nicht auch der neueste Lauf für denselben Ref fehlschlägt. Aggregierte Shard-Prüfungen verwenden `!cancelled() && always()`, damit sie normale Shard-Fehler weiterhin melden, aber nicht mehr in die Warteschlange gehen, nachdem der gesamte Workflow bereits überholt wurde. Der automatische CI-Concurrency-Key ist versioniert (`CI-v7-*`), sodass ein GitHub-seitiger Zombie in einer alten Queue-Gruppe neuere main-Läufe nicht unbegrenzt blockieren kann. Manuelle vollständige Suite-Läufe verwenden `CI-manual-v1-*` und brechen laufende Läufe nicht ab. +GitHub kann überholte Jobs als `cancelled` markieren, wenn ein neuerer Push auf demselben PR- oder `main`-Ref landet. Behandeln Sie das als CI-Rauschen, sofern nicht auch die neueste Ausführung für denselben Ref fehlschlägt. Aggregierte Shard-Prüfungen verwenden `!cancelled() && always()`, sodass sie normale Shard-Fehler weiterhin melden, aber nicht mehr eingereiht werden, nachdem der gesamte Workflow bereits überholt wurde. Der automatische CI-Concurrency-Schlüssel ist versioniert (`CI-v7-*`), damit ein Zombie auf GitHub-Seite in einer alten Queue-Gruppe neuere Main-Ausführungen nicht unbegrenzt blockieren kann. Manuelle Full-Suite-Ausführungen verwenden `CI-manual-v1-*` und brechen laufende Ausführungen nicht ab. ## Scope und Routing -Die Scope-Logik befindet sich in `scripts/ci-changed-scope.mjs` und ist durch Unit-Tests in `src/scripts/ci-changed-scope.test.ts` abgedeckt. Manueller Dispatch überspringt die Changed-Scope-Erkennung und lässt das Preflight-Manifest so agieren, als hätte sich jeder gescopte Bereich geändert. +Die Scope-Logik befindet sich in `scripts/ci-changed-scope.mjs` und wird durch Unit-Tests in `src/scripts/ci-changed-scope.test.ts` abgedeckt. Manueller Dispatch überspringt die Changed-Scope-Erkennung und lässt das Preflight-Manifest so agieren, als hätte sich jeder gescopte Bereich geändert. -- **CI-Workflow-Änderungen** validieren den Node-CI-Graphen plus Workflow-Linting, erzwingen aber nicht von selbst native Windows-, Android- oder macOS-Builds; diese Plattform-Lanes bleiben auf Plattform-Quelländerungen beschränkt. -- **Reine CI-Routing-Änderungen, ausgewählte günstige Core-Test-Fixture-Änderungen und enge Plugin-Vertrags-Helfer-/Test-Routing-Änderungen** verwenden einen schnellen Node-only-Manifestpfad: `preflight`, Sicherheit und eine einzelne `checks-fast-core`-Aufgabe. Dieser Pfad überspringt Build-Artefakte, Node-22-Kompatibilität, Channel-Verträge, vollständige Core-Shards, gebündelte-Plugin-Shards und zusätzliche Guard-Matrizen, wenn die Änderung auf die Routing- oder Hilfsflächen beschränkt ist, die die schnelle Aufgabe direkt ausübt. -- **Windows-Node-Prüfungen** sind auf Windows-spezifische Prozess-/Pfad-Wrapper, npm/pnpm/UI-Runner-Helfer, Paketmanager-Konfiguration und die CI-Workflow-Flächen beschränkt, die diese Lane ausführen; nicht zugehörige Quell-, Plugin-, Install-Smoke- und reine Teständerungen bleiben auf den Linux-Node-Lanes. +- **CI-Workflow-Bearbeitungen** validieren den Node-CI-Graphen plus Workflow-Linting, erzwingen aber für sich genommen keine nativen Windows-, Android- oder macOS-Builds; diese Plattform-Lanes bleiben auf Plattform-Quelländerungen beschränkt. +- **CI-Bearbeitungen nur am Routing, ausgewählte günstige Core-Test-Fixture-Bearbeitungen und schmale Plugin-Contract-Helper-/Test-Routing-Bearbeitungen** verwenden einen schnellen Node-only-Manifestpfad: `preflight`, Sicherheit und eine einzelne `checks-fast-core`-Aufgabe. Dieser Pfad überspringt Build-Artefakte, Node-22-Kompatibilität, Channel-Contracts, vollständige Core-Shards, Bundled-Plugin-Shards und zusätzliche Guard-Matrizen, wenn die Änderung auf die Routing- oder Helper-Oberflächen beschränkt ist, die die schnelle Aufgabe direkt ausführt. +- **Windows-Node-Prüfungen** sind auf Windows-spezifische Prozess-/Pfad-Wrapper, npm-/pnpm-/UI-Runner-Helper, Paketmanager-Konfiguration und die CI-Workflow-Oberflächen beschränkt, die diese Lane ausführen; nicht zusammenhängende Quell-, Plugin-, Install-Smoke- und reine Teständerungen bleiben auf den Linux-Node-Lanes. -Die langsamsten Node-Testfamilien sind aufgeteilt oder ausbalanciert, damit jeder Job klein bleibt, ohne Runner übermäßig zu reservieren: Channel-Verträge laufen als drei gewichtete Shards, kleine Core-Unit-Lanes werden gepaart, Auto-Reply läuft als vier ausbalancierte Worker (wobei der Reply-Teilbaum in Agent-Runner-, Dispatch- und Commands/State-Routing-Shards aufgeteilt ist), und agentische Gateway-/Plugin-Konfigurationen werden über die bestehenden quellcodebasierten agentischen Node-Jobs verteilt, statt auf gebaute Artefakte zu warten. Breite Browser-, QA-, Medien- und sonstige Plugin-Tests verwenden ihre dedizierten Vitest-Konfigurationen statt des gemeinsamen Plugin-Catch-all. Include-Pattern-Shards erfassen Timing-Einträge mit dem CI-Shard-Namen, sodass `.artifacts/vitest-shard-timings.json` eine ganze Konfiguration von einem gefilterten Shard unterscheiden kann. `check-additional` hält Paketgrenzen-Compile-/Canary-Arbeit zusammen und trennt Runtime-Topologie-Architektur von Gateway-Watch-Abdeckung; der Boundary-Guard-Shard führt seine kleinen unabhängigen Guards innerhalb eines Jobs parallel aus, einschließlich `pnpm prompt:snapshots:check`, sodass Codex-Happy-Path-Prompt-Drift an den PR gebunden wird, der ihn verursacht hat. Gateway-Watch, Channel-Tests und der Core-Support-Boundary-Shard laufen innerhalb von `build-artifacts` parallel, nachdem `dist/` und `dist-runtime/` bereits gebaut wurden. +Die langsamsten Node-Testfamilien sind aufgeteilt oder ausbalanciert, damit jeder Job klein bleibt, ohne Runner übermäßig zu reservieren: Channel-Contracts laufen als drei gewichtete Shards, kleine Core-Unit-Lanes werden gepaart, Auto-Reply läuft als vier ausbalancierte Worker (wobei der Reply-Teilbaum in Agent-Runner-, Dispatch- und Commands/State-Routing-Shards aufgeteilt ist), und agentische Gateway-/Plugin-Konfigurationen werden auf die bestehenden source-only agentischen Node-Jobs verteilt, statt auf gebaute Artefakte zu warten. Breite Browser-, QA-, Medien- und sonstige Plugin-Tests verwenden ihre dedizierten Vitest-Konfigurationen statt des gemeinsamen Plugin-Catch-all. Include-Pattern-Shards zeichnen Timing-Einträge mit dem CI-Shard-Namen auf, sodass `.artifacts/vitest-shard-timings.json` eine ganze Konfiguration von einem gefilterten Shard unterscheiden kann. `check-additional` hält Package-Boundary-Compile-/Canary-Arbeit zusammen und trennt Runtime-Topology-Architektur von Gateway-Watch-Abdeckung; der Boundary-Guard-Shard führt seine kleinen unabhängigen Guards innerhalb eines Jobs parallel aus, einschließlich `pnpm prompt:snapshots:check`, sodass Prompt-Drift im Codex-Runtime-Happy-Path an den verursachenden PR gebunden ist. Gateway-Watch-, Channel-Tests und der Core-Support-Boundary-Shard laufen innerhalb von `build-artifacts` parallel, nachdem `dist/` und `dist-runtime/` bereits gebaut wurden. -Android-CI führt sowohl `testPlayDebugUnitTest` als auch `testThirdPartyDebugUnitTest` aus und baut anschließend das Play-Debug-APK. Die Drittanbieter-Variante hat kein separates Source Set oder Manifest; ihre Unit-Test-Lane kompiliert die Variante dennoch mit den SMS-/Anrufprotokoll-`BuildConfig`-Flags, während ein doppelter Debug-APK-Paketierungsjob bei jedem Android-relevanten Push vermieden wird. +Android CI führt sowohl `testPlayDebugUnitTest` als auch `testThirdPartyDebugUnitTest` aus und baut anschließend das Play-Debug-APK. Der Third-Party-Flavor hat kein separates Source Set oder Manifest; seine Unit-Test-Lane kompiliert den Flavor dennoch mit den SMS-/Call-Log-BuildConfig-Flags und vermeidet gleichzeitig einen doppelten Debug-APK-Packaging-Job bei jedem Android-relevanten Push. -Der Shard `check-dependencies` führt `pnpm deadcode:dependencies` (einen reinen Produktions-Knip-Abhängigkeitsdurchlauf, gepinnt auf die neueste Knip-Version, wobei pnpm's Mindest-Release-Alter für die `dlx`-Installation deaktiviert ist) und `pnpm deadcode:unused-files` aus, das Knips Produktionsfunde ungenutzter Dateien mit `scripts/deadcode-unused-files.allowlist.mjs` vergleicht. Der Guard für ungenutzte Dateien schlägt fehl, wenn ein PR eine neue ungeprüfte ungenutzte Datei hinzufügt oder einen veralteten Allowlist-Eintrag hinterlässt, während absichtliche dynamische Plugin-, generierte, Build-, Live-Test- und Paket-Bridge-Flächen erhalten bleiben, die Knip statisch nicht auflösen kann. +Der Shard `check-dependencies` führt `pnpm deadcode:dependencies` (einen Produktions-Knip-Durchlauf nur für Dependencies, fixiert auf die neueste Knip-Version, wobei pnpm's Mindest-Release-Alter für die `dlx`-Installation deaktiviert ist) und `pnpm deadcode:unused-files` aus, das Knip's Produktionsbefunde zu ungenutzten Dateien mit `scripts/deadcode-unused-files.allowlist.mjs` vergleicht. Der Guard für ungenutzte Dateien schlägt fehl, wenn ein PR eine neue nicht überprüfte ungenutzte Datei hinzufügt oder einen veralteten Allowlist-Eintrag zurücklässt, während absichtliche dynamische Plugin-, generierte, Build-, Live-Test- und Package-Bridge-Oberflächen erhalten bleiben, die Knip statisch nicht auflösen kann. -## ClawSweeper-Aktivitätsweiterleitung +## Weiterleitung von ClawSweeper-Aktivitäten -`.github/workflows/clawsweeper-dispatch.yml` ist die zielseitige Bridge von OpenClaw-Repository-Aktivität zu ClawSweeper. Sie checkt keinen nicht vertrauenswürdigen Pull-Request-Code aus und führt ihn nicht aus. Der Workflow erstellt ein GitHub-App-Token aus `CLAWSWEEPER_APP_PRIVATE_KEY` und dispatcht dann kompakte `repository_dispatch`-Payloads an `openclaw/clawsweeper`. +`.github/workflows/clawsweeper-dispatch.yml` ist die zielseitige Brücke von OpenClaw-Repository-Aktivitäten zu ClawSweeper. Sie checkt keinen nicht vertrauenswürdigen Pull-Request-Code aus und führt ihn nicht aus. Der Workflow erstellt aus `CLAWSWEEPER_APP_PRIVATE_KEY` ein GitHub-App-Token und sendet dann kompakte `repository_dispatch`-Payloads an `openclaw/clawsweeper`. Der Workflow hat vier Lanes: -- `clawsweeper_item` für exakte Issue- und Pull-Request-Review-Anfragen; +- `clawsweeper_item` für exakte Review-Anfragen zu Issues und Pull Requests; - `clawsweeper_comment` für explizite ClawSweeper-Befehle in Issue-Kommentaren; - `clawsweeper_commit_review` für Review-Anfragen auf Commit-Ebene bei `main`-Pushes; -- `github_activity` für allgemeine GitHub-Aktivität, die der ClawSweeper-Agent prüfen kann. +- `github_activity` für allgemeine GitHub-Aktivitäten, die der ClawSweeper-Agent prüfen kann. -Die Lane `github_activity` leitet nur normalisierte Metadaten weiter: Ereignistyp, Aktion, Akteur, Repository, Elementnummer, URL, Titel, Status und kurze Auszüge für Kommentare oder Reviews, sofern vorhanden. Sie vermeidet bewusst, den vollständigen Webhook-Body weiterzuleiten. Der empfangende Workflow in `openclaw/clawsweeper` ist `.github/workflows/github-activity.yml`, der das normalisierte Ereignis an den OpenClaw Gateway-Hook für den ClawSweeper-Agent sendet. +Die Lane `github_activity` leitet nur normalisierte Metadaten weiter: Ereignistyp, Aktion, Actor, Repository, Item-Nummer, URL, Titel, Zustand und kurze Auszüge für Kommentare oder Reviews, sofern vorhanden. Sie vermeidet absichtlich die Weiterleitung des vollständigen Webhook-Bodys. Der empfangende Workflow in `openclaw/clawsweeper` ist `.github/workflows/github-activity.yml`, der das normalisierte Ereignis an den OpenClaw-Gateway-Hook für den ClawSweeper-Agent postet. -Allgemeine Aktivität ist Beobachtung, nicht standardmäßige Zustellung. Der ClawSweeper-Agent erhält das Discord-Ziel in seinem Prompt und sollte nur dann in `#clawsweeper` posten, wenn das Ereignis überraschend, handlungsrelevant, riskant oder operativ nützlich ist. Routinemäßige Eröffnungen, Bearbeitungen, Bot-Fluktuation, doppeltes Webhook-Rauschen und normaler Review-Verkehr sollten zu `NO_REPLY` führen. +Allgemeine Aktivität ist Beobachtung, keine standardmäßige Zustellung. Der ClawSweeper-Agent erhält das Discord-Ziel in seinem Prompt und sollte nur dann an `#clawsweeper` posten, wenn das Ereignis überraschend, handlungsrelevant, riskant oder betrieblich nützlich ist. Routinemäßiges Öffnen, Bearbeiten, Bot-Aktivität, doppeltes Webhook-Rauschen und normaler Review-Verkehr sollten zu `NO_REPLY` führen. -Behandeln Sie GitHub-Titel, Kommentare, Bodys, Review-Text, Branch-Namen und Commit-Nachrichten entlang dieses gesamten Pfads als nicht vertrauenswürdige Daten. Sie sind Eingaben für Zusammenfassung und Triage, keine Anweisungen für den Workflow oder die Agent-Runtime. +Behandeln Sie GitHub-Titel, Kommentare, Bodys, Review-Text, Branch-Namen und Commit-Nachrichten auf diesem gesamten Pfad als nicht vertrauenswürdige Daten. Sie sind Eingaben für Zusammenfassung und Triage, keine Anweisungen für den Workflow oder die Agent-Runtime. ## Manuelle Dispatches -Manuelle CI-Dispatches führen denselben Job-Graphen wie normale CI aus, erzwingen aber jede nicht auf Android beschränkte Lane: Linux Node-Shards, Shards für gebündelte Plugins, Kanalverträge, Node-22-Kompatibilität, `check`, `check-additional`, Build-Smoke, Dokumentationsprüfungen, Python-Skills, Windows, macOS und Control UI i18n. Eigenständige manuelle CI-Dispatches führen Android nur mit `include_android=true` aus; das vollständige Release-Umbrella aktiviert Android durch Übergabe von `include_android=true`. Statische Plugin-Prerelease-Prüfungen, der nur für Releases vorgesehene `agentic-plugins`-Shard, der vollständige Batch-Sweep für Extensions und Plugin-Prerelease-Docker-Lanes sind von der CI ausgeschlossen. Die Docker-Prerelease-Suite läuft nur, wenn `Full Release Validation` den separaten `Plugin Prerelease`-Workflow mit aktiviertem Release-Validation-Gate auslöst. +Manuelle CI-Dispatches führen denselben Job-Graphen wie die normale CI aus, erzwingen aber jede nicht auf Android beschränkte Lane: Linux-Node-Shards, gebündelte Plugin-Shards, Channel-Contracts, Node-22-Kompatibilität, `check`, `check-additional`, Build-Smoke, Dokumentationsprüfungen, Python-Skills, Windows, macOS und Control-UI-i18n. Eigenständige manuelle CI-Dispatches führen Android nur mit `include_android=true` aus; der vollständige Release-Umbrella aktiviert Android durch Übergabe von `include_android=true`. Statische Plugin-Prerelease-Prüfungen, der nur für Releases vorgesehene `agentic-plugins`-Shard, der vollständige Erweiterungs-Batch-Sweep und Plugin-Prerelease-Docker-Lanes sind von der CI ausgeschlossen. Die Docker-Prerelease-Suite läuft nur, wenn `Full Release Validation` den separaten Workflow `Plugin Prerelease` mit aktiviertem Release-Validierungs-Gate auslöst. -Manuelle Läufe verwenden eine eindeutige Concurrency-Gruppe, damit eine vollständige Release-Candidate-Suite nicht durch einen anderen Push- oder PR-Lauf auf demselben Ref abgebrochen wird. Die optionale Eingabe `target_ref` erlaubt es einem vertrauenswürdigen Aufrufer, diesen Graphen gegen einen Branch, Tag oder vollständigen Commit-SHA auszuführen, während die Workflow-Datei aus dem ausgewählten Dispatch-Ref verwendet wird. +Manuelle Läufe verwenden eine eindeutige Nebenläufigkeitsgruppe, damit eine vollständige Release-Candidate-Suite nicht durch einen anderen Push- oder PR-Lauf auf derselben Ref abgebrochen wird. Die optionale Eingabe `target_ref` ermöglicht es einem vertrauenswürdigen Aufrufer, diesen Graphen gegen einen Branch, ein Tag oder eine vollständige Commit-SHA auszuführen, während die Workflow-Datei aus der ausgewählten Dispatch-Ref verwendet wird. ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -98,15 +98,15 @@ gh workflow run full-release-validation.yml --ref main -f ref= ## Runner -| Runner | Jobs | -| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`, schnelle Sicherheitsjobs und Aggregate (`security-scm-fast`, `security-dependency-audit`, `security-fast`), schnelle Protokoll-/Vertrags-/Bundled-Prüfungen, geshardete Kanalvertragsprüfungen, `check`-Shards außer Lint, `check-additional`-Shards und Aggregate, Aggregat-Verifier für Node-Tests, Dokumentationsprüfungen, Python-Skills, Workflow-Sanity, Labeler, Auto-Response; die Install-Smoke-Preflight verwendet ebenfalls GitHub-gehostetes Ubuntu, damit die Blacksmith-Matrix früher in die Warteschlange eingereiht werden kann | -| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, leichtere Extension-Shards, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` und `check-test-types` | -| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, Build-Smoke, Linux Node-Test-Shards, Test-Shards für gebündelte Plugins, `android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (CPU-sensitiv genug, dass 8 vCPU mehr kosteten, als sie einsparten); Install-Smoke-Docker-Builds (32-vCPU-Warteschlangenzeit kostete mehr, als sie einsparten) | -| `blacksmith-16vcpu-windows-2025` | `checks-windows` | -| `blacksmith-6vcpu-macos-latest` | `macos-node` auf `openclaw/openclaw`; Forks fallen auf `macos-latest` zurück | -| `blacksmith-12vcpu-macos-latest` | `macos-swift` auf `openclaw/openclaw`; Forks fallen auf `macos-latest` zurück | +| Runner | Jobs | +| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ubuntu-24.04` | `preflight`, schnelle Security-Jobs und Aggregate (`security-scm-fast`, `security-dependency-audit`, `security-fast`), schnelle Protokoll-/Contract-/gebündelte Prüfungen, geshardete Channel-Contract-Prüfungen, `check`-Shards außer Lint, `check-additional`-Shards und Aggregate, Node-Test-Aggregatverifizierer, Dokumentationsprüfungen, Python-Skills, Workflow-Sanity, Labeler, Auto-Response; Install-Smoke-Preflight verwendet ebenfalls GitHub-gehostetes Ubuntu, damit die Blacksmith-Matrix früher in die Warteschlange kann | +| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, weniger aufwendige Erweiterungs-Shards, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` und `check-test-types` | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, Build-Smoke, Linux-Node-Test-Shards, gebündelte Plugin-Test-Shards, `android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (CPU-sensibel genug, dass 8 vCPU mehr gekostet haben, als sie eingespart haben); Install-Smoke-Docker-Builds (32-vCPU-Warteschlangenzeit hat mehr gekostet, als sie eingespart hat) | +| `blacksmith-16vcpu-windows-2025` | `checks-windows` | +| `blacksmith-6vcpu-macos-latest` | `macos-node` auf `openclaw/openclaw`; Forks fallen auf `macos-latest` zurück | +| `blacksmith-12vcpu-macos-latest` | `macos-swift` auf `openclaw/openclaw`; Forks fallen auf `macos-latest` zurück | ## Lokale Entsprechungen @@ -135,7 +135,7 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac pnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.json --output .artifacts/kova/summary.md ``` -## OpenClaw Performance +## OpenClaw-Performance `OpenClaw Performance` ist der Workflow für Produkt-/Runtime-Performance. Er läuft täglich auf `main` und kann manuell ausgelöst werden: @@ -146,28 +146,28 @@ gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1 Der Workflow installiert OCM aus einem gepinnten Release und Kova aus der gepinnten Eingabe `kova_ref` und führt dann drei Lanes aus: -- `mock-provider`: Kova-Diagnoseszenarien gegen eine Runtime aus lokalem Build mit deterministischer Fake-OpenAI-kompatibler Authentifizierung. -- `mock-deep-profile`: CPU-/Heap-/Trace-Profiling für Hotspots bei Start, Gateway und Agent-Turn. -- `live-gpt54`: ein echter OpenAI-`openai/gpt-5.4`-Agent-Turn, der übersprungen wird, wenn `OPENAI_API_KEY` nicht verfügbar ist. +- `mock-provider`: Kova-Diagnoseszenarien gegen eine lokal gebaute Runtime mit deterministischer gefälschter OpenAI-kompatibler Authentifizierung. +- `mock-deep-profile`: CPU-/Heap-/Trace-Profiling für Hotspots beim Start, Gateway und Agent-Turn. +- `live-gpt54`: ein echter Agent-Turn mit OpenAI `openai/gpt-5.4`, der übersprungen wird, wenn `OPENAI_API_KEY` nicht verfügbar ist. -Die Mock-Provider-Lane führt nach dem Kova-Durchlauf auch OpenClaw-native Source-Probes aus: Gateway-Startzeit und Speicher über Standard-, Hook- und 50-Plugin-Startfälle hinweg; wiederholte Mock-OpenAI-`channel-chat-baseline`-Hello-Loops; und CLI-Startbefehle gegen das gebootete Gateway. Die Markdown-Zusammenfassung der Source-Probes liegt unter `source/index.md` im Report-Bundle, mit Roh-JSON daneben. +Die Mock-Provider-Lane führt nach dem Kova-Durchlauf außerdem OpenClaw-native Source-Probes aus: Gateway-Startzeit und Speicher über Standard-, Hook- und 50-Plugin-Startfälle hinweg; wiederholte Mock-OpenAI-`channel-chat-baseline`-Hello-Loops; und CLI-Startbefehle gegen das gestartete Gateway. Die Markdown-Zusammenfassung der Source-Probe befindet sich unter `source/index.md` im Report-Bundle, mit Roh-JSON daneben. Jede Lane lädt GitHub-Artefakte hoch. Wenn `CLAWGRIT_REPORTS_TOKEN` konfiguriert ist, committet der Workflow außerdem `report.json`, `report.md`, Bundles, `index.md` und Source-Probe-Artefakte nach `openclaw/clawgrit-reports` unter `openclaw-performance//-//`. Der aktuelle Branch-Zeiger wird als `openclaw-performance//latest-.json` geschrieben. -## Full Release Validation +## Vollständige Release-Validierung -`Full Release Validation` ist der manuelle Umbrella-Workflow für „alles vor dem Release ausführen“. Er akzeptiert einen Branch, Tag oder vollständigen Commit-SHA, dispatcht den manuellen `CI`-Workflow mit diesem Ziel, dispatcht `Plugin Prerelease` für nur im Release vorgesehene Plugin-/Paket-/statische/Docker-Nachweise und dispatcht `OpenClaw Release Checks` für Install-Smoke, Paketakzeptanz, Docker-Release-Path-Suites, Live/E2E, OpenWebUI, QA-Lab-Parität, Matrix- und Telegram-Lanes. Mit `rerun_group=all` und `release_profile=full` führt er außerdem `NPM Telegram Beta E2E` gegen das Artefakt `release-package-under-test` aus den Release Checks aus. Übergeben Sie nach der Veröffentlichung `npm_telegram_package_spec`, um dieselbe Telegram-Paket-Lane gegen das veröffentlichte npm-Paket erneut auszuführen. +`Full Release Validation` ist der manuelle Umbrella-Workflow für „alles vor dem Release ausführen“. Er akzeptiert einen Branch, ein Tag oder eine vollständige Commit-SHA, löst den manuellen `CI`-Workflow mit diesem Ziel aus, löst `Plugin Prerelease` für nur im Release verwendete Plugin-/Paket-/Static-/Docker-Nachweise aus und löst `OpenClaw Release Checks` für Install-Smoke, Package Acceptance, Docker-Release-Pfad-Suites, Live/E2E, OpenWebUI, QA-Lab-Parität, Matrix- und Telegram-Lanes aus. Mit `rerun_group=all` und `release_profile=full` führt er außerdem `NPM Telegram Beta E2E` gegen das Artefakt `release-package-under-test` aus den Release-Checks aus. Übergeben Sie nach der Veröffentlichung `npm_telegram_package_spec`, um dieselbe Telegram-Paket-Lane gegen das veröffentlichte npm-Paket erneut auszuführen. Siehe [Vollständige Release-Validierung](/de/reference/full-release-validation) für die Stage-Matrix, exakte Workflow-Jobnamen, Profilunterschiede, Artefakte und fokussierte Rerun-Handles. -`OpenClaw Release Publish` ist der manuelle mutierende Release-Workflow. Dispatchen Sie ihn -von `release/YYYY.M.D` oder `main`, nachdem der Release-Tag existiert und nachdem die +`OpenClaw Release Publish` ist der manuelle mutierende Release-Workflow. Lösen Sie ihn +von `release/YYYY.M.D` oder `main` aus, nachdem das Release-Tag existiert und nachdem der OpenClaw-npm-Preflight erfolgreich war. Er verifiziert `pnpm plugins:sync:check`, -dispatcht `Plugin NPM Release` für alle veröffentlichbaren Plugin-Pakete, dispatcht -`Plugin ClawHub Release` für denselben Release-SHA und dispatcht erst dann -`OpenClaw NPM Release` mit der gespeicherten `preflight_run_id`. +löst `Plugin NPM Release` für alle veröffentlichbaren Plugin-Pakete aus, löst +`Plugin ClawHub Release` für dieselbe Release-SHA aus und löst erst dann +`OpenClaw NPM Release` mit der gespeicherten `preflight_run_id` aus. ```bash gh workflow run openclaw-release-publish.yml \ @@ -177,7 +177,7 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -Für einen Nachweis mit gepinntem Commit auf einem schnelllebigen Branch verwenden Sie den Helper statt +Für einen gepinnten Commit-Nachweis auf einem sich schnell bewegenden Branch verwenden Sie den Helper statt `gh workflow run ... --ref main -f ref=`: ```bash @@ -185,35 +185,35 @@ pnpm ci:full-release --sha ``` GitHub-Workflow-Dispatch-Refs müssen Branches oder Tags sein, keine rohen Commit-SHAs. Der -Helper pusht einen temporären Branch `release-ci/-...` auf dem Ziel-SHA, -dispatcht `Full Release Validation` von diesem gepinnten Ref, verifiziert, dass jeder -untergeordnete Workflow-`headSha` mit dem Ziel übereinstimmt, und löscht den temporären Branch, wenn der -Lauf abgeschlossen ist. Der Umbrella-Verifier schlägt außerdem fehl, wenn ein untergeordneter Workflow mit einem +Helper pusht einen temporären Branch `release-ci/-...` an der Ziel-SHA, +löst `Full Release Validation` von dieser gepinnten Ref aus, verifiziert, dass jede +Child-Workflow-`headSha` mit dem Ziel übereinstimmt, und löscht den temporären Branch, wenn der +Lauf abgeschlossen ist. Der Umbrella-Verifizierer schlägt außerdem fehl, wenn ein Child-Workflow mit einer anderen SHA lief. -`release_profile` steuert die Live-/Provider-Breite, die an Release Checks übergeben wird. Die +`release_profile` steuert die Live-/Provider-Breite, die an Release-Checks übergeben wird. Die manuellen Release-Workflows verwenden standardmäßig `stable`; verwenden Sie `full` nur, wenn Sie -absichtlich die breite advisory Provider-/Medien-Matrix möchten. +absichtlich die breite beratende Provider-/Medien-Matrix wünschen. - `minimum` behält die schnellsten OpenAI-/Core-releasekritischen Lanes bei. - `stable` fügt den stabilen Provider-/Backend-Satz hinzu. -- `full` führt die breite advisory Provider-/Medien-Matrix aus. +- `full` führt die breite beratende Provider-/Medien-Matrix aus. -Das Umbrella zeichnet die ausgelösten untergeordneten Run-IDs auf, und der abschließende Job `Verify full validation` prüft die aktuellen Conclusions der untergeordneten Läufe erneut und hängt Tabellen der langsamsten Jobs für jeden untergeordneten Lauf an. Wenn ein untergeordneter Workflow erneut ausgeführt wird und grün wird, führen Sie nur den übergeordneten Verifier-Job erneut aus, um das Umbrella-Ergebnis und die Timing-Zusammenfassung zu aktualisieren. +Der Umbrella zeichnet die ausgelösten Child-Run-IDs auf, und der abschließende Job `Verify full validation` prüft die aktuellen Child-Run-Ergebnisse erneut und hängt Tabellen der langsamsten Jobs für jeden Child-Run an. Wenn ein Child-Workflow erneut ausgeführt wird und grün wird, führen Sie nur den übergeordneten Verifiziererjob erneut aus, um das Umbrella-Ergebnis und die Timing-Zusammenfassung zu aktualisieren. Für die Wiederherstellung akzeptieren sowohl `Full Release Validation` als auch `OpenClaw Release Checks` `rerun_group`. Verwenden Sie `all` für einen Release Candidate, `ci` nur für das normale vollständige CI-Child, `plugin-prerelease` nur für das Plugin-Prerelease-Child, `release-checks` für jedes Release-Child oder eine engere Gruppe: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` oder `npm-telegram` im Umbrella. Dadurch bleibt die erneute Ausführung einer fehlgeschlagenen Release-Box nach einem gezielten Fix begrenzt. -`OpenClaw Release Checks` verwendet den vertrauenswürdigen Workflow-Ref, um den ausgewählten Ref einmal in ein `release-package-under-test`-Tarball aufzulösen, und übergibt dieses Artefakt dann sowohl an den Live/E2E-Docker-Workflow für den Release-Pfad als auch an den Package-Acceptance-Shard. Dadurch bleiben die Package-Bytes über Release-Boxen hinweg konsistent, und derselbe Candidate muss nicht in mehreren Child-Jobs erneut gepackt werden. +`OpenClaw Release Checks` verwendet den vertrauenswürdigen Workflow-Ref, um den ausgewählten Ref einmal in ein `release-package-under-test`-Tarball aufzulösen, und übergibt dieses Artefakt dann sowohl an den Live/E2E-Docker-Workflow für den Release-Pfad als auch an den Package-Acceptance-Shard. Dadurch bleiben die Paketbytes über Release-Boxen hinweg konsistent und dasselbe Candidate wird nicht in mehreren Child-Jobs erneut gepackt. -Doppelte `Full Release Validation`-Runs für `ref=main` und `rerun_group=all` -ersetzen den älteren Umbrella. Der Parent-Monitor bricht jeden Child-Workflow ab, den er +Doppelte `Full Release Validation`-Läufe für `ref=main` und `rerun_group=all` +ersetzen das ältere Umbrella. Der Parent-Monitor bricht jeden Child-Workflow ab, den er bereits ausgelöst hat, wenn der Parent abgebrochen wird, sodass neuere Main-Validierung -nicht hinter einem veralteten zweistündigen Release-Check-Run wartet. Release-Branch/Tag- -Validierung und fokussierte Rerun-Gruppen behalten `cancel-in-progress: false`. +nicht hinter einem veralteten zweistündigen Release-Check-Lauf wartet. Validierung von Release-Branches/-Tags +und gezielte Rerun-Gruppen behalten `cancel-in-progress: false`. ## Live- und E2E-Shards -Das Release-Live/E2E-Child behält die breite native `pnpm test:live`-Abdeckung bei, führt sie jedoch als benannte Shards über `scripts/test-live-shard.mjs` aus statt als einen seriellen Job: +Das Release-Live/E2E-Child behält breite native `pnpm test:live`-Abdeckung bei, führt sie aber als benannte Shards über `scripts/test-live-shard.mjs` statt als einen seriellen Job aus: - `native-live-src-agents` - `native-live-src-gateway-core` @@ -225,33 +225,33 @@ Das Release-Live/E2E-Child behält die breite native `pnpm test:live`-Abdeckung - `native-live-extensions-openai` - `native-live-extensions-o-z-other` - `native-live-extensions-xai` -- aufgeteilte Medien-Audio/Video-Shards und Provider-gefilterte Musik-Shards +- Aufgeteilte Media-Audio/Video-Shards und Provider-gefilterte Musik-Shards -Das behält dieselbe Dateiabdeckung bei und macht langsame Live-Provider-Fehler leichter erneut ausführbar und diagnostizierbar. Die aggregierten Shard-Namen `native-live-extensions-o-z`, `native-live-extensions-media` und `native-live-extensions-media-music` bleiben für manuelle einmalige Reruns gültig. +Dadurch bleibt dieselbe Datei-Abdeckung erhalten, während langsame Live-Provider-Fehler leichter erneut auszuführen und zu diagnostizieren sind. Die aggregierten Shard-Namen `native-live-extensions-o-z`, `native-live-extensions-media` und `native-live-extensions-media-music` bleiben für manuelle One-Shot-Reruns gültig. -Die nativen Live-Medien-Shards laufen in `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, gebaut durch den Workflow `Live Media Runner Image`. Dieses Image installiert `ffmpeg` und `ffprobe` vor; Medien-Jobs prüfen vor dem Setup nur die Binärdateien. Lassen Sie Docker-gestützte Live-Suites auf normalen Blacksmith-Runnern laufen — Container-Jobs sind der falsche Ort, um verschachtelte Docker-Tests zu starten. +Die nativen Live-Media-Shards laufen in `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, gebaut vom Workflow `Live Media Runner Image`. Dieses Image installiert `ffmpeg` und `ffprobe` vorab; Media-Jobs prüfen vor dem Setup nur die Binärdateien. Lassen Sie Docker-gestützte Live-Suites auf normalen Blacksmith-Runnern laufen — Container-Jobs sind der falsche Ort, um verschachtelte Docker-Tests zu starten. -Docker-gestützte Live-Modell/Backend-Shards verwenden ein separates gemeinsames Image `ghcr.io/openclaw/openclaw-live-test:` pro ausgewähltem Commit. Der Live-Release-Workflow baut und pusht dieses Image einmal; anschließend laufen die Docker-Live-Modell-, Provider-geshardeten Gateway-, CLI-Backend-, ACP-Bind- und Codex-Harness-Shards mit `OPENCLAW_SKIP_DOCKER_BUILD=1`. Gateway-Docker-Shards haben explizite Timeout-Obergrenzen auf Skriptebene unterhalb des Workflow-Job-Timeouts, damit ein hängender Container oder Cleanup-Pfad schnell fehlschlägt, statt das gesamte Release-Check-Budget zu verbrauchen. Wenn diese Shards das vollständige Source-Docker-Target unabhängig neu bauen, ist der Release-Run falsch konfiguriert und verschwendet Laufzeit mit doppelten Image-Builds. +Docker-gestützte Live-Modell-/Backend-Shards verwenden ein separates gemeinsames Image `ghcr.io/openclaw/openclaw-live-test:` pro ausgewähltem Commit. Der Live-Release-Workflow baut und pusht dieses Image einmal, dann laufen die Docker-Live-Modell-, Provider-Sharded-Gateway-, CLI-Backend-, ACP-Bind- und Codex-Harness-Shards mit `OPENCLAW_SKIP_DOCKER_BUILD=1`. Gateway-Docker-Shards haben explizite Timeout-Obergrenzen auf Skriptebene unterhalb des Workflow-Job-Timeouts, sodass ein hängender Container oder Cleanup-Pfad schnell fehlschlägt, statt das gesamte Release-Check-Budget zu verbrauchen. Wenn diese Shards das vollständige Source-Docker-Target unabhängig neu bauen, ist der Release-Lauf falsch konfiguriert und verschwendet Laufzeit mit doppelten Image-Builds. ## Package Acceptance -Verwenden Sie `Package Acceptance`, wenn die Frage lautet: „Funktioniert dieses installierbare OpenClaw-Package als Produkt?“ Sie unterscheidet sich von normaler CI: Normale CI validiert den Source Tree, während Package Acceptance ein einzelnes Tarball über denselben Docker-E2E-Harness validiert, den Benutzer nach Installation oder Update ausführen. +Verwenden Sie `Package Acceptance`, wenn die Frage lautet: „Funktioniert dieses installierbare OpenClaw-Paket als Produkt?“ Es unterscheidet sich von normaler CI: Normale CI validiert den Source Tree, während Package Acceptance ein einzelnes Tarball über dasselbe Docker-E2E-Harness validiert, das Nutzer nach Installation oder Update ausführen. ### Jobs -1. `resolve_package` checkt `workflow_ref` aus, löst einen Package-Candidate auf, schreibt `.artifacts/docker-e2e-package/openclaw-current.tgz`, schreibt `.artifacts/docker-e2e-package/package-candidate.json`, lädt beide als Artefakt `package-under-test` hoch und gibt Quelle, Workflow-Ref, Package-Ref, Version, SHA-256 und Profil in der GitHub-Step-Zusammenfassung aus. -2. `docker_acceptance` ruft `openclaw-live-and-e2e-checks-reusable.yml` mit `ref=workflow_ref` und `package_artifact_name=package-under-test` auf. Der wiederverwendbare Workflow lädt dieses Artefakt herunter, validiert das Tarball-Inventar, bereitet bei Bedarf Package-Digest-Docker-Images vor und führt die ausgewählten Docker-Lanes gegen dieses Package aus, statt den Workflow-Checkout zu packen. Wenn ein Profil mehrere gezielte `docker_lanes` auswählt, bereitet der wiederverwendbare Workflow das Package und die gemeinsamen Images einmal vor und fächert diese Lanes dann als parallele gezielte Docker-Jobs mit eindeutigen Artefakten aus. +1. `resolve_package` checkt `workflow_ref` aus, löst einen Paket-Candidate auf, schreibt `.artifacts/docker-e2e-package/openclaw-current.tgz`, schreibt `.artifacts/docker-e2e-package/package-candidate.json`, lädt beide als Artefakt `package-under-test` hoch und gibt Quelle, Workflow-Ref, Paket-Ref, Version, SHA-256 und Profil in der GitHub-Step-Summary aus. +2. `docker_acceptance` ruft `openclaw-live-and-e2e-checks-reusable.yml` mit `ref=workflow_ref` und `package_artifact_name=package-under-test` auf. Der wiederverwendbare Workflow lädt dieses Artefakt herunter, validiert das Tarball-Inventar, bereitet bei Bedarf Package-Digest-Docker-Images vor und führt die ausgewählten Docker-Lanes gegen dieses Paket aus, statt den Workflow-Checkout zu packen. Wenn ein Profil mehrere gezielte `docker_lanes` auswählt, bereitet der wiederverwendbare Workflow das Paket und die gemeinsamen Images einmal vor und fächert diese Lanes dann als parallele gezielte Docker-Jobs mit eindeutigen Artefakten auf. 3. `package_telegram` ruft optional `NPM Telegram Beta E2E` auf. Es läuft, wenn `telegram_mode` nicht `none` ist, und installiert dasselbe Artefakt `package-under-test`, wenn Package Acceptance eines aufgelöst hat; eigenständige Telegram-Dispatches können weiterhin eine veröffentlichte npm-Spezifikation installieren. -4. `summary` lässt den Workflow fehlschlagen, wenn Package-Auflösung, Docker Acceptance oder die optionale Telegram-Lane fehlgeschlagen ist. +4. `summary` lässt den Workflow fehlschlagen, wenn Paketauflösung, Docker Acceptance oder die optionale Telegram-Lane fehlgeschlagen ist. ### Candidate-Quellen -- `source=npm` akzeptiert nur `openclaw@alpha`, `openclaw@beta`, `openclaw@latest` oder eine exakte OpenClaw-Release-Version wie `openclaw@2026.4.27-beta.2`. Verwenden Sie dies für veröffentlichte Prerelease-/Stable-Abnahme. -- `source=ref` packt einen vertrauenswürdigen `package_ref`-Branch, -Tag oder vollständigen Commit-SHA. Der Resolver ruft OpenClaw-Branches/Tags ab, prüft, dass der ausgewählte Commit aus der Repository-Branch-Historie oder einem Release-Tag erreichbar ist, installiert Dependencies in einem detached Worktree und packt ihn mit `scripts/package-openclaw-for-docker.mjs`. +- `source=npm` akzeptiert nur `openclaw@beta`, `openclaw@latest` oder eine exakte OpenClaw-Release-Version wie `openclaw@2026.4.27-beta.2`. Verwenden Sie dies für veröffentlichte Prerelease-/Stable-Acceptance. +- `source=ref` packt einen vertrauenswürdigen `package_ref`-Branch, -Tag oder vollständigen Commit-SHA. Der Resolver ruft OpenClaw-Branches/-Tags ab, überprüft, dass der ausgewählte Commit aus der Repository-Branch-Historie oder einem Release-Tag erreichbar ist, installiert Abhängigkeiten in einem losgelösten Worktree und packt ihn mit `scripts/package-openclaw-for-docker.mjs`. - `source=url` lädt ein HTTPS-`.tgz` herunter; `package_sha256` ist erforderlich. - `source=artifact` lädt ein `.tgz` aus `artifact_run_id` und `artifact_name` herunter; `package_sha256` ist optional, sollte aber für extern geteilte Artefakte angegeben werden. -Halten Sie `workflow_ref` und `package_ref` getrennt. `workflow_ref` ist der vertrauenswürdige Workflow-/Harness-Code, der den Test ausführt. `package_ref` ist der Source-Commit, der gepackt wird, wenn `source=ref` gilt. Dadurch kann der aktuelle Test-Harness ältere vertrauenswürdige Source-Commits validieren, ohne alte Workflow-Logik auszuführen. +Halten Sie `workflow_ref` und `package_ref` getrennt. `workflow_ref` ist der vertrauenswürdige Workflow-/Harness-Code, der den Test ausführt. `package_ref` ist der Source-Commit, der gepackt wird, wenn `source=ref` verwendet wird. Dadurch kann das aktuelle Test-Harness ältere vertrauenswürdige Source-Commits validieren, ohne alte Workflow-Logik auszuführen. ### Suite-Profile @@ -261,25 +261,25 @@ Halten Sie `workflow_ref` und `package_ref` getrennt. `workflow_ref` ist der ver - `full` — vollständige Docker-Release-Pfad-Chunks mit OpenWebUI - `custom` — exakte `docker_lanes`; erforderlich, wenn `suite_profile=custom` -Das Profil `package` verwendet Offline-Plugin-Abdeckung, damit die Validierung veröffentlichter Packages nicht von Live-ClawHub-Verfügbarkeit abhängt. Die optionale Telegram-Lane verwendet das Artefakt `package-under-test` in `NPM Telegram Beta E2E` wieder; der veröffentlichte npm-Spezifikationspfad bleibt für eigenständige Dispatches erhalten. +Das Profil `package` verwendet Offline-Plugin-Abdeckung, sodass die Validierung veröffentlichter Pakete nicht von Live-ClawHub-Verfügbarkeit abhängt. Die optionale Telegram-Lane verwendet das Artefakt `package-under-test` in `NPM Telegram Beta E2E` wieder; der veröffentlichte npm-Spezifikationspfad bleibt für eigenständige Dispatches erhalten. -Die dedizierte Update- und Plugin-Testpolicy, einschließlich lokaler Befehle, +Zur dedizierten Richtlinie für Update- und Plugin-Tests, einschließlich lokaler Befehle, Docker-Lanes, Package-Acceptance-Eingaben, Release-Defaults und Fehlertriage, -finden Sie unter [Updates und Plugins testen](/de/help/testing-updates-plugins). +siehe [Testen von Updates und Plugins](/de/help/testing-updates-plugins). -Release Checks rufen Package Acceptance mit `source=artifact`, dem vorbereiteten Release-Package-Artefakt, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`, `published_upgrade_survivor_baselines=all-since-2026.4.23`, `published_upgrade_survivor_scenarios=reported-issues` und `telegram_mode=mock-openai` auf. Dadurch bleiben Package-Migration, Update, Cleanup veralteter Plugin-Dependency, Reparatur installierter konfigurierter Plugins, Offline-Plugin, Plugin-Update und Telegram-Nachweis auf demselben aufgelösten Package-Tarball. Setzen Sie `package_acceptance_package_spec` für Full Release Validation oder OpenClaw Release Checks, um dieselbe Matrix gegen ein ausgeliefertes npm-Package statt gegen das aus dem SHA gebaute Artefakt auszuführen. Cross-OS Release Checks decken weiterhin OS-spezifisches Onboarding, Installer- und Plattformverhalten ab; Produktvalidierung für Package/Update sollte mit Package Acceptance beginnen. Die Docker-Lane `published-upgrade-survivor` validiert pro Run eine veröffentlichte Package-Baseline. In Package Acceptance ist das aufgelöste Tarball `package-under-test` immer der Candidate, und `published_upgrade_survivor_baseline` wählt die veröffentlichte Fallback-Baseline aus, standardmäßig `openclaw@latest`; Rerun-Befehle für fehlgeschlagene Lanes behalten diese Baseline bei. Setzen Sie `published_upgrade_survivor_baselines=all-since-2026.4.23`, um Full Release CI über jede stabile npm-Version von `2026.4.23` bis `latest` zu erweitern; `release-history` bleibt für manuelle breitere Stichproben mit dem älteren Vordatums-Anker verfügbar. Setzen Sie `published_upgrade_survivor_scenarios=reported-issues`, um dieselben Baselines über issue-förmige Fixtures für Feishu-Konfiguration, erhaltene Bootstrap-/Persona-Dateien, konfigurierte OpenClaw-Plugin-Installationen, Tilde-Logpfade und veraltete Legacy-Plugin-Dependency-Roots zu erweitern. Der separate Workflow `Update Migration` verwendet die Docker-Lane `update-migration` mit `all-since-2026.4.23` und `plugin-deps-cleanup`, wenn die Frage eine vollständige Cleanup-Prüfung veröffentlichter Updates ist und nicht die normale Breite von Full Release CI. Lokale Aggregat-Runs können exakte Package-Spezifikationen mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` übergeben, eine einzelne Lane mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` wie `openclaw@2026.4.15` beibehalten oder `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` für die Szenario-Matrix setzen. Die veröffentlichte Lane konfiguriert die Baseline mit einem eingebauten `openclaw config set`-Befehlsrezept, zeichnet Rezeptschritte in `summary.json` auf und prüft nach Gateway-Start `/healthz`, `/readyz` sowie RPC-Status. Die frischen Windows-Packaged- und Installer-Lanes prüfen außerdem, dass ein installiertes Package einen Browser-Control-Override aus einem rohen absoluten Windows-Pfad importieren kann. Der OpenAI-Cross-OS-Agent-Turn-Smoke verwendet standardmäßig `OPENCLAW_CROSS_OS_OPENAI_MODEL`, wenn gesetzt, andernfalls `openai/gpt-5.4`, sodass der Installations- und Gateway-Nachweis auf einem GPT-5-Testmodell bleibt und GPT-4.x-Defaults vermieden werden. +Release-Checks rufen Package Acceptance mit `source=artifact`, dem vorbereiteten Release-Package-Artefakt, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`, `published_upgrade_survivor_baselines=all-since-2026.4.23`, `published_upgrade_survivor_scenarios=reported-issues` und `telegram_mode=mock-openai` auf. Dadurch bleiben Paketmigration, Update, Bereinigung veralteter Plugin-Abhängigkeiten, Installationsreparatur für konfigurierte Plugins, Offline-Plugin, Plugin-Update und Telegram-Nachweis auf demselben aufgelösten Paket-Tarball. Setzen Sie `package_acceptance_package_spec` bei Full Release Validation oder OpenClaw Release Checks, um dieselbe Matrix gegen ein ausgeliefertes npm-Paket statt gegen das aus dem SHA gebaute Artefakt auszuführen. Cross-OS-Release-Checks decken weiterhin betriebssystemspezifisches Onboarding-, Installer- und Plattformverhalten ab; Produktvalidierung für Pakete/Updates sollte mit Package Acceptance beginnen. Die Docker-Lane `published-upgrade-survivor` validiert eine veröffentlichte Paket-Baseline pro Lauf. In Package Acceptance ist das aufgelöste Tarball `package-under-test` immer der Candidate, und `published_upgrade_survivor_baseline` wählt die veröffentlichte Fallback-Baseline aus, standardmäßig `openclaw@latest`; Befehle zur erneuten Ausführung fehlgeschlagener Lanes behalten diese Baseline bei. Setzen Sie `published_upgrade_survivor_baselines=all-since-2026.4.23`, um Full Release CI über jedes stabile npm-Release von `2026.4.23` bis `latest` zu erweitern; `release-history` bleibt für manuelles breiteres Sampling mit dem älteren Pre-Date-Anker verfügbar. Setzen Sie `published_upgrade_survivor_scenarios=reported-issues`, um dieselben Baselines über issue-förmige Fixtures für Feishu-Konfiguration, erhaltene Bootstrap-/Persona-Dateien, konfigurierte OpenClaw-Plugin-Installationen, Tilde-Logpfade und veraltete Legacy-Plugin-Abhängigkeits-Roots zu erweitern. Der separate Workflow `Update Migration` verwendet die Docker-Lane `update-migration` mit `all-since-2026.4.23` und `plugin-deps-cleanup`, wenn es um erschöpfende veröffentlichte Update-Bereinigung geht, nicht um normale Full-Release-CI-Breite. Lokale aggregierte Läufe können exakte Paketspezifikationen mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` übergeben, eine einzelne Lane mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` wie `openclaw@2026.4.15` beibehalten oder `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` für die Szenario-Matrix setzen. Die veröffentlichte Lane konfiguriert die Baseline mit einem eingebetteten `openclaw config set`-Befehlsrezept, zeichnet Rezeptschritte in `summary.json` auf und prüft `/healthz`, `/readyz` sowie den RPC-Status nach dem Gateway-Start. Die frischen Windows-Packaged- und Installer-Lanes prüfen außerdem, dass ein installiertes Paket einen Browser-Control-Override aus einem rohen absoluten Windows-Pfad importieren kann. Der OpenAI-Cross-OS-Agent-Turn-Smoke verwendet standardmäßig `OPENCLAW_CROSS_OS_OPENAI_MODEL`, wenn gesetzt, andernfalls `openai/gpt-5.4`, sodass Installations- und Gateway-Nachweis auf einem GPT-5-Testmodell bleiben und GPT-4.x-Defaults vermieden werden. ### Legacy-Kompatibilitätsfenster -Package Acceptance hat begrenzte Legacy-Kompatibilitätsfenster für bereits veröffentlichte Packages. Packages bis `2026.4.25`, einschließlich `2026.4.25-beta.*`, dürfen den Kompatibilitätspfad verwenden: +Package Acceptance hat begrenzte Legacy-Kompatibilitätsfenster für bereits veröffentlichte Pakete. Pakete bis einschließlich `2026.4.25`, einschließlich `2026.4.25-beta.*`, können den Kompatibilitätspfad verwenden: -- bekannte private QA-Einträge in `dist/postinstall-inventory.json` dürfen auf Dateien zeigen, die im Tarball fehlen; -- `doctor-switch` darf den Teilfall zur Persistenz von `gateway install --wrapper` überspringen, wenn das Package dieses Flag nicht bereitstellt; -- `update-channel-switch` darf fehlende `pnpm.patchedDependencies` aus der vom Tarball abgeleiteten Fake-Git-Fixture entfernen und fehlendes persistiertes `update.channel` protokollieren; -- Plugin-Smokes dürfen Legacy-Speicherorte von Installationsdatensätzen lesen oder fehlende Marketplace-Persistenz von Installationsdatensätzen akzeptieren; -- `plugin-update` darf Konfigurationsmetadaten-Migration zulassen, während weiterhin verlangt wird, dass Installationsdatensatz und No-Reinstall-Verhalten unverändert bleiben. +- bekannte private QA-Einträge in `dist/postinstall-inventory.json` dürfen auf Dateien verweisen, die im Tarball fehlen; +- `doctor-switch` darf den Unterfall zur Persistenz von `gateway install --wrapper` überspringen, wenn das Paket dieses Flag nicht bereitstellt; +- `update-channel-switch` darf fehlende `pnpm.patchedDependencies` aus dem aus dem Tarball abgeleiteten Fake-Git-Fixture entfernen und darf fehlendes persistiertes `update.channel` protokollieren; +- Plugin-Smokes dürfen Legacy-Install-Record-Speicherorte lesen oder fehlende Marketplace-Install-Record-Persistenz akzeptieren; +- `plugin-update` darf die Migration von Konfigurationsmetadaten zulassen, während weiterhin gefordert wird, dass Install Record und No-Reinstall-Verhalten unverändert bleiben. -Das veröffentlichte Package `2026.4.26` darf außerdem vor lokal gebauten Metadaten-Stamp-Dateien warnen, die bereits ausgeliefert wurden. Spätere Packages müssen die modernen Verträge erfüllen; dieselben Bedingungen schlagen dann fehl, statt zu warnen oder übersprungen zu werden. +Das veröffentlichte Paket `2026.4.26` darf auch vor lokal bereits ausgelieferten Build-Metadaten-Stamp-Dateien warnen. Spätere Pakete müssen die modernen Verträge erfüllen; dieselben Bedingungen schlagen dann fehl, statt zu warnen oder übersprungen zu werden. ### Beispiele @@ -322,60 +322,60 @@ gh workflow run package-acceptance.yml \ -f docker_lanes='install-e2e plugin-update' ``` -Beginnen Sie beim Debuggen eines fehlgeschlagenen Package-Acceptance-Laufs mit der `resolve_package`-Zusammenfassung, um Paketquelle, Version und SHA-256 zu bestätigen. Prüfen Sie anschließend den untergeordneten `docker_acceptance`-Lauf und seine Docker-Artefakte: `.artifacts/docker-tests/**/summary.json`, `failures.json`, Lane-Logs, Phasenzeiten und Befehle für erneute Läufe. Führen Sie bevorzugt das fehlgeschlagene Paketprofil oder die exakten Docker-Lanes erneut aus, statt die vollständige Release-Validierung erneut zu starten. +Beginnen Sie beim Debuggen eines fehlgeschlagenen Paketakzeptanzlaufs mit der Zusammenfassung `resolve_package`, um Paketquelle, Version und SHA-256 zu bestätigen. Prüfen Sie anschließend den untergeordneten Lauf `docker_acceptance` und seine Docker-Artefakte: `.artifacts/docker-tests/**/summary.json`, `failures.json`, Lane-Logs, Phasen-Timings und Befehle zum erneuten Ausführen. Führen Sie bevorzugt das fehlgeschlagene Paketprofil oder die exakten Docker-Lanes erneut aus, statt die vollständige Release-Validierung erneut zu starten. ## Installations-Smoke-Test -Der separate Workflow `Install Smoke` verwendet dasselbe Scope-Skript über seinen eigenen `preflight`-Job wieder. Er teilt die Smoke-Abdeckung in `run_fast_install_smoke` und `run_full_install_smoke` auf. +Der separate Workflow `Install Smoke` verwendet dasselbe Scope-Skript über seinen eigenen Job `preflight` wieder. Er teilt die Smoke-Abdeckung in `run_fast_install_smoke` und `run_full_install_smoke` auf. -- **Schneller Pfad** läuft für Pull Requests, die Docker-/Paket-Oberflächen, Änderungen an gebündelten Plugin-Paketen/-Manifesten oder Core-Plugin-/Channel-/Gateway-/Plugin SDK-Oberflächen betreffen, die von den Docker-Smoke-Jobs geprüft werden. Reine Source-Änderungen an gebündelten Plugins, reine Teständerungen und reine Dokumentationsänderungen reservieren keine Docker-Worker. Der schnelle Pfad baut das Root-Dockerfile-Image einmal, prüft die CLI, führt den Agents-Delete-Shared-Workspace-CLI-Smoke-Test aus, führt das Container-Gateway-Network-E2E aus, verifiziert ein Build-Argument für gebündelte Erweiterungen und führt das begrenzte gebündelte-Plugin-Docker-Profil unter einem aggregierten Befehls-Timeout von 240 Sekunden aus (jeder Docker-Lauf eines Szenarios ist separat begrenzt). -- **Vollständiger Pfad** behält QR-Paketinstallation sowie Installer-Docker-/Update-Abdeckung für nächtlich geplante Läufe, manuelle Dispatches, Workflow-Call-Release-Checks und Pull Requests bei, die tatsächlich Installer-/Paket-/Docker-Oberflächen betreffen. Im vollständigen Modus bereitet Install-Smoke ein Root-Dockerfile-Smoke-Image aus GHCR für die Ziel-SHA vor oder verwendet es wieder und führt dann QR-Paketinstallation, Root-Dockerfile-/Gateway-Smokes, Installer-/Update-Smokes und das schnelle gebündelte-Plugin-Docker-E2E als separate Jobs aus, damit Installer-Arbeit nicht hinter den Root-Image-Smokes warten muss. +- **Schneller Pfad** läuft für Pull Requests, die Docker-/Paketoberflächen, Änderungen an gebündelten Plugin-Paketen/-Manifesten oder Kernoberflächen für Plugin/Kanal/Gateway/Plugin SDK berühren, die von den Docker-Smoke-Jobs ausgeführt werden. Reine Quelländerungen an gebündelten Plugins, reine Teständerungen und reine Dokumentationsänderungen reservieren keine Docker-Worker. Der schnelle Pfad baut das Root-Dockerfile-Image einmal, prüft die CLI, führt den CLI-Smoke-Test zum Löschen des gemeinsamen Arbeitsbereichs der Agents aus, führt den Container-Gateway-Netzwerk-E2E-Test aus, verifiziert ein Build-Argument für gebündelte Erweiterungen und führt das begrenzte gebündelte-Plugin-Docker-Profil mit einem aggregierten Befehls-Timeout von 240 Sekunden aus, wobei jeder Docker-Lauf eines Szenarios separat begrenzt ist. +- **Vollständiger Pfad** behält QR-Paketinstallation sowie Installer-Docker-/Update-Abdeckung für nächtlich geplante Läufe, manuelle Dispatches, Workflow-Call-Release-Checks und Pull Requests bei, die tatsächlich Installer-/Paket-/Docker-Oberflächen berühren. Im vollständigen Modus bereitet install-smoke ein Ziel-SHA-GHCR-Root-Dockerfile-Smoke-Image vor oder verwendet es wieder und führt dann QR-Paketinstallation, Root-Dockerfile-/Gateway-Smokes, Installer-/Update-Smokes und das schnelle gebündelte-Plugin-Docker-E2E als separate Jobs aus, damit Installer-Arbeit nicht hinter den Root-Image-Smokes warten muss. -`main`-Pushes (einschließlich Merge-Commits) erzwingen den vollständigen Pfad nicht; wenn die Changed-Scope-Logik bei einem Push vollständige Abdeckung anfordern würde, behält der Workflow den schnellen Docker-Smoke-Test bei und überlässt den vollständigen Install-Smoke-Test der nächtlichen oder Release-Validierung. +`main`-Pushes (einschließlich Merge-Commits) erzwingen den vollständigen Pfad nicht; wenn die Changed-Scope-Logik bei einem Push vollständige Abdeckung anfordern würde, behält der Workflow den schnellen Docker-Smoke-Test bei und überlässt den vollständigen Installations-Smoke-Test der nächtlichen oder Release-Validierung. -Der langsame Bun-Global-Install-Image-Provider-Smoke-Test wird separat durch `run_bun_global_install_smoke` gesteuert. Er läuft im nächtlichen Zeitplan und aus dem Release-Checks-Workflow, und manuelle `Install Smoke`-Dispatches können ihn optional aktivieren, Pull Requests und `main`-Pushes jedoch nicht. QR- und Installer-Docker-Tests behalten ihre eigenen installfokussierten Dockerfiles. +Der langsame Bun-Global-Install-Image-Provider-Smoke-Test wird separat durch `run_bun_global_install_smoke` gesteuert. Er läuft im nächtlichen Zeitplan und aus dem Release-Checks-Workflow heraus, und manuelle `Install Smoke`-Dispatches können ihn aktivieren, Pull Requests und `main`-Pushes jedoch nicht. QR- und Installer-Docker-Tests behalten ihre eigenen installfokussierten Dockerfiles. ## Lokales Docker-E2E -`pnpm test:docker:all` baut ein gemeinsames Live-Test-Image vor, packt OpenClaw einmal als npm-Tarball und baut zwei gemeinsame `scripts/e2e/Dockerfile`-Images: +`pnpm test:docker:all` baut ein gemeinsames Live-Test-Image vorab, packt OpenClaw einmal als npm-Tarball und baut zwei gemeinsame `scripts/e2e/Dockerfile`-Images: - einen einfachen Node-/Git-Runner für Installer-/Update-/Plugin-Abhängigkeits-Lanes; -- ein funktionsfähiges Image, das denselben Tarball für normale Funktions-Lanes in `/app` installiert. +- ein funktionales Image, das denselben Tarball für normale Funktions-Lanes nach `/app` installiert. -Docker-Lane-Definitionen befinden sich in `scripts/lib/docker-e2e-scenarios.mjs`, die Planerlogik in `scripts/lib/docker-e2e-plan.mjs`, und der Runner führt nur den ausgewählten Plan aus. Der Scheduler wählt das Image pro Lane mit `OPENCLAW_DOCKER_E2E_BARE_IMAGE` und `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` aus und führt Lanes dann mit `OPENCLAW_SKIP_DOCKER_BUILD=1` aus. +Docker-Lane-Definitionen befinden sich in `scripts/lib/docker-e2e-scenarios.mjs`, die Planerlogik in `scripts/lib/docker-e2e-plan.mjs`, und der Runner führt nur den ausgewählten Plan aus. Der Scheduler wählt das Image pro Lane mit `OPENCLAW_DOCKER_E2E_BARE_IMAGE` und `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` aus und führt Lanes anschließend mit `OPENCLAW_SKIP_DOCKER_BUILD=1` aus. ### Einstellbare Parameter | Variable | Standard | Zweck | | -------------------------------------- | -------- | --------------------------------------------------------------------------------------------- | -| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Slot-Anzahl im Hauptpool für normale Lanes. | -| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Provider-sensible Slot-Anzahl im Tail-Pool. | -| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Limit für gleichzeitige Live-Lanes, damit Provider nicht drosseln. | -| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Limit für gleichzeitige npm-Install-Lanes. | -| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Limit für gleichzeitige Multi-Service-Lanes. | -| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Versatz zwischen Lane-Starts, um Docker-Daemon-Create-Stürme zu vermeiden; `0` deaktiviert den Versatz. | -| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Fallback-Timeout pro Lane (120 Minuten); ausgewählte Live-/Tail-Lanes verwenden strengere Limits. | -| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` gibt den Scheduler-Plan aus, ohne Lanes auszuführen. | -| `OPENCLAW_DOCKER_ALL_LANES` | unset | Durch Kommas getrennte exakte Lane-Liste; überspringt Cleanup-Smoke, damit Agents eine fehlgeschlagene Lane reproduzieren können. | +| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Slot-Anzahl des Haupt-Pools für normale Lanes. | +| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Provider-sensible Slot-Anzahl des Tail-Pools. | +| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Obergrenze für gleichzeitige Live-Lanes, damit Provider nicht drosseln. | +| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Obergrenze für gleichzeitige npm-Install-Lanes. | +| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Obergrenze für gleichzeitige Multi-Service-Lanes. | +| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Staffelung zwischen Lane-Starts zur Vermeidung von Docker-Daemon-Erstellungswellen; setzen Sie `0` für keine Staffelung. | +| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Fallback-Timeout pro Lane (120 Minuten); ausgewählte Live-/Tail-Lanes verwenden engere Grenzen. | +| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` gibt den Scheduler-Plan aus, ohne Lanes auszuführen. | +| `OPENCLAW_DOCKER_ALL_LANES` | unset | Durch Kommas getrennte exakte Lane-Liste; überspringt den Cleanup-Smoke, damit Agents eine fehlgeschlagene Lane reproduzieren können. | -Eine Lane, die schwerer ist als ihr effektives Limit, kann dennoch aus einem leeren Pool starten und läuft dann allein, bis sie Kapazität freigibt. Die lokale aggregierte Vorprüfung prüft Docker, entfernt veraltete OpenClaw-E2E-Container, gibt den Status aktiver Lanes aus, speichert Lane-Zeiten für Longest-First-Sortierung und plant standardmäßig nach dem ersten Fehler keine neuen gepoolten Lanes mehr ein. +Eine Lane, die schwerer als ihre effektive Grenze ist, kann trotzdem aus einem leeren Pool starten und läuft dann allein, bis sie Kapazität freigibt. Die lokale Aggregation führt Docker-Preflights aus, entfernt veraltete OpenClaw-E2E-Container, gibt den Status aktiver Lanes aus, persistiert Lane-Timings für Longest-first-Sortierung und stoppt standardmäßig nach dem ersten Fehler die Planung neuer gepoolter Lanes. ### Wiederverwendbarer Live-/E2E-Workflow -Der wiederverwendbare Live-/E2E-Workflow fragt `scripts/test-docker-all.mjs --plan-json`, welche Paket-, Image-Art, welches Live-Image sowie welche Lane- und Zugangsdaten-Abdeckung erforderlich sind. `scripts/docker-e2e.mjs` wandelt diesen Plan dann in GitHub-Ausgaben und Zusammenfassungen um. Es packt OpenClaw entweder über `scripts/package-openclaw-for-docker.mjs`, lädt ein Paketartefakt des aktuellen Laufs herunter oder lädt ein Paketartefakt aus `package_artifact_run_id`; validiert das Tarball-Inventar; baut und pusht paketdigest-getaggte Bare-/Functional-GHCR-Docker-E2E-Images über Blacksmiths Docker-Layer-Cache, wenn der Plan Lanes mit installiertem Paket benötigt; und verwendet angegebene Eingaben `docker_e2e_bare_image`/`docker_e2e_functional_image` oder vorhandene Paketdigest-Images wieder, statt neu zu bauen. Docker-Image-Pulls werden mit einem begrenzten Timeout von 180 Sekunden pro Versuch erneut versucht, damit ein hängender Registry-/Cache-Stream schnell erneut versucht wird, statt den Großteil des kritischen CI-Pfads zu verbrauchen. +Der wiederverwendbare Live-/E2E-Workflow fragt `scripts/test-docker-all.mjs --plan-json`, welche Paket-, Image-Art-, Live-Image-, Lane- und Zugangsdatenabdeckung erforderlich ist. `scripts/docker-e2e.mjs` wandelt diesen Plan anschließend in GitHub-Ausgaben und Zusammenfassungen um. Es packt OpenClaw entweder über `scripts/package-openclaw-for-docker.mjs`, lädt ein Paketartefakt aus dem aktuellen Lauf herunter oder lädt ein Paketartefakt aus `package_artifact_run_id` herunter; validiert das Tarball-Inventar; baut und pusht paketdigest-getaggte Bare-/Functional-GHCR-Docker-E2E-Images über Blacksmiths Docker-Layer-Cache, wenn der Plan paketinstallierte Lanes benötigt; und verwendet bereitgestellte Eingaben `docker_e2e_bare_image`/`docker_e2e_functional_image` oder vorhandene Paketdigest-Images wieder, statt neu zu bauen. Docker-Image-Pulls werden mit einem begrenzten Timeout von 180 Sekunden pro Versuch erneut versucht, damit ein hängender Registry-/Cache-Stream schnell erneut versucht wird, statt den Großteil des kritischen CI-Pfads zu verbrauchen. -### Release-Pfad-Chunks +### Release-Pfad-Blöcke -Release-Docker-Abdeckung läuft in kleineren aufgeteilten Jobs mit `OPENCLAW_SKIP_DOCKER_BUILD=1`, sodass jeder Chunk nur die benötigte Image-Art zieht und mehrere Lanes über denselben gewichteten Scheduler ausführt: +Die Release-Docker-Abdeckung läuft in kleineren aufgeteilten Jobs mit `OPENCLAW_SKIP_DOCKER_BUILD=1`, sodass jeder Block nur die benötigte Image-Art zieht und mehrere Lanes über denselben gewichteten Scheduler ausführt: - `OPENCLAW_DOCKER_ALL_PROFILE=release-path` - `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h` -Aktuelle Release-Docker-Chunks sind `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services` und `plugins-runtime-install-a` bis `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` und `plugins-integrations` bleiben aggregierte Plugin-/Runtime-Aliasse. Der Lane-Alias `install-e2e` bleibt der aggregierte manuelle Rerun-Alias für beide Provider-Installer-Lanes. +Aktuelle Release-Docker-Blöcke sind `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services` sowie `plugins-runtime-install-a` bis `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` und `plugins-integrations` bleiben aggregierte Plugin-/Runtime-Aliase. Der Lane-Alias `install-e2e` bleibt der aggregierte manuelle Wiederholungslauf-Alias für beide Provider-Installer-Lanes. -OpenWebUI wird in `plugins-runtime-services` aufgenommen, wenn vollständige Release-Pfad-Abdeckung es anfordert, und behält nur für reine OpenWebUI-Dispatches einen eigenständigen `openwebui`-Chunk. Update-Lanes für gebündelte Channels versuchen bei vorübergehenden npm-Netzwerkfehlern einmal erneut. +OpenWebUI wird in `plugins-runtime-services` eingebunden, wenn vollständige Release-Pfad-Abdeckung dies anfordert, und behält nur für OpenWebUI-only-Dispatches einen eigenständigen Block `openwebui`. Update-Lanes für gebündelte Kanäle versuchen bei vorübergehenden npm-Netzwerkfehlern einmal erneut. -Jeder Chunk lädt `.artifacts/docker-tests/` mit Lane-Logs, Zeiten, `summary.json`, `failures.json`, Phasenzeiten, Scheduler-Plan-JSON, Tabellen langsamer Lanes und Rerun-Befehlen pro Lane hoch. Die Workflow-Eingabe `docker_lanes` führt ausgewählte Lanes gegen die vorbereiteten Images statt der Chunk-Jobs aus, wodurch das Debugging fehlgeschlagener Lanes auf einen gezielten Docker-Job begrenzt bleibt und das Paketartefakt für diesen Lauf vorbereitet, heruntergeladen oder wiederverwendet wird; wenn eine ausgewählte Lane eine Live-Docker-Lane ist, baut der gezielte Job das Live-Test-Image lokal für diesen erneuten Lauf. Generierte GitHub-Rerun-Befehle pro Lane enthalten `package_artifact_run_id`, `package_artifact_name` und vorbereitete Image-Eingaben, wenn diese Werte existieren, sodass eine fehlgeschlagene Lane exakt dasselbe Paket und dieselben Images aus dem fehlgeschlagenen Lauf wiederverwenden kann. +Jeder Block lädt `.artifacts/docker-tests/` mit Lane-Logs, Timings, `summary.json`, `failures.json`, Phasen-Timings, Scheduler-Plan-JSON, Tabellen langsamer Lanes und Wiederholungslaufbefehlen pro Lane hoch. Die Workflow-Eingabe `docker_lanes` führt ausgewählte Lanes gegen die vorbereiteten Images aus statt gegen die Block-Jobs. Dadurch bleibt das Debuggen fehlgeschlagener Lanes auf einen gezielten Docker-Job begrenzt, und das Paketartefakt für diesen Lauf wird vorbereitet, heruntergeladen oder wiederverwendet; wenn eine ausgewählte Lane eine Live-Docker-Lane ist, baut der gezielte Job das Live-Test-Image für diesen Wiederholungslauf lokal. Generierte GitHub-Wiederholungslaufbefehle pro Lane enthalten `package_artifact_run_id`, `package_artifact_name` und vorbereitete Image-Eingaben, sofern diese Werte vorhanden sind, sodass eine fehlgeschlagene Lane exakt dasselbe Paket und dieselben Images aus dem fehlgeschlagenen Lauf wiederverwenden kann. ```bash pnpm test:docker:rerun # download Docker artifacts and print combined/per-lane targeted rerun commands @@ -384,89 +384,89 @@ pnpm test:docker:timings # slow-lane and phase critical-path summari Der geplante Live-/E2E-Workflow führt täglich die vollständige Release-Pfad-Docker-Suite aus. -## Plugin-Vorveröffentlichung +## Plugin-Prerelease -`Plugin Prerelease` ist teurere Produkt-/Paket-Abdeckung und daher ein separater Workflow, der von `Full Release Validation` oder durch einen expliziten Operator ausgelöst wird. Normale Pull Requests, `main`-Pushes und eigenständige manuelle CI-Dispatches lassen diese Suite deaktiviert. Er verteilt gebündelte Plugin-Tests auf acht Erweiterungs-Worker; diese Erweiterungs-Shard-Jobs führen bis zu zwei Plugin-Konfigurationsgruppen gleichzeitig mit einem Vitest-Worker pro Gruppe und einem größeren Node-Heap aus, damit importlastige Plugin-Batches keine zusätzlichen CI-Jobs erzeugen. Der Release-only-Docker-Prerelease-Pfad bündelt gezielte Docker-Lanes in kleinen Gruppen, um nicht Dutzende Runner für ein- bis dreiminütige Jobs zu reservieren. +`Plugin Prerelease` ist teurere Produkt-/Paketabdeckung, daher ist es ein separater Workflow, der durch `Full Release Validation` oder durch einen expliziten Operator ausgelöst wird. Normale Pull Requests, `main`-Pushes und eigenständige manuelle CI-Dispatches halten diese Suite deaktiviert. Er verteilt Tests gebündelter Plugins auf acht Erweiterungs-Worker; diese Erweiterungs-Shard-Jobs führen jeweils bis zu zwei Plugin-Konfigurationsgruppen gleichzeitig aus, mit einem Vitest-Worker pro Gruppe und größerem Node-Heap, damit importlastige Plugin-Batches keine zusätzlichen CI-Jobs erzeugen. Der nur für Releases vorgesehene Docker-Prerelease-Pfad bündelt gezielte Docker-Lanes in kleinen Gruppen, um nicht Dutzende Runner für Jobs von ein bis drei Minuten zu reservieren. -## QA-Lab +## QA Lab -QA Lab hat dedizierte CI-Lanes außerhalb des wichtigsten smart-gescopten Workflows. Agentische Parität ist unter den breiten QA- und Release-Harnesses verschachtelt, nicht als eigenständiger PR-Workflow. Verwenden Sie `Full Release Validation` mit `rerun_group=qa-parity`, wenn Parität mit einem breiten Validierungslauf mitlaufen soll. +QA Lab verfügt über dedizierte CI-Lanes außerhalb des zentralen Smart-Scoped-Workflows. Agentische Parität ist unter die breiten QA- und Release-Harnesses geschachtelt, nicht als eigenständiger PR-Workflow. Verwenden Sie `Full Release Validation` mit `rerun_group=qa-parity`, wenn Parität Teil eines breiten Validierungslaufs sein soll. -- Der Workflow `QA-Lab - All Lanes` läuft nächtlich auf `main` und bei manuellem Dispatch; er fächert die Mock-Parity-Lane, Live-Matrix-Lane sowie Live-Telegram- und Discord-Lanes als parallele Jobs auf. Live-Jobs verwenden die Umgebung `qa-live-shared`, und Telegram/Discord verwenden Convex-Leases. +- Der Workflow `QA-Lab - All Lanes` läuft nächtlich auf `main` und bei manuellem Dispatch; er fächert die Mock-Paritäts-Lane, Live-Matrix-Lane sowie Live-Telegram- und Discord-Lanes als parallele Jobs auf. Live-Jobs verwenden die Umgebung `qa-live-shared`, und Telegram/Discord verwenden Convex-Leases. -Release-Checks führen Matrix- und Telegram-Live-Transport-Lanes mit dem deterministischen Mock-Provider und mock-qualifizierten Modellen (`mock-openai/gpt-5.5` und `mock-openai/gpt-5.5-alt`) aus, sodass der Channel-Vertrag von Live-Modell-Latenz und normalem Provider-Plugin-Start isoliert ist. Das Live-Transport-Gateway deaktiviert die Memory-Suche, weil QA-Parität Memory-Verhalten separat abdeckt; Provider-Konnektivität wird durch die separaten Live-Modell-, nativen Provider- und Docker-Provider-Suites abgedeckt. +Release-Checks führen Matrix- und Telegram-Live-Transport-Lanes mit dem deterministischen Mock-Provider und mockqualifizierten Modellen (`mock-openai/gpt-5.5` und `mock-openai/gpt-5.5-alt`) aus, sodass der Kanalvertrag von Live-Modelllatenz und normalem Provider-Plugin-Start isoliert ist. Das Live-Transport-Gateway deaktiviert die Speichersuche, da QA-Parität das Speicherverhalten separat abdeckt; Provider-Konnektivität wird durch die separaten Live-Modell-, nativen Provider- und Docker-Provider-Suites abgedeckt. -Matrix verwendet `--profile fast` für geplante und Release-Gates und fügt `--fail-fast` nur hinzu, wenn die ausgecheckte CLI dies unterstützt. Der CLI-Standard und die manuelle Workflow-Eingabe bleiben `all`; manuelle `matrix_profile=all`-Dispatches sharden vollständige Matrix-Abdeckung immer in die Jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` und `e2ee-cli`. +Matrix verwendet `--profile fast` für geplante und Release-Gates und ergänzt `--fail-fast` nur, wenn die ausgecheckte CLI dies unterstützt. Der CLI-Standard und die manuelle Workflow-Eingabe bleiben `all`; ein manueller Dispatch mit `matrix_profile=all` shardet vollständige Matrix-Abdeckung immer in die Jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` und `e2ee-cli`. -`OpenClaw Release Checks` führt außerdem die releasekritischen QA-Lab-Lanes vor der Release-Freigabe aus; sein QA-Parity-Gate führt Candidate- und Baseline-Packs als parallele Lane-Jobs aus und lädt anschließend beide Artefakte in einen kleinen Berichtsjob für den finalen Paritätsvergleich herunter. +`OpenClaw Release Checks` führt außerdem die releasekritischen QA-Lab-Lanes vor der Release-Freigabe aus; sein QA-Paritäts-Gate führt Kandidaten- und Baseline-Pakete als parallele Lane-Jobs aus und lädt anschließend beide Artefakte in einen kleinen Berichtsjob für den finalen Paritätsvergleich herunter. -Folgen Sie bei normalen PRs gescopten CI-/Check-Nachweisen, statt Parität als erforderlichen Status zu behandeln. +Für normale PRs verwenden Sie gescopte CI-/Check-Nachweise, statt Parität als erforderlichen Status zu behandeln. ## CodeQL -Der `CodeQL`-Workflow ist absichtlich ein eng gefasster Security-Scanner für den ersten Durchlauf, nicht der vollständige Repository-Sweep. Tägliche, manuelle und nicht als Draft markierte Pull-Request-Guard-Läufe scannen Actions-Workflow-Code sowie die risikoreichsten JavaScript-/TypeScript-Bereiche mit Security-Abfragen mit hoher Konfidenz, gefiltert auf hohe/kritische `security-severity`. +Der `CodeQL`-Workflow ist bewusst als enger Sicherheits-Scanner für den ersten Durchlauf angelegt, nicht als vollständige Repository-Prüfung. Tägliche, manuelle und Wächterläufe für Pull Requests, die keine Entwürfe sind, scannen Actions-Workflow-Code sowie die JavaScript/TypeScript-Flächen mit dem höchsten Risiko und verwenden Sicherheitsabfragen mit hoher Konfidenz, gefiltert auf hohe/kritische `security-severity`. -Der Pull-Request-Guard bleibt leichtgewichtig: Er startet nur bei Änderungen unter `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` oder `src`, und er führt dieselbe Security-Matrix mit hoher Konfidenz aus wie der geplante Workflow. Android- und macOS-CodeQL bleiben außerhalb der PR-Standardwerte. +Der Pull-Request-Wächter bleibt schlank: Er startet nur bei Änderungen unter `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` oder `src` und führt dieselbe Sicherheitsmatrix mit hoher Konfidenz aus wie der geplante Workflow. Android- und macOS-CodeQL bleiben aus den PR-Standardeinstellungen heraus. -### Security-Kategorien +### Sicherheitskategorien -| Kategorie | Bereich | -| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| `/codeql-security-high/core-auth-secrets` | Auth, Secrets, Sandbox, Cron und Gateway-Baseline | -| `/codeql-security-high/channel-runtime-boundary` | Verträge der Kern-Channel-Implementierung plus Channel-Plugin-Runtime, Gateway, Plugin SDK, Secrets, Audit-Touchpoints | -| `/codeql-security-high/network-ssrf-boundary` | Kern-SSRF, IP-Parsing, Network Guard, Web-Fetch und SSRF-Policy-Bereiche des Plugin SDK | -| `/codeql-security-high/mcp-process-tool-boundary` | MCP-Server, Helfer für Prozessausführung, ausgehende Zustellung und Agent-Gates für Tool-Ausführung | -| `/codeql-security-high/plugin-trust-boundary` | Plugin-Installation, Loader, Manifest, Registry, Paketmanager-Installation, Source-Loading und Vertrauensbereiche des Plugin-SDK-Paketvertrags | +| Kategorie | Fläche | +| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `/codeql-security-high/core-auth-secrets` | Authentifizierung, Secrets, Sandbox, Cron und Gateway-Basislinie | +| `/codeql-security-high/channel-runtime-boundary` | Implementierungsverträge für zentrale Channels plus Channel-Plugin-Runtime, Gateway, Plugin SDK, Secrets, Audit-Berührungspunkte | +| `/codeql-security-high/network-ssrf-boundary` | Zentrale SSRF-, IP-Parsing-, Netzwerkschutz-, Web-Fetch- und SSRF-Policy-Flächen des Plugin SDK | +| `/codeql-security-high/mcp-process-tool-boundary` | MCP-Server, Hilfsfunktionen für Prozessausführung, ausgehende Zustellung und Gates für Tool-Ausführung durch Agents | +| `/codeql-security-high/plugin-trust-boundary` | Plugin-Installation, Loader, Manifest, Registry, Package-Manager-Installation, Source-Loading und Trust-Flächen des Plugin-SDK-Package-Vertrags | -### Plattformspezifische Security-Shards +### Plattformspezifische Sicherheits-Shards -- `CodeQL Android Critical Security` — geplanter Android-Security-Shard. Baut die Android-App manuell für CodeQL auf dem kleinsten Blacksmith-Linux-Runner, den die Workflow-Sanity akzeptiert. Lädt unter `/codeql-critical-security/android` hoch. -- `CodeQL macOS Critical Security` — wöchentlicher/manueller macOS-Security-Shard. Baut die macOS-App manuell für CodeQL auf Blacksmith macOS, filtert Dependency-Build-Ergebnisse aus dem hochgeladenen SARIF heraus und lädt unter `/codeql-critical-security/macos` hoch. Bleibt außerhalb der täglichen Standardwerte, weil der macOS-Build selbst bei sauberem Lauf die Runtime dominiert. +- `CodeQL Android Critical Security` — geplanter Android-Sicherheits-Shard. Baut die Android-App manuell für CodeQL auf dem kleinsten Blacksmith-Linux-Runner, den die Workflow-Sanity akzeptiert. Lädt unter `/codeql-critical-security/android` hoch. +- `CodeQL macOS Critical Security` — wöchentlicher/manueller macOS-Sicherheits-Shard. Baut die macOS-App manuell für CodeQL auf Blacksmith macOS, filtert Build-Ergebnisse von Abhängigkeiten aus dem hochgeladenen SARIF heraus und lädt unter `/codeql-critical-security/macos` hoch. Bleibt außerhalb der täglichen Standardeinstellungen, weil der macOS-Build selbst bei sauberem Lauf die Laufzeit dominiert. -### Critical-Quality-Kategorien +### Kategorien für Critical Quality -`CodeQL Critical Quality` ist der passende Nicht-Security-Shard. Er führt nur JavaScript-/TypeScript-Quality-Abfragen mit Fehler-Schweregrad und ohne Security-Bezug über enge, hochwertige Bereiche auf dem kleineren Blacksmith-Linux-Runner aus. Sein Pull-Request-Guard ist absichtlich kleiner als das geplante Profil: Nicht-Draft-PRs führen nur die passenden Shards `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` und `plugin-sdk-reply-runtime` für Agent-Befehls-/Modell-/Tool-Ausführung und Reply-Dispatch-Code, Konfigurationsschema-/Migrations-/IO-Code, Auth-/Secrets-/Sandbox-/Security-Code, Kern-Channel- und gebündelte Channel-Plugin-Runtime, Gateway-Protokoll-/Server-Methoden, Memory-Runtime-/SDK-Glue, MCP-/Prozess-/ausgehende Zustellung, Provider-Runtime-/Modellkatalog, Session-Diagnostics-/Delivery-Queues, Plugin-Loader, Plugin SDK/Paketvertrag oder Änderungen an der Plugin-SDK-Reply-Runtime aus. CodeQL-Konfigurations- und Quality-Workflow-Änderungen führen alle zwölf PR-Quality-Shards aus. +`CodeQL Critical Quality` ist der entsprechende Nicht-Sicherheits-Shard. Er führt nur JavaScript/TypeScript-Qualitätsabfragen mit Fehler-Schweregrad und ohne Sicherheitsbezug über enge, besonders wertvolle Flächen auf dem kleineren Blacksmith-Linux-Runner aus. Sein Pull-Request-Wächter ist bewusst kleiner als das geplante Profil: PRs, die keine Entwürfe sind, führen nur die passenden Shards `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` und `plugin-sdk-reply-runtime` aus, wenn sich Agent-Befehls-/Modell-/Tool-Ausführung und Reply-Dispatch-Code, Konfigurationsschema-/Migrations-/IO-Code, Auth-/Secrets-/Sandbox-/Sicherheitscode, zentrale Channel- und gebündelte Channel-Plugin-Runtime, Gateway-Protokoll-/Server-Methoden, Memory-Runtime-/SDK-Verbindungscode, MCP-/Prozess-/ausgehende Zustellung, Provider-Runtime-/Modellkatalog, Session-Diagnose-/Zustellungswarteschlangen, Plugin-Loader, Plugin-SDK-/Package-Vertrag oder Plugin-SDK-Reply-Runtime ändern. Änderungen an CodeQL-Konfiguration und Qualitäts-Workflow führen alle zwölf PR-Qualitäts-Shards aus. -Manueller Dispatch akzeptiert: +Manuelle Ausführung akzeptiert: ``` profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary ``` -Die engen Profile sind Teaching-/Iterations-Hooks, um einen Quality-Shard isoliert auszuführen. +Die engen Profile sind Lehr- und Iterations-Hooks, um einen Qualitäts-Shard isoliert auszuführen. -| Kategorie | Bereich | -| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/codeql-critical-quality/core-auth-secrets` | Auth, Secrets, Sandbox, Cron und Code der Gateway-Security-Grenze | -| `/codeql-critical-quality/config-boundary` | Konfigurationsschema, Migration, Normalisierung und IO-Verträge | -| `/codeql-critical-quality/gateway-runtime-boundary` | Gateway-Protokollschemas und Server-Methoden-Verträge | -| `/codeql-critical-quality/channel-runtime-boundary` | Implementierungsverträge für Kern-Channel und gebündeltes Channel-Plugin | -| `/codeql-critical-quality/agent-runtime-boundary` | Befehlsausführung, Modell-/Provider-Dispatch, Auto-Reply-Dispatch und Queues sowie ACP-Control-Plane-Runtime-Verträge | -| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP-Server und Tool-Bridges, Helfer für Prozessüberwachung und Verträge für ausgehende Zustellung | -| `/codeql-critical-quality/memory-runtime-boundary` | Memory-Host-SDK, Memory-Runtime-Fassaden, Memory-Plugin-SDK-Aliasse, Glue für Memory-Runtime-Aktivierung und Memory-Doctor-Befehle | -| `/codeql-critical-quality/session-diagnostics-boundary` | Reply-Queue-Interna, Session-Delivery-Queues, Helfer für ausgehende Session-Bindung/-Zustellung, Diagnoseereignis-/Log-Bundle-Bereiche und Session-Doctor-CLI-Verträge | -| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Plugin-SDK-Dispatch für eingehende Replies, Reply-Payload-/Chunking-/Runtime-Helfer, Channel-Reply-Optionen, Delivery-Queues und Helfer für Session-/Thread-Bindung | -| `/codeql-critical-quality/provider-runtime-boundary` | Modellkatalog-Normalisierung, Provider-Auth und Discovery, Provider-Runtime-Registrierung, Provider-Defaults/-Kataloge und Web-/Search-/Fetch-/Embedding-Registries | -| `/codeql-critical-quality/ui-control-plane` | Control-UI-Bootstrap, lokale Persistenz, Gateway-Control-Flows und Runtime-Verträge der Task-Control-Plane | -| `/codeql-critical-quality/web-media-runtime-boundary` | Kern-Web-Fetch/Search, Media-IO, Media-Understanding, Image-Generation und Media-Generation-Runtime-Verträge | -| `/codeql-critical-quality/plugin-boundary` | Loader-, Registry-, Public-Surface- und Plugin-SDK-Entrypoint-Verträge | -| `/codeql-critical-quality/plugin-sdk-package-contract` | Veröffentlichter paketbezogener Plugin-SDK-Quellcode und Helfer für Plugin-Paketverträge | +| Kategorie | Fläche | +| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `/codeql-critical-quality/core-auth-secrets` | Authentifizierung, Secrets, Sandbox, Cron und Code für die Gateway-Sicherheitsgrenze | +| `/codeql-critical-quality/config-boundary` | Konfigurationsschema, Migration, Normalisierung und IO-Verträge | +| `/codeql-critical-quality/gateway-runtime-boundary` | Gateway-Protokollschemata und Server-Methoden-Verträge | +| `/codeql-critical-quality/channel-runtime-boundary` | Implementierungsverträge für zentrale Channels und gebündelte Channel-Plugins | +| `/codeql-critical-quality/agent-runtime-boundary` | Befehlsausführung, Modell-/Provider-Dispatch, Auto-Reply-Dispatch und Warteschlangen sowie ACP-Control-Plane-Runtime-Verträge | +| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP-Server und Tool-Bridges, Hilfsfunktionen für Prozessüberwachung und Verträge für ausgehende Zustellung | +| `/codeql-critical-quality/memory-runtime-boundary` | Memory-Host-SDK, Memory-Runtime-Fassaden, Memory-Plugin-SDK-Aliasse, Verbindungscode für Memory-Runtime-Aktivierung und Memory-Doctor-Befehle | +| `/codeql-critical-quality/session-diagnostics-boundary` | Interna der Reply-Warteschlange, Session-Zustellungswarteschlangen, Hilfsfunktionen für ausgehende Session-Bindung/-Zustellung, Diagnose-Event-/Log-Bundle-Flächen und Session-Doctor-CLI-Verträge | +| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Plugin-SDK-Dispatch für eingehende Replies, Reply-Payload-/Chunking-/Runtime-Hilfsfunktionen, Channel-Reply-Optionen, Zustellungswarteschlangen und Hilfsfunktionen für Session-/Thread-Bindung | +| `/codeql-critical-quality/provider-runtime-boundary` | Modellkatalog-Normalisierung, Provider-Authentifizierung und -Discovery, Provider-Runtime-Registrierung, Provider-Standardeinstellungen/-Kataloge sowie Web-/Search-/Fetch-/Embedding-Registries | +| `/codeql-critical-quality/ui-control-plane` | Bootstrap der Control UI, lokale Persistenz, Gateway-Control-Flows und Task-Control-Plane-Runtime-Verträge | +| `/codeql-critical-quality/web-media-runtime-boundary` | Zentrale Web-Fetch-/Search-Flächen, Medien-IO, Medienverständnis, Bildgenerierung und Runtime-Verträge für Mediengenerierung | +| `/codeql-critical-quality/plugin-boundary` | Loader-, Registry-, Public-Surface- und Plugin-SDK-Entrypoint-Verträge | +| `/codeql-critical-quality/plugin-sdk-package-contract` | Veröffentlichtes Package-seitiges Plugin-SDK-Source und Hilfsfunktionen für Plugin-Package-Verträge | -Quality bleibt von Security getrennt, damit Quality-Ergebnisse geplant, gemessen, deaktiviert oder erweitert werden können, ohne das Security-Signal zu verdecken. Swift-, Python- und gebündelte-Plugin-CodeQL-Erweiterungen sollten erst wieder als eng begrenzte oder geshardete Folgearbeit hinzugefügt werden, nachdem die engen Profile stabile Runtime und stabile Signale haben. +Qualität bleibt von Sicherheit getrennt, damit Qualitätsbefunde geplant, gemessen, deaktiviert oder erweitert werden können, ohne das Sicherheitssignal zu verdecken. Swift-, Python- und gebündelte-Plugin-CodeQL-Erweiterungen sollten erst wieder als eng begrenzte oder geshardete Folgearbeit hinzugefügt werden, nachdem die engen Profile stabile Laufzeit und stabiles Signal haben. -## Wartungsworkflows +## Wartungs-Workflows ### Docs Agent -Der `Docs Agent`-Workflow ist eine ereignisgesteuerte Codex-Wartungslane, um bestehende Dokumentation mit kürzlich gelandeten Änderungen synchron zu halten. Er hat keinen reinen Zeitplan: Ein erfolgreicher Nicht-Bot-Push-CI-Lauf auf `main` kann ihn auslösen, und manueller Dispatch kann ihn direkt ausführen. Workflow-Run-Aufrufe werden übersprungen, wenn `main` weitergezogen ist oder wenn in der letzten Stunde ein anderer nicht übersprungener Docs-Agent-Lauf erstellt wurde. Wenn er läuft, prüft er den Commit-Bereich von der vorherigen nicht übersprungenen Docs-Agent-Source-SHA bis zum aktuellen `main`, sodass ein stündlicher Lauf alle seit dem letzten Docs-Durchlauf angesammelten Main-Änderungen abdecken kann. +Der `Docs Agent`-Workflow ist eine ereignisgesteuerte Codex-Wartungsspur, um bestehende Dokumentation mit kürzlich gelandeten Änderungen abzugleichen. Er hat keinen reinen Zeitplan: Ein erfolgreicher, nicht von einem Bot stammender Push-CI-Lauf auf `main` kann ihn auslösen, und manuelle Ausführung kann ihn direkt starten. Workflow-Run-Aufrufe werden übersprungen, wenn `main` weitergelaufen ist oder wenn in der letzten Stunde ein anderer, nicht übersprungener Docs-Agent-Lauf erstellt wurde. Wenn er läuft, prüft er den Commit-Bereich von der vorherigen nicht übersprungenen Docs-Agent-Source-SHA bis zum aktuellen `main`, sodass ein stündlicher Lauf alle Main-Änderungen abdecken kann, die seit dem letzten Dokumentationsdurchlauf aufgelaufen sind. ### Test Performance Agent -Der `Test Performance Agent`-Workflow ist eine ereignisgesteuerte Codex-Wartungslane für langsame Tests. Er hat keinen reinen Zeitplan: Ein erfolgreicher Nicht-Bot-Push-CI-Lauf auf `main` kann ihn auslösen, aber er wird übersprungen, wenn an diesem UTC-Tag bereits ein anderer Workflow-Run-Aufruf gelaufen ist oder läuft. Manueller Dispatch umgeht dieses tägliche Aktivitätsgate. Die Lane erstellt einen gruppierten Vitest-Performance-Bericht für die vollständige Suite, lässt Codex nur kleine, coverage-erhaltende Test-Performance-Fixes statt breiter Refactorings vornehmen, führt dann den Bericht für die vollständige Suite erneut aus und lehnt Änderungen ab, die die bestandene Baseline-Testanzahl reduzieren. Wenn die Baseline fehlschlagende Tests enthält, darf Codex nur offensichtliche Fehler beheben, und der Nach-Agent-Bericht für die vollständige Suite muss bestehen, bevor etwas committet wird. Wenn `main` weiterläuft, bevor der Bot-Push landet, rebased die Lane den validierten Patch, führt `pnpm check:changed` erneut aus und versucht den Push erneut; widersprüchliche veraltete Patches werden übersprungen. Sie verwendet GitHub-gehostetes Ubuntu, damit die Codex-Action dieselbe Drop-Sudo-Sicherheitsposition wie der Docs Agent beibehalten kann. +Der `Test Performance Agent`-Workflow ist eine ereignisgesteuerte Codex-Wartungsspur für langsame Tests. Er hat keinen reinen Zeitplan: Ein erfolgreicher, nicht von einem Bot stammender Push-CI-Lauf auf `main` kann ihn auslösen, aber er überspringt, wenn an diesem UTC-Tag bereits ein anderer Workflow-Run-Aufruf gelaufen ist oder läuft. Manuelle Ausführung umgeht dieses tägliche Aktivitäts-Gate. Die Spur erstellt einen gruppierten Vitest-Performance-Bericht für die vollständige Suite, lässt Codex nur kleine, Coverage-erhaltende Test-Performance-Korrekturen statt breiter Refactorings vornehmen, führt danach den Full-Suite-Bericht erneut aus und verwirft Änderungen, die die Anzahl der bestehenden bestandenen Baseline-Tests reduzieren. Wenn die Baseline fehlschlagende Tests hat, darf Codex nur offensichtliche Fehler beheben, und der Full-Suite-Bericht nach dem Agent muss bestanden sein, bevor etwas committed wird. Wenn `main` weiterläuft, bevor der Bot-Push landet, rebaset die Spur den validierten Patch, führt `pnpm check:changed` erneut aus und versucht den Push erneut; konfligierende veraltete Patches werden übersprungen. Sie verwendet GitHub-gehostetes Ubuntu, damit die Codex-Action dieselbe Drop-Sudo-Sicherheitshaltung wie der Docs Agent beibehalten kann. -### Duplicate PRs After Merge +### Doppelte PRs nach Merge -Der `Duplicate PRs After Merge`-Workflow ist ein manueller Maintainer-Workflow für Duplicate-Cleanup nach dem Landen. Er ist standardmäßig ein Dry-Run und schließt nur explizit aufgelistete PRs, wenn `apply=true` gesetzt ist. Vor GitHub-Mutationen prüft er, dass der gelandete PR gemergt ist und dass jedes Duplikat entweder ein gemeinsam referenziertes Issue oder überlappende geänderte Hunks hat. +Der `Duplicate PRs After Merge`-Workflow ist ein manueller Maintainer-Workflow für die Bereinigung von Duplikaten nach dem Landen. Er verwendet standardmäßig einen Dry Run und schließt nur ausdrücklich aufgeführte PRs, wenn `apply=true` ist. Bevor GitHub geändert wird, prüft er, dass der gelandete PR gemerged ist und dass jedes Duplikat entweder ein gemeinsam referenziertes Issue oder überlappende geänderte Hunks hat. ```bash gh workflow run duplicate-after-merge.yml \ @@ -475,29 +475,29 @@ gh workflow run duplicate-after-merge.yml \ -f apply=true ``` -## Lokale Check-Gates und Changed-Routing +## Lokale Check-Gates und Routing für Änderungen -Die lokale Changed-Lane-Logik lebt in `scripts/changed-lanes.mjs` und wird von `scripts/check-changed.mjs` ausgeführt. Dieses lokale Check-Gate ist bei Architekturgrenzen strenger als der breite CI-Plattformumfang: +Die lokale Changed-Lane-Logik liegt in `scripts/changed-lanes.mjs` und wird von `scripts/check-changed.mjs` ausgeführt. Dieses lokale Check-Gate ist bei Architekturgrenzen strenger als der breite CI-Plattformumfang: -- Änderungen an Core-Produktionscode führen Core-Prod- und Core-Test-Typecheck plus Core-Lint/Guards aus; -- Änderungen nur an Core-Tests führen nur Core-Test-Typecheck plus Core-Lint aus; -- Änderungen an Extension-Produktionscode führen Extension-Prod- und Extension-Test-Typecheck plus Extension-Lint aus; -- Änderungen nur an Extension-Tests führen Extension-Test-Typecheck plus Extension-Lint aus; -- Änderungen am öffentlichen Plugin SDK oder Plugin-Vertrag erweitern auf Extension-Typecheck, weil Extensions von diesen Core-Verträgen abhängen (Vitest-Extension-Sweeps bleiben explizite Testarbeit); -- Release-Metadaten-only-Versionsbumps führen gezielte Versions-/Konfigurations-/Root-Dependency-Checks aus; -- unbekannte Root-/Konfigurationsänderungen fallen sicher auf alle Check-Lanes zurück. +- Änderungen an zentralem Produktionscode führen Core-Prod- und Core-Test-Typecheck plus Core-Lint/-Guards aus; +- reine Änderungen an zentralen Tests führen nur Core-Test-Typecheck plus Core-Lint aus; +- Änderungen an Plugin-Produktionscode führen Plugin-Prod- und Plugin-Test-Typecheck plus Plugin-Lint aus; +- reine Änderungen an Plugin-Tests führen Plugin-Test-Typecheck plus Plugin-Lint aus; +- Änderungen am öffentlichen Plugin SDK oder an Plugin-Verträgen erweitern auf Plugin-Typecheck, weil Plugins von diesen zentralen Verträgen abhängen (Vitest-Plugin-Sweeps bleiben explizite Testarbeit); +- reine Versionsbump-Änderungen an Release-Metadaten führen gezielte Versions-/Konfigurations-/Root-Abhängigkeitschecks aus; +- unbekannte Root-/Konfigurationsänderungen schlagen sicher auf alle Check-Lanes aus. -Lokales Changed-Test-Routing lebt in `scripts/test-projects.test-support.mjs` und ist absichtlich günstiger als `check:changed`: Direkte Teständerungen führen sich selbst aus, Source-Änderungen bevorzugen explizite Zuordnungen, danach Sibling-Tests und Import-Graph-Abhängige. Die gemeinsame Group-Room-Delivery-Konfiguration ist eine der expliziten Zuordnungen: Änderungen an der sichtbaren Reply-Konfiguration der Gruppe, am Source-Reply-Delivery-Modus oder am System-Prompt des Message-Tools laufen durch die Core-Reply-Tests plus Discord- und Slack-Delivery-Regressionen, damit eine gemeinsame Default-Änderung vor dem ersten PR-Push fehlschlägt. Verwenden Sie `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` nur, wenn die Änderung harness-weit genug ist, dass die günstige zugeordnete Menge kein vertrauenswürdiger Proxy ist. +Lokales Changed-Test-Routing liegt in `scripts/test-projects.test-support.mjs` und ist bewusst günstiger als `check:changed`: Direkte Teständerungen führen sich selbst aus, Source-Änderungen bevorzugen explizite Mappings, danach Geschwistertests und Import-Graph-Abhängige. Shared-Group-Room-Zustellungskonfiguration ist eines der expliziten Mappings: Änderungen an der für Gruppen sichtbaren Reply-Konfiguration, am Source-Reply-Zustellungsmodus oder am System-Prompt des Message-Tools laufen über die zentralen Reply-Tests plus Discord- und Slack-Zustellungsregressionen, damit eine gemeinsame Standardänderung vor dem ersten PR-Push fehlschlägt. Verwenden Sie `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` nur, wenn die Änderung so weitreichend für das Test-Harness ist, dass das günstige gemappte Set kein vertrauenswürdiger Proxy ist. ## Testbox-Validierung -Führen Sie Testbox aus dem Repository-Root aus und bevorzugen Sie für umfassende Nachweise eine frisch vorgewärmte Box. Bevor Sie einen langsamen Gate-Lauf auf eine Box verwenden, die wiederverwendet wurde, abgelaufen ist oder gerade eine unerwartet große Synchronisierung gemeldet hat, führen Sie zuerst `pnpm testbox:sanity` innerhalb der Box aus. +Führen Sie Testbox vom Repo-Root aus und bevorzugen Sie für breite Validierung eine frisch vorgewärmte Box. Bevor Sie eine langsame Gate-Prüfung auf einer Box ausführen, die wiederverwendet wurde, abgelaufen ist oder gerade eine unerwartet große Synchronisierung gemeldet hat, führen Sie zuerst `pnpm testbox:sanity` innerhalb der Box aus. -Der Sanity-Check schlägt schnell fehl, wenn erforderliche Root-Dateien wie `pnpm-lock.yaml` verschwunden sind oder wenn `git status --short` mindestens 200 nachverfolgte Löschungen anzeigt. Das bedeutet in der Regel, dass der Remote-Synchronisierungszustand keine vertrauenswürdige Kopie des PR ist; stoppen Sie diese Box und wärmen Sie stattdessen eine frische vor, anstatt den Produkttestfehler zu debuggen. Legen Sie für beabsichtigte PRs mit vielen Löschungen für diesen Sanity-Lauf `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` fest. +Die Sanity-Prüfung schlägt schnell fehl, wenn erforderliche Root-Dateien wie `pnpm-lock.yaml` verschwunden sind oder wenn `git status --short` mindestens 200 nachverfolgte Löschungen anzeigt. Das bedeutet in der Regel, dass der Remote-Synchronisierungszustand keine vertrauenswürdige Kopie des PR ist; stoppen Sie diese Box und wärmen Sie stattdessen eine frische vor, anstatt den Produkttestfehler zu debuggen. Für absichtliche PRs mit vielen Löschungen setzen Sie für diesen Sanity-Lauf `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1`. -`pnpm testbox:run` beendet außerdem einen lokalen Blacksmith-CLI-Aufruf, der länger als fünf Minuten in der Synchronisierungsphase bleibt, ohne Ausgabe nach der Synchronisierung zu erzeugen. Legen Sie `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` fest, um diesen Schutz zu deaktivieren, oder verwenden Sie für ungewöhnlich große lokale Diffs einen größeren Millisekundenwert. +`pnpm testbox:run` beendet außerdem eine lokale Blacksmith-CLI-Ausführung, die länger als fünf Minuten in der Synchronisierungsphase bleibt, ohne Ausgabe nach der Synchronisierung zu liefern. Setzen Sie `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, um diese Schutzvorkehrung zu deaktivieren, oder verwenden Sie einen größeren Millisekundenwert für ungewöhnlich große lokale Diffs. -Crabbox ist der repositoryeigene zweite Remote-Box-Pfad für Linux-Nachweise, wenn Blacksmith nicht verfügbar ist oder wenn eigene Cloud-Kapazität vorzuziehen ist. Wärmen Sie eine Box vor, hydratisieren Sie sie über den Projekt-Workflow, und führen Sie dann Befehle über die Crabbox-CLI aus: +Crabbox ist der repo-eigene zweite Remote-Box-Pfad für Linux-Nachweise, wenn Blacksmith nicht verfügbar ist oder wenn eigene Cloud-Kapazität vorzuziehen ist. Wärmen Sie eine Box vor, hydratisieren Sie sie über den Projekt-Workflow und führen Sie dann Befehle über die Crabbox-CLI aus: ```bash pnpm crabbox:warmup -- --idle-timeout 90m @@ -506,9 +506,9 @@ pnpm crabbox:run -- --id --shell "OPENCLAW_TESTBOX=1 pnpm check:changed pnpm crabbox:stop -- ``` -`.crabbox.yaml` verwaltet Provider-, Synchronisierungs- und GitHub-Actions-Hydrationsdefaults. Es schließt lokales `.git` aus, damit der hydratisierte Actions-Checkout seine eigenen Remote-Git-Metadaten behält, anstatt maintainerlokale Remotes und Objektspeicher zu synchronisieren, und es schließt lokale Runtime-/Build-Artefakte aus, die niemals übertragen werden sollten. `.github/workflows/crabbox-hydrate.yml` verwaltet Checkout, Node-/pnpm-Einrichtung, `origin/main`-Fetch und die nicht geheime Umgebungsübergabe, die spätere `crabbox run --id `-Befehle beziehen. +`.crabbox.yaml` verwaltet die Standardwerte für Provider, Synchronisierung und GitHub Actions-Hydration. Sie schließt die lokale `.git` aus, damit der hydratisierte Actions-Checkout seine eigenen Remote-Git-Metadaten behält, statt maintainer-lokale Remotes und Objektspeicher zu synchronisieren, und sie schließt lokale Laufzeit-/Build-Artefakte aus, die niemals übertragen werden sollten. `.github/workflows/crabbox-hydrate.yml` verwaltet Checkout, Node-/pnpm-Einrichtung, `origin/main`-Abruf und die nicht geheime Umgebungsübergabe, die spätere `crabbox run --id `-Befehle sourcen. -## Verwandt +## Verwandte Themen - [Installationsübersicht](/de/install) - [Entwicklungskanäle](/de/install/development-channels) diff --git a/docs/de/concepts/system-prompt.md b/docs/de/concepts/system-prompt.md index 62c52661b..152514851 100644 --- a/docs/de/concepts/system-prompt.md +++ b/docs/de/concepts/system-prompt.md @@ -1,152 +1,155 @@ --- read_when: - - System-Prompt-Text, Tool-Liste oder Zeit-/Heartbeat-Abschnitte bearbeiten + - System-Prompt-Text, Tools-Liste oder Zeit-/Heartbeat-Abschnitte bearbeiten - Ändern des Workspace-Bootstraps oder des Verhaltens der Skills-Injektion -summary: Was der OpenClaw-System-Prompt enthält und wie er zusammengesetzt wird -title: System-Prompt +summary: Was der OpenClaw-Systemprompt enthält und wie er zusammengesetzt wird +title: Systemanweisung x-i18n: - generated_at: "2026-05-02T22:17:58Z" + generated_at: "2026-05-02T23:39:18Z" model: gpt-5.5 provider: openai - source_hash: 3b8761a8722bb328b937e0832774be7b4e99602ae032c9a255f26843237c110c + source_hash: f8e0234453812c16cf5d273096d335049bf435ca76ade36200caf4bb344624e5 source_path: concepts/system-prompt.md workflow: 16 --- -OpenClaw erstellt für jede Agent-Ausführung einen benutzerdefinierten System-Prompt. Der Prompt ist **OpenClaw-eigen** und verwendet nicht den Standard-Prompt von pi-coding-agent. +OpenClaw erstellt für jeden Agent-Lauf einen benutzerdefinierten System-Prompt. Der Prompt ist **OpenClaw-owned** und verwendet nicht den Standard-Prompt von pi-coding-agent. -Der Prompt wird von OpenClaw zusammengesetzt und in jede Agent-Ausführung injiziert. +Der Prompt wird von OpenClaw zusammengesetzt und in jeden Agent-Lauf injiziert. -Provider-Plugins können cache-bewusste Prompt-Hinweise beitragen, ohne den -vollständigen OpenClaw-eigenen Prompt zu ersetzen. Die Provider-Laufzeitumgebung kann: +Provider-Plugins können cache-bewusste Prompt-Anweisungen beitragen, ohne den +vollständigen OpenClaw-owned Prompt zu ersetzen. Die Provider-Runtime kann: -- einen kleinen Satz benannter Kernabschnitte ersetzen (`interaction_style`, +- eine kleine Gruppe benannter Kernabschnitte ersetzen (`interaction_style`, `tool_call_style`, `execution_bias`) - ein **stabiles Präfix** oberhalb der Prompt-Cache-Grenze injizieren - ein **dynamisches Suffix** unterhalb der Prompt-Cache-Grenze injizieren -Verwenden Sie Provider-eigene Beiträge für modellfamilien-spezifische Feinabstimmung. Behalten Sie die ältere -`before_prompt_build`-Prompt-Mutation für Kompatibilität oder wirklich globale Prompt-Änderungen bei, -nicht für normales Provider-Verhalten. +Verwenden Sie Provider-eigene Beiträge für modellfamilien-spezifisches Tuning. Behalten Sie die alte +`before_prompt_build`-Prompt-Mutation für Kompatibilität oder wirklich globale Prompt- +Änderungen bei, nicht für normales Provider-Verhalten. -Das Overlay für die OpenAI GPT-5-Familie hält die Kernausführungsregel klein und ergänzt -modellspezifische Hinweise für Persona-Verankerung, knappe Ausgabe, Tool-Disziplin, -parallele Nachschlagevorgänge, Abdeckung von Liefergegenständen, Verifikation, fehlenden Kontext und -Hygiene bei Terminal-Tools. +Das OpenAI-GPT-5-Familien-Overlay hält die zentrale Ausführungsregel klein und fügt +modellspezifische Hinweise für Persona-Latching, knappe Ausgabe, Werkzeugdisziplin, +paralleles Nachschlagen, Abdeckung von Arbeitsergebnissen, Verifikation, fehlenden Kontext und +Terminal-Tool-Hygiene hinzu. ## Struktur Der Prompt ist absichtlich kompakt und verwendet feste Abschnitte: -- **Tooling**: Erinnerung an strukturierte Tools als Quelle der Wahrheit plus Laufzeit-Hinweise zur Tool-Nutzung. -- **Ausführungsfokus**: kompakte Hinweise zum konsequenten Abarbeiten: bei - handlungsfähigen Anfragen innerhalb derselben Runde handeln, fortfahren bis abgeschlossen oder blockiert, - sich von schwachen Tool-Ergebnissen erholen, veränderlichen Zustand live prüfen und vor der Finalisierung verifizieren. +- **Werkzeuge**: Erinnerung an die strukturierte Tool-Quelle der Wahrheit sowie Runtime-Hinweise zur Tool-Nutzung. +- **Ausführungsbias**: kompakte Follow-through-Hinweise: bei + umsetzbaren Anfragen im aktuellen Turn handeln, fortfahren, bis die Aufgabe erledigt oder blockiert ist, schwache Tool- + Ergebnisse ausgleichen, veränderlichen Zustand live prüfen und vor dem Abschließen verifizieren. - **Sicherheit**: kurze Guardrail-Erinnerung, machtstrebendes Verhalten oder das Umgehen von Aufsicht zu vermeiden. -- **Skills** (wenn verfügbar): erklärt dem Modell, wie es Skill-Anweisungen bei Bedarf laden soll. +- **Skills** (wenn verfügbar): erklärt dem Modell, wie Skill-Anweisungen bei Bedarf geladen werden. - **OpenClaw-Selbstaktualisierung**: wie Konfiguration sicher mit - `config.schema.lookup` geprüft, Konfiguration mit `config.patch` gepatcht, die vollständige - Konfiguration mit `config.apply` ersetzt und `update.run` nur auf ausdrückliche Benutzeranforderung - ausgeführt wird. Das nur für Eigentümer vorgesehene `gateway`-Tool verweigert außerdem das Umschreiben von - `tools.exec.ask` / `tools.exec.security`, einschließlich älterer `tools.bash.*`- - Aliasse, die auf diese geschützten exec-Pfade normalisieren. + `config.schema.lookup` geprüft, mit `config.patch` gepatcht, die vollständige + Konfiguration mit `config.apply` ersetzt und `update.run` nur auf explizite Benutzeranfrage + ausgeführt wird. Das owner-only `gateway`-Tool verweigert außerdem das Umschreiben von + `tools.exec.ask` / `tools.exec.security`, einschließlich alter `tools.bash.*`- + Aliasse, die auf diese geschützten Exec-Pfade normalisiert werden. - **Arbeitsbereich**: Arbeitsverzeichnis (`agents.defaults.workspace`). -- **Dokumentation**: lokaler Pfad zu OpenClaw-Dokumentation (Repo oder npm-Paket) und wann sie zu lesen ist. -- **Arbeitsbereichsdateien (injiziert)**: weist darauf hin, dass Bootstrap-Dateien unten enthalten sind. -- **Sandbox** (wenn aktiviert): weist auf Sandbox-Laufzeitumgebung, Sandbox-Pfade und die Verfügbarkeit erhöhter exec-Rechte hin. -- **Aktuelles Datum und Uhrzeit**: benutzerlokale Zeit, Zeitzone und Zeitformat. +- **Dokumentation**: lokaler Pfad zur OpenClaw-Dokumentation (Repo oder npm-Paket) und wann sie gelesen werden soll. +- **Arbeitsbereichsdateien (injiziert)**: zeigt an, dass Bootstrap-Dateien unten enthalten sind. +- **Sandbox** (wenn aktiviert): zeigt sandboxed Runtime, Sandbox-Pfade und ob erhöhte Exec-Rechte verfügbar sind. +- **Aktuelles Datum & Uhrzeit**: benutzerlokale Zeit, Zeitzone und Zeitformat. - **Antwort-Tags**: optionale Antwort-Tag-Syntax für unterstützte Provider. - **Heartbeats**: Heartbeat-Prompt und Bestätigungsverhalten, wenn Heartbeats für den Standard-Agent aktiviert sind. -- **Laufzeitumgebung**: Host, Betriebssystem, Node, Modell, Repo-Wurzel (wenn erkannt), Denkstufe (eine Zeile). +- **Runtime**: Host, Betriebssystem, Node, Modell, Repo-Root (wenn erkannt), Denkstufe (eine Zeile). - **Reasoning**: aktuelle Sichtbarkeitsstufe + Hinweis zum /reasoning-Umschalter. OpenClaw hält große stabile Inhalte, einschließlich **Projektkontext**, oberhalb der -internen Prompt-Cache-Grenze. Veränderliche Kanal-/Sitzungsabschnitte wie +internen Prompt-Cache-Grenze. Veränderliche Channel-/Session-Abschnitte wie Control-UI-Einbettungshinweise, **Messaging**, **Voice**, **Gruppenchat-Kontext**, -**Reaktionen**, **Heartbeats** und **Laufzeitumgebung** werden unterhalb dieser Grenze angehängt, +**Reactions**, **Heartbeats** und **Runtime** werden unterhalb dieser Grenze angehängt, damit lokale Backends mit Präfix-Caches das stabile Arbeitsbereichspräfix -über Kanalrunden hinweg wiederverwenden können. Tool-Beschreibungen sollten ebenfalls vermeiden, -aktuelle Kanalnamen einzubetten, wenn das akzeptierte Schema dieses Laufzeitdetail bereits enthält. +über Channel-Turns hinweg wiederverwenden können. Tool-Beschreibungen sollten ebenfalls vermeiden, aktuelle +Channel-Namen einzubetten, wenn das akzeptierte Schema dieses Runtime-Detail bereits enthält. -Der Tooling-Abschnitt enthält außerdem Laufzeit-Hinweise für lang laufende Arbeit: +Der Abschnitt Werkzeuge enthält außerdem Runtime-Hinweise für lang laufende Arbeit: -- Cron für zukünftige Nachverfolgung verwenden (`check back later`, Erinnerungen, wiederkehrende Arbeit) +- Verwenden Sie Cron für künftige Nachverfolgung (`check back later`, Erinnerungen, wiederkehrende Arbeit) statt `exec`-Sleep-Schleifen, `yieldMs`-Verzögerungstricks oder wiederholtem `process`- Polling -- `exec` / `process` nur für Befehle verwenden, die jetzt starten und im Hintergrund weiterlaufen -- wenn automatisches Aufwecken bei Abschluss aktiviert ist, den Befehl einmal starten und sich auf - den push-basierten Aufweckpfad verlassen, wenn er Ausgabe erzeugt oder fehlschlägt -- `process` für Protokolle, Status, Eingabe oder Eingriff verwenden, wenn Sie einen laufenden Befehl prüfen müssen -- wenn die Aufgabe größer ist, `sessions_spawn` bevorzugen; der Abschluss von Sub-Agents ist - push-basiert und kündigt sich automatisch beim Anforderer zurück -- `subagents list` / `sessions_list` nicht in einer Schleife abfragen, nur um auf den Abschluss zu warten +- verwenden Sie `exec` / `process` nur für Befehle, die jetzt starten und + im Hintergrund weiterlaufen +- wenn automatisches Aufwachen bei Abschluss aktiviert ist, starten Sie den Befehl einmal und verlassen Sie sich auf + den push-basierten Wake-Pfad, wenn er Ausgabe erzeugt oder fehlschlägt +- verwenden Sie `process` für Logs, Status, Eingaben oder Eingriffe, wenn Sie + einen laufenden Befehl prüfen müssen +- wenn die Aufgabe größer ist, bevorzugen Sie `sessions_spawn`; der Abschluss von Sub-Agents ist + push-basiert und meldet sich automatisch beim Anfragenden zurück +- pollen Sie `subagents list` / `sessions_list` nicht in einer Schleife, nur um auf + den Abschluss zu warten -Wenn das experimentelle Tool `update_plan` aktiviert ist, weist Tooling das -Modell außerdem an, es nur für nicht triviale mehrstufige Arbeit zu verwenden, genau einen -`in_progress`-Schritt beizubehalten und zu vermeiden, nach jeder Aktualisierung den gesamten Plan zu wiederholen. +Wenn das experimentelle `update_plan`-Tool aktiviert ist, weist Werkzeuge das +Modell außerdem an, es nur für nicht triviale mehrschrittige Arbeit zu verwenden, genau einen +`in_progress`-Schritt beizubehalten und den gesamten Plan nicht nach jeder Aktualisierung zu wiederholen. -Sicherheits-Guardrails im System-Prompt sind beratend. Sie leiten Modellverhalten an, erzwingen aber keine Richtlinie. Verwenden Sie Tool-Richtlinien, exec-Genehmigungen, Sandboxing und Kanal-Allowlists für harte Durchsetzung; Operatoren können diese absichtlich deaktivieren. +Sicherheits-Guardrails im System-Prompt sind beratend. Sie leiten das Modellverhalten, erzwingen aber keine Richtlinie. Verwenden Sie Tool-Richtlinien, Exec-Genehmigungen, Sandboxing und Channel-Allowlists für harte Durchsetzung; Betreiber können diese absichtlich deaktivieren. -Auf Kanälen mit nativen Genehmigungskarten/-Buttons weist der Laufzeit-Prompt den +Auf Channels mit nativen Genehmigungskarten/-Buttons weist der Runtime-Prompt den Agent jetzt an, zuerst diese native Genehmigungs-UI zu verwenden. Er sollte nur dann einen manuellen -`/approve`-Befehl einschließen, wenn das Tool-Ergebnis angibt, dass Chat-Genehmigungen nicht verfügbar sind oder +`/approve`-Befehl einschließen, wenn das Tool-Ergebnis sagt, dass Chat-Genehmigungen nicht verfügbar sind oder manuelle Genehmigung der einzige Weg ist. ## Prompt-Modi -OpenClaw kann kleinere System-Prompts für Sub-Agents rendern. Die Laufzeitumgebung setzt für jede Ausführung einen -`promptMode` (keine benutzerseitige Konfiguration): +OpenClaw kann kleinere System-Prompts für Sub-Agents rendern. Die Runtime setzt für +jeden Lauf einen `promptMode` (keine benutzerseitige Konfiguration): - `full` (Standard): enthält alle oben genannten Abschnitte. -- `minimal`: wird für Sub-Agents verwendet; lässt **Skills**, **Memory Recall**, **OpenClaw- - Selbstaktualisierung**, **Modellaliase**, **Benutzeridentität**, **Antwort-Tags**, - **Messaging**, **Stille Antworten** und **Heartbeats** aus. Tooling, **Sicherheit**, - Arbeitsbereich, Sandbox, Aktuelles Datum und Uhrzeit (wenn bekannt), Laufzeitumgebung und injizierter +- `minimal`: wird für Sub-Agents verwendet; lässt **Skills**, **Memory Recall**, **OpenClaw + Self-Update**, **Model Aliases**, **User Identity**, **Reply Tags**, + **Messaging**, **Silent Replies** und **Heartbeats** aus. Werkzeuge, **Sicherheit**, + Arbeitsbereich, Sandbox, Aktuelles Datum & Uhrzeit (wenn bekannt), Runtime und injizierter Kontext bleiben verfügbar. -- `none`: gibt nur die Basisidentitätszeile zurück. +- `none`: gibt nur die Basis-Identitätszeile zurück. -Wenn `promptMode=minimal` ist, werden zusätzlich injizierte Prompts als **Subagent- -Kontext** statt **Gruppenchat-Kontext** gekennzeichnet. +Wenn `promptMode=minimal` gilt, werden zusätzlich injizierte Prompts als **Subagent +Context** statt **Group Chat Context** beschriftet. -Für automatische Kanalantwort-Ausführungen kann OpenClaw den generischen Abschnitt **Stille Antworten** -weglassen, wenn der direkte/Gruppenchat-Kontext bereits das aufgelöste -konversationsspezifische `NO_REPLY`-Verhalten enthält. Dadurch wird vermieden, Token-Mechanik -sowohl im globalen System-Prompt als auch im Kanalkontext zu wiederholen. +Für Channel-Auto-Reply-Läufe kann OpenClaw den generischen Abschnitt **Silent Replies** +weglassen, wenn der Direkt-/Gruppenchat-Kontext bereits das aufgelöste +konversationsspezifische `NO_REPLY`-Verhalten enthält. Dadurch wird vermieden, Token-Mechaniken +sowohl im globalen System-Prompt als auch im Channel-Kontext zu wiederholen. ## Prompt-Snapshots -OpenClaw hält committete Happy-Path-Prompt-Snapshots für die Codex/message-tool- -Laufzeit unter `test/fixtures/agents/prompt-snapshots/happy-path/` vor. Sie rendern -ausgewählte App-Server-Thread-/Rundenparameter plus einen rekonstruierten modellgebundenen Prompt- -Layer-Stack für direkte Telegram-, Discord-Gruppen- und Heartbeat-Runden. Dieser Stack -enthält ein angeheftetes Codex-`gpt-5.5`-Modell-Prompt-Fixture, das aus der -Modellkatalog-/Cache-Form von Codex generiert wurde, den Codex-Happy-Path-Berechtigungs-Developer-Text, -OpenClaw-Developer-Anweisungen, Benutzerrunden-Eingabe und Verweise auf die dynamischen +OpenClaw hält committete Prompt-Snapshots für den Happy Path der Codex-Runtime unter +`test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/`. Sie rendern +ausgewählte App-Server-Thread-/Turn-Parameter plus einen rekonstruierten modellgebundenen Prompt- +Layer-Stack für Telegram-Direkt-, Discord-Gruppen- und Heartbeat-Turns. Dieser Stack +enthält ein gepinntes Codex-`gpt-5.5`-Modell-Prompt-Fixture, das aus Codex’ +Modellkatalog-/Cache-Form erzeugt wurde, den Codex-Happy-Path-Berechtigungs-Developer-Text, +OpenClaw-Developer-Anweisungen, Benutzereingabe im Turn und Referenzen auf die dynamischen Tool-Spezifikationen. -Aktualisieren Sie das angeheftete Codex-Modell-Prompt-Fixture mit -`pnpm prompt:snapshots:sync-codex-model`. Standardmäßig sucht das Skript den -Laufzeit-Cache von Codex unter `$CODEX_HOME/models_cache.json`, dann unter +Aktualisieren Sie das gepinnte Codex-Modell-Prompt-Fixture mit +`pnpm prompt:snapshots:sync-codex-model`. Standardmäßig sucht das Skript nach +Codex’ Runtime-Cache unter `$CODEX_HOME/models_cache.json`, dann unter `~/.codex/models_cache.json` und fällt erst danach auf die Maintainer-Codex- Checkout-Konvention unter `~/code/codex/codex-rs/models-manager/models.json` zurück. Wenn keine dieser Quellen existiert, beendet sich der Befehl, ohne das committete Fixture zu ändern. Übergeben Sie `--catalog `, um aus einer bestimmten `models_cache.json`- oder `models.json`-Datei zu aktualisieren. -Diese Snapshots sind weiterhin keine bytegenaue rohe OpenAI-Anfrageerfassung. Codex -kann laufzeiteigenen Arbeitsbereichskontext wie `AGENTS.md`, Umgebungskontext, -Memories, App-/Plugin-Anweisungen und zukünftige Anweisungen für den Kollaborationsmodus -innerhalb der Codex-Laufzeit hinzufügen, nachdem OpenClaw Thread- und Rundenparameter -gesendet hat. +Diese Snapshots sind weiterhin keine bytegenaue Roh-Erfassung einer OpenAI-Anfrage. Codex +kann Runtime-eigenen Arbeitsbereichskontext wie `AGENTS.md`, Umgebungs- +kontext, Erinnerungen, App-/Plugin-Anweisungen und künftige Collaboration-Mode- +Anweisungen innerhalb der Codex-Runtime hinzufügen, nachdem OpenClaw Thread- und Turn- +Parameter gesendet hat. -Generieren Sie sie mit `pnpm prompt:snapshots:gen` neu und prüfen Sie Drift mit +Regenerieren Sie sie mit `pnpm prompt:snapshots:gen` und prüfen Sie Drift mit `pnpm prompt:snapshots:check`. CI führt die Drift-Prüfung im zusätzlichen Boundary-Shard aus, damit Prompt-Änderungen und Snapshot-Aktualisierungen am selben PR hängen bleiben. ## Arbeitsbereich-Bootstrap-Injektion -Bootstrap-Dateien werden gekürzt und unter **Projektkontext** angehängt, damit das Modell Identitäts- und Profilkontext sieht, ohne explizite Lesevorgänge zu benötigen: +Bootstrap-Dateien werden gekürzt und unter **Projektkontext** angehängt, damit das Modell Identitäts- und Profilkontext sieht, ohne explizite Lesezugriffe zu benötigen: - `AGENTS.md` - `SOUL.md` @@ -154,71 +157,78 @@ Bootstrap-Dateien werden gekürzt und unter **Projektkontext** angehängt, damit - `IDENTITY.md` - `USER.md` - `HEARTBEAT.md` -- `BOOTSTRAP.md` (nur in brandneuen Arbeitsbereichen) +- `BOOTSTRAP.md` (nur bei ganz neuen Arbeitsbereichen) - `MEMORY.md`, wenn vorhanden -Alle diese Dateien werden bei jeder Runde **in das Kontextfenster injiziert**, sofern -kein dateispezifisches Gate greift. `HEARTBEAT.md` wird bei normalen Ausführungen weggelassen, wenn +Alle diese Dateien werden bei jedem Turn **in das Kontextfenster injiziert**, sofern +kein dateispezifisches Gate gilt. `HEARTBEAT.md` wird bei normalen Läufen ausgelassen, wenn Heartbeats für den Standard-Agent deaktiviert sind oder `agents.defaults.heartbeat.includeSystemPromptSection` false ist. Halten Sie injizierte -Dateien knapp, insbesondere `MEMORY.md`, das mit der Zeit wachsen und zu -unerwartet hoher Kontextnutzung und häufigerer Compaction führen kann. +Dateien knapp — besonders `MEMORY.md`, das mit der Zeit wachsen und zu +unerwartet hoher Kontextnutzung sowie häufigerer Compaction führen kann. + +Wenn eine Session auf dem nativen Codex-Harness läuft, lädt Codex `AGENTS.md` +über seine eigene Projekt-Dokumenterkennung. OpenClaw löst weiterhin die übrigen +Bootstrap-Dateien auf und leitet sie als Codex-Konfigurationsanweisungen weiter, sodass `SOUL.md`, +`TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` und +`MEMORY.md` dieselbe Arbeitsbereich-Kontextrolle behalten, ohne +`AGENTS.md` zu duplizieren. -Tägliche `memory/*.md`-Dateien sind **nicht** Teil des normalen Bootstrap-Projektkontexts. In gewöhnlichen Runden wird bei Bedarf über die Tools `memory_search` und `memory_get` auf sie zugegriffen, sodass sie nicht gegen das Kontextfenster zählen, sofern das Modell sie nicht explizit liest. Bloße `/new`- und `/reset`-Runden sind die Ausnahme: Die Laufzeitumgebung kann aktuellen täglichen Memory als einmaligen Startkontextblock für diese erste Runde voranstellen. +Tägliche `memory/*.md`-Dateien sind **nicht** Teil des normalen Bootstrap-Projektkontexts. Bei gewöhnlichen Turns wird bei Bedarf über die Tools `memory_search` und `memory_get` darauf zugegriffen, sodass sie nicht auf das Kontextfenster angerechnet werden, sofern das Modell sie nicht explizit liest. Reine `/new`- und `/reset`-Turns sind die Ausnahme: Die Runtime kann aktuellen täglichen Speicher als einmaligen Startkontextblock für diesen ersten Turn voranstellen. Große Dateien werden mit einer Markierung abgeschnitten. Die maximale Größe pro Datei wird durch `agents.defaults.bootstrapMaxChars` gesteuert (Standard: 12000). Der gesamte injizierte Bootstrap- Inhalt über alle Dateien hinweg ist durch `agents.defaults.bootstrapTotalMaxChars` -begrenzt (Standard: 60000). Fehlende Dateien injizieren eine kurze Markierung für fehlende Dateien. Wenn Kürzung +begrenzt (Standard: 60000). Fehlende Dateien injizieren eine kurze Missing-File-Markierung. Wenn Kürzung auftritt, kann OpenClaw einen Warnblock im Projektkontext injizieren; steuern Sie dies mit `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; Standard: `once`). -Sub-Agent-Sitzungen injizieren nur `AGENTS.md` und `TOOLS.md` (andere Bootstrap-Dateien +Sub-Agent-Sessions injizieren nur `AGENTS.md` und `TOOLS.md` (andere Bootstrap-Dateien werden herausgefiltert, um den Sub-Agent-Kontext klein zu halten). Interne Hooks können diesen Schritt über `agent:bootstrap` abfangen, um die injizierten Bootstrap-Dateien zu verändern oder zu ersetzen (zum Beispiel `SOUL.md` gegen eine alternative Persona auszutauschen). Wenn Sie möchten, dass der Agent weniger generisch klingt, beginnen Sie mit dem -[SOUL.md-Persönlichkeitsleitfaden](/de/concepts/soul). +[SOUL.md Personality Guide](/de/concepts/soul). -Um zu prüfen, wie viel jede injizierte Datei beiträgt (roh gegenüber injiziert, Kürzung plus Tool-Schema-Overhead), verwenden Sie `/context list` oder `/context detail`. Siehe [Kontext](/de/concepts/context). +Um zu prüfen, wie viel jede injizierte Datei beiträgt (roh vs. injiziert, Kürzung plus Tool-Schema-Overhead), verwenden Sie `/context list` oder `/context detail`. Siehe [Kontext](/de/concepts/context). -## Zeitbehandlung +## Zeitverarbeitung -Der System-Prompt enthält einen dedizierten Abschnitt **Aktuelles Datum und Uhrzeit**, wenn die -Zeitzone des Benutzers bekannt ist. Damit der Prompt cache-stabil bleibt, enthält er jetzt nur noch +Der System-Prompt enthält einen eigenen Abschnitt **Aktuelles Datum & Uhrzeit**, wenn die +Benutzerzeitzone bekannt ist. Um den Prompt cache-stabil zu halten, enthält er jetzt nur noch die **Zeitzone** (keine dynamische Uhr oder kein Zeitformat). Verwenden Sie `session_status`, wenn der Agent die aktuelle Uhrzeit benötigt; die Statuskarte -enthält eine Zeitstempelzeile. Dasselbe Tool kann optional eine modellspezifische Überschreibung pro Sitzung -setzen (`model=default` entfernt sie). +enthält eine Zeitstempelzeile. Dasselbe Tool kann optional eine Modellauswahl pro Session +setzen (`model=default` löscht sie). -Konfigurieren Sie dies mit: +Konfiguration mit: - `agents.defaults.userTimezone` - `agents.defaults.timeFormat` (`auto` | `12` | `24`) -Siehe [Datum und Uhrzeit](/de/date-time) für vollständige Verhaltensdetails. +Vollständige Verhaltensdetails finden Sie unter [Datum & Uhrzeit](/de/date-time). ## Skills Wenn geeignete Skills existieren, injiziert OpenClaw eine kompakte **Liste verfügbarer Skills** (`formatSkillsForPrompt`), die den **Dateipfad** für jeden Skill enthält. Der -Prompt weist das Modell an, `read` zu verwenden, um die SKILL.md am aufgeführten +Prompt weist das Modell an, `read` zu verwenden, um die SKILL.md am aufgelisteten Ort zu laden (Arbeitsbereich, verwaltet oder gebündelt). Wenn keine Skills geeignet sind, wird der Skills-Abschnitt ausgelassen. -Die Eignung umfasst Skill-Metadaten-Gates, Laufzeitumgebungs-/Konfigurationsprüfungen +Die Eignung umfasst Skill-Metadaten-Gates, Runtime-Umgebungs-/Konfigurationsprüfungen und die effektive Skill-Allowlist des Agent, wenn `agents.defaults.skills` oder `agents.list[].skills` konfiguriert ist. Plugin-gebündelte Skills sind nur geeignet, wenn ihr besitzendes Plugin aktiviert ist. -Dadurch können Tool-Plugins tiefere Betriebsleitfäden bereitstellen, ohne die gesamte -Anleitung direkt in jede Tool-Beschreibung einzubetten. +Dadurch können Tool-Plugins tiefere Betriebsanleitungen bereitstellen, ohne alle +diese Hinweise direkt in jede Tool-Beschreibung einzubetten. ``` @@ -230,29 +240,28 @@ Anleitung direkt in jede Tool-Beschreibung einzubetten. ``` -Dies hält den Basis-Prompt klein und ermöglicht dennoch gezielte Skill-Nutzung. +Das hält den Basis-Prompt klein und ermöglicht dennoch gezielte Skill-Nutzung. -Das Budget für die Skills-Liste gehört dem Skills-Subsystem: +Das Budget der Skills-Liste gehört dem Skills-Subsystem: - Globaler Standard: `skills.limits.maxSkillsPromptChars` -- Überschreibung pro Agent: `agents.list[].skillsLimits.maxSkillsPromptChars` +- Agent-spezifische Überschreibung: `agents.list[].skillsLimits.maxSkillsPromptChars` -Generische begrenzte Laufzeitauszüge verwenden eine andere Oberfläche: +Generische begrenzte Runtime-Auszüge verwenden eine andere Oberfläche: - `agents.defaults.contextLimits.*` - `agents.list[].contextLimits.*` -Diese Trennung hält die Skills-Größenbemessung getrennt von der Größenbemessung für Laufzeit-Lesen/-Injektion wie -`memory_get`, Live-Tool-Ergebnisse und AGENTS.md-Aktualisierungen nach Compaction. +Diese Aufteilung hält die Dimensionierung von Skills getrennt von der Dimensionierung für das Lesen/Injizieren zur Laufzeit, etwa `memory_get`, Live-Tool-Ergebnisse und AGENTS.md-Aktualisierungen nach der Compaction. ## Dokumentation -Der System-Prompt enthält einen Abschnitt **Dokumentation**. Wenn lokale Dokumentation verfügbar ist, verweist er auf das lokale OpenClaw-Dokumentationsverzeichnis (`docs/` in einem Git-Checkout oder die mitgelieferte Dokumentation des npm-Pakets). Wenn keine lokale Dokumentation verfügbar ist, weicht er auf [https://docs.openclaw.ai](https://docs.openclaw.ai) aus. +Der System-Prompt enthält einen Abschnitt **Dokumentation**. Wenn lokale Dokumentation verfügbar ist, verweist er auf das lokale OpenClaw-Dokumentationsverzeichnis (`docs/` in einem Git-Checkout oder die gebündelte npm-Paketdokumentation). Wenn keine lokale Dokumentation verfügbar ist, fällt er auf [https://docs.openclaw.ai](https://docs.openclaw.ai) zurück. -Derselbe Abschnitt enthält außerdem den Speicherort des OpenClaw-Quellcodes. Git-Checkouts stellen das lokale Quell-Root bereit, damit der Agent den Code direkt prüfen kann. Paketinstallationen enthalten die GitHub-Quell-URL und weisen den Agenten an, den Quellcode dort zu prüfen, wenn die Dokumentation unvollständig oder veraltet ist. Der Prompt erwähnt außerdem die öffentliche Dokumentationsspiegelung, den Community-Discord und ClawHub ([https://clawhub.ai](https://clawhub.ai)) für die Entdeckung von Skills. Er weist das Modell an, für OpenClaw-Verhalten, Befehle, Konfiguration oder Architektur zuerst die Dokumentation zu konsultieren und nach Möglichkeit selbst `openclaw status` auszuführen (und den Benutzer nur zu fragen, wenn ihm der Zugriff fehlt). Speziell für die Konfiguration verweist er Agenten auf die `gateway`-Tool-Aktion `config.schema.lookup` für exakte feldbezogene Dokumentation und Einschränkungen und anschließend auf `docs/gateway/configuration.md` und `docs/gateway/configuration-reference.md` für weiterführende Anleitung. +Derselbe Abschnitt enthält außerdem den Speicherort des OpenClaw-Quellcodes. Git-Checkouts stellen das lokale Source-Root bereit, damit der Agent Code direkt prüfen kann. Paketinstallationen enthalten die GitHub-Quell-URL und weisen den Agenten an, dort den Quellcode zu prüfen, wenn die Dokumentation unvollständig oder veraltet ist. Der Prompt erwähnt außerdem die öffentliche Dokumentationsspiegelung, den Community-Discord und ClawHub ([https://clawhub.ai](https://clawhub.ai)) zur Entdeckung von Skills. Er weist das Modell an, zuerst die Dokumentation zu OpenClaw-Verhalten, -Befehlen, -Konfiguration oder -Architektur zu konsultieren und nach Möglichkeit selbst `openclaw status` auszuführen (und den Benutzer nur zu fragen, wenn ihm der Zugriff fehlt). Speziell für die Konfiguration verweist er Agenten zuerst auf die `gateway`-Tool-Aktion `config.schema.lookup` für exakte Dokumentation und Einschränkungen auf Feldebene, anschließend auf `docs/gateway/configuration.md` und `docs/gateway/configuration-reference.md` für weiterführende Anleitung. -## Verwandt +## Verwandte Themen -- [Agenten-Laufzeit](/de/concepts/agent) -- [Agenten-Arbeitsbereich](/de/concepts/agent-workspace) +- [Agent-Laufzeitumgebung](/de/concepts/agent) +- [Agent-Arbeitsbereich](/de/concepts/agent-workspace) - [Kontext-Engine](/de/concepts/context-engine) diff --git a/docs/de/nodes/audio.md b/docs/de/nodes/audio.md index bc79f0af4..7ffcfa5b7 100644 --- a/docs/de/nodes/audio.md +++ b/docs/de/nodes/audio.md @@ -1,29 +1,30 @@ --- read_when: - - Audio-Transkription oder Medienverarbeitung ändern -summary: Wie eingehende Audio-/Sprachnachrichten heruntergeladen, transkribiert und in Antworten eingefügt werden -title: Audio und Sprachnotizen + - Audiotranskription oder Medienverarbeitung ändern +summary: Wie eingehende Audio-/Sprachnotizen heruntergeladen, transkribiert und in Antworten eingefügt werden +title: Audio- und Sprachnotizen x-i18n: - generated_at: "2026-04-30T07:01:55Z" + generated_at: "2026-05-02T23:39:04Z" model: gpt-5.5 provider: openai - source_hash: 35074d79104f767ee252064462202a8ec21ac26f6db25c39e67f31f6b40edeb7 + source_hash: 91cd6951f80c6137061a7d4e82415b0872bc92c6d6ad136273a2e9ad7ec00ac1 source_path: nodes/audio.md workflow: 16 --- -# Audio / Sprachnotizen (2026-01-17) +# Audio-/Sprachnotizen (2026-01-17) ## Was funktioniert - **Medienverständnis (Audio)**: Wenn Audioverständnis aktiviert ist (oder automatisch erkannt wird), führt OpenClaw Folgendes aus: - 1. Sucht den ersten Audioanhang (lokaler Pfad oder URL) und lädt ihn bei Bedarf herunter. - 2. Erzwingt `maxBytes`, bevor der Anhang an jeden Modelleintrag gesendet wird. - 3. Führt den ersten geeigneten Modelleintrag der Reihe nach aus (Provider oder CLI). + 1. Es findet den ersten Audioanhang (lokaler Pfad oder URL) und lädt ihn bei Bedarf herunter. + 2. Es erzwingt `maxBytes`, bevor an jeden Modelleintrag gesendet wird. + 3. Es führt den ersten geeigneten Modelleintrag in der Reihenfolge aus (Provider oder CLI). 4. Wenn dies fehlschlägt oder übersprungen wird (Größe/Timeout), wird der nächste Eintrag versucht. - 5. Bei Erfolg wird `Body` durch einen `[Audio]`-Block ersetzt und `{{Transcript}}` gesetzt. + 5. Bei Erfolg ersetzt es `Body` durch einen `[Audio]`-Block und setzt `{{Transcript}}`. - **Befehlsparsing**: Wenn die Transkription erfolgreich ist, werden `CommandBody`/`RawBody` auf das Transkript gesetzt, sodass Slash-Befehle weiterhin funktionieren. -- **Ausführliche Protokollierung**: Mit `--verbose` protokollieren wir, wann die Transkription ausgeführt wird und wann sie den Body ersetzt. +- **Ausführliche Protokollierung**: In `--verbose` protokollieren wir, wann die Transkription ausgeführt wird und wann sie den Body ersetzt. +- **Diktat in der Steuerungs-UI**: Der Chat-Composer kann einen im Browser aufgenommenen Mikrofonclip an `chat.transcribeAudio` senden. Dieser Gateway-RPC schreibt den Clip in eine temporäre lokale Datei, führt dieselbe Audio-Transkriptionspipeline aus, gibt Entwurfstext an den Browser zurück und löscht die temporäre Datei. Er erstellt nicht selbst einen Agentenlauf. ## Automatische Erkennung (Standard) @@ -35,18 +36,18 @@ erkennt OpenClaw automatisch in dieser Reihenfolge und stoppt bei der ersten fun - `sherpa-onnx-offline` (erfordert `SHERPA_ONNX_MODEL_DIR` mit Encoder/Decoder/Joiner/Tokens) - `whisper-cli` (aus `whisper-cpp`; verwendet `WHISPER_CPP_MODEL` oder das gebündelte Tiny-Modell) - `whisper` (Python-CLI; lädt Modelle automatisch herunter) -3. **Gemini CLI** (`gemini`) mit `read_many_files` +3. **Gemini-CLI** (`gemini`) mit `read_many_files` 4. **Provider-Authentifizierung** - Konfigurierte `models.providers.*`-Einträge, die Audio unterstützen, werden zuerst versucht - Gebündelte Fallback-Reihenfolge: OpenAI → Groq → xAI → Deepgram → Google → SenseAudio → ElevenLabs → Mistral Um die automatische Erkennung zu deaktivieren, setzen Sie `tools.media.audio.enabled: false`. -Um sie anzupassen, setzen Sie `tools.media.audio.models`. -Hinweis: Die Erkennung von Binärdateien ist unter macOS/Linux/Windows nach bestem Bemühen; stellen Sie sicher, dass die CLI in `PATH` liegt (wir erweitern `~`), oder setzen Sie ein explizites CLI-Modell mit vollständigem Befehlspfad. +Zum Anpassen setzen Sie `tools.media.audio.models`. +Hinweis: Die Binärerkennung erfolgt nach bestem Bemühen unter macOS/Linux/Windows; stellen Sie sicher, dass die CLI auf `PATH` liegt (wir erweitern `~`), oder setzen Sie ein explizites CLI-Modell mit vollständigem Befehlspfad. ## Konfigurationsbeispiele -### Provider + CLI-Fallback (OpenAI + Whisper CLI) +### Provider + CLI-Fallback (OpenAI + Whisper-CLI) ```json5 { @@ -70,7 +71,7 @@ Hinweis: Die Erkennung von Binärdateien ist unter macOS/Linux/Windows nach best } ``` -### Nur Provider mit Scope-Gating +### Nur Provider mit Bereichssteuerung ```json5 { @@ -134,7 +135,7 @@ Hinweis: Die Erkennung von Binärdateien ist unter macOS/Linux/Windows nach best } ``` -### Transkript in den Chat zurücksenden (Opt-in) +### Transkript in den Chat zurückgeben (Opt-in) ```json5 { @@ -153,28 +154,28 @@ Hinweis: Die Erkennung von Binärdateien ist unter macOS/Linux/Windows nach best ## Hinweise und Grenzen -- Die Provider-Authentifizierung folgt der standardmäßigen Authentifizierungsreihenfolge für Modelle (Auth-Profile, Umgebungsvariablen, `models.providers.*.apiKey`). +- Die Provider-Authentifizierung folgt der Standardreihenfolge für die Modellauthentifizierung (Authentifizierungsprofile, Umgebungsvariablen, `models.providers.*.apiKey`). - Details zur Groq-Einrichtung: [Groq](/de/providers/groq). -- Deepgram übernimmt `DEEPGRAM_API_KEY`, wenn `provider: "deepgram"` verwendet wird. -- Details zur Deepgram-Einrichtung: [Deepgram (Audiotranskription)](/de/providers/deepgram). +- Deepgram greift `DEEPGRAM_API_KEY` auf, wenn `provider: "deepgram"` verwendet wird. +- Details zur Deepgram-Einrichtung: [Deepgram (Audio-Transkription)](/de/providers/deepgram). - Details zur Mistral-Einrichtung: [Mistral](/de/providers/mistral). -- SenseAudio übernimmt `SENSEAUDIO_API_KEY`, wenn `provider: "senseaudio"` verwendet wird. +- SenseAudio greift `SENSEAUDIO_API_KEY` auf, wenn `provider: "senseaudio"` verwendet wird. - Details zur SenseAudio-Einrichtung: [SenseAudio](/de/providers/senseaudio). - Audio-Provider können `baseUrl`, `headers` und `providerOptions` über `tools.media.audio` überschreiben. -- Die standardmäßige Größenbegrenzung beträgt 20 MB (`tools.media.audio.maxBytes`). Zu große Audiodateien werden für dieses Modell übersprungen und der nächste Eintrag wird versucht. -- Winzige/leere Audiodateien unter 1024 Bytes werden vor der Provider-/CLI-Transkription übersprungen. +- Die standardmäßige Größenbegrenzung beträgt 20 MB (`tools.media.audio.maxBytes`). Zu große Audiodateien werden für dieses Modell übersprungen, und der nächste Eintrag wird versucht. +- Sehr kleine/leere Audiodateien unter 1024 Byte werden vor der Provider-/CLI-Transkription übersprungen. - Der Standardwert für `maxChars` bei Audio ist **nicht gesetzt** (vollständiges Transkript). Setzen Sie `tools.media.audio.maxChars` oder `maxChars` pro Eintrag, um die Ausgabe zu kürzen. - Der automatische OpenAI-Standard ist `gpt-4o-mini-transcribe`; setzen Sie `model: "gpt-4o-transcribe"` für höhere Genauigkeit. - Verwenden Sie `tools.media.audio.attachments`, um mehrere Sprachnotizen zu verarbeiten (`mode: "all"` + `maxAttachments`). -- Das Transkript ist für Vorlagen als `{{Transcript}}` verfügbar. -- `tools.media.audio.echoTranscript` ist standardmäßig deaktiviert; aktivieren Sie es, um vor der Agent-Verarbeitung eine Transkriptbestätigung an den ursprünglichen Chat zurückzusenden. +- Das Transkript ist in Vorlagen als `{{Transcript}}` verfügbar. +- `tools.media.audio.echoTranscript` ist standardmäßig deaktiviert; aktivieren Sie es, um vor der Agentenverarbeitung eine Transkriptbestätigung an den ursprünglichen Chat zurückzusenden. - `tools.media.audio.echoFormat` passt den Echo-Text an (Platzhalter: `{transcript}`). -- CLI-stdout ist begrenzt (5 MB); halten Sie die CLI-Ausgabe knapp. -- CLI-`args` sollte `{{MediaPath}}` für den lokalen Audiodateipfad verwenden. Führen Sie `openclaw doctor --fix` aus, um veraltete `{input}`-Platzhalter aus älteren `audio.transcription.command`-Konfigurationen zu migrieren. +- Die CLI-Standardausgabe ist begrenzt (5 MB); halten Sie die CLI-Ausgabe knapp. +- CLI-`args` sollten `{{MediaPath}}` für den lokalen Audiodateipfad verwenden. Führen Sie `openclaw doctor --fix` aus, um veraltete `{input}`-Platzhalter aus älteren `audio.transcription.command`-Konfigurationen zu migrieren. ### Unterstützung für Proxy-Umgebungen -Provider-basierte Audiotranskription berücksichtigt standardmäßige ausgehende Proxy-Umgebungsvariablen: +Provider-basierte Audio-Transkription berücksichtigt standardmäßige ausgehende Proxy-Umgebungsvariablen: - `HTTPS_PROXY` - `HTTP_PROXY` @@ -185,40 +186,40 @@ Provider-basierte Audiotranskription berücksichtigt standardmäßige ausgehende Wenn keine Proxy-Umgebungsvariablen gesetzt sind, wird direkter ausgehender Zugriff verwendet. Wenn die Proxy-Konfiguration fehlerhaft ist, protokolliert OpenClaw eine Warnung und fällt auf direkten Abruf zurück. -## Mention-Erkennung in Gruppen +## Erwähnungserkennung in Gruppen -Wenn `requireMention: true` für einen Gruppenchat gesetzt ist, transkribiert OpenClaw Audio jetzt **vor** der Prüfung auf Mentions. Dadurch können Sprachnotizen auch dann verarbeitet werden, wenn sie Mentions enthalten. +Wenn `requireMention: true` für einen Gruppenchat gesetzt ist, transkribiert OpenClaw Audio jetzt **vor** der Prüfung auf Erwähnungen. Dadurch können Sprachnotizen auch dann verarbeitet werden, wenn sie Erwähnungen enthalten. **So funktioniert es:** -1. Wenn eine Sprachnachricht keinen Text-Body hat und die Gruppe Mentions erfordert, führt OpenClaw eine „Preflight“-Transkription aus. -2. Das Transkript wird auf Mention-Muster geprüft (z. B. `@BotName`, Emoji-Auslöser). -3. Wenn eine Mention gefunden wird, durchläuft die Nachricht die vollständige Antwort-Pipeline. -4. Das Transkript wird für die Mention-Erkennung verwendet, damit Sprachnotizen das Mention-Gate passieren können. +1. Wenn eine Sprachnachricht keinen Text-Body hat und die Gruppe Erwähnungen erfordert, führt OpenClaw eine „Preflight“-Transkription aus. +2. Das Transkript wird auf Erwähnungsmuster geprüft (z. B. `@BotName`, Emoji-Auslöser). +3. Wenn eine Erwähnung gefunden wird, durchläuft die Nachricht die vollständige Antwortpipeline. +4. Das Transkript wird für die Erwähnungserkennung verwendet, sodass Sprachnotizen das Erwähnungs-Gate passieren können. **Fallback-Verhalten:** -- Wenn die Transkription während des Preflight fehlschlägt (Timeout, API-Fehler usw.), wird die Nachricht basierend auf reiner Text-Mention-Erkennung verarbeitet. +- Wenn die Transkription während des Preflight fehlschlägt (Timeout, API-Fehler usw.), wird die Nachricht anhand der reinen Text-Erwähnungserkennung verarbeitet. - Dadurch wird sichergestellt, dass gemischte Nachrichten (Text + Audio) nie fälschlicherweise verworfen werden. -**Opt-out pro Telegram-Gruppe/-Thema:** +**Opt-out pro Telegram-Gruppe/Thema:** -- Setzen Sie `channels.telegram.groups..disableAudioPreflight: true`, um Preflight-Transkript-Mention-Prüfungen für diese Gruppe zu überspringen. -- Setzen Sie `channels.telegram.groups..topics..disableAudioPreflight`, um dies pro Thema zu überschreiben (`true` zum Überspringen, `false` zum erzwungenen Aktivieren). -- Standard ist `false` (Preflight aktiviert, wenn Mention-Gating-Bedingungen zutreffen). +- Setzen Sie `channels.telegram.groups..disableAudioPreflight: true`, um Preflight-Transkriptprüfungen auf Erwähnungen für diese Gruppe zu überspringen. +- Setzen Sie `channels.telegram.groups..topics..disableAudioPreflight`, um pro Thema zu überschreiben (`true` zum Überspringen, `false` zum Erzwingen der Aktivierung). +- Standard ist `false` (Preflight aktiviert, wenn die durch Erwähnungen gesteuerten Bedingungen zutreffen). -**Beispiel:** Ein Benutzer sendet in einer Telegram-Gruppe mit `requireMention: true` eine Sprachnotiz mit dem Inhalt „Hey @Claude, what's the weather?“. Die Sprachnotiz wird transkribiert, die Mention wird erkannt und der Agent antwortet. +**Beispiel:** Ein Benutzer sendet in einer Telegram-Gruppe mit `requireMention: true` eine Sprachnotiz mit dem Inhalt „Hey @Claude, wie ist das Wetter?“. Die Sprachnotiz wird transkribiert, die Erwähnung wird erkannt, und der Agent antwortet. -## Stolperfallen +## Fallstricke -- Scope-Regeln verwenden First-match-wins. `chatType` wird auf `direct`, `group` oder `room` normalisiert. -- Stellen Sie sicher, dass Ihre CLI mit 0 beendet wird und Klartext ausgibt; JSON muss über `jq -r .text` angepasst werden. -- Wenn Sie bei `parakeet-mlx` `--output-dir` übergeben, liest OpenClaw `/.txt`, wenn `--output-format` `txt` ist (oder weggelassen wurde); Ausgabeformate ungleich `txt` fallen auf stdout-Parsing zurück. -- Halten Sie Timeouts angemessen (`timeoutSeconds`, Standard 60 s), um die Antwortwarteschlange nicht zu blockieren. -- Die Preflight-Transkription verarbeitet für die Mention-Erkennung nur den **ersten** Audioanhang. Zusätzliches Audio wird während der Hauptphase des Medienverständnisses verarbeitet. +- Bereichsregeln verwenden „erste Übereinstimmung gewinnt“. `chatType` wird zu `direct`, `group` oder `room` normalisiert. +- Stellen Sie sicher, dass Ihre CLI mit 0 beendet wird und Klartext ausgibt; JSON muss über `jq -r .text` aufbereitet werden. +- Bei `parakeet-mlx` liest OpenClaw, wenn Sie `--output-dir` übergeben, `/.txt`, wenn `--output-format` `txt` ist (oder ausgelassen wird); Nicht-`txt`-Ausgabeformate fallen auf das Parsen von stdout zurück. +- Halten Sie Timeouts angemessen (`timeoutSeconds`, Standard 60 s), um ein Blockieren der Antwortwarteschlange zu vermeiden. +- Die Preflight-Transkription verarbeitet zur Erwähnungserkennung nur den **ersten** Audioanhang. Zusätzliches Audio wird während der Hauptphase des Medienverständnisses verarbeitet. ## Verwandt - [Medienverständnis](/de/nodes/media-understanding) - [Sprechmodus](/de/nodes/talk) -- [Voice Wake](/de/nodes/voicewake) +- [Sprachaktivierung](/de/nodes/voicewake) diff --git a/docs/de/plugins/codex-harness.md b/docs/de/plugins/codex-harness.md index 369a5c7fb..a70dd76cb 100644 --- a/docs/de/plugins/codex-harness.md +++ b/docs/de/plugins/codex-harness.md @@ -1,58 +1,60 @@ --- read_when: - - Sie möchten den mitgelieferten Codex-App-Server-Harness verwenden - - Sie benötigen Codex-Harness-Konfigurationsbeispiele - - Sie möchten, dass reine Codex-Deployments fehlschlagen, statt auf PI zurückzufallen -summary: Führen Sie eingebettete OpenClaw-Agent-Durchläufe über den mitgelieferten Codex-App-Server-Harness aus + - Sie möchten die mitgelieferte Codex-App-Server-Testumgebung verwenden + - Sie benötigen Beispiele für die Codex-Harness-Konfiguration + - Sie möchten, dass reine Codex-Bereitstellungen fehlschlagen, anstatt auf Pi zurückzufallen +summary: Eingebettete OpenClaw-Agent-Durchläufe über den mitgelieferten Codex-App-Server-Harness ausführen title: Codex-Testumgebung x-i18n: - generated_at: "2026-05-02T06:39:59Z" + generated_at: "2026-05-02T23:39:30Z" model: gpt-5.5 provider: openai - source_hash: 107f9fc0a3e8ad6a4790fc9eb68276c81d299236f11293014d2ab9bf6e235133 + source_hash: 8ffa0cbb28422b2ed8d7c0eef6ee0222072c523d170b4b33597bb37bd3fa9700 source_path: plugins/codex-harness.md workflow: 16 --- -Das gebündelte `codex`-Plugin ermöglicht OpenClaw, eingebettete Agent-Durchläufe über den -Codex-App-Server statt über den integrierten PI-Harness auszuführen. +Das gebündelte `codex`-Plugin lässt OpenClaw eingebettete Agent-Turns über den +Codex app-server statt über das eingebaute PI-Harness ausführen. -Verwenden Sie dies, wenn Codex die Low-Level-Agent-Sitzung übernehmen soll: -Modellerkennung, native Thread-Fortsetzung, native Compaction und App-Server-Ausführung. -OpenClaw bleibt weiterhin für Chat-Kanäle, Sitzungsdateien, Modellauswahl, Tools, -Genehmigungen, Medienzustellung und die sichtbare Transkriptspiegelung zuständig. +Verwenden Sie dies, wenn Codex die Low-Level-Agent-Session übernehmen soll: +Modellerkennung, natives Thread-Resume, native Compaction und app-server-Ausführung. +OpenClaw bleibt weiterhin zuständig für Chat-Kanäle, Session-Dateien, Modellauswahl, +Tools, Genehmigungen, Medienzustellung und die sichtbare Transcript-Spiegelung. -Wenn ein Quell-Chat-Durchlauf über den Codex-Harness läuft, verwenden sichtbare Antworten standardmäßig -das OpenClaw-`message`-Tool, wenn die Bereitstellung -`messages.visibleReplies` nicht explizit konfiguriert hat. Der Agent kann seinen Codex-Durchlauf weiterhin privat abschließen; -er postet nur dann in den Kanal, wenn er `message(action="send")` aufruft. Setzen Sie -`messages.visibleReplies: "automatic"`, um abschließende Antworten in Direkt-Chats auf dem -älteren automatischen Zustellpfad zu belassen. +Wenn ein Quell-Chat-Turn über das Codex-Harness läuft, verwenden sichtbare Antworten +standardmäßig das OpenClaw-`message`-Tool, sofern das Deployment +`messages.visibleReplies` nicht ausdrücklich konfiguriert hat. Der Agent kann seinen +Codex-Turn weiterhin privat abschließen; er postet nur dann in den Kanal, wenn er +`message(action="send")` aufruft. Setzen Sie `messages.visibleReplies: "automatic"`, +um finale Antworten in direkten Chats weiterhin über den alten automatischen +Zustellpfad auszuliefern. -Codex-Heartbeat-Durchläufe erhalten standardmäßig auch das Tool `heartbeat_respond`, sodass der -Agent festhalten kann, ob der Wake still bleiben oder benachrichtigen soll, ohne -diesen Kontrollfluss im abschließenden Text zu codieren. +Codex-Heartbeat-Turns erhalten außerdem standardmäßig das Tool `heartbeat_respond`, +damit der Agent erfassen kann, ob der Wake still bleiben oder benachrichtigen soll, +ohne diesen Kontrollfluss in finalen Text zu codieren. Wenn Sie sich orientieren möchten, beginnen Sie mit [Agent-Laufzeiten](/de/concepts/agent-runtimes). Die Kurzfassung lautet: -`openai/gpt-5.5` ist die Modellreferenz, `codex` ist die Laufzeit, und Telegram, +`openai/gpt-5.5` ist die Modellreferenz, `codex` ist die Runtime, und Telegram, Discord, Slack oder ein anderer Kanal bleibt die Kommunikationsoberfläche. ## Schnellkonfiguration -Die meisten Benutzer, die „Codex in OpenClaw“ möchten, wollen diese Route: Melden Sie sich mit einem -ChatGPT-/Codex-Abonnement an und führen Sie dann eingebettete Agent-Durchläufe über die native -Codex-App-Server-Laufzeit aus. Die Modellreferenz bleibt weiterhin kanonisch -`openai/gpt-*`; die Abonnement-Authentifizierung kommt aus dem Codex-Konto/-Profil, nicht -aus einem Modellpräfix `openai-codex/*`. +Die meisten Benutzer, die „Codex in OpenClaw“ möchten, wollen diese Route: mit +einem ChatGPT/Codex-Abonnement anmelden und eingebettete Agent-Turns dann über die +native Codex app-server-Runtime ausführen. Die Modellreferenz bleibt weiterhin +kanonisch `openai/gpt-*`; die Abonnement-Authentifizierung kommt aus dem +Codex-Konto/-Profil, nicht aus einem `openai-codex/*`-Modellpräfix. -Melden Sie sich zuerst mit Codex OAuth an, falls Sie dies noch nicht getan haben: +Melden Sie sich zuerst mit Codex OAuth an, falls Sie das noch nicht getan haben: ```bash openclaw models auth login --provider openai-codex ``` -Aktivieren Sie dann das gebündelte `codex`-Plugin und erzwingen Sie die Codex-Laufzeit: +Aktivieren Sie dann das gebündelte `codex`-Plugin und erzwingen Sie die +Codex-Runtime: ```json5 { @@ -75,7 +77,8 @@ Aktivieren Sie dann das gebündelte `codex`-Plugin und erzwingen Sie die Codex-L } ``` -Wenn Ihre Konfiguration `plugins.allow` verwendet, nehmen Sie dort ebenfalls `codex` auf: +Wenn Ihre Konfiguration `plugins.allow` verwendet, nehmen Sie dort ebenfalls +`codex` auf: ```json5 { @@ -90,200 +93,226 @@ Wenn Ihre Konfiguration `plugins.allow` verwendet, nehmen Sie dort ebenfalls `co } ``` -Verwenden Sie nicht `openai-codex/gpt-*`, wenn Sie die native Codex-Laufzeit meinen. Dieses Präfix -ist die explizite Route „Codex OAuth über PI“. Konfigurationsänderungen gelten für neue oder -zurückgesetzte Sitzungen; bestehende Sitzungen behalten ihre aufgezeichnete Laufzeit. +Verwenden Sie nicht `openai-codex/gpt-*`, wenn Sie die native Codex-Runtime +meinen. Dieses Präfix ist die explizite Route „Codex OAuth über PI“. +Konfigurationsänderungen gelten für neue oder zurückgesetzte Sessions; +bestehende Sessions behalten ihre aufgezeichnete Runtime. ## Was dieses Plugin ändert Das gebündelte `codex`-Plugin stellt mehrere separate Fähigkeiten bereit: -| Fähigkeit | Wie Sie sie verwenden | Was sie bewirkt | -| --------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------- | -| Native eingebettete Laufzeit | `agentRuntime.id: "codex"` | Führt eingebettete OpenClaw-Agent-Durchläufe über den Codex-App-Server aus. | -| Native Chat-Steuerbefehle | `/codex bind`, `/codex resume`, `/codex steer`, ... | Bindet und steuert Codex-App-Server-Threads aus einer Messaging-Unterhaltung. | -| Codex-App-Server-Provider/-Katalog | `codex`-Interna, über den Harness verfügbar | Ermöglicht der Laufzeit, App-Server-Modelle zu erkennen und zu validieren. | -| Codex-Pfad für Medienverständnis | `codex/*`-Kompatibilitätspfade für Bildmodelle | Führt begrenzte Codex-App-Server-Durchläufe für unterstützte Bildverständnismodelle aus. | -| Natives Hook-Relay | Plugin-Hooks um Codex-native Ereignisse | Ermöglicht OpenClaw, unterstützte Codex-native Tool-/Finalisierungsereignisse zu beobachten/blockieren. | +| Fähigkeit | Wie Sie sie verwenden | Was sie bewirkt | +| --------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------- | +| Native eingebettete Runtime | `agentRuntime.id: "codex"` | Führt eingebettete OpenClaw-Agent-Turns über Codex app-server aus. | +| Native Chat-Steuerbefehle | `/codex bind`, `/codex resume`, `/codex steer`, ... | Bindet und steuert Codex app-server-Threads aus einer Messaging-Unterhaltung. | +| Codex app-server-Provider/-Katalog | `codex`-Interna, über das Harness offengelegt | Ermöglicht der Runtime, app-server-Modelle zu erkennen und zu validieren. | +| Codex-Pfad für Medienverständnis | `codex/*`-Kompatibilitätspfade für Bildmodelle | Führt begrenzte Codex app-server-Turns für unterstützte Modelle zum Bildverständnis aus. | +| Native Hook-Weiterleitung | Plugin-Hooks rund um Codex-native Ereignisse | Ermöglicht OpenClaw, unterstützte Codex-native Tool-/Finalisierungsereignisse zu beobachten/blockieren. | -Durch Aktivieren des Plugins werden diese Fähigkeiten verfügbar. Es bewirkt **nicht**: +Durch das Aktivieren des Plugins werden diese Fähigkeiten verfügbar. Es bewirkt +**nicht**: - Codex für jedes OpenAI-Modell zu verwenden -- `openai-codex/*`-Modellreferenzen in die native Laufzeit umzuwandeln +- `openai-codex/*`-Modellreferenzen in die native Runtime umzuwandeln - ACP/acpx zum Standard-Codex-Pfad zu machen -- bestehende Sitzungen automatisch umzuschalten, die bereits eine PI-Laufzeit aufgezeichnet haben -- OpenClaw-Kanalzustellung, Sitzungsdateien, Authentifizierungsprofilspeicher oder - Nachrichtenrouting zu ersetzen +- bestehende Sessions, die bereits eine PI-Runtime aufgezeichnet haben, im laufenden Betrieb umzuschalten +- OpenClaw-Kanalzustellung, Session-Dateien, Auth-Profil-Speicherung oder + Nachrichten-Routing zu ersetzen -Dasselbe Plugin besitzt auch die native Chat-Steuerbefehlsoberfläche `/codex`. Wenn -das Plugin aktiviert ist und der Benutzer darum bittet, Codex-Threads aus dem Chat zu binden, -fortzusetzen, zu steuern, zu stoppen oder zu prüfen, sollten Agents `/codex ...` ACP vorziehen. ACP bleibt -der explizite Fallback, wenn der Benutzer nach ACP/acpx fragt oder den ACP- -Codex-Adapter testet. +Dasselbe Plugin besitzt auch die native `/codex`-Chat-Steuerbefehlsoberfläche. +Wenn das Plugin aktiviert ist und der Benutzer darum bittet, Codex-Threads aus +dem Chat zu binden, fortzusetzen, zu steuern, zu stoppen oder zu inspizieren, +sollten Agents `/codex ...` gegenüber ACP bevorzugen. ACP bleibt der explizite +Fallback, wenn der Benutzer ACP/acpx verlangt oder den ACP-Codex-Adapter testet. -Native Codex-Durchläufe behalten OpenClaw-Plugin-Hooks als öffentliche Kompatibilitätsschicht bei. -Dies sind prozessinterne OpenClaw-Hooks, keine Codex-`hooks.json`-Command-Hooks: +Native Codex-Turns behalten OpenClaw-Plugin-Hooks als öffentliche +Kompatibilitätsschicht. Dies sind prozessinterne OpenClaw-Hooks, keine +Codex-`hooks.json`-Befehlshooks: - `before_prompt_build` - `before_compaction`, `after_compaction` - `llm_input`, `llm_output` - `before_tool_call`, `after_tool_call` -- `before_message_write` für gespiegelte Transkriptdatensätze -- `before_agent_finalize` über Codex-`Stop`-Relay +- `before_message_write` für gespiegelte Transcript-Einträge +- `before_agent_finalize` über die Codex-`Stop`-Weiterleitung - `agent_end` -Plugins können außerdem laufzeitneutrale Tool-Ergebnis-Middleware registrieren, um -dynamische OpenClaw-Tool-Ergebnisse umzuschreiben, nachdem OpenClaw das Tool ausgeführt hat und bevor das -Ergebnis an Codex zurückgegeben wird. Dies ist getrennt vom öffentlichen -Plugin-Hook `tool_result_persist`, der OpenClaw-eigene Transkript- -Tool-Ergebnisschreibvorgänge transformiert. +Plugins können außerdem runtime-neutrale Tool-Ergebnis-Middleware registrieren, +um dynamische OpenClaw-Tool-Ergebnisse umzuschreiben, nachdem OpenClaw das Tool +ausgeführt hat und bevor das Ergebnis an Codex zurückgegeben wird. Das ist +getrennt vom öffentlichen Plugin-Hook `tool_result_persist`, der von OpenClaw +verwaltete Transcript-Schreibvorgänge für Tool-Ergebnisse transformiert. -Für die Semantik der Plugin-Hooks selbst siehe [Plugin-Hooks](/de/plugins/hooks) -und [Plugin-Schutzverhalten](/de/tools/plugin). +Die Semantik der Plugin-Hooks selbst finden Sie unter +[Plugin-Hooks](/de/plugins/hooks) und +[Plugin-Guard-Verhalten](/de/tools/plugin). -Der Harness ist standardmäßig deaktiviert. Neue Konfigurationen sollten OpenAI-Modellreferenzen -kanonisch als `openai/gpt-*` belassen und explizit -`agentRuntime.id: "codex"` oder `OPENCLAW_AGENT_RUNTIME=codex` erzwingen, wenn sie -native App-Server-Ausführung wünschen. Ältere `codex/*`-Modellreferenzen wählen aus -Kompatibilitätsgründen weiterhin automatisch den Harness aus, aber laufzeitgestützte ältere Provider-Präfixe werden +Das Harness ist standardmäßig deaktiviert. Neue Konfigurationen sollten +OpenAI-Modellreferenzen kanonisch als `openai/gpt-*` beibehalten und +`agentRuntime.id: "codex"` oder `OPENCLAW_AGENT_RUNTIME=codex` ausdrücklich +erzwingen, wenn native app-server-Ausführung gewünscht ist. Alte +`codex/*`-Modellreferenzen wählen aus Kompatibilitätsgründen weiterhin +automatisch das Harness aus, aber runtime-gestützte alte Provider-Präfixe werden nicht als normale Modell-/Provider-Auswahl angezeigt. Wenn das `codex`-Plugin aktiviert ist, das primäre Modell aber weiterhin -`openai-codex/*` ist, warnt `openclaw doctor`, anstatt die Route zu ändern. Das ist -beabsichtigt: `openai-codex/*` bleibt der PI-Pfad für Codex OAuth/Abonnement, und -native App-Server-Ausführung bleibt eine explizite Laufzeitauswahl. +`openai-codex/*` ist, warnt `openclaw doctor`, statt die Route zu ändern. Das ist +beabsichtigt: `openai-codex/*` bleibt der PI-Pfad für Codex +OAuth/Abonnement, und native app-server-Ausführung bleibt eine explizite +Runtime-Auswahl. ## Routenübersicht Verwenden Sie diese Tabelle, bevor Sie die Konfiguration ändern: -| Gewünschtes Verhalten | Modellreferenz | Laufzeitkonfiguration | Authentifizierungs-/Profilroute | Erwartetes Statuslabel | -| ----------------------------------------------------- | ------------------------- | -------------------------------------- | ------------------------------- | ------------------------------- | -| ChatGPT-/Codex-Abonnement mit nativer Codex-Laufzeit | `openai/gpt-*` | `agentRuntime.id: "codex"` | Codex OAuth oder Codex-Konto | `Runtime: OpenAI Codex` | -| OpenAI API über normalen OpenClaw-Runner | `openai/gpt-*` | weggelassen oder `runtime: "pi"` | OpenAI-API-Schlüssel | `Runtime: OpenClaw Pi Default` | -| ChatGPT-/Codex-Abonnement über PI | `openai-codex/gpt-*` | weggelassen oder `runtime: "pi"` | OpenAI-Codex-OAuth-Provider | `Runtime: OpenClaw Pi Default` | -| Gemischte Provider mit konservativem Auto-Modus | Provider-spezifische Referenzen | `agentRuntime.id: "auto"` | Je ausgewähltem Provider | Hängt von der ausgewählten Laufzeit ab | -| Explizite Codex-ACP-Adapter-Sitzung | ACP-prompt-/modellabhängig | `sessions_spawn` mit `runtime: "acp"` | ACP-Backend-Authentifizierung | ACP-Aufgaben-/Sitzungsstatus | +| Gewünschtes Verhalten | Modellreferenz | Runtime-Konfiguration | Auth-/Profilroute | Erwartetes Statuslabel | +| --------------------------------------------------- | -------------------------- | ------------------------------------- | ---------------------------- | ------------------------------ | +| ChatGPT/Codex-Abonnement mit nativer Codex-Runtime | `openai/gpt-*` | `agentRuntime.id: "codex"` | Codex OAuth oder Codex-Konto | `Runtime: OpenAI Codex` | +| OpenAI API über normalen OpenClaw-Runner | `openai/gpt-*` | ausgelassen oder `runtime: "pi"` | OpenAI-API-Schlüssel | `Runtime: OpenClaw Pi Default` | +| ChatGPT/Codex-Abonnement über PI | `openai-codex/gpt-*` | ausgelassen oder `runtime: "pi"` | OpenAI Codex OAuth-Provider | `Runtime: OpenClaw Pi Default` | +| Gemischte Provider mit konservativem Automatikmodus | provider-spezifische Referenzen | `agentRuntime.id: "auto"` | Je ausgewähltem Provider | Hängt von der ausgewählten Runtime ab | +| Explizite Codex-ACP-Adapter-Session | Abhängig von ACP-Prompt/-Modell | `sessions_spawn` mit `runtime: "acp"` | ACP-Backend-Authentifizierung | ACP-Aufgaben-/Session-Status | -Die wichtige Trennung ist Provider gegenüber Laufzeit: +Die wichtige Trennung ist Provider gegenüber Runtime: -- `openai-codex/*` beantwortet „welche Provider-/Authentifizierungsroute soll PI verwenden?“ -- `agentRuntime.id: "codex"` beantwortet „welcher Loop soll diesen - eingebetteten Durchlauf ausführen?“ -- `/codex ...` beantwortet „welche native Codex-Unterhaltung soll dieser Chat binden - oder steuern?“ -- ACP beantwortet „welchen externen Harness-Prozess soll acpx starten?“ +- `openai-codex/*` beantwortet „Welche Provider-/Authentifizierungsroute soll PI verwenden?“ +- `agentRuntime.id: "codex"` beantwortet „Welche Schleife soll diesen + eingebetteten Turn ausführen?“ +- `/codex ...` beantwortet „Welche native Codex-Unterhaltung soll dieser Chat + binden oder steuern?“ +- ACP beantwortet „Welchen externen Harness-Prozess soll acpx starten?“ ## Das richtige Modellpräfix wählen -OpenAI-Familienrouten sind präfixspezifisch. Für die übliche Einrichtung mit Abonnement plus -nativer Codex-Laufzeit verwenden Sie `openai/*` mit `agentRuntime.id: "codex"`. -Verwenden Sie `openai-codex/*` nur, wenn Sie bewusst Codex OAuth über PI möchten: +OpenAI-Familienrouten sind präfixspezifisch. Für die übliche Einrichtung mit +Abonnement plus nativer Codex-Runtime verwenden Sie `openai/*` mit +`agentRuntime.id: "codex"`. Verwenden Sie `openai-codex/*` nur, wenn Sie +absichtlich Codex OAuth über PI wünschen: -| Modellreferenz | Laufzeitpfad | Verwenden, wenn | -| --------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------- | -| `openai/gpt-5.4` | OpenAI-Provider über OpenClaw-/PI-Plumbing | Sie aktuellen direkten Zugriff auf die OpenAI Platform API mit `OPENAI_API_KEY` möchten. | -| `openai-codex/gpt-5.5` | OpenAI Codex OAuth über OpenClaw/PI | Sie ChatGPT-/Codex-Abonnement-Authentifizierung mit dem standardmäßigen PI-Runner möchten. | -| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Codex-App-Server-Harness | Sie ChatGPT-/Codex-Abonnement-Authentifizierung mit nativer Codex-Ausführung möchten. | +| Modellreferenz | Runtime-Pfad | Verwendung | +| -------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------- | +| `openai/gpt-5.4` | OpenAI-Provider über OpenClaw/PI-Plumbing | Sie möchten aktuellen direkten OpenAI-Platform-API-Zugriff mit `OPENAI_API_KEY`. | +| `openai-codex/gpt-5.5` | OpenAI Codex OAuth über OpenClaw/PI | Sie möchten ChatGPT/Codex-Abonnement-Authentifizierung mit dem Standard-PI-Runner. | +| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Codex app-server-Harness | Sie möchten ChatGPT/Codex-Abonnement-Authentifizierung mit nativer Codex-Ausführung. | -GPT-5.5 kann sowohl auf direkten OpenAI-API-Schlüssel- als auch auf Codex-Abonnement-Routen erscheinen, -wenn Ihr Konto sie bereitstellt. Verwenden Sie `openai/gpt-5.5` mit dem Codex-App-Server- -Harness für native Codex-Laufzeit, `openai-codex/gpt-5.5` für PI OAuth oder -`openai/gpt-5.5` ohne Codex-Laufzeitüberschreibung für direkten API-Schlüssel-Traffic. +GPT-5.5 kann sowohl auf direkten OpenAI-API-Schlüssel-Routen als auch auf +Codex-Abonnement-Routen erscheinen, wenn Ihr Konto sie bereitstellt. Verwenden +Sie `openai/gpt-5.5` mit dem Codex app-server-Harness für native +Codex-Runtime, `openai-codex/gpt-5.5` für PI OAuth oder `openai/gpt-5.5` ohne +Codex-Runtime-Override für direkten API-Schlüssel-Traffic. -Ältere `codex/gpt-*`-Referenzen bleiben als Kompatibilitätsaliase akzeptiert. Die -Doctor-Kompatibilitätsmigration schreibt ältere primäre Laufzeitreferenzen in kanonische Modellreferenzen um -und zeichnet die Laufzeitrichtlinie separat auf, während ältere Referenzen, die nur als Fallback dienen, -unverändert bleiben, weil die Laufzeit für den gesamten Agent-Container konfiguriert wird. -Neue PI-Codex-OAuth-Konfigurationen sollten `openai-codex/gpt-*` verwenden; neue native -App-Server-Harness-Konfigurationen sollten `openai/gpt-*` plus -`agentRuntime.id: "codex"` verwenden. +Alte `codex/gpt-*`-Referenzen werden weiterhin als Kompatibilitätsalias +akzeptiert. Die Doctor-Kompatibilitätsmigration schreibt alte primäre +Runtime-Referenzen in kanonische Modellreferenzen um und zeichnet die +Runtime-Richtlinie separat auf, während alte Referenzen, die nur als Fallback +dienen, unverändert bleiben, weil die Runtime für den gesamten Agent-Container +konfiguriert wird. Neue PI-Codex-OAuth-Konfigurationen sollten +`openai-codex/gpt-*` verwenden; neue native app-server-Harness-Konfigurationen +sollten `openai/gpt-*` plus `agentRuntime.id: "codex"` verwenden. `agents.defaults.imageModel` folgt derselben Präfixtrennung. Verwenden Sie -`openai-codex/gpt-*`, wenn Bildverständnis über den OpenAI- -Codex-OAuth-Provider-Pfad laufen soll. Verwenden Sie `codex/gpt-*`, wenn Bildverständnis -über einen begrenzten Codex-App-Server-Durchlauf laufen soll. Das Codex-App-Server-Modell muss -Bild-Eingabenunterstützung ausweisen; reine Text-Codex-Modelle schlagen fehl, bevor der Medien-Durchlauf -startet. +`openai-codex/gpt-*`, wenn Bildverständnis über den OpenAI-Codex-OAuth-Provider-Pfad +laufen soll. Verwenden Sie `codex/gpt-*`, wenn Bildverständnis über einen +begrenzten Codex app-server-Turn laufen soll. Das Codex app-server-Modell muss +Unterstützung für Bildeingaben deklarieren; reine Text-Codex-Modelle schlagen +fehl, bevor der Medien-Turn startet. -Verwenden Sie `/status`, um den effektiven Harness für die aktuelle Sitzung zu bestätigen. Wenn die -Auswahl überraschend ist, aktivieren Sie Debug-Logging für das Subsystem `agents/harness` -und prüfen Sie den strukturierten Gateway-Datensatz `agent harness selected`. Er -enthält die ausgewählte Harness-ID, den Auswahlgrund, die Laufzeit-/Fallback-Richtlinie und -im `auto`-Modus das Support-Ergebnis jedes Plugin-Kandidaten. +Verwenden Sie `/status`, um das wirksame Harness für die aktuelle Session zu +bestätigen. Wenn die Auswahl überraschend ist, aktivieren Sie Debug-Logging für +das Subsystem `agents/harness` und prüfen Sie den strukturierten +`agent harness selected`-Eintrag des Gateways. Er enthält die ausgewählte +Harness-ID, den Auswahlgrund, die Runtime-/Fallback-Richtlinie und im Modus +`auto` das Support-Ergebnis jedes Plugin-Kandidaten. ### Was Doctor-Warnungen bedeuten -`openclaw doctor` warnt, wenn all dies zutrifft: +`openclaw doctor` warnt, wenn alle diese Bedingungen zutreffen: - das gebündelte `codex`-Plugin ist aktiviert oder erlaubt - das primäre Modell eines Agents ist `openai-codex/*` -- die effektive Laufzeit dieses Agents ist nicht `codex` +- die wirksame Runtime dieses Agents ist nicht `codex` -Diese Warnung existiert, weil Benutzer oft erwarten, dass „Codex-Plugin aktiviert“ bedeutet: -„native Codex-App-Server-Laufzeit“. OpenClaw zieht diesen Schluss nicht. Die Warnung -bedeutet: +Diese Warnung existiert, weil Benutzer häufig erwarten, dass „Codex-Plugin +aktiviert“ „native Codex app-server-Runtime“ bedeutet. OpenClaw zieht diesen +Schluss nicht. Die Warnung bedeutet: - **Keine Änderung ist erforderlich**, wenn Sie ChatGPT/Codex OAuth über PI beabsichtigt haben. - Ändern Sie das Modell zu `openai/` und setzen Sie - `agentRuntime.id: "codex"`, wenn Sie native App-Server- - Ausführung beabsichtigt haben. -- Bestehende Sitzungen benötigen nach einer Laufzeitänderung weiterhin `/new` oder `/reset`, - weil Sitzungs-Laufzeit-Pins dauerhaft sind. + `agentRuntime.id: "codex"`, wenn Sie native app-server-Ausführung + beabsichtigt haben. +- Bestehende Sessions benötigen nach einer Runtime-Änderung weiterhin `/new` + oder `/reset`, weil Session-Runtime-Pins sticky sind. -Harness-Auswahl ist keine Live-Sitzungssteuerung. Wenn ein eingebetteter Durchlauf läuft, -zeichnet OpenClaw die ausgewählte Harness-ID für diese Sitzung auf und verwendet sie -für spätere Durchläufe in derselben Sitzungs-ID weiter. Ändern Sie die `agentRuntime`-Konfiguration oder -`OPENCLAW_AGENT_RUNTIME`, wenn zukünftige Sitzungen einen anderen Harness verwenden sollen; -verwenden Sie `/new` oder `/reset`, um eine frische Sitzung zu starten, bevor Sie eine bestehende -Unterhaltung zwischen PI und Codex wechseln. Dadurch wird vermieden, ein Transkript durch -zwei inkompatible native Sitzungssysteme wiederzugeben. +Die Harness-Auswahl ist keine Live-Session-Steuerung. Wenn ein eingebetteter +Turn läuft, zeichnet OpenClaw die ausgewählte Harness-ID in dieser Session auf +und verwendet sie für spätere Turns in derselben Session-ID weiter. Ändern Sie +die `agentRuntime`-Konfiguration oder `OPENCLAW_AGENT_RUNTIME`, wenn zukünftige +Sessions ein anderes Harness verwenden sollen; verwenden Sie `/new` oder +`/reset`, um eine frische Session zu starten, bevor Sie eine bestehende +Unterhaltung zwischen PI und Codex umschalten. Dadurch wird vermieden, dass ein +Transcript durch zwei inkompatible native Session-Systeme wiedergegeben wird. -Ältere Sitzungen, die vor Harness-Pins erstellt wurden, werden als PI-gepinnt behandelt, sobald sie -Transkripthistorie haben. Verwenden Sie `/new` oder `/reset`, um diese Unterhaltung nach -einer Konfigurationsänderung für Codex zu aktivieren. +Alte Sessions, die vor Harness-Pins erstellt wurden, werden als PI-gepinnt +behandelt, sobald sie Transcript-Verlauf haben. Verwenden Sie `/new` oder +`/reset`, um diese Unterhaltung nach einer Konfigurationsänderung für Codex zu +aktivieren. -`/status` zeigt die effektiv verwendete Modell-Runtime. Das Standard-Pi-Harness erscheint als -`Runtime: OpenClaw Pi Default`, und das Codex-App-Server-Harness erscheint als +`/status` zeigt die effektive Modelllaufzeit an. Der Standard-PI-Harness erscheint als +`Runtime: OpenClaw Pi Default`, und der Codex-App-Server-Harness erscheint als `Runtime: OpenAI Codex`. ## Anforderungen -- OpenClaw mit verfügbarem, mitgeliefertem `codex`-Plugin. -- Codex-App-Server `0.125.0` oder neuer. Das mitgelieferte Plugin verwaltet standardmäßig eine kompatible - Codex-App-Server-Binärdatei, daher beeinflussen lokale `codex`-Befehle in `PATH` - den normalen Harness-Start nicht. -- Codex-Authentifizierung muss für den App-Server-Prozess oder für OpenClaws Codex-Authentifizierungsbridge - verfügbar sein. Lokale App-Server-Starts verwenden ein von OpenClaw verwaltetes Codex-Home für jeden - Agenten und ein isoliertes untergeordnetes `HOME`, sodass sie standardmäßig nicht Ihr persönliches - `~/.codex`-Konto, Ihre Skills, Plugins, Konfiguration, Thread-Zustände oder nativen +- OpenClaw mit verfügbarem gebündeltem `codex`-Plugin. +- Codex-App-Server `0.125.0` oder neuer. Das gebündelte Plugin verwaltet standardmäßig eine kompatible + Codex-App-Server-Binärdatei, sodass lokale `codex`-Befehle in `PATH` den + normalen Harness-Start nicht beeinflussen. +- Codex-Authentifizierung verfügbar für den App-Server-Prozess oder für OpenClaws Codex-Authentifizierungs- + Bridge. Lokale App-Server-Starts verwenden für jeden + Agent ein von OpenClaw verwaltetes Codex-Home und ein isoliertes untergeordnetes `HOME`, sodass sie standardmäßig nicht Ihr persönliches + `~/.codex`-Konto, Skills, Plugins, Konfiguration, Thread-Status oder native `$HOME/.agents/skills` lesen. -Das Plugin blockiert ältere oder nicht versionierte App-Server-Handshakes. Dadurch bleibt +Das Plugin blockiert ältere oder unversionierte App-Server-Handshakes. Dadurch bleibt OpenClaw auf der Protokolloberfläche, gegen die es getestet wurde. Für Live- und Docker-Smoke-Tests stammt die Authentifizierung üblicherweise aus dem Codex-CLI-Konto -oder einem OpenClaw-Authentifizierungsprofil `openai-codex`. Lokale stdio-App-Server-Starts können -außerdem auf `CODEX_API_KEY` / `OPENAI_API_KEY` zurückfallen, wenn kein Konto vorhanden ist. +oder aus einem OpenClaw-Authentifizierungsprofil `openai-codex`. Lokale stdio-App-Server-Starts können +auch auf `CODEX_API_KEY` / `OPENAI_API_KEY` zurückfallen, wenn kein Konto vorhanden ist. + +## Workspace-Bootstrap-Dateien + +Codex verarbeitet `AGENTS.md` selbst über native Projektdokument-Erkennung. OpenClaw +schreibt keine synthetischen Codex-Projektdokument-Dateien und ist für Persona-Dateien nicht von Codex-Fallback- +Dateinamen abhängig, da Codex-Fallbacks nur gelten, wenn +`AGENTS.md` fehlt. + +Für OpenClaw-Workspace-Parität löst der Codex-Harness die anderen Bootstrap- +Dateien auf (`SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, +`BOOTSTRAP.md` und `MEMORY.md`, wenn vorhanden) und leitet sie über Codex- +Konfigurationsanweisungen bei `thread/start` und `thread/resume` weiter. Dadurch bleiben +`SOUL.md` und verwandter Workspace-Persona-/Profilkontext sichtbar, ohne +`AGENTS.md` zu duplizieren. ## Codex neben anderen Modellen hinzufügen Setzen Sie `agentRuntime.id: "codex"` nicht global, wenn derselbe Agent frei zwischen -Codex- und Nicht-Codex-Provider-Modellen wechseln soll. Eine erzwungene Runtime gilt für jede -eingebettete Runde dieses Agenten oder dieser Sitzung. Wenn Sie ein Anthropic-Modell auswählen, während -diese Runtime erzwungen ist, versucht OpenClaw trotzdem das Codex-Harness und schlägt geschlossen fehl, -anstatt diese Runde stillschweigend über Pi zu routen. +Codex- und Nicht-Codex-Provider-Modellen wechseln soll. Eine erzwungene Laufzeit gilt für jede +eingebettete Runde dieses Agents oder dieser Sitzung. Wenn Sie ein Anthropic-Modell auswählen, während +diese Laufzeit erzwungen ist, versucht OpenClaw weiterhin den Codex-Harness und schlägt geschlossen fehl, +statt diese Runde stillschweigend über PI zu routen. Verwenden Sie stattdessen eine dieser Formen: -- Legen Sie Codex auf einen dedizierten Agenten mit `agentRuntime.id: "codex"`. -- Behalten Sie den Standard-Agenten auf `agentRuntime.id: "auto"` und Pi-Fallback für normale gemischte - Provider-Nutzung bei. -- Verwenden Sie ältere `codex/*`-Referenzen nur aus Kompatibilitätsgründen. Neue Konfigurationen sollten - `openai/*` plus eine explizite Codex-Runtime-Richtlinie bevorzugen. +- Legen Sie Codex auf einen dedizierten Agent mit `agentRuntime.id: "codex"`. +- Belassen Sie den Standard-Agent auf `agentRuntime.id: "auto"` und PI-Fallback für normale gemischte + Provider-Nutzung. +- Verwenden Sie Legacy-Refs `codex/*` nur für Kompatibilität. Neue Konfigurationen sollten + `openai/*` plus eine explizite Codex-Laufzeitrichtlinie bevorzugen. -Dieses Beispiel behält den Standard-Agenten bei normaler automatischer Auswahl und -fügt einen separaten Codex-Agenten hinzu: +Dieses Beispiel belässt den Standard-Agent bei normaler automatischer Auswahl und +fügt einen separaten Codex-Agent hinzu: ```json5 { @@ -322,35 +351,36 @@ fügt einen separaten Codex-Agenten hinzu: Mit dieser Form: -- Der Standard-Agent `main` verwendet den normalen Provider-Pfad und den Pi-Kompatibilitäts-Fallback. -- Der Agent `codex` verwendet das Codex-App-Server-Harness. -- Wenn Codex für den Agenten `codex` fehlt oder nicht unterstützt wird, schlägt die Runde fehl, - anstatt stillschweigend Pi zu verwenden. +- Der standardmäßige `main`-Agent verwendet den normalen Provider-Pfad und den PI-Kompatibilitäts-Fallback. +- Der `codex`-Agent verwendet den Codex-App-Server-Harness. +- Wenn Codex für den `codex`-Agent fehlt oder nicht unterstützt wird, schlägt die Runde fehl, + statt stillschweigend PI zu verwenden. -## Agent-Befehlsrouting +## Routing von Agent-Befehlen -Agenten sollten Benutzeranfragen nach Absicht routen, nicht allein nach dem Wort „Codex“: +Agents sollten Benutzeranfragen nach Absicht routen, nicht allein nach dem Wort „Codex“: | Benutzer fragt nach ... | Agent sollte verwenden ... | | ------------------------------------------------------ | ------------------------------------------------ | | „Diesen Chat an Codex binden“ | `/codex bind` | | „Codex-Thread `` hier fortsetzen“ | `/codex resume ` | | „Codex-Threads anzeigen“ | `/codex threads` | -| „Einen Supportbericht für einen fehlerhaften Codex-Lauf einreichen“ | `/diagnostics [note]` | -| „Nur Codex-Feedback für diesen angehängten Thread senden“ | `/codex diagnostics [note]` | -| „Mein ChatGPT/Codex-Abonnement mit der Codex-Runtime verwenden“ | `openai/*` plus `agentRuntime.id: "codex"` | -| „Mein ChatGPT/Codex-Abonnement über Pi verwenden“ | `openai-codex/*`-Modellreferenzen | +| „Einen Supportbericht für einen fehlerhaften Codex-Lauf erstellen“ | `/diagnostics [note]` | +| „Nur Codex-Feedback für diesen angehängten Thread senden“ | `/codex diagnostics [note]` | +| „Mein ChatGPT/Codex-Abonnement mit der Codex-Laufzeit verwenden“ | `openai/*` plus `agentRuntime.id: "codex"` | +| „Mein ChatGPT/Codex-Abonnement über PI verwenden“ | `openai-codex/*`-Modell-Refs | | „Codex über ACP/acpx ausführen“ | ACP `sessions_spawn({ runtime: "acp", ... })` | -| „Claude Code/Gemini/OpenCode/Cursor in einem Thread starten“ | ACP/acpx, nicht `/codex` und keine nativen Unter-Agenten | +| „Claude Code/Gemini/OpenCode/Cursor in einem Thread starten“ | ACP/acpx, nicht `/codex` und keine nativen Sub-Agents | -OpenClaw bewirbt ACP-Spawn-Anleitungen gegenüber Agenten nur, wenn ACP aktiviert, -dispatchfähig und durch ein geladenes Runtime-Backend gestützt ist. Wenn ACP nicht verfügbar ist, -sollten der System-Prompt und Plugin-Skills dem Agenten kein ACP-Routing beibringen. +OpenClaw bewirbt ACP-Spawn-Anleitungen für Agents nur dann, wenn ACP aktiviert, +dispatchfähig und durch ein geladenes Laufzeit-Backend gestützt ist. Wenn ACP nicht verfügbar ist, +sollten der System-Prompt und Plugin-Skills dem Agent kein ACP- +Routing vermitteln. ## Nur-Codex-Bereitstellungen -Erzwingen Sie das Codex-Harness, wenn Sie nachweisen müssen, dass jede eingebettete Agentenrunde -Codex verwendet. Explizite Plugin-Runtimes verwenden standardmäßig keinen Pi-Fallback, daher ist +Erzwingen Sie den Codex-Harness, wenn Sie nachweisen müssen, dass jede eingebettete Agent-Runde +Codex verwendet. Explizite Plugin-Laufzeiten verwenden standardmäßig keinen PI-Fallback, daher ist `fallback: "none"` optional, aber oft als Dokumentation nützlich: ```json5 @@ -375,12 +405,12 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run Wenn Codex erzwungen ist, schlägt OpenClaw früh fehl, wenn das Codex-Plugin deaktiviert ist, der App-Server zu alt ist oder der App-Server nicht starten kann. Setzen Sie -`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` nur, wenn Sie absichtlich möchten, dass Pi eine -fehlende Harness-Auswahl behandelt. +`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` nur, wenn Sie PI absichtlich fehlende +Harness-Auswahl behandeln lassen möchten. ## Codex pro Agent -Sie können einen Agenten ausschließlich auf Codex festlegen, während der Standard-Agent die normale +Sie können einen Agent ausschließlich für Codex konfigurieren, während der Standard-Agent die normale automatische Auswahl beibehält: ```json5 @@ -412,15 +442,15 @@ automatische Auswahl beibehält: } ``` -Verwenden Sie normale Sitzungsbefehle, um zwischen Agenten und Modellen zu wechseln. `/new` erstellt eine neue -OpenClaw-Sitzung, und das Codex-Harness erstellt oder setzt seinen Sidecar-App-Server-Thread -bei Bedarf fort. `/reset` löscht die OpenClaw-Sitzungsbindung für diesen Thread -und lässt die nächste Runde das Harness wieder aus der aktuellen Konfiguration auflösen. +Verwenden Sie normale Sitzungsbefehle, um Agents und Modelle zu wechseln. `/new` erstellt eine neue +OpenClaw-Sitzung, und der Codex-Harness erstellt oder setzt seinen Sidecar-App-Server- +Thread bei Bedarf fort. `/reset` löscht die OpenClaw-Sitzungsbindung für diesen Thread +und lässt die nächste Runde den Harness erneut aus der aktuellen Konfiguration auflösen. ## Modellerkennung -Standardmäßig fragt das Codex-Plugin den App-Server nach verfügbaren Modellen. Wenn -die Erkennung fehlschlägt oder eine Zeitüberschreitung auftritt, verwendet es einen mitgelieferten Fallback-Katalog für: +Standardmäßig fragt das Codex-Plugin den App-Server nach verfügbaren Modellen. Wenn die +Erkennung fehlschlägt oder eine Zeitüberschreitung auftritt, verwendet es einen gebündelten Fallback-Katalog für: - GPT-5.5 - GPT-5.4 mini @@ -446,7 +476,7 @@ Sie können die Erkennung unter `plugins.entries.codex.config.discovery` anpasse } ``` -Deaktivieren Sie die Erkennung, wenn der Start Codex nicht abfragen und beim +Deaktivieren Sie die Erkennung, wenn der Start Codex nicht prüfen und beim Fallback-Katalog bleiben soll: ```json5 @@ -475,17 +505,17 @@ codex app-server --listen stdio:// ``` Die verwaltete Binärdatei wird mit dem `codex`-Plugin-Paket ausgeliefert. Dadurch bleibt die -App-Server-Version an das mitgelieferte Plugin gebunden statt an die separate -Codex-CLI, die zufällig lokal installiert ist. Setzen Sie `appServer.command` nur, wenn +App-Server-Version an das gebündelte Plugin gebunden, statt an die separat installierte +Codex CLI, die zufällig lokal installiert ist. Setzen Sie `appServer.command` nur, wenn Sie absichtlich eine andere ausführbare Datei ausführen möchten. Standardmäßig startet OpenClaw lokale Codex-Harness-Sitzungen im YOLO-Modus: `approvalPolicy: "never"`, `approvalsReviewer: "user"` und -`sandbox: "danger-full-access"`. Dies ist die vertrauenswürdige lokale Operator-Haltung, die +`sandbox: "danger-full-access"`. Dies ist die vertrauensvolle lokale Operator-Haltung, die für autonome Heartbeats verwendet wird: Codex kann Shell- und Netzwerktools verwenden, ohne -bei nativen Genehmigungsaufforderungen anzuhalten, auf die niemand antworten kann. +bei nativen Genehmigungsaufforderungen anzuhalten, die niemand beantworten kann. -Um Genehmigungen mit Codex-Guardian-Prüfung zu aktivieren, setzen Sie `appServer.mode: +Um Codex-Guardian-geprüfte Genehmigungen zu aktivieren, setzen Sie `appServer.mode: "guardian"`: ```json5 @@ -506,18 +536,18 @@ Um Genehmigungen mit Codex-Guardian-Prüfung zu aktivieren, setzen Sie `appServe } ``` -Der Guardian-Modus verwendet Codex’ nativen Auto-Review-Genehmigungspfad. Wenn Codex darum bittet, -die Sandbox zu verlassen, außerhalb des Arbeitsbereichs zu schreiben oder Berechtigungen wie Netzwerkzugriff -hinzuzufügen, leitet Codex diese Genehmigungsanfrage an den nativen Prüfer statt an eine -menschliche Eingabeaufforderung weiter. Der Prüfer wendet Codex’ Risiko-Framework an und genehmigt oder verweigert -die konkrete Anfrage. Verwenden Sie Guardian, wenn Sie mehr Schutzmechanismen als im YOLO-Modus möchten, -aber weiterhin benötigen, dass unbeaufsichtigte Agenten Fortschritte machen. +Der Guardian-Modus verwendet Codex' nativen Auto-Review-Genehmigungspfad. Wenn Codex anfordert, +die Sandbox zu verlassen, außerhalb des Workspaces zu schreiben oder Berechtigungen wie Netzwerk- +Zugriff hinzuzufügen, leitet Codex diese Genehmigungsanforderung an den nativen Prüfer weiter statt an eine +menschliche Aufforderung. Der Prüfer wendet Codex' Risikorahmen an und genehmigt oder verweigert +die konkrete Anfrage. Verwenden Sie Guardian, wenn Sie mehr Leitplanken als im YOLO-Modus wünschen, +aber unbeaufsichtigte Agents trotzdem Fortschritt erzielen sollen. -Die Voreinstellung `guardian` wird zu `approvalPolicy: "on-request"`, -`approvalsReviewer: "auto_review"` und `sandbox: "workspace-write"` erweitert. -Einzelne Richtlinienfelder überschreiben `mode` weiterhin, sodass fortgeschrittene Bereitstellungen -die Voreinstellung mit expliziten Entscheidungen mischen können. Der ältere Prüferwert `guardian_subagent` wird -weiterhin als Kompatibilitätsalias akzeptiert, neue Konfigurationen sollten jedoch +Die Voreinstellung `guardian` erweitert sich zu `approvalPolicy: "on-request"`, +`approvalsReviewer: "auto_review"` und `sandbox: "workspace-write"`. +Einzelne Richtlinienfelder überschreiben `mode` weiterhin, sodass erweiterte Bereitstellungen die +Voreinstellung mit expliziten Auswahlmöglichkeiten mischen können. Der ältere Prüferwert `guardian_subagent` wird +weiterhin als Kompatibilitätsalias akzeptiert, aber neue Konfigurationen sollten `auto_review` verwenden. Für einen bereits laufenden App-Server verwenden Sie WebSocket-Transport: @@ -543,17 +573,17 @@ Für einen bereits laufenden App-Server verwenden Sie WebSocket-Transport: ``` Stdio-App-Server-Starts erben standardmäßig OpenClaws Prozessumgebung, -aber OpenClaw besitzt die Codex-App-Server-Kontobridge und setzt sowohl -`CODEX_HOME` als auch `HOME` auf agentenspezifische Verzeichnisse unter dem OpenClaw-Zustand -dieses Agenten. Codex’ eigener Skill-Loader liest `$CODEX_HOME/skills` und -`$HOME/.agents/skills`, daher sind beide Werte für lokale App-Server-Starts -isoliert. Dadurch bleiben Codex-native Skills, Plugins, Konfiguration, Konten und Thread-Zustand -auf den OpenClaw-Agenten beschränkt, statt aus dem persönlichen Codex-CLI-Home -des Operators einzusickern. +aber OpenClaw verwaltet die Codex-App-Server-Konto-Bridge und setzt sowohl +`CODEX_HOME` als auch `HOME` auf Agent-spezifische Verzeichnisse unter dem OpenClaw- +Status dieses Agents. Codex' eigener Skill-Loader liest `$CODEX_HOME/skills` und +`$HOME/.agents/skills`, sodass beide Werte für lokale App-Server- +Starts isoliert sind. Dadurch bleiben Codex-native Skills, Plugins, Konfiguration, Konten und Thread- +Status auf den OpenClaw-Agent beschränkt, statt aus dem persönlichen Codex-CLI-Home des Operators +einzusickern. OpenClaw-Plugins und OpenClaw-Skill-Snapshots fließen weiterhin durch OpenClaws eigene Plugin-Registry und den Skill-Loader. Persönliche Codex-CLI-Assets tun das nicht. Wenn Sie -nützliche Codex-CLI-Skills oder Plugins haben, die Teil eines OpenClaw-Agenten werden sollen, +nützliche Codex-CLI-Skills oder Plugins haben, die Teil eines OpenClaw-Agents werden sollen, inventarisieren Sie sie explizit: ```bash @@ -561,29 +591,29 @@ openclaw migrate codex --dry-run openclaw migrate apply codex --yes ``` -Der Codex-Migrations-Provider kopiert Skills in den aktuellen OpenClaw-Agentenarbeitsbereich. -Codex-native Plugins, Hooks und Konfigurationsdateien werden zur manuellen Prüfung gemeldet oder archiviert, -anstatt automatisch aktiviert zu werden, weil sie Befehle ausführen, -MCP-Server freigeben oder Zugangsdaten enthalten können. +Der Codex-Migrations-Provider kopiert Skills in den aktuellen OpenClaw-Agent- +Workspace. Codex-native Plugins, Hooks und Konfigurationsdateien werden gemeldet oder archiviert, +damit sie manuell geprüft werden können, statt automatisch aktiviert zu werden, da sie +Befehle ausführen, MCP-Server verfügbar machen oder Anmeldedaten enthalten können. Die Authentifizierung wird in dieser Reihenfolge ausgewählt: -1. Ein explizites OpenClaw-Codex-Authentifizierungsprofil für den Agenten. -2. Das bestehende Konto des App-Servers im Codex-Home dieses Agenten. +1. Ein explizites OpenClaw-Codex-Authentifizierungsprofil für den Agent. +2. Das vorhandene Konto des App-Servers im Codex-Home dieses Agents. 3. Nur für lokale stdio-App-Server-Starts: `CODEX_API_KEY`, dann `OPENAI_API_KEY`, wenn kein App-Server-Konto vorhanden ist und OpenAI-Authentifizierung weiterhin erforderlich ist. -Wenn OpenClaw ein Codex-Authentifizierungsprofil im Stil eines ChatGPT-Abonnements sieht, entfernt es +Wenn OpenClaw ein Codex-Authentifizierungsprofil im Stil eines ChatGPT-Abonnements erkennt, entfernt es `CODEX_API_KEY` und `OPENAI_API_KEY` aus dem erzeugten untergeordneten Codex-Prozess. Dadurch bleiben API-Schlüssel auf Gateway-Ebene für Embeddings oder direkte OpenAI-Modelle verfügbar, ohne dass native Codex-App-Server-Runden versehentlich über die API abgerechnet werden. -Explizite Codex-API-Schlüsselprofile und lokaler stdio-Env-Key-Fallback verwenden App-Server-Login -statt geerbter Env des untergeordneten Prozesses. WebSocket-App-Server-Verbindungen +Explizite Codex-API-Schlüsselprofile und lokale stdio-Env-Key-Fallbacks verwenden den App-Server- +Login statt geerbter Umgebungsvariablen des untergeordneten Prozesses. WebSocket-App-Server-Verbindungen erhalten keinen Gateway-Env-API-Schlüssel-Fallback; verwenden Sie ein explizites Authentifizierungsprofil oder das -eigene Konto des entfernten App-Servers. +eigene Konto des Remote-App-Servers. -Wenn eine Bereitstellung zusätzliche Umgebungsisolierung benötigt, fügen Sie diese Variablen zu +Wenn eine Bereitstellung zusätzliche Umgebungsisolation benötigt, fügen Sie diese Variablen zu `appServer.clearEnv` hinzu: ```json5 @@ -603,54 +633,54 @@ Wenn eine Bereitstellung zusätzliche Umgebungsisolierung benötigt, fügen Sie } ``` -`appServer.clearEnv` wirkt sich nur auf den erzeugten untergeordneten Codex-App-Server-Prozess aus. +`appServer.clearEnv` betrifft nur den erzeugten untergeordneten Codex-App-Server-Prozess. -Codex-Dynamic-Tools verwenden standardmäßig das Profil `native-first`. In diesem Modus -stellt OpenClaw keine Dynamic-Tools bereit, die Codex-native Arbeitsbereichsoperationen duplizieren: -`read`, `write`, `edit`, `apply_patch`, `exec`, `process` und +Codex Dynamic Tools verwenden standardmäßig das Profil `native-first`. In diesem Modus stellt +OpenClaw keine Dynamic Tools bereit, die native Codex-Arbeitsbereichsvorgänge +duplizieren: `read`, `write`, `edit`, `apply_patch`, `exec`, `process` und `update_plan`. OpenClaw-Integrationstools wie Messaging, Sitzungen, Medien, Cron, Browser, Nodes, Gateway, `heartbeat_respond` und `web_search` bleiben verfügbar. Unterstützte Codex-Plugin-Felder auf oberster Ebene: -| Feld | Standard | Bedeutung | -| -------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------ | -| `codexDynamicToolsProfile` | `"native-first"` | Verwenden Sie `"openclaw-compat"`, um den vollständigen dynamischen OpenClaw-Tool-Satz für den Codex app-server bereitzustellen. | -| `codexDynamicToolsExclude` | `[]` | Zusätzliche Namen dynamischer OpenClaw-Tools, die in Codex app-server-Turns ausgelassen werden. | +| Feld | Standard | Bedeutung | +| -------------------------- | ---------------- | -------------------------------------------------------------------------------------------------- | +| `codexDynamicToolsProfile` | `"native-first"` | Verwenden Sie `"openclaw-compat"`, um Codex App-Server den vollständigen OpenClaw-Dynamic-Tool-Satz bereitzustellen. | +| `codexDynamicToolsExclude` | `[]` | Zusätzliche OpenClaw-Dynamic-Tool-Namen, die in Codex-App-Server-Turns ausgelassen werden sollen. | Unterstützte `appServer`-Felder: -| Feld | Standard | Bedeutung | -| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` startet Codex; `"websocket"` verbindet sich mit `url`. | -| `command` | verwaltetes Codex-Binary | Ausführbare Datei für den stdio-Transport. Nicht setzen, um das verwaltete Binary zu verwenden; nur für eine explizite Überschreibung setzen. | -| `args` | `["app-server", "--listen", "stdio://"]` | Argumente für den stdio-Transport. | -| `url` | nicht gesetzt | WebSocket-URL des app-server. | -| `authToken` | nicht gesetzt | Bearer-Token für den WebSocket-Transport. | -| `headers` | `{}` | Zusätzliche WebSocket-Header. | -| `clearEnv` | `[]` | Zusätzliche Namen von Umgebungsvariablen, die aus dem gestarteten stdio-app-server-Prozess entfernt werden, nachdem OpenClaw seine geerbte Umgebung erstellt hat. `CODEX_HOME` und `HOME` sind für die Codex-Isolation pro Agent von OpenClaw bei lokalen Starts reserviert. | -| `requestTimeoutMs` | `60000` | Zeitlimit für app-server-Control-Plane-Aufrufe. | -| `mode` | `"yolo"` | Voreinstellung für YOLO- oder Guardian-geprüfte Ausführung. | -| `approvalPolicy` | `"never"` | Native Codex-Genehmigungsrichtlinie, die an Thread-Start/Fortsetzen/Turn gesendet wird. | -| `sandbox` | `"danger-full-access"` | Nativer Codex-Sandbox-Modus, der an Thread-Start/Fortsetzen gesendet wird. | -| `approvalsReviewer` | `"user"` | Verwenden Sie `"auto_review"`, damit Codex native Genehmigungsaufforderungen prüft. `guardian_subagent` bleibt ein Legacy-Alias. | -| `serviceTier` | nicht gesetzt | Optionale Codex app-server-Service-Stufe: `"fast"`, `"flex"` oder `null`. Ungültige Legacy-Werte werden ignoriert. | +| Feld | Standard | Bedeutung | +| ------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `transport` | `"stdio"` | `"stdio"` erzeugt Codex; `"websocket"` verbindet sich mit `url`. | +| `command` | verwaltetes Codex-Binärprogramm | Ausführbare Datei für den stdio-Transport. Lassen Sie dies nicht gesetzt, um das verwaltete Binärprogramm zu verwenden; setzen Sie es nur für eine ausdrückliche Überschreibung. | +| `args` | `["app-server", "--listen", "stdio://"]` | Argumente für den stdio-Transport. | +| `url` | nicht gesetzt | WebSocket-URL des App-Servers. | +| `authToken` | nicht gesetzt | Bearer-Token für den WebSocket-Transport. | +| `headers` | `{}` | Zusätzliche WebSocket-Header. | +| `clearEnv` | `[]` | Zusätzliche Namen von Umgebungsvariablen, die aus dem erzeugten stdio-App-Server-Prozess entfernt werden, nachdem OpenClaw seine geerbte Umgebung aufgebaut hat. `CODEX_HOME` und `HOME` sind für die Codex-Isolation pro Agent von OpenClaw bei lokalen Starts reserviert. | +| `requestTimeoutMs` | `60000` | Timeout für App-Server-Control-Plane-Aufrufe. | +| `mode` | `"yolo"` | Voreinstellung für YOLO- oder durch Guardian geprüfte Ausführung. | +| `approvalPolicy` | `"never"` | Native Codex-Genehmigungsrichtlinie, die an Thread-Start/Fortsetzung/Turn gesendet wird. | +| `sandbox` | `"danger-full-access"` | Nativer Codex-Sandbox-Modus, der an Thread-Start/Fortsetzung gesendet wird. | +| `approvalsReviewer` | `"user"` | Verwenden Sie `"auto_review"`, damit Codex native Genehmigungs-Prompts prüft. `guardian_subagent` bleibt ein Legacy-Alias. | +| `serviceTier` | nicht gesetzt | Optionale Codex-App-Server-Service-Stufe: `"fast"`, `"flex"` oder `null`. Ungültige Legacy-Werte werden ignoriert. | -Dynamische Tool-Aufrufe im Besitz von OpenClaw werden unabhängig von +OpenClaw-eigene Dynamic-Tool-Aufrufe werden unabhängig von `appServer.requestTimeoutMs` begrenzt: Jede Codex-`item/tool/call`-Anfrage muss -innerhalb von 30 Sekunden eine OpenClaw-Antwort erhalten. Bei einem Timeout -bricht OpenClaw das Tool-Signal ab, sofern unterstützt, und gibt eine -fehlgeschlagene dynamische Tool-Antwort an Codex zurück, damit der Turn -fortgesetzt werden kann, statt die Sitzung in `processing` zu belassen. +innerhalb von 30 Sekunden eine OpenClaw-Antwort erhalten. Bei einem Timeout bricht +OpenClaw das Tool-Signal ab, sofern unterstützt, und gibt eine fehlgeschlagene +Dynamic-Tool-Antwort an Codex zurück, damit der Turn fortgesetzt werden kann, +anstatt die Sitzung in `processing` zu belassen. -Nachdem OpenClaw auf eine auf einen Codex-Turn bezogene app-server-Anfrage +Nachdem OpenClaw auf eine Codex-App-Server-Anfrage mit Turn-Geltungsbereich geantwortet hat, erwartet das Harness außerdem, dass Codex den nativen Turn mit -`turn/completed` abschließt. Wenn der app-server nach dieser Antwort 60 Sekunden -lang still bleibt, unterbricht OpenClaw nach bestem Bemühen den Codex-Turn, -zeichnet ein diagnostisches Timeout auf und gibt die OpenClaw-Sitzungsspur frei, -damit nachfolgende Chat-Nachrichten nicht hinter einem veralteten nativen Turn -in die Warteschlange gestellt werden. +`turn/completed` abschließt. Wenn der App-Server nach dieser Antwort 60 Sekunden +lang still bleibt, unterbricht OpenClaw nach bestem Ermessen den Codex-Turn, +zeichnet einen diagnostischen Timeout auf und gibt die OpenClaw-Sitzungsspur frei, +damit nachfolgende Chatnachrichten nicht hinter einem veralteten nativen Turn +eingereiht werden. Umgebungsüberschreibungen bleiben für lokale Tests verfügbar: @@ -660,29 +690,29 @@ Umgebungsüberschreibungen bleiben für lokale Tests verfügbar: - `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY` - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` -`OPENCLAW_CODEX_APP_SERVER_BIN` umgeht das verwaltete Binary, wenn +`OPENCLAW_CODEX_APP_SERVER_BIN` umgeht das verwaltete Binärprogramm, wenn `appServer.command` nicht gesetzt ist. `OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` wurde entfernt. Verwenden Sie stattdessen `plugins.entries.codex.config.appServer.mode: "guardian"` oder -`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` für einmalige lokale Tests. Konfiguration -wird für wiederholbare Bereitstellungen bevorzugt, weil sie das Plugin-Verhalten -in derselben geprüften Datei wie den Rest der Codex-Harness-Einrichtung hält. +`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` für einmalige lokale Tests. Die Konfiguration +wird für reproduzierbare Bereitstellungen bevorzugt, weil sie das Plugin-Verhalten +in derselben geprüften Datei hält wie die restliche Einrichtung des Codex-Harness. ## Computer Use -Computer Use wird in einer eigenen Einrichtungsanleitung behandelt: +Computer Use wird in einem eigenen Einrichtungsleitfaden behandelt: [Codex Computer Use](/de/plugins/codex-computer-use). -Die Kurzfassung: OpenClaw liefert die Desktop-Control-App nicht mit und führt -selbst keine Desktop-Aktionen aus. Es bereitet Codex app-server vor, überprüft, -dass der MCP-Server `computer-use` verfügbar ist, und überlässt Codex dann die -nativen MCP-Tool-Aufrufe während Turns im Codex-Modus. +Die Kurzfassung: OpenClaw bündelt die Desktop-Steuerungs-App nicht und führt +Desktop-Aktionen nicht selbst aus. Es bereitet Codex App-Server vor, prüft, dass der +`computer-use`-MCP-Server verfügbar ist, und lässt Codex dann die nativen +MCP-Tool-Aufrufe während Turns im Codex-Modus verarbeiten. -Für direkten TryCua-Treiberzugriff außerhalb des Codex-Marketplace-Ablaufs -registrieren Sie `cua-driver mcp` mit `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'`. -Siehe [Codex Computer Use](/de/plugins/codex-computer-use) zur Unterscheidung -zwischen Computer Use im Besitz von Codex und direkter MCP-Registrierung. +Für direkten TryCua-Treiberzugriff außerhalb des Codex-Marketplace-Ablaufs registrieren Sie +`cua-driver mcp` mit `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'`. +Siehe [Codex Computer Use](/de/plugins/codex-computer-use) für den Unterschied +zwischen Codex-eigener Computer Use und direkter MCP-Registrierung. Minimale Konfiguration: @@ -719,25 +749,23 @@ Die Einrichtung kann über die Befehlsoberfläche geprüft oder installiert werd - `/codex computer-use install --source ` - `/codex computer-use install --marketplace-path ` -Computer Use ist macOS-spezifisch und kann lokale Betriebssystemberechtigungen -erfordern, bevor der Codex-MCP-Server Apps steuern kann. Wenn -`computerUse.enabled` true ist und der MCP-Server nicht verfügbar ist, schlagen -Turns im Codex-Modus fehl, bevor der Thread startet, statt stillschweigend ohne -die nativen Computer-Use-Tools zu laufen. Siehe -[Codex Computer Use](/de/plugins/codex-computer-use) für Marketplace-Optionen, -Remote-Kataloggrenzen, Statusgründe und Fehlerbehebung. +Computer Use ist macOS-spezifisch und kann lokale OS-Berechtigungen erfordern, +bevor der Codex-MCP-Server Apps steuern kann. Wenn `computerUse.enabled` true ist +und der MCP-Server nicht verfügbar ist, schlagen Turns im Codex-Modus fehl, bevor +der Thread startet, anstatt stillschweigend ohne die nativen Computer-Use-Tools zu +laufen. Siehe [Codex Computer Use](/de/plugins/codex-computer-use) für Marketplace-Optionen, +Remote-Katalogbeschränkungen, Statusgründe und Fehlerbehebung. -Wenn `computerUse.autoInstall` true ist, kann OpenClaw den standardmäßig -gebündelten Codex-Desktop-Marketplace aus -`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` registrieren, -falls Codex noch keinen lokalen Marketplace gefunden hat. Verwenden Sie `/new` -oder `/reset`, nachdem Sie Laufzeit- oder Computer-Use-Konfiguration geändert -haben, damit vorhandene Sitzungen keine alte PI- oder Codex-Thread-Bindung -beibehalten. +Wenn `computerUse.autoInstall` true ist, kann OpenClaw den standardmäßig gebündelten +Codex Desktop-Marketplace aus +`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` registrieren, falls Codex +noch keinen lokalen Marketplace gefunden hat. Verwenden Sie `/new` oder `/reset`, nachdem +Sie die Runtime- oder Computer-Use-Konfiguration geändert haben, damit bestehende Sitzungen +keine alte PI- oder Codex-Thread-Bindung behalten. ## Häufige Rezepte -Lokaler Codex mit standardmäßigem stdio-Transport: +Lokaler Codex mit Standard-stdio-Transport: ```json5 { @@ -751,7 +779,7 @@ Lokaler Codex mit standardmäßigem stdio-Transport: } ``` -Codex-only-Harness-Validierung: +Nur-Codex-Harness-Validierung: ```json5 { @@ -773,7 +801,7 @@ Codex-only-Harness-Validierung: } ``` -Guardian-geprüfte Codex-Genehmigungen: +Durch Guardian geprüfte Codex-Genehmigungen: ```json5 { @@ -795,7 +823,7 @@ Guardian-geprüfte Codex-Genehmigungen: } ``` -Remote-app-server mit expliziten Headern: +Remote-App-Server mit expliziten Headern: ```json5 { @@ -818,12 +846,11 @@ Remote-app-server mit expliziten Headern: } ``` -Modellwechsel bleiben OpenClaw-gesteuert. Wenn eine OpenClaw-Sitzung an einen -vorhandenen Codex-Thread angehängt ist, sendet der nächste Turn das aktuell -ausgewählte OpenAI-Modell, den Provider, die Genehmigungsrichtlinie, die Sandbox -und die Service-Stufe erneut an den app-server. Der Wechsel von `openai/gpt-5.5` -zu `openai/gpt-5.2` behält die Thread-Bindung bei, weist Codex aber an, mit dem -neu ausgewählten Modell fortzufahren. +Der Modellwechsel bleibt OpenClaw-gesteuert. Wenn eine OpenClaw-Sitzung an +einen bestehenden Codex-Thread angehängt ist, sendet der nächste Turn das aktuell ausgewählte +OpenAI-Modell, den Provider, die Genehmigungsrichtlinie, die Sandbox und die Service-Stufe +erneut an den App-Server. Der Wechsel von `openai/gpt-5.5` zu `openai/gpt-5.2` behält die +Thread-Bindung bei, fordert Codex aber auf, mit dem neu ausgewählten Modell fortzufahren. ## Codex-Befehl @@ -832,75 +859,74 @@ generisch und funktioniert in jedem Kanal, der OpenClaw-Textbefehle unterstützt Häufige Formen: -- `/codex status` zeigt Live-Konnektivität des app-server, Modelle, Konto, Ratenlimits, MCP-Server und Skills. -- `/codex models` listet Live-Modelle des Codex app-server auf. +- `/codex status` zeigt Live-App-Server-Konnektivität, Modelle, Konto, Rate Limits, MCP-Server und Skills. +- `/codex models` listet Live-Codex-App-Server-Modelle auf. - `/codex threads [filter]` listet aktuelle Codex-Threads auf. -- `/codex resume ` hängt die aktuelle OpenClaw-Sitzung an einen vorhandenen Codex-Thread an. -- `/codex compact` fordert Codex app-server auf, den angehängten Thread zu komprimieren. +- `/codex resume ` hängt die aktuelle OpenClaw-Sitzung an einen bestehenden Codex-Thread an. +- `/codex compact` fordert den Codex-App-Server auf, den angehängten Thread zu verdichten. - `/codex review` startet die native Codex-Prüfung für den angehängten Thread. -- `/codex diagnostics [note]` fragt nach, bevor Codex-Diagnosefeedback für den angehängten Thread gesendet wird. -- `/codex computer-use status` prüft das konfigurierte Computer-Use-Plugin und den MCP-Server. -- `/codex computer-use install` installiert das konfigurierte Computer-Use-Plugin und lädt MCP-Server neu. -- `/codex account` zeigt Konto- und Ratenlimitstatus. -- `/codex mcp` listet den MCP-Serverstatus des Codex app-server auf. -- `/codex skills` listet Skills des Codex app-server auf. +- `/codex diagnostics [note]` fragt vor dem Senden von Codex-Diagnosefeedback für den angehängten Thread nach. +- `/codex computer-use status` prüft das konfigurierte Computer Use-Plugin und den MCP-Server. +- `/codex computer-use install` installiert das konfigurierte Computer Use-Plugin und lädt MCP-Server neu. +- `/codex account` zeigt Konto- und Rate-Limit-Status an. +- `/codex mcp` listet den MCP-Serverstatus des Codex-App-Servers auf. +- `/codex skills` listet die Skills des Codex-App-Servers auf. ### Häufiger Debugging-Ablauf -Wenn ein Codex-gestützter Agent in Telegram, Discord, Slack +Wenn ein Codex-gestützter Agent in Telegram, Discord, Slack, oder einem anderen Kanal etwas Unerwartetes tut, beginnen Sie mit der Unterhaltung, in der das Problem aufgetreten ist: 1. Führen Sie `/diagnostics bad tool choice after image upload` oder eine andere kurze Notiz aus, die beschreibt, was Sie gesehen haben. 2. Genehmigen Sie die Diagnoseanfrage einmal. Die Genehmigung erstellt die lokale Gateway- - Diagnose-ZIP-Datei und sendet, da die Sitzung das Codex-Harness verwendet, außerdem + Diagnose-ZIP-Datei und sendet, weil die Sitzung das Codex-Harness verwendet, außerdem das relevante Codex-Feedback-Bundle an OpenAI-Server. 3. Kopieren Sie die abgeschlossene Diagnoseantwort in den Fehlerbericht oder Support-Thread. - Sie enthält den lokalen Bundle-Pfad, die Datenschutzzusammenfassung, OpenClaw-Sitzungs-IDs, - Codex-Thread-IDs und für jeden Codex-Thread eine `Inspect locally`-Zeile. -4. Wenn Sie den Lauf selbst debuggen möchten, führen Sie den ausgegebenen `Inspect locally`- - Befehl in einem Terminal aus. Er sieht wie `codex resume ` aus und öffnet den + Sie enthält den lokalen Bundle-Pfad, die Datenschutz-Zusammenfassung, OpenClaw-Sitzungs-IDs, + Codex-Thread-IDs und eine `Inspect locally`-Zeile für jeden Codex-Thread. +4. Wenn Sie den Lauf selbst debuggen möchten, führen Sie den ausgegebenen Befehl `Inspect locally` + in einem Terminal aus. Er sieht wie `codex resume ` aus und öffnet den nativen Codex-Thread, sodass Sie die Unterhaltung prüfen, lokal fortsetzen oder Codex fragen können, warum es ein bestimmtes Tool oder einen bestimmten Plan gewählt hat. Verwenden Sie `/codex diagnostics [note]` nur, wenn Sie ausdrücklich den Codex- -Feedback-Upload für den derzeit angehängten Thread ohne das vollständige OpenClaw- +Feedback-Upload für den aktuell angehängten Thread ohne das vollständige OpenClaw- Gateway-Diagnose-Bundle möchten. Für die meisten Support-Berichte ist `/diagnostics [note]` -der bessere Ausgangspunkt, weil es den lokalen Gateway-Status und die Codex- +der bessere Ausgangspunkt, weil es den lokalen Gateway-Zustand und Codex- Thread-IDs in einer Antwort zusammenführt. Siehe [Diagnoseexport](/de/gateway/diagnostics) für das vollständige Datenschutzmodell und das Verhalten in Gruppenchats. -Der Kern von OpenClaw stellt außerdem das nur für Owner bestimmte `/diagnostics [note]` -als allgemeinen Gateway-Diagnosebefehl bereit. Die Genehmigungsaufforderung zeigt den -Vorspann zu sensiblen Daten, verlinkt auf [Diagnoseexport](/de/gateway/diagnostics) und fordert -`openclaw gateway diagnostics export --json` jedes Mal über eine ausdrückliche Exec-Genehmigung -an. Genehmigen Sie Diagnosen nicht mit einer Allow-all-Regel. Nach der Genehmigung sendet -OpenClaw einen einfügbaren Bericht mit dem lokalen Bundle-Pfad und einer Manifest- +Der OpenClaw-Kern stellt außerdem das nur für Besitzer verfügbare `/diagnostics [note]` als allgemeinen +Gateway-Diagnosebefehl bereit. Die Genehmigungsaufforderung zeigt die Einleitung zu sensiblen Daten, +verlinkt auf [Diagnoseexport](/de/gateway/diagnostics) und fordert +`openclaw gateway diagnostics export --json` jedes Mal über eine ausdrückliche Ausführungsgenehmigung an. +Genehmigen Sie Diagnosen nicht mit einer Alles-erlauben-Regel. Nach der Genehmigung +sendet OpenClaw einen einfügbaren Bericht mit dem lokalen Bundle-Pfad und einer Manifest- Zusammenfassung. Wenn die aktive OpenClaw-Sitzung das Codex-Harness verwendet, autorisiert -dieselbe Genehmigung auch das Senden der relevanten Codex-Feedback-Bundles an OpenAI- -Server. Die Genehmigungsaufforderung sagt, dass Codex-Feedback gesendet wird, listet aber -vor der Genehmigung keine Codex-Sitzungs- oder Thread-IDs auf. +dieselbe Genehmigung auch das Senden der relevanten Codex-Feedback-Bundles an +OpenAI-Server. Die Genehmigungsaufforderung sagt, dass Codex-Feedback gesendet wird, +listet aber vor der Genehmigung keine Codex-Sitzungs- oder Thread-IDs auf. -Wenn `/diagnostics` von einem Owner in einem Gruppenchat aufgerufen wird, hält OpenClaw den -gemeinsamen Kanal sauber: Die Gruppe erhält nur einen kurzen Hinweis, während der -Diagnosevorspann, die Genehmigungsaufforderungen und die Codex-Sitzungs-/Thread-IDs über -die private Genehmigungsroute an den Owner gesendet werden. Wenn es keine private Owner- -Route gibt, lehnt OpenClaw die Gruppenanfrage ab und bittet den Owner, sie aus einer DM -auszuführen. +Wenn `/diagnostics` von einem Besitzer in einem Gruppenchat aufgerufen wird, hält OpenClaw den +gemeinsamen Kanal sauber: Die Gruppe erhält nur einen kurzen Hinweis, während die +Diagnoseeinleitung, Genehmigungsaufforderungen und Codex-Sitzungs-/Thread-IDs über +die private Genehmigungsroute an den Besitzer gesendet werden. Wenn es keine private Besitzerroute gibt, +lehnt OpenClaw die Gruppenanfrage ab und bittet den Besitzer, sie aus einer Direktnachricht auszuführen. -Der genehmigte Codex-Upload ruft `feedback/upload` des Codex-App-Servers auf und bittet -den App-Server, Protokolle für jeden aufgeführten Thread und erzeugte Codex-Unterthreads -einzuschließen, sofern verfügbar. Der Upload läuft über Codex' normalen Feedback-Pfad zu -OpenAI-Servern; wenn Codex-Feedback in diesem App-Server deaktiviert ist, gibt der Befehl +Der genehmigte Codex-Upload ruft `feedback/upload` des Codex-App-Servers auf und fordert +den App-Server auf, Logs für jeden aufgeführten Thread und erzeugte Codex-Subthreads +einzuschließen, sofern verfügbar. Der Upload läuft über den normalen Codex-Feedbackpfad zu OpenAI- +Servern; wenn Codex-Feedback in diesem App-Server deaktiviert ist, gibt der Befehl den App-Server-Fehler zurück. Die abgeschlossene Diagnoseantwort listet die Kanäle, -OpenClaw-Sitzungs-IDs, Codex-Thread-IDs und lokalen `codex resume `-Befehle für -die gesendeten Threads auf. Wenn Sie die Genehmigung ablehnen oder ignorieren, gibt -OpenClaw diese Codex-IDs nicht aus. Dieser Upload ersetzt nicht den lokalen Gateway- -Diagnoseexport. +OpenClaw-Sitzungs-IDs, Codex-Thread-IDs und lokalen `codex resume `- +Befehle für die gesendeten Threads auf. Wenn Sie die Genehmigung ablehnen oder ignorieren, +gibt OpenClaw diese Codex-IDs nicht aus. Dieser Upload ersetzt nicht den lokalen +Gateway-Diagnoseexport. -`/codex resume` schreibt dieselbe Sidecar-Bindungsdatei, die das Harness für normale Turns -verwendet. Bei der nächsten Nachricht setzt OpenClaw diesen Codex-Thread fort, übergibt das -derzeit ausgewählte OpenClaw-Modell an den App-Server und lässt den erweiterten Verlauf +`/codex resume` schreibt dieselbe Sidecar-Bindungsdatei, die das Harness für +normale Durchläufe verwendet. Bei der nächsten Nachricht setzt OpenClaw diesen Codex-Thread fort, übergibt das +aktuell ausgewählte OpenClaw-Modell an den App-Server und hält den erweiterten Verlauf aktiviert. ### Einen Codex-Thread über die CLI prüfen @@ -912,13 +938,12 @@ Thread direkt zu öffnen: codex resume ``` -Verwenden Sie dies, wenn Sie in einer Kanalunterhaltung einen Fehler bemerken und die -problematische Codex-Sitzung prüfen, lokal fortsetzen oder Codex fragen möchten, warum es -ein bestimmtes Tool oder eine bestimmte Reasoning-Entscheidung getroffen hat. Der einfachste -Weg ist normalerweise, zuerst `/diagnostics [note]` auszuführen: Nachdem Sie es genehmigt -haben, listet der abgeschlossene Bericht jeden Codex-Thread auf und gibt einen `Inspect locally`- -Befehl aus, zum Beispiel `codex resume `. Sie können diesen Befehl direkt in ein -Terminal kopieren. +Verwenden Sie dies, wenn Sie einen Fehler in einer Kanalunterhaltung bemerken und die +problematische Codex-Sitzung prüfen, lokal fortsetzen oder Codex fragen möchten, warum es eine +bestimmte Tool- oder Reasoning-Entscheidung getroffen hat. Der einfachste Weg ist normalerweise, zuerst +`/diagnostics [note]` auszuführen: Nachdem Sie es genehmigt haben, listet der abgeschlossene Bericht +jeden Codex-Thread auf und gibt einen `Inspect locally`-Befehl aus, zum Beispiel +`codex resume `. Sie können diesen Befehl direkt in ein Terminal kopieren. Sie können eine Thread-ID auch über `/codex binding` für den aktuellen Chat oder `/codex threads [filter]` für aktuelle Codex-App-Server-Threads erhalten und dann denselben @@ -926,173 +951,172 @@ Sie können eine Thread-ID auch über `/codex binding` für den aktuellen Chat o Die Befehlsoberfläche erfordert Codex-App-Server `0.125.0` oder neuer. Einzelne Steuermethoden werden als `unsupported by this Codex app-server` gemeldet, wenn ein -zukünftiger oder angepasster App-Server diese JSON-RPC-Methode nicht bereitstellt. +zukünftiger oder benutzerdefinierter App-Server diese JSON-RPC-Methode nicht bereitstellt. ## Hook-Grenzen Das Codex-Harness hat drei Hook-Ebenen: -| Ebene | Owner | Zweck | +| Ebene | Besitzer | Zweck | | ------------------------------------- | ------------------------ | ------------------------------------------------------------------- | | OpenClaw-Plugin-Hooks | OpenClaw | Produkt-/Plugin-Kompatibilität über PI- und Codex-Harnesses hinweg. | -| Codex-App-Server-Erweiterungsmiddleware | Mit OpenClaw gebündelte Plugins | Adapterverhalten pro Turn rund um dynamische OpenClaw-Tools. | -| Native Codex-Hooks | Codex | Niedrige Codex-Lifecycle- und native Tool-Richtlinie aus der Codex-Konfiguration. | +| Codex-App-Server-Erweiterungs-Middleware | Gebündelte OpenClaw-Plugins | Adapterverhalten pro Durchlauf rund um dynamische OpenClaw-Tools. | +| Native Codex-Hooks | Codex | Niedrigstufiger Codex-Lebenszyklus und native Tool-Richtlinie aus der Codex-Konfiguration. | -OpenClaw verwendet keine projektweiten oder globalen Codex-`hooks.json`-Dateien, um -OpenClaw-Plugin-Verhalten zu routen. Für die unterstützte native Tool- und Berechtigungs- -Bridge injiziert OpenClaw pro Thread Codex-Konfiguration für `PreToolUse`, `PostToolUse`, +OpenClaw verwendet keine Projekt- oder globalen Codex-`hooks.json`-Dateien, um +OpenClaw-Plugin-Verhalten zu routen. Für die unterstützte native Tool- und Berechtigungsbrücke +injiziert OpenClaw pro Thread Codex-Konfiguration für `PreToolUse`, `PostToolUse`, `PermissionRequest` und `Stop`. Andere Codex-Hooks wie `SessionStart` und -`UserPromptSubmit` bleiben Codex-Level-Steuerelemente; sie werden im v1-Vertrag nicht als -OpenClaw-Plugin-Hooks offengelegt. +`UserPromptSubmit` bleiben Codex-Steuerelemente; sie werden im v1-Vertrag nicht als +OpenClaw-Plugin-Hooks bereitgestellt. -Bei dynamischen OpenClaw-Tools führt OpenClaw das Tool aus, nachdem Codex den Aufruf -angefordert hat, sodass OpenClaw das eigene Plugin- und Middleware-Verhalten im Harness- -Adapter auslöst. Bei Codex-nativen Tools besitzt Codex den kanonischen Tool-Datensatz. -OpenClaw kann ausgewählte Ereignisse spiegeln, kann aber den nativen Codex-Thread nicht -umschreiben, sofern Codex diese Operation nicht über App-Server- oder native Hook-Callbacks -bereitstellt. +Für dynamische OpenClaw-Tools führt OpenClaw das Tool aus, nachdem Codex die +Ausführung angefordert hat, daher löst OpenClaw das Plugin- und Middleware-Verhalten, das es besitzt, im +Harness-Adapter aus. Für Codex-native Tools besitzt Codex den kanonischen Tool-Datensatz. +OpenClaw kann ausgewählte Ereignisse spiegeln, aber es kann den nativen Codex- +Thread nicht umschreiben, sofern Codex diese Operation nicht über App-Server- oder native Hook- +Callbacks bereitstellt. -Compaction- und LLM-Lifecycle-Projektionen stammen aus Codex-App-Server-Benachrichtigungen -und OpenClaw-Adapterstatus, nicht aus nativen Codex-Hook-Befehlen. OpenClaws Ereignisse -`before_compaction`, `after_compaction`, `llm_input` und `llm_output` sind Beobachtungen auf -Adapterebene, keine bytegenauen Erfassungen interner Anfragen oder Compaction-Payloads von -Codex. +Compaction- und LLM-Lebenszyklusprojektionen stammen aus Codex-App-Server- +Benachrichtigungen und dem OpenClaw-Adapterzustand, nicht aus nativen Codex-Hook-Befehlen. +OpenClaws `before_compaction`-, `after_compaction`-, `llm_input`- und +`llm_output`-Ereignisse sind Beobachtungen auf Adapterebene, keine bytegenauen Erfassungen +der internen Anfragen oder Compaction-Payloads von Codex. -Native Codex-App-Server-Benachrichtigungen `hook/started` und `hook/completed` werden als -`codex_app_server.hook`-Agentenereignisse für Trajektorie und Debugging projiziert. +Native Codex-`hook/started`- und `hook/completed`-App-Server-Benachrichtigungen werden +als `codex_app_server.hook`-Agentenereignisse für Trajektorie und Debugging projiziert. Sie rufen keine OpenClaw-Plugin-Hooks auf. ## V1-Supportvertrag -Der Codex-Modus ist nicht PI mit einem anderen Modellaufruf darunter. Codex besitzt mehr -der nativen Modellschleife, und OpenClaw passt seine Plugin- und Sitzungsoberflächen um -diese Grenze herum an. +Der Codex-Modus ist nicht PI mit einem anderen Modellaufruf darunter. Codex besitzt mehr von +der nativen Modellschleife, und OpenClaw passt seine Plugin- und Sitzungsoberflächen +an diese Grenze an. -Unterstützt in Codex-Runtime v1: +Unterstützt in Codex-Laufzeit v1: -| Oberfläche | Unterstützung | Warum | -| -------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| OpenAI-Modellschleife über Codex | Unterstützt | Der Codex-App-Server besitzt den OpenAI-Turn, die native Thread-Fortsetzung und die native Tool-Fortsetzung. | -| OpenClaw-Kanalrouting und -Zustellung | Unterstützt | Telegram, Discord, Slack, WhatsApp, iMessage und andere Kanäle bleiben außerhalb der Modell-Runtime. | -| Dynamische OpenClaw-Tools | Unterstützt | Codex bittet OpenClaw, diese Tools auszuführen, sodass OpenClaw im Ausführungspfad bleibt. | -| Prompt- und Kontext-Plugins | Unterstützt | OpenClaw baut Prompt-Overlays und projiziert Kontext in den Codex-Turn, bevor der Thread gestartet oder fortgesetzt wird. | -| Kontext-Engine-Lifecycle | Unterstützt | Assemble, Ingest oder Wartung nach dem Turn sowie die Koordination der Kontext-Engine-Compaction laufen für Codex-Turns. | -| Dynamische Tool-Hooks | Unterstützt | `before_tool_call`, `after_tool_call` und Tool-Ergebnis-Middleware laufen um dynamische Tools, die OpenClaw gehören. | -| Lifecycle-Hooks | Als Adapterbeobachtungen unterstützt | `llm_input`, `llm_output`, `agent_end`, `before_compaction` und `after_compaction` werden mit ehrlichen Codex-Modus-Payloads ausgelöst. | -| Gate zur Überarbeitung der finalen Antwort | Über das native Hook-Relay unterstützt | Codex `Stop` wird an `before_agent_finalize` weitergeleitet; `revise` bittet Codex um einen weiteren Modelllauf vor der Finalisierung. | -| Native Shell-, Patch- und MCP-Blockierung oder -Beobachtung | Über das native Hook-Relay unterstützt | Codex `PreToolUse` und `PostToolUse` werden für festgelegte native Tool-Oberflächen weitergeleitet, einschließlich MCP-Payloads auf Codex-App-Server `0.125.0` oder neuer. Blockieren wird unterstützt; das Umschreiben von Argumenten nicht. | -| Native Berechtigungsrichtlinie | Über das native Hook-Relay unterstützt | Codex `PermissionRequest` kann über OpenClaw-Richtlinien geroutet werden, sofern die Runtime dies bereitstellt. Wenn OpenClaw keine Entscheidung zurückgibt, setzt Codex seinen normalen Guardian- oder Benutzer-Genehmigungspfad fort. | -| App-Server-Trajektorienerfassung | Unterstützt | OpenClaw zeichnet die Anfrage auf, die es an den App-Server gesendet hat, sowie die App-Server-Benachrichtigungen, die es empfängt. | +| Oberfläche | Unterstützung | Warum | +| --------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| OpenAI-Modellschleife über Codex | Unterstützt | Der Codex-App-Server besitzt den OpenAI-Durchlauf, die native Thread-Fortsetzung und die native Tool-Fortsetzung. | +| OpenClaw-Kanalrouting und -Zustellung | Unterstützt | Telegram, Discord, Slack, WhatsApp, iMessage und andere Kanäle bleiben außerhalb der Modelllaufzeit. | +| Dynamische OpenClaw-Tools | Unterstützt | Codex fordert OpenClaw auf, diese Tools auszuführen, sodass OpenClaw im Ausführungspfad bleibt. | +| Prompt- und Kontext-Plugins | Unterstützt | OpenClaw erstellt Prompt-Overlays und projiziert Kontext in den Codex-Durchlauf, bevor der Thread gestartet oder fortgesetzt wird. | +| Kontext-Engine-Lebenszyklus | Unterstützt | Zusammenstellung, Aufnahme oder Wartung nach dem Durchlauf sowie Koordination der Kontext-Engine-Compaction laufen für Codex-Durchläufe. | +| Dynamische Tool-Hooks | Unterstützt | `before_tool_call`, `after_tool_call` und Tool-Ergebnis-Middleware laufen rund um OpenClaw-eigene dynamische Tools. | +| Lebenszyklus-Hooks | Als Adapterbeobachtungen unterstützt | `llm_input`, `llm_output`, `agent_end`, `before_compaction` und `after_compaction` werden mit ehrlichen Codex-Modus-Payloads ausgelöst. | +| Abschlussantwort-Überarbeitungsgate | Über das native Hook-Relay unterstützt | Codex `Stop` wird an `before_agent_finalize` weitergeleitet; `revise` fordert Codex vor der Finalisierung zu einem weiteren Modelldurchlauf auf. | +| Native Shell-, Patch- und MCP-Blockierung oder -Beobachtung | Über das native Hook-Relay unterstützt | Codex `PreToolUse` und `PostToolUse` werden für festgelegte native Tool-Oberflächen weitergeleitet, einschließlich MCP-Payloads auf Codex-App-Server `0.125.0` oder neuer. Blockieren wird unterstützt; Argumentumschreibung nicht. | +| Native Berechtigungsrichtlinie | Über das native Hook-Relay unterstützt | Codex `PermissionRequest` kann durch OpenClaw-Richtlinien geroutet werden, sofern die Laufzeit dies bereitstellt. Wenn OpenClaw keine Entscheidung zurückgibt, läuft Codex über seinen normalen Guardian- oder Benutzergenehmigungspfad weiter. | +| App-Server-Trajektorienerfassung | Unterstützt | OpenClaw zeichnet die Anfrage auf, die es an den App-Server gesendet hat, sowie die App-Server-Benachrichtigungen, die es empfängt. | -Nicht unterstützt in Codex-Runtime v1: +Nicht unterstützt in Codex-Laufzeit v1: -| Oberfläche | V1-Grenze | Zukünftiger Pfad | +| Oberfläche | V1-Grenze | Zukünftiger Pfad | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -| Mutation nativer Tool-Argumente | Native Codex-Pre-Tool-Hooks können blockieren, aber OpenClaw schreibt Codex-native Tool-Argumente nicht um. | Erfordert Codex-Hook-/Schemaunterstützung für ersetzende Tool-Eingaben. | -| Bearbeitbarer Codex-nativer Transkriptverlauf | Codex besitzt den kanonischen nativen Thread-Verlauf. OpenClaw besitzt eine Spiegelung und kann zukünftigen Kontext projizieren, sollte aber keine nicht unterstützten Interna mutieren. | Fügen Sie explizite Codex-App-Server-APIs hinzu, wenn native Thread-Chirurgie erforderlich ist. | -| `tool_result_persist` für Codex-native Tool-Datensätze | Dieser Hook transformiert von OpenClaw verwaltete Transkriptschreibvorgänge, nicht Codex-native Tool-Datensätze. | Könnte transformierte Datensätze spiegeln, aber kanonisches Umschreiben benötigt Codex-Unterstützung. | -| Umfangreiche native Compaction-Metadaten | OpenClaw beobachtet Start und Abschluss der Compaction, erhält aber keine stabile Liste behaltener/verworfener Einträge, Token-Differenz oder Zusammenfassungs-Payload. | Benötigt umfangreichere Codex-Compaction-Ereignisse. | -| Compaction-Intervention | Aktuelle OpenClaw-Compaction-Hooks haben im Codex-Modus Benachrichtigungsniveau. | Fügen Sie Codex-Pre-/Post-Compaction-Hooks hinzu, wenn Plugins native Compaction ablehnen oder umschreiben müssen. | -| Bytegenaue Erfassung von Model-API-Anfragen | OpenClaw kann App-Server-Anfragen und Benachrichtigungen erfassen, aber Codex Core erstellt die finale OpenAI-API-Anfrage intern. | Benötigt ein Codex-Model-Request-Tracing-Ereignis oder eine Debug-API. | +| Mutation von nativen Tool-Argumenten | Codex-native Pre-Tool-Hooks können blockieren, aber OpenClaw schreibt Codex-native Tool-Argumente nicht um. | Erfordert Codex-Hook-/Schemaunterstützung für Ersatz-Tool-Eingaben. | +| Bearbeitbarer Codex-nativer Transkriptverlauf | Codex besitzt den kanonischen nativen Thread-Verlauf. OpenClaw besitzt eine Spiegelung und kann zukünftigen Kontext projizieren, sollte aber nicht unterstützte Interna nicht mutieren. | Explizite Codex-App-Server-APIs hinzufügen, falls native Thread-Eingriffe nötig sind. | +| `tool_result_persist` für Codex-native Tool-Datensätze | Dieser Hook transformiert OpenClaw-eigene Transkriptschreibvorgänge, nicht Codex-native Tool-Datensätze. | Transformierte Datensätze könnten gespiegelt werden, aber kanonisches Umschreiben benötigt Codex-Unterstützung. | +| Umfangreiche native Compaction-Metadaten | OpenClaw beobachtet Start und Abschluss der Compaction, erhält aber keine stabile Liste beibehaltener/verworfener Einträge, kein Token-Delta und keine Zusammenfassungsnutzlast. | Benötigt umfangreichere Codex-Compaction-Ereignisse. | +| Compaction-Intervention | Aktuelle OpenClaw-Compaction-Hooks haben im Codex-Modus Benachrichtigungsniveau. | Codex-Pre-/Post-Compaction-Hooks hinzufügen, wenn Plugins native Compaction per Veto verhindern oder umschreiben müssen. | +| Bytegenaue Erfassung von Modell-API-Anfragen | OpenClaw kann App-Server-Anfragen und Benachrichtigungen erfassen, aber Codex Core erstellt die finale OpenAI-API-Anfrage intern. | Benötigt ein Codex-Modellanfrage-Tracing-Ereignis oder eine Debug-API. | ## Tools, Medien und Compaction -Der Codex-Harness ändert nur den Low-Level-Executor des eingebetteten Agents. +Der Codex-Harness ändert nur den niedrigstufigen eingebetteten Agent-Executor. OpenClaw erstellt weiterhin die Tool-Liste und empfängt dynamische Tool-Ergebnisse vom -Harness. Text, Bilder, Videos, Musik, TTS, Genehmigungen und Ausgaben von Messaging-Tools +Harness. Text, Bilder, Video, Musik, TTS, Genehmigungen und Messaging-Tool-Ausgaben laufen weiterhin über den normalen OpenClaw-Auslieferungspfad. -Das native Hook-Relay ist absichtlich generisch, aber der Supportvertrag von v1 ist +Das native Hook-Relay ist absichtlich generisch, aber der v1-Supportvertrag ist auf die Codex-nativen Tool- und Berechtigungspfade beschränkt, die OpenClaw testet. In -der Codex-Runtime umfasst das Shell-, Patch- und MCP-`PreToolUse`-, -`PostToolUse`- und `PermissionRequest`-Payloads. Gehen Sie nicht davon aus, dass jedes zukünftige -Codex-Hook-Ereignis eine OpenClaw-Plugin-Oberfläche ist, bis der Runtime-Vertrag +der Codex-Laufzeit umfasst das Shell-, Patch- und MCP-`PreToolUse`-, +`PostToolUse`- und `PermissionRequest`-Nutzlasten. Nehmen Sie nicht an, dass jedes zukünftige +Codex-Hook-Ereignis eine OpenClaw-Plugin-Oberfläche ist, bis der Laufzeitvertrag es benennt. -Für `PermissionRequest` gibt OpenClaw nur dann explizite Allow- oder Deny-Entscheidungen -zurück, wenn die Richtlinie entscheidet. Ein Ergebnis ohne Entscheidung ist kein Allow. -Codex behandelt es als keine Hook-Entscheidung und fällt auf den eigenen Guardian- oder -Benutzergenehmigungspfad zurück. +Für `PermissionRequest` gibt OpenClaw nur dann explizite Zulassen- oder Ablehnen-Entscheidungen +zurück, wenn die Richtlinie entscheidet. Ein Ergebnis ohne Entscheidung ist keine Zulassung. Codex behandelt es so, als +läge keine Hook-Entscheidung vor, und fällt auf seinen eigenen Guardian- oder Benutzerfreigabepfad zurück. -Codex-MCP-Tool-Genehmigungsabfragen werden über OpenClaws Plugin-Genehmigungsfluss -geleitet, wenn Codex `_meta.codex_approval_kind` als +Codex-MCP-Tool-Genehmigungsanfragen werden durch den OpenClaw-Plugin- +Genehmigungsfluss geleitet, wenn Codex `_meta.codex_approval_kind` als `"mcp_tool_call"` markiert. Codex-`request_user_input`-Prompts werden an den -ursprünglichen Chat zurückgesendet, und die nächste eingereihte Follow-up-Nachricht beantwortet diese native -Serveranfrage, statt als zusätzlicher Kontext gesteuert zu werden. Andere MCP-Abfrageanfragen +ursprünglichen Chat zurückgesendet, und die nächste in die Warteschlange gestellte Folgenachricht beantwortet diese native +Serveranfrage, statt als zusätzlicher Kontext gesteuert zu werden. Andere MCP-Anfrageanforderungen schlagen weiterhin geschlossen fehl. -Active-Run-Queue-Steuerung wird auf Codex-App-Server-`turn/steer` abgebildet. Mit dem -Standard `messages.queue.mode: "steer"` bündelt OpenClaw eingereihte Chatnachrichten -für das konfigurierte Ruhefenster und sendet sie in Ankunftsreihenfolge als eine `turn/steer`-Anfrage. -Der Legacy-`queue`-Modus sendet separate `turn/steer`-Anfragen. Codex- +Steuerung der Warteschlange aktiver Läufe wird auf Codex-App-Server-`turn/steer` abgebildet. Mit dem +Standard `messages.queue.mode: "steer"` bündelt OpenClaw Chatnachrichten in der Warteschlange +für das konfigurierte Ruhefenster und sendet sie in +Eingangsreihenfolge als eine `turn/steer`-Anfrage. Der Legacy-`queue`-Modus sendet separate `turn/steer`-Anfragen. Codex- Review- und manuelle Compaction-Turns können Same-Turn-Steuerung ablehnen; in diesem Fall -verwendet OpenClaw die Follow-up-Queue, wenn der ausgewählte Modus einen Fallback erlaubt. Siehe -[Steering-Queue](/de/concepts/queue-steering). +verwendet OpenClaw die Follow-up-Warteschlange, wenn der ausgewählte Modus Fallback erlaubt. Siehe +[Steuerungswarteschlange](/de/concepts/queue-steering). -Wenn das ausgewählte Model den Codex-Harness verwendet, wird native Thread-Compaction -an den Codex-App-Server delegiert. OpenClaw hält eine Transkriptspiegelung für Channel- -Verlauf, Suche, `/new`, `/reset` und zukünftige Model- oder Harness-Wechsel. Die -Spiegelung enthält den Benutzer-Prompt, den finalen Assistant-Text und leichtgewichtige Codex- +Wenn das ausgewählte Modell den Codex-Harness verwendet, wird native Thread-Compaction an den +Codex-App-Server delegiert. OpenClaw behält eine Transkriptspiegelung für Kanalverlauf, +Suche, `/new`, `/reset` und zukünftige Modell- oder Harness-Wechsel. Die +Spiegelung umfasst den Benutzerprompt, finalen Assistententext und leichtgewichtige Codex- Reasoning- oder Plan-Datensätze, wenn der App-Server sie ausgibt. Derzeit zeichnet OpenClaw nur Start- und Abschlusssignale nativer Compaction auf. Es stellt noch keine menschenlesbare Compaction-Zusammenfassung oder prüfbare Liste bereit, welche Einträge Codex -nach der Compaction behalten hat. +nach der Compaction beibehalten hat. -Da Codex den kanonischen nativen Thread besitzt, schreibt `tool_result_persist` -derzeit keine Codex-nativen Tool-Ergebnisdatensätze um. Es gilt nur, wenn -OpenClaw ein Tool-Ergebnis in ein von OpenClaw verwaltetes Sitzungstranskript schreibt. +Da Codex den kanonischen nativen Thread besitzt, schreibt `tool_result_persist` derzeit +Codex-native Tool-Ergebnisdatensätze nicht um. Es greift nur, wenn +OpenClaw ein Tool-Ergebnis in ein OpenClaw-eigenes Sitzungstranskript schreibt. -Mediengenerierung erfordert kein PI. Bild-, Video-, Musik-, PDF-, TTS- und Medien- -Verständnis verwenden weiterhin die passenden Provider-/Model-Einstellungen wie +Mediengenerierung erfordert kein PI. Bild, Video, Musik, PDF, TTS und Medienverständnis +verwenden weiterhin die passenden Provider-/Modelleinstellungen wie `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` und `messages.tts`. ## Fehlerbehebung **Codex erscheint nicht als normaler `/model`-Provider:** Das ist für -neue Konfigurationen erwartet. Wählen Sie ein `openai/gpt-*`-Model mit -`agentRuntime.id: "codex"` (oder eine Legacy-`codex/*`-Referenz), aktivieren Sie +neue Konfigurationen erwartet. Wählen Sie ein `openai/gpt-*`-Modell mit +`agentRuntime.id: "codex"` (oder eine Legacy-`codex/*`-Ref), aktivieren Sie `plugins.entries.codex.enabled` und prüfen Sie, ob `plugins.allow` `codex` ausschließt. **OpenClaw verwendet PI statt Codex:** `agentRuntime.id: "auto"` kann weiterhin PI als Kompatibilitäts-Backend verwenden, wenn kein Codex-Harness den Lauf beansprucht. Setzen Sie `agentRuntime.id: "codex"`, um die Codex-Auswahl beim Testen zu erzwingen. Eine -erzwungene Codex-Runtime schlägt jetzt fehl, statt auf PI zurückzufallen, sofern Sie nicht -explizit `agentRuntime.fallback: "pi"` setzen. Sobald der Codex-App-Server -ausgewählt ist, treten seine Fehler ohne zusätzliche Fallback-Konfiguration direkt zutage. +erzwungene Codex-Laufzeit schlägt jetzt fehl, statt auf PI zurückzufallen, es sei denn, Sie +setzen explizit `agentRuntime.fallback: "pi"`. Sobald der Codex-App-Server +ausgewählt ist, werden seine Fehler direkt ohne zusätzliche Fallback-Konfiguration sichtbar. -**Der App-Server wird abgelehnt:** Aktualisieren Sie Codex, sodass der App-Server-Handshake -Version `0.125.0` oder neuer meldet. Prereleases derselben Version oder Build-Suffix- -Versionen wie `0.125.0-alpha.2` oder `0.125.0+custom` werden abgelehnt, weil der -stabile Protokoll-Mindeststand `0.125.0` das ist, was OpenClaw testet. +**Der App-Server wird abgelehnt:** Aktualisieren Sie Codex, damit der App-Server-Handshake +Version `0.125.0` oder neuer meldet. Prereleases derselben Version oder Versionen mit Build-Suffix +wie `0.125.0-alpha.2` oder `0.125.0+custom` werden abgelehnt, weil die +stabile Protokolluntergrenze `0.125.0` das ist, was OpenClaw testet. -**Model-Erkennung ist langsam:** Senken Sie `plugins.entries.codex.config.discovery.timeoutMs` +**Modellerkennung ist langsam:** Verringern Sie `plugins.entries.codex.config.discovery.timeoutMs` oder deaktivieren Sie die Erkennung. **WebSocket-Transport schlägt sofort fehl:** Prüfen Sie `appServer.url`, `authToken` und ob der entfernte App-Server dieselbe Codex-App-Server-Protokollversion spricht. -**Ein Nicht-Codex-Model verwendet PI:** Das ist erwartet, sofern Sie nicht +**Ein Nicht-Codex-Modell verwendet PI:** Das ist erwartet, sofern Sie nicht `agentRuntime.id: "codex"` für diesen Agent erzwungen oder eine Legacy- -`codex/*`-Referenz ausgewählt haben. Einfache `openai/gpt-*`- und andere Provider-Referenzen bleiben im +`codex/*`-Ref ausgewählt haben. Einfache `openai/gpt-*`- und andere Provider-Refs bleiben im `auto`-Modus auf ihrem normalen Provider-Pfad. Wenn Sie `agentRuntime.id: "codex"` erzwingen, muss jeder eingebettete -Turn für diesen Agent ein von Codex unterstütztes OpenAI-Model sein. +Turn für diesen Agent ein von Codex unterstütztes OpenAI-Modell sein. **Computer Use ist installiert, aber Tools laufen nicht:** Prüfen Sie `/codex computer-use status` aus einer frischen Sitzung. Wenn ein Tool -`Native hook relay unavailable` meldet, verwenden Sie `/new` oder `/reset`; wenn es bestehen bleibt, starten Sie +`Native hook relay unavailable` meldet, verwenden Sie `/new` oder `/reset`; wenn dies bestehen bleibt, starten Sie das Gateway neu, um veraltete native Hook-Registrierungen zu löschen. Wenn `computer-use.list_apps` ein Timeout erreicht, starten Sie Codex Computer Use oder Codex Desktop neu und versuchen Sie es erneut. -## Verwandte Themen +## Verwandt - [Agent-Harness-Plugins](/de/plugins/sdk-agent-harness) -- [Agent-Runtimes](/de/concepts/agent-runtimes) -- [Model-Provider](/de/concepts/model-providers) +- [Agent-Laufzeiten](/de/concepts/agent-runtimes) +- [Modell-Provider](/de/concepts/model-providers) - [OpenAI-Provider](/de/providers/openai) - [Status](/de/cli/status) - [Plugin-Hooks](/de/plugins/hooks) - [Konfigurationsreferenz](/de/gateway/configuration-reference) -- [Tests](/de/help/testing-live#live-codex-app-server-harness-smoke) +- [Testen](/de/help/testing-live#live-codex-app-server-harness-smoke) diff --git a/docs/de/providers/arcee.md b/docs/de/providers/arcee.md index 2a13e21e2..a8bd1e168 100644 --- a/docs/de/providers/arcee.md +++ b/docs/de/providers/arcee.md @@ -1,43 +1,43 @@ --- read_when: - - Sie möchten Arcee AI mit OpenClaw verwenden. - - Sie benötigen die API-Key-Umgebungsvariable oder die CLI-Authentifizierungsoption. -summary: Einrichtung von Arcee AI (Authentifizierung + Modellauswahl) + - Sie möchten Arcee AI mit OpenClaw verwenden + - Sie benötigen die Umgebungsvariable für den API-Schlüssel oder die CLI-Authentifizierungsoption +summary: Arcee AI-Einrichtung (Authentifizierung + Modellauswahl) title: Arcee AI x-i18n: - generated_at: "2026-04-24T06:52:55Z" - model: gpt-5.4 + generated_at: "2026-05-02T23:39:13Z" + model: gpt-5.5 provider: openai - source_hash: 54989e1706901fedc8a0c816ca7ee7f877fa4b973697540dd90cb9182420043f + source_hash: 622ee5288aec3ae0b45d3f06ba65fd6f972e07d7a7596ae3905d6fbdac0bf737 source_path: providers/arcee.md - workflow: 15 + workflow: 16 --- -[Arcee AI](https://arcee.ai) bietet Zugriff auf die Trinity-Familie von Mixture-of-Experts-Modellen über eine OpenAI-kompatible API. Alle Trinity-Modelle sind unter Apache 2.0 lizenziert. +[Arcee AI](https://arcee.ai) bietet über eine OpenAI-kompatible API Zugriff auf die Trinity-Familie von Mixture-of-Experts-Modellen. Alle Trinity-Modelle sind unter Apache 2.0 lizenziert. -Auf Modelle von Arcee AI kann direkt über die Arcee-Plattform oder über [OpenRouter](/de/providers/openrouter) zugegriffen werden. +Auf Arcee AI-Modelle kann direkt über die Arcee-Plattform oder über [OpenRouter](/de/providers/openrouter) zugegriffen werden. | Eigenschaft | Wert | -| ----------- | ------------------------------------------------------------------------------------- | -| Provider | `arcee` | -| Auth | `ARCEEAI_API_KEY` (direkt) oder `OPENROUTER_API_KEY` (über OpenRouter) | -| API | OpenAI-kompatibel | -| Base URL | `https://api.arcee.ai/api/v1` (direkt) oder `https://openrouter.ai/api/v1` (OpenRouter) | +| -------- | ------------------------------------------------------------------------------------- | +| Provider | `arcee` | +| Auth | `ARCEEAI_API_KEY` (direkt) oder `OPENROUTER_API_KEY` (über OpenRouter) | +| API | OpenAI-kompatibel | +| Basis-URL | `https://api.arcee.ai/api/v1` (direkt) oder `https://openrouter.ai/api/v1` (OpenRouter) | ## Erste Schritte - - Erstellen Sie einen API-Key bei [Arcee AI](https://chat.arcee.ai/). + + Erstellen Sie einen API-Schlüssel bei [Arcee AI](https://chat.arcee.ai/). ```bash openclaw onboard --auth-choice arceeai-api-key ``` - + ```json5 { agents: { @@ -53,15 +53,15 @@ Auf Modelle von Arcee AI kann direkt über die Arcee-Plattform oder über [OpenR - - Erstellen Sie einen API-Key bei [OpenRouter](https://openrouter.ai/keys). + + Erstellen Sie einen API-Schlüssel bei [OpenRouter](https://openrouter.ai/keys). ```bash openclaw onboard --auth-choice arceeai-openrouter ``` - + ```json5 { agents: { @@ -72,14 +72,14 @@ Auf Modelle von Arcee AI kann direkt über die Arcee-Plattform oder über [OpenR } ``` - Dieselben Modellreferenzen funktionieren sowohl für direkte Setups als auch über OpenRouter (zum Beispiel `arcee/trinity-large-thinking`). + Dieselben Modellreferenzen funktionieren sowohl für direkte als auch für OpenRouter-Setups (zum Beispiel `arcee/trinity-large-thinking`). -## Nicht interaktives Setup +## Nicht interaktive Einrichtung @@ -101,51 +101,51 @@ Auf Modelle von Arcee AI kann direkt über die Arcee-Plattform oder über [OpenR -## Eingebauter Katalog +## Integrierter Katalog -OpenClaw wird derzeit mit diesem gebündelten Arcee-Katalog ausgeliefert: +OpenClaw enthält derzeit diesen gebündelten Arcee-Katalog: -| Modellreferenz | Name | Eingabe | Kontext | Kosten (In/Out pro 1M) | Hinweise | -| ----------------------------- | ---------------------- | ------- | ------- | ---------------------- | ------------------------------------------- | -| `arcee/trinity-large-thinking` | Trinity Large Thinking | Text | 256K | $0.25 / $0.90 | Standardmodell; Reasoning aktiviert | -| `arcee/trinity-large-preview` | Trinity Large Preview | Text | 128K | $0.25 / $1.00 | Allgemeiner Zweck; 400B Parameter, 13B aktiv | -| `arcee/trinity-mini` | Trinity Mini 26B | Text | 128K | $0.045 / $0.15 | Schnell und kosteneffizient; Function Calling | +| Modellreferenz | Name | Eingabe | Kontext | Kosten (Ein-/Ausgabe pro 1 Mio.) | Hinweise | +| ------------------------------ | ---------------------- | ----- | ------- | -------------------- | ------------------------------------------ | +| `arcee/trinity-large-thinking` | Trinity Large Thinking | Text | 256K | $0.25 / $0.90 | Standardmodell; Reasoning aktiviert; keine Tools | +| `arcee/trinity-large-preview` | Trinity Large Preview | Text | 128K | $0.25 / $1.00 | Allzweckmodell; 400B Parameter, 13B aktiv | +| `arcee/trinity-mini` | Trinity Mini 26B | Text | 128K | $0.045 / $0.15 | Schnell und kosteneffizient; Funktionsaufrufe | -Das Onboarding-Preset setzt `arcee/trinity-large-thinking` als Standardmodell. +Die Onboarding-Voreinstellung legt `arcee/trinity-large-thinking` als Standardmodell fest. Es ist ein reines Reasoning-/Textmodell und unterstützt weder Tool-Nutzung noch Funktionsaufrufe. ## Unterstützte Funktionen -| Funktion | Unterstützt | -| --------------------------------------------- | ----------------------------- | -| Streaming | Ja | -| Tool-Nutzung / Function Calling | Ja | -| Strukturierte Ausgabe (JSON-Modus und JSON-Schema) | Ja | -| Erweitertes Thinking | Ja (Trinity Large Thinking) | +| Funktion | Unterstützt | +| --------------------------------------------- | ------------------------------------------- | +| Streaming | Ja | +| Tool-Nutzung / Funktionsaufrufe | Modellabhängig; nicht Trinity Large Thinking | +| Strukturierte Ausgabe (JSON-Modus und JSON-Schema) | Ja | +| Erweitertes Denken | Ja (Trinity Large Thinking) | - Wenn das Gateway als Daemon läuft (launchd/systemd), stellen Sie sicher, dass `ARCEEAI_API_KEY` - (oder `OPENROUTER_API_KEY`) diesem Prozess zur Verfügung steht (zum Beispiel in + Wenn der Gateway als Daemon ausgeführt wird (launchd/systemd), stellen Sie sicher, dass `ARCEEAI_API_KEY` + (oder `OPENROUTER_API_KEY`) für diesen Prozess verfügbar ist (zum Beispiel in `~/.openclaw/.env` oder über `env.shellEnv`). - Wenn Sie Arcee-Modelle über OpenRouter verwenden, gelten dieselben Modellreferenzen `arcee/*`. - OpenClaw übernimmt das Routing transparent basierend auf Ihrer Authentifizierungswahl. Siehe die - [OpenRouter-Provider-Dokumentation](/de/providers/openrouter) für OpenRouter-spezifische - Konfigurationsdetails. + Wenn Sie Arcee-Modelle über OpenRouter verwenden, gelten dieselben `arcee/*`-Modellreferenzen. + OpenClaw verarbeitet das Routing transparent anhand Ihrer Auth-Auswahl. Weitere OpenRouter-spezifische + Konfigurationsdetails finden Sie in der + [OpenRouter-Provider-Dokumentation](/de/providers/openrouter). -## Verwandt +## Verwandte Themen - Zugriff auf Arcee-Modelle und viele andere über einen einzigen API-Key. + Greifen Sie mit einem einzigen API-Schlüssel auf Arcee-Modelle und viele andere zu. - Auswahl von Providern, Modellreferenzen und Failover-Verhalten. + Provider, Modellreferenzen und Failover-Verhalten auswählen. diff --git a/docs/de/reference/RELEASING.md b/docs/de/reference/RELEASING.md index 191367376..8103c0511 100644 --- a/docs/de/reference/RELEASING.md +++ b/docs/de/reference/RELEASING.md @@ -1,178 +1,179 @@ --- read_when: - - Suche nach Definitionen öffentlicher Release-Kanäle + - Suche nach Definitionen für öffentliche Release-Kanäle - Release-Validierung oder Paketabnahme ausführen - - Suchen Sie Informationen zu Versionsbenennung und Veröffentlichungsrhythmus + - Suche nach Versionsbenennung und Veröffentlichungsrhythmus summary: Release-Lanes, Operator-Checkliste, Validierungsboxen, Versionsbenennung und Taktung title: Release-Richtlinie x-i18n: - generated_at: "2026-05-02T21:01:50Z" + generated_at: "2026-05-02T23:39:26Z" model: gpt-5.5 provider: openai - source_hash: 493cb8b42f0e15f3bf5f8fb9be7d01fd626f4f16db9ac0a85e6efa747ef12d12 + source_hash: ba316d1736eae8edd2fb0a71b9a3da345f8895c3b536e9a1f619718ea12fc851 source_path: reference/RELEASING.md workflow: 16 --- -OpenClaw hat vier öffentliche Release-Lanes: +OpenClaw hat drei öffentliche Release-Lanes: -- stable: getaggte Releases, die standardmäßig nach npm `beta` veröffentlichen oder nach npm `latest`, wenn dies ausdrücklich angefordert wird -- alpha: Prerelease-Tags, die nach npm `alpha` veröffentlichen -- beta: Prerelease-Tags, die nach npm `beta` veröffentlichen -- dev: der bewegliche Head von `main` +- stable: getaggte Releases, die standardmäßig nach npm `beta` veröffentlicht werden oder nach npm `latest`, wenn dies ausdrücklich angefordert wird +- beta: Vorabversions-Tags, die nach npm `beta` veröffentlicht werden +- dev: die fortlaufende Spitze von `main` ## Versionsbenennung -- Stabile Release-Version: `YYYY.M.D` +- Version eines stabilen Releases: `YYYY.M.D` - Git-Tag: `vYYYY.M.D` -- Stabile Korrektur-Release-Version: `YYYY.M.D-N` +- Version eines stabilen Korrektur-Releases: `YYYY.M.D-N` - Git-Tag: `vYYYY.M.D-N` -- Alpha-Prerelease-Version: `YYYY.M.D-alpha.N` - - Git-Tag: `vYYYY.M.D-alpha.N` -- Beta-Prerelease-Version: `YYYY.M.D-beta.N` +- Version einer Beta-Vorabversion: `YYYY.M.D-beta.N` - Git-Tag: `vYYYY.M.D-beta.N` -- Monat oder Tag nicht mit führenden Nullen schreiben -- `latest` bedeutet das aktuell promotete stabile npm-Release -- `alpha` bedeutet das aktuelle Alpha-Installationsziel +- Monat und Tag nicht mit führenden Nullen auffüllen +- `latest` bedeutet das aktuell hochgestufte stabile npm-Release - `beta` bedeutet das aktuelle Beta-Installationsziel -- Stabile und stabile Korrektur-Releases veröffentlichen standardmäßig nach npm `beta`; Release-Operatoren können ausdrücklich `latest` als Ziel wählen oder später einen geprüften Beta-Build promoten +- Stabile Releases und stabile Korrektur-Releases werden standardmäßig nach npm `beta` veröffentlicht; Release-Operatoren können ausdrücklich `latest` als Ziel wählen oder später einen geprüften Beta-Build hochstufen - Jedes stabile OpenClaw-Release liefert das npm-Paket und die macOS-App zusammen aus; - Beta-Releases validieren und veröffentlichen normalerweise zuerst den npm-/Paketpfad, wobei - Build/Signierung/Notarisierung der mac-App für stabile Releases reserviert bleibt, sofern nicht ausdrücklich angefordert + Beta-Releases validieren und veröffentlichen normalerweise zuerst den npm-/Paketpfad, während + Build, Signierung und Notarisierung der Mac-App für stabile Releases reserviert sind, sofern nicht ausdrücklich angefordert -## Release-Rhythmus +## Release-Takt -- Releases bewegen sich Beta-zuerst +- Releases laufen zuerst über Beta - Stable folgt erst, nachdem die neueste Beta validiert wurde -- Maintainer erstellen Releases normalerweise von einem `release/YYYY.M.D`-Branch, der - aus dem aktuellen `main` erstellt wurde, damit Release-Validierung und Fixes neue +- Maintainer erstellen Releases normalerweise aus einem `release/YYYY.M.D`-Branch, der + aus dem aktuellen `main` erstellt wurde, damit Release-Validierung und Korrekturen neue Entwicklung auf `main` nicht blockieren -- Wenn ein Beta-Tag gepusht oder veröffentlicht wurde und einen Fix benötigt, erstellen Maintainer - das nächste `-beta.N`-Tag, statt das alte Beta-Tag zu löschen oder neu zu erstellen -- Detailliertes Release-Verfahren, Freigaben, Anmeldedaten und Wiederherstellungshinweise sind +- Wenn ein Beta-Tag gepusht oder veröffentlicht wurde und eine Korrektur benötigt, erstellen Maintainer + stattdessen den nächsten `-beta.N`-Tag, anstatt den alten Beta-Tag zu löschen oder neu zu erstellen +- Detaillierte Release-Verfahren, Freigaben, Zugangsdaten und Wiederherstellungshinweise sind nur für Maintainer bestimmt ## Checkliste für Release-Operatoren -Diese Checkliste beschreibt die öffentliche Form des Release-Ablaufs. Private Anmeldedaten, -Signierung, Notarisierung, Dist-Tag-Wiederherstellung und Details zu Notfall-Rollbacks bleiben im +Diese Checkliste ist die öffentliche Form des Release-Ablaufs. Private Zugangsdaten, +Signierung, Notarisierung, Wiederherstellung von dist-tags und Details zu Notfall-Rollbacks bleiben im nur für Maintainer bestimmten Release-Runbook. -1. Vom aktuellen `main` starten: neueste Änderungen pullen, bestätigen, dass der Ziel-Commit gepusht ist, - und bestätigen, dass die aktuelle CI von `main` grün genug ist, um davon zu branchen. +1. Vom aktuellen `main` starten: neuesten Stand pullen, bestätigen, dass der Ziel-Commit gepusht ist, + und bestätigen, dass die aktuelle `main`-CI grün genug ist, um davon zu branchen. 2. Den obersten Abschnitt in `CHANGELOG.md` aus der echten Commit-Historie mit `/changelog` neu schreiben, Einträge nutzerorientiert halten, committen, pushen und vor dem Branching noch einmal rebasen/pullen. 3. Release-Kompatibilitätseinträge in `src/plugins/compat/registry.ts` und `src/commands/doctor/shared/deprecation-compat.ts` prüfen. Abgelaufene - Kompatibilität nur entfernen, wenn der Upgrade-Pfad weiter abgedeckt bleibt, oder dokumentieren, warum sie + Kompatibilität nur entfernen, wenn der Upgrade-Pfad weiterhin abgedeckt bleibt, oder dokumentieren, warum sie absichtlich beibehalten wird. -4. `release/YYYY.M.D` aus dem aktuellen `main` erstellen; normale Release-Arbeiten nicht +4. `release/YYYY.M.D` aus dem aktuellen `main` erstellen; normale Release-Arbeit nicht direkt auf `main` durchführen. -5. Jede erforderliche Versionsstelle für das beabsichtigte Tag erhöhen, dann - `pnpm plugins:sync` ausführen, damit veröffentlichbare Plugin-Pakete dieselbe Release- - Version und Kompatibilitätsmetadaten teilen, danach den lokalen deterministischen Preflight ausführen: +5. Jede erforderliche Versionsstelle für den vorgesehenen Tag erhöhen, dann + `pnpm plugins:sync` ausführen, damit veröffentlichbare Plugin-Pakete die Release- + Version und Kompatibilitätsmetadaten teilen, anschließend den lokalen deterministischen Preflight ausführen: `pnpm check:test-types`, `pnpm check:architecture`, `pnpm build && pnpm ui:build`, `pnpm plugins:sync:check` und `pnpm release:check`. 6. `OpenClaw NPM Release` mit `preflight_only=true` ausführen. Bevor ein Tag existiert, - ist ein vollständiger 40-stelliger Release-Branch-SHA für einen nur zur Validierung dienenden - Preflight erlaubt. Die erfolgreiche `preflight_run_id` speichern. + ist für einen reinen Validierungs-Preflight ein vollständiger Release-Branch-SHA mit 40 Zeichen erlaubt. + Die erfolgreiche `preflight_run_id` speichern. 7. Alle Pre-Release-Tests mit `Full Release Validation` für den - Release-Branch, das Tag oder den vollständigen Commit-SHA starten. Dies ist der einzige manuelle Einstiegspunkt + Release-Branch, Tag oder vollständigen Commit-SHA anstoßen. Dies ist der einzige manuelle Einstiegspunkt für die vier großen Release-Testboxen: Vitest, Docker, QA Lab und Package. -8. Wenn die Validierung fehlschlägt, auf dem Release-Branch fixen und die kleinste fehlgeschlagene - Datei, Lane, Workflow-Job, Paketprofil, Provider- oder Modell-Allowlist erneut ausführen, die - den Fix nachweist. Den gesamten Umbrella nur erneut ausführen, wenn die geänderte Oberfläche +8. Wenn die Validierung fehlschlägt, auf dem Release-Branch korrigieren und die kleinste fehlgeschlagene + Datei, Lane, den Workflow-Job, das Paketprofil, den Provider oder die Modell-Allowlist erneut ausführen, die + die Korrektur belegt. Das vollständige Umbrella nur erneut ausführen, wenn die geänderte Oberfläche frühere Nachweise veralten lässt. -9. Für Alpha oder Beta `vYYYY.M.D-alpha.N` oder `vYYYY.M.D-beta.N` taggen, dann `OpenClaw Release Publish` vom - passenden `release/YYYY.M.D`-Branch ausführen. Es verifiziert `pnpm plugins:sync:check`, - veröffentlicht zuerst alle veröffentlichbaren Plugin-Pakete nach npm, veröffentlicht dieselbe - Menge anschließend nach ClawHub und promotet dann das vorbereitete OpenClaw-npm-Preflight- - Artefakt mit dem passenden Dist-Tag. Nach der Veröffentlichung die Package-Acceptance nach dem Veröffentlichen - gegen das veröffentlichte Paket `openclaw@YYYY.M.D-alpha.N`, `openclaw@alpha`, - `openclaw@YYYY.M.D-beta.N` oder `openclaw@beta` ausführen. Wenn ein gepushter oder - veröffentlichter Prerelease einen Fix benötigt, die nächste passende Prerelease-Nummer erstellen; - den alten Prerelease nicht löschen oder umschreiben. -10. Für stable nur fortfahren, nachdem die geprüfte Beta oder der Release Candidate die +9. Für Beta `vYYYY.M.D-beta.N` taggen, dann `OpenClaw Release Publish` aus + dem passenden `release/YYYY.M.D`-Branch ausführen. Es prüft `pnpm plugins:sync:check`, + veröffentlicht zuerst alle veröffentlichbaren Plugin-Pakete nach npm, veröffentlicht denselben + Satz danach nach ClawHub und stuft anschließend das vorbereitete OpenClaw-npm-Preflight- + Artefakt mit dem passenden dist-tag hoch. Nach der Veröffentlichung die Paketakzeptanz nach der Veröffentlichung + gegen das veröffentlichte Paket `openclaw@YYYY.M.D-beta.N` oder + `openclaw@beta` ausführen. Wenn eine gepushte oder veröffentlichte Vorabversion eine Korrektur benötigt, + die nächste passende Vorabversionsnummer erstellen; die alte + Vorabversion nicht löschen oder umschreiben. +10. Für Stable nur fortfahren, nachdem die geprüfte Beta oder der Release Candidate die erforderlichen Validierungsnachweise hat. Die stabile npm-Veröffentlichung läuft ebenfalls über `OpenClaw Release Publish` und verwendet das erfolgreiche Preflight-Artefakt über - `preflight_run_id` erneut; die stabile macOS-Release-Bereitschaft erfordert außerdem die - paketierten `.zip`, `.dmg`, `.dSYM.zip` und die aktualisierte `appcast.xml` auf `main`. -11. Nach der Veröffentlichung den npm-Post-Publish-Verifier ausführen, optional eigenständige - veröffentlichte-npm-Telegram-E2E, wenn Sie Channel-Nachweise nach der Veröffentlichung benötigen, - Dist-Tag-Promotion bei Bedarf, GitHub-Release-/Prerelease-Notizen aus dem - vollständigen passenden Abschnitt in `CHANGELOG.md` und die Schritte zur Release-Ankündigung. + `preflight_run_id` wieder; die Bereitschaft des stabilen macOS-Releases erfordert außerdem die + paketierte `.zip`, `.dmg`, `.dSYM.zip` und die aktualisierte `appcast.xml` auf `main`. +11. Nach der Veröffentlichung den npm-Verifizierer nach der Veröffentlichung ausführen, optional das eigenständige + Telegram-E2E mit veröffentlichtem npm, wenn Sie einen Kanalnachweis nach der Veröffentlichung benötigen, + dist-tag-Hochstufung bei Bedarf, GitHub-Release-/Vorabversionshinweise aus dem + vollständigen passenden Abschnitt von `CHANGELOG.md` und die Schritte zur Release-Ankündigung. ## Release-Preflight -- Führen Sie `pnpm check:test-types` vor dem Release-Preflight aus, damit Test-TypeScript auch außerhalb des schnelleren lokalen `pnpm check`-Gates abgedeckt bleibt -- Führen Sie `pnpm check:architecture` vor dem Release-Preflight aus, damit die breiteren Importzyklus- und Architekturgrenzenprüfungen außerhalb des schnelleren lokalen Gates grün sind -- Führen Sie `pnpm build && pnpm ui:build` vor `pnpm release:check` aus, damit die erwarteten Release-Artefakte unter `dist/*` und das Control-UI-Bundle für den Pack-Validierungsschritt vorhanden sind -- Führen Sie `pnpm plugins:sync` nach dem Versionssprung im Root und vor dem Tagging aus. Es aktualisiert veröffentlichbare Plugin-Paketversionen, OpenClaw-Peer/API-Kompatibilitätsmetadaten, Build-Metadaten und Plugin-Changelog-Stubs passend zur Core-Release-Version. `pnpm plugins:sync:check` ist der nicht-mutierende Release-Guard; der Veröffentlichungsworkflow schlägt vor jeder Registry-Mutation fehl, wenn dieser Schritt vergessen wurde. -- Führen Sie den manuellen Workflow `Full Release Validation` vor der Release-Freigabe aus, um alle Pre-Release-Testboxen von einem Einstiegspunkt aus zu starten. Er akzeptiert einen Branch, Tag oder vollständigen Commit-SHA, dispatcht manuelles `CI` und dispatcht `OpenClaw Release Checks` für Install-Smoke, Package Acceptance, Docker-Release-Path-Suites, Live/E2E, OpenWebUI, QA-Lab-Parität, Matrix und Telegram-Lanes. Mit `release_profile=full` und `rerun_group=all` führt er außerdem Paket-Telegram-E2E gegen das Artefakt `release-package-under-test` aus den Release-Checks aus. Geben Sie `npm_telegram_package_spec` nach der Veröffentlichung an, wenn dieselbe Telegram-E2E auch das veröffentlichte npm-Paket nachweisen soll. Geben Sie `package_acceptance_package_spec` nach der Veröffentlichung an, wenn Package Acceptance seine Paket/Update-Matrix gegen das ausgelieferte npm-Paket statt gegen das aus dem SHA gebaute Artefakt ausführen soll. Geben Sie `evidence_package_spec` an, wenn der private Evidence-Bericht nachweisen soll, dass die Validierung zu einem veröffentlichten npm-Paket passt, ohne Telegram-E2E zu erzwingen. Beispiel: +- Führen Sie `pnpm check:test-types` vor dem Release-Preflight aus, damit Test-TypeScript außerhalb des schnelleren lokalen Gates `pnpm check` abgedeckt bleibt +- Führen Sie `pnpm check:architecture` vor dem Release-Preflight aus, damit die umfassenderen Prüfungen auf Importzyklen und Architekturgrenzen außerhalb des schnelleren lokalen Gates grün sind +- Führen Sie `pnpm build && pnpm ui:build` vor `pnpm release:check` aus, damit die erwarteten Release-Artefakte `dist/*` und das Control-UI-Bundle für den Paketvalidierungsschritt vorhanden sind +- Führen Sie `pnpm plugins:sync` nach dem Versions-Bump im Root und vor dem Tagging aus. Es aktualisiert die Versionen veröffentlichbarer Plugin-Pakete, OpenClaw-Peer-/API-Kompatibilitätsmetadaten, Build-Metadaten und Plugin-Changelog-Stubs passend zur Core-Release-Version. `pnpm plugins:sync:check` ist der nicht mutierende Release-Guard; der Publish-Workflow schlägt vor jeder Registry-Mutation fehl, wenn dieser Schritt vergessen wurde. +- Führen Sie den manuellen Workflow `Full Release Validation` vor der Release-Freigabe aus, um alle Pre-Release-Testboxen über einen Einstiegspunkt zu starten. Er akzeptiert einen Branch, ein Tag oder eine vollständige Commit-SHA, startet manuell `CI` und startet `OpenClaw Release Checks` für Install-Smoke, Package Acceptance, Docker-Release-Pfad-Suiten, Live/E2E, OpenWebUI, QA-Lab-Parität, Matrix- und Telegram-Lanes. Mit `release_profile=full` und `rerun_group=all` führt er außerdem Paket-Telegram-E2E gegen das Artefakt `release-package-under-test` aus den Release-Prüfungen aus. Geben Sie `npm_telegram_package_spec` nach der Veröffentlichung an, wenn dasselbe Telegram-E2E auch das veröffentlichte npm-Paket nachweisen soll. Geben Sie `package_acceptance_package_spec` nach der Veröffentlichung an, wenn Package Acceptance seine Paket-/Update-Matrix gegen das ausgelieferte npm-Paket statt gegen das aus der SHA gebaute Artefakt ausführen soll. Geben Sie `evidence_package_spec` an, wenn der private Evidenzbericht nachweisen soll, dass die Validierung einem veröffentlichten npm-Paket entspricht, ohne Telegram-E2E zu erzwingen. + Beispiel: `gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D` -- Führen Sie den manuellen Workflow `Package Acceptance` aus, wenn Sie Side-Channel-Nachweise für einen Paketkandidaten benötigen, während die Release-Arbeit weiterläuft. Verwenden Sie `source=npm` für `openclaw@alpha`, `openclaw@beta`, `openclaw@latest` oder eine exakte Release-Version; `source=ref`, um einen vertrauenswürdigen `package_ref`-Branch/Tag/SHA mit dem aktuellen `workflow_ref`-Harness zu packen; `source=url` für einen HTTPS-Tarball mit erforderlichem SHA-256; oder `source=artifact` für einen Tarball, der von einem anderen GitHub-Actions-Lauf hochgeladen wurde. Der Workflow löst den Kandidaten zu `package-under-test` auf, verwendet den Docker-E2E-Release-Scheduler gegen diesen Tarball erneut und kann Telegram-QA gegen denselben Tarball mit `telegram_mode=mock-openai` oder `telegram_mode=live-frontier` ausführen. Wenn die ausgewählten Docker-Lanes `published-upgrade-survivor` enthalten, ist das Paketartefakt der Kandidat und `published_upgrade_survivor_baseline` wählt die veröffentlichte Baseline. +- Führen Sie den manuellen Workflow `Package Acceptance` aus, wenn Sie einen Nebenkanal-Nachweis für einen Paketkandidaten möchten, während die Release-Arbeit weiterläuft. Verwenden Sie `source=npm` für `openclaw@beta`, `openclaw@latest` oder eine exakte Release-Version; `source=ref`, um einen vertrauenswürdigen `package_ref`-Branch/-Tag/-SHA mit dem aktuellen `workflow_ref`-Harness zu packen; `source=url` für einen HTTPS-Tarball mit erforderlicher SHA-256; oder `source=artifact` für einen Tarball, der von einem anderen GitHub-Actions-Lauf hochgeladen wurde. Der Workflow löst den Kandidaten zu `package-under-test` auf, verwendet den Docker-E2E-Release-Scheduler gegen diesen Tarball erneut und kann Telegram-QA gegen denselben Tarball mit `telegram_mode=mock-openai` oder `telegram_mode=live-frontier` ausführen. Wenn die ausgewählten Docker-Lanes `published-upgrade-survivor` enthalten, ist das Paketartefakt der Kandidat und `published_upgrade_survivor_baseline` wählt die veröffentlichte Baseline aus. Beispiel: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai` Häufige Profile: - - `smoke`: Installations-, Channel/Agent-, Gateway-Netzwerk- und Config-Reload-Lanes - - `package`: artefaktnative Paket/Update/Plugin-Lanes ohne OpenWebUI oder Live-ClawHub - - `product`: Paketprofil plus MCP-Channels, Cron/Subagent-Bereinigung, OpenAI-Websuche und OpenWebUI - - `full`: Docker-Release-Path-Chunks mit OpenWebUI - - `custom`: exakte `docker_lanes`-Auswahl für eine fokussierte Wiederholung -- Führen Sie den manuellen Workflow `CI` direkt aus, wenn Sie nur die vollständige normale CI-Abdeckung für den Release-Kandidaten benötigen. Manuelle CI-Dispatches umgehen Changed-Scoping und erzwingen die Linux-Node-Shards, Bundled-Plugin-Shards, Channel-Verträge, Node-22-Kompatibilität, `check`, `check-additional`, Build-Smoke, Docs-Checks, Python-Skills, Windows, macOS, Android und Control-UI-i18n-Lanes. + - `smoke`: Install-/Channel-/Agent-, Gateway-Netzwerk- und Config-Reload-Lanes + - `package`: artefaktnative Paket-/Update-/Plugin-Lanes ohne OpenWebUI oder Live-ClawHub + - `product`: Paketprofil plus MCP-Channels, Cron-/Subagent-Bereinigung, OpenAI-Websuche und OpenWebUI + - `full`: Docker-Release-Pfad-Chunks mit OpenWebUI + - `custom`: exakte Auswahl von `docker_lanes` für einen fokussierten erneuten Lauf +- Führen Sie den manuellen Workflow `CI` direkt aus, wenn Sie nur die vollständige normale CI-Abdeckung für den Release-Kandidaten benötigen. Manuelle CI-Starts umgehen das Changed-Scoping und erzwingen die Linux-Node-Shards, Bundled-Plugin-Shards, Channel-Verträge, Node-22-Kompatibilität, `check`, `check-additional`, Build-Smoke, Docs-Prüfungen, Python-Skills, Windows, macOS, Android und Control-UI-i18n-Lanes. Beispiel: `gh workflow run ci.yml --ref release/YYYY.M.D` -- Führen Sie `pnpm qa:otel:smoke` aus, wenn Sie Release-Telemetrie validieren. Es übt QA-Lab über einen lokalen OTLP/HTTP-Empfänger aus und verifiziert die exportierten Trace-Span-Namen, begrenzten Attribute und die Redaktion von Inhalten/Bezeichnern, ohne Opik, Langfuse oder einen anderen externen Collector zu benötigen. +- Führen Sie `pnpm qa:otel:smoke` aus, wenn Sie Release-Telemetrie validieren. Es führt QA-Lab über einen lokalen OTLP/HTTP-Empfänger aus und prüft die exportierten Trace-Span-Namen, begrenzte Attribute sowie Inhalts-/Kennungsredaktion, ohne Opik, Langfuse oder einen anderen externen Collector zu benötigen. - Führen Sie `pnpm release:check` vor jedem getaggten Release aus -- Führen Sie `OpenClaw Release Publish` für die mutierende Veröffentlichungssequenz aus, nachdem das Tag existiert. Dispatchen Sie ihn von `release/YYYY.M.D` (oder `main`, wenn ein von main erreichbares Tag veröffentlicht wird), übergeben Sie das Release-Tag und die erfolgreiche OpenClaw-npm-`preflight_run_id`, und behalten Sie den Standard-Plugin-Veröffentlichungsumfang `all-publishable` bei, sofern Sie nicht bewusst eine fokussierte Reparatur ausführen. Der Workflow serialisiert die Veröffentlichung von Plugin-npm, Plugin-ClawHub und OpenClaw-npm, damit das Core-Paket nicht vor seinen externalisierten Plugins veröffentlicht wird. -- Release-Checks laufen jetzt in einem separaten manuellen Workflow: +- Führen Sie `OpenClaw Release Publish` für die mutierende Publish-Sequenz aus, nachdem das Tag existiert. Starten Sie es von `release/YYYY.M.D` aus (oder von `main`, wenn ein von `main` erreichbares Tag veröffentlicht wird), übergeben Sie das Release-Tag und die erfolgreiche OpenClaw-npm-`preflight_run_id`, und behalten Sie den standardmäßigen Plugin-Publish-Scope `all-publishable` bei, sofern Sie nicht bewusst eine fokussierte Reparatur ausführen. Der Workflow serialisiert den Plugin-npm-Publish, den Plugin-ClawHub-Publish und den OpenClaw-npm-Publish, damit das Core-Paket nicht vor seinen externalisierten Plugins veröffentlicht wird. +- Release-Prüfungen laufen jetzt in einem separaten manuellen Workflow: `OpenClaw Release Checks` -- `OpenClaw Release Checks` führt vor der Release-Freigabe außerdem die QA-Lab-Mock-Paritäts-Lane plus das schnelle Live-Matrix-Profil und die Telegram-QA-Lane aus. Die Live-Lanes verwenden die Umgebung `qa-live-shared`; Telegram verwendet außerdem Convex-CI-Credential-Leases. Führen Sie den manuellen Workflow `QA-Lab - All Lanes` mit `matrix_profile=all` und `matrix_shards=true` aus, wenn Sie den vollständigen Matrix-Transport, Medien und E2EE-Inventar parallel benötigen. -- Cross-OS-Installations- und Upgrade-Laufzeitvalidierung ist Teil der öffentlichen `OpenClaw Release Checks` und `Full Release Validation`, die den wiederverwendbaren Workflow `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` direkt aufrufen -- Diese Aufteilung ist beabsichtigt: Der echte npm-Release-Pfad bleibt kurz, deterministisch und artefaktfokussiert, während langsamere Live-Checks in ihrer eigenen Lane bleiben, damit sie die Veröffentlichung nicht verzögern oder blockieren -- Release-Checks mit Secrets sollten über `Full Release Validation` oder vom `main`/Release-Workflow-Ref dispatcht werden, damit Workflow-Logik und Secrets kontrolliert bleiben -- `OpenClaw Release Checks` akzeptiert einen Branch, ein Tag oder einen vollständigen Commit-SHA, solange der aufgelöste Commit von einem OpenClaw-Branch oder Release-Tag erreichbar ist -- Der validierungsreine Preflight `OpenClaw NPM Release` akzeptiert auch den aktuellen vollständigen 40-Zeichen-Commit-SHA des Workflow-Branches, ohne ein gepushtes Tag zu verlangen -- Dieser SHA-Pfad ist nur für die Validierung und kann nicht in eine echte Veröffentlichung befördert werden -- Im SHA-Modus synthetisiert der Workflow `v` nur für die Paketmetadatenprüfung; echte Veröffentlichung erfordert weiterhin ein echtes Release-Tag -- Beide Workflows halten den echten Veröffentlichungs- und Promotion-Pfad auf GitHub-gehosteten Runnern, während der nicht-mutierende Validierungspfad die größeren Blacksmith-Linux-Runner verwenden kann -- Dieser Workflow führt `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` mit den beiden Workflow-Secrets `OPENAI_API_KEY` und `ANTHROPIC_API_KEY` aus +- `OpenClaw Release Checks` führt außerdem die QA-Lab-Mock-Paritäts-Lane sowie das schnelle Live-Matrix-Profil und die Telegram-QA-Lane vor der Release-Freigabe aus. Die Live-Lanes verwenden die Umgebung `qa-live-shared`; Telegram verwendet außerdem Convex-CI-Credential-Leases. Führen Sie den manuellen Workflow `QA-Lab - All Lanes` mit `matrix_profile=all` und `matrix_shards=true` aus, wenn Sie den vollständigen Matrix-Transport-, Medien- und E2EE-Bestand parallel prüfen möchten. +- Plattformübergreifende Installations- und Upgrade-Laufzeitvalidierung ist Teil der öffentlichen `OpenClaw Release Checks` und von `Full Release Validation`, die den wiederverwendbaren Workflow `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` direkt aufrufen +- Diese Aufteilung ist beabsichtigt: Halten Sie den echten npm-Release-Pfad kurz, deterministisch und artefaktfokussiert, während langsamere Live-Prüfungen in ihrer eigenen Lane bleiben, damit sie den Publish nicht aufhalten oder blockieren +- Release-Prüfungen mit Secrets sollten über `Full Release Validation` oder vom Workflow-Ref `main`/Release aus gestartet werden, damit Workflow-Logik und Secrets kontrolliert bleiben +- `OpenClaw Release Checks` akzeptiert einen Branch, ein Tag oder eine vollständige Commit-SHA, solange der aufgelöste Commit von einem OpenClaw-Branch oder Release-Tag erreichbar ist +- Der rein validierende Preflight von `OpenClaw NPM Release` akzeptiert außerdem die aktuelle vollständige 40-stellige Workflow-Branch-Commit-SHA, ohne ein gepushtes Tag zu verlangen +- Dieser SHA-Pfad dient nur der Validierung und kann nicht zu einem echten Publish befördert werden +- Im SHA-Modus synthetisiert der Workflow `v` nur für die Paketmetadatenprüfung; echter Publish erfordert weiterhin ein echtes Release-Tag +- Beide Workflows behalten den echten Publish- und Promotion-Pfad auf GitHub-gehosteten Runnern, während der nicht mutierende Validierungspfad die größeren Blacksmith-Linux-Runner verwenden kann +- Dieser Workflow führt + `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` + mit den Workflow-Secrets `OPENAI_API_KEY` und `ANTHROPIC_API_KEY` aus - Der npm-Release-Preflight wartet nicht mehr auf die separate Release-Checks-Lane -- Führen Sie `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` (oder das passende Beta/Korrektur-Tag) vor der Freigabe aus -- Führen Sie nach der npm-Veröffentlichung `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` (oder die passende Beta/Korrektur-Version) aus, um den veröffentlichten Registry-Installationspfad in einem frischen temporären Präfix zu verifizieren -- Führen Sie nach einer Beta-Veröffentlichung `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` aus, um Installed-Package-Onboarding, Telegram-Einrichtung und echte Telegram-E2E gegen das veröffentlichte npm-Paket mit dem gemeinsam geleasten Telegram-Credential-Pool zu verifizieren. Lokale Maintainer-Einmalprüfungen können die Convex-Variablen weglassen und die drei `OPENCLAW_QA_TELEGRAM_*`-Env-Credentials direkt übergeben. -- Maintainer können dieselbe Post-Publish-Prüfung über den manuellen Workflow `NPM Telegram Beta E2E` in GitHub Actions ausführen. Er ist absichtlich nur manuell und läuft nicht bei jedem Merge. +- Führen Sie `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` (oder das passende Beta-/Korrektur-Tag) vor der Freigabe aus +- Führen Sie nach dem npm-Publish + `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` + (oder die passende Beta-/Korrekturversion) aus, um den veröffentlichten Registry-Installationspfad in einem frischen temporären Prefix zu prüfen +- Führen Sie nach einem Beta-Publish `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` aus, um Installed-Package-Onboarding, Telegram-Einrichtung und echtes Telegram-E2E gegen das veröffentlichte npm-Paket mit dem gemeinsam genutzten geleasten Telegram-Credential-Pool zu prüfen. Lokale einmalige Maintainer-Läufe können die Convex-Variablen weglassen und die drei `OPENCLAW_QA_TELEGRAM_*`-Env-Credentials direkt übergeben. +- Maintainer können dieselbe Post-Publish-Prüfung über den manuellen Workflow `NPM Telegram Beta E2E` aus GitHub Actions ausführen. Er ist bewusst ausschließlich manuell und läuft nicht bei jedem Merge. - Maintainer-Release-Automatisierung verwendet jetzt Preflight-dann-Promote: - - echte npm-Veröffentlichung muss eine erfolgreiche npm-`preflight_run_id` bestehen - - die echte npm-Veröffentlichung muss vom selben `main`- oder `release/YYYY.M.D`-Branch wie der erfolgreiche Preflight-Lauf dispatcht werden + - echter npm-Publish muss eine erfolgreiche npm-`preflight_run_id` bestehen + - der echte npm-Publish muss von demselben `main`- oder `release/YYYY.M.D`-Branch gestartet werden wie der erfolgreiche Preflight-Lauf - stabile npm-Releases verwenden standardmäßig `beta` - - stabile npm-Veröffentlichung kann über Workflow-Eingabe explizit `latest` ansteuern - - tokenbasierte npm-Dist-Tag-Mutation befindet sich aus Sicherheitsgründen jetzt in `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`, weil `npm dist-tag add` weiterhin `NPM_TOKEN` benötigt, während das öffentliche Repo nur OIDC-Veröffentlichung beibehält - - öffentliches `macOS Release` dient nur der Validierung; wenn ein Tag nur auf einem Release-Branch existiert, der Workflow aber von `main` dispatcht wird, setzen Sie `public_release_branch=release/YYYY.M.D` - - echte private Mac-Veröffentlichung muss erfolgreiche private Mac-`preflight_run_id` und `validate_run_id` bestehen - - die echten Veröffentlichungspfade promoten vorbereitete Artefakte, statt sie erneut zu bauen -- Für stabile Korrektur-Releases wie `YYYY.M.D-N` prüft der Post-Publish-Verifier außerdem denselben Upgrade-Pfad mit temporärem Präfix von `YYYY.M.D` zu `YYYY.M.D-N`, damit Release-Korrekturen ältere globale Installationen nicht still auf dem Basis-Stable-Payload belassen können -- Der npm-Release-Preflight schlägt geschlossen fehl, sofern der Tarball nicht sowohl `dist/control-ui/index.html` als auch einen nicht leeren `dist/control-ui/assets/`-Payload enthält, damit wir nicht erneut ein leeres Browser-Dashboard ausliefern -- Die Post-Publish-Verifizierung prüft außerdem, dass veröffentlichte Plugin-Einstiegspunkte und Paketmetadaten im installierten Registry-Layout vorhanden sind. Ein Release, das fehlende Plugin-Runtime-Payloads ausliefert, schlägt im Postpublish-Verifier fehl und kann nicht zu `latest` promotet werden. -- `pnpm test:install:smoke` erzwingt außerdem das npm-Pack-`unpackedSize`-Budget für den Kandidaten-Update-Tarball, damit Installer-E2E versehentlichen Pack-Bloat vor dem Release-Veröffentlichungspfad findet -- Wenn die Release-Arbeit CI-Planung, Timing-Manifeste von Erweiterungen oder Testmatrizen von Erweiterungen berührt hat, generieren und prüfen Sie die planer-eigenen `plugin-prerelease-extension-shard`-Matrixausgaben aus `.github/workflows/plugin-prerelease.yml` vor der Freigabe neu, damit Release Notes kein veraltetes CI-Layout beschreiben -- Zur Bereitschaft eines stabilen macOS-Release gehören außerdem die Updater-Oberflächen: + - stabiler npm-Publish kann über Workflow-Eingabe explizit auf `latest` zielen + - tokenbasierte npm-Dist-Tag-Mutation liegt aus Sicherheitsgründen jetzt in `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`, da `npm dist-tag add` weiterhin `NPM_TOKEN` benötigt, während das öffentliche Repo OIDC-only-Publish beibehält + - öffentliches `macOS Release` ist nur validierend; wenn ein Tag nur auf einem Release-Branch liegt, der Workflow aber von `main` gestartet wird, setzen Sie `public_release_branch=release/YYYY.M.D` + - echter privater Mac-Publish muss erfolgreiche private Mac-`preflight_run_id` und `validate_run_id` bestehen + - die echten Publish-Pfade promoten vorbereitete Artefakte, statt sie erneut zu bauen +- Für stabile Korrektur-Releases wie `YYYY.M.D-N` prüft der Post-Publish-Verifier außerdem denselben Temp-Prefix-Upgrade-Pfad von `YYYY.M.D` zu `YYYY.M.D-N`, damit Release-Korrekturen ältere globale Installationen nicht stillschweigend auf dem stabilen Basis-Payload zurücklassen können +- Der npm-Release-Preflight schlägt geschlossen fehl, sofern der Tarball nicht sowohl `dist/control-ui/index.html` als auch einen nicht leeren Payload `dist/control-ui/assets/` enthält, damit wir nicht erneut ein leeres Browser-Dashboard ausliefern +- Die Post-Publish-Verifizierung prüft außerdem, dass veröffentlichte Plugin-Entry-Points und Paketmetadaten im installierten Registry-Layout vorhanden sind. Ein Release, das fehlende Plugin-Laufzeit-Payloads ausliefert, lässt den Postpublish-Verifier fehlschlagen und kann nicht zu `latest` promotet werden. +- `pnpm test:install:smoke` erzwingt außerdem das npm-Pack-`unpackedSize`-Budget für den Kandidaten-Update-Tarball, sodass Installer-E2E versehentlichen Pack-Bloat vor dem Release-Publish-Pfad erkennt +- Wenn die Release-Arbeit CI-Planung, Extension-Timing-Manifeste oder Extension-Testmatrizen berührt hat, regenerieren und prüfen Sie vor der Freigabe die Planner-eigenen `plugin-prerelease-extension-shard`-Matrixausgaben aus `.github/workflows/plugin-prerelease.yml`, damit Release Notes kein veraltetes CI-Layout beschreiben +- Die Bereitschaft für stabile macOS-Releases umfasst außerdem die Updater-Flächen: - das GitHub-Release muss am Ende die gepackten `.zip`, `.dmg` und `.dSYM.zip` enthalten - - `appcast.xml` auf `main` muss nach der Veröffentlichung auf das neue stabile Zip zeigen - - die gepackte App muss eine Nicht-Debug-Bundle-ID, eine nicht leere Sparkle-Feed-URL und eine `CFBundleVersion` auf oder über dem kanonischen Sparkle-Build-Floor für diese Release-Version behalten + - `appcast.xml` auf `main` muss nach dem Publish auf das neue stabile Zip verweisen + - die gepackte App muss eine Nicht-Debug-Bundle-ID, eine nicht leere Sparkle-Feed-URL und eine `CFBundleVersion` auf oder über dem kanonischen Sparkle-Build-Minimum für diese Release-Version behalten ## Release-Testboxen -`Full Release Validation` ist der Weg, wie Operators alle Pre-Release-Tests von einem Einstiegspunkt aus starten. Für einen Pinned-Commit-Nachweis auf einem schnelllebigen Branch verwenden Sie den Helper, damit jeder Child-Workflow von einem temporären Branch läuft, der auf den Ziel-SHA fixiert ist: +`Full Release Validation` ist die Methode, mit der Operatoren alle Pre-Release-Tests über einen Einstiegspunkt starten. Für einen gepinnten Commit-Nachweis auf einem schnell bewegten Branch verwenden Sie den Helper, damit jeder Child-Workflow von einem temporären Branch läuft, der auf die Ziel-SHA fixiert ist: ```bash pnpm ci:full-release --sha ``` -Der Helper pusht `release-ci/-...`, dispatcht `Full Release Validation` von diesem Branch mit `ref=`, verifiziert, dass jeder Child-Workflow-`headSha` dem Ziel entspricht, und löscht dann den temporären Branch. So wird vermieden, versehentlich einen neueren `main`-Child-Lauf nachzuweisen. +Der Helper pusht `release-ci/-...`, startet `Full Release Validation` von diesem Branch mit `ref=`, prüft, dass jede Child-Workflow-`headSha` dem Ziel entspricht, und löscht anschließend den temporären Branch. Dadurch wird vermieden, versehentlich einen neueren `main`-Child-Lauf nachzuweisen. -Für die Validierung von Release-Branch oder Tag führen Sie ihn vom vertrauenswürdigen `main`-Workflow-Ref aus und übergeben den Release-Branch oder das Tag als `ref`: +Für Release-Branch- oder Tag-Validierung führen Sie ihn vom vertrauenswürdigen Workflow-Ref `main` aus und übergeben den Release-Branch oder das Tag als `ref`: ```bash gh workflow run full-release-validation.yml \ @@ -184,41 +185,49 @@ gh workflow run full-release-validation.yml \ -f evidence_package_spec=openclaw@YYYY.M.D-beta.N ``` -Der Workflow löst die Ziel-Ref auf, startet manuell `CI` mit -`target_ref=`, startet `OpenClaw Release Checks` und startet -eigenständige Package-Telegram-E2E, wenn `release_profile=full` mit -`rerun_group=all` verwendet wird oder wenn `npm_telegram_package_spec` gesetzt -ist. `OpenClaw Release Checks` verzweigt dann in Install-Smoke, Cross-OS-Release-Checks, Live-/E2E-Docker-Abdeckung für den Release-Pfad, Package Acceptance mit Telegram-Package-QA, QA-Lab-Parität, Live-Matrix und Live-Telegram. Ein vollständiger Lauf ist nur akzeptabel, wenn die -Zusammenfassung von `Full Release Validation` -`normal_ci` und `release_checks` als erfolgreich ausweist. Im full/all-Modus -muss auch das untergeordnete `npm_telegram` erfolgreich sein; außerhalb von -full/all wird es übersprungen, sofern kein veröffentlichtes -`npm_telegram_package_spec` angegeben wurde. Die abschließende -Verifiziererzusammenfassung enthält Tabellen der langsamsten Jobs für jeden untergeordneten Lauf, sodass die Release-Verantwortlichen den aktuellen kritischen Pfad sehen können, ohne Logs herunterladen zu müssen. -Siehe [vollständige Release-Validierung](/de/reference/full-release-validation) für die -vollständige Phasenmatrix, die exakten Workflow-Jobnamen, Unterschiede zwischen stabilem und vollständigem Profil, Artefakte und gezielte Rerun-Handles. -Untergeordnete Workflows werden von der vertrauenswürdigen Ref gestartet, die -`Full Release Validation` ausführt, normalerweise `--ref main`, selbst wenn die Ziel-`ref` auf einen -älteren Release-Branch oder Tag zeigt. Es gibt keine separate Workflow-Ref-Eingabe für Full Release Validation; wählen Sie das vertrauenswürdige Harness, indem Sie die Ref des Workflow-Laufs wählen. -Verwenden Sie `--ref main -f ref=` nicht für exakten Commit-Nachweis auf beweglichem `main`; -rohe Commit-SHAs können keine Workflow-Dispatch-Refs sein. Verwenden Sie daher -`pnpm ci:full-release --sha `, um den angehefteten temporären Branch zu erstellen. +Der Workflow löst den Ziel-Ref auf, dispatcht manuell `CI` mit +`target_ref=`, dispatcht `OpenClaw Release Checks` und dispatcht +eigenständige Telegram-Paket-E2E, wenn `release_profile=full` mit +`rerun_group=all` gesetzt ist oder wenn `npm_telegram_package_spec` gesetzt ist. +`OpenClaw Release Checks` verzweigt dann in Install-Smoke, Cross-OS-Release-Checks, +Live/E2E-Docker-Abdeckung des Release-Pfads, Package Acceptance mit Telegram-Paket-QA, +QA-Lab-Parität, Live-Matrix und Live-Telegram. Ein vollständiger Lauf ist nur +akzeptabel, wenn die Zusammenfassung von `Full Release Validation` `normal_ci` +und `release_checks` als erfolgreich anzeigt. Im full/all-Modus muss auch der +`npm_telegram`-Child erfolgreich sein; außerhalb von full/all wird er übersprungen, +sofern kein veröffentlichtes `npm_telegram_package_spec` bereitgestellt wurde. +Die abschließende Verifier-Zusammenfassung enthält Tabellen der langsamsten Jobs +für jeden Child-Lauf, sodass der Release-Manager den aktuellen kritischen Pfad +sehen kann, ohne Logs herunterzuladen. +Siehe [Vollständige Release-Validierung](/de/reference/full-release-validation) für +die vollständige Stage-Matrix, exakte Workflow-Jobnamen, Unterschiede zwischen +stable- und full-Profilen, Artefakte und gezielte Rerun-Handles. +Child-Workflows werden von dem vertrauenswürdigen Ref dispatched, der +`Full Release Validation` ausführt, normalerweise `--ref main`, selbst wenn der +Ziel-`ref` auf einen älteren Release-Branch oder Tag zeigt. Es gibt keine separate +Workflow-Ref-Eingabe für Full Release Validation; wählen Sie den vertrauenswürdigen +Harness, indem Sie den Ref des Workflow-Laufs wählen. Verwenden Sie nicht +`--ref main -f ref=` für exakte Commit-Nachweise auf einem sich bewegenden +`main`; rohe Commit-SHAs können keine Workflow-Dispatch-Refs sein. Verwenden Sie +daher `pnpm ci:full-release --sha `, um den gepinnten temporären Branch zu +erstellen. Verwenden Sie `release_profile`, um die Breite von Live/Provider auszuwählen: -- `minimum`: schnellster release-kritischer OpenAI-/Core-Live- und Docker-Pfad -- `stable`: Minimum plus stabile Provider-/Backend-Abdeckung für Release-Freigabe -- `full`: Stable plus breite Abdeckung für beratende Provider/Medien +- `minimum`: schnellster releasekritischer OpenAI/Core-Live- und Docker-Pfad +- `stable`: minimum plus stabile Provider-/Backend-Abdeckung für die Release-Freigabe +- `full`: stable plus breite advisory Provider-/Media-Abdeckung -`OpenClaw Release Checks` verwendet die vertrauenswürdige Workflow-Ref, um die Ziel-Ref -einmal als `release-package-under-test` aufzulösen, und verwendet dieses Artefakt sowohl in -Docker-Checks für den Release-Pfad als auch in Package Acceptance wieder. Dadurch bleiben alle -package-seitigen Boxen auf denselben Bytes und wiederholte Package-Builds werden vermieden. -Der Cross-OS-OpenAI-Install-Smoke verwendet `OPENCLAW_CROSS_OS_OPENAI_MODEL`, wenn die -Repo-/Org-Variable gesetzt ist, andernfalls `openai/gpt-5.4`, weil diese Lane -Package-Installation, Onboarding, Gateway-Start und eine Live-Agent-Runde nachweist, -statt das langsamste Standardmodell zu benchmarken. Die breitere Live-Provider-Matrix -bleibt der Ort für modellspezifische Abdeckung. +`OpenClaw Release Checks` verwendet den vertrauenswürdigen Workflow-Ref, um den +Ziel-Ref einmal als `release-package-under-test` aufzulösen, und verwendet dieses +Artefakt sowohl in Docker-Checks des Release-Pfads als auch in Package Acceptance +wieder. Dadurch bleiben alle packagebezogenen Boxen auf denselben Bytes, und +wiederholte Paket-Builds werden vermieden. Der Cross-OS-OpenAI-Install-Smoke +verwendet `OPENCLAW_CROSS_OS_OPENAI_MODEL`, wenn die Repo-/Org-Variable gesetzt +ist, andernfalls `openai/gpt-5.4`, weil diese Lane Paketinstallation, Onboarding, +Gateway-Start und einen Live-Agent-Turn nachweist, statt das langsamste +Standardmodell zu benchmarken. Die breitere Live-Provider-Matrix bleibt der Ort +für modellspezifische Abdeckung. Verwenden Sie diese Varianten je nach Release-Phase: @@ -250,36 +259,46 @@ gh workflow run full-release-validation.yml \ -f npm_telegram_provider_mode=mock-openai ``` -Verwenden Sie den vollständigen Umbrella nicht als ersten Rerun nach einem gezielten Fix. Wenn eine Box -fehlschlägt, verwenden Sie für den nächsten Nachweis den fehlgeschlagenen untergeordneten Workflow, Job, Docker-Lane, Package-Profil, Modell-Provider oder QA-Lane. Führen Sie den vollständigen Umbrella nur erneut aus, wenn -der Fix die gemeinsame Release-Orchestrierung geändert oder frühere All-Box-Evidence -veraltet gemacht hat. Der abschließende Verifizierer des Umbrella prüft die aufgezeichneten IDs untergeordneter Workflow-Läufe erneut. Nachdem ein untergeordneter Workflow erfolgreich erneut ausgeführt wurde, führen Sie daher nur den fehlgeschlagenen übergeordneten Job -`Verify full validation` erneut aus. +Verwenden Sie den vollständigen Umbrella-Lauf nicht als ersten Rerun nach einem +gezielten Fix. Wenn eine Box fehlschlägt, verwenden Sie für den nächsten Nachweis +den fehlgeschlagenen Child-Workflow, Job, die Docker-Lane, das Paketprofil, den +Modell-Provider oder die QA-Lane. Führen Sie den vollständigen Umbrella-Lauf nur +dann erneut aus, wenn der Fix die gemeinsame Release-Orchestrierung geändert hat +oder frühere All-Box-Nachweise veraltet gemacht hat. Der abschließende Verifier +des Umbrella-Laufs prüft die aufgezeichneten Child-Workflow-Run-IDs erneut. +Nachdem ein Child-Workflow erfolgreich erneut ausgeführt wurde, führen Sie daher +nur den fehlgeschlagenen Parent-Job `Verify full validation` erneut aus. -Für begrenzte Wiederherstellung übergeben Sie `rerun_group` an den Umbrella. `all` ist der echte -Release-Candidate-Lauf, `ci` führt nur das normale CI-Child aus, `plugin-prerelease` -führt nur das release-only Plugin-Child aus, `release-checks` führt jede Release-Box aus, und die engeren Release-Gruppen sind `install-smoke`, `cross-os`, -`live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` und `npm-telegram`. -Gezielte `npm-telegram`-Reruns erfordern `npm_telegram_package_spec`; full/all-Läufe -mit `release_profile=full` verwenden das Package-Artefakt aus release-checks. +Für begrenzte Wiederherstellung übergeben Sie `rerun_group` an den Umbrella-Lauf. +`all` ist der echte Release-Candidate-Lauf, `ci` führt nur den normalen CI-Child +aus, `plugin-prerelease` führt nur den releasebezogenen Plugin-Child aus, +`release-checks` führt jede Release-Box aus, und die engeren Release-Gruppen sind +`install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` +und `npm-telegram`. Gezielte `npm-telegram`-Reruns erfordern +`npm_telegram_package_spec`; full/all-Läufe mit `release_profile=full` verwenden +das Paketartefakt aus den Release-Checks. ### Vitest -Die Vitest-Box ist der manuelle untergeordnete `CI`-Workflow. Manuelles CI umgeht absichtlich -Changed-Scoping und erzwingt den normalen Testgraphen für den Release -Candidate: Linux-Node-Shards, gebündelte Plugin-Shards, Channel-Contracts, Node-22-Kompatibilität, `check`, `check-additional`, Build-Smoke, Docs-Checks, Python-Skills, Windows, macOS, Android und Control-UI-i18n. +Die Vitest-Box ist der manuelle `CI`-Child-Workflow. Manuelle CI umgeht bewusst +Changed-Scoping und erzwingt den normalen Testgraphen für den Release-Kandidaten: +Linux-Node-Shards, gebündelte Plugin-Shards, Kanalverträge, Node-22-Kompatibilität, +`check`, `check-additional`, Build-Smoke, Docs-Checks, Python-Skills, Windows, +macOS, Android und Control-UI-i18n. -Verwenden Sie diese Box, um zu beantworten: „Hat der Source Tree die vollständige normale Testsuite bestanden?“ -Sie ist nicht dasselbe wie Produktvalidierung für den Release-Pfad. Aufzubewahrende Evidence: +Verwenden Sie diese Box, um zu beantworten: „Hat der Quellbaum die vollständige +normale Testsuite bestanden?“ Sie ist nicht dasselbe wie Produktvalidierung über +den Release-Pfad. Aufzubewahrende Nachweise: -- Zusammenfassung von `Full Release Validation`, die die URL des gestarteten `CI`-Laufs zeigt -- grüner `CI`-Lauf auf dem exakten Ziel-SHA +- Zusammenfassung von `Full Release Validation` mit der URL des dispatched `CI`-Laufs +- grüner `CI`-Lauf auf der exakten Ziel-SHA - Namen fehlgeschlagener oder langsamer Shards aus den CI-Jobs bei der Untersuchung von Regressionen -- Vitest-Timing-Artefakte wie `.artifacts/vitest-shard-timings.json`, wenn - ein Lauf Performance-Analyse benötigt +- Vitest-Timing-Artefakte wie `.artifacts/vitest-shard-timings.json`, wenn ein + Lauf eine Performance-Analyse benötigt -Führen Sie manuelles CI nur direkt aus, wenn der Release deterministisches normales CI benötigt, aber -nicht die Docker-, QA-Lab-, Live-, Cross-OS- oder Package-Boxen: +Führen Sie manuelle CI nur dann direkt aus, wenn das Release deterministische +normale CI benötigt, aber nicht die Docker-, QA-Lab-, Live-, Cross-OS- oder +Paket-Boxen: ```bash gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D @@ -288,17 +307,18 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D ### Docker Die Docker-Box befindet sich in `OpenClaw Release Checks` über -`openclaw-live-and-e2e-checks-reusable.yml` plus dem Release-Modus-Workflow -`install-smoke`. Sie validiert den Release Candidate durch paketierte -Docker-Umgebungen statt nur durch Source-Level-Tests. +`openclaw-live-and-e2e-checks-reusable.yml` sowie im Release-Modus-Workflow +`install-smoke`. Sie validiert den Release-Kandidaten über paketierte +Docker-Umgebungen statt nur über Tests auf Quellcodeebene. -Die Docker-Abdeckung für Releases umfasst: +Die Release-Docker-Abdeckung umfasst: -- vollständigen Install-Smoke mit aktiviertem langsamem globalem Bun-Install-Smoke -- Vorbereitung/Wiederverwendung des Root-Dockerfile-Smoke-Images nach Ziel-SHA, wobei QR-, - Root-/Gateway- und Installer-/Bun-Smoke-Jobs als separate Install-Smoke-Shards laufen +- vollständigen Install-Smoke mit aktiviertem langsamen globalen Bun-Install-Smoke +- Vorbereitung/Wiederverwendung des Root-Dockerfile-Smoke-Images nach Ziel-SHA, + wobei QR-, Root/Gateway- und Installer/Bun-Smoke-Jobs als separate + install-smoke-Shards laufen - Repository-E2E-Lanes -- Docker-Chunks für den Release-Pfad: `core`, `package-update-openai`, +- Docker-Chunks des Release-Pfads: `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, `plugins-runtime-install-a`, `plugins-runtime-install-b`, @@ -309,90 +329,95 @@ Die Docker-Abdeckung für Releases umfasst: - aufgeteilte Install-/Uninstall-Lanes für gebündelte Plugins `bundled-plugin-install-uninstall-0` bis `bundled-plugin-install-uninstall-23` -- Live-/E2E-Provider-Suiten und Docker-Live-Modellabdeckung, wenn Release-Checks - Live-Suiten enthalten +- Live/E2E-Provider-Suites und Docker-Live-Modellabdeckung, wenn Release-Checks + Live-Suites einschließen -Verwenden Sie Docker-Artefakte vor einem Rerun. Der Release-Pfad-Scheduler lädt -`.artifacts/docker-tests/` mit Lane-Logs, `summary.json`, `failures.json`, -Phasen-Timings, Scheduler-Plan-JSON und Rerun-Befehlen hoch. Für gezielte Wiederherstellung -verwenden Sie `docker_lanes=` im wiederverwendbaren Live-/E2E-Workflow, statt -alle Release-Chunks erneut auszuführen. Generierte Rerun-Befehle enthalten vorherige -`package_artifact_run_id` und vorbereitete Docker-Image-Eingaben, wenn verfügbar, sodass eine -fehlgeschlagene Lane denselben Tarball und dieselben GHCR-Images wiederverwenden kann. +Verwenden Sie Docker-Artefakte vor einem Rerun. Der Scheduler des Release-Pfads +lädt `.artifacts/docker-tests/` mit Lane-Logs, `summary.json`, `failures.json`, +Phasen-Timings, Scheduler-Plan-JSON und Rerun-Befehlen hoch. Für gezielte +Wiederherstellung verwenden Sie `docker_lanes=` im wiederverwendbaren +Live/E2E-Workflow, statt alle Release-Chunks erneut auszuführen. Generierte +Rerun-Befehle enthalten frühere `package_artifact_run_id`- und vorbereitete +Docker-Image-Eingaben, wenn verfügbar, sodass eine fehlgeschlagene Lane denselben +Tarball und dieselben GHCR-Images wiederverwenden kann. ### QA Lab -Die QA-Lab-Box ist ebenfalls Teil von `OpenClaw Release Checks`. Sie ist das agentische -Verhaltens- und Channel-Level-Release-Gate, getrennt von Vitest und Docker- -Package-Mechanik. +Die QA-Lab-Box ist ebenfalls Teil von `OpenClaw Release Checks`. Sie ist das +Release-Gate für agentisches Verhalten und Kanalebene, getrennt von Vitest und +Docker-Paketmechanik. -Die QA-Lab-Abdeckung für Releases umfasst: +Die Release-QA-Lab-Abdeckung umfasst: -- Mock-Paritäts-Lane, die die OpenAI-Candidate-Lane mit der Opus-4.6- - Baseline unter Verwendung des agentischen Paritätspakets vergleicht +- Mock-Parity-Lane, die die OpenAI-Kandidaten-Lane mit der Opus-4.6-Baseline + mithilfe des agentischen Parity-Packs vergleicht - schnelles Live-Matrix-QA-Profil mit der Umgebung `qa-live-shared` - Live-Telegram-QA-Lane mit Convex-CI-Credential-Leases - `pnpm qa:otel:smoke`, wenn Release-Telemetrie expliziten lokalen Nachweis benötigt -Verwenden Sie diese Box, um zu beantworten: „Verhält sich der Release in QA-Szenarien und -Live-Channel-Flows korrekt?“ Bewahren Sie die Artefakt-URLs für Paritäts-, Matrix- und Telegram- -Lanes auf, wenn Sie den Release freigeben. Vollständige Matrix-Abdeckung bleibt als -manueller, geshardeter QA-Lab-Lauf verfügbar, nicht als standardmäßige release-kritische Lane. +Verwenden Sie diese Box, um zu beantworten: „Verhält sich das Release in +QA-Szenarien und Live-Kanalflüssen korrekt?“ Bewahren Sie die Artefakt-URLs für +Parity-, Matrix- und Telegram-Lanes auf, wenn Sie das Release freigeben. +Vollständige Matrix-Abdeckung bleibt als manueller geshardeter QA-Lab-Lauf +verfügbar und ist nicht die standardmäßige releasekritische Lane. -### Package +### Paket -Die Package-Box ist das Gate für das installierbare Produkt. Sie wird von -`Package Acceptance` und dem Resolver -`scripts/resolve-openclaw-package-candidate.mjs` gestützt. Der Resolver normalisiert einen -Candidate in den `package-under-test`-Tarball, der von Docker E2E konsumiert wird, validiert -das Package-Inventar, zeichnet die Package-Version und SHA-256 auf und hält die -Workflow-Harness-Ref getrennt von der Package-Source-Ref. +Die Paket-Box ist das Gate für das installierbare Produkt. Sie wird durch +`Package Acceptance` und den Resolver `scripts/resolve-openclaw-package-candidate.mjs` +gestützt. Der Resolver normalisiert einen Kandidaten in den Tarball +`package-under-test`, der von Docker E2E konsumiert wird, validiert das +Paketinventar, zeichnet Paketversion und SHA-256 auf und hält den +Workflow-Harness-Ref vom Paketquell-Ref getrennt. -Unterstützte Candidate-Quellen: +Unterstützte Kandidatenquellen: -- `source=npm`: `openclaw@beta`, `openclaw@latest` oder eine exakte OpenClaw-Release- - Version -- `source=ref`: einen vertrauenswürdigen `package_ref`-Branch, Tag oder vollständigen Commit-SHA - mit dem ausgewählten `workflow_ref`-Harness packen -- `source=url`: eine HTTPS-`.tgz` mit erforderlichem `package_sha256` herunterladen -- `source=artifact`: eine von einem anderen GitHub-Actions-Lauf hochgeladene `.tgz` wiederverwenden +- `source=npm`: `openclaw@beta`, `openclaw@latest` oder eine exakte OpenClaw-Release-Version +- `source=ref`: einen vertrauenswürdigen `package_ref`-Branch, Tag oder vollständige + Commit-SHA mit dem ausgewählten `workflow_ref`-Harness packen +- `source=url`: ein HTTPS-`.tgz` mit erforderlichem `package_sha256` herunterladen +- `source=artifact`: ein von einem anderen GitHub-Actions-Lauf hochgeladenes `.tgz` wiederverwenden `OpenClaw Release Checks` führt Package Acceptance mit `source=artifact`, dem -vorbereiteten Release-Package-Artefakt, `suite_profile=custom`, +vorbereiteten Release-Paketartefakt, `suite_profile=custom`, `docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`, `published_upgrade_survivor_baselines=all-since-2026.4.23`, `published_upgrade_survivor_scenarios=reported-issues` und -`telegram_mode=mock-openai` aus. Package Acceptance hält Migration, Update, Bereinigung veralteter -Plugin-Abhängigkeiten, Offline-Plugin-Fixtures, Plugin-Update und Telegram- -Package-QA gegen denselben aufgelösten Tarball. Die Upgrade-Matrix deckt jede stabil npm-veröffentlichte Baseline von `2026.4.23` bis `latest` ab; verwenden Sie -Package Acceptance mit `source=npm` für einen bereits ausgelieferten Candidate oder -`source=ref`/`source=artifact` für einen SHA-gestützten lokalen npm-Tarball vor der -Veröffentlichung. Sie ist der GitHub-native -Ersatz für den Großteil der Package-/Update-Abdeckung, die zuvor Parallels erforderte. -Cross-OS-Release-Checks bleiben für OS-spezifisches Onboarding, -Installer- und Plattformverhalten wichtig, aber Package-/Update-Produktvalidierung sollte -Package Acceptance bevorzugen. +`telegram_mode=mock-openai` aus. Package Acceptance hält Migration, Update, +Bereinigung veralteter Plugin-Abhängigkeiten, Offline-Plugin-Fixtures, +Plugin-Update und Telegram-Paket-QA gegen denselben aufgelösten Tarball. Die +Upgrade-Matrix deckt jede stabile npm-veröffentlichte Baseline von `2026.4.23` +bis `latest` ab; verwenden Sie Package Acceptance mit `source=npm` für einen +bereits ausgelieferten Kandidaten oder `source=ref`/`source=artifact` für einen +SHA-gestützten lokalen npm-Tarball vor der Veröffentlichung. Sie ist der +GitHub-native Ersatz für den größten Teil der Paket-/Update-Abdeckung, die zuvor +Parallels erforderte. Cross-OS-Release-Checks bleiben für OS-spezifisches +Onboarding, Installer- und Plattformverhalten wichtig, aber Paket-/Update- +Produktvalidierung sollte Package Acceptance bevorzugen. Die kanonische Checkliste für Update- und Plugin-Validierung ist -[Updates und Plugins testen](/de/help/testing-updates-plugins). Verwenden Sie sie, wenn Sie -entscheiden, welche lokale, Docker-, Package-Acceptance- oder Release-Check-Lane eine -Plugin-Installation/ein Plugin-Update, Doctor-Cleanup oder eine veröffentlichte Package-Migrationsänderung nachweist. -Erschöpfende veröffentlichte Update-Migration aus jedem stabilen Package `2026.4.23+` ist -ein separater manueller Workflow `Update Migration` und nicht Teil von Full Release CI. +[Updates und Plugins testen](/de/help/testing-updates-plugins). Verwenden Sie sie, +wenn Sie entscheiden, welche lokale Lane, Docker-Lane, Package-Acceptance-Lane +oder Release-Check-Lane eine Plugin-Installation/ein Plugin-Update, +Doctor-Cleanup oder eine Änderung der Migration veröffentlichter Pakete nachweist. +Erschöpfende veröffentlichte Update-Migration aus jedem stabilen Paket +`2026.4.23+` ist ein separater manueller Workflow `Update Migration` und nicht +Teil von Full Release CI. -Legacy-Nachsicht bei Package Acceptance ist absichtlich zeitlich begrenzt. Packages bis -`2026.4.25` dürfen den Kompatibilitätspfad für bereits auf npm veröffentlichte Metadatenlücken -verwenden: private QA-Inventareinträge, die im Tarball fehlen, fehlendes -`gateway install --wrapper`, fehlende Patch-Dateien im aus dem Tarball abgeleiteten Git- -Fixture, fehlendes persistiertes `update.channel`, Legacy-Plugin-Install-Record- -Speicherorte, fehlende Persistenz von Marketplace-Install-Records und Config-Metadaten- -Migration während `plugins update`. Das veröffentlichte Package `2026.4.26` darf -für bereits ausgelieferte lokale Build-Metadaten-Stamp-Dateien warnen. Spätere Packages -müssen die modernen Package-Verträge erfüllen; dieselben Lücken lassen die Release- -Validierung fehlschlagen. +Legacy-Nachsicht bei package-acceptance ist bewusst zeitlich begrenzt. Pakete +bis einschließlich `2026.4.25` dürfen den Kompatibilitätspfad für Metadatenlücken +verwenden, die bereits auf npm veröffentlicht wurden: private QA-Inventareinträge, +die im Tarball fehlen, fehlendes `gateway install --wrapper`, fehlende Patch-Dateien +in der aus dem Tarball abgeleiteten Git-Fixture, fehlendes persistiertes +`update.channel`, Legacy-Speicherorte für Plugin-Install-Records, fehlende +Persistenz von Marketplace-Install-Records und Config-Metadatenmigration während +`plugins update`. Das veröffentlichte Paket `2026.4.26` darf für bereits +ausgelieferte lokale Build-Metadaten-Stamp-Dateien warnen. Spätere Pakete müssen +die modernen Paketverträge erfüllen; dieselben Lücken lassen die Release-Validierung +fehlschlagen. -Verwenden Sie breitere Package-Acceptance-Profile, wenn sich die Release-Frage auf ein -tatsächliches installierbares Package bezieht: +Verwenden Sie breitere Package-Acceptance-Profile, wenn sich die Release-Frage +auf ein tatsächlich installierbares Paket bezieht: ```bash gh workflow run package-acceptance.yml \ @@ -404,20 +429,18 @@ gh workflow run package-acceptance.yml \ -f published_upgrade_survivor_baseline=openclaw@2026.4.26 ``` -Gängige Package-Profile: +Gängige Paketprofile: -- `smoke`: schnelle Package-Install-/Channel-/Agent-, Gateway-Netzwerk- und Config- - Reload-Lanes -- `package`: Install-/Update-/Plugin-Package-Verträge ohne Live-ClawHub; dies ist der Release-Check- - Standard -- `product`: `package` plus MCP-Channels, Cron-/Subagent-Cleanup, OpenAI-Web- - Suche und OpenWebUI -- `full`: Docker-Release-Pfad-Chunks mit OpenWebUI +- `smoke`: schnelle Lanes für Paketinstallation/Kanal/Agent, Gateway-Netzwerk und Config-Neuladen +- `package`: Install-/Update-/Plugin-Paketverträge ohne Live-ClawHub; dies ist der + Standard für Release-Checks +- `product`: `package` plus MCP-Kanäle, Cron-/Subagent-Cleanup, OpenAI-Websuche und OpenWebUI +- `full`: Docker-Chunks des Release-Pfads mit OpenWebUI - `custom`: exakte `docker_lanes`-Liste für gezielte Reruns -Für den Telegram-Nachweis für Package Candidates aktivieren Sie `telegram_mode=mock-openai` oder -`telegram_mode=live-frontier` in Package Acceptance. Der Workflow übergibt den -aufgelösten `package-under-test`-Tarball an die Telegram-Lane; der eigenständige +Für den Telegram-Nachweis eines Package-Kandidaten aktivieren Sie `telegram_mode=mock-openai` oder +`telegram_mode=live-frontier` in Package Acceptance. Der Workflow übergibt das +aufgelöste `package-under-test`-Tarball an die Telegram-Lane; der eigenständige Telegram-Workflow akzeptiert weiterhin eine veröffentlichte npm-Spezifikation für Prüfungen nach der Veröffentlichung. ## Automatisierung der Release-Veröffentlichung @@ -426,15 +449,15 @@ Telegram-Workflow akzeptiert weiterhin eine veröffentlichte npm-Spezifikation f orchestriert die Trusted-Publisher-Workflows in der Reihenfolge, die das Release benötigt: 1. Release-Tag auschecken und dessen Commit-SHA auflösen. -2. Prüfen, ob das Tag von `main` oder `release/*` erreichbar ist. +2. Prüfen, dass der Tag von `main` oder `release/*` erreichbar ist. 3. `pnpm plugins:sync:check` ausführen. 4. `Plugin NPM Release` mit `publish_scope=all-publishable` und `ref=` auslösen. 5. `Plugin ClawHub Release` mit demselben Scope und derselben SHA auslösen. -6. `OpenClaw NPM Release` mit dem Release-Tag, dem npm-Dist-Tag und der +6. `OpenClaw NPM Release` mit dem Release-Tag, npm-Dist-Tag und der gespeicherten `preflight_run_id` auslösen. -Beispiel für eine Beta-Veröffentlichung: +Beispiel für Beta-Veröffentlichung: ```bash gh workflow run openclaw-release-publish.yml \ @@ -444,17 +467,7 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -Beispiel für eine Alpha-Veröffentlichung: - -```bash -gh workflow run openclaw-release-publish.yml \ - --ref release/YYYY.M.D \ - -f tag=vYYYY.M.D-alpha.N \ - -f preflight_run_id= \ - -f npm_dist_tag=alpha -``` - -Stabile Veröffentlichung mit dem Standard-Beta-Dist-Tag: +Stabile Veröffentlichung zum standardmäßigen Beta-Dist-Tag: ```bash gh workflow run openclaw-release-publish.yml \ @@ -464,7 +477,7 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -Die stabile Promotion direkt zu `latest` erfolgt ausdrücklich: +Stabile Promotion direkt zu `latest` ist explizit: ```bash gh workflow run openclaw-release-publish.yml \ @@ -475,91 +488,90 @@ gh workflow run openclaw-release-publish.yml \ ``` Verwenden Sie die untergeordneten Workflows `Plugin NPM Release` und `Plugin ClawHub Release` -nur für gezielte Reparatur- oder erneute Veröffentlichungsarbeiten. Für die Reparatur eines ausgewählten Plugins übergeben Sie +nur für gezielte Reparatur- oder Neuveröffentlichungsarbeiten. Für eine ausgewählte Plugin-Reparatur übergeben Sie `plugin_publish_scope=selected` und `plugins=@openclaw/name` an `OpenClaw Release Publish`, oder lösen Sie den Child-Workflow direkt aus, wenn das OpenClaw-Paket nicht veröffentlicht werden darf. ## NPM-Workflow-Eingaben -`OpenClaw NPM Release` akzeptiert diese operatorgesteuerten Eingaben: +`OpenClaw NPM Release` akzeptiert diese vom Operator gesteuerten Eingaben: -- `tag`: erforderliches Release-Tag wie `v2026.4.2`, `v2026.4.2-1` oder - `v2026.4.2-alpha.1` oder `v2026.4.2-beta.1`; wenn `preflight_only=true` gilt, kann es auch die aktuelle - vollständige 40-Zeichen-Commit-SHA des Workflow-Branches für einen rein validierenden Preflight sein +- `tag`: erforderlicher Release-Tag wie `v2026.4.2`, `v2026.4.2-1` oder + `v2026.4.2-beta.1`; wenn `preflight_only=true`, kann er auch die aktuelle + vollständige 40-Zeichen-Commit-SHA des Workflow-Branches für einen reinen Validierungs-Preflight sein - `preflight_only`: `true` nur für Validierung/Build/Paket, `false` für den echten Veröffentlichungspfad -- `preflight_run_id`: auf dem echten Veröffentlichungspfad erforderlich, damit der Workflow - den vorbereiteten Tarball aus dem erfolgreichen Preflight-Lauf wiederverwendet +- `preflight_run_id`: im echten Veröffentlichungspfad erforderlich, damit der Workflow + das vorbereitete Tarball aus dem erfolgreichen Preflight-Lauf wiederverwendet - `npm_dist_tag`: npm-Ziel-Tag für den Veröffentlichungspfad; Standardwert ist `beta` -`OpenClaw Release Publish` akzeptiert diese operatorgesteuerten Eingaben: +`OpenClaw Release Publish` akzeptiert diese vom Operator gesteuerten Eingaben: -- `tag`: erforderliches Release-Tag; muss bereits existieren -- `preflight_run_id`: erfolgreiche `OpenClaw NPM Release`-Preflight-Run-ID; - erforderlich, wenn `publish_openclaw_npm=true` gilt +- `tag`: erforderlicher Release-Tag; muss bereits existieren +- `preflight_run_id`: erfolgreiche Preflight-Lauf-ID von `OpenClaw NPM Release`; + erforderlich, wenn `publish_openclaw_npm=true` - `npm_dist_tag`: npm-Ziel-Tag für das OpenClaw-Paket - `plugin_publish_scope`: Standardwert ist `all-publishable`; verwenden Sie `selected` nur für gezielte Reparaturarbeiten -- `plugins`: durch Kommas getrennte Paketnamen im Format `@openclaw/*`, wenn - `plugin_publish_scope=selected` gilt -- `publish_openclaw_npm`: Standardwert ist `true`; setzen Sie dies nur dann auf `false`, wenn der - Workflow als reiner Plugin-Reparatur-Orchestrator verwendet wird +- `plugins`: kommagetrennte `@openclaw/*`-Paketnamen, wenn + `plugin_publish_scope=selected` +- `publish_openclaw_npm`: Standardwert ist `true`; setzen Sie dies nur dann auf `false`, wenn Sie den + Workflow als reinen Reparatur-Orchestrator für Plugins verwenden -`OpenClaw Release Checks` akzeptiert diese operatorgesteuerten Eingaben: +`OpenClaw Release Checks` akzeptiert diese vom Operator gesteuerten Eingaben: -- `ref`: Branch, Tag oder vollständige Commit-SHA, die validiert werden soll. Prüfungen mit Secrets +- `ref`: Branch, Tag oder vollständige Commit-SHA zur Validierung. Prüfungen mit Secrets erfordern, dass der aufgelöste Commit von einem OpenClaw-Branch oder Release-Tag erreichbar ist. Regeln: -- Stabile Tags und Korrektur-Tags dürfen entweder zu `beta` oder `latest` veröffentlichen -- Alpha-Prerelease-Tags dürfen nur zu `alpha` veröffentlichen -- Beta-Prerelease-Tags dürfen nur zu `beta` veröffentlichen -- Für `OpenClaw NPM Release` ist eine vollständige Commit-SHA-Eingabe nur erlaubt, wenn - `preflight_only=true` gilt -- `OpenClaw Release Checks` und `Full Release Validation` dienen immer - nur der Validierung +- Stabile Tags und Korrektur-Tags dürfen entweder zu `beta` oder `latest` veröffentlicht werden +- Beta-Prerelease-Tags dürfen nur zu `beta` veröffentlicht werden +- Für `OpenClaw NPM Release` ist die Eingabe einer vollständigen Commit-SHA nur erlaubt, wenn + `preflight_only=true` +- `OpenClaw Release Checks` und `Full Release Validation` sind immer + reine Validierung - Der echte Veröffentlichungspfad muss dasselbe `npm_dist_tag` verwenden, das während des Preflights verwendet wurde; - der Workflow prüft diese Metadaten, bevor die Veröffentlichung fortgesetzt wird + der Workflow prüft diese Metadaten vor dem Fortsetzen der Veröffentlichung ## Stabile npm-Release-Sequenz Beim Erstellen eines stabilen npm-Releases: 1. Führen Sie `OpenClaw NPM Release` mit `preflight_only=true` aus - - Bevor ein Tag existiert, können Sie die aktuelle vollständige Workflow-Branch-Commit-SHA - für einen rein validierenden Probelauf des Preflight-Workflows verwenden -2. Wählen Sie `npm_dist_tag=beta` für den normalen Beta-zuerst-Ablauf oder `latest` nur dann, + - Bevor ein Tag existiert, können Sie die aktuelle vollständige Commit-SHA des Workflow-Branches + für einen reinen Validierungs-Trockenlauf des Preflight-Workflows verwenden +2. Wählen Sie `npm_dist_tag=beta` für den normalen Beta-zuerst-Ablauf oder nur dann `latest`, wenn Sie bewusst eine direkte stabile Veröffentlichung wünschen -3. Führen Sie `Full Release Validation` auf dem Release-Branch, dem Release-Tag oder der vollständigen +3. Führen Sie `Full Release Validation` auf dem Release-Branch, Release-Tag oder der vollständigen Commit-SHA aus, wenn Sie normale CI plus Live-Prompt-Cache, Docker, QA Lab, - Matrix und Telegram-Abdeckung aus einem manuellen Workflow heraus wünschen + Matrix und Telegram-Abdeckung aus einem manuellen Workflow wünschen 4. Wenn Sie bewusst nur den deterministischen normalen Testgraphen benötigen, führen Sie stattdessen den - manuellen `CI`-Workflow auf der Release-Ref aus + manuellen `CI`-Workflow auf der Release-Referenz aus 5. Speichern Sie die erfolgreiche `preflight_run_id` 6. Führen Sie `OpenClaw Release Publish` mit demselben `tag`, demselben `npm_dist_tag` und der gespeicherten `preflight_run_id` aus; dies veröffentlicht externalisierte Plugins auf npm - und ClawHub, bevor das OpenClaw-npm-Paket hochgestuft wird + und ClawHub, bevor das OpenClaw-npm-Paket promoted wird 7. Wenn das Release auf `beta` gelandet ist, verwenden Sie den privaten - Workflow `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`, - um diese stabile Version von `beta` zu `latest` hochzustufen + `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`- + Workflow, um diese stabile Version von `beta` zu `latest` zu promoten 8. Wenn das Release bewusst direkt zu `latest` veröffentlicht wurde und `beta` sofort demselben stabilen Build folgen soll, verwenden Sie denselben privaten - Workflow, um beide Dist-Tags auf die stabile Version zeigen zu lassen, oder lassen Sie die geplante + Workflow, um beide Dist-Tags auf die stabile Version zeigen zu lassen, oder lassen Sie dessen geplante selbstheilende Synchronisierung `beta` später verschieben Die Dist-Tag-Mutation liegt aus Sicherheitsgründen im privaten Repo, weil sie weiterhin -`NPM_TOKEN` benötigt, während das öffentliche Repo ausschließlich OIDC-Veröffentlichungen verwendet. +`NPM_TOKEN` erfordert, während das öffentliche Repo nur OIDC-Veröffentlichung verwendet. -Damit bleiben sowohl der direkte Veröffentlichungspfad als auch der Beta-zuerst-Promotion-Pfad +Dadurch bleiben sowohl der direkte Veröffentlichungspfad als auch der Beta-zuerst-Promotion-Pfad dokumentiert und für Operatoren sichtbar. -Wenn ein Maintainer auf lokale npm-Authentifizierung zurückfallen muss, führen Sie alle 1Password- -CLI-Befehle (`op`) nur innerhalb einer dedizierten tmux-Sitzung aus. Rufen Sie `op` nicht -direkt aus der Haupt-Agent-Shell auf; innerhalb von tmux bleiben Prompts, -Warnungen und OTP-Handling beobachtbar und wiederholte Host-Warnungen werden verhindert. +Wenn ein Maintainer auf lokale npm-Authentifizierung zurückgreifen muss, führen Sie alle 1Password +CLI-(`op`)-Befehle nur innerhalb einer dedizierten tmux-Sitzung aus. Rufen Sie `op` nicht +direkt aus der Haupt-Agent-Shell auf; wenn es in tmux bleibt, sind Prompts, +Warnungen und OTP-Verarbeitung beobachtbar, und wiederholte Host-Warnungen werden verhindert. ## Öffentliche Referenzen diff --git a/docs/de/web/control-ui.md b/docs/de/web/control-ui.md index 1bf546fe7..371c9dc13 100644 --- a/docs/de/web/control-ui.md +++ b/docs/de/web/control-ui.md @@ -3,23 +3,23 @@ read_when: - Sie möchten das Gateway über einen Browser bedienen - Sie möchten Tailnet-Zugriff ohne SSH-Tunnel sidebarTitle: Control UI -summary: Browserbasierte Steuerungsoberfläche für das Gateway (Chat, Knoten, Konfiguration) -title: Steuerungsoberfläche +summary: Browserbasierte Steuerungs-UI für das Gateway (Chat, Nodes, Konfiguration) +title: Steuerungs-UI x-i18n: - generated_at: "2026-05-02T21:05:24Z" + generated_at: "2026-05-02T23:39:16Z" model: gpt-5.5 provider: openai - source_hash: 88959ccf435b31015039bf28c3043023d99f0b953a1489986ab2d0cbd261771c + source_hash: 50bef807915f27406e19f1c6ca7d839a610d79ba79da85d7a78523400cbf9208 source_path: web/control-ui.md workflow: 16 --- -Die Control UI ist eine kleine **Vite + Lit**-Single-Page-App, die vom Gateway bereitgestellt wird: +Die Steuerungsoberfläche ist eine kleine **Vite + Lit** Single-Page-App, die vom Gateway bereitgestellt wird: - Standard: `http://:18789/` - optionales Präfix: `gateway.controlUi.basePath` festlegen (z. B. `/openclaw`) -Sie kommuniziert **direkt mit dem Gateway WebSocket** auf demselben Port. +Sie kommuniziert **direkt mit dem Gateway-WebSocket** auf demselben Port. ## Schnell öffnen (lokal) @@ -33,16 +33,16 @@ Die Authentifizierung wird während des WebSocket-Handshakes bereitgestellt übe - `connect.params.auth.token` - `connect.params.auth.password` -- Tailscale Serve-Identitätsheader, wenn `gateway.auth.allowTailscale: true` +- Tailscale-Serve-Identitätsheader, wenn `gateway.auth.allowTailscale: true` - Trusted-Proxy-Identitätsheader, wenn `gateway.auth.mode: "trusted-proxy"` -Das Einstellungsfenster des Dashboards speichert ein Token für die aktuelle Browser-Tab-Sitzung und die ausgewählte Gateway-URL; Passwörter werden nicht dauerhaft gespeichert. Das Onboarding erzeugt beim ersten Verbindungsaufbau normalerweise ein Gateway-Token für Shared-Secret-Authentifizierung, aber Passwortauthentifizierung funktioniert ebenfalls, wenn `gateway.auth.mode` `"password"` ist. +Das Einstellungsfenster des Dashboards speichert ein Token für die aktuelle Browser-Tab-Sitzung und die ausgewählte Gateway-URL; Passwörter werden nicht dauerhaft gespeichert. Das Onboarding erzeugt beim ersten Verbinden normalerweise ein Gateway-Token für Shared-Secret-Authentifizierung, aber Passwortauthentifizierung funktioniert ebenfalls, wenn `gateway.auth.mode` `"password"` ist. ## Gerätekopplung (erste Verbindung) -Wenn Sie von einem neuen Browser oder Gerät aus eine Verbindung zur Control UI herstellen, verlangt das Gateway normalerweise eine **einmalige Kopplungsgenehmigung**. Dies ist eine Sicherheitsmaßnahme, um unbefugten Zugriff zu verhindern. +Wenn Sie die Steuerungsoberfläche von einem neuen Browser oder Gerät aus verbinden, verlangt das Gateway normalerweise eine **einmalige Kopplungsbestätigung**. Dies ist eine Sicherheitsmaßnahme, um unbefugten Zugriff zu verhindern. -**Was Sie sehen:** „disconnected (1008): pairing required“ +**Was Sie sehen:** "getrennt (1008): Kopplung erforderlich" @@ -50,103 +50,104 @@ Wenn Sie von einem neuen Browser oder Gerät aus eine Verbindung zur Control UI openclaw devices list ``` - + ```bash openclaw devices approve ``` -Wenn der Browser die Kopplung mit geänderten Authentifizierungsdetails (Rolle/Scopes/öffentlicher Schlüssel) erneut versucht, wird die vorherige ausstehende Anfrage ersetzt und eine neue `requestId` erstellt. Führen Sie vor der Genehmigung erneut `openclaw devices list` aus. +Wenn der Browser die Kopplung mit geänderten Authentifizierungsdetails (Rolle/Berechtigungsumfänge/öffentlicher Schlüssel) erneut versucht, wird die vorherige ausstehende Anfrage ersetzt und eine neue `requestId` erstellt. Führen Sie vor der Genehmigung erneut `openclaw devices list` aus. -Wenn der Browser bereits gekoppelt ist und Sie ihn von Lesezugriff auf Schreib-/Admin-Zugriff ändern, wird dies als Genehmigungsupgrade behandelt, nicht als stiller Neuaufbau der Verbindung. OpenClaw hält die alte Genehmigung aktiv, blockiert die Verbindung mit erweiterten Rechten und fordert Sie auf, das neue Scope-Set ausdrücklich zu genehmigen. +Wenn der Browser bereits gekoppelt ist und Sie ihn von Lesezugriff auf Schreib-/Adminzugriff umstellen, wird dies als Genehmigungsupgrade behandelt, nicht als stillschweigende erneute Verbindung. OpenClaw hält die alte Genehmigung aktiv, blockiert die umfassendere erneute Verbindung und fordert Sie auf, den neuen Umfangssatz explizit zu genehmigen. -Nach der Genehmigung wird das Gerät gemerkt und erfordert keine erneute Genehmigung, es sei denn, Sie widerrufen es mit `openclaw devices revoke --device --role `. Siehe [Devices CLI](/de/cli/devices) für Tokenrotation und Widerruf. +Nach der Genehmigung wird das Gerät gespeichert und erfordert keine erneute Genehmigung, es sei denn, Sie widerrufen es mit `openclaw devices revoke --device --role `. Siehe [Geräte-CLI](/de/cli/devices) für Token-Rotation und Widerruf. -- Direkte local loopback-Browserverbindungen (`127.0.0.1` / `localhost`) werden automatisch genehmigt. -- Tailscale Serve kann den Kopplungsdurchlauf für Control UI-Operatorsitzungen überspringen, wenn `gateway.auth.allowTailscale: true` gilt, die Tailscale-Identität verifiziert wird und der Browser seine Geräteidentität präsentiert. -- Direkte Tailnet-Bindings, LAN-Browserverbindungen und Browserprofile ohne Geräteidentität erfordern weiterhin eine ausdrückliche Genehmigung. +- Direkte Browserverbindungen über local loopback (`127.0.0.1` / `localhost`) werden automatisch genehmigt. +- Tailscale Serve kann den Kopplungsdurchlauf für Operator-Sitzungen der Steuerungsoberfläche überspringen, wenn `gateway.auth.allowTailscale: true` gesetzt ist, die Tailscale-Identität verifiziert wird und der Browser seine Geräteidentität vorlegt. +- Direkte Tailnet-Bindungen, LAN-Browserverbindungen und Browserprofile ohne Geräteidentität erfordern weiterhin eine explizite Genehmigung. - Jedes Browserprofil erzeugt eine eindeutige Geräte-ID, daher erfordert ein Browserwechsel oder das Löschen von Browserdaten eine erneute Kopplung. ## Persönliche Identität (browserlokal) -Die Control UI unterstützt eine browserbezogene persönliche Identität (Anzeigename und Avatar), die ausgehenden Nachrichten zur Zuordnung in geteilten Sitzungen angehängt wird. Sie befindet sich im Browserspeicher, ist auf das aktuelle Browserprofil beschränkt und wird weder mit anderen Geräten synchronisiert noch serverseitig dauerhaft gespeichert, abgesehen von den normalen Urheberschaftsmetadaten im Transkript für Nachrichten, die Sie tatsächlich senden. Das Löschen von Websitedaten oder ein Browserwechsel setzt sie auf leer zurück. +Die Steuerungsoberfläche unterstützt eine persönliche Identität pro Browser (Anzeigename und Avatar), die ausgehenden Nachrichten zur Zuordnung in geteilten Sitzungen angehängt wird. Sie befindet sich im Browserspeicher, ist auf das aktuelle Browserprofil beschränkt und wird weder mit anderen Geräten synchronisiert noch serverseitig über die normalen Autor-Metadaten des Transkripts für Nachrichten hinaus gespeichert, die Sie tatsächlich senden. Das Löschen von Websitedaten oder ein Browserwechsel setzt sie auf leer zurück. -Dasselbe browserlokale Muster gilt für die Überschreibung des Assistenten-Avatars. Hochgeladene Assistenten-Avatare überlagern die vom Gateway aufgelöste Identität nur im lokalen Browser und laufen nie über `config.patch` zurück. Das gemeinsame Konfigurationsfeld `ui.assistant.avatar` bleibt für Nicht-UI-Clients verfügbar, die das Feld direkt schreiben (etwa geskriptete Gateways oder benutzerdefinierte Dashboards). +Dasselbe browserlokale Muster gilt für die Avatar-Überschreibung des Assistenten. Hochgeladene Assistenten-Avatare überlagern die vom Gateway aufgelöste Identität nur im lokalen Browser und durchlaufen niemals `config.patch`. Das geteilte Konfigurationsfeld `ui.assistant.avatar` bleibt weiterhin für Nicht-UI-Clients verfügbar, die das Feld direkt schreiben (z. B. skriptgesteuerte Gateways oder benutzerdefinierte Dashboards). -## Endpunkt für Laufzeitkonfiguration +## Laufzeitkonfigurations-Endpunkt -Die Control UI ruft ihre Laufzeiteinstellungen von `/__openclaw/control-ui-config.json` ab. Dieser Endpunkt ist durch dieselbe Gateway-Authentifizierung geschützt wie der Rest der HTTP-Oberfläche: Nicht authentifizierte Browser können ihn nicht abrufen, und ein erfolgreicher Abruf erfordert entweder ein bereits gültiges Gateway-Token/Passwort, eine Tailscale Serve-Identität oder eine Trusted-Proxy-Identität. +Die Steuerungsoberfläche ruft ihre Laufzeiteinstellungen von `/__openclaw/control-ui-config.json` ab. Dieser Endpunkt wird durch dieselbe Gateway-Authentifizierung geschützt wie die restliche HTTP-Oberfläche: Nicht authentifizierte Browser können ihn nicht abrufen, und ein erfolgreicher Abruf erfordert entweder ein bereits gültiges Gateway-Token/Passwort, eine Tailscale-Serve-Identität oder eine Trusted-Proxy-Identität. ## Sprachunterstützung -Die Control UI kann sich beim ersten Laden anhand Ihrer Browserlocale lokalisieren. Um sie später zu überschreiben, öffnen Sie **Overview -> Gateway Access -> Language**. Die Locale-Auswahl befindet sich in der Gateway Access-Karte, nicht unter Appearance. +Die Steuerungsoberfläche kann sich beim ersten Laden anhand Ihrer Browser-Locale lokalisieren. Um dies später zu überschreiben, öffnen Sie **Übersicht -> Gateway-Zugriff -> Sprache**. Die Locale-Auswahl befindet sich in der Gateway-Zugriff-Karte, nicht unter Darstellung. - Unterstützte Locales: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa` -- Nicht englische Übersetzungen werden im Browser verzögert geladen. +- Nicht englische Übersetzungen werden im Browser bei Bedarf geladen. - Die ausgewählte Locale wird im Browserspeicher gespeichert und bei zukünftigen Besuchen wiederverwendet. - Fehlende Übersetzungsschlüssel fallen auf Englisch zurück. -Dokumentationsübersetzungen werden für dieselbe nicht englische Locale-Menge generiert, aber die integrierte Mintlify-Sprachauswahl der Dokumentationswebsite ist auf die Locale-Codes beschränkt, die Mintlify akzeptiert. Thailändische (`th`) und persische (`fa`) Dokumentation wird weiterhin im Veröffentlichungs-Repo generiert; sie erscheint möglicherweise erst in dieser Auswahl, wenn Mintlify diese Codes unterstützt. +Dokumentationsübersetzungen werden für dieselbe nicht englische Locale-Menge erzeugt, aber die integrierte Mintlify-Sprachauswahl der Dokumentationswebsite ist auf die Locale-Codes beschränkt, die Mintlify akzeptiert. Thailändische (`th`) und persische (`fa`) Dokumentation wird weiterhin im Veröffentlichungs-Repository erzeugt; sie erscheint möglicherweise erst in dieser Auswahl, wenn Mintlify diese Codes unterstützt. ## Darstellungsthemen -Das Appearance-Fenster behält die integrierten Themen Claw, Knot und Dash sowie einen browserlokalen tweakcn-Importslot. Um ein Thema zu importieren, öffnen Sie [tweakcn themes](https://tweakcn.com/themes), wählen oder erstellen Sie ein Thema, klicken Sie auf **Share** und fügen Sie den kopierten Themenlink in Appearance ein. Der Importer akzeptiert außerdem `https://tweakcn.com/r/themes/`-Registry-URLs, Editor-URLs wie `https://tweakcn.com/editor/theme?theme=amethyst-haze`, relative `/themes/`-Pfade, rohe Themen-IDs und Standardthemennamen wie `amethyst-haze`. +Das Darstellungsfenster behält die integrierten Designs Claw, Knot und Dash sowie einen browserlokalen tweakcn-Importplatz. Um ein Design zu importieren, öffnen Sie [tweakcn-Designs](https://tweakcn.com/themes), wählen oder erstellen Sie ein Design, klicken Sie auf **Teilen**, und fügen Sie den kopierten Designlink in Darstellung ein. Der Importer akzeptiert außerdem `https://tweakcn.com/r/themes/`-Registry-URLs, Editor-URLs wie `https://tweakcn.com/editor/theme?theme=amethyst-haze`, relative `/themes/`-Pfade, reine Design-IDs und Standard-Designnamen wie `amethyst-haze`. -Importierte Themen werden nur im aktuellen Browserprofil gespeichert. Sie werden nicht in die Gateway-Konfiguration geschrieben und nicht zwischen Geräten synchronisiert. Das Ersetzen des importierten Themas aktualisiert den einen lokalen Slot; das Löschen wechselt das aktive Thema zurück zu Claw, wenn das importierte Thema ausgewählt war. +Importierte Designs werden nur im aktuellen Browserprofil gespeichert. Sie werden nicht in die Gateway-Konfiguration geschrieben und nicht geräteübergreifend synchronisiert. Das Ersetzen des importierten Designs aktualisiert den einen lokalen Platz; das Löschen schaltet das aktive Design zurück auf Claw, wenn das importierte Design ausgewählt war. ## Was sie kann (heute) - - - Chatten Sie mit dem Modell über Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`). - - Sprechen Sie über Browser-Echtzeitsitzungen. OpenAI nutzt direktes WebRTC, Google Live nutzt ein eingeschränktes, einmal verwendbares Browser-Token über WebSocket, und reine Backend-Echtzeit-Sprach-Plugins verwenden den Gateway-Relay-Transport. Das Relay hält Provider-Anmeldedaten auf dem Gateway, während der Browser Mikrofon-PCM über `talk.realtime.relay*`-RPCs streamt und `openclaw_agent_consult`-Toolaufrufe über `chat.send` an das größere konfigurierte OpenClaw-Modell zurücksendet. - - Streamen Sie Toolaufrufe und Live-Toolausgabekarten im Chat (Agent-Ereignisse). + + - Mit dem Modell über Gateway WS chatten (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`). + - In den Chat-Composer mit serverseitiger STT diktieren (`chat.transcribeAudio`). Der Browser zeichnet einen kurzen Mikrofonclip auf und sendet ihn an das Gateway, das die konfigurierte `tools.media.audio`-Transkriptionspipeline ausführt und Entwurfstext zurückgibt, ohne Provider-Anmeldedaten im Browser offenzulegen. + - Über Browser-Echtzeitsitzungen sprechen. OpenAI verwendet direktes WebRTC, Google Live verwendet ein eingeschränktes einmalig nutzbares Browser-Token über WebSocket, und nur backendseitige Echtzeit-Sprach-Plugins verwenden den Gateway-Relay-Transport. Das Relay hält Provider-Anmeldedaten auf dem Gateway, während der Browser Mikrofon-PCM über `talk.realtime.relay*`-RPCs streamt und `openclaw_agent_consult`-Toolaufrufe über `chat.send` an das größere konfigurierte OpenClaw-Modell zurücksendet. + - Toolaufrufe und Live-Toolausgabe-Karten im Chat streamen (Agent-Ereignisse). - - - Kanäle: Status integrierter sowie gebündelter/externer Plugin-Kanäle, QR-Login und kanalbezogene Konfiguration (`channels.status`, `web.login.*`, `config.patch`). + + - Kanäle: integrierter Status plus Status gebündelter/externer Plugin-Kanäle, QR-Anmeldung und Konfiguration pro Kanal (`channels.status`, `web.login.*`, `config.patch`). - Instanzen: Anwesenheitsliste und Aktualisierung (`system-presence`). - - Sitzungen: Liste und sitzungsbezogene Überschreibungen für Modell/Thinking/Fast/Verbose/Trace/Reasoning (`sessions.list`, `sessions.patch`). - - Dreams: Dreaming-Status, Aktivieren/Deaktivieren-Schalter und Dream Diary-Reader (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`). + - Sitzungen: Liste und sitzungsbezogene Überschreibungen für Modell/Denken/schnell/ausführlich/Trace/Reasoning (`sessions.list`, `sessions.patch`). + - Träume: Dreaming-Status, Umschalter zum Aktivieren/Deaktivieren und Dream-Diary-Leser (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`). - - Cron-Jobs: auflisten/hinzufügen/bearbeiten/ausführen/aktivieren/deaktivieren und Ausführungsverlauf (`cron.*`). + - Cron-Jobs: auflisten/hinzufügen/bearbeiten/ausführen/aktivieren/deaktivieren und Ausführungshistorie (`cron.*`). - Skills: Status, aktivieren/deaktivieren, installieren, API-Schlüssel aktualisieren (`skills.*`). - - Nodes: Liste und Caps (`node.list`). - - Exec-Genehmigungen: Gateway- oder Node-Allowlists und Ask-Policy für `exec host=gateway/node` bearbeiten (`exec.approvals.*`). + - Nodes: Liste und Fähigkeiten (`node.list`). + - Exec-Genehmigungen: Gateway- oder Node-Allowlists bearbeiten und Abfragerichtlinie für `exec host=gateway/node` (`exec.approvals.*`). - `~/.openclaw/openclaw.json` anzeigen/bearbeiten (`config.get`, `config.set`). - - Anwenden und mit Validierung neu starten (`config.apply`) sowie die zuletzt aktive Sitzung wecken. - - Schreibvorgänge enthalten eine Base-Hash-Schutzprüfung, um das Überschreiben gleichzeitiger Bearbeitungen zu verhindern. - - Schreibvorgänge (`config.set`/`config.apply`/`config.patch`) prüfen vorab die Auflösung aktiver SecretRef für Refs im übermittelten Konfigurationspayload; nicht auflösbare aktive übermittelte Refs werden vor dem Schreiben abgelehnt. - - Schema- und Formular-Rendering (`config.schema` / `config.schema.lookup`, einschließlich Feld-`title` / `description`, passender UI-Hinweise, Zusammenfassungen unmittelbarer untergeordneter Elemente, Dokumentationsmetadaten auf verschachtelten Objekt-/Wildcard-/Array-/Kompositions-Nodes sowie Plugin- und Kanalschemas, wenn verfügbar); der Raw-JSON-Editor ist nur verfügbar, wenn der Snapshot einen sicheren Raw-Roundtrip hat. - - Wenn ein Snapshot Rohtext nicht sicher per Roundtrip erhalten kann, erzwingt die Control UI den Formularmodus und deaktiviert für diesen Snapshot den Raw-Modus. - - „Reset to saved“ im Raw-JSON-Editor bewahrt die roh verfasste Form (Formatierung, Kommentare, `$include`-Layout), statt einen abgeflachten Snapshot erneut zu rendern, sodass externe Bearbeitungen einen Reset überstehen, wenn der Snapshot sicher per Roundtrip erhalten werden kann. - - Strukturierte SecretRef-Objektwerte werden in Formular-Texteingaben schreibgeschützt gerendert, um versehentliche Objekt-zu-String-Beschädigung zu verhindern. + - Anwenden und Neustart mit Validierung (`config.apply`) sowie Aufwecken der zuletzt aktiven Sitzung. + - Schreibvorgänge enthalten einen Basis-Hash-Schutz, um das Überschreiben gleichzeitiger Bearbeitungen zu verhindern. + - Schreibvorgänge (`config.set`/`config.apply`/`config.patch`) prüfen vorab die aktive SecretRef-Auflösung für Referenzen in der übermittelten Konfigurationsnutzlast; nicht aufgelöste aktive übermittelte Referenzen werden vor dem Schreiben abgelehnt. + - Schema- und Formular-Rendering (`config.schema` / `config.schema.lookup`, einschließlich Feld-`title` / `description`, passender UI-Hinweise, unmittelbarer Kindzusammenfassungen, Dokumentationsmetadaten auf verschachtelten Objekt-/Wildcard-/Array-/Kompositions-Nodes sowie Plugin- und Kanalschemata, wenn verfügbar); der Raw-JSON-Editor ist nur verfügbar, wenn der Snapshot eine sichere Raw-Roundtrip-Verarbeitung hat. + - Wenn ein Snapshot Rohtext nicht sicher im Roundtrip verarbeiten kann, erzwingt die Steuerungsoberfläche den Formularmodus und deaktiviert den Raw-Modus für diesen Snapshot. + - Der Raw-JSON-Editor „Auf gespeicherten Stand zurücksetzen“ bewahrt die raw-verfasste Form (Formatierung, Kommentare, `$include`-Layout), statt einen abgeflachten Snapshot neu zu rendern, sodass externe Bearbeitungen einen Reset überstehen, wenn der Snapshot sicher im Roundtrip verarbeitet werden kann. + - Strukturierte SecretRef-Objektwerte werden in Formular-Texteingaben schreibgeschützt dargestellt, um versehentliche Beschädigung durch Umwandlung von Objekt zu String zu verhindern. - - - Debug: Status-/Health-/Modellsnapshots, Ereignisprotokoll und manuelle RPC-Aufrufe (`status`, `health`, `models.list`). + + - Debug: Status-/Health-/Modell-Snapshots, Ereignisprotokoll und manuelle RPC-Aufrufe (`status`, `health`, `models.list`). - Protokolle: Live-Tail der Gateway-Dateiprotokolle mit Filter/Export (`logs.tail`). - - Update: ein Paket-/Git-Update und Neustart ausführen (`update.run`) mit Neustartbericht, anschließend nach dem erneuten Verbinden `update.status` abfragen, um die laufende Gateway-Version zu verifizieren. + - Aktualisierung: Paket-/Git-Aktualisierung und Neustart ausführen (`update.run`) mit Neustartbericht, anschließend nach der erneuten Verbindung `update.status` abfragen, um die laufende Gateway-Version zu verifizieren. - - Für isolierte Jobs ist die Auslieferung standardmäßig auf Zusammenfassung ankündigen gesetzt. Sie können auf keine umschalten, wenn Sie rein interne Ausführungen wünschen. + - Für isolierte Jobs ist die Zustellung standardmäßig auf Zusammenfassung ankündigen gesetzt. Sie können auf keine umschalten, wenn Sie nur interne Ausführungen wünschen. - Kanal-/Zielfelder erscheinen, wenn Ankündigen ausgewählt ist. - - Der Webhook-Modus verwendet `delivery.mode = "webhook"` mit `delivery.to`, das auf eine gültige HTTP(S)-Webhook-URL gesetzt ist. - - Für Hauptsitzungs-Jobs sind die Auslieferungsmodi Webhook und keine verfügbar. - - Erweiterte Bearbeitungssteuerelemente umfassen Nach-Ausführung-löschen, Agent-Überschreibung löschen, exakte/gestaffelte Cron-Optionen, Agent-Modell-/Thinking-Überschreibungen und Best-Effort-Auslieferungsschalter. - - Formularvalidierung erfolgt inline mit feldbezogenen Fehlern; ungültige Werte deaktivieren die Speichern-Schaltfläche, bis sie behoben sind. - - Setzen Sie `cron.webhookToken`, um ein dediziertes Bearer-Token zu senden; wenn es weggelassen wird, wird der Webhook ohne Authentifizierungsheader gesendet. - - Veralteter Fallback: gespeicherte Legacy-Jobs mit `notify: true` können bis zur Migration weiterhin `cron.webhook` verwenden. + - Der Webhook-Modus verwendet `delivery.mode = "webhook"` mit `delivery.to`, gesetzt auf eine gültige HTTP(S)-Webhook-URL. + - Für Hauptsitzungs-Jobs sind die Zustellmodi Webhook und keine verfügbar. + - Erweiterte Bearbeitungssteuerelemente umfassen Nach-Ausführung-löschen, Agent-Überschreibung löschen, Cron-Optionen exakt/gestaffelt, Überschreibungen für Agent-Modell/Denken und Best-Effort-Zustellumschalter. + - Die Formularvalidierung erfolgt inline mit feldbezogenen Fehlern; ungültige Werte deaktivieren die Speichern-Schaltfläche, bis sie korrigiert sind. + - Setzen Sie `cron.webhookToken`, um ein dediziertes Bearer-Token zu senden; wenn ausgelassen, wird der Webhook ohne Authentifizierungsheader gesendet. + - Veralteter Fallback: Gespeicherte Legacy-Jobs mit `notify: true` können weiterhin `cron.webhook` verwenden, bis sie migriert wurden. @@ -155,61 +156,62 @@ Importierte Themen werden nur im aktuellen Browserprofil gespeichert. Sie werden - - `chat.send` ist **nicht blockierend**: Es bestätigt sofort mit `{ runId, status: "started" }`, und die Antwort wird über `chat`-Events gestreamt. + - `chat.send` ist **nicht blockierend**: Es bestätigt sofort mit `{ runId, status: "started" }`, und die Antwort wird über `chat`-Ereignisse gestreamt. + - `chat.transcribeAudio` ist ein einmaliger Diktierhelfer für Chat-Entwürfe. Er akzeptiert im Browser aufgezeichnetes Base64-Audio, hält Uploads unterhalb des Gateway-WebSocket-Frame-Limits, schreibt eine temporäre lokale Datei, führt Audio-Transkription mit Medienverständnis und der aktiven Gateway-Konfiguration aus, gibt `{ text, provider, model }` zurück und entfernt die temporäre Datei. Er erstellt keinen Agentenlauf und ist von Echtzeit-Talk getrennt. - Chat-Uploads akzeptieren Bilder sowie Nicht-Video-Dateien. Bilder behalten den nativen Bildpfad; andere Dateien werden als verwaltete Medien gespeichert und im Verlauf als Anhangslinks angezeigt. - - Erneutes Senden mit demselben `idempotencyKey` gibt während der Ausführung `{ status: "in_flight" }` zurück und nach Abschluss `{ status: "ok" }`. - - `chat.history`-Antworten sind aus Sicherheitsgründen für die UI größenbegrenzt. Wenn Transkripteinträge zu groß sind, kann Gateway lange Textfelder kürzen, umfangreiche Metadatenblöcke auslassen und übergroße Nachrichten durch einen Platzhalter ersetzen (`[chat.history omitted: message too large]`). - - Von Assistenten generierte Bilder werden als verwaltete Medienreferenzen dauerhaft gespeichert und über authentifizierte Gateway-Medien-URLs zurückgeliefert, sodass Neuladevorgänge nicht davon abhängen, dass rohe Base64-Bilddaten in der Chat-Verlaufsantwort verbleiben. - - `chat.history` entfernt außerdem nur zur Anzeige dienende Inline-Direktiv-Tags aus sichtbarem Assistententext (zum Beispiel `[[reply_to_*]]` und `[[audio_as_voice]]`), Nur-Text-XML-Nutzdaten von Tool-Aufrufen (einschließlich `...`, `...`, `...`, `...` und gekürzter Tool-Aufruf-Blöcke) sowie durchgesickerte ASCII- und vollbreite Modell-Steuertoken und lässt Assistenteneinträge aus, deren gesamter sichtbarer Text ausschließlich das exakte stille Token `NO_REPLY` / `no_reply` ist. - - Während eines aktiven Sendevorgangs und der abschließenden Verlaufsaktualisierung hält die Chat-Ansicht lokale optimistische Benutzer-/Assistentennachrichten sichtbar, wenn `chat.history` kurzzeitig einen älteren Snapshot zurückgibt; das kanonische Transkript ersetzt diese lokalen Nachrichten, sobald der Gateway-Verlauf aufgeholt hat. - - `chat.inject` fügt dem Sitzungstranskript eine Assistentennotiz hinzu und sendet ein `chat`-Event für reine UI-Aktualisierungen (kein Agent-Lauf, keine Kanalauslieferung). - - Die Modell- und Denk-Auswahlen im Chat-Header patchen die aktive Sitzung sofort über `sessions.patch`; sie sind dauerhafte Sitzungsüberschreibungen, keine nur für einen Zug geltenden Sendeoptionen. - - Die Eingabe von `/new` in der Control UI erstellt dieselbe frische Dashboard-Sitzung wie Neuer Chat und wechselt zu ihr. Die Eingabe von `/reset` behält den expliziten In-Place-Reset des Gateway für die aktuelle Sitzung bei. - - Die Chat-Modellauswahl fordert die konfigurierte Modellansicht des Gateway an. Wenn `agents.defaults.models` vorhanden ist, steuert diese Allowlist die Auswahl. Andernfalls zeigt die Auswahl explizite `models.providers.*.models`-Einträge sowie Provider mit nutzbarer Authentifizierung. Der vollständige Katalog bleibt über den Debug-RPC `models.list` mit `view: "all"` verfügbar. - - Wenn frische Gateway-Sitzungsnutzungsberichte hohen Kontextdruck anzeigen, zeigt der Chat-Composer-Bereich einen Kontexthinweis und bei empfohlenen Compaction-Stufen eine Kompakt-Schaltfläche, die den normalen Sitzungspfad für Compaction ausführt. Veraltete Token-Snapshots werden ausgeblendet, bis Gateway wieder frische Nutzung meldet. + - Erneutes Senden mit demselben `idempotencyKey` gibt während der Ausführung `{ status: "in_flight" }` und nach Abschluss `{ status: "ok" }` zurück. + - `chat.history`-Antworten sind zur UI-Sicherheit größenbegrenzt. Wenn Transkripteinträge zu groß sind, kann das Gateway lange Textfelder kürzen, umfangreiche Metadatenblöcke auslassen und übergroße Nachrichten durch einen Platzhalter ersetzen (`[chat.history omitted: message too large]`). + - Vom Assistenten generierte Bilder werden als verwaltete Medienreferenzen persistiert und über authentifizierte Gateway-Medien-URLs wieder ausgeliefert, sodass Neuladen nicht davon abhängt, dass rohe Base64-Bilddaten in der Chat-Verlaufsantwort verbleiben. + - `chat.history` entfernt außerdem nur für die Anzeige bestimmte Inline-Direktiv-Tags aus sichtbarem Assistententext (zum Beispiel `[[reply_to_*]]` und `[[audio_as_voice]]`), Nur-Text-XML-Nutzdaten von Tool-Aufrufen (einschließlich `...`, `...`, `...`, `...` und gekürzter Tool-Aufrufblöcke) sowie durchgesickerte ASCII- und vollbreite Modell-Steuertoken und lässt Assistenteneinträge aus, deren gesamter sichtbarer Text nur das exakte stille Token `NO_REPLY` / `no_reply` ist. + - Während eines aktiven Sendevorgangs und der abschließenden Verlaufsaktualisierung hält die Chat-Ansicht lokale optimistische Benutzer- und Assistentennachrichten sichtbar, wenn `chat.history` kurzzeitig einen älteren Snapshot zurückgibt; das kanonische Transkript ersetzt diese lokalen Nachrichten, sobald der Gateway-Verlauf aufgeholt hat. + - `chat.inject` hängt eine Assistentennotiz an das Sitzungstranskript an und sendet ein `chat`-Ereignis für reine UI-Aktualisierungen (kein Agentenlauf, keine Kanalzustellung). + - Die Modell- und Thinking-Auswahlen im Chat-Header patchen die aktive Sitzung sofort über `sessions.patch`; sie sind persistente Sitzungsüberschreibungen, keine nur für einen einzelnen Turn geltenden Sendeoptionen. + - Die Eingabe von `/new` in der Control UI erstellt und wechselt zu derselben frischen Dashboard-Sitzung wie New Chat. Die Eingabe von `/reset` behält den expliziten In-Place-Reset des Gateways für die aktuelle Sitzung bei. + - Die Chat-Modellauswahl fordert die konfigurierte Modellansicht des Gateways an. Wenn `agents.defaults.models` vorhanden ist, steuert diese Allowlist die Auswahl. Andernfalls zeigt die Auswahl explizite `models.providers.*.models`-Einträge sowie Provider mit nutzbarer Authentifizierung. Der vollständige Katalog bleibt über den Debug-RPC `models.list` mit `view: "all"` verfügbar. + - Wenn frische Gateway-Sitzungsnutzungsberichte hohen Kontextdruck anzeigen, zeigt der Chat-Composer-Bereich einen Kontexthinweis und bei empfohlenen Compaction-Stufen eine kompakte Schaltfläche, die den normalen Sitzungs-Compaction-Pfad ausführt. Veraltete Token-Snapshots werden ausgeblendet, bis das Gateway erneut frische Nutzung meldet. - - Der Sprechmodus verwendet einen registrierten Echtzeit-Sprachprovider. Konfigurieren Sie OpenAI mit `talk.provider: "openai"` plus `talk.providers.openai.apiKey`, oder konfigurieren Sie Google mit `talk.provider: "google"` plus `talk.providers.google.apiKey`; die Echtzeit-Provider-Konfiguration für Sprachanrufe kann weiterhin als Fallback wiederverwendet werden. Der Browser erhält niemals einen standardmäßigen Provider-API-Schlüssel. OpenAI erhält ein kurzlebiges Realtime-Client-Secret für WebRTC. Google Live erhält ein einmalig verwendbares, eingeschränktes Live-API-Authentifizierungstoken für eine Browser-WebSocket-Sitzung, wobei Anweisungen und Tool-Deklarationen durch den Gateway im Token fixiert werden. Provider, die nur eine Backend-Echtzeitbrücke bereitstellen, laufen über den Gateway-Relay-Transport, sodass Anmeldedaten und Anbieter-Sockets serverseitig bleiben, während Browser-Audio über authentifizierte Gateway-RPCs läuft. Der Realtime-Sitzungsprompt wird vom Gateway zusammengesetzt; `talk.realtime.session` akzeptiert keine vom Aufrufer bereitgestellten Anweisungsüberschreibungen. + + Der Talk-Modus verwendet einen registrierten Echtzeit-Sprach-Provider. Konfigurieren Sie OpenAI mit `talk.provider: "openai"` plus `talk.providers.openai.apiKey`, oder konfigurieren Sie Google mit `talk.provider: "google"` plus `talk.providers.google.apiKey`; die Echtzeit-Provider-Konfiguration für Voice Call kann weiterhin als Fallback wiederverwendet werden. Der Browser erhält niemals einen standardmäßigen Provider-API-Schlüssel. OpenAI erhält ein kurzlebiges Realtime-Client-Secret für WebRTC. Google Live erhält ein einmalig nutzbares, eingeschränktes Live-API-Authentifizierungstoken für eine Browser-WebSocket-Sitzung, wobei Anweisungen und Tool-Deklarationen durch das Gateway im Token gesperrt sind. Provider, die nur eine Backend-Echtzeit-Bridge bereitstellen, laufen über den Gateway-Relay-Transport, sodass Zugangsdaten und Vendor-Sockets serverseitig bleiben, während Browser-Audio über authentifizierte Gateway-RPCs übertragen wird. Der Realtime-Sitzungsprompt wird vom Gateway zusammengesetzt; `talk.realtime.session` akzeptiert keine vom Aufrufer bereitgestellten Anweisungsüberschreibungen. - Im Chat-Composer ist das Sprech-Steuerelement die Wellen-Schaltfläche neben der Mikrofon-Diktat-Schaltfläche. Wenn Sprechen startet, zeigt die Composer-Statuszeile `Connecting Talk...`, danach `Talk live`, während Audio verbunden ist, oder `Asking OpenClaw...`, während ein Echtzeit-Tool-Aufruf das konfigurierte größere Modell über `chat.send` konsultiert. + Im Chat-Composer ist das Talk-Steuerelement die Wellen-Schaltfläche neben der Mikrofon-Diktat-Schaltfläche. Wenn Talk startet, zeigt die Composer-Statuszeile `Connecting Talk...`, dann `Talk live`, während Audio verbunden ist, oder `Asking OpenClaw...`, während ein Echtzeit-Tool-Aufruf das konfigurierte größere Modell über `chat.send` konsultiert. - Maintainer-Live-Smoke: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` verifiziert den OpenAI-Browser-WebRTC-SDP-Austausch, die Google Live-Einrichtung eines eingeschränkten Token-Browser-WebSocket sowie den Gateway-Relay-Browser-Adapter mit gefälschten Mikrofonmedien. Der Befehl gibt nur den Provider-Status aus und protokolliert keine Secrets. + Maintainer-Live-Smoke: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` überprüft den OpenAI-Browser-WebRTC-SDP-Austausch, die Google-Live-Browser-WebSocket-Einrichtung mit eingeschränktem Token und den Gateway-Relay-Browseradapter mit gefälschten Mikrofonmedien. Der Befehl gibt nur den Provider-Status aus und protokolliert keine Secrets. - - Klicken Sie auf **Stoppen** (ruft `chat.abort` auf). - - Während ein Lauf aktiv ist, werden normale Folgefragen in die Warteschlange gestellt. Klicken Sie bei einer eingereihten Nachricht auf **Steuern**, um diese Folgefrage in den laufenden Zug einzuspeisen. - - Geben Sie `/stop` ein (oder eigenständige Abbruchphrasen wie `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`), um außerhalb des Bands abzubrechen. + - Klicken Sie auf **Stop** (ruft `chat.abort` auf). + - Während ein Lauf aktiv ist, werden normale Folgeanfragen in die Warteschlange gestellt. Klicken Sie bei einer wartenden Nachricht auf **Steer**, um diese Folgeanfrage in den laufenden Turn einzuschleusen. + - Geben Sie `/stop` ein (oder eigenständige Abbruchphrasen wie `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`), um außerhalb des normalen Pfads abzubrechen. - `chat.abort` unterstützt `{ sessionKey }` (ohne `runId`), um alle aktiven Läufe für diese Sitzung abzubrechen. - - - Wenn ein Lauf abgebrochen wird, kann teilweiser Assistententext weiterhin in der UI angezeigt werden. - - Gateway speichert abgebrochenen teilweisen Assistententext im Transkriptverlauf dauerhaft, wenn gepufferte Ausgabe vorhanden ist. - - Dauerhaft gespeicherte Einträge enthalten Abbruchmetadaten, damit Transkriptverbraucher Abbruch-Teilausgaben von normaler Abschlussausgabe unterscheiden können. + + - Wenn ein Lauf abgebrochen wird, kann partieller Assistententext weiterhin in der UI angezeigt werden. + - Das Gateway persistiert abgebrochenen partiellen Assistententext im Transkriptverlauf, wenn gepufferte Ausgabe vorhanden ist. + - Persistierte Einträge enthalten Abbruchmetadaten, damit Transkriptkonsumenten abgebrochene Teilausgaben von normaler Abschlussausgabe unterscheiden können. ## PWA-Installation und Web Push -Die Control UI liefert ein `manifest.webmanifest` und einen Service Worker aus, sodass moderne Browser sie als eigenständige PWA installieren können. Web Push ermöglicht es dem Gateway, die installierte PWA mit Benachrichtigungen aufzuwecken, selbst wenn der Tab oder das Browserfenster nicht geöffnet ist. +Die Control UI liefert ein `manifest.webmanifest` und einen Service Worker aus, sodass moderne Browser sie als eigenständige PWA installieren können. Web Push ermöglicht dem Gateway, die installierte PWA mit Benachrichtigungen zu wecken, auch wenn der Tab oder das Browserfenster nicht geöffnet ist. | Oberfläche | Funktion | | ----------------------------------------------------- | ------------------------------------------------------------------ | | `ui/public/manifest.webmanifest` | PWA-Manifest. Browser bieten „App installieren“ an, sobald es erreichbar ist. | -| `ui/public/sw.js` | Service Worker, der `push`-Events und Benachrichtigungsklicks verarbeitet. | -| `push/vapid-keys.json` (unter dem OpenClaw-State-Verzeichnis) | Automatisch generiertes VAPID-Schlüsselpaar zum Signieren von Web-Push-Nutzdaten. | -| `push/web-push-subscriptions.json` | Dauerhaft gespeicherte Browser-Abonnement-Endpunkte. | +| `ui/public/sw.js` | Service Worker, der `push`-Ereignisse und Benachrichtigungsklicks verarbeitet. | +| `push/vapid-keys.json` (im OpenClaw-Statusverzeichnis) | Automatisch generiertes VAPID-Schlüsselpaar zum Signieren von Web-Push-Nutzdaten. | +| `push/web-push-subscriptions.json` | Persistierte Browser-Abonnement-Endpunkte. | -Überschreiben Sie das VAPID-Schlüsselpaar über Umgebungsvariablen im Gateway-Prozess, wenn Sie Schlüssel fest vorgeben möchten (für Multi-Host-Deployments, Secret-Rotation oder Tests): +Überschreiben Sie das VAPID-Schlüsselpaar über Umgebungsvariablen im Gateway-Prozess, wenn Sie Schlüssel festlegen möchten (für Multi-Host-Deployments, Secret-Rotation oder Tests): - `OPENCLAW_VAPID_PUBLIC_KEY` - `OPENCLAW_VAPID_PRIVATE_KEY` -- `OPENCLAW_VAPID_SUBJECT` (Standard ist `mailto:openclaw@localhost`) +- `OPENCLAW_VAPID_SUBJECT` (standardmäßig `mailto:openclaw@localhost`) -Die Control UI verwendet diese scope-geschützten Gateway-Methoden, um Browser-Abonnements zu registrieren und zu testen: +Die Control UI verwendet diese scope-gebundenen Gateway-Methoden, um Browser-Abonnements zu registrieren und zu testen: - `push.web.vapidPublicKey` — ruft den aktiven öffentlichen VAPID-Schlüssel ab. - `push.web.subscribe` — registriert einen `endpoint` plus `keys.p256dh`/`keys.auth`. @@ -217,7 +219,7 @@ Die Control UI verwendet diese scope-geschützten Gateway-Methoden, um Browser-A - `push.web.test` — sendet eine Testbenachrichtigung an das Abonnement des Aufrufers. -Web Push ist unabhängig vom iOS-APNS-Relay-Pfad (siehe [Konfiguration](/de/gateway/configuration) für relaygestützten Push) und von der bestehenden Methode `push.test`, die auf native Mobile-Kopplung zielen. +Web Push ist unabhängig vom iOS-APNS-Relay-Pfad (siehe [Konfiguration](/de/gateway/configuration) für relay-gestützte Push-Benachrichtigungen) und von der bestehenden Methode `push.test`, die auf native mobile Kopplung abzielt. ## Gehostete Einbettungen @@ -226,13 +228,13 @@ Assistentennachrichten können gehostete Webinhalte inline mit dem Shortcode `[e - Deaktiviert die Skriptausführung innerhalb gehosteter Einbettungen. + Deaktiviert Skriptausführung innerhalb gehosteter Einbettungen. - - Erlaubt interaktive Einbettungen bei beibehaltener Origin-Isolation; dies ist die Standardeinstellung und reicht in der Regel für eigenständige Browserspiele/-widgets aus. + + Erlaubt interaktive Einbettungen bei gleichzeitiger Origin-Isolation; dies ist die Standardeinstellung und reicht normalerweise für eigenständige Browser-Spiele/Widgets aus. - Fügt `allow-same-origin` zusätzlich zu `allow-scripts` für Same-Site-Dokumente hinzu, die bewusst stärkere Berechtigungen benötigen. + Fügt `allow-same-origin` zusätzlich zu `allow-scripts` für Dokumente derselben Website hinzu, die absichtlich stärkere Berechtigungen benötigen. @@ -249,14 +251,14 @@ Beispiel: ``` -Verwenden Sie `trusted` nur, wenn das eingebettete Dokument wirklich Same-Origin-Verhalten benötigt. Für die meisten agentgenerierten Spiele und interaktiven Canvases ist `scripts` die sicherere Wahl. +Verwenden Sie `trusted` nur, wenn das eingebettete Dokument tatsächlich Same-Origin-Verhalten benötigt. Für die meisten von Agenten generierten Spiele und interaktiven Canvases ist `scripts` die sicherere Wahl. -Absolute externe `http(s)`-Einbettungs-URLs bleiben standardmäßig blockiert. Wenn Sie bewusst möchten, dass `[embed url="https://..."]` Drittanbieterseiten lädt, setzen Sie `gateway.controlUi.allowExternalEmbedUrls: true`. +Absolute externe `http(s)`-Einbettungs-URLs bleiben standardmäßig blockiert. Wenn Sie absichtlich möchten, dass `[embed url="https://..."]` Drittanbieterseiten lädt, setzen Sie `gateway.controlUi.allowExternalEmbedUrls: true`. -## Chat-Nachrichtenbreite +## Breite von Chat-Nachrichten -Gruppierte Chat-Nachrichten verwenden eine lesbare standardmäßige Maximalbreite. Deployments mit breiten Monitoren können sie überschreiben, ohne gebündeltes CSS zu patchen, indem `gateway.controlUi.chatMessageMaxWidth` gesetzt wird: +Gruppierte Chat-Nachrichten verwenden eine gut lesbare Standard-Maximalbreite. Deployments mit breiten Monitoren können sie ohne Patchen des gebündelten CSS überschreiben, indem `gateway.controlUi.chatMessageMaxWidth` gesetzt wird: ```json5 { @@ -268,13 +270,13 @@ Gruppierte Chat-Nachrichten verwenden eine lesbare standardmäßige Maximalbreit } ``` -Der Wert wird validiert, bevor er den Browser erreicht. Unterstützte Werte umfassen einfache Längen und Prozentwerte wie `960px` oder `82%` sowie eingeschränkte Breiten-Ausdrücke mit `min(...)`, `max(...)`, `clamp(...)`, `calc(...)` und `fit-content(...)`. +Der Wert wird validiert, bevor er den Browser erreicht. Unterstützte Werte umfassen einfache Längen und Prozentsätze wie `960px` oder `82%` sowie beschränkte Breiten-Ausdrücke mit `min(...)`, `max(...)`, `clamp(...)`, `calc(...)` und `fit-content(...)`. ## Tailnet-Zugriff (empfohlen) - - Halten Sie den Gateway auf loopback und lassen Sie ihn von Tailscale Serve per HTTPS proxien: + + Halten Sie das Gateway auf loopback und lassen Sie Tailscale Serve es per HTTPS proxien: ```bash openclaw gateway --tailscale serve @@ -284,12 +286,12 @@ Der Wert wird validiert, bevor er den Browser erreicht. Unterstützte Werte umfa - `https:///` (oder Ihren konfigurierten `gateway.controlUi.basePath`) - Standardmäßig können Control-UI-/WebSocket-Serve-Anfragen sich über Tailscale-Identitätsheader (`tailscale-user-login`) authentifizieren, wenn `gateway.auth.allowTailscale` `true` ist. OpenClaw verifiziert die Identität, indem es die Adresse `x-forwarded-for` mit `tailscale whois` auflöst und mit dem Header abgleicht, und akzeptiert diese nur, wenn die Anfrage local loopback mit den `x-forwarded-*`-Headern von Tailscale erreicht. Für Control-UI-Operator-Sitzungen mit Browser-Geräteidentität überspringt dieser verifizierte Serve-Pfad außerdem den Device-Pairing-Roundtrip; Browser ohne Gerät und Verbindungen mit Node-Rolle folgen weiterhin den normalen Geräteprüfungen. Setzen Sie `gateway.auth.allowTailscale: false`, wenn Sie auch für Serve-Traffic explite Anmeldedaten mit gemeinsamem Secret verlangen möchten. Verwenden Sie dann `gateway.auth.mode: "token"` oder `"password"`. + Standardmäßig können sich Control-UI-/WebSocket-Serve-Anfragen über Tailscale-Identitätsheader (`tailscale-user-login`) authentifizieren, wenn `gateway.auth.allowTailscale` `true` ist. OpenClaw verifiziert die Identität, indem die Adresse `x-forwarded-for` mit `tailscale whois` aufgelöst und mit dem Header abgeglichen wird, und akzeptiert diese nur, wenn die Anfrage loopback mit Tailscales `x-forwarded-*`-Headern erreicht. Für Control-UI-Operator-Sitzungen mit Browser-Geräteidentität überspringt dieser verifizierte Serve-Pfad außerdem den Geräte-Kopplungs-Roundtrip; Browser ohne Gerät und Verbindungen mit Node-Rolle folgen weiterhin den normalen Geräteprüfungen. Setzen Sie `gateway.auth.allowTailscale: false`, wenn Sie selbst für Serve-Datenverkehr explizite Shared-Secret-Zugangsdaten verlangen möchten. Verwenden Sie dann `gateway.auth.mode: "token"` oder `"password"`. - Für diesen asynchronen Serve-Identitätspfad werden fehlgeschlagene Authentifizierungsversuche für dieselbe Client-IP und denselben Authentifizierungs-Scope serialisiert, bevor Rate-Limit-Schreibvorgänge erfolgen. Gleichzeitige fehlerhafte Wiederholungen aus demselben Browser können daher bei der zweiten Anfrage `retry later` anzeigen, statt dass zwei einfache Nichtübereinstimmungen parallel konkurrieren. + Für diesen asynchronen Serve-Identitätspfad werden fehlgeschlagene Authentifizierungsversuche für dieselbe Client-IP und denselben Authentifizierungs-Scope vor Rate-Limit-Schreibvorgängen serialisiert. Gleichzeitige fehlerhafte Wiederholungen aus demselben Browser können daher bei der zweiten Anfrage `retry later` anzeigen, anstatt dass zwei einfache Nichtübereinstimmungen parallel konkurrieren. - Tokenlose Serve-Authentifizierung setzt voraus, dass der Gateway-Host vertrauenswürdig ist. Wenn nicht vertrauenswürdiger lokaler Code auf diesem Host laufen kann, verlangen Sie Token-/Passwortauthentifizierung. + Tokenlose Serve-Authentifizierung setzt voraus, dass der Gateway-Host vertrauenswürdig ist. Wenn nicht vertrauenswürdiger lokaler Code auf diesem Host ausgeführt werden könnte, verlangen Sie Token-/Passwort-Authentifizierung. @@ -309,21 +311,21 @@ Der Wert wird validiert, bevor er den Browser erreicht. Unterstützte Werte umfa ## Unsicheres HTTP -Wenn Sie das Dashboard über unverschlüsseltes HTTP öffnen (`http://` oder `http://`), läuft der Browser in einem **nicht sicheren Kontext** und blockiert WebCrypto. Standardmäßig **blockiert** OpenClaw Control-UI-Verbindungen ohne Geräteidentität. +Wenn Sie das Dashboard über einfaches HTTP öffnen (`http://` oder `http://`), läuft der Browser in einem **nicht sicheren Kontext** und blockiert WebCrypto. Standardmäßig **blockiert** OpenClaw Control-UI-Verbindungen ohne Geräteidentität. Dokumentierte Ausnahmen: -- localhost-only-Kompatibilität für unsicheres HTTP mit `gateway.controlUi.allowInsecureAuth=true` +- nur für localhost gedachte unsichere HTTP-Kompatibilität mit `gateway.controlUi.allowInsecureAuth=true` - erfolgreiche Operator-Control-UI-Authentifizierung über `gateway.auth.mode: "trusted-proxy"` -- Break-Glass-Option `gateway.controlUi.dangerouslyDisableDeviceAuth=true` +- Break-Glass `gateway.controlUi.dangerouslyDisableDeviceAuth=true` -**Empfohlene Lösung:** Verwenden Sie HTTPS (Tailscale Serve) oder öffnen Sie die UI lokal: +**Empfohlene Behebung:** Verwenden Sie HTTPS (Tailscale Serve) oder öffnen Sie die UI lokal: - `https:///` (Serve) - `http://127.0.0.1:18789/` (auf dem Gateway-Host) - + ```json5 { gateway: { @@ -334,14 +336,14 @@ Dokumentierte Ausnahmen: } ``` - `allowInsecureAuth` ist nur ein lokaler Kompatibilitätsschalter: + `allowInsecureAuth` ist nur ein lokaler Kompatibilitäts-Schalter: - - Er erlaubt localhost-Control-UI-Sitzungen, in unsicheren HTTP-Kontexten ohne Geräteidentität fortzufahren. - - Er umgeht keine Kopplungsprüfungen. - - Er lockert keine Anforderungen an die Geräteidentität für entfernte Geräte (nicht localhost). + - Er ermöglicht localhost-Control-UI-Sitzungen ohne Geräteidentität in nicht sicheren HTTP-Kontexten. + - Er umgeht keine Pairing-Prüfungen. + - Er lockert keine Anforderungen an die Geräteidentität für entfernte (nicht lokale localhost-)Zugriffe. - + ```json5 { gateway: { @@ -353,52 +355,52 @@ Dokumentierte Ausnahmen: ``` - `dangerouslyDisableDeviceAuth` deaktiviert die Geräteidentitätsprüfungen der Control UI und ist eine schwerwiegende Sicherheitsverschlechterung. Setzen Sie dies nach der Notfallnutzung schnell zurück. + `dangerouslyDisableDeviceAuth` deaktiviert die Geräteidentitätsprüfungen der Control UI und stellt eine erhebliche Sicherheitsabsenkung dar. Setzen Sie dies nach der Notfallnutzung schnell wieder zurück. - - - Erfolgreiche Authentifizierung über einen vertrauenswürdigen Proxy kann **Operator**-Control-UI-Sitzungen ohne Geräteidentität zulassen. - - Dies gilt **nicht** für Control-UI-Sitzungen mit node-role. - - Reverse Proxys über loopback auf demselben Host erfüllen die Authentifizierung über vertrauenswürdige Proxys weiterhin nicht; siehe [Authentifizierung über vertrauenswürdigen Proxy](/de/gateway/trusted-proxy-auth). + + - Erfolgreiche trusted-proxy-Authentifizierung kann **Operator**-Control-UI-Sitzungen ohne Geräteidentität zulassen. + - Dies gilt **nicht** für Control-UI-Sitzungen mit Node-Rolle. + - local loopback-Reverse-Proxys auf demselben Host erfüllen trusted-proxy-Authentifizierung weiterhin nicht; siehe [Trusted proxy auth](/de/gateway/trusted-proxy-auth). -Siehe [Tailscale](/de/gateway/tailscale) für Anleitungen zur HTTPS-Einrichtung. +Siehe [Tailscale](/de/gateway/tailscale) für Hinweise zur HTTPS-Einrichtung. -## Content Security Policy +## Content-Security-Policy -Die Control UI wird mit einer strengen `img-src`-Policy ausgeliefert: Es sind nur Assets mit **same-origin**, `data:`-URLs und lokal generierte `blob:`-URLs erlaubt. Entfernte `http(s)`- und protokollrelative Bild-URLs werden vom Browser abgelehnt und lösen keine Netzwerkabrufe aus. +Die Control UI wird mit einer strengen `img-src`-Richtlinie ausgeliefert: Es sind nur Assets mit **gleichem Ursprung**, `data:`-URLs und lokal erzeugte `blob:`-URLs erlaubt. Entfernte `http(s)`- und protokollrelative Bild-URLs werden vom Browser abgewiesen und lösen keine Netzwerkabrufe aus. Das bedeutet in der Praxis: - Avatare und Bilder, die unter relativen Pfaden bereitgestellt werden (zum Beispiel `/avatars/`), werden weiterhin gerendert, einschließlich authentifizierter Avatar-Routen, die die UI abruft und in lokale `blob:`-URLs umwandelt. -- Inline-`data:image/...`-URLs werden weiterhin gerendert (nützlich für Nutzdaten innerhalb des Protokolls). -- Lokale `blob:`-URLs, die von der Control UI erstellt werden, werden weiterhin gerendert. -- Entfernte Avatar-URLs, die von Kanalmetadaten ausgegeben werden, werden in den Avatar-Hilfsfunktionen der Control UI entfernt und durch das integrierte Logo/Badge ersetzt, sodass ein kompromittierter oder bösartiger Kanal keine beliebigen entfernten Bildabrufe aus dem Browser eines Operators erzwingen kann. +- Inline-`data:image/...`-URLs werden weiterhin gerendert (nützlich für Payloads innerhalb des Protokolls). +- Von der Control UI erstellte lokale `blob:`-URLs werden weiterhin gerendert. +- Entfernte Avatar-URLs, die von Kanalmetadaten ausgegeben werden, werden in den Avatar-Hilfsfunktionen der Control UI entfernt und durch das integrierte Logo/Badge ersetzt. So kann ein kompromittierter oder bösartiger Kanal keine beliebigen entfernten Bildabrufe aus dem Browser eines Operators erzwingen. -Sie müssen nichts ändern, um dieses Verhalten zu erhalten — es ist immer aktiv und nicht konfigurierbar. +Sie müssen nichts ändern, um dieses Verhalten zu erhalten — es ist immer aktiviert und nicht konfigurierbar. ## Authentifizierung der Avatar-Route Wenn Gateway-Authentifizierung konfiguriert ist, erfordert der Avatar-Endpunkt der Control UI dasselbe Gateway-Token wie der Rest der API: - `GET /avatar/` gibt das Avatar-Bild nur an authentifizierte Aufrufer zurück. `GET /avatar/?meta=1` gibt die Avatar-Metadaten nach derselben Regel zurück. -- Nicht authentifizierte Anfragen an eine der beiden Routen werden abgelehnt (entsprechend der benachbarten assistant-media-Route). Dadurch wird verhindert, dass die Avatar-Route auf ansonsten geschützten Hosts Agentenidentitäten preisgibt. -- Die Control UI selbst leitet das Gateway-Token beim Abrufen von Avataren als Bearer-Header weiter und verwendet authentifizierte Blob-URLs, sodass das Bild in Dashboards weiterhin gerendert wird. +- Nicht authentifizierte Anfragen an eine der beiden Routen werden abgelehnt (entsprechend der benachbarten assistant-media-Route). Dadurch wird verhindert, dass die Avatar-Route die Agentenidentität auf Hosts preisgibt, die ansonsten geschützt sind. +- Die Control UI selbst leitet beim Abrufen von Avataren das Gateway-Token als Bearer-Header weiter und verwendet authentifizierte Blob-URLs, damit das Bild in Dashboards weiterhin gerendert wird. -Wenn Sie die Gateway-Authentifizierung deaktivieren (auf gemeinsam genutzten Hosts nicht empfohlen), wird auch die Avatar-Route unauthentifiziert, entsprechend dem Rest des Gateways. +Wenn Sie die Gateway-Authentifizierung deaktivieren (auf gemeinsam genutzten Hosts nicht empfohlen), wird auch die Avatar-Route nicht authentifiziert, entsprechend dem restlichen Gateway. -## UI bauen +## UI erstellen -Das Gateway stellt statische Dateien aus `dist/control-ui` bereit. Bauen Sie sie mit: +Das Gateway stellt statische Dateien aus `dist/control-ui` bereit. Erstellen Sie sie mit: ```bash pnpm ui:build ``` -Optionale absolute Basis (wenn Sie feste Asset-URLs möchten): +Optionale absolute Basis (wenn Sie feste Asset-URLs wünschen): ```bash OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build @@ -410,19 +412,19 @@ Für lokale Entwicklung (separater Dev-Server): pnpm ui:dev ``` -Verweisen Sie die UI anschließend auf Ihre Gateway-WS-URL (z. B. `ws://127.0.0.1:18789`). +Richten Sie die UI dann auf Ihre Gateway-WS-URL aus (z. B. `ws://127.0.0.1:18789`). -## Debugging/Tests: Dev-Server + entferntes Gateway +## Debugging/Testen: Dev-Server + entferntes Gateway -Die Control UI besteht aus statischen Dateien; das WebSocket-Ziel ist konfigurierbar und kann sich vom HTTP-Origin unterscheiden. Das ist praktisch, wenn Sie den Vite-Dev-Server lokal verwenden möchten, das Gateway aber an anderer Stelle läuft. +Die Control UI besteht aus statischen Dateien; das WebSocket-Ziel ist konfigurierbar und kann sich vom HTTP-Ursprung unterscheiden. Das ist praktisch, wenn Sie den Vite-Dev-Server lokal verwenden möchten, das Gateway aber anderswo läuft. - + ```bash pnpm ui:dev ``` - + ```text http://localhost:5173/?gatewayUrl=ws%3A%2F%2F%3A18789 ``` @@ -437,18 +439,18 @@ Die Control UI besteht aus statischen Dateien; das WebSocket-Ziel ist konfigurie - + - `gatewayUrl` wird nach dem Laden in localStorage gespeichert und aus der URL entfernt. - - Wenn Sie über `gatewayUrl` einen vollständigen `ws://`- oder `wss://`-Endpunkt übergeben, URL-kodieren Sie den Wert `gatewayUrl`, damit der Browser den Query-String korrekt parst. - - `token` sollte nach Möglichkeit über das URL-Fragment (`#token=...`) übergeben werden. Fragmente werden nicht an den Server gesendet, wodurch Lecks in Anfrageprotokollen und Referern vermieden werden. Legacy-Query-Parameter `?token=` werden aus Kompatibilitätsgründen weiterhin einmal importiert, aber nur als Fallback, und unmittelbar nach dem Bootstrap entfernt. + - Wenn Sie einen vollständigen `ws://`- oder `wss://`-Endpunkt über `gatewayUrl` übergeben, URL-kodieren Sie den `gatewayUrl`-Wert, damit der Browser die Abfragezeichenfolge korrekt parst. + - `token` sollte nach Möglichkeit über das URL-Fragment (`#token=...`) übergeben werden. Fragmente werden nicht an den Server gesendet, wodurch Lecks in Anfrageprotokollen und im Referer vermieden werden. Veraltete `?token=`-Abfrageparameter werden aus Kompatibilitätsgründen weiterhin einmal importiert, aber nur als Fallback, und unmittelbar nach dem Bootstrap entfernt. - `password` wird nur im Arbeitsspeicher gehalten. - - Wenn `gatewayUrl` gesetzt ist, fällt die UI nicht auf Anmeldedaten aus Konfiguration oder Umgebung zurück. Geben Sie `token` (oder `password`) explizit an. Fehlende explizite Anmeldedaten sind ein Fehler. - - Verwenden Sie `wss://`, wenn sich das Gateway hinter TLS befindet (Tailscale Serve, HTTPS-Proxy usw.). + - Wenn `gatewayUrl` gesetzt ist, greift die UI nicht auf Konfigurations- oder Umgebungs-Zugangsdaten zurück. Geben Sie `token` (oder `password`) explizit an. Fehlende explizite Zugangsdaten sind ein Fehler. + - Verwenden Sie `wss://`, wenn das Gateway hinter TLS liegt (Tailscale Serve, HTTPS-Proxy usw.). - `gatewayUrl` wird nur in einem Top-Level-Fenster akzeptiert (nicht eingebettet), um Clickjacking zu verhindern. - - Nicht-loopback-Control-UI-Bereitstellungen müssen `gateway.controlUi.allowedOrigins` explizit setzen (vollständige Origins). Dies schließt entfernte Dev-Setups ein. - - Der Gateway-Start kann lokale Origins wie `http://localhost:` und `http://127.0.0.1:` aus dem effektiven Runtime-Bind und Port erzeugen, aber entfernte Browser-Origins benötigen weiterhin explizite Einträge. - - Verwenden Sie `gateway.controlUi.allowedOrigins: ["*"]` nur für streng kontrollierte lokale Tests. Es bedeutet, jeden Browser-Origin zuzulassen, nicht „den Host abgleichen, den ich gerade verwende“. - - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` aktiviert den Host-Header-Origin-Fallback-Modus, aber dies ist ein gefährlicher Sicherheitsmodus. + - Nicht-loopback-Control-UI-Bereitstellungen müssen `gateway.controlUi.allowedOrigins` explizit setzen (vollständige Ursprünge). Dazu gehören entfernte Dev-Setups. + - Der Gateway-Start kann lokale Ursprünge wie `http://localhost:` und `http://127.0.0.1:` aus dem effektiven Laufzeit-Bind und -Port ableiten, aber entfernte Browser-Ursprünge benötigen weiterhin explizite Einträge. + - Verwenden Sie `gateway.controlUi.allowedOrigins: ["*"]` nur für streng kontrollierte lokale Tests. Es bedeutet, jeden Browser-Ursprung zu erlauben, nicht „den Host abgleichen, den ich gerade verwende“. + - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` aktiviert den Fallback-Modus für Host-Header-Ursprünge, ist aber ein gefährlicher Sicherheitsmodus. @@ -465,11 +467,11 @@ Beispiel: } ``` -Details zur Einrichtung des Fernzugriffs: [Fernzugriff](/de/gateway/remote). +Details zur Einrichtung des entfernten Zugriffs: [Remote access](/de/gateway/remote). ## Verwandt - [Dashboard](/de/web/dashboard) — Gateway-Dashboard -- [Integritätsprüfungen](/de/gateway/health) — Gateway-Integritätsüberwachung +- [Health Checks](/de/gateway/health) — Gateway-Zustandsüberwachung - [TUI](/de/web/tui) — Terminal-Benutzeroberfläche - [WebChat](/de/web/webchat) — browserbasierte Chat-Oberfläche diff --git a/docs/de/web/webchat.md b/docs/de/web/webchat.md index ef9813836..012863cc6 100644 --- a/docs/de/web/webchat.md +++ b/docs/de/web/webchat.md @@ -1,66 +1,67 @@ --- read_when: - - WebChat-Zugriff debuggen oder konfigurieren -summary: Statischer Loopback-WebChat-Host und Gateway-WS-Nutzung für die Chat-UI + - Debuggen oder Konfigurieren des WebChat-Zugriffs +summary: Statischer Loopback-WebChat-Host und Gateway-WS-Nutzung für die Chat-Benutzeroberfläche title: Webchat x-i18n: - generated_at: "2026-05-02T06:49:22Z" + generated_at: "2026-05-02T23:39:04Z" model: gpt-5.5 provider: openai - source_hash: fe6d3cb30ed18d651b0d0ca8fd188b47c5f1d186410ee340deb79315f194ed8d + source_hash: ad3a09c8962e3a6dda83716d319df7ba27e18105cee50721278b5cba0a85c52f source_path: web/webchat.md workflow: 16 --- -Status: Die macOS/iOS-SwiftUI-Chatoberfläche spricht direkt mit dem Gateway-WebSocket. +Status: Die macOS/iOS-SwiftUI-Chat-UI kommuniziert direkt mit dem Gateway-WebSocket. ## Was es ist -- Eine native Chatoberfläche für das Gateway (kein eingebetteter Browser und kein lokaler statischer Server). -- Verwendet dieselben Sitzungen und Routingregeln wie andere Kanäle. +- Eine native Chat-UI für das Gateway (kein eingebetteter Browser und kein lokaler statischer Server). +- Verwendet dieselben Sitzungen und Routing-Regeln wie andere Kanäle. - Deterministisches Routing: Antworten gehen immer zurück an WebChat. ## Schnellstart 1. Starten Sie das Gateway. 2. Öffnen Sie die WebChat-UI (macOS/iOS-App) oder den Chat-Tab der Control UI. -3. Stellen Sie sicher, dass ein gültiger Gateway-Authentifizierungspfad konfiguriert ist (standardmäßig shared-secret, - selbst bei Loopback). +3. Stellen Sie sicher, dass ein gültiger Gateway-Authentifizierungspfad konfiguriert ist (standardmäßig Shared Secret, + auch bei Loopback). ## Funktionsweise (Verhalten) -- Die UI verbindet sich mit dem Gateway-WebSocket und verwendet `chat.history`, `chat.send` und `chat.inject`. -- `chat.history` ist aus Stabilitätsgründen begrenzt: Das Gateway kann lange Textfelder kürzen, umfangreiche Metadaten auslassen und übergroße Einträge durch `[chat.history omitted: message too large]` ersetzen. -- `chat.history` folgt dem aktiven Transkriptzweig für moderne Append-only-Sitzungsdateien, sodass verworfene Rewrite-Zweige und ersetzte Prompt-Kopien nicht in WebChat gerendert werden. -- Die Control UI merkt sich die vom `chat.history` zurückgegebene zugrunde liegende Gateway-`sessionId` und fügt sie nachfolgenden `chat.send`-Aufrufen hinzu, sodass Neuverbindungen und Seitenaktualisierungen dieselbe gespeicherte Unterhaltung fortsetzen, sofern der Benutzer keine Sitzung startet oder zurücksetzt. -- Die Control UI fasst doppelte laufende Übermittlungen für dieselbe Sitzung, Nachricht und Anhänge zusammen, bevor sie eine neue `chat.send`-Run-ID generiert; das Gateway dedupliziert weiterhin wiederholte Anfragen, die denselben Idempotenzschlüssel wiederverwenden. -- `chat.history` ist außerdem für die Anzeige normalisiert: nur zur Laufzeit vorhandener OpenClaw-Kontext, +- Die UI verbindet sich mit dem Gateway-WebSocket und verwendet `chat.history`, `chat.send`, `chat.inject` und `chat.transcribeAudio`. +- `chat.history` ist zur Stabilität begrenzt: Gateway kann lange Textfelder kürzen, umfangreiche Metadaten auslassen und übergroße Einträge durch `[chat.history omitted: message too large]` ersetzen. +- `chat.history` folgt bei modernen Append-only-Sitzungsdateien dem aktiven Transkriptzweig, sodass verworfene Rewrite-Zweige und ersetzte Prompt-Kopien nicht in WebChat gerendert werden. +- Control UI merkt sich die vom Gateway über `chat.history` zurückgegebene zugrunde liegende `sessionId` und übergibt sie bei nachfolgenden `chat.send`-Aufrufen, sodass erneute Verbindungen und Seitenaktualisierungen dieselbe gespeicherte Unterhaltung fortsetzen, sofern der Benutzer keine Sitzung startet oder zurücksetzt. +- Control UI führt doppelte laufende Übermittlungen für dieselbe Sitzung, Nachricht und Anhänge zusammen, bevor eine neue `chat.send`-Lauf-ID erzeugt wird; das Gateway dedupliziert weiterhin wiederholte Anfragen, die denselben Idempotenzschlüssel wiederverwenden. +- `chat.history` wird auch für die Anzeige normalisiert: Nur zur Laufzeit verwendeter OpenClaw-Kontext, eingehende Envelope-Wrapper, Inline-Tags für Zustellungsdirektiven - wie `[[reply_to_*]]` und `[[audio_as_voice]]`, XML-Nutzdaten von Klartext-Tool-Aufrufen + wie `[[reply_to_*]]` und `[[audio_as_voice]]`, Nur-Text-XML-Nutzlasten von Tool-Aufrufen (einschließlich `...`, `...`, `...`, `...` und gekürzter Tool-Aufrufblöcke) sowie durchgesickerte ASCII-/vollbreite Modell-Steuerungstoken werden aus sichtbarem Text entfernt, - und Assistant-Einträge, deren gesamter sichtbarer Text nur aus dem exakten stillen - Token `NO_REPLY` / `no_reply` besteht, werden ausgelassen. -- Als Reasoning markierte Antwortnutzdaten (`isReasoning: true`) werden von WebChat-Assistant-Inhalten, Transkript-Wiedergabetext und Audioinhaltsblöcken ausgeschlossen, sodass reine Denkinhalte nicht als sichtbare Assistant-Nachrichten oder abspielbares Audio erscheinen. -- `chat.inject` hängt eine Assistant-Notiz direkt an das Transkript an und sendet sie an die UI (kein Agent-Lauf). -- Abgebrochene Läufe können partielle Assistant-Ausgabe in der UI sichtbar lassen. -- Das Gateway speichert abgebrochenen partiellen Assistant-Text in der Transkript-Historie, wenn gepufferte Ausgabe vorhanden ist, und markiert diese Einträge mit Abbruchmetadaten. -- Die Historie wird immer vom Gateway abgerufen (keine lokale Dateiüberwachung). + und Assistenteneinträge, deren gesamter sichtbarer Text ausschließlich das exakte stille + Token `NO_REPLY` / `no_reply` ist, werden ausgelassen. +- Antwort-Nutzlasten mit Reasoning-Flag (`isReasoning: true`) werden aus WebChat-Assistenteninhalten, Transkript-Wiedergabetext und Audio-Inhaltsblöcken ausgeschlossen, sodass reine Denk-Nutzlasten nicht als sichtbare Assistentennachrichten oder abspielbares Audio erscheinen. +- `chat.transcribeAudio` ermöglicht serverseitiges Diktieren im Chat-Composer der Control UI. Der Browser zeichnet Mikrofon-Audio auf, sendet es als Base64 an das Gateway, und das Gateway führt die konfigurierte `tools.media.audio`-Pipeline aus. Das zurückgegebene Transkript wird in den Entwurf eingefügt; es wird kein Agentenlauf gestartet, bis der Benutzer ihn absendet. +- `chat.inject` hängt eine Assistentennotiz direkt an das Transkript an und sendet sie an die UI (kein Agentenlauf). +- Abgebrochene Läufe können teilweise Assistentenausgaben in der UI sichtbar halten. +- Gateway persistiert abgebrochenen partiellen Assistententext im Transkriptverlauf, wenn gepufferte Ausgabe vorhanden ist, und markiert diese Einträge mit Abbruchmetadaten. +- Der Verlauf wird immer vom Gateway abgerufen (keine lokale Dateiüberwachung). - Wenn das Gateway nicht erreichbar ist, ist WebChat schreibgeschützt. -## Tools-Panel für Control-UI-Agents +## Tools-Bereich für Control-UI-Agenten -- Das Tools-Panel `/agents` der Control UI hat zwei separate Ansichten: - - **Derzeit verfügbar** verwendet `tools.effective(sessionKey=...)` und zeigt, was die aktuelle - Sitzung zur Laufzeit tatsächlich verwenden kann, einschließlich core-, Plugin- und kanaleigener Tools. +- Der Tools-Bereich der Control UI unter `/agents` hat zwei getrennte Ansichten: + - **Aktuell verfügbar** verwendet `tools.effective(sessionKey=...)` und zeigt, was die aktuelle + Sitzung zur Laufzeit tatsächlich verwenden kann, einschließlich Core-, Plugin- und kanalverwalteter Tools. - **Tool-Konfiguration** verwendet `tools.catalog` und bleibt auf Profile, Überschreibungen und Katalogsemantik fokussiert. -- Die Laufzeitverfügbarkeit ist sitzungsbezogen. Das Wechseln von Sitzungen auf demselben Agent kann die - Liste **Derzeit verfügbar** ändern. -- Der Konfigurationseditor impliziert keine Laufzeitverfügbarkeit; der effektive Zugriff folgt weiterhin der Richtlinienpriorität - (`allow`/`deny`, pro Agent und Provider-/Kanal-Überschreibungen). +- Laufzeitverfügbarkeit ist sitzungsbezogen. Der Wechsel zwischen Sitzungen desselben Agenten kann die Liste + **Aktuell verfügbar** ändern. +- Der Konfigurationseditor impliziert keine Laufzeitverfügbarkeit; effektiver Zugriff folgt weiterhin der Richtlinienpriorität + (`allow`/`deny`, Überschreibungen pro Agent sowie Provider-/Kanal-Overrides). ## Remote-Nutzung @@ -73,20 +74,20 @@ Vollständige Konfiguration: [Konfiguration](/de/gateway/configuration) WebChat-Optionen: -- `gateway.webchat.chatHistoryMaxChars`: maximale Zeichenanzahl für Textfelder in `chat.history`-Antworten. Wenn ein Transkripteintrag dieses Limit überschreitet, kürzt das Gateway lange Textfelder und kann übergroße Nachrichten durch einen Platzhalter ersetzen. Pro Anfrage kann außerdem `maxChars` vom Client gesendet werden, um diesen Standardwert für einen einzelnen `chat.history`-Aufruf zu überschreiben. +- `gateway.webchat.chatHistoryMaxChars`: maximale Zeichenanzahl für Textfelder in `chat.history`-Antworten. Wenn ein Transkripteintrag diesen Grenzwert überschreitet, kürzt Gateway lange Textfelder und kann übergroße Nachrichten durch einen Platzhalter ersetzen. Der Client kann pro Anfrage auch `maxChars` senden, um diesen Standardwert für einen einzelnen `chat.history`-Aufruf zu überschreiben. Zugehörige globale Optionen: - `gateway.port`, `gateway.bind`: WebSocket-Host/-Port. - `gateway.auth.mode`, `gateway.auth.token`, `gateway.auth.password`: - shared-secret-WebSocket-Authentifizierung. -- `gateway.auth.allowTailscale`: Der Chat-Tab der Browser-Control-UI kann bei Aktivierung Tailscale - Serve-Identitäts-Header verwenden. -- `gateway.auth.mode: "trusted-proxy"`: Reverse-Proxy-Authentifizierung für Browser-Clients hinter einer identitätsbewussten **Nicht-Loopback**-Proxyquelle (siehe [Trusted Proxy Auth](/de/gateway/trusted-proxy-auth)). + Shared-Secret-WebSocket-Authentifizierung. +- `gateway.auth.allowTailscale`: Der Chat-Tab der browserbasierten Control UI kann bei Aktivierung Tailscale- + Serve-Identitätsheader verwenden. +- `gateway.auth.mode: "trusted-proxy"`: Reverse-Proxy-Authentifizierung für Browser-Clients hinter einer identitätsbewussten **Nicht-Loopback**-Proxy-Quelle (siehe [Trusted Proxy Auth](/de/gateway/trusted-proxy-auth)). - `gateway.remote.url`, `gateway.remote.token`, `gateway.remote.password`: Remote-Gateway-Ziel. -- `session.*`: Sitzungsspeicher und Standardwerte für den Hauptschlüssel. +- `session.*`: Sitzungsspeicher und Standardwerte für Hauptschlüssel. -## Verwandt +## Verwandte Themen - [Control UI](/de/web/control-ui) - [Dashboard](/de/web/dashboard)